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 that are 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.
get_coords_by_name(obj, axis)	Retrieve the coordinate variable based on its name.
create_bounds(axis, coord_var)	Creates bounds for an axis using coordinate points as midpoints.
create_axis(name, data[, bounds, ...])	Creates an axis and optional bounds.
create_mask(ds[, dims])	Create a mask as an xarray.DataArray based on the specified dimensions.
create_nan_mask(da[, dims])	Create a mask as an xarray.DataArray with NaN values based on source data.
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([x, y, z, attrs, add_bounds])	Creates a grid dataset using the specified axes.
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.
tutorial.open_dataset(name[, cache, ...])	Open a dataset from the online repository (requires internet).

Module-level API Functions

Below is a list of module-level API functions that are available in xcdat.

mask.pcmdi_land_sea_mask(da[, threshold1, ...])

Generate a land-sea mask using the PCMDI method.

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.

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

bounds.BoundsAccessor(dataset)	An accessor class that provides bounds attributes and methods on xarray Datasets through the .bounds attribute.
spatial.SpatialAccessor(dataset)	An accessor class that provides spatial attributes and methods on xarray Datasets through the .spatial attribute.
temporal.TemporalAccessor(dataset)	An accessor class that provides temporal attributes and methods on xarray Datasets through the .temporal attribute.
regridder.accessor.RegridderAccessor(dataset)	An accessor class that provides regridding attributes and methods for xarray Datasets through the .regridder attribute.
regridder.regrid2.Regrid2Regridder(...[, ...])
regridder.xesmf.XESMFRegridder(input_grid, ...)
regridder.xgcm.XGCMRegridder(input_grid, ...)

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	Extract the X, Y, and Z axes from the Dataset and return a new xr.Dataset.

Methods

Dataset.bounds.add_bounds(axis)	Add bounds for an axis using its coordinates as midpoints.
Dataset.bounds.add_time_bounds(method[, ...])	Add bounds for an axis using its coordinate points.
Dataset.bounds.get_bounds(axis[, var_key])	Gets coordinate bounds.
Dataset.bounds.add_missing_bounds([axes])	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.spatial.mask_land(data_var[, ...])	Masks a data variable by land.
Dataset.spatial.mask_sea(data_var[, method, ...])	Masks a data variable by sea.
Dataset.spatial.generate_land_sea_mask([...])	Generate a land-sea mask.
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, ...)	Transform data_var to output_grid.
Dataset.regridder.vertical(data_var, output_grid)	Transform data_var to output_grid.

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(tool="regrid2")	cdms2.regrid2()