#16 Merge pull request from astropenguin/astropenguin/issue15

Add option for method chain

.devcontainer/devcontainer.json

@@ -1,11 +1,14 @@
 {
     "name": "xarray-units",
-    "image":"python:3.12",
-    "onCreateCommand": "pip install poetry==1.7.1",
-    "postCreateCommand": "poetry install",
+    "image": "python:3.12",
+    "runArgs": [
+        "--name=xarray-units"
+    ],
     "containerEnv": {
         "POETRY_VIRTUALENVS_CREATE": "false"
     },
+    "onCreateCommand": "pip install poetry==1.7.1",
+    "postCreateCommand": "poetry install",
     "customizations": {
         "vscode": {
             "extensions": [

.github/workflows/tests.yaml

@@ -24,6 +24,6 @@ jobs:
         with:
           python-version: ${{ matrix.python }}
       - run: pip install poetry==1.7.1 && poetry install
-      - run: black --check xarray_units
-      - run: pyright xarray_units
+      - run: black --check docs tests xarray_units
+      - run: pyright docs tests xarray_units
       - run: pytest -v tests

CITATION.cff

@@ -3,8 +3,8 @@ message: "If you use this software, please cite it as below."
 
 title: "xarray-units"
 abstract: "xarray extension for handling units"
-version: 0.3.0
-date-released: 2023-12-27
+version: 0.4.0
+date-released: 2024-02-03
 license: "MIT"
 doi: "10.5281/zenodo.10354517"
 url: "https://github.com/astropenguin/xarray-units/"

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2023 Akio Taniguchi
+Copyright (c) 2023-2024 Akio Taniguchi
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -10,12 +10,15 @@ xarray extension for handling units
 
 ## Overview
 
-xarray-units is an import-only package that provides a DataArray accessor `.units` for handling units such as converting units and numeric operations considering units. [Astropy](https://www.astropy.org) is used as a backend. Unlike similar implementations, xarray-units does not use a special data type to handle units, but uses the original data type in a DataArray. This allows to continue to use powerful features such as parallel and lazy processing with [Dask](https://www.dask.org) and/or user-defined DataArray subclasses.
+xarray-units is an import-only package that provides a DataArray accessor `.units` for handling units such as converting units and numeric operations considering units.
+[Astropy](https://www.astropy.org) is used as a backend.
+Unlike similar implementations, xarray-units does not use a special data type to handle units, but uses the original data type in a DataArray.
+This allows to continue to use powerful features such as parallel and lazy processing with [Dask](https://www.dask.org) and/or user-defined DataArray subclasses.
 
 ## Installation
 
 ```shell
-pip install xarray-units==0.3.0
+pip install xarray-units==0.4.0
 ```
 
 ## Basic usages
@@ -57,7 +60,7 @@ array([1, 2, 3])
 Dimensions without coordinates: dim_0
 ```
 
-These are equivalent to manually un/setting the units in the DataArray attributes, but the accessor also check that the units are valid when setting.
+These are equivalent to manually un/setting the units in the DataArray attributes, but the `units ` accessor also check that the units are valid when setting.
 
 ### Converting units to others
 
@@ -97,7 +100,7 @@ Attributes:
 
 ### Numeric operations considering units
 
-xarray-units performs numerical operations considering units when the accessor is attached to the DataArray on the left side of the operator:
+xarray-units performs numerical operations considering units when the `units` accessor is attached to the DataArray on the left side of the operator:
 
 ```python
 da_m = xr.DataArray([1000, 2000, 3000]).units.set("m")
@@ -124,10 +127,12 @@ Attributes:
     units:    km
 ```
 
-The units of the DataArray after the operation follows those of the DataArray with the accessor. Therefore, the resulting data values will be different depending on the order of the operation. They are, of course, identical when considering units:
+The units of the DataArray after the operation follows those of the DataArray with the `units` accessor.
+The resulting data values will be therefore different depending on the order of the operation.
+They are, of course, equal when considering units:
 
 ```python
-da_eq = da_sum_m.units == da_sum_km
+da_eq = (da_sum_m.units == da_sum_km)
 print(da_eq)
 ```
 
@@ -137,6 +142,10 @@ array([ True,  True,  True])
 Dimensions without coordinates: dim_0
 ```
 
+> [!IMPORTANT]
+> Because this feature is accessor-based, units are only considered for the operation right after the `units` accessor.
+> See [method and operation chains](#method-and-operation-chains) for performing multiple operations at once.
+
 ### Formatting units
 
 xarray-units converts units to [various string formats](https://docs.astropy.org/en/stable/units/format.html):
@@ -173,27 +182,56 @@ da.units.format("latex").plot()
 
 ## Advanced usages
 
+### Method and operation chains
+
+The `units` accessor has an option for chaining methods or operations while considering units:
+
+```python
+da_m = xr.DataArray([1, 2, 3]).units.set("m")
+da_s = xr.DataArray([1, 2, 3]).units.set("s")
+da_a = da_m.units(chain=2) / da_s / da_s
+print(da_a)
+```
+
+```
+<xarray.DataArray (dim_0: 3)>
+array([1.        , 0.5       , 0.33333333])
+Dimensions without coordinates: dim_0
+Attributes:
+    units:    m / s2
+```
+
+where `chain` is the number of chained methods or operations.
+This is equivalent to nesting the `units` accessors:
+
+```python
+(da_m.units / da_s).units / da_s
+```
+
 ### Use with static type checking
 
-xarray-units provides a special type hint `xarray_units.DataArray` that has the `units` accessor. By replacing `xarray.DataArray` with it at the beginning of the code, type checkers can statically handle the accessor and its methods:
+xarray-units provides a special type hint `xarray_units.DataArray` with which type checkers can statically handle the `units ` accessor and its methods:
 
 ```python
-import xarray as xr
 from xarray_units import DataArray
 
-xr.DataArray = DataArray
+da: DataArray = xr.DataArray([1, 2, 3]).units.set("km")
 ```
 
-Note that it will become exactly identical to `xarray.DataArray` at runtime, so the replacement is not a problem at all.
+> [!TIP]
+> `xarray_units.DataArray` will be replaced by `xarray.DataArray` at runtime, so it can also be used for creating and subclassing `DataArray`.
 
 ### Use without the units accessor
 
-xarray-units provides a function `xarray_units.units` that returns the `units` accessor of a DataArray. The following two lines are therefore identical:
+xarray-units provides a function `xarray_units.units` that returns the `units` accessor of a DataArray.
+The following two codes are therefore equivalent:
+
+```python
+xr.DataArray([1, 2, 3]).units.set("km")
+```
 
 ```python
-import xarray as xr
 from xarray_units import units
 
-xr.DataArray([1, 2, 3]).units.set("km")
 units(xr.DataArray([1, 2, 3])).set("km")
 ```

docs/conf.py

@@ -1,6 +1,6 @@
 # project information
 author = "Akio Taniguchi"
-copyright = "2023 Akio Taniguchi"
+copyright = "2023-2024 Akio Taniguchi"
 
 
 # general configuration