# Xarray_SimpleUnits
[](https://github.com/st-bender/xarray-simpleunits/actions/workflows/ci_build_and_test.yml)
[](https://pypi.org/project/xarray-simpleunits)
[](https://pypi.org/project/xarray-simpleunits)
[](https://pypi.org/project/xarray-simpleunits)
[](https://codecov.io/gh/st-bender/xarray-simpleunits)
[](https://coveralls.io/github/st-bender/xarray-simpleunits)
**Unitful calculations with `xarray`**
Keeps track of units when working with `xarray.DataArray`s
and `xarray.Dataset`s using `astropy.units` for the conversions.
:warning: This package is in **alpha** stage, that is, it works mostly,
but the interface might still be subject to change.
## Install
### Requirements
- `astropy` - required
- `xarray` - required
- `pytest` - optional, for testing
### xarray_simpleunits
An installable `pip` package called `xarray-simpleunits` will be available soon
from the main package repository, it can then be installed with:
```sh
$ pip install xarray_simpleunits
```
The latest development version can be installed
with [`pip`](https://pip.pypa.io) directly from github
(see <https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support>
and <https://pip.pypa.io/en/stable/reference/pip_install/#git>):
```sh
$ pip install [-e] git+https://github.com/st-bender/xarray-simpleunits.git
```
The other option is to use a local clone:
```sh
$ git clone https://github.com/st-bender/xarray-simpleunits.git
$ cd xarray-simpleunits
```
and then using `pip` (optionally using `-e`, see
<https://pip.pypa.io/en/stable/reference/pip_install/#install-editable>):
```sh
$ pip install [-e] .
```
or using `setup.py`:
```sh
$ python setup.py install
```
Optionally, test the correct function of the module with
```sh
$ py.test [-v]
```
or even including the [doctests](https://docs.python.org/library/doctest.html)
in this document:
```sh
$ py.test [-v] --doctest-glob='*.md'
```
## Usage
The python module itself is named `xarray_simpleunits` and is imported as usual.
All functions should be `numpy`-compatible and work with scalars
and appropriately shaped arrays.
```python
>>> import xarray_simpleunits as xru
```
The module basically works by adapting (“monkey-patching”) the `xarray.Variable` arithmetic
methods to honour and keep track of the "units" attribute.
To initialize unit handling with `xarray`, call `init_units()` first:
```python
>>> import xarray_simpleunits as xru
>>> xru.init_units()
```
(A similar method to restore the original behaviour is planned.)
So far, the supported operations are addition, subtraction, multiplication, and division.
Unit mismatch when adding or subtracting unitful arrays raises an exception.
Currently, unit handling with `xarray.DataArray` requires that the respective
array is on the left side of any calculation:
```python
>>> from astropy import units as au
>>> import numpy as np
>>> import xarray as xr
>>> import xarray_simpleunits as xru
>>> np.set_printoptions(precision=6)
>>> xru.init_units()
>>> ds = xr.Dataset(
... data_vars={
... "s": ("x", [1., 2., 3.], {"units": "m"}),
... "t": ("x", [3., 2., 1.], {"units": "s"}),
... },
... )
>>> v = ds["s"] / ds["t"]
>>> v
<xarray.DataArray (x: 3)>
array([0.333333, 1. , 3. ])
Dimensions without coordinates: x
Attributes:
units: m / s
>>> # using `astropy` units directly:
>>> v = ds["s"] / (2 * au.Unit("s"))
>>> v
<xarray.DataArray 's' (x: 3)>
array([0.5, 1. , 1.5])
Dimensions without coordinates: x
Attributes:
units: m / s
```
Basic class and method documentation is accessible via `pydoc`:
```sh
$ pydoc xarray_simpleunits
```
## License
This python package is free software: you can redistribute it or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, version 2 (GPLv2), see [local copy](./LICENSE)
or [online version](http://www.gnu.org/licenses/gpl-2.0.html).
Raw data
{
"_id": null,
"home_page": "https://github.com/st-bender/xarray-simpleunits",
"name": "xarray-simpleunits",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Stefan Bender",
"author_email": "sbender@iaa.es",
"download_url": "https://files.pythonhosted.org/packages/51/62/b6b357b25120b4ab464f5f9586b672773d8a3fe81227526554a2ebbc6a68/xarray_simpleunits-0.0.3.tar.gz",
"platform": null,
"description": "# Xarray_SimpleUnits\n\n[](https://github.com/st-bender/xarray-simpleunits/actions/workflows/ci_build_and_test.yml)\n[](https://pypi.org/project/xarray-simpleunits)\n[](https://pypi.org/project/xarray-simpleunits)\n[](https://pypi.org/project/xarray-simpleunits)\n[](https://codecov.io/gh/st-bender/xarray-simpleunits)\n[](https://coveralls.io/github/st-bender/xarray-simpleunits)\n\n**Unitful calculations with `xarray`**\n\nKeeps track of units when working with `xarray.DataArray`s\nand `xarray.Dataset`s using `astropy.units` for the conversions.\n\n:warning: This package is in **alpha** stage, that is, it works mostly,\nbut the interface might still be subject to change.\n\n## Install\n\n### Requirements\n\n- `astropy` - required\n- `xarray` - required\n- `pytest` - optional, for testing\n\n### xarray_simpleunits\n\nAn installable `pip` package called `xarray-simpleunits` will be available soon\nfrom the main package repository, it can then be installed with:\n```sh\n$ pip install xarray_simpleunits\n```\nThe latest development version can be installed\nwith [`pip`](https://pip.pypa.io) directly from github\n(see <https://pip.pypa.io/en/stable/reference/pip_install/#vcs-support>\nand <https://pip.pypa.io/en/stable/reference/pip_install/#git>):\n\n```sh\n$ pip install [-e] git+https://github.com/st-bender/xarray-simpleunits.git\n```\n\nThe other option is to use a local clone:\n\n```sh\n$ git clone https://github.com/st-bender/xarray-simpleunits.git\n$ cd xarray-simpleunits\n```\nand then using `pip` (optionally using `-e`, see\n<https://pip.pypa.io/en/stable/reference/pip_install/#install-editable>):\n\n```sh\n$ pip install [-e] .\n```\n\nor using `setup.py`:\n\n```sh\n$ python setup.py install\n```\n\nOptionally, test the correct function of the module with\n\n```sh\n$ py.test [-v]\n```\n\nor even including the [doctests](https://docs.python.org/library/doctest.html)\nin this document:\n\n```sh\n$ py.test [-v] --doctest-glob='*.md'\n```\n\n## Usage\n\nThe python module itself is named `xarray_simpleunits` and is imported as usual.\n\nAll functions should be `numpy`-compatible and work with scalars\nand appropriately shaped arrays.\n\n```python\n>>> import xarray_simpleunits as xru\n\n```\n\nThe module basically works by adapting (\u201cmonkey-patching\u201d) the `xarray.Variable` arithmetic\nmethods to honour and keep track of the \"units\" attribute.\nTo initialize unit handling with `xarray`, call `init_units()` first:\n\n```python\n>>> import xarray_simpleunits as xru\n>>> xru.init_units()\n\n```\n(A similar method to restore the original behaviour is planned.)\n\nSo far, the supported operations are addition, subtraction, multiplication, and division.\nUnit mismatch when adding or subtracting unitful arrays raises an exception.\nCurrently, unit handling with `xarray.DataArray` requires that the respective\narray is on the left side of any calculation:\n\n```python\n>>> from astropy import units as au\n>>> import numpy as np\n>>> import xarray as xr\n>>> import xarray_simpleunits as xru\n>>> np.set_printoptions(precision=6)\n>>> xru.init_units()\n>>> ds = xr.Dataset(\n... data_vars={\n... \"s\": (\"x\", [1., 2., 3.], {\"units\": \"m\"}),\n... \"t\": (\"x\", [3., 2., 1.], {\"units\": \"s\"}),\n... },\n... )\n>>> v = ds[\"s\"] / ds[\"t\"]\n>>> v\n<xarray.DataArray (x: 3)>\narray([0.333333, 1. , 3. ])\nDimensions without coordinates: x\nAttributes:\n units: m / s\n>>> # using `astropy` units directly:\n>>> v = ds[\"s\"] / (2 * au.Unit(\"s\"))\n>>> v\n<xarray.DataArray 's' (x: 3)>\narray([0.5, 1. , 1.5])\nDimensions without coordinates: x\nAttributes:\n units: m / s\n\n```\n\nBasic class and method documentation is accessible via `pydoc`:\n\n```sh\n$ pydoc xarray_simpleunits\n```\n\n## License\n\nThis python package is free software: you can redistribute it or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation, version 2 (GPLv2), see [local copy](./LICENSE)\nor [online version](http://www.gnu.org/licenses/gpl-2.0.html).\n",
"bugtrack_url": null,
"license": "GPLv2",
"summary": "Simple unitful calculations with `xarray`",
"version": "0.0.3",
"project_urls": {
"Homepage": "https://github.com/st-bender/xarray-simpleunits"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "85acad938a670194f007350f7b931e772a7aae0cbdfb7e19a37f66a7ae913bfa",
"md5": "064cc786d8d7fc0539f842b30c75ec05",
"sha256": "297da8f7a2ad6e6f14414f1e18f8eb4eee95966d552b5b482bc7946f59a52d89"
},
"downloads": -1,
"filename": "xarray_simpleunits-0.0.3-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "064cc786d8d7fc0539f842b30c75ec05",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 12553,
"upload_time": "2023-11-13T17:39:25",
"upload_time_iso_8601": "2023-11-13T17:39:25.890724Z",
"url": "https://files.pythonhosted.org/packages/85/ac/ad938a670194f007350f7b931e772a7aae0cbdfb7e19a37f66a7ae913bfa/xarray_simpleunits-0.0.3-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "5162b6b357b25120b4ab464f5f9586b672773d8a3fe81227526554a2ebbc6a68",
"md5": "621cee33085931c0ec355fc69f83a026",
"sha256": "dde2f4e6bd6a8cc9343998cd2a06aa5b7a61008923dc65543622a226358f2201"
},
"downloads": -1,
"filename": "xarray_simpleunits-0.0.3.tar.gz",
"has_sig": false,
"md5_digest": "621cee33085931c0ec355fc69f83a026",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 14100,
"upload_time": "2023-11-13T17:39:27",
"upload_time_iso_8601": "2023-11-13T17:39:27.421636Z",
"url": "https://files.pythonhosted.org/packages/51/62/b6b357b25120b4ab464f5f9586b672773d8a3fe81227526554a2ebbc6a68/xarray_simpleunits-0.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2023-11-13 17:39:27",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "st-bender",
"github_project": "xarray-simpleunits",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "xarray-simpleunits"
}
JSON
