From 6237834e0aecdad0e178965148aa14f99b308900 Mon Sep 17 00:00:00 2001 From: dcherian Date: Tue, 5 Feb 2019 10:45:02 -0700 Subject: [PATCH 01/15] Friendlier io title. --- doc/io.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/io.rst b/doc/io.rst index 0dc5181f9b8..dbe0a053d87 100644 --- a/doc/io.rst +++ b/doc/io.rst @@ -1,11 +1,11 @@ .. _io: -Serialization and IO -==================== +Reading and writing files +========================= xarray supports direct serialization and IO to several file formats, from simple :ref:`io.pickle` files to the more flexible :ref:`io.netcdf` -format. +format (recommended). .. ipython:: python :suppress: From 519ff9e978732e43da0467200e1a432464158bac Mon Sep 17 00:00:00 2001 From: dcherian Date: Tue, 5 Feb 2019 10:46:43 -0700 Subject: [PATCH 02/15] Fix lists. --- xarray/backends/api.py | 34 +++++++++++++++++----------------- xarray/core/combine.py | 3 +++ xarray/core/dataarray.py | 8 ++++---- xarray/core/dataset.py | 8 ++++---- 4 files changed, 28 insertions(+), 25 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 61efcfdedf2..80bf80f52b4 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -538,12 +538,12 @@ def open_mfdataset(paths, chunks=None, concat_dim=_CONCAT_DIM_DEFAULT, compat : {'identical', 'equals', 'broadcast_equals', 'no_conflicts'}, optional String indicating how to compare variables of the same name for potential conflicts when merging: - * 'broadcast_equals': all values must be equal when variables are + - 'broadcast_equals': all values must be equal when variables are broadcast against each other to ensure common dimensions. - * 'equals': all values and dimensions must be the same. - * 'identical': all values, dimensions and attributes must be the + - 'equals': all values and dimensions must be the same. + - 'identical': all values, dimensions and attributes must be the same. - * 'no_conflicts': only values which are not null in both datasets + - 'no_conflicts': only values which are not null in both datasets must be equal. The returned dataset then contains the combination of all non-null values. preprocess : callable, optional @@ -563,34 +563,34 @@ def open_mfdataset(paths, chunks=None, concat_dim=_CONCAT_DIM_DEFAULT, data_vars : {'minimal', 'different', 'all' or list of str}, optional These data variables will be concatenated together: - * 'minimal': Only data variables in which the dimension already + - 'minimal': Only data variables in which the dimension already appears are included. - * 'different': Data variables which are not equal (ignoring + - 'different': Data variables which are not equal (ignoring attributes) across all datasets are also concatenated (as well as all for which dimension already appears). Beware: this option may load the data payload of data variables into memory if they are not already loaded. - * 'all': All data variables will be concatenated. - * list of str: The listed data variables will be concatenated, in + - 'all': All data variables will be concatenated. + - list of str: The listed data variables will be concatenated, in addition to the 'minimal' data variables. coords : {'minimal', 'different', 'all' o list of str}, optional These coordinate variables will be concatenated together: - * 'minimal': Only coordinates in which the dimension already appears + - 'minimal': Only coordinates in which the dimension already appears are included. - * 'different': Coordinates which are not equal (ignoring attributes) + - 'different': Coordinates which are not equal (ignoring attributes) across all datasets are also concatenated (as well as all for which dimension already appears). Beware: this option may load the data payload of coordinate variables into memory if they are not already loaded. - * 'all': All coordinate variables will be concatenated, except + - 'all': All coordinate variables will be concatenated, except those corresponding to other dimensions. - * list of str: The listed coordinate variables will be concatenated, + - list of str: The listed coordinate variables will be concatenated, in addition the 'minimal' coordinates. parallel : bool, optional If True, the open and preprocess steps of this function will be performed in parallel using ``dask.delayed``. Default is False. - **kwargs : optional + \*\*kwargs : optional Additional arguments passed on to :py:func:`xarray.open_dataset`. Returns @@ -835,14 +835,14 @@ def save_mfdataset(datasets, paths, mode='w', format=None, groups=None, File format for the resulting netCDF file: - * NETCDF4: Data is stored in an HDF5 file, using netCDF4 API + - NETCDF4: Data is stored in an HDF5 file, using netCDF4 API features. - * NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only + - NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only netCDF 3 compatible API features. - * NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, + - NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, which fully supports 2+ GB files, but is only compatible with clients linked against netCDF version 3.6.0 or later. - * NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not + - NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not handle 2+ GB files very well. All formats are supported by the netCDF4-python library. diff --git a/xarray/core/combine.py b/xarray/core/combine.py index 11961dff520..b7910124111 100644 --- a/xarray/core/combine.py +++ b/xarray/core/combine.py @@ -31,6 +31,7 @@ def concat(objs, dim=None, data_vars='all', coords='different', as a coordinate. data_vars : {'minimal', 'different', 'all' or list of str}, optional These data variables will be concatenated together: + * 'minimal': Only data variables in which the dimension already appears are included. * 'different': Data variables which are not equal (ignoring @@ -41,9 +42,11 @@ def concat(objs, dim=None, data_vars='all', coords='different', * 'all': All data variables will be concatenated. * list of str: The listed data variables will be concatenated, in addition to the 'minimal' data variables. + If objects are DataArrays, data_vars must be 'all'. coords : {'minimal', 'different', 'all' or list of str}, optional These coordinate variables will be concatenated together: + * 'minimal': Only coordinates in which the dimension already appears are included. * 'different': Coordinates which are not equal (ignoring attributes) diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 96b42f19555..82315e85ec2 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -1703,14 +1703,14 @@ def to_netcdf(self, *args, **kwargs): 'NETCDF3_CLASSIC'}, optional File format for the resulting netCDF file: - * NETCDF4: Data is stored in an HDF5 file, using netCDF4 API + - NETCDF4: Data is stored in an HDF5 file, using netCDF4 API features. - * NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only + - NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only netCDF 3 compatible API features. - * NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, + - NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, which fully supports 2+ GB files, but is only compatible with clients linked against netCDF version 3.6.0 or later. - * NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not + - NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not handle 2+ GB files very well. All formats are supported by the netCDF4-python library. diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 7bb085848ef..3092f15a5c7 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -1269,14 +1269,14 @@ def to_netcdf(self, path=None, mode='w', format=None, group=None, 'NETCDF3_CLASSIC'}, optional File format for the resulting netCDF file: - * NETCDF4: Data is stored in an HDF5 file, using netCDF4 API + - NETCDF4: Data is stored in an HDF5 file, using netCDF4 API features. - * NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only + - NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only netCDF 3 compatible API features. - * NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, + - NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, which fully supports 2+ GB files, but is only compatible with clients linked against netCDF version 3.6.0 or later. - * NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not + - NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not handle 2+ GB files very well. All formats are supported by the netCDF4-python library. From dfd4c1f7589038e354c1c9e6e8ec572100dedf74 Mon Sep 17 00:00:00 2001 From: dcherian Date: Tue, 5 Feb 2019 10:52:48 -0700 Subject: [PATCH 03/15] Fix *args, **kwargs "inline emphasis..." --- xarray/core/alignment.py | 8 ++++---- xarray/core/common.py | 4 ++-- xarray/core/dataarray.py | 16 ++++++++-------- xarray/core/dataset.py | 16 ++++++++-------- 4 files changed, 22 insertions(+), 22 deletions(-) diff --git a/xarray/core/alignment.py b/xarray/core/alignment.py index 71cdfdebb61..c22990f6b7e 100644 --- a/xarray/core/alignment.py +++ b/xarray/core/alignment.py @@ -35,7 +35,7 @@ def _get_joiner(join): def align(*objects, **kwargs): - """align(*objects, join='inner', copy=True, indexes=None, + """align(\*objects, join='inner', copy=True, indexes=None, exclude=frozenset()) Given any number of Dataset and/or DataArray objects, returns new @@ -48,7 +48,7 @@ def align(*objects, **kwargs): Parameters ---------- - *objects : Dataset or DataArray + \*objects : Dataset or DataArray Objects to align. join : {'outer', 'inner', 'left', 'right', 'exact'}, optional Method for joining the indexes of the passed objects along each @@ -73,7 +73,7 @@ def align(*objects, **kwargs): Returns ------- - aligned : same as *objects + aligned : same as \*objects Tuple of objects with aligned coordinates. Raises @@ -413,7 +413,7 @@ def broadcast(*args, **kwargs): Parameters ---------- - *args : DataArray or Dataset objects + \*args : DataArray or Dataset objects Arrays to broadcast against each other. exclude : sequence of str, optional Dimensions that must not be broadcasted diff --git a/xarray/core/common.py b/xarray/core/common.py index 2f32ca941be..d366983f691 100644 --- a/xarray/core/common.py +++ b/xarray/core/common.py @@ -352,7 +352,7 @@ def assign_coords(self, **kwargs): def assign_attrs(self, *args, **kwargs): """Assign new attrs to this object. - Returns a new object equivalent to self.attrs.update(*args, **kwargs). + Returns a new object equivalent to self.attrs.update(\*args, \*\*kwargs). Parameters ---------- @@ -374,7 +374,7 @@ def assign_attrs(self, *args, **kwargs): def pipe(self, func, *args, **kwargs): """ - Apply func(self, *args, **kwargs) + Apply func(self, \*args, \*\*kwargs) This method replicates the pandas method of the same name. diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 82315e85ec2..cdaa53148d2 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -632,7 +632,7 @@ def load(self, **kwargs): Parameters ---------- - **kwargs : dict + \*\*kwargs : dict Additional keyword arguments passed on to ``dask.array.compute``. See Also @@ -657,7 +657,7 @@ def compute(self, **kwargs): Parameters ---------- - **kwargs : dict + \*\*kwargs : dict Additional keyword arguments passed on to ``dask.array.compute``. See Also @@ -676,7 +676,7 @@ def persist(self, **kwargs): Parameters ---------- - **kwargs : dict + \*\*kwargs : dict Additional keyword arguments passed on to ``dask.persist``. See Also @@ -997,7 +997,7 @@ def interp(self, coords=None, method='linear', assume_sorted=False, values. kwargs: dictionary Additional keyword passed to scipy's interpolator. - **coords_kwarg : {dim: coordinate, ...}, optional + \*\*coords_kwarg : {dim: coordinate, ...}, optional The keyword arguments form of ``coords``. One of coords or coords_kwargs must be provided. @@ -1579,7 +1579,7 @@ def reduce(self, func, dim=None, axis=None, keep_attrs=None, **kwargs): ---------- func : function Function which can be called in the form - `f(x, axis=axis, **kwargs)` to return the result of reducing an + `f(x, axis=axis, \*\*kwargs)` to return the result of reducing an np.ndarray over an integer valued axis. dim : str or sequence of str, optional Dimension(s) over which to apply `func`. @@ -1592,7 +1592,7 @@ def reduce(self, func, dim=None, axis=None, keep_attrs=None, **kwargs): If True, the variable's attributes (`attrs`) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes. - **kwargs : dict + \*\*kwargs : dict Additional keyword arguments passed on to `func`. Returns @@ -2320,7 +2320,7 @@ def quantile(self, q, dim=None, interpolation='linear', keep_attrs=None): is a scalar. If multiple percentiles are given, first axis of the result corresponds to the quantile and a quantile dimension is added to the return array. The other dimensions are the - dimensions that remain after the reduction of the array. + dimensions that remain after the reduction of the array. See Also -------- @@ -2427,7 +2427,7 @@ def differentiate(self, coord, edge_order=1, datetime_unit=None): return self._from_temp_dataset(ds) def integrate(self, dim, datetime_unit=None): - """ integrate the array with the trapezoidal rule. + """ Integrate the array with the trapezoidal rule. .. note:: This feature is limited to simple cartesian geometry, i.e. coord diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 3092f15a5c7..d3997a36916 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -494,7 +494,7 @@ def load(self: T, **kwargs) -> T: Parameters ---------- - **kwargs : dict + \*\*kwargs : dict Additional keyword arguments passed on to ``dask.array.compute``. See Also @@ -626,7 +626,7 @@ def compute(self: T, **kwargs) -> T: Parameters ---------- - **kwargs : dict + \*\*kwargs : dict Additional keyword arguments passed on to ``dask.array.compute``. See Also @@ -663,7 +663,7 @@ def persist(self: T, **kwargs) -> T: Parameters ---------- - **kwargs : dict + \*\*kwargs : dict Additional keyword arguments passed on to ``dask.persist``. See Also @@ -3046,7 +3046,7 @@ def reduce(self, func, dim=None, keep_attrs=None, numeric_only=False, ---------- func : function Function which can be called in the form - `f(x, axis=axis, **kwargs)` to return the result of reducing an + `f(x, axis=axis, \*\*kwargs)` to return the result of reducing an np.ndarray over an integer valued axis. dim : str or sequence of str, optional Dimension(s) over which to apply `func`. By default `func` is @@ -3057,7 +3057,7 @@ def reduce(self, func, dim=None, keep_attrs=None, numeric_only=False, object will be returned without attributes. numeric_only : bool, optional If True, only apply ``func`` to variables with a numeric dtype. - **kwargs : dict + \*\*kwargs : dict Additional keyword arguments passed on to ``func``. Returns @@ -3117,7 +3117,7 @@ def apply(self, func, keep_attrs=None, args=(), **kwargs): Parameters ---------- func : function - Function which can be called in the form `func(x, *args, **kwargs)` + Function which can be called in the form `func(x, \*args, \*\*kwargs)` to transform each DataArray `x` in this dataset into another DataArray. keep_attrs : bool, optional @@ -3126,7 +3126,7 @@ def apply(self, func, keep_attrs=None, args=(), **kwargs): be returned without attributes. args : tuple, optional Positional arguments passed on to `func`. - **kwargs : dict + \*\*kwargs : dict Keyword arguments passed on to `func`. Returns @@ -4109,7 +4109,7 @@ def filter_by_attrs(self, **kwargs): Parameters ---------- - **kwargs : key=value + \*\*kwargs : key=value key : str Attribute name. value : callable or obj From a301ded827f6221c9ba0fa7987cd46d079dee3fa Mon Sep 17 00:00:00 2001 From: dcherian Date: Tue, 5 Feb 2019 11:01:39 -0700 Subject: [PATCH 04/15] misc --- doc/whats-new.rst | 2 +- xarray/core/dataarray.py | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 9ac671d5858..452c7dc8c28 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -87,7 +87,7 @@ Bug fixes from higher frequencies to lower frequencies. Datapoints outside the bounds of the original time coordinate are now filled with NaN (:issue:`2197`). By `Spencer Clark `_. -- Line plots with the `x` argument set to a non-dimensional coord now plot the correct data for 1D DataArrays. +- Line plots with the ``x`` argument set to a non-dimensional coord now plot the correct data for 1D DataArrays. (:issue:`27251). By `Tom Nicholas `_. - Subtracting a scalar ``cftime.datetime`` object from a :py:class:`CFTimeIndex` now results in a :py:class:`pandas.TimedeltaIndex` diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index cdaa53148d2..efc6d402a3b 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -2437,10 +2437,10 @@ def integrate(self, dim, datetime_unit=None): ---------- dim: str, or a sequence of str Coordinate(s) used for the integration. - datetime_unit - Can be specify the unit if datetime coordinate is used. One of - {'Y', 'M', 'W', 'D', 'h', 'm', 's', 'ms', 'us', 'ns', 'ps', 'fs', - 'as'} + datetime_unit: str, optional + Can be used to specify the unit if datetime coordinate is used. + One of {'Y', 'M', 'W', 'D', 'h', 'm', 's', 'ms', 'us', 'ns', + 'ps', 'fs', 'as'} Returns ------- From aae2acc9f6d5e991b0335683b9bc820e15da14f5 Mon Sep 17 00:00:00 2001 From: dcherian Date: Tue, 5 Feb 2019 12:41:17 -0700 Subject: [PATCH 05/15] Reference xarray_extras for csv writing. Closes #2289 --- doc/io.rst | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/doc/io.rst b/doc/io.rst index dbe0a053d87..51c747189da 100644 --- a/doc/io.rst +++ b/doc/io.rst @@ -739,11 +739,14 @@ options are listed on the PseudoNetCDF page. .. _PseudoNetCDF: http://github.com/barronh/PseudoNetCDF -Formats supported by Pandas ---------------------------- +CSV and other formats supported by Pandas +----------------------------------------- For more options (tabular formats and CSV files in particular), consider exporting your objects to pandas and using its broad range of `IO tools`_. +For CSV files, one might also consider `xarray_extras`_. + +.. _xarray_extras: https://xarray-extras.readthedocs.io/en/latest/api/csv.html .. _IO tools: http://pandas.pydata.org/pandas-docs/stable/io.html From f291301a18c01cb0c4c9eccf7cf6991c7a671835 Mon Sep 17 00:00:00 2001 From: dcherian Date: Tue, 5 Feb 2019 12:50:47 -0700 Subject: [PATCH 06/15] Add metpy accessor. Closes #461 --- doc/data-structures.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/data-structures.rst b/doc/data-structures.rst index 618ccccff3e..1ff415b8812 100644 --- a/doc/data-structures.rst +++ b/doc/data-structures.rst @@ -549,6 +549,14 @@ binary operations that act on xarray objects. In the future, we hope to write more helper functions so that you can easily make your functions act like xarray's built-in arithmetic. +CF-compliant coordinate variables +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +`MetPy`_ adds a ``metpy`` accessor that allows accessing coordinates with appropriate CF metadata using generic names ``x``, ``y``, ``vertical`` and ``time``. See `their documentation`_ for more information. + +.. _`MetPy`: https://unidata.github.io/MetPy/dev/index.html +.. _`their documentation`: https://unidata.github.io/MetPy/dev/tutorials/xarray_tutorial.html#coordinates + Indexes ~~~~~~~ From 032fb24e03e5aa0f391c987c2eaf1f7684d3f13a Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 7 Mar 2019 12:47:36 -0800 Subject: [PATCH 07/15] fix transpose docstring. Closes #2576 --- xarray/core/dataarray.py | 5 +++-- xarray/core/dataset.py | 5 +++-- xarray/core/variable.py | 4 ++-- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index efc6d402a3b..02b3951630d 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -1385,8 +1385,9 @@ def transpose(self, *dims): Notes ----- - Although this operation returns a view of this array's data, it is - not lazy -- the data will be fully loaded. + This operation returns a view of this array's data. It is + lazy for dask-backed DataArrays but not for numpy-backed DataArrays + -- the data will be fully loaded. See Also -------- diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index d3997a36916..41895ca12fa 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -2817,8 +2817,9 @@ def transpose(self, *dims): Notes ----- - Although this operation returns a view of each array's data, it - is not lazy -- the data will be fully loaded into memory. + This operation returns a view of each array's data. It is + lazy for dask-backed DataArrays but not for numpy-backed DataArrays + -- the data will be fully loaded into memory. See Also -------- diff --git a/xarray/core/variable.py b/xarray/core/variable.py index b675317d83d..433f4a05e1f 100644 --- a/xarray/core/variable.py +++ b/xarray/core/variable.py @@ -1133,8 +1133,8 @@ def transpose(self, *dims): Notes ----- - Although this operation returns a view of this variable's data, it is - not lazy -- the data will be fully loaded. + This operation returns a view of this variable's data. It is + lazy for dask-backed Variables but not for numpy-backed Variables. See Also -------- From a8648105de8595d9e9c3802149fe289f38095413 Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 7 Mar 2019 12:48:12 -0800 Subject: [PATCH 08/15] Revert "Fix lists." This reverts commit 39983a5835612d7158ae91a9cce7196a03742983. --- xarray/backends/api.py | 34 +++++++++++++++++----------------- xarray/core/combine.py | 3 --- xarray/core/dataarray.py | 8 ++++---- xarray/core/dataset.py | 8 ++++---- 4 files changed, 25 insertions(+), 28 deletions(-) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 80bf80f52b4..61efcfdedf2 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -538,12 +538,12 @@ def open_mfdataset(paths, chunks=None, concat_dim=_CONCAT_DIM_DEFAULT, compat : {'identical', 'equals', 'broadcast_equals', 'no_conflicts'}, optional String indicating how to compare variables of the same name for potential conflicts when merging: - - 'broadcast_equals': all values must be equal when variables are + * 'broadcast_equals': all values must be equal when variables are broadcast against each other to ensure common dimensions. - - 'equals': all values and dimensions must be the same. - - 'identical': all values, dimensions and attributes must be the + * 'equals': all values and dimensions must be the same. + * 'identical': all values, dimensions and attributes must be the same. - - 'no_conflicts': only values which are not null in both datasets + * 'no_conflicts': only values which are not null in both datasets must be equal. The returned dataset then contains the combination of all non-null values. preprocess : callable, optional @@ -563,34 +563,34 @@ def open_mfdataset(paths, chunks=None, concat_dim=_CONCAT_DIM_DEFAULT, data_vars : {'minimal', 'different', 'all' or list of str}, optional These data variables will be concatenated together: - - 'minimal': Only data variables in which the dimension already + * 'minimal': Only data variables in which the dimension already appears are included. - - 'different': Data variables which are not equal (ignoring + * 'different': Data variables which are not equal (ignoring attributes) across all datasets are also concatenated (as well as all for which dimension already appears). Beware: this option may load the data payload of data variables into memory if they are not already loaded. - - 'all': All data variables will be concatenated. - - list of str: The listed data variables will be concatenated, in + * 'all': All data variables will be concatenated. + * list of str: The listed data variables will be concatenated, in addition to the 'minimal' data variables. coords : {'minimal', 'different', 'all' o list of str}, optional These coordinate variables will be concatenated together: - - 'minimal': Only coordinates in which the dimension already appears + * 'minimal': Only coordinates in which the dimension already appears are included. - - 'different': Coordinates which are not equal (ignoring attributes) + * 'different': Coordinates which are not equal (ignoring attributes) across all datasets are also concatenated (as well as all for which dimension already appears). Beware: this option may load the data payload of coordinate variables into memory if they are not already loaded. - - 'all': All coordinate variables will be concatenated, except + * 'all': All coordinate variables will be concatenated, except those corresponding to other dimensions. - - list of str: The listed coordinate variables will be concatenated, + * list of str: The listed coordinate variables will be concatenated, in addition the 'minimal' coordinates. parallel : bool, optional If True, the open and preprocess steps of this function will be performed in parallel using ``dask.delayed``. Default is False. - \*\*kwargs : optional + **kwargs : optional Additional arguments passed on to :py:func:`xarray.open_dataset`. Returns @@ -835,14 +835,14 @@ def save_mfdataset(datasets, paths, mode='w', format=None, groups=None, File format for the resulting netCDF file: - - NETCDF4: Data is stored in an HDF5 file, using netCDF4 API + * NETCDF4: Data is stored in an HDF5 file, using netCDF4 API features. - - NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only + * NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only netCDF 3 compatible API features. - - NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, + * NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, which fully supports 2+ GB files, but is only compatible with clients linked against netCDF version 3.6.0 or later. - - NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not + * NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not handle 2+ GB files very well. All formats are supported by the netCDF4-python library. diff --git a/xarray/core/combine.py b/xarray/core/combine.py index b7910124111..11961dff520 100644 --- a/xarray/core/combine.py +++ b/xarray/core/combine.py @@ -31,7 +31,6 @@ def concat(objs, dim=None, data_vars='all', coords='different', as a coordinate. data_vars : {'minimal', 'different', 'all' or list of str}, optional These data variables will be concatenated together: - * 'minimal': Only data variables in which the dimension already appears are included. * 'different': Data variables which are not equal (ignoring @@ -42,11 +41,9 @@ def concat(objs, dim=None, data_vars='all', coords='different', * 'all': All data variables will be concatenated. * list of str: The listed data variables will be concatenated, in addition to the 'minimal' data variables. - If objects are DataArrays, data_vars must be 'all'. coords : {'minimal', 'different', 'all' or list of str}, optional These coordinate variables will be concatenated together: - * 'minimal': Only coordinates in which the dimension already appears are included. * 'different': Coordinates which are not equal (ignoring attributes) diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 02b3951630d..33d4710b869 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -1704,14 +1704,14 @@ def to_netcdf(self, *args, **kwargs): 'NETCDF3_CLASSIC'}, optional File format for the resulting netCDF file: - - NETCDF4: Data is stored in an HDF5 file, using netCDF4 API + * NETCDF4: Data is stored in an HDF5 file, using netCDF4 API features. - - NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only + * NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only netCDF 3 compatible API features. - - NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, + * NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, which fully supports 2+ GB files, but is only compatible with clients linked against netCDF version 3.6.0 or later. - - NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not + * NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not handle 2+ GB files very well. All formats are supported by the netCDF4-python library. diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 41895ca12fa..9e4df2264e1 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -1269,14 +1269,14 @@ def to_netcdf(self, path=None, mode='w', format=None, group=None, 'NETCDF3_CLASSIC'}, optional File format for the resulting netCDF file: - - NETCDF4: Data is stored in an HDF5 file, using netCDF4 API + * NETCDF4: Data is stored in an HDF5 file, using netCDF4 API features. - - NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only + * NETCDF4_CLASSIC: Data is stored in an HDF5 file, using only netCDF 3 compatible API features. - - NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, + * NETCDF3_64BIT: 64-bit offset version of the netCDF 3 file format, which fully supports 2+ GB files, but is only compatible with clients linked against netCDF version 3.6.0 or later. - - NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not + * NETCDF3_CLASSIC: The classic netCDF 3 file format. It does not handle 2+ GB files very well. All formats are supported by the netCDF4-python library. From a1eb7751c6eb6ddc35ae541a51c4eaea8fdb5177 Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 7 Mar 2019 12:48:22 -0800 Subject: [PATCH 09/15] Revert "Fix *args, **kwargs" This reverts commit 1b9da35ef43e44ce7855f2ab8406a781c9a68933. --- xarray/core/alignment.py | 8 ++++---- xarray/core/common.py | 4 ++-- xarray/core/dataarray.py | 16 ++++++++-------- xarray/core/dataset.py | 16 ++++++++-------- 4 files changed, 22 insertions(+), 22 deletions(-) diff --git a/xarray/core/alignment.py b/xarray/core/alignment.py index c22990f6b7e..71cdfdebb61 100644 --- a/xarray/core/alignment.py +++ b/xarray/core/alignment.py @@ -35,7 +35,7 @@ def _get_joiner(join): def align(*objects, **kwargs): - """align(\*objects, join='inner', copy=True, indexes=None, + """align(*objects, join='inner', copy=True, indexes=None, exclude=frozenset()) Given any number of Dataset and/or DataArray objects, returns new @@ -48,7 +48,7 @@ def align(*objects, **kwargs): Parameters ---------- - \*objects : Dataset or DataArray + *objects : Dataset or DataArray Objects to align. join : {'outer', 'inner', 'left', 'right', 'exact'}, optional Method for joining the indexes of the passed objects along each @@ -73,7 +73,7 @@ def align(*objects, **kwargs): Returns ------- - aligned : same as \*objects + aligned : same as *objects Tuple of objects with aligned coordinates. Raises @@ -413,7 +413,7 @@ def broadcast(*args, **kwargs): Parameters ---------- - \*args : DataArray or Dataset objects + *args : DataArray or Dataset objects Arrays to broadcast against each other. exclude : sequence of str, optional Dimensions that must not be broadcasted diff --git a/xarray/core/common.py b/xarray/core/common.py index d366983f691..2f32ca941be 100644 --- a/xarray/core/common.py +++ b/xarray/core/common.py @@ -352,7 +352,7 @@ def assign_coords(self, **kwargs): def assign_attrs(self, *args, **kwargs): """Assign new attrs to this object. - Returns a new object equivalent to self.attrs.update(\*args, \*\*kwargs). + Returns a new object equivalent to self.attrs.update(*args, **kwargs). Parameters ---------- @@ -374,7 +374,7 @@ def assign_attrs(self, *args, **kwargs): def pipe(self, func, *args, **kwargs): """ - Apply func(self, \*args, \*\*kwargs) + Apply func(self, *args, **kwargs) This method replicates the pandas method of the same name. diff --git a/xarray/core/dataarray.py b/xarray/core/dataarray.py index 33d4710b869..e7e12ae3da4 100644 --- a/xarray/core/dataarray.py +++ b/xarray/core/dataarray.py @@ -632,7 +632,7 @@ def load(self, **kwargs): Parameters ---------- - \*\*kwargs : dict + **kwargs : dict Additional keyword arguments passed on to ``dask.array.compute``. See Also @@ -657,7 +657,7 @@ def compute(self, **kwargs): Parameters ---------- - \*\*kwargs : dict + **kwargs : dict Additional keyword arguments passed on to ``dask.array.compute``. See Also @@ -676,7 +676,7 @@ def persist(self, **kwargs): Parameters ---------- - \*\*kwargs : dict + **kwargs : dict Additional keyword arguments passed on to ``dask.persist``. See Also @@ -997,7 +997,7 @@ def interp(self, coords=None, method='linear', assume_sorted=False, values. kwargs: dictionary Additional keyword passed to scipy's interpolator. - \*\*coords_kwarg : {dim: coordinate, ...}, optional + **coords_kwarg : {dim: coordinate, ...}, optional The keyword arguments form of ``coords``. One of coords or coords_kwargs must be provided. @@ -1580,7 +1580,7 @@ def reduce(self, func, dim=None, axis=None, keep_attrs=None, **kwargs): ---------- func : function Function which can be called in the form - `f(x, axis=axis, \*\*kwargs)` to return the result of reducing an + `f(x, axis=axis, **kwargs)` to return the result of reducing an np.ndarray over an integer valued axis. dim : str or sequence of str, optional Dimension(s) over which to apply `func`. @@ -1593,7 +1593,7 @@ def reduce(self, func, dim=None, axis=None, keep_attrs=None, **kwargs): If True, the variable's attributes (`attrs`) will be copied from the original object to the new one. If False (default), the new object will be returned without attributes. - \*\*kwargs : dict + **kwargs : dict Additional keyword arguments passed on to `func`. Returns @@ -2321,7 +2321,7 @@ def quantile(self, q, dim=None, interpolation='linear', keep_attrs=None): is a scalar. If multiple percentiles are given, first axis of the result corresponds to the quantile and a quantile dimension is added to the return array. The other dimensions are the - dimensions that remain after the reduction of the array. + dimensions that remain after the reduction of the array. See Also -------- @@ -2428,7 +2428,7 @@ def differentiate(self, coord, edge_order=1, datetime_unit=None): return self._from_temp_dataset(ds) def integrate(self, dim, datetime_unit=None): - """ Integrate the array with the trapezoidal rule. + """ integrate the array with the trapezoidal rule. .. note:: This feature is limited to simple cartesian geometry, i.e. coord diff --git a/xarray/core/dataset.py b/xarray/core/dataset.py index 9e4df2264e1..1622a785e64 100644 --- a/xarray/core/dataset.py +++ b/xarray/core/dataset.py @@ -494,7 +494,7 @@ def load(self: T, **kwargs) -> T: Parameters ---------- - \*\*kwargs : dict + **kwargs : dict Additional keyword arguments passed on to ``dask.array.compute``. See Also @@ -626,7 +626,7 @@ def compute(self: T, **kwargs) -> T: Parameters ---------- - \*\*kwargs : dict + **kwargs : dict Additional keyword arguments passed on to ``dask.array.compute``. See Also @@ -663,7 +663,7 @@ def persist(self: T, **kwargs) -> T: Parameters ---------- - \*\*kwargs : dict + **kwargs : dict Additional keyword arguments passed on to ``dask.persist``. See Also @@ -3047,7 +3047,7 @@ def reduce(self, func, dim=None, keep_attrs=None, numeric_only=False, ---------- func : function Function which can be called in the form - `f(x, axis=axis, \*\*kwargs)` to return the result of reducing an + `f(x, axis=axis, **kwargs)` to return the result of reducing an np.ndarray over an integer valued axis. dim : str or sequence of str, optional Dimension(s) over which to apply `func`. By default `func` is @@ -3058,7 +3058,7 @@ def reduce(self, func, dim=None, keep_attrs=None, numeric_only=False, object will be returned without attributes. numeric_only : bool, optional If True, only apply ``func`` to variables with a numeric dtype. - \*\*kwargs : dict + **kwargs : dict Additional keyword arguments passed on to ``func``. Returns @@ -3118,7 +3118,7 @@ def apply(self, func, keep_attrs=None, args=(), **kwargs): Parameters ---------- func : function - Function which can be called in the form `func(x, \*args, \*\*kwargs)` + Function which can be called in the form `func(x, *args, **kwargs)` to transform each DataArray `x` in this dataset into another DataArray. keep_attrs : bool, optional @@ -3127,7 +3127,7 @@ def apply(self, func, keep_attrs=None, args=(), **kwargs): be returned without attributes. args : tuple, optional Positional arguments passed on to `func`. - \*\*kwargs : dict + **kwargs : dict Keyword arguments passed on to `func`. Returns @@ -4110,7 +4110,7 @@ def filter_by_attrs(self, **kwargs): Parameters ---------- - \*\*kwargs : key=value + **kwargs : key=value key : str Attribute name. value : callable or obj From 60bfdc5f8cbccd729993012b4f0a41b34e05d0be Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 7 Mar 2019 12:54:14 -0800 Subject: [PATCH 10/15] Add MetPy to related projects. --- doc/related-projects.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/related-projects.rst b/doc/related-projects.rst index c89e324ff7c..e899022e5d4 100644 --- a/doc/related-projects.rst +++ b/doc/related-projects.rst @@ -13,6 +13,7 @@ Geosciences - `aospy `_: Automated analysis and management of gridded climate data. - `infinite-diff `_: xarray-based finite-differencing, focused on gridded climate/meterology data - `marc_analysis `_: Analysis package for CESM/MARC experiments and output. +- `MetPy `_: A collection of tools in Python for reading, visualizing, and performing calculations with weather data. - `MPAS-Analysis `_: Analysis for simulations produced with Model for Prediction Across Scales (MPAS) components and the Accelerated Climate Model for Energy (ACME). - `OGGM `_: Open Global Glacier Model - `Oocgcm `_: Analysis of large gridded geophysical datasets From aa3d45b2f4e73de1bcbfaa07994d76c0be9630a0 Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 7 Mar 2019 13:34:39 -0800 Subject: [PATCH 11/15] Add hvplot. --- doc/plotting.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/plotting.rst b/doc/plotting.rst index a705c683594..c8f568e516f 100644 --- a/doc/plotting.rst +++ b/doc/plotting.rst @@ -39,6 +39,10 @@ For more extensive plotting applications consider the following projects: data structures for building even complex visualizations easily." Includes native support for xarray objects. +- `hvplot `_: ``hvplot`` makes it very easy to produce + dynamic plots (backed by ``Holoviews`` or ``Geoviews``) by adding a ``hvplot`` + accessor to DataArrays. + - `Cartopy `_: Provides cartographic tools. From e5c04dcd08c2b0d38752881577a1ba9501eba2cb Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 7 Mar 2019 13:31:40 -0800 Subject: [PATCH 12/15] Add Weather and Climate specific page. --- doc/data-structures.rst | 8 -- doc/index.rst | 2 + doc/time-series.rst | 137 ---------------------------------- doc/weather-climate.rst | 159 ++++++++++++++++++++++++++++++++++++++++ 4 files changed, 161 insertions(+), 145 deletions(-) create mode 100644 doc/weather-climate.rst diff --git a/doc/data-structures.rst b/doc/data-structures.rst index 1ff415b8812..618ccccff3e 100644 --- a/doc/data-structures.rst +++ b/doc/data-structures.rst @@ -549,14 +549,6 @@ binary operations that act on xarray objects. In the future, we hope to write more helper functions so that you can easily make your functions act like xarray's built-in arithmetic. -CF-compliant coordinate variables -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -`MetPy`_ adds a ``metpy`` accessor that allows accessing coordinates with appropriate CF metadata using generic names ``x``, ``y``, ``vertical`` and ``time``. See `their documentation`_ for more information. - -.. _`MetPy`: https://unidata.github.io/MetPy/dev/index.html -.. _`their documentation`: https://unidata.github.io/MetPy/dev/tutorials/xarray_tutorial.html#coordinates - Indexes ~~~~~~~ diff --git a/doc/index.rst b/doc/index.rst index dbe911011cd..1d3bb110ddb 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -52,6 +52,7 @@ Documentation * :doc:`reshaping` * :doc:`combining` * :doc:`time-series` +* :doc:`weather-climate` * :doc:`pandas` * :doc:`io` * :doc:`dask` @@ -70,6 +71,7 @@ Documentation reshaping combining time-series + weather-climate pandas io dask diff --git a/doc/time-series.rst b/doc/time-series.rst index 3249dad2ec6..53efcd45ba2 100644 --- a/doc/time-series.rst +++ b/doc/time-series.rst @@ -212,140 +212,3 @@ Data that has indices outside of the given ``tolerance`` are set to ``NaN``. For more examples of using grouped operations on a time dimension, see :ref:`toy weather data`. - - -.. _CFTimeIndex: - -Non-standard calendars and dates outside the Timestamp-valid range ------------------------------------------------------------------- - -Through the standalone ``cftime`` library and a custom subclass of -:py:class:`pandas.Index`, xarray supports a subset of the indexing -functionality enabled through the standard :py:class:`pandas.DatetimeIndex` for -dates from non-standard calendars commonly used in climate science or dates -using a standard calendar, but outside the `Timestamp-valid range`_ -(approximately between years 1678 and 2262). - -.. note:: - - As of xarray version 0.11, by default, :py:class:`cftime.datetime` objects - will be used to represent times (either in indexes, as a - :py:class:`~xarray.CFTimeIndex`, or in data arrays with dtype object) if - any of the following are true: - - - The dates are from a non-standard calendar - - Any dates are outside the Timestamp-valid range. - - Otherwise pandas-compatible dates from a standard calendar will be - represented with the ``np.datetime64[ns]`` data type, enabling the use of a - :py:class:`pandas.DatetimeIndex` or arrays with dtype ``np.datetime64[ns]`` - and their full set of associated features. - -For example, you can create a DataArray indexed by a time -coordinate with dates from a no-leap calendar and a -:py:class:`~xarray.CFTimeIndex` will automatically be used: - -.. ipython:: python - - from itertools import product - from cftime import DatetimeNoLeap - dates = [DatetimeNoLeap(year, month, 1) for year, month in - product(range(1, 3), range(1, 13))] - da = xr.DataArray(np.arange(24), coords=[dates], dims=['time'], name='foo') - -xarray also includes a :py:func:`~xarray.cftime_range` function, which enables -creating a :py:class:`~xarray.CFTimeIndex` with regularly-spaced dates. For -instance, we can create the same dates and DataArray we created above using: - -.. ipython:: python - - dates = xr.cftime_range(start='0001', periods=24, freq='MS', calendar='noleap') - da = xr.DataArray(np.arange(24), coords=[dates], dims=['time'], name='foo') - -For data indexed by a :py:class:`~xarray.CFTimeIndex` xarray currently supports: - -- `Partial datetime string indexing`_ using strictly `ISO 8601-format`_ partial - datetime strings: - -.. ipython:: python - - da.sel(time='0001') - da.sel(time=slice('0001-05', '0002-02')) - -- Access of basic datetime components via the ``dt`` accessor (in this case - just "year", "month", "day", "hour", "minute", "second", "microsecond", - "season", "dayofyear", and "dayofweek"): - -.. ipython:: python - - da.time.dt.year - da.time.dt.month - da.time.dt.season - da.time.dt.dayofyear - da.time.dt.dayofweek - -- Group-by operations based on datetime accessor attributes (e.g. by month of - the year): - -.. ipython:: python - - da.groupby('time.month').sum() - -- Interpolation using :py:class:`cftime.datetime` objects: - -.. ipython:: python - - da.interp(time=[DatetimeNoLeap(1, 1, 15), DatetimeNoLeap(1, 2, 15)]) - -- Interpolation using datetime strings: - -.. ipython:: python - - da.interp(time=['0001-01-15', '0001-02-15']) - -- Differentiation: - -.. ipython:: python - - da.differentiate('time') - -- Serialization: - -.. ipython:: python - - da.to_netcdf('example-no-leap.nc') - xr.open_dataset('example-no-leap.nc') - -- And resampling along the time dimension for data indexed by a :py:class:`~xarray.CFTimeIndex`: - -.. ipython:: python - - da.resample(time='81T', closed='right', label='right', base=3).mean() - -.. note:: - - - For some use-cases it may still be useful to convert from - a :py:class:`~xarray.CFTimeIndex` to a :py:class:`pandas.DatetimeIndex`, - despite the difference in calendar types. The recommended way of doing this - is to use the built-in :py:meth:`~xarray.CFTimeIndex.to_datetimeindex` - method: - - .. ipython:: python - :okwarning: - - modern_times = xr.cftime_range('2000', periods=24, freq='MS', calendar='noleap') - da = xr.DataArray(range(24), [('time', modern_times)]) - da - datetimeindex = da.indexes['time'].to_datetimeindex() - da['time'] = datetimeindex - - However in this case one should use caution to only perform operations which - do not depend on differences between dates (e.g. differentiation, - interpolation, or upsampling with resample), as these could introduce subtle - and silent errors due to the difference in calendar types between the dates - encoded in your data and the dates stored in memory. - -.. _Timestamp-valid range: https://pandas.pydata.org/pandas-docs/stable/timeseries.html#timestamp-limitations -.. _ISO 8601-format: https://en.wikipedia.org/wiki/ISO_8601 -.. _partial datetime string indexing: https://pandas.pydata.org/pandas-docs/stable/timeseries.html#partial-string-indexing diff --git a/doc/weather-climate.rst b/doc/weather-climate.rst new file mode 100644 index 00000000000..676705820e6 --- /dev/null +++ b/doc/weather-climate.rst @@ -0,0 +1,159 @@ +.. _weather-climate: + +Weather and climate data +======================== + +.. ipython:: python + :suppress: + + import xarray as xr + +``xarray`` can leverage metadata that follows the `Climate and Forecast (CF) conventions`_ if present. Examples include automatic labelling of plots with descriptive names and units if proper metadata is present (see :ref:`plotting`) and support for non-standard calendars used in climate science through the ``cftime`` module (see :ref:`CFTimeIndex`). There are also a number of geosciences-focused projects that build on xarray (see :ref:`related-projects`). + +.. _Climate and Forecast (CF) conventions: http://cfconventions.org + +.. _metpy_accessor: + +CF-compliant coordinate variables +--------------------------------- + +`MetPy`_ adds a ``metpy`` accessor that allows accessing coordinates with appropriate CF metadata using generic names ``x``, ``y``, ``vertical`` and ``time``. See `their documentation`_ for more information. + +.. _`MetPy`: https://unidata.github.io/MetPy/dev/index.html +.. _`their documentation`: https://unidata.github.io/MetPy/dev/tutorials/xarray_tutorial.html#coordinates + +.. _CFTimeIndex: + +Non-standard calendars and dates outside the Timestamp-valid range +------------------------------------------------------------------ + +Through the standalone ``cftime`` library and a custom subclass of +:py:class:`pandas.Index`, xarray supports a subset of the indexing +functionality enabled through the standard :py:class:`pandas.DatetimeIndex` for +dates from non-standard calendars commonly used in climate science or dates +using a standard calendar, but outside the `Timestamp-valid range`_ +(approximately between years 1678 and 2262). + +.. note:: + + As of xarray version 0.11, by default, :py:class:`cftime.datetime` objects + will be used to represent times (either in indexes, as a + :py:class:`~xarray.CFTimeIndex`, or in data arrays with dtype object) if + any of the following are true: + + - The dates are from a non-standard calendar + - Any dates are outside the Timestamp-valid range. + + Otherwise pandas-compatible dates from a standard calendar will be + represented with the ``np.datetime64[ns]`` data type, enabling the use of a + :py:class:`pandas.DatetimeIndex` or arrays with dtype ``np.datetime64[ns]`` + and their full set of associated features. + +For example, you can create a DataArray indexed by a time +coordinate with dates from a no-leap calendar and a +:py:class:`~xarray.CFTimeIndex` will automatically be used: + +.. ipython:: python + + from itertools import product + from cftime import DatetimeNoLeap + dates = [DatetimeNoLeap(year, month, 1) for year, month in + product(range(1, 3), range(1, 13))] + da = xr.DataArray(np.arange(24), coords=[dates], dims=['time'], name='foo') + +xarray also includes a :py:func:`~xarray.cftime_range` function, which enables +creating a :py:class:`~xarray.CFTimeIndex` with regularly-spaced dates. For +instance, we can create the same dates and DataArray we created above using: + +.. ipython:: python + + dates = xr.cftime_range(start='0001', periods=24, freq='MS', calendar='noleap') + da = xr.DataArray(np.arange(24), coords=[dates], dims=['time'], name='foo') + +For data indexed by a :py:class:`~xarray.CFTimeIndex` xarray currently supports: + +- `Partial datetime string indexing`_ using strictly `ISO 8601-format`_ partial + datetime strings: + +.. ipython:: python + + da.sel(time='0001') + da.sel(time=slice('0001-05', '0002-02')) + +- Access of basic datetime components via the ``dt`` accessor (in this case + just "year", "month", "day", "hour", "minute", "second", "microsecond", + "season", "dayofyear", and "dayofweek"): + +.. ipython:: python + + da.time.dt.year + da.time.dt.month + da.time.dt.season + da.time.dt.dayofyear + da.time.dt.dayofweek + +- Group-by operations based on datetime accessor attributes (e.g. by month of + the year): + +.. ipython:: python + + da.groupby('time.month').sum() + +- Interpolation using :py:class:`cftime.datetime` objects: + +.. ipython:: python + + da.interp(time=[DatetimeNoLeap(1, 1, 15), DatetimeNoLeap(1, 2, 15)]) + +- Interpolation using datetime strings: + +.. ipython:: python + + da.interp(time=['0001-01-15', '0001-02-15']) + +- Differentiation: + +.. ipython:: python + + da.differentiate('time') + +- Serialization: + +.. ipython:: python + + da.to_netcdf('example-no-leap.nc') + xr.open_dataset('example-no-leap.nc') + +- And resampling along the time dimension for data indexed by a :py:class:`~xarray.CFTimeIndex`: + +.. ipython:: python + + da.resample(time='81T', closed='right', label='right', base=3).mean() + +.. note:: + + + For some use-cases it may still be useful to convert from + a :py:class:`~xarray.CFTimeIndex` to a :py:class:`pandas.DatetimeIndex`, + despite the difference in calendar types. The recommended way of doing this + is to use the built-in :py:meth:`~xarray.CFTimeIndex.to_datetimeindex` + method: + + .. ipython:: python + :okwarning: + + modern_times = xr.cftime_range('2000', periods=24, freq='MS', calendar='noleap') + da = xr.DataArray(range(24), [('time', modern_times)]) + da + datetimeindex = da.indexes['time'].to_datetimeindex() + da['time'] = datetimeindex + + However in this case one should use caution to only perform operations which + do not depend on differences between dates (e.g. differentiation, + interpolation, or upsampling with resample), as these could introduce subtle + and silent errors due to the difference in calendar types between the dates + encoded in your data and the dates stored in memory. + +.. _Timestamp-valid range: https://pandas.pydata.org/pandas-docs/stable/timeseries.html#timestamp-limitations +.. _ISO 8601-format: https://en.wikipedia.org/wiki/ISO_8601 +.. _partial datetime string indexing: https://pandas.pydata.org/pandas-docs/stable/timeseries.html#partial-string-indexing From 83f92ac3d6356731e99bdc50261ce3f515d64130 Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 7 Mar 2019 14:04:23 -0800 Subject: [PATCH 13/15] Note open_dataset, mfdataset open files as read-only (closes #2345). --- xarray/backends/api.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/xarray/backends/api.py b/xarray/backends/api.py index 61efcfdedf2..36baa9071c0 100644 --- a/xarray/backends/api.py +++ b/xarray/backends/api.py @@ -247,6 +247,13 @@ def open_dataset(filename_or_obj, group=None, decode_cf=True, dataset : Dataset The newly created dataset. + Notes + ----- + ``open_dataset`` opens the file with read-only access. When you modify + values of a Dataset, even one linked to files on disk, only the in-memory + copy you are manipulating in xarray is modified: the original file on disk + is never touched. + See Also -------- open_mfdataset @@ -597,6 +604,13 @@ def open_mfdataset(paths, chunks=None, concat_dim=_CONCAT_DIM_DEFAULT, ------- xarray.Dataset + Notes + ----- + ``open_mfdataset`` opens files with read-only access. When you modify values + of a Dataset, even one linked to files on disk, only the in-memory copy you + are manipulating in xarray is modified: the original file on disk is never + touched. + See Also -------- auto_combine From a4b1c9f7ce4baf63dcb989159215057191cde945 Mon Sep 17 00:00:00 2001 From: Ryan May Date: Tue, 12 Mar 2019 06:24:23 -0600 Subject: [PATCH 14/15] Update metpy 1 Co-Authored-By: dcherian --- doc/weather-climate.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/weather-climate.rst b/doc/weather-climate.rst index 676705820e6..5d4a413f19e 100644 --- a/doc/weather-climate.rst +++ b/doc/weather-climate.rst @@ -17,7 +17,7 @@ Weather and climate data CF-compliant coordinate variables --------------------------------- -`MetPy`_ adds a ``metpy`` accessor that allows accessing coordinates with appropriate CF metadata using generic names ``x``, ``y``, ``vertical`` and ``time``. See `their documentation`_ for more information. +`MetPy`_ adds a ``metpy`` accessor that allows accessing coordinates with appropriate CF metadata using generic names ``x``, ``y``, ``vertical`` and ``time``. There is also a `cartopy_crs` attribute that provides projection information, parsed from the appropriate CF metadata, as a `Cartopy`_ projection object. See `their documentation`_ for more information. .. _`MetPy`: https://unidata.github.io/MetPy/dev/index.html .. _`their documentation`: https://unidata.github.io/MetPy/dev/tutorials/xarray_tutorial.html#coordinates From e71148e38d0a207d78f7271336d7f089500bbef6 Mon Sep 17 00:00:00 2001 From: Ryan May Date: Tue, 12 Mar 2019 09:00:03 -0600 Subject: [PATCH 15/15] Update doc/weather-climate.rst Co-Authored-By: dcherian --- doc/weather-climate.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/doc/weather-climate.rst b/doc/weather-climate.rst index 5d4a413f19e..1950ba62ffb 100644 --- a/doc/weather-climate.rst +++ b/doc/weather-climate.rst @@ -21,6 +21,7 @@ CF-compliant coordinate variables .. _`MetPy`: https://unidata.github.io/MetPy/dev/index.html .. _`their documentation`: https://unidata.github.io/MetPy/dev/tutorials/xarray_tutorial.html#coordinates +.. _`Cartopy`: https://scitools.org.uk/cartopy/docs/latest/crs/projections.html .. _CFTimeIndex: