API reference
This page provides an auto-generated summary of xarray’s API. For more detailsand examples, refer to the relevant chapters in the main part of thedocumentation.
See also: :ref:public api
_.
Top-level functions
apply_ufunc (func, args[, input_core_dims, …]) | Apply a vectorized function for unlabeled arrays on xarray objects. |
align (objects[, join, copy, indexes, …]) | Given any number of Dataset and/or DataArray objects, returns new objects with aligned indexes and dimension sizes. |
broadcast (args[, exclude]) | Explicitly broadcast any number of DataArray or Dataset objects against one another. |
concat (objs[, dim, datavars, coords, …]) | Concatenate xarray objects along a new or existing dimension. |
merge (objects[, compat, join, fill_value]) | Merge any number of xarray objects into a single Dataset as variables. |
auto_combine (datasets[, concat_dim, compat, …]) | Attempt to auto-magically combine the given datasets into one. |
combine_by_coords (datasets[, compat, …]) | Attempt to auto-magically combine the given datasets into one by using dimension coordinates. |
combine_nested (datasets, concat_dim[, …]) | Explicitly combine an N-dimensional grid of datasets into one by using a succession of concat and merge operations along each dimension of the grid. |
where (cond, x, y) | Return elements from _x or y depending on cond. |
set_options (**kwargs) | Set options for xarray in a controlled context. |
full_like (other, fill_value[, dtype]) | Return a new object with the same shape and type as a given object. |
zeros_like (other[, dtype]) | Shorthand for full_like(other, 0, dtype) |
ones_like (other[, dtype]) | Shorthand for full_like(other, 1, dtype) |
dot (arrays[, dims]) | Generalized dot product for xarray objects. |
Dataset
Creating a dataset
Dataset ([data_vars, 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
Dictionary interface
Datasets implement the mapping interface with keys given by variable namesand values given by DataArray
objects.
Dataset contents
Dataset.copy ([deep, data]) | Returns a copy of this dataset. |
Dataset.assign ([variables]) | 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. |
Dataset.assign_attrs (*args, kwargs) | Assign new attrs to this object. |
Dataset.pipe (func, args, **kwargs) | Apply func(self, [](http://xarray.pydata.org/en/v0.12.3/#id3)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.rename_vars ([name_dict]) | Returns a new object with renamed variables including coordinates |
Dataset.rename_dims ([dims_dict]) | Returns a new object with renamed dimensions only. |
Dataset.swap_dims (dims_dict[, inplace]) | Returns a new object with swapped dimensions. |
Dataset.expand_dims ([dim, axis]) | Return a new object with an additional axis (or axes) inserted at the corresponding position in the array shape. |
Dataset.drop (labels[, dim, errors]) | Drop variables or index labels from this dataset. |
Dataset.drop_dims (drop_dims, *[, errors]) | Drop dimensions and associated variables 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, drop]) | Returns a new dataset with each array indexed along the specified dimension(s). |
Dataset.sel ([indexers, method, tolerance, drop]) | Returns a new dataset with each array indexed by tick labels along the specified dimension(s). |
Dataset.squeeze ([dim, drop, axis]) | Return a new object with squeezed data. |
Dataset.interp ([coords, method, …]) | Multidimensional interpolation of Dataset. |
Dataset.interp_like (other[, method, …]) | Interpolate this object onto the coordinates of another object, filling the out of range values with NaN. |
Dataset.reindex ([indexers, method, …]) | Conform this object onto a new set of indexes, filling in missing values with fill_value . |
Dataset.reindex_like (other[, method, …]) | Conform this object onto the indexes of another object, filling in missing values with fill_value . |
Dataset.set_index ([indexes, append, inplace]) | Set Dataset (multi-)indexes using one or more existing coordinates or variables. |
Dataset.reset_index (dims_or_levels[, drop, …]) | Reset the specified index(es) or multi-index level(s). |
Dataset.reorder_levels ([dim_order, inplace]) | Rearrange index levels using input order. |
Missing value handling
Dataset.isnull (args, **kwargs) | |
Dataset.notnull (args, **kwargs) | |
Dataset.combine_first (other) | Combine two Datasets, default to datavars of self. |
Dataset.count ([dim]) | Reduce this Dataset’s data by applying _count along some dimension(s). |
Dataset.dropna (dim[, how, thresh, subset]) | Returns a new dataset with dropped labels for missing values along the provided dimension. |
Dataset.fillna (value) | Fill missing values in this object. |
Dataset.ffill (dim[, limit]) | Fill NaN values by propogating values forward |
Dataset.bfill (dim[, limit]) | Fill NaN values by propogating values backward |
Dataset.interpolate_na ([dim, method, limit, …]) | Interpolate values according to different methods. |
Dataset.where (cond[, other, drop]) | Filter elements from this object according to a condition. |
Dataset.isin (test_elements) | Tests each value in the array for whether it is in test elements. |
Computation
Dataset.apply (func[, keepattrs, 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.groupby_bins (group, bins[, right, …]) | Returns a GroupBy object for performing grouped operations. |
Dataset.rolling ([dim, min_periods, center]) | Rolling window object. |
Dataset.rolling_exp ([window, window_type]) | Exponentially-weighted moving window. |
Dataset.coarsen ([dim, boundary, side, …]) | Coarsen object. |
Dataset.resample ([indexer, skipna, closed, …]) | Returns a Resample object for performing resampling operations. |
Dataset.diff (dim[, n, label]) | Calculate the n-th order discrete difference along given axis. |
Dataset.quantile (q[, dim, interpolation, …]) | Compute the qth quantile of the data along the specified dimension. |
Dataset.differentiate (coord[, edge_order, …]) | Differentiate with the second order accurate central differences. |
Dataset.integrate (coord[, datetime_unit]) | integrate the array with the trapezoidal rule. |
Aggregation:all
any
argmax
argmin
max
mean
median
min
prod
sum
std
var
ndarray methods:astype
argsort
clip
conj
conjugate
imag
round
real
cumsum
cumprod
rank
Grouped operations:assign
assign_coords
first
last
fillna
where
quantile
Reshaping and reorganizing
Dataset.transpose (*dims) | Return a new Dataset object with all array dimensions transposed. |
Dataset.stack ([dimensions]) | Stack any number of existing dimensions into a single new dimension. |
Dataset.unstack ([dim]) | Unstack existing dimensions corresponding to MultiIndexes into multiple new dimensions. |
Dataset.to_stacked_array (new_dim, sample_dims) | Combine variables of differing dimensionality into a DataArray without broadcasting. |
Dataset.shift ([shifts, fill_value]) | Shift this dataset by an offset along one or more dimensions. |
Dataset.roll ([shifts, roll_coords]) | Roll this dataset by an offset along one or more dimensions. |
Dataset.sortby (variables[, ascending]) | Sort object by labels or values (along an axis). |
DataArray
DataArray (data[, coords, dims, name, attrs, …]) | N-dimensional array with labeled coordinates and dimensions. |
Attributes
ndarray attributes:ndim
shape
size
dtype
nbytes
chunks
DataArray contents
DataArray.assign_coords (kwargs) | Assign new coordinates to this object. |
DataArray.assign_attrs (*args, kwargs) | Assign new attrs to this object. |
DataArray.pipe (func, args, **kwargs) | Apply func(self, [](http://xarray.pydata.org/en/v0.12.3/#id8)args, **kwargs) |
DataArray.rename ([new_name_or_name_dict]) | Returns a new DataArray with renamed coordinates or a new name. |
DataArray.swap_dims (dims_dict) | Returns a new DataArray with swapped dimensions. |
DataArray.expand_dims ([dim, axis]) | Return a new object with an additional axis (or axes) inserted at the corresponding position in the array shape. |
DataArray.drop (labels[, dim, errors]) | 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, data]) | 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, drop]) | Return a new DataArray whose data is given by integer indexing along the specified dimension(s). |
DataArray.sel ([indexers, method, tolerance, …]) | Return a new DataArray whose data is given by selecting index labels along the specified dimension(s). |
DataArray.squeeze ([dim, drop, axis]) | Return a new object with squeezed data. |
DataArray.interp ([coords, method, …]) | Multidimensional interpolation of variables. |
DataArray.interp_like (other[, method, …]) | Interpolate this object onto the coordinates of another object, filling out of range values with NaN. |
DataArray.reindex ([indexers, method, …]) | Conform this object onto the indexes of another object, filling in missing values with fill_value . |
DataArray.reindex_like (other[, method, …]) | Conform this object onto the indexes of another object, filling in missing values with fill_value . |
DataArray.set_index ([indexes, append, inplace]) | Set DataArray (multi-)indexes using one or more existing coordinates. |
DataArray.reset_index (dims_or_levels[, …]) | Reset the specified index(es) or multi-index level(s). |
DataArray.reorder_levels ([dim_order, inplace]) | Rearrange index levels using input order. |
Missing value handling
DataArray.isnull (args, **kwargs) | |
DataArray.notnull (args, **kwargs) | |
DataArray.combine_first (other) | Combine two DataArray objects, with union of coordinates. |
DataArray.count ([dim, axis]) | Reduce this DataArray’s data by applying count along some dimension(s). |
DataArray.dropna (dim[, how, thresh]) | Returns a new array with dropped labels for missing values along the provided dimension. |
DataArray.fillna (value) | Fill missing values in this object. |
DataArray.ffill (dim[, limit]) | Fill NaN values by propogating values forward |
DataArray.bfill (dim[, limit]) | Fill NaN values by propogating values backward |
DataArray.interpolate_na ([dim, method, …]) | Interpolate values according to different methods. |
DataArray.where (cond[, other, drop]) | Filter elements from this object according to a condition. |
DataArray.isin (test_elements) | Tests each value in the array for whether it is in test elements. |
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. |
Computation
DataArray.reduce (func[, dim, axis, …]) | Reduce this array by applying func along some dimension(s). |
DataArray.groupby (group[, squeeze, …]) | Returns a GroupBy object for performing grouped operations. |
DataArray.groupby_bins (group, bins[, right, …]) | Returns a GroupBy object for performing grouped operations. |
DataArray.rolling ([dim, min_periods, center]) | Rolling window object. |
DataArray.rolling_exp ([window, window_type]) | Exponentially-weighted moving window. |
DataArray.coarsen ([dim, boundary, side, …]) | Coarsen object. |
DataArray.dt | Access datetime fields for DataArrays with datetime-like dtypes. |
DataArray.resample ([indexer, skipna, …]) | Returns a Resample object for performing resampling operations. |
DataArray.get_axis_num (dim) | Return axis number(s) corresponding to dimension(s) in this array. |
DataArray.diff (dim[, n, label]) | Calculate the n-th order discrete difference along given axis. |
DataArray.dot (other[, dims]) | Perform dot product of two DataArrays along their shared dims. |
DataArray.quantile (q[, dim, interpolation, …]) | Compute the qth quantile of the data along the specified dimension. |
DataArray.differentiate (coord[, edge_order, …]) | Differentiate the array with the second order accurate central differences. |
DataArray.integrate (dim[, datetime_unit]) | integrate the array with the trapezoidal rule. |
DataArray.str | Vectorized string functions for string-like arrays. |
Aggregation:all
any
argmax
argmin
max
mean
median
min
prod
sum
std
var
ndarray methods:argsort
clip
conj
conjugate
imag
searchsorted
round
real
T
cumsum
cumprod
rank
Grouped operations:assign_coords
first
last
fillna
where
quantile
Reshaping and reorganizing
DataArray.transpose (*dims[, transpose_coords]) | Return a new DataArray object with transposed dimensions. |
DataArray.stack ([dimensions]) | Stack any number of existing dimensions into a single new dimension. |
DataArray.unstack ([dim]) | Unstack existing dimensions corresponding to MultiIndexes into multiple new dimensions. |
DataArray.to_unstacked_dataset (dim[, level]) | Unstack DataArray expanding to Dataset along a given level of a stacked coordinate. |
DataArray.shift ([shifts, fill_value]) | Shift this array by an offset along one or more dimensions. |
DataArray.roll ([shifts, roll_coords]) | Roll this array by an offset along one or more dimensions. |
DataArray.sortby (variables[, ascending]) | Sort object by labels or values (along an axis). |
Universal functions
Warning
With recent versions of numpy, dask and xarray, NumPy ufuncs are nowsupported directly on all xarray and dask objects. This obviates the needfor the xarray.ufuncs
module, which should not be used for new codeunless compatibility with versions of NumPy prior to v1.13 is required.
This functions are copied from NumPy, but extended to work on NumPy arrays,dask arrays and all xarray objects. You can find them in the xarray.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, …]) | Open and decode a dataset from a file or file-like object. |
load_dataset (filename_or_obj, kwargs) | Open, load into memory, and close a Dataset from a file or file-like object. |
open_mfdataset (paths[, chunks, concat_dim, …]) | Open multiple files as a single dataset. |
open_rasterio (filename[, parse_coordinates, …]) | Open a file with rasterio (experimental). |
open_zarr (store[, group, synchronizer, …]) | Load and decode a dataset from a Zarr store. |
Dataset.to_netcdf ([path, mode, format, …]) | Write dataset contents to a netCDF file. |
Dataset.to_zarr ([store, mode, synchronizer, …]) | Write dataset contents to a zarr group. |
save_mfdataset (datasets, paths[, mode, …]) | Write multiple datasets to disk as netCDF files simultaneously. |
Dataset.to_array ([dim, name]) | Convert this dataset into an xarray.DataArray |
Dataset.to_dataframe () | Convert this dataset into a pandas.DataFrame. |
Dataset.to_dask_dataframe ([dim_order, set_index]) | Convert this dataset into a dask.dataframe.DataFrame. |
Dataset.to_dict ([data]) | Convert this dataset to a dictionary following xarray naming conventions. |
Dataset.from_dataframe (dataframe) | Convert a pandas.DataFrame into an xarray.Dataset |
Dataset.from_dict (d) | Convert a dictionary into an xarray.Dataset. |
Dataset.close () | Close any files linked to this object |
Dataset.compute (kwargs) | Manually trigger loading of this dataset’s data from disk or a remote source into memory and return a new dataset. |
Dataset.persist (kwargs) | Trigger computation, keeping data as dask arrays |
Dataset.load (kwargs) | Manually trigger loading of this dataset’s data from disk or a remote source into memory and return this dataset. |
Dataset.chunk ([chunks, name_prefix, token, lock]) | Coerce all arrays in this dataset into dask arrays with the given chunks. |
Dataset.filter_by_attrs (**kwargs) | Returns a Dataset with variables that match specific conditions. |
Dataset.info ([buf]) | Concise summary of a Dataset variables and attributes. |
DataArray methods
GroupBy objects
Rolling objects
Resample objects
Resample objects also implement the GroupBy interface(methods like apply()
, reduce()
, mean()
, sum()
, etc.).
Accessors
Custom Indexes
CFTimeIndex | Custom Index for working with CF calendars and dates |
Creating custom indexes
cftime_range ([start, end, periods, freq, …]) | Return a fixed frequency CFTimeIndex. |
Plotting
DataArray.plot | Access plotting functions |
plot.plot (darray[, row, col, col_wrap, ax, …]) | Default plot of DataArray using matplotlib.pyplot. |
plot.contourf (x, y, z, ax, kwargs) | Filled contour plot of 2d DataArray |
plot.contour (x, y, z, ax, kwargs) | Contour plot of 2d DataArray |
plot.hist (darray[, figsize, size, aspect, …]) | Histogram of DataArray |
plot.imshow (x, y, z, ax, *kwargs) | Image plot of 2d DataArray using matplotlib.pyplot |
plot.line (darray, args[, row, col, …]) | Line plot of DataArray index against values |
plot.pcolormesh (x, y, z, ax[, infer_intervals]) | Pseudocolor plot of 2d DataArray |
plot.FacetGrid (data[, col, row, col_wrap, …]) | Initialize the matplotlib figure and FacetGrid object. |
Testing
Exceptions
Advanced API
Dataset.variables | Low level interface to Dataset contents as dict of Variable objects. |
DataArray.variable | Low level interface to the Variable object for this DataArray. |
Variable (dims, data[, attrs, encoding, fastpath]) | A netcdf-like variable consisting of dimensions, data and attributes which describe a single Array. |
IndexVariable (dims, data[, attrs, encoding, …]) | Wrapper for accommodating a pandas.Index in an xarray.Variable. |
as_variable (obj[, name]) | Convert an object into a Variable. |
register_dataset_accessor (name) | Register a custom property on xarray.Dataset objects. |
register_dataarray_accessor (name) | Register a custom accessor on xarray.DataArray objects. |
These backends provide a low-level interface for lazily loading data fromexternal file-formats or protocols, and can be manually invoked to createarguments for the from_store
and dump_to_store
Dataset methods: