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.
Files changed (21) hide show
  1. unxts_interop_xarray-2.0.1/LICENSE +29 -0
  2. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/PKG-INFO +7 -7
  3. unxts_interop_xarray-2.0.1/docs/_data/README.md +20 -0
  4. unxts_interop_xarray-2.0.1/docs/_data/generate_sample_data.py +50 -0
  5. unxts_interop_xarray-2.0.1/docs/_data/sample_data.nc +0 -0
  6. unxts_interop_xarray-2.0.1/docs/index.md +224 -0
  7. unxts_interop_xarray-2.0.1/docs/xarray-guide.md +644 -0
  8. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/pyproject.toml +6 -5
  9. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/_src/accessors.py +10 -9
  10. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/_src/conversion.py +140 -18
  11. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/_version.py +2 -2
  12. unxts_interop_xarray-2.0.1/tests/test_conversion_edges.py +100 -0
  13. unxts_interop_xarray-2.0.1/tests/test_stale_units_attrs.py +227 -0
  14. unxts_interop_xarray-2.0.1/tests/test_unknown_unit_keys.py +34 -0
  15. unxts_interop_xarray-2.0.0/docs/index.md +0 -12
  16. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/.gitignore +0 -0
  17. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/README.md +0 -0
  18. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/__init__.py +0 -0
  19. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/_src/__init__.py +0 -0
  20. {unxts_interop_xarray-2.0.0 → unxts_interop_xarray-2.0.1}/src/unxts/interop/xarray/py.typed +0 -0
  21. {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.4
1
+ Metadata-Version: 2.5
2
2
  Name: unxts.interop.xarray
3
- Version: 2.0.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.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,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/)