[](https://codeberg.org/Cs137/UnPaAc/src/branch/main/LICENSE)
[](https://pypi.org/project/UnPaAc/)
[](https://pepy.tech/projects/unpaac)
# UnPaAc - Uncertainties Pandas Accessors
This python package provides accessors to handle quantities with uncertainties
in pandas [`Series`](https://pandas.pydata.org/pandas-docs/stable/reference/series.html#series)
and [`DataFrame`](https://pandas.pydata.org/pandas-docs/stable/reference/frame.html#dataframe)
objects using the packages [`Pint`](https://github.com/hgrecco/pint)
and [`Uncertainties`](https://github.com/lebigot/uncertainties).
The accessors combine some of the functionalities provided by their pandas
integrations [`pint-pandas`](https://github.com/hgrecco/pint-pandas) and
[`uncertainties-pandas`](https://github.com/andrewgsavage/uncertainties-pandas/tree/main).
```{warning}
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`](https://pandas.pydata.org/pandas-docs/stable/development/extending.html#extensionarray)
provided by the [`pint-pandas` package](https://github.com/hgrecco/pint-pandas)
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](https://pint-pandas.readthedocs.io/en/latest).
- __Pint Uncertainty Series__ are Pint Series where the `PintArray` holds an `UncertaintyArray`.
The latter is provided by the [`uncertainties-pandas` package](https://github.com/andrewgsavage/uncertainties-pandas/tree/main)
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](http://uncertainties.readthedocs.io/), and an example for
the combination with a `PintArray` in [this section](https://pint-pandas.readthedocs.io/en/latest/user/initializing.html#non-native-pandas-dtypes)
of the pint-pandas documentation.
## Installation
Install the latest release of UnPaAc from [PyPI](https://pypi.org/project/unpaac/)
via `pip`:
```sh
pip install unpaac
```
The development version can be installed from
[the Git repository](https://codeberg.org/Cs137/unpaac) using `pip`:
```sh
# Via https
pip install git+https://codeberg.org/Cs137/unpaac.git
# Via ssh
pip install git+ssh://git@codeberg.org: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`:
```python
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](https://codeberg.org/Cs137/unpaac/issues).
### 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.
```python
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](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html)
that are passed to the pandas Series constructor, e.g. `name`.
If uncertainties are provided, a Pint Uncertainty Series is created.
```python
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.
```python
pu_series.uncrts.n
```
0 1.0
1 2.0
2 3.0
Name: length, dtype: pint[meter][Float64]
```python
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:
```python
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.
```python
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.
```python
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.
```python
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
```python
# 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
```python
# 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`](https://codeberg.org/Cs137/unpaac/src/branch/main/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](https://forgejo.org/docs/latest/user/pull-requests-and-git-flow/)
and follow the steps using this repository instead of the `example` repository.
Create your [pull request (PR)](https://codeberg.org/Cs137/unpaac/pulls) 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](https://python-poetry.org/docs/#installation).
```bash
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](https://codeberg.org/Cs137/UnPaAc/src/branch/main/LICENSE) file for details.
---
This package was created and is maintained by Christian Schreinemachers, (C) 2025.
Raw data
{
"_id": null,
"home_page": null,
"name": "unpaac",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "physical, quantities, unit, conversion, error propagation, uncertainties, uncertainty, uncertainty calculations, standard deviation, science, pandas, series, dataframe",
"author": "Christian Schreinemachers (Cs137)",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/4c/e3/23dcf45ba37c62472361e110b6ee1eb5f8e3e22fdaeaea52e0678eb96030/unpaac-0.1.4.tar.gz",
"platform": null,
"description": "[](https://codeberg.org/Cs137/UnPaAc/src/branch/main/LICENSE)\n[](https://pypi.org/project/UnPaAc/)\n[](https://pepy.tech/projects/unpaac)\n\n\n# UnPaAc - Uncertainties Pandas Accessors\n\nThis python package provides accessors to handle quantities with uncertainties\nin pandas [`Series`](https://pandas.pydata.org/pandas-docs/stable/reference/series.html#series)\nand [`DataFrame`](https://pandas.pydata.org/pandas-docs/stable/reference/frame.html#dataframe)\nobjects using the packages [`Pint`](https://github.com/hgrecco/pint)\nand [`Uncertainties`](https://github.com/lebigot/uncertainties).\nThe accessors combine some of the functionalities provided by their pandas\nintegrations [`pint-pandas`](https://github.com/hgrecco/pint-pandas) and\n[`uncertainties-pandas`](https://github.com/andrewgsavage/uncertainties-pandas/tree/main).\n\n\n```{warning}\nThe project is currently under development and changes in its behaviour might be introduced.\n```\n\n\n## Glossary\n\n- __Pint Series__ are pandas Series that contain a `PintArray` as values. The\n `PintArray` is a Pandas [`ExtensionArray`](https://pandas.pydata.org/pandas-docs/stable/development/extending.html#extensionarray)\n provided by the [`pint-pandas` package](https://github.com/hgrecco/pint-pandas)\n and allows performing unit-aware operations where appropriate. The units are\n reflected in the Series' `dtype` attribute, e.g. `pint[milligram][Float64]`.\n The `subdtype` corresponds to the `dtype` of the magnitudes. For detailed information\n consult the [`pint-pandas` documentation](https://pint-pandas.readthedocs.io/en/latest).\n\n- __Pint Uncertainty Series__ are Pint Series where the `PintArray` holds an `UncertaintyArray`.\n The latter is provided by the [`uncertainties-pandas` package](https://github.com/andrewgsavage/uncertainties-pandas/tree/main)\n and results in a `subdtype` corresponding to `UncertaintyDtype`.\n Pint Uncertainty Series allow calculations with quantities having uncertainties.\n Detailed information on the `uncertainties` package can be found in\n [its documentation](http://uncertainties.readthedocs.io/), and an example for\n the combination with a `PintArray` in [this section](https://pint-pandas.readthedocs.io/en/latest/user/initializing.html#non-native-pandas-dtypes)\n of the pint-pandas documentation.\n\n\n## Installation\n\nInstall the latest release of UnPaAc from [PyPI](https://pypi.org/project/unpaac/)\nvia `pip`:\n\n```sh\npip install unpaac\n```\n\nThe development version can be installed from\n[the Git repository](https://codeberg.org/Cs137/unpaac) using `pip`:\n\n```sh\n# Via https\npip install git+https://codeberg.org/Cs137/unpaac.git\n\n# Via ssh\npip install git+ssh://git@codeberg.org:Cs137/unpaac.git\n```\n\n\n## Usage\n\nThe pandas `Series` and `DataFrame` accessors are available via the `uncrts`\nattribute of instances of the aforementioned object classes. In order to make\nuse of the accessors, import the module `uncrts` from the package `unpaac`:\n\n```python\nfrom unpaac import uncrts\n```\n\nThe available methods provide detailed docstrings, including examples.\nHowever, the following subsection demonstrates a couple of use cases, including\na workflow that can be adopted to store and restore pandas DataFrames that contain\nquantities with uncertainties.\n\nIf you have any questions or need assistance, feel free to\n[open an issue on the repository](https://codeberg.org/Cs137/unpaac/issues).\n\n### Examples\n\n#### Create a Pint Series\n\nA Pint Series can be created via the `create_pint_series()` function.\nThe creation with the mandatory attributes `values` and `unit`, is shown underneath.\n\n```python\nfrom unpaac.uncrts import create_pint_series\n\np_series = create_pint_series([1.0, 2.0, 3.0], \"mg\")\nprint(p_series)\n```\n\n 0 1.0\n 1 2.0\n 2 3.0\n dtype: pint[milligram][Float64]\n\nOptionally, you can declare `uncertainties` and/or\n[further keyword arguments](https://pandas.pydata.org/pandas-docs/stable/reference/api/pandas.Series.html)\nthat are passed to the pandas Series constructor, e.g. `name`.\nIf uncertainties are provided, a Pint Uncertainty Series is created.\n\n```python\npu_series = create_pint_series([1.0, 2.0, 3.0], \"m\", uncertainties=[0.1, 0.2, 0.3], name=\"length\")\nprint(pu_series)\n```\n\n 0 1.00+/-0.10\n 1 2.00+/-0.20\n 2 3.00+/-0.30\n Name: length, dtype: pint[meter][UncertaintyDtype]\n\n#### Retrieve nominal values and standard deviations as Pint Series\n\nYou can obtain Pint Series of the nominal values and standard deviations via the\nseries accessor properties `nominal_values` and `std_devs`, or their shortcuts\n`n` and `s`, respectively.\n\n```python\npu_series.uncrts.n\n```\n\n 0 1.0\n 1 2.0\n 2 3.0\n Name: length, dtype: pint[meter][Float64]\n\n```python\npu_series.uncrts.s\n```\n\n 0 0.1\n 1 0.2\n 2 0.3\n Name: \u03b4(length), dtype: pint[meter][Float64]\n\nThe method `to_series()` returns a tuple with both Pint Series:\n\n```python\nn, s = pu_series.uncrts.to_series()\n```\n\n#### Add Uncertainties to a Pint Series in a DataFrame\n\nThe DataFrame accessor allows assigning uncertainties to a column that holds a\nPint Series via the `add()` method, as shows underneath.\n\n```python\ndf = pd.DataFrame({\"mass\": p_series})\ndf.uncrts.add(\"mass\", [0.1, 0.2, 0.3])\nprint(df)\n```\n\n mass\n 0 1.00+/-0.10\n 1 2.00+/-0.20\n 2 3.00+/-0.30\n\n#### Deconvolute Pint Uncertainty Series Columns\n\nThe `deconvolute()` method allows splitting a column with a Pint Uncertainty Series\ninto separate columns for nominal values and uncertainties containing Pint Series.\n\n```python\ndeconv_df = df.uncrts.deconvolute()\nprint(deconv_df)\n```\n\n mass \u03b4(mass)\n 0 1.0 0.1\n 1 2.0 0.2\n 2 3.0 0.3\n\n#### Convolute Pint Series Columns\n\nThe `convolute()` method allows combining nominal values and standard deviations\nfrom separate columns containing Pint Series into a single column holding a Pint\nUncertainty Series. In case your standard deviation column uses custom `prefix`\nand `suffix` values, those can be specified as keyword arguments to a call of the\nmethod.\n\n```python\ndeconv_df.uncrts.convolute()\n```\n\n mass\n 0 1.00+/-0.10\n 1 2.00+/-0.20\n 2 3.00+/-0.30\n\n### Save a DataFrame to CSV and restore DataFrame from CSV\n\nAfter using the `deconvolute()` method to split a Pint Uncertainty Series column\ninto Pint Series with the nominal values and uncertainties, you can save the data\nto a CSV file. However, you should first apply `pint.dequantify()` method to add\nthe units to the column headers before saving. When reading the data back, use\n`pint.quantify()` to restore the units, followed by the `convolute()` method to\ncombine the nominal values and uncertainties again.\n\n#### Example Workflow\n\n```python\n# Dequantify DataFrame and saving as CSV\ndf_dequantified = deconv_df.pint.dequantify()\ndf_dequantified.to_csv(\"data_with_uncertainties_and_units.csv\")\n\n# Read back from CSV\ndf_read = pd.read_csv(\"data_with_uncertainties_and_units.csv\", header=[0,1], index_col=0)\nprint(df_read)\n```\n mass \u03b4(mass)\n unit milligram milligram\n 0 1.0 0.1\n 1 2.0 0.2\n 2 3.0 0.3\n\n```python\n# Restore units\ndf_quantified = df_read.pint.quantify(level=-1)\n\n# Restore uncertainties\ndf_restored = df_quantified.uncrts.convolute()\nprint(df_restored)\n```\n\n mass\n 0 1.00+/-0.10\n 1 2.00+/-0.20\n 2 3.00+/-0.30\n\n\n## Changes\n\nAll notable changes to this project are documented in the file\n[`CHANGELOG.md`](https://codeberg.org/Cs137/unpaac/src/branch/main/CHANGELOG.md).\n\n\n## Contributing\n\nContributions to the `UnPaAc` package are very welcomed. Feel free to submit a\npull request, if you would like to contribute to the project. In case you are\nunfamiliar with the process, consult the\n[forgejo documentation](https://forgejo.org/docs/latest/user/pull-requests-and-git-flow/)\nand follow the steps using this repository instead of the `example` repository.\n\nCreate your [pull request (PR)](https://codeberg.org/Cs137/unpaac/pulls) to\ninform that you start working on a contribution. Provide a clear description\nof your envisaged changes and the motivation behind them, prefix the PR's title\nwith ``WIP: `` until your changes are finalised.\n\nAll kind of contributions are appreciated, whether they are\nbug fixes, new features, or improvements to the documentation.\n\n\n## Development\n\n### Installing for development\n\nTo install the package in development mode, clone the Git repository and install\nthe package using Poetry, as shown in the code block underneath. To install Poetry,\nwhich is required for virtual environment and dependency management, follow the\ninstructions on the [Poetry website](https://python-poetry.org/docs/#installation).\n\n```bash\ngit clone https://codeberg.org/Cs137/unpaac.git\ncd unpaac\npoetry install\n```\n\nThis will create a virtual environment and install the package dependencies and\nthe package itself in editable mode, allowing you to make changes to the code and\nsee the effects immediately in the corresponding virtual environment. Alternatively,\nyou can install it via `pip install -e` in an existing virtual environment.\n\n\n## License\n\nUnPaAc is open source software released under the MIT License.\nSee [LICENSE](https://codeberg.org/Cs137/UnPaAc/src/branch/main/LICENSE) file for details.\n\n---\n\nThis package was created and is maintained by Christian Schreinemachers, (C) 2025.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pandas DataFrame and Series accessors to handle quantities with uncertainties.",
"version": "0.1.4",
"project_urls": {
"Changelog": "https://codeberg.org/Cs137/UnPaAc/src/branch/main/CHANGELOG.md",
"Issues": "https://codeberg.org/Cs137/UnPaAc/issues",
"repository": "https://codeberg.org/Cs137/UnPaAc"
},
"split_keywords": [
"physical",
" quantities",
" unit",
" conversion",
" error propagation",
" uncertainties",
" uncertainty",
" uncertainty calculations",
" standard deviation",
" science",
" pandas",
" series",
" dataframe"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e300f437594a8497eec37d3a57ae6bf7e7c7f22d70b48344c3b8d0363ba60238",
"md5": "7d33164523b7f2aff0505760b5a65550",
"sha256": "bc261025fa6d415e9d86106c2d26f34c989eca9af47d1b6c065be5c4401ead72"
},
"downloads": -1,
"filename": "unpaac-0.1.4-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7d33164523b7f2aff0505760b5a65550",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 10227,
"upload_time": "2025-03-03T00:13:11",
"upload_time_iso_8601": "2025-03-03T00:13:11.181782Z",
"url": "https://files.pythonhosted.org/packages/e3/00/f437594a8497eec37d3a57ae6bf7e7c7f22d70b48344c3b8d0363ba60238/unpaac-0.1.4-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "4ce323dcf45ba37c62472361e110b6ee1eb5f8e3e22fdaeaea52e0678eb96030",
"md5": "4a649e1d6b2150547a77e61da94884fa",
"sha256": "ee914d574ccb26e7968f5d971fce4df434811c5b1e277df6e5f9baf84cb2f099"
},
"downloads": -1,
"filename": "unpaac-0.1.4.tar.gz",
"has_sig": false,
"md5_digest": "4a649e1d6b2150547a77e61da94884fa",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 9158,
"upload_time": "2025-03-03T00:13:12",
"upload_time_iso_8601": "2025-03-03T00:13:12.429394Z",
"url": "https://files.pythonhosted.org/packages/4c/e3/23dcf45ba37c62472361e110b6ee1eb5f8e3e22fdaeaea52e0678eb96030/unpaac-0.1.4.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-03-03 00:13:12",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": true,
"codeberg_user": "Cs137",
"codeberg_project": "UnPaAc",
"lcname": "unpaac"
}
JSON