unxts.interop.xarray 2.0.0__tar.gz → 2.0.1__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.1/LICENSE +29 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/PKG-INFO +7 -7
- unxts_interop_xarray-2.0.1/docs/_data/README.md +20 -0
- unxts_interop_xarray-2.0.1/docs/_data/generate_sample_data.py +50 -0
- unxts_interop_xarray-2.0.1/docs/_data/sample_data.nc +0 -0
- unxts_interop_xarray-2.0.1/docs/index.md +224 -0
- unxts_interop_xarray-2.0.1/docs/xarray-guide.md +644 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/pyproject.toml +6 -5
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/_src/accessors.py +10 -9
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/_src/conversion.py +140 -18
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/_version.py +2 -2
- unxts_interop_xarray-2.0.1/tests/test_conversion_edges.py +100 -0
- unxts_interop_xarray-2.0.1/tests/test_stale_units_attrs.py +227 -0
- unxts_interop_xarray-2.0.1/tests/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.0.1}/.gitignore +0 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/README.md +0 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/__init__.py +0 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/_src/__init__.py +0 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/py.typed +0 -0
- {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/tests/test_public_api.py +0 -0
|
@@ -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.0.
|
|
3
|
+
Version: 2.0.1
|
|
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,224 @@
|
|
|
1
|
+
# unxts.interop.xarray
|
|
2
|
+
|
|
3
|
+
```{toctree}
|
|
4
|
+
:maxdepth: 1
|
|
5
|
+
:hidden:
|
|
6
|
+
|
|
7
|
+
xarray-guide
|
|
8
|
+
```
|
|
9
|
+
|
|
10
|
+
`xarray` integration for unxt - JAX-based physical quantities with `xarray`'s labeled arrays.
|
|
11
|
+
|
|
12
|
+
:::{note}
|
|
13
|
+
|
|
14
|
+
`unxts.interop.xarray` is the canonical package, superseding the deprecated `unxt-xarray` distribution. Once installed, it registers the `.unxt` xarray accessor on import.
|
|
15
|
+
|
|
16
|
+
:::
|
|
17
|
+
|
|
18
|
+
## Installation
|
|
19
|
+
|
|
20
|
+
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:
|
|
21
|
+
|
|
22
|
+
::::{tab-set}
|
|
23
|
+
|
|
24
|
+
:::{tab-item} uv
|
|
25
|
+
|
|
26
|
+
```bash
|
|
27
|
+
uv add "unxt[interop-xarray]"
|
|
28
|
+
```
|
|
29
|
+
|
|
30
|
+
:::
|
|
31
|
+
|
|
32
|
+
:::{tab-item} pip
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
pip install "unxt[interop-xarray]"
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
:::
|
|
39
|
+
|
|
40
|
+
::::
|
|
41
|
+
|
|
42
|
+
Or install the package directly:
|
|
43
|
+
|
|
44
|
+
::::{tab-set}
|
|
45
|
+
|
|
46
|
+
:::{tab-item} uv
|
|
47
|
+
|
|
48
|
+
```bash
|
|
49
|
+
uv add unxts.interop.xarray
|
|
50
|
+
```
|
|
51
|
+
|
|
52
|
+
:::
|
|
53
|
+
|
|
54
|
+
:::{tab-item} pip
|
|
55
|
+
|
|
56
|
+
```bash
|
|
57
|
+
pip install unxts.interop.xarray
|
|
58
|
+
```
|
|
59
|
+
|
|
60
|
+
:::
|
|
61
|
+
|
|
62
|
+
::::
|
|
63
|
+
|
|
64
|
+
## Quick Start
|
|
65
|
+
|
|
66
|
+
```python
|
|
67
|
+
import xarray as xr
|
|
68
|
+
import unxt as u
|
|
69
|
+
import unxts.interop.xarray # This registers the .unxt accessor
|
|
70
|
+
|
|
71
|
+
# Create DataArray with unit attributes
|
|
72
|
+
da = xr.DataArray(
|
|
73
|
+
[1.0, 2.0, 3.0],
|
|
74
|
+
dims=["x"],
|
|
75
|
+
attrs={"units": "m"},
|
|
76
|
+
)
|
|
77
|
+
|
|
78
|
+
# Convert to unxt Quantities
|
|
79
|
+
quantified = da.unxt.quantify()
|
|
80
|
+
print(quantified.data)
|
|
81
|
+
# Quantity(Array([1., 2., 3.], dtype=float32), unit='m')
|
|
82
|
+
|
|
83
|
+
# Convert back to plain arrays with unit attributes
|
|
84
|
+
dequantified = quantified.unxt.dequantify()
|
|
85
|
+
print(dequantified.attrs["units"])
|
|
86
|
+
# 'm'
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Usage
|
|
90
|
+
|
|
91
|
+
### DataArray Operations
|
|
92
|
+
|
|
93
|
+
The `.unxt` accessor provides two main methods for `DataArray`:
|
|
94
|
+
|
|
95
|
+
#### `quantify()`
|
|
96
|
+
|
|
97
|
+
Convert a DataArray with unit attributes into one containing unxt Quantities:
|
|
98
|
+
|
|
99
|
+
```python
|
|
100
|
+
import xarray as xr
|
|
101
|
+
import unxts.interop.xarray
|
|
102
|
+
|
|
103
|
+
# From attributes
|
|
104
|
+
da = xr.DataArray([1.0, 2.0, 3.0], dims=["x"], attrs={"units": "m"})
|
|
105
|
+
q = da.unxt.quantify()
|
|
106
|
+
|
|
107
|
+
# With explicit units
|
|
108
|
+
da = xr.DataArray([1.0, 2.0, 3.0], dims=["x"])
|
|
109
|
+
q = da.unxt.quantify("km")
|
|
110
|
+
|
|
111
|
+
# With coordinate units. Use a *non-dimension* coordinate ("time" on dim "i"):
|
|
112
|
+
# a dimension coordinate is coerced to a plain array by xarray, dropping its unit.
|
|
113
|
+
da = xr.DataArray(
|
|
114
|
+
[1.0, 2.0],
|
|
115
|
+
dims=["i"],
|
|
116
|
+
coords={"time": ("i", [0.0, 1.0])},
|
|
117
|
+
attrs={"units": "m"},
|
|
118
|
+
)
|
|
119
|
+
q = da.unxt.quantify(time="s") # Specify units for the "time" coord
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
#### `dequantify()`
|
|
123
|
+
|
|
124
|
+
Convert Quantities back to plain arrays with unit attributes:
|
|
125
|
+
|
|
126
|
+
```python
|
|
127
|
+
import unxt as u
|
|
128
|
+
|
|
129
|
+
q = u.Quantity([1.0, 2.0, 3.0], "m")
|
|
130
|
+
da = xr.DataArray(q, dims=["x"])
|
|
131
|
+
|
|
132
|
+
plain = da.unxt.dequantify()
|
|
133
|
+
print(plain.attrs["units"]) # 'm'
|
|
134
|
+
print(type(plain.data)) # Array (not Quantity)
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
### Dataset Operations
|
|
138
|
+
|
|
139
|
+
The accessor works similarly for `Dataset` objects:
|
|
140
|
+
|
|
141
|
+
```python
|
|
142
|
+
import xarray as xr
|
|
143
|
+
import unxts.interop.xarray
|
|
144
|
+
|
|
145
|
+
# Create Dataset with unit attributes
|
|
146
|
+
ds = xr.Dataset(
|
|
147
|
+
{
|
|
148
|
+
"temperature": ("time", [20.0, 25.0, 30.0], {"units": "deg_C"}),
|
|
149
|
+
"pressure": ("time", [1.0, 1.1, 1.2], {"units": "bar"}),
|
|
150
|
+
}
|
|
151
|
+
)
|
|
152
|
+
|
|
153
|
+
# Quantify all variables
|
|
154
|
+
q_ds = ds.unxt.quantify()
|
|
155
|
+
print(q_ds["temperature"].data)
|
|
156
|
+
# Quantity(Array([20., 25., 30.], dtype=float32), unit='deg_C')
|
|
157
|
+
|
|
158
|
+
# Dequantify back
|
|
159
|
+
plain_ds = q_ds.unxt.dequantify()
|
|
160
|
+
print(plain_ds["temperature"].attrs["units"]) # 'deg_C'
|
|
161
|
+
```
|
|
162
|
+
|
|
163
|
+
## Advanced Usage
|
|
164
|
+
|
|
165
|
+
### Custom Unit Attributes
|
|
166
|
+
|
|
167
|
+
By default, units are stored in the `"units"` attribute. You can customize this:
|
|
168
|
+
|
|
169
|
+
```python
|
|
170
|
+
da = xr.DataArray([1.0, 2.0], dims=["x"])
|
|
171
|
+
q_da = xr.DataArray(u.Quantity([1.0, 2.0], "m"), dims=["x"])
|
|
172
|
+
|
|
173
|
+
# Use custom attribute name
|
|
174
|
+
plain = q_da.unxt.dequantify(unit_attribute="unit_str")
|
|
175
|
+
print(plain.attrs["unit_str"]) # 'm'
|
|
176
|
+
```
|
|
177
|
+
|
|
178
|
+
### Format Strings
|
|
179
|
+
|
|
180
|
+
Control how units are formatted when dequantifying:
|
|
181
|
+
|
|
182
|
+
```python
|
|
183
|
+
import unxt as u
|
|
184
|
+
|
|
185
|
+
q = u.Quantity([1.0, 2.0], "m/s")
|
|
186
|
+
da = xr.DataArray(q, dims=["x"])
|
|
187
|
+
|
|
188
|
+
# Default format
|
|
189
|
+
plain = da.unxt.dequantify()
|
|
190
|
+
print(plain.attrs["units"]) # 'm / s'
|
|
191
|
+
|
|
192
|
+
# Custom format (if supported by unit system)
|
|
193
|
+
# plain = da.unxt.dequantify(format="{:~}") # Compact format
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
### Partial Quantification
|
|
197
|
+
|
|
198
|
+
You can quantify only specific variables in a Dataset:
|
|
199
|
+
|
|
200
|
+
```python
|
|
201
|
+
ds = xr.Dataset(
|
|
202
|
+
{
|
|
203
|
+
"with_units": ("x", [1.0, 2.0], {"units": "m"}),
|
|
204
|
+
"without_units": ("y", [3.0, 4.0]),
|
|
205
|
+
}
|
|
206
|
+
)
|
|
207
|
+
|
|
208
|
+
q_ds = ds.unxt.quantify()
|
|
209
|
+
# Only "with_units" is quantified
|
|
210
|
+
```
|
|
211
|
+
|
|
212
|
+
## Best Practices
|
|
213
|
+
|
|
214
|
+
1. **Consistent Units**: Ensure unit attributes are consistent across your workflow
|
|
215
|
+
2. **Explicit is Better**: Use explicit units in `quantify()` when possible for clarity
|
|
216
|
+
3. **Preserve Attributes**: Other attributes (like `long_name`, `description`) are preserved
|
|
217
|
+
4. **JAX Compatibility**: Remember that quantified data is JAX arrays - use `jax.numpy` operations
|
|
218
|
+
|
|
219
|
+
## See Also
|
|
220
|
+
|
|
221
|
+
- [unxt documentation](https://unxt.readthedocs.io/)
|
|
222
|
+
- [xarray documentation](https://docs.xarray.dev/)
|
|
223
|
+
- [pint-xarray](https://pint-xarray.readthedocs.io/) - The original inspiration
|
|
224
|
+
- [JAX documentation](https://jax.readthedocs.io/)
|