unxts.interop.xarray 2.0.0__tar.gz → 2.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/.gitignore +4 -1
- unxts_interop_xarray-2.1.0/LICENSE +29 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/PKG-INFO +7 -7
- unxts_interop_xarray-2.1.0/docs/_data/README.md +20 -0
- unxts_interop_xarray-2.1.0/docs/_data/generate_sample_data.py +50 -0
- unxts_interop_xarray-2.1.0/docs/_data/sample_data.nc +0 -0
- unxts_interop_xarray-2.1.0/docs/api.md +99 -0
- unxts_interop_xarray-2.1.0/docs/index.md +105 -0
- unxts_interop_xarray-2.1.0/docs/sharp-bits.md +42 -0
- unxts_interop_xarray-2.1.0/docs/tutorial-first-dataset.md +158 -0
- unxts_interop_xarray-2.1.0/docs/xarray-guide.md +508 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/pyproject.toml +6 -5
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/_src/accessors.py +10 -9
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/_src/conversion.py +163 -24
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/_version.py +2 -2
- unxts_interop_xarray-2.1.0/tests/unit/test_conversion_edges.py +100 -0
- unxts_interop_xarray-2.1.0/tests/unit/test_stale_units_attrs.py +227 -0
- unxts_interop_xarray-2.1.0/tests/unit/test_unknown_unit_keys.py +34 -0
- unxts_interop_xarray-2.0.0/docs/index.md +0 -12
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/README.md +0 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/__init__.py +0 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/_src/__init__.py +0 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/py.typed +0 -0
- {unxts_interop_xarray-2.0.0/tests → unxts_interop_xarray-2.1.0/tests/smoke}/test_public_api.py +0 -0
|
@@ -80,7 +80,7 @@ instance/
|
|
|
80
80
|
|
|
81
81
|
# Sphinx documentation
|
|
82
82
|
docs/_build/
|
|
83
|
-
docs/
|
|
83
|
+
docs/how-to/optimize-performance.ipynb
|
|
84
84
|
|
|
85
85
|
# PyBuilder
|
|
86
86
|
.pybuilder/
|
|
@@ -164,3 +164,6 @@ Thumbs.db
|
|
|
164
164
|
*~
|
|
165
165
|
*.swp
|
|
166
166
|
/.codspeed
|
|
167
|
+
|
|
168
|
+
# graphify knowledge graph (generated; `nox -s graph`)
|
|
169
|
+
/graphify-out/
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
BSD 3-Clause License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2023, Nathaniel Starkman.
|
|
4
|
+
All rights reserved.
|
|
5
|
+
|
|
6
|
+
Redistribution and use in source and binary forms, with or without
|
|
7
|
+
modification, are permitted provided that the following conditions are met:
|
|
8
|
+
|
|
9
|
+
* Redistributions of source code must retain the above copyright notice, this
|
|
10
|
+
list of conditions and the following disclaimer.
|
|
11
|
+
|
|
12
|
+
* Redistributions in binary form must reproduce the above copyright notice,
|
|
13
|
+
this list of conditions and the following disclaimer in the documentation
|
|
14
|
+
and/or other materials provided with the distribution.
|
|
15
|
+
|
|
16
|
+
* Neither the name of the copyright holder nor the names of its
|
|
17
|
+
contributors may be used to endorse or promote products derived from
|
|
18
|
+
this software without specific prior written permission.
|
|
19
|
+
|
|
20
|
+
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
|
|
21
|
+
AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
22
|
+
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
|
|
23
|
+
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
|
|
24
|
+
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
25
|
+
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
|
|
26
|
+
SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
|
|
27
|
+
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
|
|
28
|
+
OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
|
|
29
|
+
OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
|
@@ -1,26 +1,26 @@
|
|
|
1
|
-
Metadata-Version: 2.
|
|
1
|
+
Metadata-Version: 2.5
|
|
2
2
|
Name: unxts.interop.xarray
|
|
3
|
-
Version: 2.
|
|
3
|
+
Version: 2.1.0
|
|
4
4
|
Summary: xarray integration for unxt (canonical: unxts.interop.xarray)
|
|
5
5
|
Project-URL: Bug Tracker, https://github.com/GalacticDynamics/unxt/issues
|
|
6
6
|
Project-URL: Homepage, https://github.com/GalacticDynamics/unxt
|
|
7
7
|
Author-email: GalacticDynamics <nstarman@users.noreply.github.com>, Nathaniel Starkman <nstarman@users.noreply.github.com>
|
|
8
|
-
License: BSD-3-Clause
|
|
8
|
+
License-Expression: BSD-3-Clause
|
|
9
|
+
License-File: LICENSE
|
|
9
10
|
Classifier: Development Status :: 4 - Beta
|
|
10
11
|
Classifier: Intended Audience :: Developers
|
|
11
12
|
Classifier: Intended Audience :: Science/Research
|
|
12
|
-
Classifier: License :: OSI Approved :: BSD License
|
|
13
13
|
Classifier: Operating System :: OS Independent
|
|
14
14
|
Classifier: Programming Language :: Python
|
|
15
15
|
Classifier: Programming Language :: Python :: 3
|
|
16
16
|
Classifier: Programming Language :: Python :: 3 :: Only
|
|
17
|
-
Classifier: Programming Language :: Python :: 3.11
|
|
18
17
|
Classifier: Programming Language :: Python :: 3.12
|
|
19
18
|
Classifier: Programming Language :: Python :: 3.13
|
|
19
|
+
Classifier: Programming Language :: Python :: 3.14
|
|
20
20
|
Classifier: Topic :: Scientific/Engineering
|
|
21
21
|
Classifier: Typing :: Typed
|
|
22
|
-
Requires-Python: >=3.
|
|
23
|
-
Requires-Dist: unxt
|
|
22
|
+
Requires-Python: >=3.12
|
|
23
|
+
Requires-Dist: unxt>=2.0.0
|
|
24
24
|
Requires-Dist: xarray>=2024.1.0
|
|
25
25
|
Description-Content-Type: text/markdown
|
|
26
26
|
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Sample Data Files
|
|
2
|
+
|
|
3
|
+
This directory contains sample NetCDF files used in the documentation examples.
|
|
4
|
+
|
|
5
|
+
## Files
|
|
6
|
+
|
|
7
|
+
- `sample_data.nc`: Example atmospheric measurements dataset with CF-compliant unit metadata
|
|
8
|
+
- Generated by `generate_sample_data.py`
|
|
9
|
+
- Contains temperature, pressure, and distance measurements
|
|
10
|
+
- Used in the "Loading from NetCDF" example in `xarray-guide.md`
|
|
11
|
+
|
|
12
|
+
## Regenerating the Data
|
|
13
|
+
|
|
14
|
+
To regenerate the sample data file:
|
|
15
|
+
|
|
16
|
+
```bash
|
|
17
|
+
uv run python generate_sample_data.py
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
This is useful if you need to update the sample data structure or values.
|
|
@@ -0,0 +1,50 @@
|
|
|
1
|
+
"""Generate sample NetCDF file with unit metadata for documentation examples."""
|
|
2
|
+
|
|
3
|
+
from pathlib import Path
|
|
4
|
+
|
|
5
|
+
import xarray as xr
|
|
6
|
+
|
|
7
|
+
# Create sample dataset with unit metadata
|
|
8
|
+
ds = xr.Dataset(
|
|
9
|
+
{
|
|
10
|
+
"temperature": (
|
|
11
|
+
["time", "location"],
|
|
12
|
+
[[273.15, 293.15, 313.15], [275.0, 295.0, 315.0]],
|
|
13
|
+
{"units": "K", "long_name": "Temperature", "standard_name": "temperature"},
|
|
14
|
+
),
|
|
15
|
+
"pressure": (
|
|
16
|
+
["time", "location"],
|
|
17
|
+
[[101325.0, 102000.0, 103000.0], [101500.0, 102200.0, 103200.0]],
|
|
18
|
+
{"units": "Pa", "long_name": "Pressure", "standard_name": "air_pressure"},
|
|
19
|
+
),
|
|
20
|
+
"distance": (
|
|
21
|
+
["location"],
|
|
22
|
+
[0.0, 100.0, 200.0],
|
|
23
|
+
{"units": "m", "long_name": "Distance from origin"},
|
|
24
|
+
),
|
|
25
|
+
},
|
|
26
|
+
coords={
|
|
27
|
+
"time": (
|
|
28
|
+
["time"],
|
|
29
|
+
[0.0, 3600.0],
|
|
30
|
+
{"units": "s", "long_name": "Time since start"},
|
|
31
|
+
),
|
|
32
|
+
"location": (
|
|
33
|
+
["location"],
|
|
34
|
+
[0, 1, 2],
|
|
35
|
+
{"long_name": "Measurement location index"},
|
|
36
|
+
),
|
|
37
|
+
},
|
|
38
|
+
attrs={
|
|
39
|
+
"title": "Sample atmospheric measurements",
|
|
40
|
+
"description": (
|
|
41
|
+
"Example dataset with physical units for unxts.interop.xarray documentation"
|
|
42
|
+
),
|
|
43
|
+
"conventions": "CF-1.8",
|
|
44
|
+
},
|
|
45
|
+
)
|
|
46
|
+
|
|
47
|
+
# Save to NetCDF file (only when run as a script, not on import)
|
|
48
|
+
if __name__ == "__main__":
|
|
49
|
+
output_path = Path(__file__).parent / "sample_data.nc"
|
|
50
|
+
ds.to_netcdf(output_path)
|
|
Binary file
|
|
@@ -0,0 +1,99 @@
|
|
|
1
|
+
# API
|
|
2
|
+
|
|
3
|
+
For task-shaped guidance see [How to use unxt with xarray](xarray-guide).
|
|
4
|
+
|
|
5
|
+
## The `.unxt` accessor
|
|
6
|
+
|
|
7
|
+
Registered on both `DataArray` and `Dataset` when `unxts.interop.xarray` is imported.
|
|
8
|
+
|
|
9
|
+
| Member | Signature | Returns |
|
|
10
|
+
| --- | --- | --- |
|
|
11
|
+
| `.unxt.quantify` | `(units=None, **unit_kwargs)` | a copy with `Quantity` data |
|
|
12
|
+
| `.unxt.dequantify` | `(format=None, unit_attribute="units")` | a copy with plain arrays and unit attributes |
|
|
13
|
+
| `.unxt.units` | property | mapping of name → unit; the data itself is under the `None` key (`DataArray` only) |
|
|
14
|
+
|
|
15
|
+
`quantify`'s `units` accepts a unit string or object (applied to the data), or a mapping of names to units; `**unit_kwargs` is the keyword spelling of the same mapping, so `quantify(time="s")` and `quantify({"time": "s"})` are equivalent. On a `Dataset`, `units` must be a mapping — variables are named. Anything not named is read from that object's `units` attribute, and variables with no `units` attribute are left as plain arrays.
|
|
16
|
+
|
|
17
|
+
`dequantify`'s `format` is passed to {func}`format` to render each unit; the default `None` uses `str(unit)`. `unit_attribute` is the attribute the unit string is written to.
|
|
18
|
+
|
|
19
|
+
## Lower-level functions
|
|
20
|
+
|
|
21
|
+
These are the layer underneath the accessor, for inspecting or manipulating units without going through a `DataArray` or `Dataset`.
|
|
22
|
+
|
|
23
|
+
The `.unxt` accessor covers most workflows, but the four underlying functions are also exported for use in pipelines, custom integrations, or cases where you need direct control.
|
|
24
|
+
|
|
25
|
+
## `extract_unit_attributes`
|
|
26
|
+
|
|
27
|
+
Reads `"units"` attrs from each variable and coordinate — without converting anything to a Quantity. Use this to inspect declared units before committing to a conversion.
|
|
28
|
+
|
|
29
|
+
```python
|
|
30
|
+
import xarray as xr
|
|
31
|
+
from unxts.interop.xarray import extract_unit_attributes
|
|
32
|
+
|
|
33
|
+
ds = xr.Dataset(
|
|
34
|
+
{
|
|
35
|
+
"temperature": ("time", [273.0, 293.0], {"units": "K"}),
|
|
36
|
+
"pressure": ("time", [101325.0, 102000.0]),
|
|
37
|
+
}
|
|
38
|
+
)
|
|
39
|
+
print(extract_unit_attributes(ds))
|
|
40
|
+
# {'temperature': Unit("K")}
|
|
41
|
+
```
|
|
42
|
+
|
|
43
|
+
## `attach_units`
|
|
44
|
+
|
|
45
|
+
Attaches units to a DataArray or Dataset, converting plain array data into Quantities. Use `None` as the key for a DataArray's own data (as opposed to a named coordinate).
|
|
46
|
+
|
|
47
|
+
```python
|
|
48
|
+
import xarray as xr
|
|
49
|
+
from unxts.interop.xarray import attach_units
|
|
50
|
+
|
|
51
|
+
da = xr.DataArray([1.0, 2.0, 3.0], dims=["x"])
|
|
52
|
+
quantified = attach_units(da, {None: "m"})
|
|
53
|
+
print(quantified.data)
|
|
54
|
+
# Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
Use `attach_units` directly when you already have a units mapping (e.g., from a file header or a prior `extract_unit_attributes` call) and want to skip the attribute-reading step.
|
|
58
|
+
|
|
59
|
+
## `extract_units`
|
|
60
|
+
|
|
61
|
+
Reads the units from **existing Quantities** in a DataArray or Dataset. This is the inverse of `attach_units` — use it when you need the units for computation before stripping them.
|
|
62
|
+
|
|
63
|
+
```python
|
|
64
|
+
import xarray as xr
|
|
65
|
+
import unxt as u
|
|
66
|
+
from unxts.interop.xarray import extract_units
|
|
67
|
+
|
|
68
|
+
q = u.Quantity([1.0, 2.0], "m")
|
|
69
|
+
da = xr.DataArray(q, dims=["x"])
|
|
70
|
+
print(extract_units(da))
|
|
71
|
+
# {None: Unit("m")}
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
## `strip_units`
|
|
75
|
+
|
|
76
|
+
Removes Quantity wrappers, returning plain arrays. The unit information is discarded unless you capture it with `extract_units` first.
|
|
77
|
+
|
|
78
|
+
```python
|
|
79
|
+
import xarray as xr
|
|
80
|
+
import unxt as u
|
|
81
|
+
from unxts.interop.xarray import strip_units
|
|
82
|
+
|
|
83
|
+
q = u.Quantity([1.0, 2.0], "m")
|
|
84
|
+
da = xr.DataArray(q, dims=["x"])
|
|
85
|
+
stripped = strip_units(da)
|
|
86
|
+
print(stripped.data)
|
|
87
|
+
# Array([1., 2.], dtype=float32)
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
## When to use the low-level API
|
|
91
|
+
|
|
92
|
+
| Task | Use |
|
|
93
|
+
| --- | --- |
|
|
94
|
+
| Interactive quantify/dequantify | `.unxt.quantify()` / `.unxt.dequantify()` |
|
|
95
|
+
| Inspect declared units without converting | `extract_unit_attributes` |
|
|
96
|
+
| Attach a pre-built units mapping | `attach_units` |
|
|
97
|
+
| Read units from already-quantified data | `extract_units` |
|
|
98
|
+
| Strip Quantities to plain arrays | `strip_units` |
|
|
99
|
+
| Build a custom quantify/dequantify pipeline | All four, composed manually |
|
|
@@ -0,0 +1,105 @@
|
|
|
1
|
+
# `unxts.interop.xarray`
|
|
2
|
+
|
|
3
|
+
```{toctree}
|
|
4
|
+
:maxdepth: 1
|
|
5
|
+
:hidden:
|
|
6
|
+
|
|
7
|
+
tutorial-first-dataset
|
|
8
|
+
xarray-guide
|
|
9
|
+
api
|
|
10
|
+
sharp-bits
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
`unxts.interop.xarray` is the canonical location for [xarray](https://docs.xarray.dev/) integration. It adds a `.unxt` accessor to `DataArray` and `Dataset` that converts between `xarray`'s unit _metadata_ — a `units` string in `.attrs` — and real `unxt.Quantity` values, so units become part of the data rather than a label beside it.
|
|
14
|
+
|
|
15
|
+
Importing the package registers the accessor as an import side effect.
|
|
16
|
+
|
|
17
|
+
## Install
|
|
18
|
+
|
|
19
|
+
The recommended install adds `unxts.interop.xarray` alongside `unxt` via the `interop-xarray` [extra](https://peps.python.org/pep-0508/#extras), so it, `unxt` and `xarray` are resolved together as a compatible set:
|
|
20
|
+
|
|
21
|
+
::::{tab-set}
|
|
22
|
+
|
|
23
|
+
:::{tab-item} uv
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
uv add "unxt[interop-xarray]"
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
:::
|
|
30
|
+
|
|
31
|
+
:::{tab-item} pip
|
|
32
|
+
|
|
33
|
+
```bash
|
|
34
|
+
pip install "unxt[interop-xarray]"
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
:::
|
|
38
|
+
|
|
39
|
+
::::
|
|
40
|
+
|
|
41
|
+
Or install the package directly:
|
|
42
|
+
|
|
43
|
+
::::{tab-set}
|
|
44
|
+
|
|
45
|
+
:::{tab-item} uv
|
|
46
|
+
|
|
47
|
+
```bash
|
|
48
|
+
uv add unxts.interop.xarray
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
:::
|
|
52
|
+
|
|
53
|
+
:::{tab-item} pip
|
|
54
|
+
|
|
55
|
+
```bash
|
|
56
|
+
pip install unxts.interop.xarray
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
:::
|
|
60
|
+
|
|
61
|
+
::::
|
|
62
|
+
|
|
63
|
+
## At a glance
|
|
64
|
+
|
|
65
|
+
```python
|
|
66
|
+
import numpy as np
|
|
67
|
+
import xarray as xr
|
|
68
|
+
|
|
69
|
+
import unxts.interop.xarray # registers the .unxt accessor
|
|
70
|
+
|
|
71
|
+
da = xr.DataArray(np.array([1.0, 2.0, 3.0]), dims="x", attrs={"units": "m"})
|
|
72
|
+
|
|
73
|
+
q = da.unxt.quantify()
|
|
74
|
+
q.data
|
|
75
|
+
# Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
|
|
76
|
+
|
|
77
|
+
plain = q.unxt.dequantify()
|
|
78
|
+
plain.attrs["units"]
|
|
79
|
+
# 'm'
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
`quantify()` reads the `units` attribute and turns the values into a `Quantity`; `dequantify()` reverses it, putting the unit back in `.attrs`.
|
|
83
|
+
|
|
84
|
+
## Pages
|
|
85
|
+
|
|
86
|
+
**Tutorial**
|
|
87
|
+
|
|
88
|
+
- [Turn unit labels into real units](tutorial-first-dataset) — start here: watch `xarray` add kilometres to hours without complaint, then quantify and watch the same operation refuse.
|
|
89
|
+
|
|
90
|
+
**How-to**
|
|
91
|
+
|
|
92
|
+
- [How to use unxt with xarray](xarray-guide) — quantifying and dequantifying `DataArray`s and `Dataset`s, coordinates, unit conversion, JAX transforms, and round-tripping through NetCDF.
|
|
93
|
+
|
|
94
|
+
**Reference**
|
|
95
|
+
|
|
96
|
+
- [API](api) — the functions underneath the accessor: `extract_unit_attributes`, `attach_units`, `extract_units`, `strip_units`.
|
|
97
|
+
|
|
98
|
+
**Discussion**
|
|
99
|
+
|
|
100
|
+
- [The xarray sharp bits](sharp-bits) — why dimension coordinates cannot hold quantities, and which operations drop units.
|
|
101
|
+
|
|
102
|
+
## See also
|
|
103
|
+
|
|
104
|
+
- [xarray documentation](https://docs.xarray.dev/)
|
|
105
|
+
- [unxt documentation](https://unxt.readthedocs.io/)
|
|
@@ -0,0 +1,42 @@
|
|
|
1
|
+
# The xarray sharp bits
|
|
2
|
+
|
|
3
|
+
Two things about the integration surprise people. Both follow from how `xarray` itself works rather than from anything `unxts.interop.xarray` chose, which is why neither is going to be fixed.
|
|
4
|
+
|
|
5
|
+
## Dimension coordinates cannot hold quantities
|
|
6
|
+
|
|
7
|
+
`xarray` backs every _dimension coordinate_ (one named like its dimension, shown with a `*` in the repr) with a `pandas.Index`. Building that index coerces the data to a plain `numpy` array, so a dimension coordinate cannot hold a `Quantity`. This is inherent to `xarray`'s indexing model, not something `unxts.interop.xarray` can override, and it affects every duck-array unit library (including `pint-xarray`) the same way.
|
|
8
|
+
|
|
9
|
+
Assigning one **raises** rather than dropping the unit on the floor — `Quantity.__array__` refuses to hand a dimensionful value to a consumer that cannot see its unit. `quantify()` handles this for you by leaving dimension coordinates plain.
|
|
10
|
+
|
|
11
|
+
**Workaround**: store the unitful values on a _non-dimension_ coordinate, keeping a plain index on the dimension itself:
|
|
12
|
+
|
|
13
|
+
```{code-block} python
|
|
14
|
+
>>> import unxt as u
|
|
15
|
+
>>> import xarray as xr
|
|
16
|
+
|
|
17
|
+
>>> data = [10.0, 20.0, 30.0]
|
|
18
|
+
>>> quantities = u.Q([1.0, 2.0, 3.0], "m")
|
|
19
|
+
|
|
20
|
+
>>> # Dimension coordinate: refused, because the unit could not survive
|
|
21
|
+
>>> try:
|
|
22
|
+
... xr.DataArray(data, dims=["x"], coords={"x": quantities})
|
|
23
|
+
... except Exception as e:
|
|
24
|
+
... print(type(e).__name__)
|
|
25
|
+
UnitConversionError
|
|
26
|
+
|
|
27
|
+
>>> # Non-dimension coordinate: the Quantity (and its unit) is preserved
|
|
28
|
+
>>> da = xr.DataArray(data, dims=["i"],
|
|
29
|
+
... coords={"i": [0, 1, 2], "x": ("i", quantities)})
|
|
30
|
+
>>> da.coords["x"].data
|
|
31
|
+
Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
|
|
32
|
+
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Operations that drop units
|
|
36
|
+
|
|
37
|
+
A few `xarray` operations route through code paths that cannot preserve a `Quantity`:
|
|
38
|
+
|
|
39
|
+
- **`rolling` / sliding-window reductions** use `numpy.lib.stride_tricks`, which has no Array API (or `jax.numpy`) equivalent, so they are unsupported on JAX-backed data generally — not specific to units.
|
|
40
|
+
- **`interp`** delegates to `scipy`/`numpy` interpolation internally and returns a plain array (the same behavior as `pint-xarray`).
|
|
41
|
+
|
|
42
|
+
For these, `dequantify`, operate, then re-`quantify`, or work on `.data` with `unxt`/`quaxed` directly.
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
# Turn unit labels into real units
|
|
2
|
+
|
|
3
|
+
An `xarray` object can carry a `units` string in its attributes, but that string is only a label — nothing checks it, and `xarray` will happily add kilometres to hours. In this tutorial we will watch exactly that happen, then turn those labels into real `unxt` quantities so the same mistake becomes an error, compute with them, and put the labels back.
|
|
4
|
+
|
|
5
|
+
You need `unxt`, `unxts.interop.xarray` and `xarray` installed, and nothing else.
|
|
6
|
+
|
|
7
|
+
## Set up
|
|
8
|
+
|
|
9
|
+
```{code-block} python
|
|
10
|
+
>>> import numpy as np
|
|
11
|
+
>>> import xarray as xr
|
|
12
|
+
>>> import unxt as u
|
|
13
|
+
>>> import unxts.interop.xarray # registers the .unxt accessor
|
|
14
|
+
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
That import is the setup. It attaches a `.unxt` accessor to `DataArray` and `Dataset`.
|
|
18
|
+
|
|
19
|
+
## Build some labelled data
|
|
20
|
+
|
|
21
|
+
Three legs of a journey — distances in kilometres, times in hours — with the units recorded the way `xarray` users normally record them, as an attribute:
|
|
22
|
+
|
|
23
|
+
```{code-block} python
|
|
24
|
+
>>> dist = xr.DataArray(np.array([90.0, 180.0, 270.0]),
|
|
25
|
+
... dims="leg", attrs={"units": "km"})
|
|
26
|
+
>>> time = xr.DataArray(np.array([1.0, 2.0, 3.0]),
|
|
27
|
+
... dims="leg", attrs={"units": "h"})
|
|
28
|
+
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
## Watch the labels fail to protect you
|
|
32
|
+
|
|
33
|
+
Add a distance to a time. This is meaningless, so let's see what `xarray` does about it:
|
|
34
|
+
|
|
35
|
+
```{code-block} python
|
|
36
|
+
>>> (dist + time).values
|
|
37
|
+
array([ 91., 182., 273.])
|
|
38
|
+
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
It did the addition. 90 km plus 1 hour is 91 of something, and we now have an array of nonsense that looks exactly like data.
|
|
42
|
+
|
|
43
|
+
Worse, look at what happened to the units:
|
|
44
|
+
|
|
45
|
+
```{code-block} python
|
|
46
|
+
>>> (dist + time).attrs
|
|
47
|
+
{}
|
|
48
|
+
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
Gone. The attribute could not survive an operation it had no part in, so the result is not even mislabelled — it is unlabelled. Nothing raised, nothing warned.
|
|
52
|
+
|
|
53
|
+
## Make the units real
|
|
54
|
+
|
|
55
|
+
Now `quantify()`. It reads the `units` attribute and replaces the plain array with an `unxt.Quantity`:
|
|
56
|
+
|
|
57
|
+
```{code-block} python
|
|
58
|
+
>>> qd = dist.unxt.quantify()
|
|
59
|
+
>>> qt = time.unxt.quantify()
|
|
60
|
+
|
|
61
|
+
>>> qd.data
|
|
62
|
+
Quantity(Array([ 90., 180., 270.], dtype=float32), unit='km')
|
|
63
|
+
|
|
64
|
+
```
|
|
65
|
+
|
|
66
|
+
The unit is no longer a string beside the numbers — it is part of them. You can ask an object what units it found, before or after:
|
|
67
|
+
|
|
68
|
+
```{code-block} python
|
|
69
|
+
>>> dist.unxt.units
|
|
70
|
+
{None: Unit("km")}
|
|
71
|
+
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
(The data itself lives under the `None` key; named coordinates appear under their own names.)
|
|
75
|
+
|
|
76
|
+
## Try the mistake again
|
|
77
|
+
|
|
78
|
+
Same addition, now on quantified data:
|
|
79
|
+
|
|
80
|
+
```{code-block} python
|
|
81
|
+
>>> try:
|
|
82
|
+
... qd + qt
|
|
83
|
+
... except Exception as e:
|
|
84
|
+
... print(type(e).__name__)
|
|
85
|
+
UnitConversionError
|
|
86
|
+
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
There it is. The operation that quietly produced nonsense a moment ago now refuses to run at all.
|
|
90
|
+
|
|
91
|
+
## Compute something that does make sense
|
|
92
|
+
|
|
93
|
+
Distance divided by time is a speed, and the unit follows from the arithmetic:
|
|
94
|
+
|
|
95
|
+
```{code-block} python
|
|
96
|
+
>>> speed = qd / qt
|
|
97
|
+
>>> speed.data
|
|
98
|
+
Quantity(Array([90., 90., 90.], dtype=float32), unit='km / h')
|
|
99
|
+
|
|
100
|
+
```
|
|
101
|
+
|
|
102
|
+
Notice `km / h` — we never wrote it down. Ninety kilometres per hour on every leg, which is what the numbers say.
|
|
103
|
+
|
|
104
|
+
## Put the labels back
|
|
105
|
+
|
|
106
|
+
When you are done computing — writing to NetCDF, handing off to a library that does not know about quantities — `dequantify()` reverses the first step, moving the unit back into the attributes:
|
|
107
|
+
|
|
108
|
+
```{code-block} python
|
|
109
|
+
>>> speed.unxt.dequantify().attrs
|
|
110
|
+
{'units': 'km / h'}
|
|
111
|
+
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
The derived unit was written out as a label, ready to be stored.
|
|
115
|
+
|
|
116
|
+
## Do it to a whole dataset
|
|
117
|
+
|
|
118
|
+
Both methods work on a `Dataset`, converting every variable that has a `units` attribute:
|
|
119
|
+
|
|
120
|
+
```{code-block} python
|
|
121
|
+
>>> ds = xr.Dataset({"d": dist, "t": time})
|
|
122
|
+
>>> qds = ds.unxt.quantify()
|
|
123
|
+
|
|
124
|
+
>>> qds["d"].data
|
|
125
|
+
Quantity(Array([ 90., 180., 270.], dtype=float32), unit='km')
|
|
126
|
+
|
|
127
|
+
>>> qds["t"].data
|
|
128
|
+
Quantity(Array([1., 2., 3.], dtype=float32), unit='h')
|
|
129
|
+
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
And the round trip returns the labels exactly as they started:
|
|
133
|
+
|
|
134
|
+
```{code-block} python
|
|
135
|
+
>>> qds.unxt.dequantify()["d"].attrs
|
|
136
|
+
{'units': 'km'}
|
|
137
|
+
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
## Convert while you are in there
|
|
141
|
+
|
|
142
|
+
One thing worth knowing before you go: once quantified, the data converts like any other quantity.
|
|
143
|
+
|
|
144
|
+
```{code-block} python
|
|
145
|
+
>>> qd.data.uconvert("m")
|
|
146
|
+
Quantity(Array([ 90000., 180000., 270000.], dtype=float32), unit='m')
|
|
147
|
+
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
## What we built
|
|
151
|
+
|
|
152
|
+
You took a dataset whose units were decorative, made them real, watched a bug that had been silent become an exception, computed a derived quantity whose unit came out of the arithmetic, and wrote the labels back for storage. That round trip — `quantify`, compute, `dequantify` — is the shape of nearly every workflow with this package.
|
|
153
|
+
|
|
154
|
+
## Where to go next
|
|
155
|
+
|
|
156
|
+
- [How to use unxt with xarray](xarray-guide) — coordinates, per-variable units, JAX transforms, and NetCDF round trips.
|
|
157
|
+
- [The xarray sharp bits](sharp-bits) — why dimension coordinates cannot hold quantities.
|
|
158
|
+
- [API](api) — the accessor's parameters and the lower-level functions.
|