From eb6dc62b6f398e0af5be295982d56b26fb57d059 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Tue, 13 May 2025 17:22:42 +0200 Subject: [PATCH 01/16] implement `Coordinates` methods modifying coords --- xarray/core/coordinates.py | 76 +++++++++++++++++++++++++++++++++++++- 1 file changed, 74 insertions(+), 2 deletions(-) diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py index 13fe0a791bb..c6c9eb0d15a 100644 --- a/xarray/core/coordinates.py +++ b/xarray/core/coordinates.py @@ -1,6 +1,6 @@ from __future__ import annotations -from collections.abc import Hashable, Iterator, Mapping, Sequence +from collections.abc import Callable, Hashable, Iterable, Iterator, Mapping, Sequence from contextlib import contextmanager from typing import ( TYPE_CHECKING, @@ -21,7 +21,7 @@ assert_no_index_corrupted, create_default_index_implicit, ) -from xarray.core.types import DataVars, Self, T_DataArray, T_Xarray +from xarray.core.types import DataVars, ErrorOptions, Self, T_DataArray, T_Xarray from xarray.core.utils import ( Frozen, ReprObject, @@ -719,6 +719,78 @@ def copy( ), ) + def drop_vars( + self, + names: str | Iterable[Hashable] | Callable[[Self], str | Iterable[Hashable]], + *, + errors: ErrorOptions = "raise", + ) -> Self: + """Drop variables from this Coordinates object. + + Note that indexes that depend on these variables will also be dropped. + + Parameters + ---------- + names : hashable or iterable or callable + Name(s) of variables to drop. If a callable, this is object is passed as its + only argument and its result is used. + errors : {"raise", "ignore"}, default: "raise" + Error treatment. + + - ``'raise'``: raises a :py:class:`ValueError` error if any of the variable + passed are not in the dataset + - ``'ignore'``: any given names that are in the dataset are dropped and no + error is raised. + """ + return self.to_dataset().drop_vars(names, errors=errors).coords + + def rename_dims( + self, + dims_dict: Mapping[Any, Hashable] | None = None, + **dims: Hashable, + ) -> Self: + """Returns a new object with renamed dimensions only. + + Parameters + ---------- + dims_dict : dict-like, optional + Dictionary whose keys are current dimension names and + whose values are the desired names. The desired names must + not be the name of an existing dimension or Variable in the Dataset. + **dims : optional + Keyword form of ``dims_dict``. + One of dims_dict or dims must be provided. + + Returns + ------- + renamed : Coordinates + Coordinates object with renamed dimensions. + """ + return self.to_dataset().rename_dims(dims_dict, **dims).coords + + def rename_vars( + self, + name_dict: Mapping[Any, Hashable] | None = None, + **names: Hashable, + ) -> Self: + """Returns a new object with renamed variables including coordinates + + Parameters + ---------- + name_dict : dict-like, optional + Dictionary whose keys are current variable or coordinate names and + whose values are the desired names. + **names : optional + Keyword form of ``name_dict``. + One of name_dict or names must be provided. + + Returns + ------- + renamed : Dataset + Dataset with renamed variables including coordinates + """ + return self.to_dataset().rename_vars(name_dict, **names) + class DatasetCoordinates(Coordinates): """Dictionary like container for Dataset coordinates (variables + indexes). From 8a18a52897483de3d821ef55d2ff7a09a4e8b5ac Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Tue, 13 May 2025 18:03:51 +0200 Subject: [PATCH 02/16] allow using the binary-or operator (`|`) for merging --- xarray/core/coordinates.py | 25 +++++++++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py index c6c9eb0d15a..e2008687b24 100644 --- a/xarray/core/coordinates.py +++ b/xarray/core/coordinates.py @@ -561,6 +561,31 @@ def merge(self, other: Mapping[Any, Any] | None) -> Dataset: variables=coords, coord_names=coord_names, indexes=indexes ) + def __or__(self, other: Self) -> Self: + """Merge two sets of coordinates to create a new Coordinates object + + The method implements the logic used for joining coordinates in the + result of a binary operation performed on xarray objects: + + - If two index coordinates conflict (are not equal), an exception is + raised. You must align your data before passing it to this method. + - If an index coordinate and a non-index coordinate conflict, the non- + index coordinate is dropped. + - If two non-index coordinates conflict, both are dropped. + + Parameters + ---------- + other : dict-like, optional + A :py:class:`Coordinates` object or any mapping that can be turned + into coordinates. + + Returns + ------- + merged : Coordinates + A new Coordinates object with merged coordinates. + """ + return self.merge(other).coords + def __setitem__(self, key: Hashable, value: Any) -> None: self.update({key: value}) From f8b7f57548008fea467788fa45e468b399451416 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Tue, 13 May 2025 18:09:34 +0200 Subject: [PATCH 03/16] tests for `drop_vars` --- xarray/tests/test_coordinates.py | 16 ++++++++++++++++ 1 file changed, 16 insertions(+) diff --git a/xarray/tests/test_coordinates.py b/xarray/tests/test_coordinates.py index b4ba922203a..d1e07dca12e 100644 --- a/xarray/tests/test_coordinates.py +++ b/xarray/tests/test_coordinates.py @@ -208,3 +208,19 @@ def test_dataset_from_coords_with_multidim_var_same_name(self): coords = Coordinates(coords={"x": var}, indexes={}) ds = Dataset(coords=coords) assert ds.coords["x"].dims == ("x", "y") + + def test_drop_vars(self): + coords = Coordinates( + coords={ + "x": Variable("x", range(3)), + "y": Variable("y", list("ab")), + "a": Variable(["x", "y"], np.arange(6).reshape(3, 2)), + }, + indexes={}, + ) + + actual = coords.drop_vars("x") + assert set(actual.variables) == {"a", "y"} + + actual = coords.drop_vars(["x", "y"]) + assert set(actual.variables) == {"a"} From 4626ce5a6e0f7e88f73543598feb347a0838ad04 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Tue, 13 May 2025 18:36:58 +0200 Subject: [PATCH 04/16] tests for `rename_dims` and `rename_vars` --- xarray/tests/test_coordinates.py | 36 ++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/xarray/tests/test_coordinates.py b/xarray/tests/test_coordinates.py index d1e07dca12e..def2235029b 100644 --- a/xarray/tests/test_coordinates.py +++ b/xarray/tests/test_coordinates.py @@ -224,3 +224,39 @@ def test_drop_vars(self): actual = coords.drop_vars(["x", "y"]) assert set(actual.variables) == {"a"} + + def test_rename_dims(self): + coords = Coordinates( + coords={ + "x": Variable("x", range(3)), + "y": Variable("y", list("ab")), + "a": Variable(["x", "y"], np.arange(6).reshape(3, 2)), + }, + indexes={}, + ) + + actual = coords.rename_dims({"x": "X"}) + assert set(actual.dims) == {"X", "y"} + assert set(actual.variables) == {"a", "x", "y"} + + actual = coords.rename_dims({"x": "u", "y": "v"}) + assert set(actual.dims) == {"u", "v"} + assert set(actual.variables) == {"a", "x", "y"} + + def test_rename_vars(self): + coords = Coordinates( + coords={ + "x": Variable("x", range(3)), + "y": Variable("y", list("ab")), + "a": Variable(["x", "y"], np.arange(6).reshape(3, 2)), + }, + indexes={}, + ) + + actual = coords.rename_vars({"x": "X"}) + assert set(actual.dims) == {"x", "y"} + assert set(actual.variables) == {"a", "X", "y"} + + actual = coords.rename_vars({"x": "u", "y": "v"}) + assert set(actual.dims) == {"x", "y"} + assert set(actual.variables) == {"a", "u", "v"} From a370ed91b332fcd196cda2afd27496be040ceec0 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Tue, 13 May 2025 18:39:06 +0200 Subject: [PATCH 05/16] tests for the merge operator --- xarray/tests/test_coordinates.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/xarray/tests/test_coordinates.py b/xarray/tests/test_coordinates.py index def2235029b..3f95acaf005 100644 --- a/xarray/tests/test_coordinates.py +++ b/xarray/tests/test_coordinates.py @@ -260,3 +260,11 @@ def test_rename_vars(self): actual = coords.rename_vars({"x": "u", "y": "v"}) assert set(actual.dims) == {"x", "y"} assert set(actual.variables) == {"a", "u", "v"} + + def test_operator_merge(self): + coords1 = Coordinates({"x": ("x", [0, 1, 2])}) + coords2 = Coordinates({"y": ("y", [3, 4, 5])}) + expected = Dataset(coords={"x": [0, 1, 2], "y": [3, 4, 5]}) + + actual = coords1 | coords2 + assert_identical(Dataset(coords=actual), expected) From c909ca9d991eca59471910580689dfd2759a95fe Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Sat, 28 Jun 2025 23:57:26 +0200 Subject: [PATCH 06/16] Apply suggestions from code review Co-authored-by: Benoit Bovy --- xarray/core/coordinates.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py index e2008687b24..8458a012772 100644 --- a/xarray/core/coordinates.py +++ b/xarray/core/coordinates.py @@ -781,7 +781,7 @@ def rename_dims( dims_dict : dict-like, optional Dictionary whose keys are current dimension names and whose values are the desired names. The desired names must - not be the name of an existing dimension or Variable in the Dataset. + not be the name of an existing dimension or Variable in the Coordinates. **dims : optional Keyword form of ``dims_dict``. One of dims_dict or dims must be provided. @@ -798,7 +798,7 @@ def rename_vars( name_dict: Mapping[Any, Hashable] | None = None, **names: Hashable, ) -> Self: - """Returns a new object with renamed variables including coordinates + """Returns a new object with renamed variables. Parameters ---------- @@ -811,8 +811,8 @@ def rename_vars( Returns ------- - renamed : Dataset - Dataset with renamed variables including coordinates + renamed : Coordinates + Coordinates object with renamed variables """ return self.to_dataset().rename_vars(name_dict, **names) From 22c89e35531d27f9500636aa518d77a3355d2918 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Sun, 29 Jun 2025 10:56:58 +0200 Subject: [PATCH 07/16] attempt to fix the typing --- xarray/core/coordinates.py | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py index 4adcb2324da..fb752be8b4f 100644 --- a/xarray/core/coordinates.py +++ b/xarray/core/coordinates.py @@ -561,7 +561,7 @@ def merge(self, other: Mapping[Any, Any] | None) -> Dataset: variables=coords, coord_names=coord_names, indexes=indexes ) - def __or__(self, other: Self) -> Self: + def __or__(self, other: Mapping[Any, Any] | None) -> Coordinates: """Merge two sets of coordinates to create a new Coordinates object The method implements the logic used for joining coordinates in the @@ -746,7 +746,12 @@ def copy( def drop_vars( self, - names: str | Iterable[Hashable] | Callable[[Self], str | Iterable[Hashable]], + names: str + | Iterable[Hashable] + | Callable[ + [Coordinates | Dataset | DataArray | DataTree], + str | Iterable[Hashable], + ], *, errors: ErrorOptions = "raise", ) -> Self: @@ -767,13 +772,13 @@ def drop_vars( - ``'ignore'``: any given names that are in the dataset are dropped and no error is raised. """ - return self.to_dataset().drop_vars(names, errors=errors).coords + return cast(Self, self.to_dataset().drop_vars(names, errors=errors).coords) def rename_dims( self, dims_dict: Mapping[Any, Hashable] | None = None, **dims: Hashable, - ) -> Self: + ) -> Coordinates: """Returns a new object with renamed dimensions only. Parameters @@ -797,7 +802,7 @@ def rename_vars( self, name_dict: Mapping[Any, Hashable] | None = None, **names: Hashable, - ) -> Self: + ) -> Coordinates: """Returns a new object with renamed variables. Parameters From 3b9e3e545f7caa63207dff0611a9982078fb5afe Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Sun, 29 Jun 2025 10:57:16 +0200 Subject: [PATCH 08/16] make sure we always return a `Coordinates` object --- xarray/core/coordinates.py | 2 +- xarray/tests/test_coordinates.py | 6 ++++++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py index fb752be8b4f..90d4fa93318 100644 --- a/xarray/core/coordinates.py +++ b/xarray/core/coordinates.py @@ -819,7 +819,7 @@ def rename_vars( renamed : Coordinates Coordinates object with renamed variables """ - return self.to_dataset().rename_vars(name_dict, **names) + return self.to_dataset().rename_vars(name_dict, **names).coords class DatasetCoordinates(Coordinates): diff --git a/xarray/tests/test_coordinates.py b/xarray/tests/test_coordinates.py index 3f95acaf005..f8ad096fd10 100644 --- a/xarray/tests/test_coordinates.py +++ b/xarray/tests/test_coordinates.py @@ -220,9 +220,11 @@ def test_drop_vars(self): ) actual = coords.drop_vars("x") + assert isinstance(actual, Coordinates) assert set(actual.variables) == {"a", "y"} actual = coords.drop_vars(["x", "y"]) + assert isinstance(actual, Coordinates) assert set(actual.variables) == {"a"} def test_rename_dims(self): @@ -236,10 +238,12 @@ def test_rename_dims(self): ) actual = coords.rename_dims({"x": "X"}) + assert isinstance(actual, Coordinates) assert set(actual.dims) == {"X", "y"} assert set(actual.variables) == {"a", "x", "y"} actual = coords.rename_dims({"x": "u", "y": "v"}) + assert isinstance(actual, Coordinates) assert set(actual.dims) == {"u", "v"} assert set(actual.variables) == {"a", "x", "y"} @@ -254,10 +258,12 @@ def test_rename_vars(self): ) actual = coords.rename_vars({"x": "X"}) + assert isinstance(actual, Coordinates) assert set(actual.dims) == {"x", "y"} assert set(actual.variables) == {"a", "X", "y"} actual = coords.rename_vars({"x": "u", "y": "v"}) + assert isinstance(actual, Coordinates) assert set(actual.dims) == {"x", "y"} assert set(actual.variables) == {"a", "u", "v"} From e53b84866a7ce59c8c442bbf62751a0649ff3955 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Sun, 29 Jun 2025 10:59:05 +0200 Subject: [PATCH 09/16] replace docstring by a reference to `Coordinates.merge` --- xarray/core/coordinates.py | 22 +++------------------- 1 file changed, 3 insertions(+), 19 deletions(-) diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py index 90d4fa93318..ccb9293b797 100644 --- a/xarray/core/coordinates.py +++ b/xarray/core/coordinates.py @@ -564,25 +564,9 @@ def merge(self, other: Mapping[Any, Any] | None) -> Dataset: def __or__(self, other: Mapping[Any, Any] | None) -> Coordinates: """Merge two sets of coordinates to create a new Coordinates object - The method implements the logic used for joining coordinates in the - result of a binary operation performed on xarray objects: - - - If two index coordinates conflict (are not equal), an exception is - raised. You must align your data before passing it to this method. - - If an index coordinate and a non-index coordinate conflict, the non- - index coordinate is dropped. - - If two non-index coordinates conflict, both are dropped. - - Parameters - ---------- - other : dict-like, optional - A :py:class:`Coordinates` object or any mapping that can be turned - into coordinates. - - Returns - ------- - merged : Coordinates - A new Coordinates object with merged coordinates. + See Also + -------- + Coordinates.merge """ return self.merge(other).coords From 7dbd26a0e1b9fc5b35318ddc6577a924de434f29 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Sun, 29 Jun 2025 11:06:36 +0200 Subject: [PATCH 10/16] changelog --- doc/whats-new.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 6db780484bd..35ec4e26029 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -14,6 +14,8 @@ New Features ~~~~~~~~~~~~ - Expose :py:class:`~xarray.indexes.RangeIndex`, and :py:class:`~xarray.indexes.CoordinateTransformIndex` as public api under the ``xarray.indexes`` namespace. By `Deepak Cherian `_. +- Add convenience methods to :py:class:`~xarray.Coordinates` (:pull:`10318`) + By `Justus Magin `_. Breaking changes From 059512a37dd65f4f7c45e2c53db0f2546fef88f5 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Sun, 29 Jun 2025 11:07:53 +0200 Subject: [PATCH 11/16] create docs pages --- doc/api.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/api.rst b/doc/api.rst index df6e87c0cf8..199dec0ea27 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -954,7 +954,11 @@ Coordinates contents Coordinates.to_index Coordinates.assign Coordinates.merge + Coordinates.__or__ Coordinates.copy + Coordinates.drop_vars + Coordinates.rename_dims + Coordinates.rename_vars Comparisons ----------- From 773f1497f10e4ae0d2dc789e00dbcd7d46460c87 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Sun, 29 Jun 2025 11:09:00 +0200 Subject: [PATCH 12/16] add back the docstring for `__or__` --- xarray/core/coordinates.py | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py index ccb9293b797..3b2448d4c80 100644 --- a/xarray/core/coordinates.py +++ b/xarray/core/coordinates.py @@ -564,6 +564,26 @@ def merge(self, other: Mapping[Any, Any] | None) -> Dataset: def __or__(self, other: Mapping[Any, Any] | None) -> Coordinates: """Merge two sets of coordinates to create a new Coordinates object + The method implements the logic used for joining coordinates in the + result of a binary operation performed on xarray objects: + + - If two index coordinates conflict (are not equal), an exception is + raised. You must align your data before passing it to this method. + - If an index coordinate and a non-index coordinate conflict, the non- + index coordinate is dropped. + - If two non-index coordinates conflict, both are dropped. + + Parameters + ---------- + other : dict-like, optional + A :py:class:`Coordinates` object or any mapping that can be turned + into coordinates. + + Returns + ------- + merged : Coordinates + A new Coordinates object with merged coordinates. + See Also -------- Coordinates.merge From 7bd79136583505f83b6f073debc9487559163371 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Tue, 29 Jul 2025 00:16:52 +0200 Subject: [PATCH 13/16] add `drop_dims` --- xarray/core/coordinates.py | 25 +++++++++++++++++++++++++ xarray/tests/test_coordinates.py | 18 ++++++++++++++++++ 2 files changed, 43 insertions(+) diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py index 3b2448d4c80..261baaf573e 100644 --- a/xarray/core/coordinates.py +++ b/xarray/core/coordinates.py @@ -778,6 +778,31 @@ def drop_vars( """ return cast(Self, self.to_dataset().drop_vars(names, errors=errors).coords) + def drop_dims( + self, + drop_dims: str | Iterable[Hashable], + *, + errors: ErrorOptions = "raise", + ) -> Self: + """Drop dimensions and associated variables from this dataset. + + Parameters + ---------- + drop_dims : str or Iterable of Hashable + Dimension or dimensions to drop. + errors : {"raise", "ignore"}, default: "raise" + If 'raise', raises a ValueError error if any of the + dimensions passed are not in the dataset. If 'ignore', any given + dimensions that are in the dataset are dropped and no error is raised. + + Returns + ------- + obj : Coordinates + Coordinates object without the given dimensions (or any coordinates + containing those dimensions). + """ + return cast(Self, self.to_dataset().drop_dims(drop_dims, errors=errors).coords) + def rename_dims( self, dims_dict: Mapping[Any, Hashable] | None = None, diff --git a/xarray/tests/test_coordinates.py b/xarray/tests/test_coordinates.py index f8ad096fd10..75ed84a7719 100644 --- a/xarray/tests/test_coordinates.py +++ b/xarray/tests/test_coordinates.py @@ -227,6 +227,24 @@ def test_drop_vars(self): assert isinstance(actual, Coordinates) assert set(actual.variables) == {"a"} + def test_drop_dims(self) -> None: + coords = Coordinates( + coords={ + "x": Variable("x", range(3)), + "y": Variable("y", list("ab")), + "a": Variable(["x", "y"], np.arange(6).reshape(3, 2)), + }, + indexes={}, + ) + + actual = coords.drop_dims("x") + assert isinstance(actual, Coordinates) + assert set(actual.variables) == {"y"} + + actual = coords.drop_dims(["x", "y"]) + assert isinstance(actual, Coordinates) + assert set(actual.variables) == set() + def test_rename_dims(self): coords = Coordinates( coords={ From 85d685b88e276acc48321eb2bfb2ee036fbe7aa9 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Tue, 29 Jul 2025 00:17:13 +0200 Subject: [PATCH 14/16] typing --- xarray/core/coordinates.py | 6 +++--- xarray/tests/test_coordinates.py | 6 +++--- 2 files changed, 6 insertions(+), 6 deletions(-) diff --git a/xarray/core/coordinates.py b/xarray/core/coordinates.py index 261baaf573e..69169fe86ac 100644 --- a/xarray/core/coordinates.py +++ b/xarray/core/coordinates.py @@ -807,7 +807,7 @@ def rename_dims( self, dims_dict: Mapping[Any, Hashable] | None = None, **dims: Hashable, - ) -> Coordinates: + ) -> Self: """Returns a new object with renamed dimensions only. Parameters @@ -825,7 +825,7 @@ def rename_dims( renamed : Coordinates Coordinates object with renamed dimensions. """ - return self.to_dataset().rename_dims(dims_dict, **dims).coords + return cast(Self, self.to_dataset().rename_dims(dims_dict, **dims).coords) def rename_vars( self, @@ -848,7 +848,7 @@ def rename_vars( renamed : Coordinates Coordinates object with renamed variables """ - return self.to_dataset().rename_vars(name_dict, **names).coords + return cast(Self, self.to_dataset().rename_vars(name_dict, **names).coords) class DatasetCoordinates(Coordinates): diff --git a/xarray/tests/test_coordinates.py b/xarray/tests/test_coordinates.py index 75ed84a7719..40af670f3cf 100644 --- a/xarray/tests/test_coordinates.py +++ b/xarray/tests/test_coordinates.py @@ -245,7 +245,7 @@ def test_drop_dims(self) -> None: assert isinstance(actual, Coordinates) assert set(actual.variables) == set() - def test_rename_dims(self): + def test_rename_dims(self) -> None: coords = Coordinates( coords={ "x": Variable("x", range(3)), @@ -265,7 +265,7 @@ def test_rename_dims(self): assert set(actual.dims) == {"u", "v"} assert set(actual.variables) == {"a", "x", "y"} - def test_rename_vars(self): + def test_rename_vars(self) -> None: coords = Coordinates( coords={ "x": Variable("x", range(3)), @@ -285,7 +285,7 @@ def test_rename_vars(self): assert set(actual.dims) == {"x", "y"} assert set(actual.variables) == {"a", "u", "v"} - def test_operator_merge(self): + def test_operator_merge(self) -> None: coords1 = Coordinates({"x": ("x", [0, 1, 2])}) coords2 = Coordinates({"y": ("y", [3, 4, 5])}) expected = Dataset(coords={"x": [0, 1, 2], "y": [3, 4, 5]}) From c599d617770075695cbf11ad595eb79f435a97de Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Tue, 29 Jul 2025 00:38:44 +0200 Subject: [PATCH 15/16] undo a bad merge [skip-ci] --- doc/api.rst | 1810 +-------------------------------------------------- 1 file changed, 26 insertions(+), 1784 deletions(-) diff --git a/doc/api.rst b/doc/api.rst index cae2e4b4397..fc862c21e4c 100644 --- a/doc/api.rst +++ b/doc/api.rst @@ -12,1787 +12,29 @@ documentation. See also: :ref:`public-api` and :ref:`api-stability`. -Top-level functions -=================== - -.. autosummary:: - :toctree: generated/ - - apply_ufunc - align - broadcast - concat - merge - combine_by_coords - combine_nested - where - infer_freq - full_like - zeros_like - ones_like - cov - corr - cross - dot - polyval - map_blocks - show_versions - set_options - get_options - unify_chunks - -Dataset -======= - -Creating a dataset ------------------- - -.. autosummary:: - :toctree: generated/ - - Dataset - decode_cf - -Attributes ----------- - -.. autosummary:: - :toctree: generated/ - - Dataset.dims - Dataset.sizes - Dataset.dtypes - Dataset.data_vars - Dataset.coords - Dataset.attrs - Dataset.encoding - Dataset.indexes - Dataset.xindexes - Dataset.chunks - Dataset.chunksizes - Dataset.nbytes - -Dictionary interface --------------------- - -Datasets implement the mapping interface with keys given by variable names -and values given by ``DataArray`` objects. - -.. autosummary:: - :toctree: generated/ - - Dataset.__getitem__ - Dataset.__setitem__ - Dataset.__delitem__ - Dataset.update - Dataset.get - Dataset.items - Dataset.keys - Dataset.values - -Dataset contents ----------------- - -.. autosummary:: - :toctree: generated/ - - Dataset.copy - Dataset.assign - Dataset.assign_coords - Dataset.assign_attrs - Dataset.pipe - Dataset.merge - Dataset.rename - Dataset.rename_vars - Dataset.rename_dims - Dataset.swap_dims - Dataset.expand_dims - Dataset.drop_vars - Dataset.drop_indexes - Dataset.drop_duplicates - Dataset.drop_dims - Dataset.drop_encoding - Dataset.drop_attrs - Dataset.set_coords - Dataset.reset_coords - Dataset.convert_calendar - Dataset.interp_calendar - Dataset.get_index - -Comparisons ------------ - -.. autosummary:: - :toctree: generated/ - - Dataset.equals - Dataset.identical - Dataset.broadcast_equals - -Indexing --------- - -.. autosummary:: - :toctree: generated/ - - Dataset.loc - Dataset.isel - Dataset.sel - Dataset.drop_sel - Dataset.drop_isel - Dataset.head - Dataset.tail - Dataset.thin - Dataset.squeeze - Dataset.interp - Dataset.interp_like - Dataset.reindex - Dataset.reindex_like - Dataset.set_index - Dataset.reset_index - Dataset.set_xindex - Dataset.reorder_levels - Dataset.query - -Missing value handling ----------------------- - -.. autosummary:: - :toctree: generated/ - - Dataset.isnull - Dataset.notnull - Dataset.combine_first - Dataset.count - Dataset.dropna - Dataset.fillna - Dataset.ffill - Dataset.bfill - Dataset.interpolate_na - Dataset.where - Dataset.isin - -Computation ------------ - -.. autosummary:: - :toctree: generated/ - - Dataset.map - Dataset.reduce - Dataset.groupby - Dataset.groupby_bins - Dataset.rolling - Dataset.rolling_exp - Dataset.cumulative - Dataset.weighted - Dataset.coarsen - Dataset.resample - Dataset.diff - Dataset.quantile - Dataset.differentiate - Dataset.integrate - Dataset.map_blocks - Dataset.polyfit - Dataset.curvefit - Dataset.eval - -Aggregation ------------ - -.. autosummary:: - :toctree: generated/ - - Dataset.all - Dataset.any - Dataset.argmax - Dataset.argmin - Dataset.count - Dataset.idxmax - Dataset.idxmin - Dataset.max - Dataset.min - Dataset.mean - Dataset.median - Dataset.prod - Dataset.sum - Dataset.std - Dataset.var - Dataset.cumsum - Dataset.cumprod - -ndarray methods ---------------- - -.. autosummary:: - :toctree: generated/ - - Dataset.argsort - Dataset.astype - Dataset.clip - Dataset.conj - Dataset.conjugate - Dataset.imag - Dataset.round - Dataset.real - Dataset.rank - -Reshaping and reorganizing --------------------------- - -.. autosummary:: - :toctree: generated/ - - Dataset.transpose - Dataset.stack - Dataset.unstack - Dataset.to_stacked_array - Dataset.shift - Dataset.roll - Dataset.pad - Dataset.sortby - Dataset.broadcast_like - -DataArray -========= - -.. autosummary:: - :toctree: generated/ - - DataArray - -Attributes ----------- - -.. autosummary:: - :toctree: generated/ - - DataArray.values - DataArray.data - DataArray.coords - DataArray.dims - DataArray.sizes - DataArray.name - DataArray.attrs - DataArray.encoding - DataArray.indexes - DataArray.xindexes - DataArray.chunksizes - -ndarray attributes ------------------- - -.. autosummary:: - :toctree: generated/ - - DataArray.ndim - DataArray.nbytes - DataArray.shape - DataArray.size - DataArray.dtype - DataArray.chunks - - -DataArray contents ------------------- - -.. autosummary:: - :toctree: generated/ - - DataArray.assign_coords - DataArray.assign_attrs - DataArray.pipe - DataArray.rename - DataArray.swap_dims - DataArray.expand_dims - DataArray.drop_vars - DataArray.drop_indexes - DataArray.drop_duplicates - DataArray.drop_encoding - DataArray.drop_attrs - DataArray.reset_coords - DataArray.copy - DataArray.convert_calendar - DataArray.interp_calendar - DataArray.get_index - DataArray.astype - DataArray.item - -Indexing --------- - -.. autosummary:: - :toctree: generated/ - - DataArray.__getitem__ - DataArray.__setitem__ - DataArray.loc - DataArray.isel - DataArray.sel - DataArray.drop_sel - DataArray.drop_isel - DataArray.head - DataArray.tail - DataArray.thin - DataArray.squeeze - DataArray.interp - DataArray.interp_like - DataArray.reindex - DataArray.reindex_like - DataArray.set_index - DataArray.reset_index - DataArray.set_xindex - DataArray.reorder_levels - DataArray.query - -Missing value handling ----------------------- - -.. autosummary:: - :toctree: generated/ - - DataArray.isnull - DataArray.notnull - DataArray.combine_first - DataArray.count - DataArray.dropna - DataArray.fillna - DataArray.ffill - DataArray.bfill - DataArray.interpolate_na - DataArray.where - DataArray.isin - -Comparisons ------------ - -.. autosummary:: - :toctree: generated/ - - DataArray.equals - DataArray.identical - DataArray.broadcast_equals - -Computation ------------ - -.. autosummary:: - :toctree: generated/ - - DataArray.reduce - DataArray.groupby - DataArray.groupby_bins - DataArray.rolling - DataArray.rolling_exp - DataArray.cumulative - DataArray.weighted - DataArray.coarsen - DataArray.resample - DataArray.get_axis_num - DataArray.diff - DataArray.dot - DataArray.quantile - DataArray.differentiate - DataArray.integrate - DataArray.polyfit - DataArray.map_blocks - DataArray.curvefit - -Aggregation ------------ - -.. autosummary:: - :toctree: generated/ - - DataArray.all - DataArray.any - DataArray.argmax - DataArray.argmin - DataArray.count - DataArray.idxmax - DataArray.idxmin - DataArray.max - DataArray.min - DataArray.mean - DataArray.median - DataArray.prod - DataArray.sum - DataArray.std - DataArray.var - DataArray.cumsum - DataArray.cumprod - -ndarray methods ---------------- - -.. autosummary:: - :toctree: generated/ - - DataArray.argsort - DataArray.clip - DataArray.conj - DataArray.conjugate - DataArray.imag - DataArray.searchsorted - DataArray.round - DataArray.real - DataArray.T - DataArray.rank - - -String manipulation -------------------- - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor.rst - - DataArray.str - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor_method.rst - - DataArray.str.capitalize - DataArray.str.casefold - DataArray.str.cat - DataArray.str.center - DataArray.str.contains - DataArray.str.count - DataArray.str.decode - DataArray.str.encode - DataArray.str.endswith - DataArray.str.extract - DataArray.str.extractall - DataArray.str.find - DataArray.str.findall - DataArray.str.format - DataArray.str.get - DataArray.str.get_dummies - DataArray.str.index - DataArray.str.isalnum - DataArray.str.isalpha - DataArray.str.isdecimal - DataArray.str.isdigit - DataArray.str.islower - DataArray.str.isnumeric - DataArray.str.isspace - DataArray.str.istitle - DataArray.str.isupper - DataArray.str.join - DataArray.str.len - DataArray.str.ljust - DataArray.str.lower - DataArray.str.lstrip - DataArray.str.match - DataArray.str.normalize - DataArray.str.pad - DataArray.str.partition - DataArray.str.repeat - DataArray.str.replace - DataArray.str.rfind - DataArray.str.rindex - DataArray.str.rjust - DataArray.str.rpartition - DataArray.str.rsplit - DataArray.str.rstrip - DataArray.str.slice - DataArray.str.slice_replace - DataArray.str.split - DataArray.str.startswith - DataArray.str.strip - DataArray.str.swapcase - DataArray.str.title - DataArray.str.translate - DataArray.str.upper - DataArray.str.wrap - DataArray.str.zfill - -Datetimelike properties ------------------------ - -**Datetime properties**: - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor_attribute.rst - - DataArray.dt.year - DataArray.dt.month - DataArray.dt.day - DataArray.dt.hour - DataArray.dt.minute - DataArray.dt.second - DataArray.dt.microsecond - DataArray.dt.nanosecond - DataArray.dt.dayofweek - DataArray.dt.weekday - DataArray.dt.dayofyear - DataArray.dt.quarter - DataArray.dt.days_in_month - DataArray.dt.daysinmonth - DataArray.dt.days_in_year - DataArray.dt.season - DataArray.dt.time - DataArray.dt.date - DataArray.dt.decimal_year - DataArray.dt.calendar - DataArray.dt.is_month_start - DataArray.dt.is_month_end - DataArray.dt.is_quarter_end - DataArray.dt.is_year_start - DataArray.dt.is_leap_year - -**Datetime methods**: - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor_method.rst - - DataArray.dt.floor - DataArray.dt.ceil - DataArray.dt.isocalendar - DataArray.dt.round - DataArray.dt.strftime - -**Timedelta properties**: - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor_attribute.rst - - DataArray.dt.days - DataArray.dt.seconds - DataArray.dt.microseconds - DataArray.dt.nanoseconds - DataArray.dt.total_seconds - -**Timedelta methods**: - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor_method.rst - - DataArray.dt.floor - DataArray.dt.ceil - DataArray.dt.round - - -Reshaping and reorganizing --------------------------- - -.. autosummary:: - :toctree: generated/ - - DataArray.transpose - DataArray.stack - DataArray.unstack - DataArray.to_unstacked_dataset - DataArray.shift - DataArray.roll - DataArray.pad - DataArray.sortby - DataArray.broadcast_like - -DataTree -======== - -Creating a DataTree -------------------- - -Methods of creating a ``DataTree``. - -.. autosummary:: - :toctree: generated/ - - DataTree - DataTree.from_dict - -Tree Attributes ---------------- - -Attributes relating to the recursive tree-like structure of a ``DataTree``. - -.. autosummary:: - :toctree: generated/ - - DataTree.parent - DataTree.children - DataTree.name - DataTree.path - DataTree.root - DataTree.is_root - DataTree.is_leaf - DataTree.leaves - DataTree.level - DataTree.depth - DataTree.width - DataTree.subtree - DataTree.subtree_with_keys - DataTree.descendants - DataTree.siblings - DataTree.lineage - DataTree.parents - DataTree.ancestors - DataTree.groups - DataTree.xindexes - -Data Contents -------------- - -Interface to the data objects (optionally) stored inside a single ``DataTree`` node. -This interface echoes that of ``xarray.Dataset``. - -.. autosummary:: - :toctree: generated/ - - DataTree.dims - DataTree.sizes - DataTree.data_vars - DataTree.ds - DataTree.coords - DataTree.attrs - DataTree.encoding - DataTree.indexes - DataTree.nbytes - DataTree.dataset - DataTree.to_dataset - DataTree.has_data - DataTree.has_attrs - DataTree.is_empty - DataTree.is_hollow - DataTree.chunksizes - -Dictionary Interface --------------------- - -``DataTree`` objects also have a dict-like interface mapping keys to either ``xarray.DataArray``\s or to child ``DataTree`` nodes. - -.. autosummary:: - :toctree: generated/ - - DataTree.__getitem__ - DataTree.__setitem__ - DataTree.__delitem__ - DataTree.update - DataTree.get - DataTree.items - DataTree.keys - DataTree.values - -Tree Manipulation ------------------ - -For manipulating, traversing, navigating, or mapping over the tree structure. - -.. autosummary:: - :toctree: generated/ - - DataTree.orphan - DataTree.same_tree - DataTree.relative_to - DataTree.iter_lineage - DataTree.find_common_ancestor - DataTree.map_over_datasets - DataTree.pipe - DataTree.match - DataTree.filter - DataTree.filter_like - -Pathlib-like Interface ----------------------- - -``DataTree`` objects deliberately echo some of the API of :py:class:`pathlib.PurePath`. - -.. autosummary:: - :toctree: generated/ - - DataTree.name - DataTree.parent - DataTree.parents - DataTree.relative_to - -.. Missing: - -.. .. - -.. ``DataTree.glob`` -.. ``DataTree.joinpath`` -.. ``DataTree.with_name`` -.. ``DataTree.walk`` -.. ``DataTree.rename`` -.. ``DataTree.replace`` - -DataTree Contents ------------------ - -Manipulate the contents of all nodes in a ``DataTree`` simultaneously. - -.. autosummary:: - :toctree: generated/ - - DataTree.copy - - .. DataTree.assign_coords - .. DataTree.merge - .. DataTree.rename - .. DataTree.rename_vars - .. DataTree.rename_dims - .. DataTree.swap_dims - .. DataTree.expand_dims - .. DataTree.drop_vars - .. DataTree.drop_dims - .. DataTree.set_coords - .. DataTree.reset_coords - -DataTree Node Contents ----------------------- - -Manipulate the contents of a single ``DataTree`` node. - -.. autosummary:: - :toctree: generated/ - - DataTree.assign - DataTree.drop_nodes - -DataTree Operations -------------------- - -Apply operations over multiple ``DataTree`` objects. - -.. autosummary:: - :toctree: generated/ - - map_over_datasets - group_subtrees - -Comparisons ------------ - -Compare one ``DataTree`` object to another. - -.. autosummary:: - :toctree: generated/ - - DataTree.isomorphic - DataTree.equals - DataTree.identical - -Indexing --------- - -Index into all nodes in the subtree simultaneously. - -.. autosummary:: - :toctree: generated/ - - DataTree.isel - DataTree.sel - -.. DataTree.drop_sel -.. DataTree.drop_isel -.. DataTree.head -.. DataTree.tail -.. DataTree.thin -.. DataTree.squeeze -.. DataTree.interp -.. DataTree.interp_like -.. DataTree.reindex -.. DataTree.reindex_like -.. DataTree.set_index -.. DataTree.reset_index -.. DataTree.reorder_levels -.. DataTree.query - -.. .. - -.. Missing: -.. ``DataTree.loc`` - - -.. Missing Value Handling -.. ---------------------- - -.. .. autosummary:: -.. :toctree: generated/ - -.. DataTree.isnull -.. DataTree.notnull -.. DataTree.combine_first -.. DataTree.dropna -.. DataTree.fillna -.. DataTree.ffill -.. DataTree.bfill -.. DataTree.interpolate_na -.. DataTree.where -.. DataTree.isin - -.. Computation -.. ----------- - -.. Apply a computation to the data in all nodes in the subtree simultaneously. - -.. .. autosummary:: -.. :toctree: generated/ - -.. DataTree.map -.. DataTree.reduce -.. DataTree.diff -.. DataTree.quantile -.. DataTree.differentiate -.. DataTree.integrate -.. DataTree.map_blocks -.. DataTree.polyfit -.. DataTree.curvefit - -Aggregation ------------ - -Aggregate data in all nodes in the subtree simultaneously. - -.. autosummary:: - :toctree: generated/ - - DataTree.all - DataTree.any - DataTree.max - DataTree.min - DataTree.mean - DataTree.median - DataTree.prod - DataTree.sum - DataTree.std - DataTree.var - DataTree.cumsum - DataTree.cumprod - -ndarray methods ---------------- - -Methods copied from :py:class:`numpy.ndarray` objects, here applying to the data in all nodes in the subtree. - -.. autosummary:: - :toctree: generated/ - - DataTree.argsort - DataTree.conj - DataTree.conjugate - DataTree.round -.. DataTree.astype -.. DataTree.clip -.. DataTree.rank - -.. Reshaping and reorganising -.. -------------------------- - -.. Reshape or reorganise the data in all nodes in the subtree. - -.. .. autosummary:: -.. :toctree: generated/ - -.. DataTree.transpose -.. DataTree.stack -.. DataTree.unstack -.. DataTree.shift -.. DataTree.roll -.. DataTree.pad -.. DataTree.sortby -.. DataTree.broadcast_like - -Coordinates -=========== - -Creating coordinates --------------------- - -.. autosummary:: - :toctree: generated/ - - Coordinates - Coordinates.from_xindex - Coordinates.from_pandas_multiindex - -Attributes ----------- - -.. autosummary:: - :toctree: generated/ - - Coordinates.dims - Coordinates.sizes - Coordinates.dtypes - Coordinates.variables - Coordinates.indexes - Coordinates.xindexes - -Dictionary Interface --------------------- - -Coordinates implement the mapping interface with keys given by variable names -and values given by ``DataArray`` objects. - -.. autosummary:: - :toctree: generated/ - - Coordinates.__getitem__ - Coordinates.__setitem__ - Coordinates.__delitem__ - Coordinates.update - Coordinates.get - Coordinates.items - Coordinates.keys - Coordinates.values - -Coordinates contents --------------------- - -.. autosummary:: - :toctree: generated/ - - Coordinates.to_dataset - Coordinates.to_index - Coordinates.assign - Coordinates.merge - Coordinates.__or__ - Coordinates.copy - Coordinates.drop_vars - Coordinates.rename_dims - Coordinates.rename_vars - -Comparisons ------------ - -.. autosummary:: - :toctree: generated/ - - Coordinates.equals - Coordinates.identical - -Proxies -------- - -Coordinates that are accessed from the ``coords`` property of Dataset, DataArray -and DataTree objects, respectively. - -.. autosummary:: - :toctree: generated/ - - core.coordinates.DatasetCoordinates - core.coordinates.DataArrayCoordinates - core.coordinates.DataTreeCoordinates - -Indexes -======= - -Default, pandas-backed indexes built-in to Xarray: - -.. autosummary:: - :toctree: generated/ - - indexes.PandasIndex - indexes.PandasMultiIndex - - -More complex indexes built-in to Xarray: - -.. autosummary:: - :toctree: generated/ - - CFTimeIndex - indexes.RangeIndex - indexes.NDPointIndex - - -Creating indexes ----------------- -.. autosummary:: - :toctree: generated/ - - cftime_range - date_range - date_range_like - indexes.RangeIndex.arange - indexes.RangeIndex.linspace - - -Universal functions -=================== - -These functions are equivalent to their NumPy versions, but for xarray -objects backed by non-NumPy array types (e.g. ``cupy``, ``sparse``, or ``jax``), -they will ensure that the computation is dispatched to the appropriate -backend. You can find them in the ``xarray.ufuncs`` module: - -.. autosummary:: - :toctree: generated/ - - ufuncs.abs - ufuncs.absolute - ufuncs.acos - ufuncs.acosh - ufuncs.arccos - ufuncs.arccosh - ufuncs.arcsin - ufuncs.arcsinh - ufuncs.arctan - ufuncs.arctanh - ufuncs.asin - ufuncs.asinh - ufuncs.atan - ufuncs.atanh - ufuncs.bitwise_count - ufuncs.bitwise_invert - ufuncs.bitwise_not - ufuncs.cbrt - ufuncs.ceil - ufuncs.conj - ufuncs.conjugate - ufuncs.cos - ufuncs.cosh - ufuncs.deg2rad - ufuncs.degrees - ufuncs.exp - ufuncs.exp2 - ufuncs.expm1 - ufuncs.fabs - ufuncs.floor - ufuncs.invert - ufuncs.isfinite - ufuncs.isinf - ufuncs.isnan - ufuncs.isnat - ufuncs.log - ufuncs.log10 - ufuncs.log1p - ufuncs.log2 - ufuncs.logical_not - ufuncs.negative - ufuncs.positive - ufuncs.rad2deg - ufuncs.radians - ufuncs.reciprocal - ufuncs.rint - ufuncs.sign - ufuncs.signbit - ufuncs.sin - ufuncs.sinh - ufuncs.spacing - ufuncs.sqrt - ufuncs.square - ufuncs.tan - ufuncs.tanh - ufuncs.trunc - ufuncs.add - ufuncs.arctan2 - ufuncs.atan2 - ufuncs.bitwise_and - ufuncs.bitwise_left_shift - ufuncs.bitwise_or - ufuncs.bitwise_right_shift - ufuncs.bitwise_xor - ufuncs.copysign - ufuncs.divide - ufuncs.equal - ufuncs.float_power - ufuncs.floor_divide - ufuncs.fmax - ufuncs.fmin - ufuncs.fmod - ufuncs.gcd - ufuncs.greater - ufuncs.greater_equal - ufuncs.heaviside - ufuncs.hypot - ufuncs.lcm - ufuncs.ldexp - ufuncs.left_shift - ufuncs.less - ufuncs.less_equal - ufuncs.logaddexp - ufuncs.logaddexp2 - ufuncs.logical_and - ufuncs.logical_or - ufuncs.logical_xor - ufuncs.maximum - ufuncs.minimum - ufuncs.mod - ufuncs.multiply - ufuncs.nextafter - ufuncs.not_equal - ufuncs.pow - ufuncs.power - ufuncs.remainder - ufuncs.right_shift - ufuncs.subtract - ufuncs.true_divide - ufuncs.angle - ufuncs.isreal - ufuncs.iscomplex - -IO / Conversion -=============== - -Dataset methods ---------------- - -.. autosummary:: - :toctree: generated/ - - load_dataset - open_dataset - open_mfdataset - open_zarr - save_mfdataset - Dataset.as_numpy - Dataset.from_dataframe - Dataset.from_dict - Dataset.to_dataarray - Dataset.to_dataframe - Dataset.to_dask_dataframe - Dataset.to_dict - Dataset.to_netcdf - Dataset.to_pandas - Dataset.to_zarr - Dataset.chunk - Dataset.close - Dataset.compute - Dataset.filter_by_attrs - Dataset.info - Dataset.load - Dataset.persist - Dataset.unify_chunks - -DataArray methods ------------------ - -.. autosummary:: - :toctree: generated/ - - load_dataarray - open_dataarray - DataArray.as_numpy - DataArray.from_dict - DataArray.from_iris - DataArray.from_series - DataArray.to_dask_dataframe - DataArray.to_dataframe - DataArray.to_dataset - DataArray.to_dict - DataArray.to_index - DataArray.to_iris - DataArray.to_masked_array - DataArray.to_netcdf - DataArray.to_numpy - DataArray.to_pandas - DataArray.to_series - DataArray.to_zarr - DataArray.chunk - DataArray.close - DataArray.compute - DataArray.persist - DataArray.load - DataArray.unify_chunks - -DataTree methods ----------------- - -.. autosummary:: - :toctree: generated/ - - open_datatree - open_groups - DataTree.to_dict - DataTree.to_netcdf - DataTree.to_zarr - DataTree.chunk - DataTree.load - DataTree.compute - DataTree.persist - -.. .. - -.. Missing: -.. ``open_mfdatatree`` - -Encoding/Decoding -================= - -Coder objects -------------- - -.. autosummary:: - :toctree: generated/ - - coders.CFDatetimeCoder - -Plotting -======== - -Dataset -------- - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor_method.rst - - Dataset.plot.scatter - Dataset.plot.quiver - Dataset.plot.streamplot - -DataArray ---------- - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor_callable.rst - - DataArray.plot - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor_method.rst - - DataArray.plot.contourf - DataArray.plot.contour - DataArray.plot.hist - DataArray.plot.imshow - DataArray.plot.line - DataArray.plot.pcolormesh - DataArray.plot.step - DataArray.plot.scatter - DataArray.plot.surface - - -Faceting --------- -.. autosummary:: - :toctree: generated/ - - plot.FacetGrid - plot.FacetGrid.add_colorbar - plot.FacetGrid.add_legend - plot.FacetGrid.add_quiverkey - plot.FacetGrid.map - plot.FacetGrid.map_dataarray - plot.FacetGrid.map_dataarray_line - plot.FacetGrid.map_dataset - plot.FacetGrid.map_plot1d - plot.FacetGrid.set_axis_labels - plot.FacetGrid.set_ticks - plot.FacetGrid.set_titles - plot.FacetGrid.set_xlabels - plot.FacetGrid.set_ylabels - - - -GroupBy objects -=============== - -.. currentmodule:: xarray.core.groupby - -Dataset -------- - -.. autosummary:: - :toctree: generated/ - - DatasetGroupBy - DatasetGroupBy.map - DatasetGroupBy.reduce - DatasetGroupBy.assign - DatasetGroupBy.assign_coords - DatasetGroupBy.first - DatasetGroupBy.last - DatasetGroupBy.fillna - DatasetGroupBy.quantile - DatasetGroupBy.where - DatasetGroupBy.all - DatasetGroupBy.any - DatasetGroupBy.count - DatasetGroupBy.cumsum - DatasetGroupBy.cumprod - DatasetGroupBy.max - DatasetGroupBy.mean - DatasetGroupBy.median - DatasetGroupBy.min - DatasetGroupBy.prod - DatasetGroupBy.std - DatasetGroupBy.sum - DatasetGroupBy.var - DatasetGroupBy.dims - DatasetGroupBy.groups - DatasetGroupBy.shuffle_to_chunks - -DataArray ---------- - -.. autosummary:: - :toctree: generated/ - - DataArrayGroupBy - DataArrayGroupBy.map - DataArrayGroupBy.reduce - DataArrayGroupBy.assign_coords - DataArrayGroupBy.first - DataArrayGroupBy.last - DataArrayGroupBy.fillna - DataArrayGroupBy.quantile - DataArrayGroupBy.where - DataArrayGroupBy.all - DataArrayGroupBy.any - DataArrayGroupBy.count - DataArrayGroupBy.cumsum - DataArrayGroupBy.cumprod - DataArrayGroupBy.max - DataArrayGroupBy.mean - DataArrayGroupBy.median - DataArrayGroupBy.min - DataArrayGroupBy.prod - DataArrayGroupBy.std - DataArrayGroupBy.sum - DataArrayGroupBy.var - DataArrayGroupBy.dims - DataArrayGroupBy.groups - DataArrayGroupBy.shuffle_to_chunks - -Grouper Objects ---------------- - -.. currentmodule:: xarray - -.. autosummary:: - :toctree: generated/ - - groupers.BinGrouper - groupers.UniqueGrouper - groupers.TimeResampler - groupers.SeasonGrouper - groupers.SeasonResampler - - -Rolling objects -=============== - -.. currentmodule:: xarray.computation.rolling - -Dataset -------- - -.. autosummary:: - :toctree: generated/ - - DatasetRolling - DatasetRolling.construct - DatasetRolling.reduce - DatasetRolling.argmax - DatasetRolling.argmin - DatasetRolling.count - DatasetRolling.max - DatasetRolling.mean - DatasetRolling.median - DatasetRolling.min - DatasetRolling.prod - DatasetRolling.std - DatasetRolling.sum - DatasetRolling.var - -DataArray ---------- - -.. autosummary:: - :toctree: generated/ - - DataArrayRolling - DataArrayRolling.__iter__ - DataArrayRolling.construct - DataArrayRolling.reduce - DataArrayRolling.argmax - DataArrayRolling.argmin - DataArrayRolling.count - DataArrayRolling.max - DataArrayRolling.mean - DataArrayRolling.median - DataArrayRolling.min - DataArrayRolling.prod - DataArrayRolling.std - DataArrayRolling.sum - DataArrayRolling.var - -Coarsen objects -=============== - -Dataset -------- - -.. autosummary:: - :toctree: generated/ - - DatasetCoarsen - DatasetCoarsen.all - DatasetCoarsen.any - DatasetCoarsen.construct - DatasetCoarsen.count - DatasetCoarsen.max - DatasetCoarsen.mean - DatasetCoarsen.median - DatasetCoarsen.min - DatasetCoarsen.prod - DatasetCoarsen.reduce - DatasetCoarsen.std - DatasetCoarsen.sum - DatasetCoarsen.var - -DataArray ---------- - -.. autosummary:: - :toctree: generated/ - - DataArrayCoarsen - DataArrayCoarsen.all - DataArrayCoarsen.any - DataArrayCoarsen.construct - DataArrayCoarsen.count - DataArrayCoarsen.max - DataArrayCoarsen.mean - DataArrayCoarsen.median - DataArrayCoarsen.min - DataArrayCoarsen.prod - DataArrayCoarsen.reduce - DataArrayCoarsen.std - DataArrayCoarsen.sum - DataArrayCoarsen.var - -Exponential rolling objects -=========================== - -.. currentmodule:: xarray.computation.rolling_exp - -.. autosummary:: - :toctree: generated/ - - RollingExp - RollingExp.mean - RollingExp.sum - -Weighted objects -================ - -.. currentmodule:: xarray.computation.weighted - -Dataset -------- - -.. autosummary:: - :toctree: generated/ - - DatasetWeighted - DatasetWeighted.mean - DatasetWeighted.quantile - DatasetWeighted.sum - DatasetWeighted.std - DatasetWeighted.var - DatasetWeighted.sum_of_weights - DatasetWeighted.sum_of_squares - -DataArray ---------- - -.. autosummary:: - :toctree: generated/ - - DataArrayWeighted - DataArrayWeighted.mean - DataArrayWeighted.quantile - DataArrayWeighted.sum - DataArrayWeighted.std - DataArrayWeighted.var - DataArrayWeighted.sum_of_weights - DataArrayWeighted.sum_of_squares - -Resample objects -================ - -.. currentmodule:: xarray.core.resample - -Dataset -------- - -.. autosummary:: - :toctree: generated/ - - DatasetResample - DatasetResample.asfreq - DatasetResample.backfill - DatasetResample.interpolate - DatasetResample.nearest - DatasetResample.pad - DatasetResample.all - DatasetResample.any - DatasetResample.apply - DatasetResample.assign - DatasetResample.assign_coords - DatasetResample.bfill - DatasetResample.count - DatasetResample.ffill - DatasetResample.fillna - DatasetResample.first - DatasetResample.last - DatasetResample.map - DatasetResample.max - DatasetResample.mean - DatasetResample.median - DatasetResample.min - DatasetResample.prod - DatasetResample.quantile - DatasetResample.reduce - DatasetResample.std - DatasetResample.sum - DatasetResample.var - DatasetResample.where - DatasetResample.dims - DatasetResample.groups - - -DataArray ---------- - -.. autosummary:: - :toctree: generated/ - - DataArrayResample - DataArrayResample.asfreq - DataArrayResample.backfill - DataArrayResample.interpolate - DataArrayResample.nearest - DataArrayResample.pad - DataArrayResample.all - DataArrayResample.any - DataArrayResample.apply - DataArrayResample.assign_coords - DataArrayResample.bfill - DataArrayResample.count - DataArrayResample.ffill - DataArrayResample.fillna - DataArrayResample.first - DataArrayResample.last - DataArrayResample.map - DataArrayResample.max - DataArrayResample.mean - DataArrayResample.median - DataArrayResample.min - DataArrayResample.prod - DataArrayResample.quantile - DataArrayResample.reduce - DataArrayResample.std - DataArrayResample.sum - DataArrayResample.var - DataArrayResample.where - DataArrayResample.dims - DataArrayResample.groups - -Accessors -========= - -.. currentmodule:: xarray.core - -.. autosummary:: - :toctree: generated/ - - accessor_dt.DatetimeAccessor - accessor_dt.TimedeltaAccessor - accessor_str.StringAccessor - - -Custom Indexes -============== -.. currentmodule:: xarray - -Building custom indexes ------------------------ - -These classes are building blocks for more complex Indexes: - -.. autosummary:: - :toctree: generated/ - - indexes.CoordinateTransform - indexes.CoordinateTransformIndex - indexes.NDPointIndex - indexes.TreeAdapter - -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 - - -Tutorial -======== - -.. autosummary:: - :toctree: generated/ - - tutorial.open_dataset - tutorial.load_dataset - tutorial.open_datatree - tutorial.load_datatree - -Testing -======= - -.. autosummary:: - :toctree: generated/ - - testing.assert_equal - testing.assert_identical - testing.assert_allclose - testing.assert_chunks_equal - -Test that two ``DataTree`` objects are similar. - -.. autosummary:: - :toctree: generated/ - - testing.assert_isomorphic - testing.assert_equal - testing.assert_identical - -Hypothesis Testing Strategies -============================= - -.. currentmodule:: xarray - -See the :ref:`documentation page on testing ` for a guide on how to use these strategies. - -.. warning:: - These strategies should be considered highly experimental, and liable to change at any time. - -.. autosummary:: - :toctree: generated/ - - testing.strategies.supported_dtypes - testing.strategies.names - testing.strategies.dimension_names - testing.strategies.dimension_sizes - testing.strategies.attrs - testing.strategies.variables - testing.strategies.unique_subset_of - -Exceptions -========== - -.. autosummary:: - :toctree: generated/ - - AlignmentError - CoordinateValidationError - MergeError - SerializationWarning - -DataTree --------- - -Exceptions raised when manipulating trees. - -.. autosummary:: - :toctree: generated/ - - TreeIsomorphismError - InvalidTreeError - NotFoundInTreeError - -Advanced API -============ - -.. autosummary:: - :toctree: generated/ - - Coordinates - Dataset.variables - DataArray.variable - DataTree.variables - Variable - IndexVariable - as_variable - Index - IndexSelResult - Context - register_dataset_accessor - register_dataarray_accessor - register_datatree_accessor - Dataset.set_close - backends.BackendArray - backends.BackendEntrypoint - backends.list_engines - backends.refresh_engines - -.. .. - -.. Missing: -.. ``DataTree.set_close`` - -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: - -.. autosummary:: - :toctree: generated/ - - backends.NetCDF4DataStore - backends.H5NetCDFStore - backends.PydapDataStore - backends.ScipyDataStore - backends.ZarrStore - backends.FileManager - backends.CachingFileManager - backends.DummyFileManager - -These BackendEntrypoints provide a basic interface to the most commonly -used filetypes in the xarray universe. - -.. autosummary:: - :toctree: generated/ - - backends.NetCDF4BackendEntrypoint - backends.H5netcdfBackendEntrypoint - backends.PydapBackendEntrypoint - backends.ScipyBackendEntrypoint - backends.StoreBackendEntrypoint - backends.ZarrBackendEntrypoint - -Deprecated / Pending Deprecation -================================ - -.. autosummary:: - :toctree: generated/ - - Dataset.drop - DataArray.drop - Dataset.apply - core.groupby.DataArrayGroupBy.apply - core.groupby.DatasetGroupBy.apply - -.. autosummary:: - :toctree: generated/ - :template: autosummary/accessor_attribute.rst - - DataArray.dt.weekofyear - DataArray.dt.week +.. toctree:: + :maxdepth: 1 + + api/top-level + api/dataset + api/dataarray + api/datatree + api/coordinates + api/indexes + api/ufuncs + api/io + api/encoding + api/plotting + api/groupby + api/rolling + api/coarsen + api/rolling-exp + api/weighted + api/resample + api/accessors + api/tutorial + api/testing + api/backends + api/exceptions + api/advanced + api/deprecated From ce177dbf5b0edb14cf21024e1931eb7030b6f2f8 Mon Sep 17 00:00:00 2001 From: Justus Magin Date: Tue, 29 Jul 2025 00:47:33 +0200 Subject: [PATCH 16/16] document `drop_dims` [skip-ci] --- doc/api/coordinates.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/api/coordinates.rst b/doc/api/coordinates.rst index bafd555df0a..a4a6480be83 100644 --- a/doc/api/coordinates.rst +++ b/doc/api/coordinates.rst @@ -54,6 +54,7 @@ Coordinates contents Coordinates.to_dataset Coordinates.to_index Coordinates.assign + Coordinates.drop_dims Coordinates.drop_vars Coordinates.merge Coordinates.copy