unit_conversion

unit_conversion

Engineering unit conversion for ts-shape, backed by the pint library.

:class:UnitConverter is a thin wrapper around pint <https://pint.readthedocs.io>_, the de-facto-standard, actively maintained open-source Python units library. pint owns all conversion data, dimensional analysis, affine temperature handling and SI prefixes -- ts-shape stores no conversion factors of its own.

pint is an optional dependency; install it with::

pip install ts-shape[units]

UnitConverter

UnitConverter(
    dataframe: DataFrame, time_column: str = "systime"
)

Bases: Base

Convert engineering units in scalars and DataFrame columns via pint.

Unit names are whatever pint understands (e.g. "bar", "psi", "m^3/hour", "kWh", "degC"). The temperature shorthands C, F, K and R are accepted as conveniences.

Example usage::

UnitConverter.convert_value(100, "C", "F")          # 212.0
UnitConverter.conversion_factor("bar", "psi")        # (14.5037..., 0.0)
UnitConverter.convert_column(df, "bar", "psi", value_column="value_double")

Example

import pandas as pd from ts_shape import UnitConverter round(UnitConverter.convert_value(100, "C", "F"), 6) 212.0 factor, offset = UnitConverter.conversion_factor("bar", "psi") round(factor, 4), offset (14.5038, 0.0) df = pd.DataFrame({ ... "systime": pd.date_range("2025-01-01", periods=3, freq="1h"), ... "uuid": "pressure", ... "value_double": [2.0, 1.5, 0.0], ... }) UnitConverter.convert_column(df, "bar", "kPa")[["systime", "value_double"]] systime value_double 0 2025-01-01 00:00:00 200.0 1 2025-01-01 01:00:00 150.0 2 2025-01-01 02:00:00 0.0

convert_value classmethod

convert_value(
    value: float, from_unit: str, to_unit: str
) -> float

Convert a single scalar value from from_unit to to_unit.

Parameters:

Name	Type	Description	Default
value	float	The numeric value to convert.	required
from_unit	str	Source unit (any pint unit name).	required
to_unit	str	Target unit (any pint unit name).	required

Returns:

Type	Description
float	The converted value as a float.

Raises:

Type	Description
ImportError	If the pint library is not installed.
ValueError	If a unit is unknown or the units are incompatible.

conversion_factor classmethod

conversion_factor(
    from_unit: str, to_unit: str
) -> tuple[float, float]

Return the (scale, offset) mapping from_unit -> to_unit.

The conversion is target = value * scale + offset. offset is 0.0 for pure-ratio units and non-zero for affine units such as temperature. The pair is derived automatically from pint.

Parameters:

Name	Type	Description	Default
from_unit	str	Source unit.	required
to_unit	str	Target unit.	required

Returns:

Type	Description
tuple[float, float]	(scale, offset) as floats.

Raises:

Type	Description
ImportError	If the pint library is not installed.
ValueError	If a unit is unknown or the units are incompatible.

convert_column classmethod

convert_column(
    dataframe: DataFrame,
    from_unit: str,
    to_unit: str,
    *,
    value_column: str = "value_double",
    target_column: str | None = None
) -> pd.DataFrame

Convert a numeric DataFrame column to different units.

Parameters:

Name	Type	Description	Default
dataframe	DataFrame	The DataFrame to operate on.	required
from_unit	str	Source unit of the column values.	required
to_unit	str	Target unit.	required
value_column	str	Column holding the values to convert.	'value_double'
target_column	str | None	Column to write the converted values to. Defaults to value_column (in-place on a copy).	None

Returns:

Type	Description
DataFrame	A copy of the DataFrame with the converted column.

Raises:

Type	Description
ImportError	If the pint library is not installed.
ColumnNotFoundError	If value_column is missing.
ValueError	If a unit is unknown or the units are incompatible.

Warns:

Type	Description
DataQualityWarning	When values are not numbers; they become NaN.