From d0a283d0b279a52d4c9c87a6fae902329c9d460b Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 28 Oct 2021 05:20:39 -0600 Subject: [PATCH 1/5] [skip-ci] Update docstring for set_options Add use_bottleneck. Alphabetize. --- xarray/core/options.py | 49 ++++++++++++++++++++++-------------------- 1 file changed, 26 insertions(+), 23 deletions(-) diff --git a/xarray/core/options.py b/xarray/core/options.py index 14f77306316..3e2df379c55 100644 --- a/xarray/core/options.py +++ b/xarray/core/options.py @@ -158,20 +158,8 @@ class set_options: Parameters ---------- - display_width : int, default: 80 - Maximum display width for ``repr`` on xarray objects. - display_max_rows : int, default: 12 - Maximum display rows. - arithmetic_join : {"inner", "outer", "left", "right", "exact"} + arithmetic_join : {"inner", "outer", "left", "right", "exact"}, default: "inner" DataArray/Dataset alignment in binary operations. - file_cache_maxsize : int, default: 128 - Maximum number of open files to hold in xarray's - global least-recently-usage cached. This should be smaller than - your system's per-process file descriptor limit, e.g., - ``ulimit -n`` on Linux. - warn_for_unclosed_files : bool, default: False - Whether or not to issue a warning when unclosed files are - deallocated. This is mostly useful for debugging. cmap_sequential : str or matplotlib.colors.Colormap, default: "viridis" Colormap to use for nondivergent data plots. If string, must be matplotlib built-in colormap. Can also be a Colormap object @@ -180,16 +168,6 @@ class set_options: Colormap to use for divergent data plots. If string, must be matplotlib built-in colormap. Can also be a Colormap object (e.g. mpl.cm.magma) - keep_attrs : {"default", True, False} - Whether to keep attributes on xarray Datasets/dataarrays after - operations. Can be - - * ``True`` : to always keep attrs - * ``False`` : to always discard attrs - * ``default`` : to use original logic that attrs should only - be kept in unambiguous circumstances - display_style : {"text", "html"} - Display style to use in jupyter for xarray objects. display_expand_attrs : {"default", True, False}: Whether to expand the attributes section for display of ``DataArray`` or ``Dataset`` objects. Can be @@ -218,6 +196,31 @@ class set_options: * ``True`` : to always expand data variables * ``False`` : to always collapse data variables * ``default`` : to expand unless over a pre-defined limit + display_max_rows : int, default: 12 + Maximum display rows. + display_style : {"text", "html"}, default: "html" + Display style to use in jupyter for xarray objects. + display_width : int, default: 80 + Maximum display width for ``repr`` on xarray objects. + file_cache_maxsize : int, default: 128 + Maximum number of open files to hold in xarray's + global least-recently-usage cached. This should be smaller than + your system's per-process file descriptor limit, e.g., + ``ulimit -n`` on Linux. + keep_attrs : {"default", True, False} + Whether to keep attributes on xarray Datasets/dataarrays after + operations. Can be + + * ``True`` : to always keep attrs + * ``False`` : to always discard attrs + * ``default`` : to use original logic that attrs should only + be kept in unambiguous circumstances + use_bottleneck : bool, default: True + Whether to use ``bottleneck`` to accelerate 1D reductions and + 1D rolling reduction operations. + warn_for_unclosed_files : bool, default: False + Whether or not to issue a warning when unclosed files are + deallocated. This is mostly useful for debugging. Examples -------- From c002509053246d88c62fbc7e6cbd0caf6816cd50 Mon Sep 17 00:00:00 2001 From: dcherian Date: Wed, 27 Oct 2021 10:09:12 -0700 Subject: [PATCH 2/5] [skip-ci] Update apply_ufunc docstring --- xarray/core/computation.py | 25 +++++++++++++------------ 1 file changed, 13 insertions(+), 12 deletions(-) diff --git a/xarray/core/computation.py b/xarray/core/computation.py index 7f60da7e1b2..48015bf7541 100644 --- a/xarray/core/computation.py +++ b/xarray/core/computation.py @@ -840,7 +840,7 @@ def apply_ufunc( the style of NumPy universal functions [1]_ (if this is not the case, set ``vectorize=True``). If this function returns multiple outputs, you must set ``output_core_dims`` as well. - *args : Dataset, DataArray, GroupBy, Variable, numpy.ndarray, dask.array.Array or scalar + *args : Dataset, DataArray, DataArrayGroupBy, DatasetGroupBy, Variable, numpy.ndarray, dask.array.Array or scalar Mix of labeled and/or unlabeled arrays to which to apply the function. input_core_dims : sequence of sequence, optional List of the same length as ``args`` giving the list of core dimensions @@ -911,16 +911,16 @@ def apply_ufunc( - 'allowed': pass dask arrays directly on to ``func``. Prefer this option if ``func`` natively supports dask arrays. - 'parallelized': automatically parallelize ``func`` if any of the - inputs are a dask array by using `dask.array.apply_gufunc`. Multiple output + inputs are a dask array by using :py:func:`dask.array.apply_gufunc`. Multiple output arguments are supported. Only use this option if ``func`` does not natively support dask arrays (e.g. converts them to numpy arrays). dask_gufunc_kwargs : dict, optional - Optional keyword arguments passed to ``dask.array.apply_gufunc`` if + Optional keyword arguments passed to :py:func:`dask.array.apply_gufunc` if dask='parallelized'. Possible keywords are ``output_sizes``, ``allow_rechunk`` and ``meta``. output_dtypes : list of dtype, optional Optional list of output dtypes. Only used if ``dask='parallelized'`` or - vectorize=True. + ``vectorize=True``. output_sizes : dict, optional Optional mapping from dimension names to sizes for outputs. Only used if dask='parallelized' and new dimensions (not found on inputs) appear @@ -928,7 +928,7 @@ def apply_ufunc( parameter. It will be removed as direct parameter in a future version. meta : optional Size-0 object representing the type of array wrapped by dask array. Passed on to - ``dask.array.apply_gufunc``. ``meta`` should be given in the + :py:func:`dask.array.apply_gufunc`. ``meta`` should be given in the ``dask_gufunc_kwargs`` parameter . It will be removed as direct parameter a future version. @@ -943,7 +943,7 @@ def apply_ufunc( arrays. If ``func`` needs to manipulate a whole xarray object subset to each block it is possible to use :py:func:`xarray.map_blocks`. - Note that due to the overhead ``map_blocks`` is considerably slower than ``apply_ufunc``. + Note that due to the overhead :py:func:`xarray.map_blocks` is considerably slower than ``apply_ufunc``. Examples -------- @@ -954,7 +954,7 @@ def apply_ufunc( ... return xr.apply_ufunc(func, a, b) ... - You can now apply ``magnitude()`` to ``xr.DataArray`` and ``xr.Dataset`` + You can now apply ``magnitude()`` to :py:class:`DataArray` and :py:class:`Dataset` objects, with automatically preserved dimensions and coordinates, e.g., >>> array = xr.DataArray([1, 2, 3], coords=[("x", [0.1, 0.2, 0.3])]) @@ -989,7 +989,7 @@ def apply_ufunc( ... ) ... - Inner product over a specific dimension (like ``xr.dot``): + Inner product over a specific dimension (like :py:func:`dot`): >>> def _inner(x, y): ... result = np.matmul(x[..., np.newaxis, :], y[..., :, np.newaxis]) @@ -999,7 +999,7 @@ def apply_ufunc( ... return apply_ufunc(_inner, a, b, input_core_dims=[[dim], [dim]]) ... - Stack objects along a new dimension (like ``xr.concat``): + Stack objects along a new dimension (like :py:func:`concat`): >>> def stack(objects, dim, new_coord): ... # note: this version does not stack coordinates @@ -1034,9 +1034,9 @@ def apply_ufunc( ... Most of NumPy's builtin functions already broadcast their inputs - appropriately for use in `apply`. You may find helper functions such as - numpy.broadcast_arrays helpful in writing your function. `apply_ufunc` also - works well with numba's vectorize and guvectorize. Further explanation with + appropriately for use in ``apply_ufunc``. You may find helper functions such as + :py:func:`numpy.broadcast_arrays` helpful in writing your function. ``apply_ufunc`` also + works well with :py:func:`numba.vectorize` and :py:func:`numba.guvectorize`. Further explanation with examples are provided in the xarray documentation [3]_. See Also @@ -1046,6 +1046,7 @@ def apply_ufunc( numba.guvectorize dask.array.apply_gufunc xarray.map_blocks + :ref:`dask.automatic-parallelization` References ---------- From 72dcea6d88936be9064ce9fcec5f55174bf7696a Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 28 Oct 2021 05:39:28 -0600 Subject: [PATCH 3/5] [skip-ci] fix links --- doc/conf.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/doc/conf.py b/doc/conf.py index 77387dfd965..51eb4e2ae1b 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -147,14 +147,18 @@ "matplotlib colormap name": ":doc:`matplotlib colormap name `", "matplotlib axes object": ":py:class:`matplotlib axes object `", "colormap": ":py:class:`colormap `", - # objects without namespace + # objects without namespace: xarray "DataArray": "~xarray.DataArray", "Dataset": "~xarray.Dataset", "Variable": "~xarray.Variable", + "DatasetGroupBy": "~xarray.core.weighted.DatasetGroupBy", + "DataArrayGroupBy": "~xarray.core.weighted.DataArrayGroupBy", + # objects without namespace: numpy "ndarray": "~numpy.ndarray", "MaskedArray": "~numpy.ma.MaskedArray", "dtype": "~numpy.dtype", "ComplexWarning": "~numpy.ComplexWarning", + # objects without namespace: pandas "Index": "~pandas.Index", "MultiIndex": "~pandas.MultiIndex", "CategoricalIndex": "~pandas.CategoricalIndex", From 7b3fb241ad5420cc9bc143d3c1cd9ca3649e728c Mon Sep 17 00:00:00 2001 From: dcherian Date: Thu, 28 Oct 2021 06:43:09 -0600 Subject: [PATCH 4/5] [skip-ci] minor updates --- doc/conf.py | 4 ++-- xarray/core/computation.py | 5 ++--- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/doc/conf.py b/doc/conf.py index 51eb4e2ae1b..93174c6aaec 100644 --- a/doc/conf.py +++ b/doc/conf.py @@ -151,8 +151,8 @@ "DataArray": "~xarray.DataArray", "Dataset": "~xarray.Dataset", "Variable": "~xarray.Variable", - "DatasetGroupBy": "~xarray.core.weighted.DatasetGroupBy", - "DataArrayGroupBy": "~xarray.core.weighted.DataArrayGroupBy", + "DatasetGroupBy": "~xarray.core.groupby.DatasetGroupBy", + "DataArrayGroupBy": "~xarray.core.groupby.DataArrayGroupBy", # objects without namespace: numpy "ndarray": "~numpy.ndarray", "MaskedArray": "~numpy.ma.MaskedArray", diff --git a/xarray/core/computation.py b/xarray/core/computation.py index 48015bf7541..0c21ca07744 100644 --- a/xarray/core/computation.py +++ b/xarray/core/computation.py @@ -1036,8 +1036,7 @@ def apply_ufunc( Most of NumPy's builtin functions already broadcast their inputs appropriately for use in ``apply_ufunc``. You may find helper functions such as :py:func:`numpy.broadcast_arrays` helpful in writing your function. ``apply_ufunc`` also - works well with :py:func:`numba.vectorize` and :py:func:`numba.guvectorize`. Further explanation with - examples are provided in the xarray documentation [3]_. + works well with :py:func:`numba.vectorize` and :py:func:`numba.guvectorize`. See Also -------- @@ -1047,12 +1046,12 @@ def apply_ufunc( dask.array.apply_gufunc xarray.map_blocks :ref:`dask.automatic-parallelization` + User guide describing :py:func:`apply_ufunc` and :py:func:`map_blocks`. References ---------- .. [1] http://docs.scipy.org/doc/numpy/reference/ufuncs.html .. [2] http://docs.scipy.org/doc/numpy/reference/c-api.generalized-ufuncs.html - .. [3] http://xarray.pydata.org/en/stable/computation.html#wrapping-custom-computation """ from .dataarray import DataArray from .groupby import GroupBy From e5f534dc36db25668715d863429803269af52e34 Mon Sep 17 00:00:00 2001 From: dcherian Date: Fri, 29 Oct 2021 15:05:50 -0600 Subject: [PATCH 5/5] review feedback --- xarray/core/options.py | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/xarray/core/options.py b/xarray/core/options.py index 6a321d4bd2a..90018c51807 100644 --- a/xarray/core/options.py +++ b/xarray/core/options.py @@ -51,8 +51,8 @@ class T_Options(TypedDict): "enable_cftimeindex": True, "file_cache_maxsize": 128, "keep_attrs": "default", - "warn_for_unclosed_files": False, "use_bottleneck": True, + "warn_for_unclosed_files": False, } _JOIN_OPTIONS = frozenset(["inner", "outer", "left", "right", "exact"]) @@ -75,8 +75,8 @@ def _positive_integer(value): "enable_cftimeindex": lambda value: isinstance(value, bool), "file_cache_maxsize": _positive_integer, "keep_attrs": lambda choice: choice in [True, False, "default"], - "warn_for_unclosed_files": lambda value: isinstance(value, bool), "use_bottleneck": lambda value: isinstance(value, bool), + "warn_for_unclosed_files": lambda value: isinstance(value, bool), } @@ -125,14 +125,14 @@ class set_options: ---------- arithmetic_join : {"inner", "outer", "left", "right", "exact"}, default: "inner" DataArray/Dataset alignment in binary operations. - cmap_sequential : str or matplotlib.colors.Colormap, default: "viridis" - Colormap to use for nondivergent data plots. If string, must be - matplotlib built-in colormap. Can also be a Colormap object - (e.g. mpl.cm.magma) cmap_divergent : str or matplotlib.colors.Colormap, default: "RdBu_r" Colormap to use for divergent data plots. If string, must be matplotlib built-in colormap. Can also be a Colormap object (e.g. mpl.cm.magma) + cmap_sequential : str or matplotlib.colors.Colormap, default: "viridis" + Colormap to use for nondivergent data plots. If string, must be + matplotlib built-in colormap. Can also be a Colormap object + (e.g. mpl.cm.magma) display_expand_attrs : {"default", True, False}: Whether to expand the attributes section for display of ``DataArray`` or ``Dataset`` objects. Can be