Calling Functions via Accessors

A subset of esmtools functions are registered as xarray accessors. What this means is that you can call some of these functions as you would .isel(), .coarsen(), .interp(), and so on with xarray.

There is just one extra step to do so. After importing esmtools, you have to do add the module call after ds and then the function. For example, you can call ds.grid.convert_lon() to transform between -180 to 180 longitudes and 0 to 360 longitudes.

List of currently supported modules/functions. See the API for usage.

  1. grid
    • convert_lon()
[1]:
import esmtools
import numpy as np
import xarray as xr
[2]:
lat = np.linspace(-89.5, 89.5, 180)
lon = np.linspace(0.5, 359.5, 360)
empty = xr.DataArray(np.empty((180, 360)), dims=['lat', 'lon'])
data = xr.DataArray(np.linspace(0, 360, 360), dims=['lon'],)
data, _ = xr.broadcast(data, empty)
data = data.T
data['lon'] = lon
data['lat'] = lat
[3]:
print(data)
<xarray.DataArray (lat: 180, lon: 360)>
array([[  0.        ,   1.00278552,   2.00557103, ..., 357.99442897,
        358.99721448, 360.        ],
       [  0.        ,   1.00278552,   2.00557103, ..., 357.99442897,
        358.99721448, 360.        ],
       [  0.        ,   1.00278552,   2.00557103, ..., 357.99442897,
        358.99721448, 360.        ],
       ...,
       [  0.        ,   1.00278552,   2.00557103, ..., 357.99442897,
        358.99721448, 360.        ],
       [  0.        ,   1.00278552,   2.00557103, ..., 357.99442897,
        358.99721448, 360.        ],
       [  0.        ,   1.00278552,   2.00557103, ..., 357.99442897,
        358.99721448, 360.        ]])
Coordinates:
  * lon      (lon) float64 0.5 1.5 2.5 3.5 4.5 ... 355.5 356.5 357.5 358.5 359.5
  * lat      (lat) float64 -89.5 -88.5 -87.5 -86.5 -85.5 ... 86.5 87.5 88.5 89.5

Our sample data is just a plot of longitude.

[4]:
data.plot(x='lon', y='lat')
[4]:
<matplotlib.collections.QuadMesh at 0x7f3f5780a2e8>
_images/accessors_5_1.png

However, it ranges from 0 to 360, which is sometimes problematic. We can use the accessor convert_lon() to convert this to -180 to 180.

[5]:
help(data.grid.convert_lon)
Help on method convert_lon in module esmtools.accessor:

convert_lon(coord='lon') method of esmtools.accessor.GridAccessor instance
    Converts longitude grid from -180to180 to 0to360 and vice versa.

    .. note::
        Longitudes are not sorted after conversion (i.e., spanning -180 to 180 or
        0 to 360 from index 0, ..., N) if it is 2D.

    Args:
        ds (xarray object): Dataset to be converted.
        coord (optional str): Name of longitude coordinate, defaults to 'lon'.

    Returns:
        xarray object: Dataset with converted longitude grid.

    Raises:
        CoordinateError: If ``coord`` does not exist in the dataset.

[6]:
converted = data.grid.convert_lon(coord='lon')

Now we’ve switched over to the -180 to 180 coordinate system.

[7]:
converted
[7]:
<xarray.DataArray (lat: 180, lon: 360)>
array([[180.50139276, 181.50417827, 182.50696379, ..., 177.49303621,
        178.49582173, 179.49860724],
       [180.50139276, 181.50417827, 182.50696379, ..., 177.49303621,
        178.49582173, 179.49860724],
       [180.50139276, 181.50417827, 182.50696379, ..., 177.49303621,
        178.49582173, 179.49860724],
       ...,
       [180.50139276, 181.50417827, 182.50696379, ..., 177.49303621,
        178.49582173, 179.49860724],
       [180.50139276, 181.50417827, 182.50696379, ..., 177.49303621,
        178.49582173, 179.49860724],
       [180.50139276, 181.50417827, 182.50696379, ..., 177.49303621,
        178.49582173, 179.49860724]])
Coordinates:
  * lon      (lon) float64 -179.5 -178.5 -177.5 -176.5 ... 177.5 178.5 179.5
  * lat      (lat) float64 -89.5 -88.5 -87.5 -86.5 -85.5 ... 86.5 87.5 88.5 89.5
[8]:
converted.plot(x='lon', y='lat')
[8]:
<matplotlib.collections.QuadMesh at 0x7f3f57512550>
_images/accessors_11_1.png

This is equivalent to running the functional convert_lon() argument:

[9]:
converted = esmtools.grid.convert_lon(data, coord='lon')
[10]:
converted.plot(x='lon', y='lat')
[10]:
<matplotlib.collections.QuadMesh at 0x7f3f574d03c8>
_images/accessors_14_1.png