Skip to content

Examples added to docstrings #7936

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 43 commits into from
Jul 11, 2023
Merged

Examples added to docstrings #7936

Changes from 30 commits
Commits
Show all changes
43 commits
Select commit Hold shift + click to select a range
4dc72de
xarray.dataset.tail
harshitha1201 Jun 20, 2023
2c55b95
xarray.dataset.head
harshitha1201 Jun 20, 2023
052fc8f
xarray.dataset.dropna
harshitha1201 Jun 20, 2023
6820863
xarray.dataset.ffill
harshitha1201 Jun 20, 2023
fd7eed4
xarray.dataset.bfill
harshitha1201 Jun 20, 2023
f9ff19c
xarray.dataset.set_Coords
harshitha1201 Jun 20, 2023
2562c58
xarray.dataset.reset_coords
harshitha1201 Jun 20, 2023
3e25744
indentation changes
harshitha1201 Jun 23, 2023
54ad806
indentation
harshitha1201 Jun 27, 2023
44b18b8
reset_coords example
harshitha1201 Jun 27, 2023
70bcf3a
tail_edited
harshitha1201 Jun 27, 2023
1ee84e8
bfill change
harshitha1201 Jun 27, 2023
f46c867
Merge branch 'main' into add-examples2
harshitha1201 Jun 27, 2023
4ba26a6
change
harshitha1201 Jun 27, 2023
3533074
Merge branch 'add-examples2' of https://github.com/harshitha1201/xarr…
harshitha1201 Jun 30, 2023
7bb884f
changes
harshitha1201 Jun 30, 2023
9421faa
indented
harshitha1201 Jul 2, 2023
74a94f9
indented
harshitha1201 Jul 3, 2023
1a728a2
minute_changes
harshitha1201 Jul 3, 2023
a06a8c8
doctest failure change
harshitha1201 Jul 3, 2023
1aa8c92
changes_
harshitha1201 Jul 3, 2023
7b6a2f6
change
harshitha1201 Jul 3, 2023
b00c1b3
Merge branch 'main' into add-examples2
harshitha1201 Jul 3, 2023
f0a9b54
change
harshitha1201 Jul 6, 2023
c168716
Merge branch 'add-examples2' of https://github.com/harshitha1201/xarr…
harshitha1201 Jul 6, 2023
c8999da
change
harshitha1201 Jul 7, 2023
4676ad9
Merge branch 'main' into add-examples2
harshitha1201 Jul 7, 2023
fd3f7ac
indented
harshitha1201 Jul 7, 2023
7882556
Merge branch 'add-examples2' of https://github.com/harshitha1201/xarr…
harshitha1201 Jul 7, 2023
11edc30
.
harshitha1201 Jul 7, 2023
e85f43c
what's new
harshitha1201 Jul 9, 2023
d683a82
.
harshitha1201 Jul 9, 2023
04f167f
head & tail
harshitha1201 Jul 9, 2023
13c4004
bfill & ffill
harshitha1201 Jul 9, 2023
718438c
dropna
harshitha1201 Jul 9, 2023
38e5885
head & tail
harshitha1201 Jul 9, 2023
f44312f
doctest
harshitha1201 Jul 9, 2023
5ef5aad
doctest error
harshitha1201 Jul 9, 2023
0f20bcd
Update xarray/core/dataset.py
harshitha1201 Jul 11, 2023
7d31547
Merge branch 'main' into add-examples2
harshitha1201 Jul 11, 2023
2028eac
.
harshitha1201 Jul 11, 2023
1b167c9
Merge branch 'add-examples2' of https://github.com/harshitha1201/xarr…
harshitha1201 Jul 11, 2023
4ecabe9
Fix doctest
TomNicholas Jul 11, 2023
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
283 changes: 281 additions & 2 deletions xarray/core/dataset.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1742,6 +1742,33 @@ def set_coords(self: T_Dataset, names: Hashable | Iterable[Hashable]) -> T_Datas
names : hashable or iterable of hashable
Name(s) of variables in this dataset to convert into coordinates.

Examples
--------
>>> dataset = xr.Dataset(
... {
... "temperature": ("time", [25, 30, 27]),
... "time": pd.date_range("2023-01-01", periods=3),
... }
... )
>>> dataset
<xarray.Dataset>
Dimensions: (time: 3)
Coordinates:
* time (time) datetime64[ns] 2023-01-01 2023-01-02 2023-01-03
Data variables:
temperature (time) int64 25 30 27

>>> dataset.set_coords("temperature")
<xarray.Dataset>
Dimensions: (time: 3)
Coordinates:
temperature (time) int64 25 30 27
* time (time) datetime64[ns] 2023-01-01 2023-01-02 2023-01-03
Data variables:
*empty*

On calling ``set_coords`` , these variables are converted to coordinates, as shown in the final dataset.

Returns
-------
Dataset
Expand Down Expand Up @@ -1780,6 +1807,119 @@ def reset_coords(
If True, remove coordinates instead of converting them into
variables.

Examples
--------
>>> dataset = xr.Dataset(
... {
... "temperature": (
... ["time", "lat", "lon"],
... [[[25, 26], [27, 28]], [[29, 30], [31, 32]]],
... ),
... "precipitation": (
... ["time", "lat", "lon"],
... [[[0.5, 0.8], [0.2, 0.4]], [[0.3, 0.6], [0.7, 0.9]]],
... ),
... },
... coords={
... "time": pd.date_range(start="2023-01-01", periods=2),
... "lat": [40, 41],
... "lon": [-80, -79],
... "altitude": 1000,
... },
... )

# Dataset before resetting coordinates

>>> dataset
<xarray.Dataset>
Dimensions: (time: 2, lat: 2, lon: 2)
Coordinates:
* time (time) datetime64[ns] 2023-01-01 2023-01-02
* lat (lat) int64 40 41
* lon (lon) int64 -80 -79
altitude int64 1000
Data variables:
temperature (time, lat, lon) int64 25 26 27 28 29 30 31 32
precipitation (time, lat, lon) float64 0.5 0.8 0.2 0.4 0.3 0.6 0.7 0.9

# Reset the 'altitude' coordinate

>>> dataset_reset = dataset.reset_coords("altitude")

# Dataset after resetting coordinates

>>> dataset_reset
<xarray.Dataset>
Dimensions: (time: 2, lat: 2, lon: 2)
Coordinates:
* time (time) datetime64[ns] 2023-01-01 2023-01-02
* lat (lat) int64 40 41
* lon (lon) int64 -80 -79
Data variables:
temperature (time, lat, lon) int64 25 26 27 28 29 30 31 32
precipitation (time, lat, lon) float64 0.5 0.8 0.2 0.4 0.3 0.6 0.7 0.9
altitude int64 1000

>>> cities = ["New York", "London", "Tokyo"]
>>> time = pd.date_range(start="2022-01-01", periods=12, freq="M")
>>> temperature_data = [
... # Temperature values for New York
... [32, 34, 36, 40, 45, 50, 55, 60, 55, 45, 38, 35],
... # Temperature values for London
... [40, 42, 44, 48, 53, 58, 62, 64, 59, 52, 46, 42],
... # Temperature values for Tokyo
... [45, 47, 50, 58, 65, 72, 79, 82, 77, 68, 58, 50],
... ]
>>> precipitation_data = [
... # Precipitation values for New York
... [1.2, 1.5, 1.8, 2.5, 3.0, 2.8, 2.3, 2.0, 2.4, 2.8, 2.3, 1.8],
... # Precipitation values for London
... [2.0, 2.2, 2.5, 2.8, 3.0, 2.7, 2.3, 2.1, 2.3, 2.7, 2.5, 2.2],
... # Precipitation values for Tokyo
... [0.8, 0.9, 1.2, 1.5, 1.8, 2.0, 2.2, 2.1, 2.0, 1.7, 1.4, 1.2],
... ]
>>> dataset = xr.Dataset(
... {
... "temperature": (["city", "time"], temperature_data),
... "precipitation": (["city", "time"], precipitation_data),
... },
... coords={
... "city": cities,
... "time": time,
... "altitude": 1000,
... },
... )

# Dataset before resetting coordinates

>>> dataset
<xarray.Dataset>
Dimensions: (city: 3, time: 12)
Coordinates:
* city (city) <U8 'New York' 'London' 'Tokyo'
* time (time) datetime64[ns] 2022-01-31 2022-02-28 ... 2022-12-31
altitude int64 1000
Data variables:
temperature (city, time) int64 32 34 36 40 45 50 55 ... 79 82 77 68 58 50
precipitation (city, time) float64 1.2 1.5 1.8 2.5 3.0 ... 2.0 1.7 1.4 1.2

# Reset the 'altitude' coordinate

>>> dataset_reset = dataset.reset_coords("altitude")

# Dataset after resetting coordinates

>>> dataset_reset
<xarray.Dataset>
Dimensions: (city: 3, time: 12)
Coordinates:
* city (city) <U8 'New York' 'London' 'Tokyo'
* time (time) datetime64[ns] 2022-01-31 2022-02-28 ... 2022-12-31
Data variables:
temperature (city, time) int64 32 34 36 40 45 50 55 ... 79 82 77 68 58 50
precipitation (city, time) float64 1.2 1.5 1.8 2.5 3.0 ... 2.0 1.7 1.4 1.2
altitude int64 1000

Returns
-------
Dataset
Expand Down Expand Up @@ -2742,6 +2882,37 @@ def head(
The keyword arguments form of ``indexers``.
One of indexers or indexers_kwargs must be provided.

Examples
--------
>>> dataset = xr.Dataset(
... {
... "temperature": [25.1, 28.3, 30.5, 27.2, 26.8],
... "humidity": [60.2, 55.6, 50.3, 58.8, 61.7],
... },
... coords={"time": [1, 2, 3, 4, 5]},
... )
>>> dataset
<xarray.Dataset>
Dimensions: (temperature: 5, humidity: 5, time: 5)
Coordinates:
* temperature (temperature) float64 25.1 28.3 30.5 27.2 26.8
* humidity (humidity) float64 60.2 55.6 50.3 58.8 61.7
* time (time) int64 1 2 3 4 5
Data variables:
*empty*

# Use head() function to retrieve the first three elements

>>> dataset.head(2)
<xarray.Dataset>
Dimensions: (temperature: 2, humidity: 2, time: 2)
Coordinates:
* temperature (temperature) float64 25.1 28.3
* humidity (humidity) float64 60.2 55.6
* time (time) int64 1 2
Data variables:
*empty*

See Also
--------
Dataset.tail
Expand Down Expand Up @@ -2788,6 +2959,26 @@ def tail(
The keyword arguments form of ``indexers``.
One of indexers or indexers_kwargs must be provided.

Examples
--------
>>> data = xr.DataArray([[1, 2, 3], [4, 5, 6], [7, 8, 9]], dims=("x", "y"))
>>> dataset = xr.Dataset({"data": data})
>>> dataset
<xarray.Dataset>
Dimensions: (x: 3, y: 3)
Dimensions without coordinates: x, y
Data variables:
data (x, y) int64 1 2 3 4 5 6 7 8 9

# Get the last 2 elements using tail()

>>> dataset.tail(2)
<xarray.Dataset>
Dimensions: (x: 2, y: 2)
Dimensions without coordinates: x, y
Data variables:
data (x, y) int64 5 6 8 9

See Also
--------
Dataset.head
Expand Down Expand Up @@ -5617,6 +5808,39 @@ def dropna(
Which variables to check for missing values. By default, all
variables in the dataset are checked.

Examples
--------

>>> dataset = xr.Dataset(
... {
... "temperature": (
... ["time", "location"],
... [[23.4, 24.1], [np.nan, 22.1], [21.8, 24.2]],
... )
... },
... coords={"time": [1, 2, 3], "location": ["A", "B"]},
... )
>>> dataset
<xarray.Dataset>
Dimensions: (time: 3, location: 2)
Coordinates:
* time (time) int64 1 2 3
* location (location) <U1 'A' 'B'
Data variables:
temperature (time, location) float64 23.4 24.1 nan 22.1 21.8 24.2

# Drop NaN values from the dataset

>>> dataset_dropped = dataset.dropna(dim="time")
>>> dataset_dropped
<xarray.Dataset>
Dimensions: (time: 2, location: 2)
Coordinates:
* time (time) int64 1 3
* location (location) <U1 'A' 'B'
Data variables:
temperature (time, location) float64 23.4 24.1 21.8 24.2

Returns
-------
Dataset
Expand Down Expand Up @@ -5877,15 +6101,42 @@ def ffill(self: T_Dataset, dim: Hashable, limit: int | None = None) -> T_Dataset
Parameters
----------
dim : Hashable
Specifies the dimension along which to propagate values when
filling.
Specifies the dimension along which to propagate values when filling.
limit : int or None, optional
The maximum number of consecutive NaN values to forward fill. In
other words, if there is a gap with more than this number of
consecutive NaNs, it will only be partially filled. Must be greater
than 0 or None for no limit. Must be None or greater than or equal
to axis length if filling along chunked axes (dimensions).

Examples
--------
# Sample dataset with missing values

>>> time = pd.date_range("2023-01-01", periods=10, freq="D")
>>> data = np.array([1, np.nan, 3, np.nan, 5, 6, np.nan, 8, np.nan, 10])

>>> dataset = xr.Dataset({"data": (("time",), data)}, coords={"time": time})

# Perform forward fill (ffill) on the dataset

>>> filled_dataset = dataset.ffill(dim="time")
>>> dataset
<xarray.Dataset>
Dimensions: (time: 10)
Coordinates:
* time (time) datetime64[ns] 2023-01-01 2023-01-02 ... 2023-01-10
Data variables:
data (time) float64 1.0 nan 3.0 nan 5.0 6.0 nan 8.0 nan 10.0

>>> filled_dataset
<xarray.Dataset>
Dimensions: (time: 10)
Coordinates:
* time (time) datetime64[ns] 2023-01-01 2023-01-02 ... 2023-01-10
Data variables:
data (time) float64 1.0 1.0 3.0 3.0 5.0 6.0 6.0 8.0 8.0 10.0

Returns
-------
Dataset
Expand All @@ -5912,6 +6163,34 @@ def bfill(self: T_Dataset, dim: Hashable, limit: int | None = None) -> T_Dataset
than 0 or None for no limit. Must be None or greater than or equal
to axis length if filling along chunked axes (dimensions).

Examples
--------
# Define the time range

>>> time = pd.date_range("2023-01-01", periods=10, freq="D")

# Define the data array with missing values

>>> data = np.array([1, np.nan, 3, np.nan, 5, 6, np.nan, 8, np.nan, 10])
>>> dataset = xr.Dataset({"data": (("time",), data)}, coords={"time": time})
>>> dataset
<xarray.Dataset>
Dimensions: (time: 10)
Coordinates:
* time (time) datetime64[ns] 2023-01-01 2023-01-02 ... 2023-01-10
Data variables:
data (time) float64 1.0 nan 3.0 nan 5.0 6.0 nan 8.0 nan 10.0

# filled dataset, fills NaN values by propagating values backward

>>> dataset.bfill(dim="time")
<xarray.Dataset>
Dimensions: (time: 10)
Coordinates:
* time (time) datetime64[ns] 2023-01-01 2023-01-02 ... 2023-01-10
Data variables:
data (time) float64 1.0 3.0 3.0 5.0 5.0 6.0 8.0 8.0 10.0 10.0

Returns
-------
Dataset
Expand Down