Skip to content
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

Jump to bottom

Documentation improvements #3328

Merged
merged 21 commits into from
Sep 29, 2019
Merged

Documentation improvements #3328

Show file tree
Hide file tree
Changes from 3 commits
Commits
Show all changes
21 commits
Select commit Hold shift + click to select a range
53158d0
Add examples for full_like, zeros_like, ones_like
andersy005 Sep 20, 2019
5daf83d
Add examples for xr.align
andersy005 Sep 20, 2019
a2537cc
Add examples for xr.merge
andersy005 Sep 20, 2019
d448daf
Merge branch 'master' of github.com:pydata/xarray into docs-improvements
andersy005 Sep 21, 2019
2c28ac1
Merge branch 'master' of github.com:pydata/xarray into docs-improvements
andersy005 Sep 24, 2019
7504f60
Update xr.where docstring
andersy005 Sep 24, 2019
a60467a
Update xr.dot docstring
andersy005 Sep 24, 2019
7329adb
Update xarray/core/common.py
andersy005 Sep 24, 2019
68aa199
Update xarray/core/common.py
andersy005 Sep 24, 2019
a4ca35d
Update xr.combine_by_coords docstring
andersy005 Sep 24, 2019
5eeaf19
Apply black formatting only
andersy005 Sep 24, 2019
5c36ed5
More black formatting
andersy005 Sep 24, 2019
003fa9e
Remove unnecessary pandas bits
andersy005 Sep 24, 2019
6094f61
Fix indentation issues
andersy005 Sep 24, 2019
7248fe3
Update assign and pipe
andersy005 Sep 25, 2019
e396103
Update `Dataset.reindex` with examples
andersy005 Sep 25, 2019
0c31c34
Update `Dataset.fillna` with examples
andersy005 Sep 25, 2019
54d32df
Merge branch 'master' of github.com:pydata/xarray into docs-improvements
andersy005 Sep 25, 2019
3c703db
Address styling issues
andersy005 Sep 25, 2019
2a021e4
Update docstring
andersy005 Sep 25, 2019
d386247
Merge branch 'master' into docs-improvements
dcherian Sep 29, 2019
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
130 changes: 130 additions & 0 deletions xarray/core/alignment.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -116,6 +116,136 @@ def align(
ValueError
If any dimensions without labels on the arguments have different sizes,
or a different size than the size of the aligned dimension labels.

Examples
--------

>>> import xarray as xr
>>> x = xr.DataArray([[25, 35], [10, 24]], dims=('lat', 'lon'),
... coords={'lat': [35., 40.], 'lon': [100., 120.]})
>>> y = xr.DataArray([[20, 5], [7, 13]], dims=('lat', 'lon'),
... coords={'lat': [35., 42.], 'lon': [100., 120.]})

>>> x
<xarray.DataArray (lat: 2, lon: 2)>
array([[25, 35],
[10, 24]])
Coordinates:
* lat (lat) float64 35.0 40.0
* lon (lon) float64 100.0 120.0

>>> y
<xarray.DataArray (lat: 2, lon: 2)>
array([[20, 5],
[ 7, 13]])
Coordinates:
* lat (lat) float64 35.0 42.0
* lon (lon) float64 100.0 120.0

>>> a, b = xr.align(x, y)
>>> a
<xarray.DataArray (lat: 1, lon: 2)>
array([[25, 35]])
Coordinates:
* lat (lat) float64 35.0
* lon (lon) float64 100.0 120.0
>>> b
<xarray.DataArray (lat: 1, lon: 2)>
array([[20, 5]])
Coordinates:
* lat (lat) float64 35.0
* lon (lon) float64 100.0 120.0

>>> a, b = xr.align(x, y, join='outer')
>>> a
<xarray.DataArray (lat: 3, lon: 2)>
array([[25., 35.],
[10., 24.],
[nan, nan]])
Coordinates:
* lat (lat) float64 35.0 40.0 42.0
* lon (lon) float64 100.0 120.0
>>> b
<xarray.DataArray (lat: 3, lon: 2)>
array([[20., 5.],
[nan, nan],
[ 7., 13.]])
Coordinates:
* lat (lat) float64 35.0 40.0 42.0
* lon (lon) float64 100.0 120.0

>>> a, b = xr.align(x, y, join='outer', fill_value=-999)
>>> a
<xarray.DataArray (lat: 3, lon: 2)>
array([[ 25, 35],
[ 10, 24],
[-999, -999]])
Coordinates:
* lat (lat) float64 35.0 40.0 42.0
* lon (lon) float64 100.0 120.0
>>> b
<xarray.DataArray (lat: 3, lon: 2)>
array([[ 20, 5],
[-999, -999],
[ 7, 13]])
Coordinates:
* lat (lat) float64 35.0 40.0 42.0
* lon (lon) float64 100.0 120.0

>>> a, b = xr.align(x, y, join='left')
>>> a
<xarray.DataArray (lat: 2, lon: 2)>
array([[25, 35],
[10, 24]])
Coordinates:
* lat (lat) float64 35.0 40.0
* lon (lon) float64 100.0 120.0
>>> b
<xarray.DataArray (lat: 2, lon: 2)>
array([[20., 5.],
[nan, nan]])
Coordinates:
* lat (lat) float64 35.0 40.0
* lon (lon) float64 100.0 120.0

>>> a, b = xr.align(x, y, join='right')
>>> a
<xarray.DataArray (lat: 2, lon: 2)>
array([[25., 35.],
[nan, nan]])
Coordinates:
* lat (lat) float64 35.0 42.0
* lon (lon) float64 100.0 120.0
>>> b
<xarray.DataArray (lat: 2, lon: 2)>
array([[20, 5],
[ 7, 13]])
Coordinates:
* lat (lat) float64 35.0 42.0
* lon (lon) float64 100.0 120.0

>>> a, b = xr.align(x, y, join='exact')
Traceback (most recent call last):
...
"indexes along dimension {!r} are not equal".format(dim)
ValueError: indexes along dimension 'lat' are not equal
Copy link
Collaborator

Choose a reason for hiding this comment

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

This looks a bit awkward to me. How about just ValueError: indexes along dimension 'lat' are not equal? Or other ideas welcome / not terrible atm


>>> a, b = xr.align(x, y, join='override')
>>> a
<xarray.DataArray (lat: 2, lon: 2)>
array([[25, 35],
[10, 24]])
Coordinates:
* lat (lat) float64 35.0 40.0
* lon (lon) float64 100.0 120.0
>>> b
<xarray.DataArray (lat: 2, lon: 2)>
array([[20, 5],
[ 7, 13]])
Coordinates:
* lat (lat) float64 35.0 40.0
* lon (lon) float64 100.0 120.0

"""
if indexes is None:
indexes = {}
Expand Down
148 changes: 146 additions & 2 deletions xarray/core/common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1172,6 +1172,57 @@ def full_like(other, fill_value, dtype: DTypeLike = None):
filled with fill_value. Coords will be copied from other.
If other is based on dask, the new one will be as well, and will be
split in the same chunks.

Examples
--------

>>> import numpy as np
>>> import xarray as xr
>>> x = xr.DataArray(np.arange(6).reshape(2, 3),
... dims=['lat', 'lon'],
... coords={'lat': [1, 2], 'lon': [0, 1, 2]})
>>> x
<xarray.DataArray (lat: 2, lon: 3)>
array([[0, 1, 2],
[3, 4, 5]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2
>>> xr.full_like(x, 1)
dcherian marked this conversation as resolved.
Show resolved Hide resolved
<xarray.DataArray (lat: 2, lon: 3)>
array([[1, 1, 1],
[1, 1, 1]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2
>>> xr.full_like(x, 0.5)
<xarray.DataArray (lat: 2, lon: 3)>
array([[0, 0, 0],
[0, 0, 0]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2
>>> xr.full_like(x, 0.5, dtype=np.double)
<xarray.DataArray (lat: 2, lon: 3)>
array([[0.5, 0.5, 0.5],
[0.5, 0.5, 0.5]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2
>>> xr.full_like(x, np.nan, dtype=np.double)
<xarray.DataArray (lat: 2, lon: 3)>
array([[nan, nan, nan],
[nan, nan, nan]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2

See also
--------

zeros_like
ones_like

"""
from .dataarray import DataArray
from .dataset import Dataset
Expand Down Expand Up @@ -1217,13 +1268,106 @@ def _full_like_variable(other, fill_value, dtype: DTypeLike = None):


def zeros_like(other, dtype: DTypeLike = None):
"""Shorthand for full_like(other, 0, dtype)
"""Return a new object of zeros with the same shape and
type as a given dataarray or dataset.

Parameters
----------
other : DataArray, Dataset, or Variable
The reference object in input
andersy005 marked this conversation as resolved.
Show resolved Hide resolved
dtype : dtype, optional
dtype of the new array. If omitted, it defaults to other.dtype.

Returns
-------
out : same as object
New object of zeros with the same shape and type as other.

Examples
--------

>>> import numpy as np
>>> import xarray as xr
>>> x = xr.DataArray(np.arange(6).reshape(2, 3),
... dims=['lat', 'lon'],
... coords={'lat': [1, 2], 'lon': [0, 1, 2]})
>>> x
<xarray.DataArray (lat: 2, lon: 3)>
array([[0, 1, 2],
[3, 4, 5]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2
>>> xr.zeros_like(x)
<xarray.DataArray (lat: 2, lon: 3)>
array([[0, 0, 0],
[0, 0, 0]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2
>>> xr.zeros_like(x, dtype=np.float)
<xarray.DataArray (lat: 2, lon: 3)>
array([[0., 0., 0.],
[0., 0., 0.]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2

See also
--------

ones_like
full_like

"""
return full_like(other, 0, dtype)


def ones_like(other, dtype: DTypeLike = None):
"""Shorthand for full_like(other, 1, dtype)
"""Return a new object of ones with the same shape and
type as a given dataarray or dataset.

Parameters
----------
other : DataArray, Dataset, or Variable
The reference object in input
andersy005 marked this conversation as resolved.
Show resolved Hide resolved
dtype : dtype, optional
dtype of the new array. If omitted, it defaults to other.dtype.

Returns
-------
out : same as object
New object of ones with the same shape and type as other.

Examples
--------

>>> import numpy as np
>>> import xarray as xr
>>> x = xr.DataArray(np.arange(6).reshape(2, 3),
... dims=['lat', 'lon'],
... coords={'lat': [1, 2], 'lon': [0, 1, 2]})
>>> x
<xarray.DataArray (lat: 2, lon: 3)>
array([[0, 1, 2],
[3, 4, 5]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2
>>> >>> xr.ones_like(x)
<xarray.DataArray (lat: 2, lon: 3)>
array([[1, 1, 1],
[1, 1, 1]])
Coordinates:
* lat (lat) int64 1 2
* lon (lon) int64 0 1 2

See also
--------

zeros_like
full_like

"""
return full_like(other, 1, dtype)

Expand Down
Loading