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.
Files changed (24) hide show
  1. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/.gitignore +4 -1
  2. unxts_interop_xarray-2.1.0/LICENSE +29 -0
  3. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/PKG-INFO +7 -7
  4. unxts_interop_xarray-2.1.0/docs/_data/README.md +20 -0
  5. unxts_interop_xarray-2.1.0/docs/_data/generate_sample_data.py +50 -0
  6. unxts_interop_xarray-2.1.0/docs/_data/sample_data.nc +0 -0
  7. unxts_interop_xarray-2.1.0/docs/api.md +99 -0
  8. unxts_interop_xarray-2.1.0/docs/index.md +105 -0
  9. unxts_interop_xarray-2.1.0/docs/sharp-bits.md +42 -0
  10. unxts_interop_xarray-2.1.0/docs/tutorial-first-dataset.md +158 -0
  11. unxts_interop_xarray-2.1.0/docs/xarray-guide.md +508 -0
  12. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/pyproject.toml +6 -5
  13. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/_src/accessors.py +10 -9
  14. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/_src/conversion.py +163 -24
  15. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/_version.py +2 -2
  16. unxts_interop_xarray-2.1.0/tests/unit/test_conversion_edges.py +100 -0
  17. unxts_interop_xarray-2.1.0/tests/unit/test_stale_units_attrs.py +227 -0
  18. unxts_interop_xarray-2.1.0/tests/unit/test_unknown_unit_keys.py +34 -0
  19. unxts_interop_xarray-2.0.0/docs/index.md +0 -12
  20. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/README.md +0 -0
  21. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/__init__.py +0 -0
  22. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/_src/__init__.py +0 -0
  23. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.1.0}/src/unxts/interop/xarray/py.typed +0 -0
  24. {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/guides/perf.ipynb
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.4
1
+ Metadata-Version: 2.5
2
2
  Name: unxts.interop.xarray
3
- Version: 2.0.0
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.11
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)
@@ -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.