Skip to content

Update Custom Indexes section in api.rst #10517

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Jul 9, 2025
Merged

Update Custom Indexes section in api.rst #10517

Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
dac661d
Fix docs build.
dcherian Jul 9, 2025
0bda19a
Update Custom Indexes section in api.rst
dcherian Jul 9, 2025
e05f085
Move user-facing API up to Indexes section
dcherian Jul 9, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 0 additions & 16 deletions doc/api-hidden.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -515,22 +515,6 @@
CFTimeIndex.values
CFTimeIndex.year

Index.from_variables
Index.concat
Index.stack
Index.unstack
Index.create_variables
Index.should_add_coord_to_array
Index.to_pandas_index
Index.isel
Index.sel
Index.join
Index.reindex_like
Index.equals
Index.roll
Index.rename
Index.copy

indexes.RangeIndex.start
indexes.RangeIndex.stop
indexes.RangeIndex.step
Expand Down
46 changes: 37 additions & 9 deletions doc/api.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1571,12 +1571,22 @@ Custom Indexes
==============
.. currentmodule:: xarray

Default, pandas-backed indexes built-in to Xarray:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm wondering about renaming this entire section Custom Indexes -> Indexes, and promoting it up so that it's underneath other core data structures (under Coordinates)

Also a quick update here would be nice https://xray--10517.org.readthedocs.build/en/10517/internals/internal-design.html#internal-design (but that can also happen later as part of #10323)

Copy link
Contributor Author

@dcherian dcherian Jul 9, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I moved half of it up, and left the "build new indexes" pieces down where they are now.

The internal design page will require more time than I have now.


.. autosummary::
:toctree: generated/

indexes.PandasIndex
indexes.PandasMultiIndex


More complex indexes built-in to Xarray:

.. autosummary::
:toctree: generated/

CFTimeIndex
indexes.RangeIndex
indexes.CoordinateTransformIndex
indexes.NDPointIndex

Creating custom indexes
Expand All @@ -1590,12 +1600,38 @@ Creating custom indexes
indexes.RangeIndex.arange
indexes.RangeIndex.linspace

The Index base class for building custom indexes:

.. autosummary::
:toctree: generated/

Index.from_variables
Index.concat
Index.stack
Index.unstack
Index.create_variables
Index.should_add_coord_to_array
Index.to_pandas_index
Index.isel
Index.sel
Index.join
Index.reindex_like
Index.equals
Index.roll
Index.rename
Index.copy

Building custom indexes
-----------------------

These classes are building blocks for more complex Indexes:

.. autosummary::
:toctree: generated/

indexes.CoordinateTransform
indexes.CoordinateTransformIndex
indexes.NDPointIndex

Tutorial
========
Expand Down Expand Up @@ -1702,14 +1738,6 @@ Advanced API
.. Missing:
.. ``DataTree.set_close``

Default, pandas-backed indexes built-in Xarray:

.. autosummary::
:toctree: generated/

indexes.PandasIndex
indexes.PandasMultiIndex

These backends provide a low-level interface for lazily loading data from
external file-formats or protocols, and can be manually invoked to create
arguments for the ``load_store`` and ``dump_to_store`` Dataset methods:
Expand Down
5 changes: 3 additions & 2 deletions xarray/core/coordinate_transform.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9,8 +9,9 @@
class CoordinateTransform:
"""Abstract coordinate transform with dimension & coordinate names.

EXPERIMENTAL (not ready for public use yet).

.. caution::
This API is experimental and subject to change. Please report any bugs or surprising
behaviour you encounter.
"""

coord_names: tuple[Hashable, ...]
Expand Down
2 changes: 1 addition & 1 deletion xarray/core/dataarray.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6915,7 +6915,7 @@ def groupby(
:ref:`groupby`
Users guide explanation of how to group and bin data.

:doc:`xarray-tutorial:intermediate/01-high-level-computation-patterns`
:doc:`xarray-tutorial:intermediate/computation/01-high-level-computation-patterns`
Tutorial on :py:func:`~xarray.DataArray.Groupby` for windowed computation

:doc:`xarray-tutorial:fundamentals/03.2_groupby_with_xarray`
Expand Down
2 changes: 1 addition & 1 deletion xarray/core/dataset.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -9941,7 +9941,7 @@ def groupby(
:ref:`groupby`
Users guide explanation of how to group and bin data.

:doc:`xarray-tutorial:intermediate/01-high-level-computation-patterns`
:doc:`xarray-tutorial:intermediate/computation/01-high-level-computation-patterns`
Tutorial on :py:func:`~xarray.Dataset.Groupby` for windowed computation.

:doc:`xarray-tutorial:fundamentals/03.2_groupby_with_xarray`
Expand Down
5 changes: 3 additions & 2 deletions xarray/core/indexes.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1455,14 +1455,15 @@ def rename(self, name_dict, dims_dict):
class CoordinateTransformIndex(Index):
"""Helper class for creating Xarray indexes based on coordinate transforms.

EXPERIMENTAL (not ready for public use yet).

- wraps a :py:class:`CoordinateTransform` instance
- takes care of creating the index (lazy) coordinates
- supports point-wise label-based selection
- supports exact alignment only, by comparing indexes based on their transform
(not on their explicit coordinate labels)

.. caution::
This API is experimental and subject to change. Please report any bugs or surprising
behaviour you encounter.
"""

transform: CoordinateTransform
Expand Down
Loading