xarray.Dataset#

class xarray.Dataset(data_vars=None, coords=None, attrs=None)[source]#

A multi-dimensional, in memory, array database.

A dataset resembles an in-memory representation of a NetCDF file, and consists of variables, coordinates and attributes which together form a self describing dataset.

Dataset implements the mapping interface with keys given by variable names and values given by DataArray objects for each variable name.

By default, pandas indexes are created for one dimensional variables with name equal to their dimension (i.e., Dimension coordinate) so those variables can be readily used as coordinates for label based indexing. When a Coordinates object is passed to coords, any existing index(es) built from those coordinates will be added to the Dataset.

To load data from a file or file-like object, use the open_dataset function.

Parameters:

data_vars (dict-like, optional) – A mapping from variable names to DataArray objects, Variable objects or to tuples of the form (dims, data[, attrs]) which can be used as arguments to create a new Variable. Each dimension must have the same length in all variables in which it appears.

The following notations are accepted:
- mapping {var name: DataArray}
- mapping {var name: Variable}
- mapping {var name: (dimension name, array-like)}
- mapping {var name: (tuple of dimension names, array-like)}
- mapping {dimension name: array-like} (if array-like is not a scalar it will be automatically moved to coords, see below)
Each dimension must have the same length in all variables in which it appears.
coords (Coordinates or dict-like, optional) – A Coordinates object or another mapping in similar form as the data_vars argument, except that each item is saved on the dataset as a “coordinate”. These variables have an associated meaning: they describe constant/fixed/independent quantities, unlike the varying/measured/dependent quantities that belong in variables.

The following notations are accepted for arbitrary mappings:
- mapping {coord name: DataArray}
- mapping {coord name: Variable}
- mapping {coord name: (dimension name, array-like)}
- mapping {coord name: (tuple of dimension names, array-like)}
- mapping {dimension name: array-like} (the dimension name is implicitly set to be the same as the coord name)
The last notation implies either that the coordinate value is a scalar or that it is a 1-dimensional array and the coord name is the same as the dimension name (i.e., a Dimension coordinate). In the latter case, the 1-dimensional array will be assumed to give index values along the dimension with the same name.

Alternatively, a Coordinates object may be used in order to explicitly pass indexes (e.g., a multi-index or any custom Xarray index) or to bypass the creation of a default index for any Dimension coordinate included in that object.
attrs (dict-like, optional) – Global attributes to save on this dataset. (see FAQ, What is your approach to metadata?)

Examples

In this example dataset, we will represent measurements of the temperature and pressure that were made under various conditions:

the measurements were made on four different days;
they were made at two separate locations, which we will represent using their latitude and longitude; and
they were made using three instrument developed by three different manufacturers, which we will refer to using the strings ‘manufac1’, ‘manufac2’, and ‘manufac3’.

>>> np.random.seed(0)
>>> temperature = 15 + 8 * np.random.randn(2, 3, 4)
>>> precipitation = 10 * np.random.rand(2, 3, 4)
>>> lon = [-99.83, -99.32]
>>> lat = [42.25, 42.21]
>>> instruments = ["manufac1", "manufac2", "manufac3"]
>>> time = pd.date_range("2014-09-06", periods=4)
>>> reference_time = pd.Timestamp("2014-09-05")

Here, we initialize the dataset with multiple dimensions. We use the string “loc” to represent the location dimension of the data, the string “instrument” to represent the instrument manufacturer dimension, and the string “time” for the time dimension.

>>> ds = xr.Dataset(
...     data_vars=dict(
...         temperature=(["loc", "instrument", "time"], temperature),
...         precipitation=(["loc", "instrument", "time"], precipitation),
...     ),
...     coords=dict(
...         lon=("loc", lon),
...         lat=("loc", lat),
...         instrument=instruments,
...         time=time,
...         reference_time=reference_time,
...     ),
...     attrs=dict(description="Weather related data."),
... )
>>> ds
<xarray.Dataset> Size: 552B
Dimensions:         (loc: 2, instrument: 3, time: 4)
Coordinates:
    lon             (loc) float64 16B -99.83 -99.32
    lat             (loc) float64 16B 42.25 42.21
  * instrument      (instrument) <U8 96B 'manufac1' 'manufac2' 'manufac3'
  * time            (time) datetime64[us] 32B 2014-09-06 ... 2014-09-09
    reference_time  datetime64[us] 8B 2014-09-05
Dimensions without coordinates: loc
Data variables:
    temperature     (loc, instrument, time) float64 192B 29.11 18.2 ... 9.063
    precipitation   (loc, instrument, time) float64 192B 4.562 5.684 ... 1.613
Attributes:
    description:  Weather related data.

Find out where the coldest temperature was and what values the other variables had:

>>> ds.isel(ds.temperature.argmin(...))
<xarray.Dataset> Size: 80B
Dimensions:         ()
Coordinates:
    lon             float64 8B -99.32
    lat             float64 8B 42.21
    instrument      <U8 32B 'manufac3'
    time            datetime64[us] 8B 2014-09-06
    reference_time  datetime64[us] 8B 2014-09-05
Data variables:
    temperature     float64 8B -5.424
    precipitation   float64 8B 9.884
Attributes:
    description:  Weather related data.

__init__(data_vars=None, coords=None, attrs=None)[source]#

Methods

`__init__`([data_vars, coords, attrs])
`all`([dim, keep_attrs])	Reduce this Dataset's data by applying `all` along some dimension(s).
`any`([dim, keep_attrs])	Reduce this Dataset's data by applying `any` along some dimension(s).
`apply`(func[, keep_attrs, args])	Apply a function to each data variable (backward compatible `map`).
`argmax`([dim])	Return the indices of the maxima of the member variables.
`argmin`([dim])	Return the indices of the minima of the member variables.
`argsort`([axis, kind, order, stable, descending])	Returns the indices that would sort this array.
`as_numpy`()	Coerces wrapped data and coordinates into numpy arrays, returning a Dataset.
`assign`([variables])	Assign new data variables to a Dataset.
`assign_attrs`(args, *kwargs)	Assign new attrs to this object.
`assign_coords`([coords])	Assign new coordinates to this object.
`astype`(dtype, *[, order, casting, subok, ...])	Return a copy of the xarray object, with data cast to a specified type.
`bfill`(dim[, limit])	Fill NaN values by propagating values backward.
`broadcast_equals`(other)	Check whether two Datasets are broadcast equal.
`broadcast_like`(other[, exclude])	Broadcast this DataArray against another Dataset or DataArray.
`chunk`([chunks, name_prefix, token, lock, ...])	Coerce all arrays in this dataset into dask arrays with the given chunks.
`clip`([min, max, keep_attrs])	Return an array whose values are limited to `[min, max]`.
`close`()	Release any resources linked to this object.
`coarsen`([dim, boundary, side, coord_func])	Coarsen object for Datasets.
`combine_first`(other)	Combine two Datasets, default to data_vars of self.
`compute`(**kwargs)	Trigger loading data into memory and return a new dataset.
`conj`()	Complex-conjugate all elements.
`conjugate`(args, *kwargs)	a.conj()
`convert_calendar`(calendar[, dim, align_on, ...])	Convert the Dataset to another calendar.
`copy`([deep, data])	Return a copy of this dataset.
`count`([dim, keep_attrs])	Reduce this Dataset's data by applying `count` along some dimension(s).
`cumprod`([dim, skipna, keep_attrs])	Reduce this Dataset's data by applying `cumprod` (i.e., cumulative product) along some dimension(s).
`cumsum`([dim, skipna, keep_attrs])	Reduce this Dataset's data by applying `cumsum` (i.e., cumulative sum) along some dimension(s).
`cumulative`(dim[, min_periods])	Return an accumulating object for Datasets.
`cumulative_integrate`(coord[, datetime_unit])	Integrate along the given coordinate using the trapezoidal rule.
`curvefit`(coords, func[, reduce_dims, ...])	Curve fitting optimization for arbitrary functions.
`diff`(dim[, n, label])	Calculate the n-th order discrete difference along given axis.
`differentiate`(coord[, edge_order, datetime_unit])	Differentiate with the second order accurate central differences.
`drop`([labels, dim, errors])	Backward compatible method based on drop_vars and drop_sel.
`drop_attrs`(*[, deep])	Remove all attributes from the Dataset and its variables.
`drop_dims`(drop_dims, *[, errors])	Drop dimensions and associated variables from this dataset.
`drop_duplicates`(dim, *[, keep])	Return a new Dataset with duplicate dimension values removed.
`drop_encoding`()	Return a new Dataset without encoding.
`drop_indexes`(coord_names, *[, errors])	Drop the indexes assigned to the given coordinates.
`drop_isel`([indexers])	Drop index positions from this Dataset.
`drop_sel`([labels, errors])	Drop index labels from this dataset.
`drop_vars`(names, *[, errors])	Drop variables from this dataset.
`dropna`(dim, *[, how, thresh, subset])	Return a new dataset with dropped labels for missing values.
`dump_to_store`(store, **kwargs)	Store dataset contents to a backends.*DataStore object.
`equals`(other)	Check whether two Datasets are equal.
`eval`(statement, *[, parser])	Calculate an expression supplied as a string in the context of the dataset.
`expand_dims`([dim, axis, ...])	Return a new object with an additional axis (or axes).
`ffill`(dim[, limit])	Fill NaN values by propagating values forward.
`fillna`(value)	Fill missing values in this object.
`filter_by_attrs`(**kwargs)	Return a `Dataset` with variables that match specific conditions.
`from_dataframe`(dataframe[, sparse])	Convert a pandas.DataFrame into an xarray.Dataset.
`from_dict`(d)	Convert a dictionary into an xarray.Dataset.
`get`(k[,d])
`get_index`(key)	Get an index for a dimension, with fall-back to a default RangeIndex.
`groupby`([group, squeeze, ...])	Return a DatasetGroupBy object for performing grouped operations.
`groupby_bins`(group, bins, *[, right, ...])	Return a DatasetGroupBy object for performing grouped operations.
`head`([indexers])	Return a new dataset with the first n values of each array.
`identical`(other)	Check whether two Datasets are identical.
`idxmax`([dim, skipna, fill_value, keep_attrs])	Return the coordinate label of the maximum value along a dimension.
`idxmin`([dim, skipna, fill_value, keep_attrs])	Return the coordinate label of the minimum value along a dimension.
`info`([buf])	Concise summary of a Dataset variables and attributes.
`integrate`(coord[, datetime_unit])	Integrate along the given coordinate using the trapezoidal rule.
`interp`([coords, method, assume_sorted, ...])	Interpolate a Dataset onto new coordinates.
`interp_calendar`(target[, dim])	Interpolates the Dataset to another calendar based on decimal year measure.
`interp_like`(other[, method, assume_sorted, ...])	Interpolate this object onto the coordinates of another object.
`interpolate_na`([dim, method, limit, ...])	Fill in NaNs by interpolating according to different methods.
`isel`([indexers, drop, missing_dims])	Return a new dataset with each array indexed along the given dimension(s).
`isin`(test_elements)	Test each value in the array for whether it is in test elements.
`isnull`([keep_attrs])	Test each value in the array for whether it is a missing value.
`items`()
`keys`()
`load`(**kwargs)	Trigger loading data into memory and return this dataset.
`load_async`(**kwargs)	Trigger and await asynchronous loading of data into memory and return this dataset.
`load_store`(store[, decoder])	Create a new dataset from the contents of a backends.*DataStore object.
`map`(func[, keep_attrs, args])	Apply a function to each data variable in this dataset.
`map_blocks`(func[, args, kwargs, template])	Apply a function to each block of this Dataset.
`max`([dim, skipna, keep_attrs])	Reduce this Dataset's data by applying `max` (i.e., maximum) along some dimension(s).
`mean`([dim, skipna, keep_attrs])	Reduce this Dataset's data by applying `mean` along some dimension(s).
`median`([dim, skipna, keep_attrs])	Reduce this Dataset's data by applying `median` along some dimension(s).
`merge`(other[, overwrite_vars, compat, join, ...])	Merge the arrays of two datasets into a single dataset.
`min`([dim, skipna, keep_attrs])	Reduce this Dataset's data by applying `min` (i.e., minimum) along some dimension(s).
`notnull`([keep_attrs])	Test each value in the array for whether it is not a missing value.
`pad`([pad_width, mode, stat_length, ...])	Pad this dataset along one or more dimensions.
`persist`(**kwargs)	Trigger computation, keeping data as chunked arrays.
`pipe`(func, args, *kwargs)	Apply `func(self, args, *kwargs)`.
`polyfit`(dim, deg[, skipna, rcond, w, full, cov])	Least squares polynomial fit.
`prod`([dim, skipna, min_count, keep_attrs])	Reduce this Dataset's data by applying `prod` (i.e., product) along some dimension(s).
`quantile`(q[, dim, method, numeric_only, ...])	Compute the qth quantile of the data along the specified dimension.
`query`([queries, parser, engine, missing_dims])	Return a new dataset with each array indexed by query strings.
`rank`(dim, *[, pct, keep_attrs])	Ranks the data.
`reduce`(func[, dim, keep_attrs, keepdims, ...])	Reduce this dataset by applying func along some dimension(s).
`reindex`([indexers, method, tolerance, copy, ...])	Conform this object onto a new set of indexes.
`reindex_like`(other[, method, tolerance, ...])	Conform this object onto the indexes of another object.
`rename`([name_dict])	Return an object with renamed variables, coordinates and dimensions.
`rename_dims`([dims_dict])	Return an object with renamed dimensions only.
`rename_vars`([name_dict])	Return an object with renamed variables including coordinates.
`reorder_levels`([dim_order])	Rearrange index levels using input order.
`resample`([indexer, skipna, closed, label, ...])	Return a Resample object for performing resampling operations.
`reset_coords`([names, drop])	Given names of coordinates, reset them to become variables.
`reset_encoding`()
`reset_index`(dims_or_levels, *[, drop])	Reset the specified index(es) or multi-index level(s).
`roll`([shifts, roll_coords])	Roll this dataset by an offset along one or more dimensions.
`rolling`([dim, min_periods, center])	Return a rolling window object for Datasets.
`rolling_exp`([window, window_type])	Exponentially-weighted moving window.
`round`(args, *kwargs)
`sel`([indexers, method, tolerance, drop])	Return a new dataset with each array indexed by tick labels.
`set_close`(close)	Register the function that releases any resources linked to this object.
`set_coords`(names)	Given names of one or more variables, set them as coordinates.
`set_index`([indexes, append])	Set Dataset (multi-)indexes using one or more existing coords or variables.
`set_xindex`(coord_names[, index_cls])	Set a new, Xarray-compatible index from one or more existing coordinate(s).
`shift`([shifts, fill_value])	Shift this dataset by an offset along one or more dimensions.
`sortby`(variables[, ascending])	Sort object by labels or values (along an axis).
`squeeze`([dim, drop, axis])	Return a new object with squeezed data.
`stack`([dim, create_index, index_cls])	Stack any number of existing dimensions into a single new dimension.
`std`([dim, skipna, ddof, keep_attrs])	Reduce this Dataset's data by applying `std` (i.e., standard deviation) along some dimension(s).
`sum`([dim, skipna, min_count, keep_attrs])	Reduce this Dataset's data by applying `sum` along some dimension(s).
`swap_dims`([dims_dict])	Return a new object with swapped dimensions.
`tail`([indexers])	Return a new dataset with the last n values of each array.
`thin`([indexers])	Return a new dataset with each array indexed along every n-th value.
`to_array`([dim, name])	Convert this dataset into a DataArray (deprecated, use to_dataarray).
`to_dask_dataframe`([dim_order, set_index])	Convert this dataset into a dask.dataframe.DataFrame.
`to_dataarray`([dim, name])	Convert this dataset into an xarray.DataArray.
`to_dataframe`([dim_order])	Convert this dataset into a pandas.DataFrame.
`to_dict`([data, encoding])	Convert this dataset to a dictionary following xarray naming conventions.
`to_netcdf`([path, mode, format, group, ...])	Write dataset contents to a netCDF file.
`to_pandas`()	Convert this dataset into a pandas object without changing the number of dimensions.
`to_stacked_array`(new_dim, sample_dims[, ...])	Combine variables of differing dimensionality into a DataArray.
`to_zarr`([store, mode, group, encoding, ...])	Write dataset contents to a zarr group.
`transpose`(*dim[, missing_dims])	Return a new Dataset object with all array dimensions transposed.
`unify_chunks`()	Unify chunk size along all chunked dimensions of this Dataset.
`unstack`([dim, fill_value, sparse])	Unstack existing dimensions corresponding to MultiIndexes into new dimensions.
`update`(other)	Update this dataset's variables with those from another dataset.
`values`()
`var`([dim, skipna, ddof, keep_attrs])	Reduce this Dataset's data by applying `var` (i.e., variance) along some dimension(s).
`weighted`(weights)	Weighted Dataset operations.
`where`(cond[, other, drop])	Filter elements from this object according to a condition.

Attributes

`attrs`	Dictionary of global attributes on this dataset.
`chunks`	Mapping from dimension names to block lengths for this dataset's data.
`chunksizes`	Mapping from dimension names to block lengths for this dataset's data.
`coords`	Mapping of `DataArray` objects for coordinate variables.
`data_vars`	Dictionary of DataArray objects corresponding to data variables.
`dims`	Mapping from dimension names to lengths.
`dtypes`	Mapping from data variable names to dtypes.
`encoding`	Dictionary of global encoding attributes on this dataset.
`imag`	The imaginary part of each data variable.
`indexes`	Mapping of pandas.Index objects used for label based indexing.
`loc`	Attribute for location based indexing.
`nbytes`	Total bytes consumed by the data arrays of all variables in this dataset.
`real`	The real part of each data variable.
`sizes`	Mapping from dimension names to lengths.
`variables`	Low level interface to Dataset contents as dict of Variable objects.
`xindexes`	Mapping of `Index` objects.