Pint-Pandas

Common errors

• ModuleNotFoundError: No module named 'pint_pandas'

  cause The `pint-pandas` package has not been installed. Users sometimes install `pint` but forget to install its Pandas integration package.
  fix Run `pip install pint-pandas` or `conda install -c conda-forge pint-pandas` to install the package.

• DataFrame `dtype` is `object` instead of `pint[unit]` for columns expected to have units.

  cause Columns were created or loaded (e.g., from CSV) containing `pint.Quantity` objects but were not explicitly cast to `PintArray` dtypes, leading Pandas to infer an `object` dtype. Operations may then fail to be units-aware.
  fix After loading data, use the `.pint.quantify()` or `.pint.convert_object_dtype()` accessor methods to correctly convert the `object` columns into `PintArray` dtypes. For example: `df = df.pint.quantify(level=-1)` if units are in the header, or `df = df.pint.convert_object_dtype()` for Series of Quantities.

• In-place Series operations (e.g., `s.pint.ito('new_unit')`) appear to do nothing.

  cause Due to how Pint-Pandas handles delegated methods for its Series accessor, direct in-place modification might not work as intuitively expected for all methods.
  fix Instead of in-place operations, reassign the result of the method. For example, use `s = s.pint.to('new_unit')` instead of `s.pint.ito('new_unit')`.

Warnings

• gotcha The Pandas integration is officially considered 'experimental'. While functional, some edge cases or advanced Pandas features might not behave as expected or could change in future releases.
  Fix: Always refer to the latest documentation and test thoroughly, especially for critical applications.
• gotcha When downcasting a PintArray to a NumPy array (e.g., implicitly in some Pandas operations), the unit information will be stripped, resulting in a `UnitStrippedWarning`. This can lead to loss of unit context if not handled explicitly.
  Fix: If units are not needed, explicitly extract magnitudes using `.pint.magnitude`. If units are critical, ensure operations are units-aware or explicitly convert units before array conversion.
• breaking Pint-Pandas has specific minimum version requirements for both `pandas` and `pint` that evolve with new releases. For instance, `pint-pandas` 0.6 requires `pandas` >= 2.2 and `pint` >= 0.24. Pandas 3.0 also introduced significant breaking changes and mandates Python 3.11+.
  Fix: Always check the `pint-pandas` changelog and documentation for the exact compatible versions of `pandas` and `pint` for your desired `pint-pandas` version. Ensure your Python environment meets the minimum `requires_python` of `pint-pandas` and `pandas`.

Install

• pip install pint-pandas Install with pip
• conda install -c conda-forge pint-pandas Install with Conda

Imports

• pandas

  import pandas as pd

• pint

  import pint

• pint_pandas
  wrong:

  from pint import pandas

  correct:

  import pint_pandas

  pint_pandas is a separate package, not a submodule of pint.

Quickstart

This quickstart demonstrates how to create a Pandas DataFrame with unit-aware columns using `pint[unit]` dtypes. It then shows how to perform arithmetic operations that automatically handle unit conversions and dimensional analysis. Finally, it illustrates how to convert units of a Series using the `.pint` accessor.

import pandas as pd
import pint
import pint_pandas

# Create a DataFrame with PintArrays as columns
df = pd.DataFrame({
    "torque": pd.Series([1.0, 2.0, 2.0, 3.0], dtype="pint[lbf ft]"),
    "angular_velocity": pd.Series([1.0, 2.0, 2.0, 3.0], dtype="pint[rpm]"),
})

print("Original DataFrame:\n", df)
print("\nData Types:\n", df.dtypes)

# Perform units-aware operations
df['power'] = df['torque'] * df['angular_velocity']

print("\nDataFrame with calculated 'power':\n", df)
print("\nData Types after calculation:\n", df.dtypes)

# Access magnitudes or convert units
print("\nPower in Watts:\n", df['power'].pint.to('W'))