From 0398801c1a3cb125f385616d031f6e947a4509ae Mon Sep 17 00:00:00 2001 From: dcherian Date: Mon, 30 Sep 2019 09:57:50 -0600 Subject: [PATCH 1/6] Add how do I ... section --- doc/_static/style.css | 9 +++++++++ doc/howdoi.rst | 47 +++++++++++++++++++++++++++++++++++++++++++ doc/index.rst | 2 ++ 3 files changed, 58 insertions(+) create mode 100644 doc/howdoi.rst diff --git a/doc/_static/style.css b/doc/_static/style.css index 7257d57db66..b7d30f429cf 100644 --- a/doc/_static/style.css +++ b/doc/_static/style.css @@ -16,3 +16,12 @@ .wy-nav-top { background-color: #555; } + +table.colwidths-given { + table-layout: fixed; + width: 100%; +} +table.docutils td { + white-space: unset; + word-wrap: break-word; +} diff --git a/doc/howdoi.rst b/doc/howdoi.rst new file mode 100644 index 00000000000..1cae6affeda --- /dev/null +++ b/doc/howdoi.rst @@ -0,0 +1,47 @@ +.. currentmodule:: xarray + +How do I ... +============ + +.. list-table:: + :header-rows: 1 + :widths: 40 60 + + * - How do I... + - Solution + * - add variables from other datasets to my dataset + - :py:meth:`Dataset.merge` + * - add a new dimension and/or coordinate + - :py:meth:`DataArray.expand_dims`, :py:meth:`Dataset.expand_dims` + * - add a new coordinate variable + - :py:meth:`DataArray.assign_coords` + * - change a data variable to a coordinate variables + - :py:meth:`Dataset.set_coords` + * - change the order of dimensions + - :py:meth:`DataArray.transpose`, :py:meth:`Dataset.transpose` + * - remove a variable from my object + - :py:meth:`Dataset.drop`, :py:meth:`DataArray.drop` + * - remove dimensions of length 1 + - :py:meth:`DataArray.squeeze`, :py:meth:`Dataset.squeeze` + * - convert non-dimension coordinates to data variables or remove them + - :py:meth:`DataArray.reset_coords`, :py:meth:`Dataset.reset_coords` + * - rename a variable, dimension or coordinate + - :py:meth:`Dataset.rename`, :py:meth:`DataArray.rename_dims`, :py:meth:`DataArray.rename_coords` + * - convert a DataArray to Dataset or vice versa + - :py:meth:`DataArray.to_dataset`, :py:meth:`Dataset.to_array` + * - extract the underlying array (e.g. numpy or Dask arrays) + - :py:attr:`DataArray.data` + * - convert to and extract the underlying numpy array + - :py:attr:`DataArray.values` + * - find out if my xarray object is wrapping a Dask Array + - :py:func:`dask.is_dask_collection` + * - know how much memory my object requires + - :py:attr:`DataArray.nbytes`, :py:attr:`Dataset.nbytes` + * - convert a possibly irregularly sampled timeseries to a regularly sampled timeseries + - :py:meth:`DataArray.resample`, :py:meth:`Dataset.resample` + * - apply a function on all data variables in a Dataset + - :py:meth:`Dataset.apply` + * - write xarray objects with complex values to a netCDF file + - :py:func:`Dataset.to_netcdf`, :py:func:`DataArray.to_netcdf` specifying ``engine="h5netcdf", invalid_netcdf=True`` + * - make xarray objects look like other xarray objects + - :py:func:`~xarray.ones_like`, :py:func:`~xarray.zeros_like`, :py:func:`~xarray.full_like`, :py:func:`Dataset.reindex_like`, :py:meth:`Dataset.interpolate_like`, :py:meth:`Dataset.broadcast_like`, :py:func:`DataArray.reindex_like`, :py:meth:`DataArray.interpolate_like`, :py:meth:`DataArray.broadcast_like` diff --git a/doc/index.rst b/doc/index.rst index 4cf67a37f4c..e5bd03801ff 100644 --- a/doc/index.rst +++ b/doc/index.rst @@ -84,6 +84,7 @@ Documentation **Help & reference** * :doc:`whats-new` +* :doc:`howdoi` * :doc:`api` * :doc:`internals` * :doc:`roadmap` @@ -96,6 +97,7 @@ Documentation :caption: Help & reference whats-new + howdoi api internals roadmap From 6935665b918c458b60d4abb06b5442aa932e007c Mon Sep 17 00:00:00 2001 From: dcherian Date: Mon, 30 Sep 2019 10:09:18 -0600 Subject: [PATCH 2/6] Bbugfix. --- doc/howdoi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/howdoi.rst b/doc/howdoi.rst index 1cae6affeda..399476fb2e3 100644 --- a/doc/howdoi.rst +++ b/doc/howdoi.rst @@ -26,7 +26,7 @@ How do I ... * - convert non-dimension coordinates to data variables or remove them - :py:meth:`DataArray.reset_coords`, :py:meth:`Dataset.reset_coords` * - rename a variable, dimension or coordinate - - :py:meth:`Dataset.rename`, :py:meth:`DataArray.rename_dims`, :py:meth:`DataArray.rename_coords` + - :py:meth:`Dataset.rename`, :py:meth:`DataArray.rename`, :py:meth:`Dataset.rename_vars`, :py:meth:`Dataset.rename_dims`, * - convert a DataArray to Dataset or vice versa - :py:meth:`DataArray.to_dataset`, :py:meth:`Dataset.to_array` * - extract the underlying array (e.g. numpy or Dask arrays) From 46691f57d30459c325650ffe1bb4c226cd238054 Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Mon, 30 Sep 2019 16:55:12 +0000 Subject: [PATCH 3/6] Update doc/howdoi.rst Co-Authored-By: Maximilian Roos <5635139+max-sixty@users.noreply.github.com> --- doc/howdoi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/howdoi.rst b/doc/howdoi.rst index 399476fb2e3..17e2cd579dc 100644 --- a/doc/howdoi.rst +++ b/doc/howdoi.rst @@ -21,7 +21,7 @@ How do I ... - :py:meth:`DataArray.transpose`, :py:meth:`Dataset.transpose` * - remove a variable from my object - :py:meth:`Dataset.drop`, :py:meth:`DataArray.drop` - * - remove dimensions of length 1 + * - remove dimensions of length 1 or 0 - :py:meth:`DataArray.squeeze`, :py:meth:`Dataset.squeeze` * - convert non-dimension coordinates to data variables or remove them - :py:meth:`DataArray.reset_coords`, :py:meth:`Dataset.reset_coords` From 28d181c2c92a2e2b6735374874f6503634d86d6b Mon Sep 17 00:00:00 2001 From: Deepak Cherian Date: Mon, 30 Sep 2019 16:55:20 +0000 Subject: [PATCH 4/6] Update doc/howdoi.rst Co-Authored-By: Maximilian Roos <5635139+max-sixty@users.noreply.github.com> --- doc/howdoi.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/howdoi.rst b/doc/howdoi.rst index 17e2cd579dc..5cc5446ba59 100644 --- a/doc/howdoi.rst +++ b/doc/howdoi.rst @@ -15,7 +15,7 @@ How do I ... - :py:meth:`DataArray.expand_dims`, :py:meth:`Dataset.expand_dims` * - add a new coordinate variable - :py:meth:`DataArray.assign_coords` - * - change a data variable to a coordinate variables + * - change a data variable to a coordinate variable - :py:meth:`Dataset.set_coords` * - change the order of dimensions - :py:meth:`DataArray.transpose`, :py:meth:`Dataset.transpose` From 81817b018dc992adec9673b192e28e74cad25a21 Mon Sep 17 00:00:00 2001 From: dcherian Date: Mon, 30 Sep 2019 13:44:14 -0600 Subject: [PATCH 5/6] small updates. --- doc/howdoi.rst | 10 +++++++--- doc/whats-new.rst | 3 ++- 2 files changed, 9 insertions(+), 4 deletions(-) diff --git a/doc/howdoi.rst b/doc/howdoi.rst index 5cc5446ba59..71b51492bc9 100644 --- a/doc/howdoi.rst +++ b/doc/howdoi.rst @@ -1,5 +1,7 @@ .. currentmodule:: xarray +.. _howdoi: + How do I ... ============ @@ -21,8 +23,8 @@ How do I ... - :py:meth:`DataArray.transpose`, :py:meth:`Dataset.transpose` * - remove a variable from my object - :py:meth:`Dataset.drop`, :py:meth:`DataArray.drop` - * - remove dimensions of length 1 or 0 - - :py:meth:`DataArray.squeeze`, :py:meth:`Dataset.squeeze` + * - remove dimensions of length 1 or 0 + - :py:meth:`DataArray.squeeze`, :py:meth:`Dataset.squeeze` * - convert non-dimension coordinates to data variables or remove them - :py:meth:`DataArray.reset_coords`, :py:meth:`Dataset.reset_coords` * - rename a variable, dimension or coordinate @@ -44,4 +46,6 @@ How do I ... * - write xarray objects with complex values to a netCDF file - :py:func:`Dataset.to_netcdf`, :py:func:`DataArray.to_netcdf` specifying ``engine="h5netcdf", invalid_netcdf=True`` * - make xarray objects look like other xarray objects - - :py:func:`~xarray.ones_like`, :py:func:`~xarray.zeros_like`, :py:func:`~xarray.full_like`, :py:func:`Dataset.reindex_like`, :py:meth:`Dataset.interpolate_like`, :py:meth:`Dataset.broadcast_like`, :py:func:`DataArray.reindex_like`, :py:meth:`DataArray.interpolate_like`, :py:meth:`DataArray.broadcast_like` + - :py:func:`~xarray.ones_like`, :py:func:`~xarray.zeros_like`, :py:func:`~xarray.full_like`, :py:meth:`Dataset.reindex_like`, :py:meth:`Dataset.interpolate_like`, :py:meth:`Dataset.broadcast_like`, :py:meth:`DataArray.reindex_like`, :py:meth:`DataArray.interpolate_like`, :py:meth:`DataArray.broadcast_like` + * - replace NaNs with other values + - :py:meth:`~Dataset.fillna`, :py:meth:`Dataset.interpolate_na`, :py:meth:`~DataArray.fillna`, :py:meth:`DataArray.interpolate_na` diff --git a/doc/whats-new.rst b/doc/whats-new.rst index 33410f82c2c..f9c952f6752 100644 --- a/doc/whats-new.rst +++ b/doc/whats-new.rst @@ -33,7 +33,8 @@ Documentation - Created a glossary of important xarray terms (:issue:`2410`, :pull:`3352`). By `Gregory Gundersen `_. - +- Created a "How do I..." section (:ref:`howdoi`) for solutions to common questions. (:pull:`3357`). + By `Deepak Cherian `_. - Add examples for :py:meth:`Dataset.swap_dims` and :py:meth:`DataArray.swap_dims`. By `Justus Magin `_. - Add examples for :py:meth:`align`, :py:meth:`merge`, :py:meth:`combine_by_coords`, From 459e3fe3edfa3fa209ab6061ff14d22731aea896 Mon Sep 17 00:00:00 2001 From: dcherian Date: Mon, 30 Sep 2019 13:57:39 -0600 Subject: [PATCH 6/6] Add more. --- doc/howdoi.rst | 12 ++++++++++-- doc/time-series.rst | 2 ++ 2 files changed, 12 insertions(+), 2 deletions(-) diff --git a/doc/howdoi.rst b/doc/howdoi.rst index 71b51492bc9..721d1323e73 100644 --- a/doc/howdoi.rst +++ b/doc/howdoi.rst @@ -25,6 +25,8 @@ How do I ... - :py:meth:`Dataset.drop`, :py:meth:`DataArray.drop` * - remove dimensions of length 1 or 0 - :py:meth:`DataArray.squeeze`, :py:meth:`Dataset.squeeze` + * - remove all variables with a particular dimension + - :py:meth:`Dataset.drop_dims` * - convert non-dimension coordinates to data variables or remove them - :py:meth:`DataArray.reset_coords`, :py:meth:`Dataset.reset_coords` * - rename a variable, dimension or coordinate @@ -40,7 +42,7 @@ How do I ... * - know how much memory my object requires - :py:attr:`DataArray.nbytes`, :py:attr:`Dataset.nbytes` * - convert a possibly irregularly sampled timeseries to a regularly sampled timeseries - - :py:meth:`DataArray.resample`, :py:meth:`Dataset.resample` + - :py:meth:`DataArray.resample`, :py:meth:`Dataset.resample` (see :ref:`resampling` for more) * - apply a function on all data variables in a Dataset - :py:meth:`Dataset.apply` * - write xarray objects with complex values to a netCDF file @@ -48,4 +50,10 @@ How do I ... * - make xarray objects look like other xarray objects - :py:func:`~xarray.ones_like`, :py:func:`~xarray.zeros_like`, :py:func:`~xarray.full_like`, :py:meth:`Dataset.reindex_like`, :py:meth:`Dataset.interpolate_like`, :py:meth:`Dataset.broadcast_like`, :py:meth:`DataArray.reindex_like`, :py:meth:`DataArray.interpolate_like`, :py:meth:`DataArray.broadcast_like` * - replace NaNs with other values - - :py:meth:`~Dataset.fillna`, :py:meth:`Dataset.interpolate_na`, :py:meth:`~DataArray.fillna`, :py:meth:`DataArray.interpolate_na` + - :py:meth:`Dataset.fillna`, :py:meth:`Dataset.ffill`, :py:meth:`Dataset.bfill`, :py:meth:`Dataset.interpolate_na`, :py:meth:`DataArray.fillna`, :py:meth:`DataArray.ffill`, :py:meth:`DataArray.bfill`, :py:meth:`DataArray.interpolate_na` + * - extract the year, month, day or similar from a DataArray of time values + - ``obj.dt.month`` for example where ``obj`` is a :py:class:`~xarray.DataArray` containing ``datetime64`` or ``cftime`` values. See :ref:`dt_accessor` for more. + * - round off time values to a specified frequency + - ``obj.dt.ceil``, ``obj.dt.floor``, ``obj.dt.round``. See :ref:`dt_accessor` for more. + * - make a mask that is ``True`` where an object contains any of the values in a array + - :py:meth:`Dataset.isin`, :py:meth:`DataArray.isin` diff --git a/doc/time-series.rst b/doc/time-series.rst index e198887dd0d..1cb535ea886 100644 --- a/doc/time-series.rst +++ b/doc/time-series.rst @@ -101,6 +101,8 @@ You can also select a particular time by indexing with a For more details, read the pandas documentation. +.. _dt_accessor: + Datetime components -------------------