unpaac 0.1.4

Pandas DataFrame and Series accessors to handle quantities with uncertainties.

UnPaAc - Uncertainties Pandas Accessors

This python package provides accessors to handle quantities with uncertainties in pandas Series and DataFrame objects using the packages Pint and Uncertainties. The accessors combine some of the functionalities provided by their pandas integrations pint-pandas and uncertainties-pandas.

The project is currently under development and changes in its behaviour might be introduced.

Glossary

• Pint Series are pandas Series that contain a PintArray as values. The PintArray is a Pandas ExtensionArray provided by the pint-pandas package and allows performing unit-aware operations where appropriate. The units are reflected in the Series' dtype attribute, e.g. pint[milligram][Float64]. The subdtype corresponds to the dtype of the magnitudes. For detailed information consult the pint-pandas documentation.

• Pint Uncertainty Series are Pint Series where the PintArray holds an UncertaintyArray. The latter is provided by the uncertainties-pandas package and results in a subdtype corresponding to UncertaintyDtype. Pint Uncertainty Series allow calculations with quantities having uncertainties. Detailed information on the uncertainties package can be found in its documentation, and an example for the combination with a PintArray in this section of the pint-pandas documentation.

Installation

Install the latest release of UnPaAc from PyPI via pip:

pip install unpaac

The development version can be installed from the Git repository using pip:

# Via https
pip install git+https://codeberg.org/Cs137/unpaac.git

# Via ssh
pip install git+ssh://[e-mail]:Cs137/unpaac.git

Usage

The pandas Series and DataFrame accessors are available via the uncrts attribute of instances of the aforementioned object classes. In order to make use of the accessors, import the module uncrts from the package unpaac:

from unpaac import uncrts

The available methods provide detailed docstrings, including examples. However, the following subsection demonstrates a couple of use cases, including a workflow that can be adopted to store and restore pandas DataFrames that contain quantities with uncertainties.

If you have any questions or need assistance, feel free to open an issue on the repository.

Examples

Create a Pint Series

A Pint Series can be created via the create_pint_series() function. The creation with the mandatory attributes values and unit, is shown underneath.

from unpaac.uncrts import create_pint_series

p_series = create_pint_series([1.0, 2.0, 3.0], "mg")
print(p_series)

0    1.0
1    2.0
2    3.0
dtype: pint[milligram][Float64]

Optionally, you can declare uncertainties and/or further keyword arguments that are passed to the pandas Series constructor, e.g. name. If uncertainties are provided, a Pint Uncertainty Series is created.

pu_series = create_pint_series([1.0, 2.0, 3.0], "m", uncertainties=[0.1, 0.2, 0.3], name="length")
print(pu_series)

0    1.00+/-0.10
1    2.00+/-0.20
2    3.00+/-0.30
Name: length, dtype: pint[meter][UncertaintyDtype]

Retrieve nominal values and standard deviations as Pint Series

You can obtain Pint Series of the nominal values and standard deviations via the series accessor properties nominal_values and std_devs, or their shortcuts n and s, respectively.

pu_series.uncrts.n

0    1.0
1    2.0
2    3.0
Name: length, dtype: pint[meter][Float64]

pu_series.uncrts.s

0    0.1
1    0.2
2    0.3
Name: δ(length), dtype: pint[meter][Float64]

The method to_series() returns a tuple with both Pint Series:

n, s = pu_series.uncrts.to_series()

Add Uncertainties to a Pint Series in a DataFrame

The DataFrame accessor allows assigning uncertainties to a column that holds a Pint Series via the add() method, as shows underneath.

df = pd.DataFrame({"mass": p_series})
df.uncrts.add("mass", [0.1, 0.2, 0.3])
print(df)

          mass
0  1.00+/-0.10
1  2.00+/-0.20
2  3.00+/-0.30

Deconvolute Pint Uncertainty Series Columns

The deconvolute() method allows splitting a column with a Pint Uncertainty Series into separate columns for nominal values and uncertainties containing Pint Series.

deconv_df = df.uncrts.deconvolute()
print(deconv_df)

   mass  δ(mass)
0   1.0      0.1
1   2.0      0.2
2   3.0      0.3

Convolute Pint Series Columns

The convolute() method allows combining nominal values and standard deviations from separate columns containing Pint Series into a single column holding a Pint Uncertainty Series. In case your standard deviation column uses custom prefix and suffix values, those can be specified as keyword arguments to a call of the method.

deconv_df.uncrts.convolute()

          mass
0  1.00+/-0.10
1  2.00+/-0.20
2  3.00+/-0.30

Save a DataFrame to CSV and restore DataFrame from CSV

After using the deconvolute() method to split a Pint Uncertainty Series column into Pint Series with the nominal values and uncertainties, you can save the data to a CSV file. However, you should first apply pint.dequantify() method to add the units to the column headers before saving. When reading the data back, use pint.quantify() to restore the units, followed by the convolute() method to combine the nominal values and uncertainties again.

Example Workflow

# Dequantify DataFrame and saving as CSV
df_dequantified = deconv_df.pint.dequantify()
df_dequantified.to_csv("data_with_uncertainties_and_units.csv")

# Read back from CSV
df_read = pd.read_csv("data_with_uncertainties_and_units.csv", header=[0,1], index_col=0)
print(df_read)

          mass   δ(mass)
unit milligram milligram
0          1.0       0.1
1          2.0       0.2
2          3.0       0.3

# Restore units
df_quantified = df_read.pint.quantify(level=-1)

# Restore uncertainties
df_restored = df_quantified.uncrts.convolute()
print(df_restored)

          mass
0  1.00+/-0.10
1  2.00+/-0.20
2  3.00+/-0.30

Changes

All notable changes to this project are documented in the file CHANGELOG.md.

Contributing

Contributions to the UnPaAc package are very welcomed. Feel free to submit a pull request, if you would like to contribute to the project. In case you are unfamiliar with the process, consult the forgejo documentation and follow the steps using this repository instead of the example repository.

Create your pull request (PR) to inform that you start working on a contribution. Provide a clear description of your envisaged changes and the motivation behind them, prefix the PR's title with WIP: until your changes are finalised.

All kind of contributions are appreciated, whether they are bug fixes, new features, or improvements to the documentation.

Development

Installing for development

To install the package in development mode, clone the Git repository and install the package using Poetry, as shown in the code block underneath. To install Poetry, which is required for virtual environment and dependency management, follow the instructions on the Poetry website.

git clone https://codeberg.org/Cs137/unpaac.git
cd unpaac
poetry install

This will create a virtual environment and install the package dependencies and the package itself in editable mode, allowing you to make changes to the code and see the effects immediately in the corresponding virtual environment. Alternatively, you can install it via pip install -e in an existing virtual environment.

License

UnPaAc is open source software released under the MIT License. See LICENSE file for details.

---

This package was created and is maintained by Christian Schreinemachers, (C) 2025.