ucon.integrations.pandas¶
Pandas integration via NumberSeries and UconSeriesAccessor. Install with pip install ucon[pandas].
Pandas integration for ucon.
This module provides NumberSeries and a pandas accessor for working with unit-aware Series data.
Requires: pip install ucon[pandas]
Example
import pandas as pd from ucon import units from ucon.pandas import NumberSeries
heights = NumberSeries(pd.Series([1.7, 1.8, 1.9]), unit=units.meter) heights.to(units.foot)
Or using the accessor:¶
df = pd.DataFrame({'height': [1.7, 1.8, 1.9]}) df['height'].ucon.with_unit(units.meter).to(units.foot)
NumberSeries
¶
A pandas Series with an associated unit.
Combines a pandas Series of magnitudes with a unit, enabling vectorized arithmetic and conversion while preserving pandas functionality.
Parameters¶
series : pd.Series The numeric values. unit : Unit or UnitProduct, optional The unit for all values. Defaults to dimensionless. uncertainty : float or pd.Series, optional Uncertainty value(s). If scalar, applies uniformly to all elements. If Series, must have the same index.
Examples¶
import pandas as pd from ucon import units from ucon.pandas import NumberSeries
Create from Series:
heights = NumberSeries(pd.Series([1.7, 1.8, 1.9]), unit=units.meter) len(heights) 3
Vectorized conversion:
heights_ft = heights.to(units.foot)
With uncertainty:
temps = NumberSeries(pd.Series([20, 21, 22]), unit=units.celsius, uncertainty=0.5)
series
property
¶
The underlying pandas Series.
values
property
¶
Alias for series (for compatibility).
unit
property
¶
The unit shared by all values.
uncertainty
property
¶
The uncertainty (scalar or per-element Series).
index
property
¶
The pandas index.
shape
property
¶
Shape of the series.
dtype
property
¶
Data type of the series.
dimension
property
¶
The physical dimension of the quantities.
__len__()
¶
Return the number of elements.
__getitem__(key)
¶
Index or slice the series.
__iter__()
¶
Iterate as Number instances.
__repr__()
¶
String representation.
__mul__(other)
¶
Multiply by scalar, Number, or NumberSeries.
__rmul__(other)
¶
Right multiplication.
__truediv__(other)
¶
Divide by scalar, Number, or NumberSeries.
__add__(other)
¶
Add NumberSeries or Number (same unit required).
__radd__(other)
¶
Right addition.
__sub__(other)
¶
Subtract NumberSeries or Number (same unit required).
__neg__()
¶
Negation.
__abs__()
¶
Absolute value.
__eq__(other)
¶
Element-wise equality comparison. Returns boolean Series.
__ne__(other)
¶
Element-wise inequality comparison. Returns boolean Series.
__lt__(other)
¶
Element-wise less-than comparison. Returns boolean Series.
__le__(other)
¶
Element-wise less-than-or-equal comparison. Returns boolean Series.
__gt__(other)
¶
Element-wise greater-than comparison. Returns boolean Series.
__ge__(other)
¶
Element-wise greater-than-or-equal comparison. Returns boolean Series.
to(target, graph=None)
¶
to_frame(name=None)
¶
Convert to DataFrame with unit in column name.
sum()
¶
Sum all values.
mean()
¶
Compute the mean.
std(ddof=1)
¶
Compute the standard deviation.
min()
¶
Return the minimum value.
max()
¶
Return the maximum value.
UconSeriesAccessor
¶
Pandas Series accessor for ucon unit operations.
Enables syntax like
df['height'].ucon.with_unit(units.meter).to(units.foot)
Examples¶
import pandas as pd from ucon import units
df = pd.DataFrame({'height_m': [1.7, 1.8, 1.9]}) heights = df['height_m'].ucon.with_unit(units.meter) heights.to(units.foot)