API Reference#

Overview#

Most public xcdat APIs operate on xarray.Dataset objects. xcdat follows this design pattern because coordinate variable bounds are often required to perform robust calculations. Currently, coordinate variable bounds can only be stored on Dataset objects and not DataArray objects. Refer to this issue for more information.

Top-level API Functions#

Below is a list of top-level API functions available in xcdat.

open_dataset(path[, data_var, add_bounds, ...])

Wraps xarray.open_dataset() with post-processing options.

open_mfdataset(paths[, data_var, ...])

Wraps xarray.open_mfdataset() with post-processing options.

center_times(dataset)

Centers time coordinates using the midpoint between time bounds.

decode_time(dataset)

Decodes CF and non-CF time coordinates and time bounds using cftime.

swap_lon_axis(dataset, to[, sort_ascending])

Swaps the orientation of a dataset's longitude axis.

compare_datasets(ds1, ds2)

Compares the keys and values of two datasets.

get_dim_coords(obj, axis)

Gets the dimension coordinates for an axis.

get_dim_keys(obj, axis)

Gets the dimension key(s) for an axis.

create_gaussian_grid(nlats)

Creates a grid with Gaussian latitudes and uniform longitudes.

create_global_mean_grid(grid)

Creates a global mean grid.

create_grid(lat, lon[, lat_bnds, lon_bnds])

Creates a grid for a give latitude and longitude array.

create_uniform_grid(lat_start, lat_stop, ...)

Creates a uniform rectilinear grid and sets appropriate the attributes for the lat/lon axis.

create_zonal_grid(grid)

Creates a zonal grid.

Accessors#

What are accessors?#

xcdat provides Dataset accessors, which are implicit namespaces for custom functionality that clearly identifies it as separate from built-in xarray methods. xcdat implements accessors to extend xarray with custom functionality because it is the officially recommended and most common practice (over sub-classing).

In the example below, custom spatial functionality is exposed by chaining the spatial accessor attribute to the Dataset object. This chaining enables access to the underlying spatial average() method.

Accessor API Diagram

How do I use xcdat accessors?#

First, import the package:

>>> from xcdat

Then open up a dataset file as a Dataset object:

>>> ds = xcdat.open_dataset("path/to/file", data_var="ts")

Now chain the accessor attribute to the Dataset to expose the accessor class attributes, methods, or properties:

>>> ds = ds.spatial.average("ts", axis=["X", "Y"])

Note

Accessors are created once per Dataset instance. New instances, like those created from arithmetic operations will have new accessors created.

Classes#

xcdat.bounds.BoundsAccessor(dataset)

An accessor class that provides bounds attributes and methods on xarray Datasets through the .bounds attribute.

xcdat.spatial.SpatialAccessor(dataset)

An accessor class that provides spatial attributes and methods on xarray Datasets through the .spatial attribute.

xcdat.temporal.TemporalAccessor(dataset)

An accessor class that provides temporal attributes and methods on xarray Datasets through the .temporal attribute.

xcdat.regridder.accessor.RegridderAccessor(dataset)

An accessor class that provides regridding attributes and methods on xarray Datasets through the .regridder attribute.

xcdat.regridder.regrid2.Regrid2Regridder(...)

xcdat.regridder.xesmf.XESMFRegridder(...[, ...])

Attributes#

Dataset.bounds.map

Returns a map of axis and coordinates keys to their bounds.

Dataset.bounds.keys

Returns a list of keys for the bounds data variables in the Dataset.

Dataset.regridder.grid

Returns xr.Dataset containing grid information.

Methods#

Dataset.bounds.add_bounds(axis[, width])

Add bounds for an axis using its coordinate points.

Dataset.bounds.get_bounds(axis[, var_key])

Gets coordinate bounds.

Dataset.bounds.add_missing_bounds([width])

Adds missing coordinate bounds for supported axes in the Dataset.

Dataset.spatial.average(data_var[, axis, ...])

Calculates the spatial average for a rectilinear grid over an optionally specified regional domain.

Dataset.temporal.average(data_var[, ...])

Returns a Dataset with the average of a data variable and the time dimension removed.

Dataset.temporal.group_average(data_var, freq)

Returns a Dataset with average of a data variable by time group.

Dataset.temporal.climatology(data_var, freq)

Returns a Dataset with the climatology of a data variable.

Dataset.temporal.departures(data_var, freq)

Returns a Dataset with the climatological departures (anomalies) for a data variable.

Dataset.regridder.horizontal(data_var, ...)

Apply horizontal regridding to data_var of the current xr.Dataset to output_grid.

Dataset.regridder.horizontal_xesmf(data_var, ...)

Wraps the xESMF library providing access to regridding between structured rectilinear and curvilinear grids.

Dataset.regridder.horizontal_regrid2(...)

Pure python implementation of CDAT's regrid2 horizontal regridder.

CDAT Mapping Table#

The table below maps the supported xCDAT operations to the equivalent CDAT and xCDAT APIs. It is especially useful for those who are transitioning over from CDAT to xarray/xCDAT.

How do I…

xCDAT

CDAT

Open dataset files?

xcdat.open_dataset() and xcdat.open_mfdataset()

cdms2.open()

Get coordinate bounds?

Dataset.bounds.get_bounds()

cdms2.tvariable.getBounds()

Set coordinate bounds for a single axis?

Dataset.bounds.add_bounds()

cdms2.tvariable.setBounds()

Set coordinate bounds for all axes with missing bounds?

Dataset.bounds.add_missing_bounds()

N/A

Center time coordinates using time bounds?

xcdat.center_times()

N/A

Swap the longitude axis orientation between (-180 to 180) and (0 to 360)?

axis.swap_lon_axis()

N/A

Spatially average over an optionally specified rectilinear grid?

Dataset.spatial.average("VAR_KEY", axis=["X", "Y"]) specifying lat_bounds and lon_bounds

cdutil.averager(TransientVariable, axis="xy"), optionally subset TransientVariable with cdutil.region.domain()

Decode time coordinates with CF/Non-CF units?

xr.decode_cf() specifying decode_times=True, or xcdat.decode_time()

cdms2.axis.Axis.asComponentTime()

Temporally averaging with a single time-averaged snapshot and time coordinates removed?

Dataset.temporal.average("VAR_KEY")

cdutil.averager(TransientVariable, axis="t")

Temporally average by time group?

Dataset.temporal.group_average("VAR_KEY", freq=<"season"|"month"|"day"|"hour">), subset results for individual seasons, months, or hours

cdutil.SEASONALCYCLE(), cdutil.ANNUALCYCLE(), cdutil.<DJF|MAM|JJA|SON>(), cdutil.<JAN|FEB|...|DEC>()

Calculate climatologies?

Dataset.temporal.climatology("VAR_KEY", freq=<"season"|"month"|"day">), subset results for individual seasons, months, or days

cdutil.SEASONALCYCLE.climatology(), cdutil.ANNUALCYCLE.climatology(), cdutil.<DJF|MAM|JJA|SON>.climatology(), cdutil.<JAN|FEB|...|DEC>.climatology()

Calculate climatological departures?

Dataset.temporal.departures("VAR_KEY", freq=<"season"|"month"|"day">), subset results for individual seasons, months, or days

cdutil.SEASONALCYCLE.departures(), cdutil.ANNUALCYCLE.departures(), cdutil.<DJF|MAM|JJA|SON>.departures(), cdutil.<JAN|FEB|...|DEC>.departures()

Regrid horizontally?

Dataset.regridder.horizontal_regrid2(), Dataset.regridder.horizontal_xesmf()

cdms2.regrid2()