Skip to content

Commit b51683f

Browse files
andersy005dcherian
andersy005
and
dcherian
committed
Documentation improvements (#3328)
* Add examples for full_like, zeros_like, ones_like * Add examples for xr.align * Add examples for xr.merge * Update xr.where docstring * Update xr.dot docstring * Update xarray/core/common.py Co-Authored-By: Deepak Cherian <[email protected]> * Update xarray/core/common.py Co-Authored-By: Deepak Cherian <[email protected]> * Update xr.combine_by_coords docstring * Apply black formatting only * More black formatting * Remove unnecessary pandas bits * Fix indentation issues * Update assign and pipe * Update `Dataset.reindex` with examples * Update `Dataset.fillna` with examples * Address styling issues * Update docstring Co-Authored-By: Deepak Cherian <[email protected]>
1 parent f3c7da6 commit b51683f

File tree

7 files changed

+899
-41
lines changed

7 files changed

+899
-41
lines changed

‎doc/whats-new.rst

+4-1
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,10 @@ Documentation
3232
~~~~~~~~~~~~~
3333
- Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims`.
3434
By `Justus Magin <https://github.com/keewis>`_.
35-
35+
- Add examples for :py:meth:`align`, :py:meth:`merge`, :py:meth:`combine_by_coords`,
36+
:py:meth:`full_like`, :py:meth:`zeros_like`, :py:meth:`ones_like`, :py:meth:`Dataset.pipe`,
37+
:py:meth:`Dataset.assign`, :py:meth:`Dataset.reindex`, :py:meth:`Dataset.fillna`.
38+
By `Anderson Banihirwe <https://github.com/andersy005>`_.
3639
- Fixed documentation to clean up an unwanted file created in ``ipython`` example
3740
(:pull:`3353`).
3841
By `Gregory Gundersen <https://github.com/gwgundersen/>`_.

‎xarray/core/alignment.py

+130
Original file line numberDiff line numberDiff line change
@@ -116,6 +116,136 @@ def align(
116116
ValueError
117117
If any dimensions without labels on the arguments have different sizes,
118118
or a different size than the size of the aligned dimension labels.
119+
120+
Examples
121+
--------
122+
123+
>>> import xarray as xr
124+
>>> x = xr.DataArray([[25, 35], [10, 24]], dims=('lat', 'lon'),
125+
... coords={'lat': [35., 40.], 'lon': [100., 120.]})
126+
>>> y = xr.DataArray([[20, 5], [7, 13]], dims=('lat', 'lon'),
127+
... coords={'lat': [35., 42.], 'lon': [100., 120.]})
128+
129+
>>> x
130+
<xarray.DataArray (lat: 2, lon: 2)>
131+
array([[25, 35],
132+
[10, 24]])
133+
Coordinates:
134+
* lat (lat) float64 35.0 40.0
135+
* lon (lon) float64 100.0 120.0
136+
137+
>>> y
138+
<xarray.DataArray (lat: 2, lon: 2)>
139+
array([[20, 5],
140+
[ 7, 13]])
141+
Coordinates:
142+
* lat (lat) float64 35.0 42.0
143+
* lon (lon) float64 100.0 120.0
144+
145+
>>> a, b = xr.align(x, y)
146+
>>> a
147+
<xarray.DataArray (lat: 1, lon: 2)>
148+
array([[25, 35]])
149+
Coordinates:
150+
* lat (lat) float64 35.0
151+
* lon (lon) float64 100.0 120.0
152+
>>> b
153+
<xarray.DataArray (lat: 1, lon: 2)>
154+
array([[20, 5]])
155+
Coordinates:
156+
* lat (lat) float64 35.0
157+
* lon (lon) float64 100.0 120.0
158+
159+
>>> a, b = xr.align(x, y, join='outer')
160+
>>> a
161+
<xarray.DataArray (lat: 3, lon: 2)>
162+
array([[25., 35.],
163+
[10., 24.],
164+
[nan, nan]])
165+
Coordinates:
166+
* lat (lat) float64 35.0 40.0 42.0
167+
* lon (lon) float64 100.0 120.0
168+
>>> b
169+
<xarray.DataArray (lat: 3, lon: 2)>
170+
array([[20., 5.],
171+
[nan, nan],
172+
[ 7., 13.]])
173+
Coordinates:
174+
* lat (lat) float64 35.0 40.0 42.0
175+
* lon (lon) float64 100.0 120.0
176+
177+
>>> a, b = xr.align(x, y, join='outer', fill_value=-999)
178+
>>> a
179+
<xarray.DataArray (lat: 3, lon: 2)>
180+
array([[ 25, 35],
181+
[ 10, 24],
182+
[-999, -999]])
183+
Coordinates:
184+
* lat (lat) float64 35.0 40.0 42.0
185+
* lon (lon) float64 100.0 120.0
186+
>>> b
187+
<xarray.DataArray (lat: 3, lon: 2)>
188+
array([[ 20, 5],
189+
[-999, -999],
190+
[ 7, 13]])
191+
Coordinates:
192+
* lat (lat) float64 35.0 40.0 42.0
193+
* lon (lon) float64 100.0 120.0
194+
195+
>>> a, b = xr.align(x, y, join='left')
196+
>>> a
197+
<xarray.DataArray (lat: 2, lon: 2)>
198+
array([[25, 35],
199+
[10, 24]])
200+
Coordinates:
201+
* lat (lat) float64 35.0 40.0
202+
* lon (lon) float64 100.0 120.0
203+
>>> b
204+
<xarray.DataArray (lat: 2, lon: 2)>
205+
array([[20., 5.],
206+
[nan, nan]])
207+
Coordinates:
208+
* lat (lat) float64 35.0 40.0
209+
* lon (lon) float64 100.0 120.0
210+
211+
>>> a, b = xr.align(x, y, join='right')
212+
>>> a
213+
<xarray.DataArray (lat: 2, lon: 2)>
214+
array([[25., 35.],
215+
[nan, nan]])
216+
Coordinates:
217+
* lat (lat) float64 35.0 42.0
218+
* lon (lon) float64 100.0 120.0
219+
>>> b
220+
<xarray.DataArray (lat: 2, lon: 2)>
221+
array([[20, 5],
222+
[ 7, 13]])
223+
Coordinates:
224+
* lat (lat) float64 35.0 42.0
225+
* lon (lon) float64 100.0 120.0
226+
227+
>>> a, b = xr.align(x, y, join='exact')
228+
Traceback (most recent call last):
229+
...
230+
"indexes along dimension {!r} are not equal".format(dim)
231+
ValueError: indexes along dimension 'lat' are not equal
232+
233+
>>> a, b = xr.align(x, y, join='override')
234+
>>> a
235+
<xarray.DataArray (lat: 2, lon: 2)>
236+
array([[25, 35],
237+
[10, 24]])
238+
Coordinates:
239+
* lat (lat) float64 35.0 40.0
240+
* lon (lon) float64 100.0 120.0
241+
>>> b
242+
<xarray.DataArray (lat: 2, lon: 2)>
243+
array([[20, 5],
244+
[ 7, 13]])
245+
Coordinates:
246+
* lat (lat) float64 35.0 40.0
247+
* lon (lon) float64 100.0 120.0
248+
119249
"""
120250
if indexes is None:
121251
indexes = {}

‎xarray/core/combine.py

+91-18
Original file line numberDiff line numberDiff line change
@@ -393,7 +393,7 @@ def combine_nested(
393393
--------
394394
395395
A common task is collecting data from a parallelized simulation in which
396-
each processor wrote out to a separate file. A domain which was decomposed
396+
each process wrote out to a separate file. A domain which was decomposed
397397
into 4 parts, 2 each along both the x and y axes, requires organising the
398398
datasets into a doubly-nested list, e.g:
399399
@@ -505,8 +505,7 @@ def combine_by_coords(
505505
----------
506506
datasets : sequence of xarray.Dataset
507507
Dataset objects to combine.
508-
compat : {'identical', 'equals', 'broadcast_equals',
509-
'no_conflicts', 'override'}, optional
508+
compat : {'identical', 'equals', 'broadcast_equals', 'no_conflicts', 'override'}, optional
510509
String indicating how to compare variables of the same name for
511510
potential conflicts:
512511
@@ -520,9 +519,21 @@ def combine_by_coords(
520519
of all non-null values.
521520
- 'override': skip comparing and pick variable from first dataset
522521
data_vars : {'minimal', 'different', 'all' or list of str}, optional
523-
Details are in the documentation of concat
522+
These data variables will be concatenated together:
523+
524+
* 'minimal': Only data variables in which the dimension already
525+
appears are included.
526+
* 'different': Data variables which are not equal (ignoring
527+
attributes) across all datasets are also concatenated (as well as
528+
all for which dimension already appears). Beware: this option may
529+
load the data payload of data variables into memory if they are not
530+
already loaded.
531+
* 'all': All data variables will be concatenated.
532+
* list of str: The listed data variables will be concatenated, in
533+
addition to the 'minimal' data variables.
534+
If objects are DataArrays, `data_vars` must be 'all'.
524535
coords : {'minimal', 'different', 'all' or list of str}, optional
525-
Details are in the documentation of concat
536+
As per the 'data_vars' kwarg, but for coordinate variables.
526537
fill_value : scalar, optional
527538
Value to use for newly missing values
528539
join : {'outer', 'inner', 'left', 'right', 'exact'}, optional
@@ -556,29 +567,91 @@ def combine_by_coords(
556567
they are concatenated based on the values in their dimension coordinates,
557568
not on their position in the list passed to `combine_by_coords`.
558569
570+
>>> import numpy as np
571+
>>> import xarray as xr
572+
573+
>>> x1 = xr.Dataset(
574+
... {
575+
... "temperature": (("y", "x"), 20 * np.random.rand(6).reshape(2, 3)),
576+
... "precipitation": (("y", "x"), np.random.rand(6).reshape(2, 3)),
577+
... },
578+
... coords={"y": [0, 1], "x": [10, 20, 30]},
579+
... )
580+
>>> x2 = xr.Dataset(
581+
... {
582+
... "temperature": (("y", "x"), 20 * np.random.rand(6).reshape(2, 3)),
583+
... "precipitation": (("y", "x"), np.random.rand(6).reshape(2, 3)),
584+
... },
585+
... coords={"y": [2, 3], "x": [10, 20, 30]},
586+
... )
587+
>>> x3 = xr.Dataset(
588+
... {
589+
... "temperature": (("y", "x"), 20 * np.random.rand(6).reshape(2, 3)),
590+
... "precipitation": (("y", "x"), np.random.rand(6).reshape(2, 3)),
591+
... },
592+
... coords={"y": [2, 3], "x": [40, 50, 60]},
593+
... )
594+
559595
>>> x1
560596
<xarray.Dataset>
561-
Dimensions: (x: 3)
562-
Coords:
563-
* position (x) int64 0 1 2
597+
Dimensions: (x: 3, y: 2)
598+
Coordinates:
599+
* y (y) int64 0 1
600+
* x (x) int64 10 20 30
564601
Data variables:
565-
temperature (x) float64 11.04 23.57 20.77 ...
602+
temperature (y, x) float64 1.654 10.63 7.015 2.543 13.93 9.436
603+
precipitation (y, x) float64 0.2136 0.9974 0.7603 0.4679 0.3115 0.945
566604
567605
>>> x2
568606
<xarray.Dataset>
569-
Dimensions: (x: 3)
570-
Coords:
571-
* position (x) int64 3 4 5
607+
Dimensions: (x: 3, y: 2)
608+
Coordinates:
609+
* y (y) int64 2 3
610+
* x (x) int64 10 20 30
611+
Data variables:
612+
temperature (y, x) float64 9.341 0.1251 6.269 7.709 8.82 2.316
613+
precipitation (y, x) float64 0.1728 0.1178 0.03018 0.6509 0.06938 0.3792
614+
615+
>>> x3
616+
<xarray.Dataset>
617+
Dimensions: (x: 3, y: 2)
618+
Coordinates:
619+
* y (y) int64 2 3
620+
* x (x) int64 40 50 60
572621
Data variables:
573-
temperature (x) float64 6.97 8.13 7.42 ...
622+
temperature (y, x) float64 2.789 2.446 6.551 12.46 2.22 15.96
623+
precipitation (y, x) float64 0.4804 0.1902 0.2457 0.6125 0.4654 0.5953
574624
575-
>>> combined = xr.combine_by_coords([x2, x1])
625+
>>> xr.combine_by_coords([x2, x1])
576626
<xarray.Dataset>
577-
Dimensions: (x: 6)
578-
Coords:
579-
* position (x) int64 0 1 2 3 4 5
627+
Dimensions: (x: 3, y: 4)
628+
Coordinates:
629+
* x (x) int64 10 20 30
630+
* y (y) int64 0 1 2 3
580631
Data variables:
581-
temperature (x) float64 11.04 23.57 20.77 ...
632+
temperature (y, x) float64 1.654 10.63 7.015 2.543 ... 7.709 8.82 2.316
633+
precipitation (y, x) float64 0.2136 0.9974 0.7603 ... 0.6509 0.06938 0.3792
634+
635+
>>> xr.combine_by_coords([x3, x1])
636+
<xarray.Dataset>
637+
Dimensions: (x: 6, y: 4)
638+
Coordinates:
639+
* x (x) int64 10 20 30 40 50 60
640+
* y (y) int64 0 1 2 3
641+
Data variables:
642+
temperature (y, x) float64 1.654 10.63 7.015 nan ... nan 12.46 2.22 15.96
643+
precipitation (y, x) float64 0.2136 0.9974 0.7603 ... 0.6125 0.4654 0.5953
644+
645+
>>> xr.combine_by_coords([x3, x1], join='override')
646+
<xarray.Dataset>
647+
Dimensions: (x: 3, y: 4)
648+
Coordinates:
649+
* x (x) int64 10 20 30
650+
* y (y) int64 0 1 2 3
651+
Data variables:
652+
temperature (y, x) float64 1.654 10.63 7.015 2.543 ... 12.46 2.22 15.96
653+
precipitation (y, x) float64 0.2136 0.9974 0.7603 ... 0.6125 0.4654 0.5953
654+
582655
"""
583656

584657
# Group by data vars

0 commit comments

Comments
 (0)