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, column_name: 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", column_name="value_double")

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,
    *,
    column_name: 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
column_name	str	Column holding the values to convert.	'value_double'
target_column	str | None	Column to write the converted values to. Defaults to column_name (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 column_name is missing.
ValueError	If a unit is unknown or the units are incompatible.