| Name | unpaac JSON |
| Version |
0.1.0
JSON |
| download |
| home_page | None |
| Summary | Pandas DataFrame and Series accessors to handle quantities with uncertainties. |
| upload_time | 2025-01-20 10:13:37 |
| maintainer | None |
| docs_url | None |
| author | Christian Schreinemachers (Cs137) |
| requires_python | <4.0,>=3.13 |
| license | MIT |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
.. image:: https://img.shields.io/pypi/v/UnPaAc.svg
:target: https://pypi.python.org/pypi/UnPaAc
:alt: Latest Version
# UnPaAc - Uncertainties Pandas Accessors
This python package provides accessors to handle quantities with uncertainties in
pandas `Series` and `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 the 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.
```
## Installation
<!-- Install UnPaAc simply via `pip`: -->
<!-- ```sh -->
<!-- $ pip install unpaac -->
<!-- ``` -->
The package is currently not available via PyPI, but can be installed it from
[its 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
```
### 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.
## Usage
Import `unpaac.uncrts` in order to make use of the `Series` and/or `DataFrame`
accessors. They are available via the `uncrts` attribute of instances of the
aforementioned object classes.
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 pandas Series that holds a PintArray 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 that
are passed to the pandas Series constructor, like e.g. a `name`.
If uncertainties are provided, an UncertaintyArray is created, which is nested
in the PintArray that is assigned to the values of the created series.
```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]
```
#### Access nominal values and standard deviations in a Pint Uncertainty Series
You can access the nominal values and standard deviations via the series accessors
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]
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, nominal values and
standard deviations.
#### Add Uncertainties to a pint Series in a DataFrame
The DataFrame accessor allows to assign 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 Columns
The `deconvolute` method allows to split a column with a pint uncertainty series
into separate columns for nominal values and uncertainties.
```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 Columns
The `convolute` method allows to to combine nominal value and uncertainty columns
from separate columns into a single column.
```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 column with a `PintArray` into
nominal values and uncertainties, you can save the data to CSV. However, you must
first apply `pint.dequantify()` to add units to the columns 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 deconvoluted DataFrame to add units to it before saving as CSV
df_dequantified = deconv_df.pint.dequantify()
df_dequantified.to_csv("data_with_uncertainties_and_units.csv")
# Read back
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_deconvoluted.pint.quantify(level=-1)
print(df_quantified)
mass δ(mass)
0 1.0 0.1
1 2.0 0.2
2 3.0 0.3
# Reapply convolute to restore uncertainty data
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
```
## 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.
## 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.
---
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": "<4.0,>=3.13",
"maintainer_email": null,
"keywords": null,
"author": "Christian Schreinemachers (Cs137)",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/31/19/bcc5a164ff2b377f14da4c6895d72183cc9ceeeabbf7254c336f8ffacb69/unpaac-0.1.0.tar.gz",
"platform": null,
"description": ".. image:: https://img.shields.io/pypi/v/UnPaAc.svg\n :target: https://pypi.python.org/pypi/UnPaAc\n :alt: Latest Version\n\n\n# UnPaAc - Uncertainties Pandas Accessors\n\nThis python package provides accessors to handle quantities with uncertainties in\npandas `Series` and `DataFrame` objects 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 the 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## Installation\n\n<!-- Install UnPaAc simply via `pip`: -->\n\n<!-- ```sh -->\n<!-- $ pip install unpaac -->\n<!-- ``` -->\n\nThe package is currently not available via PyPI, but can be installed it from\n[its 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### 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## Usage\n\nImport `unpaac.uncrts` in order to make use of the `Series` and/or `DataFrame`\naccessors. They are available via the `uncrts` attribute of instances of the\naforementioned object classes.\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 pandas Series that holds a PintArray 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)\n0 1.0\n1 2.0\n2 3.0\ndtype: pint[milligram][Float64]\n```\n\nOptionally, you can declare `uncertainties` and/or further keyword arguments that\nare passed to the pandas Series constructor, like e.g. a `name`.\nIf uncertainties are provided, an UncertaintyArray is created, which is nested\nin the PintArray that is assigned to the values of the created series.\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)\n0 1.00+/-0.10\n1 2.00+/-0.20\n2 3.00+/-0.30\nName: length, dtype: pint[meter][UncertaintyDtype]\n```\n\n#### Access nominal values and standard deviations in a Pint Uncertainty Series\n\nYou can access the nominal values and standard deviations via the series accessors\nproperties `nominal_values` and `std_devs`, or their shortcuts `n` and `s`, respectively.\n\n```python\npu_series.uncrts.n\n0 1.0\n1 2.0\n2 3.0\nName: length, dtype: pint[meter][Float64]\n\npu_series.uncrts.s\n0 0.1\n1 0.2\n2 0.3\nName: \u03b4(length), dtype: pint[meter][Float64]\n```\n\nThe method `to_series` returns a tuple with both pint series, nominal values and\nstandard deviations.\n\n#### Add Uncertainties to a pint Series in a DataFrame\n\nThe DataFrame accessor allows to assign 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 mass\n0 1.00+/-0.10\n1 2.00+/-0.20\n2 3.00+/-0.30\n```\n\n#### Deconvolute Columns\n\nThe `deconvolute` method allows to split a column with a pint uncertainty series\ninto separate columns for nominal values and uncertainties.\n\n```python\ndeconv_df = df.uncrts.deconvolute()\nprint(deconv_df)\n mass \u03b4(mass)\n0 1.0 0.1\n1 2.0 0.2\n2 3.0 0.3\n```\n\n#### Convolute Columns\n\nThe `convolute` method allows to to combine nominal value and uncertainty columns\nfrom separate columns into a single column.\n\n```python\ndeconv_df.uncrts.convolute()\n mass\n0 1.00+/-0.10\n1 2.00+/-0.20\n2 3.00+/-0.30\n```\n\n### Save a DataFrame to CSV and restore DataFrame from CSV\n\nAfter using the `deconvolute` method to split a column with a `PintArray` into\nnominal values and uncertainties, you can save the data to CSV. However, you must\nfirst apply `pint.dequantify()` to add units to the columns before saving.\nWhen reading the data back, use `pint.quantify()` to restore the units, followed\nby the `convolute` method to combine the nominal values and uncertainties again.\n\n#### Example Workflow\n\n```python\n# Dequantify deconvoluted DataFrame to add units to it before saving as CSV\ndf_dequantified = deconv_df.pint.dequantify()\ndf_dequantified.to_csv(\"data_with_uncertainties_and_units.csv\")\n\n# Read back\ndf_read = pd.read_csv(\"data_with_uncertainties_and_units.csv\", header=[0,1], index_col=0)\nprint(df_read)\n mass \u03b4(mass)\nunit milligram milligram\n0 1.0 0.1\n1 2.0 0.2\n2 3.0 0.3\n\n# Restore units\ndf_quantified = df_deconvoluted.pint.quantify(level=-1)\nprint(df_quantified)\n mass \u03b4(mass)\n0 1.0 0.1\n1 2.0 0.2\n2 3.0 0.3\n\n# Reapply convolute to restore uncertainty data\ndf_restored = df_quantified.uncrts.convolute()\nprint(df_restored)\n mass\n0 1.00+/-0.10\n1 2.00+/-0.20\n2 3.00+/-0.30\n```\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## 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---\n\nThis package was created and is maintained by Christian Schreinemachers, (C) 2025.\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Pandas DataFrame and Series accessors to handle quantities with uncertainties.",
"version": "0.1.0",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "0eb14ada30507cce51ac709ebff2fea7bc15cd7bd515966f0370813e5639599d",
"md5": "cc5d2760172baf0512932470b3dd1f3d",
"sha256": "8c0d5ec72485108ed65e60576a3d2292ab14157d68de9766f001490006a76856"
},
"downloads": -1,
"filename": "unpaac-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "cc5d2760172baf0512932470b3dd1f3d",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4.0,>=3.13",
"size": 9306,
"upload_time": "2025-01-20T10:13:35",
"upload_time_iso_8601": "2025-01-20T10:13:35.828902Z",
"url": "https://files.pythonhosted.org/packages/0e/b1/4ada30507cce51ac709ebff2fea7bc15cd7bd515966f0370813e5639599d/unpaac-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "3119bcc5a164ff2b377f14da4c6895d72183cc9ceeeabbf7254c336f8ffacb69",
"md5": "0e9930c2865748360b8ce96848b9d4f8",
"sha256": "47f79249c23f988c027c63e8dde210ad234c9ec1b7b43da760fe8b8886a84c2b"
},
"downloads": -1,
"filename": "unpaac-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "0e9930c2865748360b8ce96848b9d4f8",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4.0,>=3.13",
"size": 8385,
"upload_time": "2025-01-20T10:13:37",
"upload_time_iso_8601": "2025-01-20T10:13:37.381210Z",
"url": "https://files.pythonhosted.org/packages/31/19/bcc5a164ff2b377f14da4c6895d72183cc9ceeeabbf7254c336f8ffacb69/unpaac-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-01-20 10:13:37",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "unpaac"
}
