From dfa508bd6a6ad9441fd247ef7d13b3284be9be57 Mon Sep 17 00:00:00 2001 From: Callan Gray Date: Wed, 1 Apr 2026 20:34:28 +0800 Subject: [PATCH 1/6] astropy 7.2.0 support Signed-off-by: Callan Gray --- astropy_xarray/coordinates/frame.py | 13 +++++++++++-- docs/requirements.txt | 2 +- pyproject.toml | 8 +++++--- 3 files changed, 17 insertions(+), 6 deletions(-) diff --git a/astropy_xarray/coordinates/frame.py b/astropy_xarray/coordinates/frame.py index 210d6735..94ba4c63 100644 --- a/astropy_xarray/coordinates/frame.py +++ b/astropy_xarray/coordinates/frame.py @@ -296,11 +296,20 @@ def load_representation( else: # using frame component names frame_type: BaseCoordinateFrame = frame_transform_graph.lookup_name(frame_name) + + if False: # astropy 7.1+ + representation_info = frame_type._frame_class_cache["representation_info"] + elif False: # astropy 6.0-7.0 + representation_info = frame_type._get_representation_info() + else: + # unknown instantiation avoidance (this should really be a class method) + representation_info = frame_type().representation_info + diff_to_data = ( dict( zip( tuple(DifferentialClass.attr_classes), - frame_type._get_representation_info()[DifferentialClass]["names"], + representation_info[DifferentialClass]["names"], ) ) if DifferentialClass is not None @@ -310,7 +319,7 @@ def load_representation( dict( zip( tuple(RepresentationClass.attr_classes), - frame_type._get_representation_info()[RepresentationClass]["names"], + representation_info[RepresentationClass]["names"], ) ) if RepresentationClass is not None diff --git a/docs/requirements.txt b/docs/requirements.txt index 2d6e110d..602f7256 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,4 +1,4 @@ -astropy==7.1.0 +astropy==7.2.0 xarray>=2022.06.0 pooch netCDF4 diff --git a/pyproject.toml b/pyproject.toml index 281dc117..57e0708f 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -27,14 +27,16 @@ requires-python = ">=3.10" dependencies = [ "numpy>=1.23,<2.3.0", "xarray>=2022.06.0,<=2025.4.0", - "astropy>=6.1.0,<7.2.0", + "astropy>=6.1.0", "pandas>=2.3.0,<3.0.0", ] dynamic = ["version"] [project.urls] -Home = "https://github.com/calgray/astropy-xarray" -Documentation = "https://astropy-xarray.readthedocs.io/en/stable" +homepage = "https://github.com/calgray/astropy-xarray" +documentation = "https://astropy-xarray.readthedocs.io/en/stable" +repository = "https://github.com/calgray/astropy-xarray" +issues = "https://github.com/calgray/astropy-xarray/issues" [project.optional-dependencies] test = [ From 7a83a083a2ce6f7a920cce978d4b99d1a239e1b2 Mon Sep 17 00:00:00 2001 From: Callan Gray Date: Thu, 2 Apr 2026 09:08:19 +0800 Subject: [PATCH 2/6] use safe representation_info Signed-off-by: Callan Gray --- astropy_xarray/coordinates/frame.py | 9 +-------- 1 file changed, 1 insertion(+), 8 deletions(-) diff --git a/astropy_xarray/coordinates/frame.py b/astropy_xarray/coordinates/frame.py index 94ba4c63..b1e438f2 100644 --- a/astropy_xarray/coordinates/frame.py +++ b/astropy_xarray/coordinates/frame.py @@ -296,14 +296,7 @@ def load_representation( else: # using frame component names frame_type: BaseCoordinateFrame = frame_transform_graph.lookup_name(frame_name) - - if False: # astropy 7.1+ - representation_info = frame_type._frame_class_cache["representation_info"] - elif False: # astropy 6.0-7.0 - representation_info = frame_type._get_representation_info() - else: - # unknown instantiation avoidance (this should really be a class method) - representation_info = frame_type().representation_info + representation_info = frame_type().representation_info diff_to_data = ( dict( From 3d6ef0a223b1367fd3dbe83610ce5b5bb15e1853 Mon Sep 17 00:00:00 2001 From: Callan Gray Date: Thu, 2 Apr 2026 23:14:58 +0800 Subject: [PATCH 3/6] convert docs to myst Signed-off-by: Callan Gray --- docs/{api.rst => api.md} | 29 +++-- docs/conf.py | 7 +- docs/contributing.md | 18 +++ docs/contributing.rst | 18 --- docs/{conversion.rst => conversion.md} | 16 ++- docs/creation.md | 156 +++++++++++++++++++++++++ docs/creation.rst | 134 --------------------- docs/examples.md | 10 ++ docs/examples.rst | 9 -- docs/index.md | 66 +++++++++++ docs/index.rst | 63 ---------- docs/installation.md | 26 +++++ docs/installation.rst | 26 ----- docs/terminology.md | 8 ++ docs/terminology.rst | 10 -- docs/whats-new.md | 39 +++++++ docs/whats-new.rst | 39 ------- pyproject.toml | 2 +- 18 files changed, 362 insertions(+), 314 deletions(-) rename docs/{api.rst => api.md} (88%) create mode 100644 docs/contributing.md delete mode 100644 docs/contributing.rst rename docs/{conversion.rst => conversion.md} (72%) create mode 100644 docs/creation.md delete mode 100644 docs/creation.rst create mode 100644 docs/examples.md delete mode 100644 docs/examples.rst create mode 100644 docs/index.md delete mode 100644 docs/index.rst create mode 100644 docs/installation.md delete mode 100644 docs/installation.rst create mode 100644 docs/terminology.md delete mode 100644 docs/terminology.rst create mode 100644 docs/whats-new.md delete mode 100644 docs/whats-new.rst diff --git a/docs/api.rst b/docs/api.md similarity index 88% rename from docs/api.rst rename to docs/api.md index 00206146..eac4e2bd 100644 --- a/docs/api.rst +++ b/docs/api.md @@ -1,7 +1,8 @@ -API reference -============= -This page contains a auto-generated summary of ``astropy-xarray``'s API. +# API reference +This page contains a auto-generated summary of `astropy-xarray`'s API. + +```{eval-rst} .. autosummary:: :toctree: generated/ @@ -9,15 +10,19 @@ This page contains a auto-generated summary of ``astropy-xarray``'s API. astropy_xarray.coordinates.skycoord_to_dataset astropy_xarray.coordinates.load_frame astropy_xarray.coordinates.load_representation +``` + +## Dataset -Dataset -------- +```{eval-rst} .. autosummary:: :toctree: generated/ :template: autosummary/accessor_attribute.rst xarray.Dataset.astropy.loc +``` +```{eval-rst} .. autosummary:: :toctree: generated/ :template: autosummary/accessor_method.rst @@ -36,9 +41,11 @@ Dataset xarray.Dataset.astropy.bfill xarray.Dataset.astropy.interpolate_na xarray.Dataset.astropy.to_skycoord +``` + +## DataArray -DataArray ---------- +```{eval-rst} .. autosummary:: :toctree: generated/ :template: autosummary/accessor_attribute.rst @@ -49,7 +56,9 @@ DataArray .. xarray.DataArray.astropy.units .. xarray.DataArray.astropy.dimensionality .. xarray.DataArray.astropy.registry +``` +```{eval-rst} .. autosummary:: :toctree: generated/ :template: autosummary/accessor_method.rst @@ -67,11 +76,13 @@ DataArray xarray.DataArray.astropy.ffill xarray.DataArray.astropy.bfill xarray.DataArray.astropy.interpolate_na +``` -Testing -------- +## Testing +```{eval-rst} .. autosummary:: :toctree: generated/ astropy_xarray.testing.assert_units_equal +``` diff --git a/docs/conf.py b/docs/conf.py index 6920d052..1fbc90a3 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -46,7 +46,12 @@ "sphinx_autosummary_accessors", "IPython.sphinxext.ipython_directive", "IPython.sphinxext.ipython_console_highlighting", - "nbsphinx", + "myst_nb", +] + +myst_enable_extensions = [ + "dollarmath", + "colon_fence", ] # Add any paths that contain templates here, relative to this directory. diff --git a/docs/contributing.md b/docs/contributing.md new file mode 100644 index 00000000..3305ef5b --- /dev/null +++ b/docs/contributing.md @@ -0,0 +1,18 @@ +# Contributing + +`astropy-xarray` is developed on [github](https://github.com/calgray/astropy-xarray). + +## Commit message tags + +By default, the upstream dev CI is disabled on pull request and push events. You can +override this behavior per commit by adding a \[test-upstream]\ tag to the first +line of the commit message. + +## Linters / Autoformatters + +In order to keep code consistent, we use + +- [Black](https://black.readthedocs.io/en/stable/) for standardized code formatting +- [blackdoc](https://blackdoc.readthedocs.io/en/stable/) for standardized code formatting in documentation +- [Flake8](https://flake8.pycqa.org/en/latest/) for general code quality +- [isort](https://github.com/PyCQA/isort) for standardized order in imports. See also [flake8-isort](https://github.com/gforcada/flake8-isort). diff --git a/docs/contributing.rst b/docs/contributing.rst deleted file mode 100644 index 4f82a67e..00000000 --- a/docs/contributing.rst +++ /dev/null @@ -1,18 +0,0 @@ -Contributing -============ -``astropy-xarray`` is developed on `github `_. - -Commit message tags -------------------- -By default, the upstream dev CI is disabled on pull request and push events. You can -override this behavior per commit by adding a [test-upstream] tag to the first -line of the commit message. - -Linters / Autoformatters ------------------------- -In order to keep code consistent, we use - -- `Black `_ for standardized code formatting -- `blackdoc `_ for standardized code formatting in documentation -- `Flake8 `_ for general code quality -- `isort `_ for standardized order in imports. See also `flake8-isort `_. diff --git a/docs/conversion.rst b/docs/conversion.md similarity index 72% rename from docs/conversion.rst rename to docs/conversion.md index e220b9b2..d0c947f4 100644 --- a/docs/conversion.rst +++ b/docs/conversion.md @@ -1,15 +1,20 @@ +```{eval-rst} .. currentmodule:: xarray +``` -Converting units -================ +# Converting units + +```{eval-rst} .. ipython:: python :suppress: import xarray as xr +``` -When working with :py:class:`Dataset` or :py:class:`DataArray` objects with +When working with {py:class}`Dataset` or {py:class}`DataArray` objects with units, we frequently might want to convert the units. Suppose we have: +```{eval-rst} .. ipython:: In [1]: ds = xr.Dataset( @@ -19,12 +24,15 @@ units, we frequently might want to convert the units. Suppose we have: In [2]: da = ds.a ...: da +``` To convert the data to different units, we can use the -:py:meth:`Dataset.astropy.to` and :py:meth:`DataArray.astropy.to` methods: +{py:meth}`Dataset.astropy.to` and {py:meth}`DataArray.astropy.to` methods: +```{eval-rst} .. ipython:: In [3]: ds.astropy.to(a="cm", u="ks") In [4]: da.astropy.to({da.name: "km", "u": "ms"}) +``` diff --git a/docs/creation.md b/docs/creation.md new file mode 100644 index 00000000..27ab6e1c --- /dev/null +++ b/docs/creation.md @@ -0,0 +1,156 @@ +```{eval-rst} +.. currentmodule:: xarray +``` + +# Creating and saving objects with units + +## Attaching units + +```{eval-rst} +.. ipython:: python + :suppress: + + import astropy + import astropy_xarray + import xarray as xr +``` + +Usually, when loading data from disk we get a {py:class}`Dataset` or +{py:class}`DataArray` with units in attributes: + +```{eval-rst} +.. ipython:: + + In [1]: ds = xr.Dataset( + ...: { + ...: "a": (("lon", "lat"), [[11.84, 3.12, 9.7], [7.8, 9.3, 14.72]]), + ...: "b": (("lon", "lat"), [[13, 2, 7], [5, 4, 9]], {"units": "m"}), + ...: }, + ...: coords={"lat": [10, 20, 30], "lon": [74, 76]}, + ...: ) + ...: ds + + In [2]: da = ds.b + ...: da +``` + +In order to get {py:class}`astropy.Quantity` instances, we can use the +{py:meth}`Dataset.astropy.quantify` or {py:meth}`DataArray.astropy.quantify` methods: + +```{eval-rst} +.. ipython:: + + In [3]: ds.astropy.quantify() +``` + +We can also override the units of a variable: + +```{eval-rst} +.. ipython:: + + In [4]: ds.astropy.quantify(b="km") + + In [5]: da.astropy.quantify("degree") +``` + +Overriding works even if there is no `units` attribute, so we could use this +to attach units to a normal {py:class}`Dataset`: + +```{eval-rst} +.. ipython:: + + In [6]: temporary_ds = xr.Dataset({"a": ("x", [0, 5, 10])}, coords={"x": [1, 2, 3]}) + ...: temporary_ds.astropy.quantify({"a": "m"}) +``` + +Of course, we could use {py:class}`astropy.Unit` instances instead of strings to +specify units, too. + +:::{note} +Unit objects tied to different registries cannot interact with each +other. In order to avoid this, {py:meth}`DataArray.astropy.quantify` and +{py:meth}`Dataset.astropy.quantify` will make sure only a single registry is +used per `xarray` object. +::: + +If we wanted to change the units of the data of a {py:class}`DataArray`, we +could do so using the {py:attr}`DataArray.name` attribute: + +```{eval-rst} +.. ipython:: + + In [7]: da.astropy.quantify({da.name: "J", "lat": "degree", "lon": "degree"}) +``` + +However, [xarray] currently doesn't support [units in indexes], so the new units were set +as attributes. To really observe the changes the `quantify` methods make, we +have to first swap the dimensions: + +```{eval-rst} +.. ipython:: + + In [8]: ds_with_units = ds.swap_dims({"lon": "x", "lat": "y"}).astropy.quantify( + ...: {"lat": "degree", "lon": "degree"} + ...: ) + ...: ds_with_units + + In [9]: da_with_units = da.swap_dims({"lon": "x", "lat": "y"}).astropy.quantify( + ...: {"lat": "degree", "lon": "degree"} + ...: ) + ...: da_with_units +``` + +By default, {py:meth}`Dataset.astropy.quantify` and +{py:meth}`DataArray.astropy.quantify` will use the unit registry at +{py:obj}`astropy_xarray.unit_registry` (the +{py:func}`application registry `). If we want a +different registry, we can either pass it as the `unit_registry` parameter: + +```{eval-rst} +.. ipython:: + + In [10]: import astropy.units as u + ...: + ...: # set up the registry + + In [11]: da.astropy.quantify("degree") +``` + +or overwrite the default registry: + +```{eval-rst} +.. ipython:: + + In [12]: da.astropy.quantify("degree") +``` + +:::{note} + +> To properly work with `xarray`, the `force_ndarray_like` or +> `force_ndarray` options have to be enabled on the custom registry. + +Without it, python scalars wrapped by {py:class}`astropy.Quantity` may raise errors or +have their units stripped. +::: + +## Saving with units + +In order to not lose the units when saving to disk, we first have to call the +{py:meth}`Dataset.astropy.dequantify` and {py:meth}`DataArray.astropy.dequantify` +methods: + +```{eval-rst} +.. ipython:: + + In [10]: ds_with_units.astropy.dequantify() + + In [11]: da_with_units.astropy.dequantify() +``` + +This will get the string representation of a {py:class}`astropy.Unit` instance and +attach it as a `units` attribute. The data of the variable will now be +whatever [astropy] wrapped. + +[astropy]: https://docs.astropy.org/en/latest/ +[units in indexes]: https://github.com/pydata/xarray/issues/1603 +[xarray]: https://docs.xarray.dev/en/stable/ diff --git a/docs/creation.rst b/docs/creation.rst deleted file mode 100644 index 193a9bad..00000000 --- a/docs/creation.rst +++ /dev/null @@ -1,134 +0,0 @@ -.. currentmodule:: xarray - -Creating and saving objects with units -====================================== - -Attaching units ---------------- -.. ipython:: python - :suppress: - - import astropy - import astropy_xarray - import xarray as xr - -Usually, when loading data from disk we get a :py:class:`Dataset` or -:py:class:`DataArray` with units in attributes: - -.. ipython:: - - In [1]: ds = xr.Dataset( - ...: { - ...: "a": (("lon", "lat"), [[11.84, 3.12, 9.7], [7.8, 9.3, 14.72]]), - ...: "b": (("lon", "lat"), [[13, 2, 7], [5, 4, 9]], {"units": "m"}), - ...: }, - ...: coords={"lat": [10, 20, 30], "lon": [74, 76]}, - ...: ) - ...: ds - - In [2]: da = ds.b - ...: da - -In order to get :py:class:`astropy.Quantity` instances, we can use the -:py:meth:`Dataset.astropy.quantify` or :py:meth:`DataArray.astropy.quantify` methods: - -.. ipython:: - - In [3]: ds.astropy.quantify() - -We can also override the units of a variable: - -.. ipython:: - - In [4]: ds.astropy.quantify(b="km") - - In [5]: da.astropy.quantify("degree") - -Overriding works even if there is no ``units`` attribute, so we could use this -to attach units to a normal :py:class:`Dataset`: - -.. ipython:: - - In [6]: temporary_ds = xr.Dataset({"a": ("x", [0, 5, 10])}, coords={"x": [1, 2, 3]}) - ...: temporary_ds.astropy.quantify({"a": "m"}) - -Of course, we could use :py:class:`astropy.Unit` instances instead of strings to -specify units, too. - -.. note:: - - Unit objects tied to different registries cannot interact with each - other. In order to avoid this, :py:meth:`DataArray.astropy.quantify` and - :py:meth:`Dataset.astropy.quantify` will make sure only a single registry is - used per ``xarray`` object. - -If we wanted to change the units of the data of a :py:class:`DataArray`, we -could do so using the :py:attr:`DataArray.name` attribute: - -.. ipython:: - - In [7]: da.astropy.quantify({da.name: "J", "lat": "degree", "lon": "degree"}) - -However, `xarray`_ currently doesn't support `units in indexes`_, so the new units were set -as attributes. To really observe the changes the ``quantify`` methods make, we -have to first swap the dimensions: - -.. ipython:: - - In [8]: ds_with_units = ds.swap_dims({"lon": "x", "lat": "y"}).astropy.quantify( - ...: {"lat": "degree", "lon": "degree"} - ...: ) - ...: ds_with_units - - In [9]: da_with_units = da.swap_dims({"lon": "x", "lat": "y"}).astropy.quantify( - ...: {"lat": "degree", "lon": "degree"} - ...: ) - ...: da_with_units - -By default, :py:meth:`Dataset.astropy.quantify` and -:py:meth:`DataArray.astropy.quantify` will use the unit registry at -:py:obj:`astropy_xarray.unit_registry` (the -:py:func:`application registry `). If we want a -different registry, we can either pass it as the ``unit_registry`` parameter: - -.. ipython:: - - In [10]: import astropy.units as u - ...: - ...: # set up the registry - - In [11]: da.astropy.quantify("degree") - -or overwrite the default registry: - -.. ipython:: - - In [12]: da.astropy.quantify("degree") - -.. note:: - - To properly work with ``xarray``, the ``force_ndarray_like`` or - ``force_ndarray`` options have to be enabled on the custom registry. - - Without it, python scalars wrapped by :py:class:`astropy.Quantity` may raise errors or - have their units stripped. - -Saving with units ------------------ -In order to not lose the units when saving to disk, we first have to call the -:py:meth:`Dataset.astropy.dequantify` and :py:meth:`DataArray.astropy.dequantify` -methods: - -.. ipython:: - - In [10]: ds_with_units.astropy.dequantify() - - In [11]: da_with_units.astropy.dequantify() - -This will get the string representation of a :py:class:`astropy.Unit` instance and -attach it as a ``units`` attribute. The data of the variable will now be -whatever `astropy`_ wrapped. - -.. _astropy: https://docs.astropy.org/en/latest/ -.. _xarray: https://docs.xarray.dev/en/stable/ -.. _units in indexes: https://github.com/pydata/xarray/issues/1603 diff --git a/docs/examples.md b/docs/examples.md new file mode 100644 index 00000000..29079250 --- /dev/null +++ b/docs/examples.md @@ -0,0 +1,10 @@ +# Examples + +```{toctree} +--- +maxdepth: 1 +--- +examples/plotting +examples/skycoord +examples/specialized_quantities +``` diff --git a/docs/examples.rst b/docs/examples.rst deleted file mode 100644 index 4879a2ca..00000000 --- a/docs/examples.rst +++ /dev/null @@ -1,9 +0,0 @@ -Examples -======== - -.. toctree:: - :maxdepth: 1 - - examples/plotting - examples/skycoord - examples/specialized_quantities diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 00000000..1665ccb3 --- /dev/null +++ b/docs/index.md @@ -0,0 +1,66 @@ +# astropy-xarray + +Seamless interoperability between [astropy] and [xarray]. + +```{image} img/astropy_xarray_logo.svg +:align: center +:width: 50% +``` + +--- + +:::{warning} +This package is experimental, and new versions might introduce backwards incompatible +changes. +::: + +## Documentation + +### Getting Started + +- {doc}`installation` +- {doc}`examples` + +```{toctree} +:caption: Getting Started +:hidden: true +:maxdepth: 1 + +installation +examples +``` + +### User Guide + +- {doc}`terminology` +- {doc}`creation` +- {doc}`conversion` + +```{toctree} +:caption: User Guide +:hidden: true +:maxdepth: 1 + +terminology +creation +conversion +``` + +### Help & Reference: + +- {doc}`whats-new` +- {doc}`api` +- {doc}`contributing` + +```{toctree} +:caption: Help & Reference +:hidden: true +:maxdepth: 1 + +whats-new +api +contributing +``` + +[astropy]: https://docs.astropy.org/en/latest/ +[xarray]: https://xarray.pydata.org/en/stable diff --git a/docs/index.rst b/docs/index.rst deleted file mode 100644 index c7d3e8f1..00000000 --- a/docs/index.rst +++ /dev/null @@ -1,63 +0,0 @@ -astropy-xarray -============== - -.. image:: img/astropy_xarray_logo.svg - :align: center - :width: 50% - -Seamless interoperability between `astropy`_ and `xarray`_. - -.. _astropy: https://docs.astropy.org/en/latest/ -.. _xarray: https://xarray.pydata.org/en/stable - -.. warning:: - - This package is experimental, and new versions might introduce backwards incompatible - changes. - -Documentation -------------- - -**Getting Started**: - -- :doc:`installation` -- :doc:`examples` - -.. toctree:: - :maxdepth: 1 - :caption: Getting Started - :hidden: - - installation - examples - -**User Guide**: - -- :doc:`terminology` -- :doc:`creation` -- :doc:`conversion` - -.. toctree:: - :maxdepth: 1 - :caption: User Guide - :hidden: - - terminology - creation - conversion - - -**Help & Reference**: - -- :doc:`whats-new` -- :doc:`api` -- :doc:`contributing` - -.. toctree:: - :maxdepth: 1 - :caption: Help & Reference - :hidden: - - whats-new - api - contributing diff --git a/docs/installation.md b/docs/installation.md new file mode 100644 index 00000000..3ec6ff47 --- /dev/null +++ b/docs/installation.md @@ -0,0 +1,26 @@ +# Installation + +Install from `conda-forge`: + +```sh +conda install -c conda-forge astropy-xarray +``` + +or from `PyPI`: + +```sh +python -m pip install astropy-xarray +``` + +or from source, either directly from github: + +```sh +python -m pip install git+https://github.com/calgray/astropy-xarray +``` + +or from a local copy: + +```sh +git clone https://github.com/calgray/astropy-xarray +python -m pip install ./astropy-xarray +``` diff --git a/docs/installation.rst b/docs/installation.rst deleted file mode 100644 index c8511002..00000000 --- a/docs/installation.rst +++ /dev/null @@ -1,26 +0,0 @@ -Installation ------------- -Install from ``conda-forge``: - -.. code:: sh - - conda install -c conda-forge astropy-xarray - -or from ``PyPI``: - -.. code:: sh - - python -m pip install astropy-xarray - -or from source, either directly from github: - -.. code:: sh - - python -m pip install git+https://github.com/calgray/astropy-xarray - -or from a local copy: - -.. code:: sh - - git clone https://github.com/calgray/astropy-xarray - python -m pip install ./astropy-xarray diff --git a/docs/terminology.md b/docs/terminology.md new file mode 100644 index 00000000..1bd955fa --- /dev/null +++ b/docs/terminology.md @@ -0,0 +1,8 @@ +# Terminology + +:::{glossary} +unit-like +: A [astropy] unit definition, as accepted by {py:class}`astropy.units.Unit`. May be either a {py:class}`str` or a {py:class}`astropy.units.Unit` instance. +::: + +[astropy]: https://docs.astropy.org/en/latest/ diff --git a/docs/terminology.rst b/docs/terminology.rst deleted file mode 100644 index 3e04744b..00000000 --- a/docs/terminology.rst +++ /dev/null @@ -1,10 +0,0 @@ -Terminology -=========== - -.. glossary:: - - unit-like - A `astropy`_ unit definition, as accepted by :py:class:`astropy.units.Unit`. - May be either a :py:class:`str` or a :py:class:`astropy.units.Unit` instance. - -.. _astropy: https://docs.astropy.org/en/latest/ diff --git a/docs/whats-new.md b/docs/whats-new.md new file mode 100644 index 00000000..55ab540b --- /dev/null +++ b/docs/whats-new.md @@ -0,0 +1,39 @@ +```{eval-rst} +.. currentmodule:: xarray +``` + +# What's new + +## 0.2.0 (31 Mar 2026) + +- Added `coordinates` submodule with `dataset_to_skycoord` and `skycoord_to_dataset` explicit conversion functions for working with {py:class}`astropy.coordinates.SkyCoord`. + +- Added support for specialized quantities: + - {py:class}`astropy.time.Time` + - {py:class}`astropy.time.TimeDelta` + - {py:class}`astropy.coordinates.Angle` + - {py:class}`astropy.coordinates.Longitude` + - {py:class}`astropy.coordinates.Latitude` + - {py:class}`astropy.coordinates.Distance` + - {py:class}`astropy.units.LogQuantity` + +- Added {py:meth}`Dataset.astropy.to_skycoord` accessor. + + By [Callan Gray](https://github.com/calgray). + +## 0.1.0 (17 Jul 2025) + +- Added `equivalencies` parameter to {py:meth}`DataArray.astropy.to` and {py:meth}`Dataset.astropy.to`. + +- Removed `registry` parameter from {py:meth}`DataArray.astropy.quantify` and {py:meth}`Dataset.astropy.quantify`. + +- Migrated `pint.Quantity` usage to {py:class}`astropy.units.Quantity`, `pint.UnitRegistry` to {py:mod}`astropy.units`, `pint.UnitRegistry.formatter` to {py:mod}`astropy.units.format` ({pull}`1`) + + Notable behavioural differences include: + - Unit registry instance is managed at module scope instead of local scope. + - Multiplying by an array by an {py:class}`astropy.units.Unit` coerses to {py:class}`astropy.units.Quantity` of float64. Explicit construction required to use other numpy dtypes. + - {py:class}`astropy.units.Quantity` uses `unit` and `value` members instead of `units` and `magnitude`. + - `Unit()` is not an instance of {py:class}`astropy.units.Unit`, only {py:class}`astropy.units.UnitBase`. + - Different format literals, see [built-in formats](https://docs.astropy.org/en/stable/units/format.html#built-in-formats). + + By [Callan Gray](https://github.com/calgray). diff --git a/docs/whats-new.rst b/docs/whats-new.rst deleted file mode 100644 index bf7b3da8..00000000 --- a/docs/whats-new.rst +++ /dev/null @@ -1,39 +0,0 @@ -.. currentmodule:: xarray - -What's new -========== - -0.2.0 (31 Mar 2026) -------------------- - -- Added `coordinates` submodule with `dataset_to_skycoord` and `skycoord_to_dataset` explicit conversion functions for working with :py:class:`astropy.coordinates.SkyCoord`. -- Added support for specialized quantities: - - * :py:class:`astropy.time.Time` - * :py:class:`astropy.time.TimeDelta` - * :py:class:`astropy.coordinates.Angle` - * :py:class:`astropy.coordinates.Longitude` - * :py:class:`astropy.coordinates.Latitude` - * :py:class:`astropy.coordinates.Distance` - * :py:class:`astropy.units.LogQuantity` - -- Added :py:meth:`Dataset.astropy.to_skycoord` accessor. - - By `Callan Gray `_. - -0.1.0 (17 Jul 2025) -------------------- - -- Added `equivalencies` parameter to :py:meth:`DataArray.astropy.to` and :py:meth:`Dataset.astropy.to`. -- Removed `registry` parameter from :py:meth:`DataArray.astropy.quantify` and :py:meth:`Dataset.astropy.quantify`. -- Migrated ``pint.Quantity`` usage to :py:class:`astropy.units.Quantity`, ``pint.UnitRegistry`` to :py:mod:`astropy.units`, ``pint.UnitRegistry.formatter`` to :py:mod:`astropy.units.format` (:pull:`1`) - - Notable behavioural differences include: - - * Unit registry instance is managed at module scope instead of local scope. - * Multiplying by an array by an :py:class:`astropy.units.Unit` coerses to :py:class:`astropy.units.Quantity` of float64. Explicit construction required to use other numpy dtypes. - * :py:class:`astropy.units.Quantity` uses ``unit`` and ``value`` members instead of ``units`` and ``magnitude``. - * ``Unit()`` is not an instance of :py:class:`astropy.units.Unit`, only :py:class:`astropy.units.UnitBase`. - * Different format literals, see `built-in formats `_. - - By `Callan Gray `_. diff --git a/pyproject.toml b/pyproject.toml index 57e0708f..1a6711e6 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -50,9 +50,9 @@ test = [ ] docs = [ "sphinx==8.2.3", - "sphinx_auto_summary_accessors", "nbsphinx", "sphinx_rtd_theme", + "sphinx-autosummary-accessors", ] [tool.setuptools.packages.find] From 16a0f8334c1d25dd6a235b2bd10e58434bb268b1 Mon Sep 17 00:00:00 2001 From: Callan Gray Date: Sat, 18 Apr 2026 20:25:14 +0800 Subject: [PATCH 4/6] revamp docs Signed-off-by: Callan Gray --- docs/whats-new.md => CHANGELOG.md | 13 +++- CODE_OF_CONDUCT.md | 83 ++++++++++++++++++++ CONTRIBUTING.md | 55 +++++++++++++ HOW_TO_RELEASE.rst | 36 --------- docs/api.md | 21 +++-- docs/changelog.md | 1 + docs/code_of_conduct.md | 5 ++ docs/contributing.md | 19 +---- docs/creation.md | 2 +- docs/examples/plotting.ipynb | 2 +- docs/examples/skycoord.ipynb | 91 ++++++++++++---------- docs/examples/specialized_quantities.ipynb | 82 +++++++++++-------- docs/index.md | 45 ++++------- docs/license.md | 7 ++ docs/overview.md | 5 ++ docs/terminology.md | 6 +- 16 files changed, 301 insertions(+), 172 deletions(-) rename docs/whats-new.md => CHANGELOG.md (78%) create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md delete mode 100644 HOW_TO_RELEASE.rst create mode 120000 docs/changelog.md create mode 100644 docs/code_of_conduct.md create mode 100644 docs/license.md create mode 100644 docs/overview.md diff --git a/docs/whats-new.md b/CHANGELOG.md similarity index 78% rename from docs/whats-new.md rename to CHANGELOG.md index 55ab540b..2fe8e33e 100644 --- a/docs/whats-new.md +++ b/CHANGELOG.md @@ -1,19 +1,26 @@ ```{eval-rst} +.. currentmodule:: astropy_xarray .. currentmodule:: xarray ``` -# What's new +# What's New + +## 0.2.1 (8 Apr 2026) + +- Added support for `astropy==7.2.0`. + + By [Callan Gray](https://github.com/calgray). ## 0.2.0 (31 Mar 2026) -- Added `coordinates` submodule with `dataset_to_skycoord` and `skycoord_to_dataset` explicit conversion functions for working with {py:class}`astropy.coordinates.SkyCoord`. +- Added {py:mod}`coordinates` submodule with {py:func}`coordinates.dataset_to_skycoord` and {py:func}`coordinates.skycoord_to_dataset` explicit conversion functions for working with {py:class}`astropy.coordinates.SkyCoord`. - Added support for specialized quantities: - {py:class}`astropy.time.Time` - {py:class}`astropy.time.TimeDelta` - {py:class}`astropy.coordinates.Angle` - {py:class}`astropy.coordinates.Longitude` - - {py:class}`astropy.coordinates.Latitude` + - {py:class}`astropy.coordinates.Latitude`\*\*\*\* - {py:class}`astropy.coordinates.Distance` - {py:class}`astropy.units.LogQuantity` diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..3764b64d --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,83 @@ +# Contributor Covenant 3.0 Code of Conduct + +## Our Pledge + +We pledge to make our community welcoming, safe, and equitable for all. + +We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant. + +## Encouraged Behaviors + +While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language. + +With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including: + +1. Respecting the **purpose of our community**, our activities, and our ways of gathering. +2. Engaging **kindly and honestly** with others. +3. Respecting **different viewpoints** and experiences. +4. **Taking responsibility** for our actions and contributions. +5. Gracefully giving and accepting **constructive feedback**. +6. Committing to **repairing harm** when it occurs. +7. Behaving in other ways that promote and sustain the **well-being of our community**. + +## Restricted Behaviors + +We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct. + +1. **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop. +2. **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people. +3. **Stereotyping or discrimination.** Characterizing anyone’s personality or behavior on the basis of immutable identities or traits. +4. **Sexualization.** Behaving in a way that would generally be considered inappropriately intimate in the context or purpose of the community. +5. **Violating confidentiality**. Sharing or acting on someone's personal or private information without their permission. +6. **Endangerment.** Causing, encouraging, or threatening violence or other harm toward any person or group. +7. Behaving in other ways that **threaten the well-being** of our community. + +### Other Restrictions + +1. **Misleading identity.** Impersonating someone else for any reason, or pretending to be someone else to evade enforcement actions. +2. **Failing to credit sources.** Not properly crediting the sources of content you contribute. +3. **Promotional materials**. Sharing marketing or other commercial content in a way that is outside the norms of the community. +4. **Irresponsible communication.** Failing to responsibly present content which includes, links or describes any other restricted behaviors. + +## Reporting an Issue + +Tensions can occur between community members even when they are trying their best to collaborate. Not every conflict represents a code of conduct violation, and this Code of Conduct reinforces encouraged behaviors and norms that can help avoid conflicts and minimize harm. + +When an incident does occur, it is important to report it promptly. Toavailable report a possible violation, email [cal.j.gray@gmail.com](mailto:cal.j.gray@gmail.com) outlining any details and evidences. + +Community Moderators take reports of violations seriously and will make every effort to respond in a timely manner. They will investigate all reports of code of conduct violations, reviewing messages, logs, and recordings, or interviewing witnesses and other participants. Community Moderators will keep investigation and enforcement actions as transparent as possible while prioritizing safety and confidentiality. In order to honor these values, enforcement actions are carried out in private with the involved parties, but communicating to the whole community may be part of a mutually agreed upon resolution. + +## Addressing and Repairing Harm + +If an investigation by the Community Moderators finds that this Code of Conduct has been violated, the following enforcement ladder may be used to determine how best to repair harm, based on the incident's impact on the individuals involved and the community as a whole. Depending on the severity of a violation, lower rungs on the ladder may be skipped. + +1. Warning + 1. Event: A violation involving a single incident or series of incidents. + 2. Consequence: A private, written warning from the Community Moderators. + 3. Repair: Examples of repair include a private written apology, acknowledgement of responsibility, and seeking clarification on expectations. +2. Temporarily Limited Activities + 1. Event: A repeated incidence of a violation that previously resulted in a warning, or the first incidence of a more serious violation. + 2. Consequence: A private, written warning with a time-limited cooldown period designed to underscore the seriousness of the situation and give the community members involved time to process the incident. The cooldown period may be limited to particular communication channels or interactions with particular community members. + 3. Repair: Examples of repair may include making an apology, using the cooldown period to reflect on actions and impact, and being thoughtful about re-entering community spaces after the period is over. +3. Temporary Suspension + 1. Event: A pattern of repeated violation which the Community Moderators have tried to address with warnings, or a single serious violation. + 2. Consequence: A private written warning with conditions for return from suspension. In general, temporary suspensions give the person being suspended time to reflect upon their behavior and possible corrective actions. + 3. Repair: Examples of repair include respecting the spirit of the suspension, meeting the specified conditions for return, and being thoughtful about how to reintegrate with the community when the suspension is lifted. +4. Permanent Ban + 1. Event: A pattern of repeated code of conduct violations that other steps on the ladder have failed to resolve, or a violation so serious that the Community Moderators determine there is no way to keep the community safe with this person as a member. + 2. Consequence: Access to all community spaces, tools, and communication channels is removed. In general, permanent bans should be rarely used, should have strong reasoning behind them, and should only be resorted to if working through other remedies has failed to change the behavior. + 3. Repair: There is no possible repair in cases of this severity. + +This enforcement ladder is intended as a guideline. It does not limit the ability of Community Managers to use their discretion and judgment, in keeping with the best interests of our community. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Attribution + +This Code of Conduct is adapted from the Contributor Covenant, version 3.0, permanently available at [https://www.contributor-covenant.org/version/3/0/](https://www.contributor-covenant.org/version/3/0/). + +Contributor Covenant is stewarded by the Organization for Ethical Source and licensed under CC BY-SA 4.0. To view a copy of this license, visit [https://creativecommons.org/licenses/by-sa/4.0/](https://creativecommons.org/licenses/by-sa/4.0/) + +For answers to common questions about Contributor Covenant, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are provided at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations). Additional enforcement and community guideline resources can be found at [https://www.contributor-covenant.org/resources](https://www.contributor-covenant.org/resources). The enforcement ladder was inspired by the work of [Mozilla’s code of conduct team](https://github.com/mozilla/inclusion). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..040954b7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,55 @@ +# Contributing + +`astropy-xarray` is developed on [github](https://github.com/calgray/astropy-xarray). + +## Commit message tags + +By default, the upstream dev CI is disabled on pull request and push events. You can +override this behavior per commit by adding a \[test-upstream]\ tag to the first +line of the commit message. + +## Linters / Autoformatters + +In order to keep code consistent, we use + +- [Black](https://black.readthedocs.io/en/stable/) for standardized code formatting +- [blackdoc](https://blackdoc.readthedocs.io/en/stable/) for standardized code formatting in documentation +- [Flake8](https://flake8.pycqa.org/en/latest/) for general code quality +- [isort](https://github.com/PyCQA/isort) for standardized order in imports. See also [flake8-isort](https://github.com/gforcada/flake8-isort). + +## Release process + +1. the release happens from `main` so make sure it is up-to-date: + + ```sh + git pull origin main + ``` + +2. look at `CHANGELOG.md` and make sure it is complete and with + references to issues and pull requests + +3. open and merge a pull request with these changes + +4. make sure the CI on main pass + +5. check that the documentation build on readthedocs completed successfully + +6. Fill in the release date and commit the release: + + ```sh + git commit -am "Release v0.X.Y" + ``` + +7. Tag the release and push to main: + + ```sh + git tag -a v0.X.Y -m "v0.X.Y" + git push origin --tags + ``` + +8. Draft a release for the new tag on github. A CI will pick that up, build the project + and push to PyPI. Be careful, this can't be undone. + +9. Make sure readthedocs builds both `stable` and the new tag + +10. Add a new section to `CHANGELOG.md` and push directly to main diff --git a/HOW_TO_RELEASE.rst b/HOW_TO_RELEASE.rst deleted file mode 100644 index 308122a3..00000000 --- a/HOW_TO_RELEASE.rst +++ /dev/null @@ -1,36 +0,0 @@ -Release process -=============== -1. the release happens from `main` so make sure it is up-to-date: - - .. code:: sh - - git pull origin main - -2. look at `whats-new.rst` and make sure it is complete and with - references to issues and pull requests - -3. open and merge a pull request with these changes - -4. make sure the CI on main pass - -5. check that the documentation build on readthedocs completed successfully - -6. Fill in the release date and commit the release: - - .. code:: sh - - git commit -am "Release v0.X.Y" - -7. Tag the release and push to main: - - .. code:: sh - - git tag -a v0.X.Y -m "v0.X.Y" - git push origin --tags - -8. Draft a release for the new tag on github. A CI will pick that up, build the project - and push to PyPI. Be careful, this can't be undone. - -9. Make sure readthedocs builds both `stable` and the new tag - -10. Add a new section to `whats-new.rst` and push directly to main diff --git a/docs/api.md b/docs/api.md index eac4e2bd..5e78b99b 100644 --- a/docs/api.md +++ b/docs/api.md @@ -1,17 +1,7 @@ -# API reference +# Python API This page contains a auto-generated summary of `astropy-xarray`'s API. -```{eval-rst} -.. autosummary:: - :toctree: generated/ - - astropy_xarray.coordinates.dataset_to_skycoord - astropy_xarray.coordinates.skycoord_to_dataset - astropy_xarray.coordinates.load_frame - astropy_xarray.coordinates.load_representation -``` - ## Dataset ```{eval-rst} @@ -78,6 +68,15 @@ This page contains a auto-generated summary of `astropy-xarray`'s API. xarray.DataArray.astropy.interpolate_na ``` +## Coordinates + +```{eval-rst} +.. autosummary:: + :toctree: generated/ + + astropy_xarray.coordinates +``` + ## Testing ```{eval-rst} diff --git a/docs/changelog.md b/docs/changelog.md new file mode 120000 index 00000000..a7942c51 --- /dev/null +++ b/docs/changelog.md @@ -0,0 +1 @@ +/home/callan/Code/astropy-xarray/CHANGELOG.md \ No newline at end of file diff --git a/docs/code_of_conduct.md b/docs/code_of_conduct.md new file mode 100644 index 00000000..74fe1778 --- /dev/null +++ b/docs/code_of_conduct.md @@ -0,0 +1,5 @@ +# Code of Conduct + +```{include} ../CODE_OF_CONDUCT.md +:heading-offset: 1 +``` diff --git a/docs/contributing.md b/docs/contributing.md index 3305ef5b..66c1f98d 100644 --- a/docs/contributing.md +++ b/docs/contributing.md @@ -1,18 +1,3 @@ -# Contributing +```{include} ../CONTRIBUTING.md -`astropy-xarray` is developed on [github](https://github.com/calgray/astropy-xarray). - -## Commit message tags - -By default, the upstream dev CI is disabled on pull request and push events. You can -override this behavior per commit by adding a \[test-upstream]\ tag to the first -line of the commit message. - -## Linters / Autoformatters - -In order to keep code consistent, we use - -- [Black](https://black.readthedocs.io/en/stable/) for standardized code formatting -- [blackdoc](https://blackdoc.readthedocs.io/en/stable/) for standardized code formatting in documentation -- [Flake8](https://flake8.pycqa.org/en/latest/) for general code quality -- [isort](https://github.com/PyCQA/isort) for standardized order in imports. See also [flake8-isort](https://github.com/gforcada/flake8-isort). +``` diff --git a/docs/creation.md b/docs/creation.md index 27ab6e1c..ad73c94c 100644 --- a/docs/creation.md +++ b/docs/creation.md @@ -2,7 +2,7 @@ .. currentmodule:: xarray ``` -# Creating and saving objects with units +# Creating datasets with units ## Attaching units diff --git a/docs/examples/plotting.ipynb b/docs/examples/plotting.ipynb index 509533c8..cbda3d39 100644 --- a/docs/examples/plotting.ipynb +++ b/docs/examples/plotting.ipynb @@ -5,7 +5,7 @@ "id": "0", "metadata": {}, "source": [ - "# plotting quantified data" + "# Plotting Quantified Data" ] }, { diff --git a/docs/examples/skycoord.ipynb b/docs/examples/skycoord.ipynb index 5c5d3e91..e049ad7a 100644 --- a/docs/examples/skycoord.ipynb +++ b/docs/examples/skycoord.ipynb @@ -4,7 +4,7 @@ "cell_type": "markdown", "metadata": {}, "source": [ - "## SkyCoord, Frame and Angles as xarray Dataset\n", + "# SkyCoord, Frame and Angles as Dataset\n", "\n", "SkyCoord and Frame fully support conversion to datasets preserving:\n", "* Representation\n", @@ -36,12 +36,10 @@ " dec=[[4, 7, 4, 3]] * u.deg,\n", " pm_ra_cosdec=[[1, 1, 1, 1]] * u.mas / u.yr,\n", " pm_dec=[[1, 1, 1, 1]] * u.mas / u.yr,\n", - " frame=\"icrs\",\n", - " # NOTE: for explicit direction, consider using:\n", - " # frame=ICRS(\n", - " # representation_type='unitspherical',\n", - " # differential_type='unitsphericalcoslat',\n", - " # ),\n", + " frame=ICRS(\n", + " representation_type=\"unitspherical\",\n", + " differential_type=\"unitsphericalcoslat\",\n", + " ),\n", ")\n", "display(sky_direction)\n", "skycoord_to_dataset(\n", @@ -75,7 +73,10 @@ " distance=[4, 3, 6, 4] * u.parsec,\n", " pm_ra_cosdec=[1, 1, 1, 1] * u.mas / u.yr,\n", " pm_dec=[1, 1, 1, 1] * u.mas / u.yr,\n", - " frame=\"icrs\",\n", + " frame=ICRS(\n", + " representation_type=\"spherical\",\n", + " differential_type=\"unitsphericalcoslat\",\n", + " ),\n", ")\n", "display(sky_position)\n", "display(\n", @@ -85,24 +86,6 @@ ")" ] }, - { - "cell_type": "code", - "execution_count": null, - "metadata": {}, - "outputs": [], - "source": [ - "# Since the default ICRS differential type is 'sphericalcoslat', the first access\n", - "# to 'radial_velocity' will compute, cache and mutate the skycoordinate data\n", - "display(sky_position.radial_velocity)\n", - "\n", - "# skycoord_to_dataset will then subsequently include these radial velocity values when this occurs\n", - "display(\n", - " skycoord_to_dataset(\n", - " sky_position, coords={\"field_label\": (\"field\", [\"a\", \"b\", \"c\", \"d\"])}\n", - " )\n", - ")" - ] - }, { "cell_type": "markdown", "metadata": {}, @@ -151,7 +134,7 @@ "source": [ "## Serialization and Deserialization\n", "\n", - "Using dequantifing, all type metadata can be converted entriely to json-like attributes:" + "Using dequantifing, all type metadata can be converted entirely to json-like attributes." ] }, { @@ -219,7 +202,7 @@ "metadata": {}, "outputs": [], "source": [ - "# SkyCoord itself doesn't strongly infer directional reprentation and differential types.\n", + "# SkyCoord frame doesn't strongly infer directional reprentation and differential types\n", "import astropy.units as u\n", "from astropy.coordinates import SkyCoord\n", "\n", @@ -232,10 +215,18 @@ ")\n", "assert (\n", " sky_direction.representation_type.name == \"spherical\"\n", - ") # would expect \"unitspherical\"\n", + ") # may have expected \"unitspherical\"\n", "assert (\n", " sky_direction.differential_type.name == \"sphericalcoslat\"\n", - ") # would expect \"unitsphericalcoslat\"" + ") # may have expected \"unitsphericalcoslat\"\n", + "\n", + "display(sky_direction)\n", + "\n", + "# additional members are therefore implicitly available\n", + "display(sky_direction.distance)\n", + "display(sky_direction.radial_velocity)\n", + "\n", + "display(sky_direction)" ] }, { @@ -244,23 +235,45 @@ "metadata": {}, "outputs": [], "source": [ - "# For differential mismatch, this effects SkyCoord methods until the prefered representations are cached.\n", "sky_position = SkyCoord(\n", " ra=[2, 6, 7, 4] * u.deg,\n", " dec=[4, 7, 4, 3] * u.deg,\n", + " distance=[4, 3, 6, 4] * u.parsec,\n", + " pm_ra_cosdec=[1, 1, 1, 1] * u.mas / u.yr,\n", + " pm_dec=[1, 1, 1, 1] * u.mas / u.yr,\n", + " frame=\"icrs\",\n", + ")\n", + "display(sky_position)\n", + "# using positional representation with direction differentials causes accessor of\n", + "# `radial_velocity` to mutate data of the skycoordinate\n", + "display(sky_position.radial_velocity)\n", + "# skycoord_to_dataset will then subsequently include these radial velocity values when this occurs\n", + "display(sky_position)" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "metadata": {}, + "outputs": [], + "source": [ + "# `represent_as` can also update cached data\n", + "sky_direction = SkyCoord(\n", + " ra=[2, 6, 7, 4] * u.deg,\n", + " dec=[4, 7, 4, 3] * u.deg,\n", " distance=[1, 1, 1, 1] * u.dimensionless_unscaled,\n", " pm_ra_cosdec=[1, 1, 1, 1] * u.mas / u.yr,\n", " pm_dec=[1, 1, 1, 1] * u.mas / u.yr,\n", " frame=\"icrs\",\n", ")\n", - "assert sky_position.representation_type.name == \"spherical\"\n", - "assert sky_position.differential_type.name == \"sphericalcoslat\"\n", - "sky_position_old_str = str(sky_position)\n", + "assert sky_direction.representation_type.name == \"spherical\"\n", + "assert sky_direction.differential_type.name == \"sphericalcoslat\"\n", + "sky_direction_old_str = str(sky_direction)\n", "\n", - "sky_position.represent_as(\"spherical\", \"sphericalcoslat\") # cache updated\n", - "assert sky_position.representation_type.name == \"spherical\"\n", - "assert sky_position.differential_type.name == \"sphericalcoslat\"\n", - "assert str(sky_position) != sky_position_old_str # string method changed" + "sky_direction.represent_as(\"spherical\", \"sphericalcoslat\") # cache updated\n", + "assert sky_direction.representation_type.name == \"spherical\"\n", + "assert sky_direction.differential_type.name == \"sphericalcoslat\"\n", + "assert str(sky_direction) != sky_direction_old_str # string method changed" ] }, { @@ -303,7 +316,7 @@ ")\n", "print(\"SkyCoord:\", sky_direction.ra.data[1])\n", "\n", - "# dataset serialization avoids unit conversions where possible\n", + "# astropy-xarray dataset prevents unit conversion loss\n", "ds = skycoord_to_dataset(sky_direction, coords={\"field\": [\"a\", \"b\", \"c\", \"d\"]})\n", "print(\"Dataset:\", ds.ra.data[1].value)" ] diff --git a/docs/examples/specialized_quantities.ipynb b/docs/examples/specialized_quantities.ipynb index e2733a13..df70e85b 100644 --- a/docs/examples/specialized_quantities.ipynb +++ b/docs/examples/specialized_quantities.ipynb @@ -108,10 +108,7 @@ " skycoord_to_dataset,\n", ")\n", "\n", - "sc = SkyCoord(\n", - " ra=[2, 6, 7, 4] * u.deg,\n", - " dec=[4, 7, 4, 3] * u.deg,\n", - ")\n", + "sc = SkyCoord(ra=[2, 6, 7, 4] * u.deg, dec=[4, 7, 4, 3] * u.deg, frame=\"icrs\")\n", "\n", "\n", "s = skycoord_to_dataset(sc, coords={\"field\": [\"a\", \"b\", \"c\", \"d\"]})\n", @@ -140,10 +137,18 @@ "| Magnitude (AB) | Jy | -2.5 | 10 | 3631 Jy |" ] }, + { + "cell_type": "markdown", + "id": "8", + "metadata": {}, + "source": [ + "### Custom Unit References" + ] + }, { "cell_type": "code", "execution_count": null, - "id": "8", + "id": "9", "metadata": {}, "outputs": [], "source": [ @@ -154,37 +159,52 @@ "import numpy as np\n", "from astropy.units import Dex, Equivalency, Magnitude, Quantity\n", "\n", - "import astropy_xarray # noqa: F401\n", - "\n", "\n", "# extend registry\n", - "def asplund():\n", - " asplund = types.ModuleType(\"asplund\")\n", + "def solar():\n", + " solar = types.ModuleType(\"solar\")\n", + "\n", + " # Solar relative metalicity\n", " astropy.units.def_unit(\n", " [\"solH\", \"Xsun\"],\n", - " format={\"latex\": \"X_{\\\\odot}\", \"unicode\": \"X⊙\"},\n", - " namespace=asplund.__dict__,\n", + " format={\"latex\": \"X_{\\\\odot}\", \"unicode\": \"X☉\"},\n", + " namespace=solar.__dict__,\n", " )\n", " astropy.units.def_unit(\n", " [\"solHe\", \"Ysun\"],\n", - " format={\"latex\": \"Y_{\\\\odot}\", \"unicode\": \"Y⊙\"},\n", - " namespace=asplund.__dict__,\n", + " format={\"latex\": \"Y_{\\\\odot}\", \"unicode\": \"Y☉\"},\n", + " namespace=solar.__dict__,\n", " )\n", " astropy.units.def_unit(\n", " [\"solMetal\", \"Zsun\"],\n", - " format={\"latex\": \"Z_{\\\\odot}\", \"unicode\": \"Z⊙\"},\n", - " namespace=asplund.__dict__,\n", + " format={\"latex\": \"Z_{\\\\odot}\", \"unicode\": \"Z☉\"},\n", + " namespace=solar.__dict__,\n", " )\n", "\n", - " return asplund\n", - "\n", - "\n", - "if not hasattr(u, \"asplund\"):\n", - " u.asplund = asplund()\n", - " u.add_enabled_units(u.asplund)\n", - " u.__dict__.update(u.get_current_unit_registry().registry)\n", + " return solar\n", "\n", "\n", + "if not hasattr(u, \"solar\"):\n", + " u.solar = solar()\n", + " u.add_enabled_units(u.solar)\n", + " u.__dict__.update(u.get_current_unit_registry().registry)" + ] + }, + { + "cell_type": "markdown", + "id": "10", + "metadata": {}, + "source": [ + "### asplund et. al equivalencies" + ] + }, + { + "cell_type": "code", + "execution_count": null, + "id": "11", + "metadata": {}, + "outputs": [], + "source": [ "def asplund_solar_relative_mass() -> Equivalency:\n", " \"\"\"measurements from https://www.aanda.org/articles/aa/full_html/2021/09/aa40445-21/aa40445-21.html\"\"\"\n", " return Equivalency(\n", @@ -205,7 +225,7 @@ { "cell_type": "code", "execution_count": null, - "id": "9", + "id": "12", "metadata": {}, "outputs": [], "source": [ @@ -220,19 +240,15 @@ " data_vars={\n", " \"mass\": ([\"time\", \"body\"], Dex([[0.0, 0.02]], unit=u.dex(u.Msun))),\n", " \"distance\": ([\"time\", \"body\"], [[1.007, 12950]] * u.AU),\n", + " # radiant flux\n", " \"luminosity\": (\n", " [\"time\", \"body\"],\n", " Quantity([[1, 0.001]], unit=u.Lsun).to(u.dex(u.Lsun)),\n", - " ), # radiant flux\n", + " ),\n", " \"metallicity\": ([\"time\", \"body\"], Dex([[0.0, np.nan]], unit=u.dex(u.Zsun))),\n", - " \"apparent_magnitude\": (\n", - " [\"time\", \"body\"],\n", - " Magnitude([[-26.74, 10.67]]),\n", - " ), # to Vega\n", + " # relative to Vega\n", + " \"apparent_magnitude\": ([\"time\", \"body\"], Magnitude([[-26.74, 10.67]])),\n", " \"absolute_magnitude\": ([\"time\", \"body\"], Magnitude([[4.83, 15.60]])),\n", - " # \"irradiance\": ([\"time\", \"body\"], [[1361, 0]] * u.W / u.m**2),\n", - " # \"radiant_flux_density\": ([\"time\", \"body\"], [[1.0, 0.0]] * u.W / u.m**2),\n", - " # \"spectral_flux_density\": ([\"time\", \"body\", \"frequency\"], [[[68000, 0, 0], [0, 0, 0]]] * u.Jy),\n", " },\n", ")\n", "ds" @@ -241,7 +257,7 @@ { "cell_type": "code", "execution_count": null, - "id": "10", + "id": "13", "metadata": {}, "outputs": [], "source": [ @@ -260,7 +276,7 @@ { "cell_type": "code", "execution_count": null, - "id": "11", + "id": "14", "metadata": {}, "outputs": [], "source": [] diff --git a/docs/index.md b/docs/index.md index 1665ccb3..3ce23ea9 100644 --- a/docs/index.md +++ b/docs/index.md @@ -9,57 +9,46 @@ Seamless interoperability between [astropy] and [xarray]. --- +# Documentation + :::{warning} This package is experimental, and new versions might introduce backwards incompatible changes. ::: -## Documentation - -### Getting Started - -- {doc}`installation` -- {doc}`examples` - ```{toctree} :caption: Getting Started -:hidden: true -:maxdepth: 1 +:maxdepth: 2 installation -examples +overview ``` -### User Guide - -- {doc}`terminology` -- {doc}`creation` -- {doc}`conversion` - ```{toctree} :caption: User Guide -:hidden: true -:maxdepth: 1 +:maxdepth: 2 -terminology creation conversion +examples +terminology ``` -### Help & Reference: +```{toctree} +:caption: API Reference +:maxdepth: 2 -- {doc}`whats-new` -- {doc}`api` -- {doc}`contributing` +api +``` ```{toctree} -:caption: Help & Reference -:hidden: true -:maxdepth: 1 +:caption: Community +:maxdepth: 2 -whats-new -api +changelog contributing +code_of_conduct +license ``` [astropy]: https://docs.astropy.org/en/latest/ diff --git a/docs/license.md b/docs/license.md new file mode 100644 index 00000000..f17ce239 --- /dev/null +++ b/docs/license.md @@ -0,0 +1,7 @@ +# License + +## Apache License 2.0 + +```{literalinclude} ../LICENSE + +``` diff --git a/docs/overview.md b/docs/overview.md new file mode 100644 index 00000000..25ad8ff6 --- /dev/null +++ b/docs/overview.md @@ -0,0 +1,5 @@ +# Quick Overview + +```{include} ../README.md +:start-line: 16 +``` diff --git a/docs/terminology.md b/docs/terminology.md index 1bd955fa..2476daa1 100644 --- a/docs/terminology.md +++ b/docs/terminology.md @@ -1,8 +1,8 @@ # Terminology -:::{glossary} +```{glossary} unit-like -: A [astropy] unit definition, as accepted by {py:class}`astropy.units.Unit`. May be either a {py:class}`str` or a {py:class}`astropy.units.Unit` instance. -::: + A [astropy] unit definition, as accepted by {py:class}`astropy.units.Unit`. May be either a {py:class}`str` or a {py:class}`astropy.units.Unit` instance. +``` [astropy]: https://docs.astropy.org/en/latest/ From 70ce86dfa17ccf13740ab4a5bf956e7ef90d2f58 Mon Sep 17 00:00:00 2001 From: Callan Gray Date: Sat, 18 Apr 2026 20:33:04 +0800 Subject: [PATCH 5/6] update doc dependencies Signed-off-by: Callan Gray --- docs/requirements.txt | 1 + pyproject.toml | 7 ++++--- 2 files changed, 5 insertions(+), 3 deletions(-) diff --git a/docs/requirements.txt b/docs/requirements.txt index 602f7256..b2d0f5e5 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,5 +1,6 @@ astropy==7.2.0 xarray>=2022.06.0 +myst-nb==1.4.0 pooch netCDF4 msgpack-numpy>=0.4.8 diff --git a/pyproject.toml b/pyproject.toml index 1a6711e6..1c019604 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -44,14 +44,15 @@ test = [ "pytest-cov", "dask[array]", "msgpack>=1.1.2", - "msgpack_numpy>=0.4.8", - "cf_xarray>=0.10.6", + "msgpack-numpy>=0.4.8", + "cf-xarray>=0.10.6", "bottleneck", ] docs = [ "sphinx==8.2.3", + "myst-nb==1.4.0", "nbsphinx", - "sphinx_rtd_theme", + "sphinx-rtd-theme", "sphinx-autosummary-accessors", ] From 3041a4adf612aec17a0ad9862b21c7a3a37a9bf3 Mon Sep 17 00:00:00 2001 From: Callan Gray Date: Sat, 18 Apr 2026 20:39:26 +0800 Subject: [PATCH 6/6] update changelog Signed-off-by: Callan Gray --- docs/whats-new.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/docs/whats-new.rst b/docs/whats-new.rst index bf7b3da8..2b183463 100644 --- a/docs/whats-new.rst +++ b/docs/whats-new.rst @@ -3,6 +3,13 @@ What's new ========== +0.2.1 (TBD) +----------- + +- Added support for `astropy==7.2.0` sky coordinates. + +By `Callan Gray `_. + 0.2.0 (31 Mar 2026) ------------------- @@ -19,7 +26,7 @@ What's new - Added :py:meth:`Dataset.astropy.to_skycoord` accessor. - By `Callan Gray `_. +By `Callan Gray `_. 0.1.0 (17 Jul 2025) ------------------- @@ -36,4 +43,4 @@ What's new * ``Unit()`` is not an instance of :py:class:`astropy.units.Unit`, only :py:class:`astropy.units.UnitBase`. * Different format literals, see `built-in formats `_. - By `Callan Gray `_. +By `Callan Gray `_.