Pandas Integration for ansys-units#
The ansys-units library provides pandas extension types for unit-aware
DataFrame and Series objects, similar to pint-pandas.
Installation#
Pandas integration is available when pandas is installed:
pip install ansys-units pandas
Features#
ExtensionDtype:
QuantityDtypefor declaring unit-aware column typesExtensionArray:
QuantityArrayfor storing arrays of quantities with consistent unitsUnit-aware operations: Automatic unit tracking and conversion
Series accessor:
.unitsaccessor for unit operations onSeriesDataFrame accessor:
.unitsaccessor for DataFrame-level unit operations
Quick Start#
Creating Unit-Aware Series#
import pandas as pd
from ansys.units import QuantityDtype
# Create a Series with units
distances = pd.Series([1.0, 2.0, 3.0], dtype="quantity[m]")
print(distances)
# 0 1.0 m
# 1 2.0 m
# 2 3.0 m
# dtype: quantity[m]
# Or use QuantityDtype explicitly
dtype = QuantityDtype("kg")
masses = pd.Series([10.0, 20.0, 30.0], dtype=dtype)
Creating Unit-Aware DataFrames#
import pandas as pd
df = pd.DataFrame(
{
"length": pd.Series([1.0, 2.0, 3.0], dtype="quantity[m]"),
"mass": pd.Series([10.0, 20.0, 30.0], dtype="quantity[kg]"),
"time": pd.Series([5.0, 10.0, 15.0], dtype="quantity[s]"),
}
)
print(df)
Unit Conversion#
Converting Series Units#
distances = pd.Series([1.0, 2.0, 3.0], dtype="quantity[m]")
distances_cm = distances.units.to("cm")
print(distances_cm)
Converting DataFrame Columns#
df = pd.DataFrame(
{
"length": pd.Series([1.0, 2.0], dtype="quantity[m]"),
"mass": pd.Series([1.0, 2.0], dtype="quantity[kg]"),
}
)
df_converted = df.units.to(
{
"length": "cm",
"mass": "g",
}
)
print(df_converted)
DataFrame Unit Summary#
df = pd.DataFrame(
{
"length": pd.Series([1.0, 2.0], dtype="quantity[m]"),
"mass": pd.Series([10.0, 20.0], dtype="quantity[kg]"),
"count": pd.Series([1, 2]),
}
)
summary = df.units.summary()
print(summary)
Working with Quantity Objects#
Creating Arrays from Quantities#
import pandas as pd
from ansys.units import Quantity, QuantityArray
quantities = [
Quantity(1.0, "m"),
Quantity(2.0, "m"),
Quantity(3.0, "m"),
]
arr = QuantityArray._from_sequence(quantities)
series = pd.Series(arr)
Accessing as Quantity#
series = pd.Series([1.0, 2.0, 3.0], dtype="quantity[m]")
q = series.units.quantity
print(type(q))
print(q.units)
Indexing and Selection#
series = pd.Series([1.0, 2.0, 3.0, 4.0, 5.0], dtype="quantity[m]")
element = series.iloc[0]
subset = series.iloc[1:3]
Concatenation#
Series with compatible units are combined in the units of the first one. Series
with incompatible units, such as m and kg, are combined into an object
series.
s1 = pd.Series([1.0, 2.0], dtype="quantity[m]")
s2 = pd.Series([250.0], dtype="quantity[cm]")
result = pd.concat([s1, s2], ignore_index=True)
print(result.dtype) # quantity[m], values [1.0, 2.0, 2.5]
Missing Values (NaN)#
import numpy as np
import pandas as pd
series = pd.Series([1.0, np.nan, 3.0], dtype="quantity[m]")
print(series.isna())
Reduction Operations#
series = pd.Series([1.0, 2.0, 3.0, 4.0], dtype="quantity[m]")
total = series.sum()
average = series.mean()
middle = series.median()
minimum = series.min()
maximum = series.max()
spread = series.std() # in "m"
variance = series.var() # in "m^2"
error = series.sem() # in "m"
product = series.prod() # 24.0 in "m^4"
series.skew() # plain float, shape statistics have no units
series.kurt()
The units of prod() depend on the number of values that are multiplied, so
missing values that are skipped don’t count.
DataFrame reductions return one quantity per column, so columns with different units can be reduced together:
df = pd.DataFrame(
{
"length": pd.Series([1.0, 2.0], dtype="quantity[m]"),
"mass": pd.Series([3.0, 4.0], dtype="quantity[kg]"),
}
)
df.sum() # [Quantity(3.0, "m"), Quantity(7.0, "kg")]
df.mean()
Series.describe() converts its results to plain floats, which drops the units.
Use the .units accessor to get the same statistics with units:
series.units.describe() # count, mean, std, min, 25%, 50%, 75%, max
df.units.describe() # one column per unit-aware column
Cumulative Operations and Unique Values#
series = pd.Series([1.0, 2.0, 2.0, 4.0], dtype="quantity[m]")
series.cumsum() # [1.0, 3.0, 5.0, 9.0] in "m"
series.cummax()
series.unique() # [1.0, 2.0, 4.0] in "m"
series.nunique() # 3
series.drop_duplicates()
series.round(1)
abs(series)
A cumulative product of quantities would have different units for each value, so
cumprod() is only available for dimensionless series:
ratios = pd.Series([2.0, 3.0, 4.0], dtype="quantity[]")
ratios.cumprod() # [2.0, 6.0, 24.0], dimensionless
Rolling, Expanding, and Exponentially Weighted Windows#
pandas converts window data to plain floats, so series.rolling(2).mean() has no
units. Use the .units accessor to keep them:
series = pd.Series([1.0, 2.0, 3.0, 4.0], dtype="quantity[m]")
series.units.rolling(2).mean() # [NaN, 1.5, 2.5, 3.5] in "m"
series.units.rolling(2).var() # in "m^2"
series.units.expanding().max() # in "m"
series.units.ewm(span=2).mean() # in "m"
sum, mean, median, min, max, quantile, first, and last
keep the units of the series. std and sem are in the units of a difference,
and var is in squared units. Results whose units can’t be determined, such as
count, apply, and corr, are plain floats.
Grouping#
Grouped aggregations keep the units of the column:
df = pd.DataFrame(
{
"beam": ["A", "A", "B"],
"load": pd.Series([10.0, 20.0, 30.0], dtype="quantity[kN]"),
}
)
df.groupby("beam")["load"].sum() # [30.0, 30.0] in "kN"
df.groupby("beam")["load"].mean()
df.groupby("beam")["load"].std() # in "kN"
df.groupby("beam")["load"].var() # in "kN^2"
Grouped prod() and cumprod() are only available for dimensionless columns,
because each group would otherwise have different units.
Temperatures#
Unit-aware series follow the same temperature rules as quantities. See Temperature and temperature difference:
Absolute temperatures, such as
quantity[C], can’t be summed, sosum()andcumsum()raise aProhibitedTemperatureOperationerror, including in grouped aggregations.mean(),min(), andmax()are allowed.The standard deviation and variance of absolute temperatures are temperature differences, for example
delta_Canddelta_C^2.
Arithmetic and Comparisons#
Arithmetic between unit-aware Series objects converts units and returns a
unit-aware Series. Comparisons are element-wise:
length = pd.Series([1.0, 2.0], dtype="quantity[m]")
width = pd.Series([50.0, 100.0], dtype="quantity[cm]")
length + width # [1.5, 3.0] in "m"
length * width # [50.0, 200.0] in "m cm"
length * 2 # [2.0, 4.0] in "m"
length > width # [True, True]
-length # [-1.0, -2.0] in "m"
Advanced: Subdtype Specification#
from ansys.units import QuantityDtype
series = pd.Series(
[1.0, 2.0, 3.0],
dtype=QuantityDtype("m", subdtype="float32"),
)
print(series.dtype.name)
Integration with Existing Code#
df = pd.read_csv("data.csv")
df["length"] = pd.Series(df["length"].values, dtype="quantity[m]")
df["mass"] = pd.Series(df["mass"].values, dtype="quantity[kg]")
units_info = df.units.summary()
Limitations#
Products:
cumprod()and groupedprod()raise aTypeErrorunless the series is dimensionless, because each result would have different units.Built-in windows and describe():
series.rolling(),series.expanding(),series.ewm(), andseries.describe()return plain floats. Use the.unitsversions of these methods to keep units.
Examples#
Engineering Data Analysis#
import pandas as pd
df = pd.DataFrame(
{
"beam_id": [1, 2, 3, 4],
"length": pd.Series([5.0, 10.0, 15.0, 20.0], dtype="quantity[m]"),
"load": pd.Series([1000.0, 2000.0, 3000.0, 4000.0], dtype="quantity[N]"),
"deflection": pd.Series([0.5, 1.0, 1.5, 2.0], dtype="quantity[mm]"),
}
)
df_imperial = df.units.to(
{
"length": "ft",
"load": "lbf",
"deflection": "in",
}
)
Temperature Data#
temps = pd.Series([20.0, 25.0, 30.0], dtype="quantity[C]")
temps_f = temps.units.to("F")
print(temps_f)
Multiple Unit Systems#
df = pd.DataFrame(
{
"metric_length": pd.Series([1.0, 2.0], dtype="quantity[m]"),
"imperial_length": pd.Series([3.0, 4.0], dtype="quantity[ft]"),
}
)
df_si = df.units.to(
{
"metric_length": "m",
"imperial_length": "m",
}
)