API reference

This page provides an auto-generated summary of xray’s API. For more details and examples, refer to the relevant chapter in the main part of the documentation.

Top-level functions

align(*objects[, join, copy]) Given any number of Dataset and/or DataArray objects, returns new objects with aligned indexes.
concat(objs[, dim, data_vars, coords, ...]) Concatenate xray objects along a new or existing dimension.
set_options(**kwargs) Set global state within a controlled context

Dataset

Creating a dataset

Dataset([variables, coords, attrs, compat]) A multi-dimensional, in memory, array database.
decode_cf(obj[, concat_characters, ...]) Decode the given Dataset or Datastore according to CF conventions into a new Dataset.

Attributes

Dataset.dims Mapping from dimension names to lengths.
Dataset.data_vars Dictionary of xray.DataArray objects corresponding to data variables
Dataset.coords Dictionary of xray.DataArray objects corresponding to coordinate
Dataset.attrs Dictionary of global attributes on this dataset

Dictionary interface

Datasets implement the mapping interface with keys given by variable names and values given by DataArray objects.

Dataset.__getitem__(key) Access variables or coordinates this dataset as a DataArray.
Dataset.__setitem__(key, value) Add an array to this dataset.
Dataset.__delitem__(key) Remove a variable from this dataset.
Dataset.update(other[, inplace]) Update this dataset’s variables with those from another dataset.
Dataset.iteritems(...)
Dataset.itervalues(...)

Dataset contents

Dataset.copy([deep]) Returns a copy of this dataset.
Dataset.assign(**kwargs) Assign new data variables to a Dataset, returning a new object with all the original variables in addition to the new ones.
Dataset.assign_coords(**kwargs) Assign new coordinates to this object, returning a new object with all the original data in addition to the new coordinates.
Dataset.pipe(func, *args, **kwargs) Apply func(self, *args, **kwargs)
Dataset.merge(other[, inplace, ...]) Merge the arrays of two datasets into a single dataset.
Dataset.rename(name_dict[, inplace]) Returns a new object with renamed variables and dimensions.
Dataset.swap_dims(dims_dict[, inplace]) Returns a new object with swapped dimensions.
Dataset.drop(labels[, dim]) Drop variables or index labels from this dataset.
Dataset.set_coords(names[, inplace]) Given names of one or more variables, set them as coordinates
Dataset.reset_coords([names, drop, inplace]) Given names of coordinates, reset them to become variables

Comparisons

Dataset.equals(other) Two Datasets are equal if they have matching variables and coordinates, all of which are equal.
Dataset.identical(other) Like equals, but also checks all dataset attributes and the attributes on all variables and coordinates.
Dataset.broadcast_equals(other) Two Datasets are broadcast equal if they are equal after broadcasting all variables against each other.

Indexing

Dataset.loc Attribute for location based indexing.
Dataset.isel(**indexers) Returns a new dataset with each array indexed along the specified dimension(s).
Dataset.sel([method]) Returns a new dataset with each array indexed by tick labels along the specified dimension(s).
Dataset.squeeze([dim]) Returns a new dataset with squeezed data.
Dataset.reindex([indexers, method, copy]) Conform this object onto a new set of indexes, filling in missing values with NaN.
Dataset.reindex_like(other[, method, copy]) Conform this object onto the indexes of another object, filling in missing values with NaN.

Computation

Dataset.apply(func[, keep_attrs, args]) Apply a function over the data variables in this dataset.
Dataset.reduce(func[, dim, keep_attrs, ...]) Reduce this dataset by applying func along some dimension(s).
Dataset.groupby(group[, squeeze]) Returns a GroupBy object for performing grouped operations.
Dataset.resample(freq, dim[, how, skipna, ...]) Resample this object to a new temporal resolution.
Dataset.transpose(*dims) Return a new Dataset object with all array dimensions transposed.

Aggregation: all any argmax argmin max mean median min prod sum std var

Missing values: isnull notnull count dropna fillna

ndarray methods: argsort clip conj conjugate round T

Grouped operations: assign assign_coords first last fillna

DataArray

DataArray(data[, coords, dims, name, attrs, ...]) N-dimensional array with labeled coordinates and dimensions.

Attributes

DataArray.values The array’s data as a numpy.ndarray
DataArray.data The array’s data as a dask or numpy array
DataArray.coords Dictionary-like container of coordinate arrays.
DataArray.dims Dimension names associated with this array.
DataArray.name The name of this array.
DataArray.attrs Dictionary storing arbitrary metadata with this array.
DataArray.encoding Dictionary of format-specific settings for how this array should be serialized.

ndarray attributes: ndim shape size dtype

DataArray contents

DataArray.assign_coords(**kwargs) Assign new coordinates to this object, returning a new object with all the original data in addition to the new coordinates.
DataArray.rename(new_name_or_name_dict) Returns a new DataArray with renamed coordinates and/or a new name.
DataArray.swap_dims(dims_dict) Returns a new DataArray with swapped dimensions.
DataArray.drop(labels[, dim]) Drop coordinates or index labels from this DataArray.
DataArray.reset_coords([names, drop, inplace]) Given names of coordinates, reset them to become variables.
DataArray.copy([deep]) Returns a copy of this array.

ndarray methods: astype item

Indexing

DataArray.__getitem__(key)
DataArray.__setitem__(key, value)
DataArray.loc Attribute for location based indexing like pandas.
DataArray.isel(**indexers) Return a new DataArray whose dataset is given by integer indexing along the specified dimension(s).
DataArray.sel([method]) Return a new DataArray whose dataset is given by selecting index labels along the specified dimension(s).
DataArray.squeeze([dim]) Return a new DataArray object with squeezed data.
DataArray.reindex([method, copy]) Conform this object onto a new set of indexes, filling in missing values with NaN.
DataArray.reindex_like(other[, method, copy]) Conform this object onto the indexes of another object, filling in missing values with NaN.

Computation

DataArray.reduce(func[, dim, axis, keep_attrs]) Reduce this array by applying func along some dimension(s).
DataArray.groupby(group[, squeeze]) Returns a GroupBy object for performing grouped operations.
DataArray.resample(freq, dim[, how, skipna, ...]) Resample this object to a new temporal resolution.
DataArray.transpose(*dims) Return a new DataArray object with transposed dimensions.
DataArray.get_axis_num(dim) Return axis number(s) corresponding to dimension(s) in this array.

Aggregation: all any argmax argmin max mean median min prod sum std var

Missing values: isnull notnull count dropna fillna

ndarray methods: argsort clip conj conjugate searchsorted round T

Grouped operations: assign_coords first last fillna

Comparisons

DataArray.equals(other) True if two DataArrays have the same dimensions, coordinates and values; otherwise False.
DataArray.identical(other) Like equals, but also checks the array name and attributes, and attributes on all coordinates.
DataArray.broadcast_equals(other) Two DataArrays are broadcast equal if they are equal after broadcasting them against each other such that they have the same dimensions.

Universal functions

This functions are copied from NumPy, but extended to work on NumPy arrays, dask arrays and all xray objects. You can find them in the xray.ufuncs module:

angle arccos arccosh arcsin arcsinh arctan arctan2 arctanh ceil conj copysign cos cosh deg2rad degrees exp expm1 fabs fix floor fmax fmin fmod fmod frexp hypot imag iscomplex isfinite isinf isnan isreal ldexp log log10 log1p log2 logaddexp logaddexp2 logical_and logical_not logical_or logical_xor maximum minimum nextafter rad2deg radians real rint sign signbit sin sinh sqrt square tan tanh trunc

IO / Conversion

Dataset methods

open_dataset(filename_or_obj[, group, ...]) Load and decode a dataset from a file or file-like object.
open_mfdataset(paths[, chunks, concat_dim, ...]) Open multiple files as a single dataset.
Dataset.to_netcdf([path, mode, format, ...]) Write dataset contents to a netCDF file.
save_mfdataset(datasets, paths[, mode, ...]) Write multiple datasets to disk as netCDF files simultaneously.
Dataset.to_array([dim, name]) Convert this dataset into an xray.DataArray
Dataset.to_dataframe() Convert this dataset into a pandas.DataFrame.
Dataset.from_dataframe(dataframe) Convert a pandas.DataFrame into an xray.Dataset
Dataset.close() Close any files linked to this dataset
Dataset.load() Manually trigger loading of this dataset’s data from disk or a remote source into memory and return this dataset.
Dataset.chunk([chunks, lock]) Coerce all arrays in this dataset into dask arrays with the given chunks.

DataArray methods

DataArray.to_dataset([dim, name]) Convert a DataArray to a Dataset.
DataArray.to_pandas() Convert this array into a pandas object with the same shape.
DataArray.to_series() Convert this array into a pandas.Series.
DataArray.to_dataframe() Convert this array and its coordinates into a tidy pandas.DataFrame.
DataArray.to_index() Convert this variable to a pandas.Index.
DataArray.to_cdms2() Convert this array into a cdms2.Variable
DataArray.from_series(series) Convert a pandas.Series into an xray.DataArray.
DataArray.from_cdms2(variable) Convert a cdms2.Variable into an xray.DataArray
DataArray.load() Manually trigger loading of this array’s data from disk or a remote source into memory and return this array.
DataArray.chunk([chunks]) Coerce this array’s data into a dask arrays with the given chunks.

Backends (experimental)

These backends provide a low-level interface for lazily loading data from external file-formats or protocols, and can be manually invoked to create arguments for the from_store and dump_to_store Dataset methods.

backends.NetCDF4DataStore(filename[, mode, ...]) Store for reading and writing data via the Python-NetCDF4 library.
backends.H5NetCDFStore(filename[, mode, ...]) Store for reading and writing data via h5netcdf
backends.PydapDataStore(url) Store for accessing OpenDAP datasets with pydap.
backends.ScipyDataStore(filename_or_obj[, ...]) Store for reading and writing data via scipy.io.netcdf.

Plotting

DataArray.plot(darray[, ax, rtol]) Default plot of DataArray using matplotlib / pylab.
DataArray.plot_contourf(darray[, ax, ...]) Filled contour plot of 2d DataArray
DataArray.plot_contour(darray[, ax, ...]) Contour plot of 2d DataArray
DataArray.plot_hist(darray[, ax]) Histogram of DataArray
DataArray.plot_imshow(darray[, ax, ...]) Image plot of 2d DataArray using matplotlib / pylab
DataArray.plot_line(darray, *args, **kwargs) Line plot of 1 dimensional DataArray index against values