Allow a halo to be added by indices and subspace

Author: davidhassell

cf/docstring/docstring.py

@@ -80,6 +80,14 @@
         Whether `esmpy` logging is enabled or not is determined by
         `cf.regrid_logging`. If it is enabled then logging takes place
         after every call. By default logging is disabled.""",
+    # subspace halos
+    "{{subspace halos}}": """
+        If a halo is defined via a positional argument, then each
+        subspaced axis will be extended to include that many extra
+        elements at each "side" of the axis. The number of extra
+        elements will be automatically reduced if including the full
+        amount defined by the halo would extend the subspace beyond
+        the axis limits.""",
     # ----------------------------------------------------------------
     # Method description substitutions (3 levels of indentation)
     # ----------------------------------------------------------------
@@ -613,6 +621,40 @@
     "{{to_size: `int`, optional}}": """to_size: `int`, optional
                 Pad the axis after so that the new axis has the given
                 size.""",
+    # subspace mode options
+    "{{mode: optional}}": """mode: optional
+                Specify the mode of operation (``mode``) and a halo to
+                be added to the subspaced axes (``halo``) with
+                positional arguments in format ``mode``, or ``halo``,
+                or ``mode, halo``, or with no positional arguments at
+                all.
+
+                A mode of operation is given as a `str`, and a halo as
+                a non-negative `int` (or any object that can be
+                converted to one):
+
+                ==============  ======================================
+                *mode*          Description
+                ==============  ======================================
+                ````            If no positional arguments are
+                                provided then assume the
+                                ``'compress'`` mode of operation with
+                                no halo added to the subspaced
+                                axes.
+
+                ``mode``        Define the mode of operation with no
+                                halo added to the subspaced axes.
+
+                ``mode, halo``  Define a mode of operation, as well as
+                                a halo to be added to the subspaced
+                                axes.
+
+                ``halo``        Assume the ``'compress'`` mode of
+                                operation and define a halo to be
+                                added to the subspaced axes. Note that
+                                ``halo`` is equivalent to
+                                ``'compress', halo``.
+                ==============  ======================================""",
     # ----------------------------------------------------------------
     # Method description substitutions (4 levels of indentation)
     # ----------------------------------------------------------------
@@ -663,4 +705,42 @@
                 The removed CFA-netCDF file name substitution. If the
                 substitution was not defined then an empty dictionary
                 is returned.""",
+    # subspace valid modes Field
+    "{{subspace valid modes Field}}": """Valid modes are:
+
+                * ``'compress'`` This the default.
+                     Unselected locations are removed to create the
+                     subspace. If the result is not hyperrectangular
+                     then the minimum amount of unselected locations
+                     required to make it so will also be specially
+                     selected. Missing data is inserted at the
+                     specially selected locations, unless a halo has
+                     been defined (of any size, including 0).
+
+                * ``'envelope'``
+                     The subspace is the smallest hyperrectangular
+                     subspace that contains all of the selected
+                     locations. Missing data is inserted at unselected
+                     locations within the envelope, unless a halo has
+                     been defined (of any size, including 0).
+
+                * ``'full'``
+                     The subspace has the same domain as the original
+                     construct. Missing data is inserted at unselected
+                     locations, unless a halo has been defined (of any
+                     size, including 0).""",
+    # subspace valid modes Domain
+    "{{subspace valid modes Domain}}": """Valid modes are:
+
+                * ``'compress'`` This the default.
+                     Unselected locations are removed to create the
+                     subspace. If the result is not hyperrectangular
+                     then the minimum amount of unselected locations
+                     required to make it so will also be specially
+                     selected.
+
+                * ``'envelope'``
+                     The subspace is the smallest hyperrectangular
+                     subspace that contains all of the selected
+                     locations.""",
 }

cf/domain.py

@@ -743,7 +743,7 @@ def indices(self, *mode, **kwargs):
         """Create indices that define a subspace of the domain
         construct.
 
-        The indices returned by this method be used to create the
+        The indices returned by this method may be used to create the
         subspace by passing them to the `subspace` method of the
         original domain construct.
 
@@ -778,34 +778,22 @@ def indices(self, *mode, **kwargs):
           may still need to be inserted into the field construct's
           data.
 
+        **Halos**
+
+        {{subspace halos}}
+
         .. versionadded:: 3.11.0
 
         .. seealso:: `subspace`, `where`, `__getitem__`,
                      `__setitem__`, `cf.Field.indices`
 
         :Parameters:
 
-            mode: `str`, *optional*
-                There are two modes of operation, each of which provides
-                indices for a different type of subspace:
-
-                ==============  ======================================
-                *mode*          Description
-                ==============  ======================================
-                ``'compress'``  This is the default mode. Unselected
-                                locations are removed to create the
-                                returned subspace. Note that if a
-                                multi-dimensional metadata construct
-                                is being used to define the indices
-                                then some missing data may still be
-                                inserted at unselected locations.
-
-                ``'envelope'``  The returned subspace is the smallest
-                                that contains all of the selected
-                                indices.
-                ==============  ======================================
-
-            kwargs: *optional*
+            {{mode: optional}}
+
+                {{subspace valid modes Domain}}
+
+            kwargs: optional
                 A keyword name is an identity of a metadata construct,
                 and the keyword value provides a condition for
                 inferring indices that apply to the dimension (or
@@ -857,19 +845,6 @@ def indices(self, *mode, **kwargs):
                         : time(1) = [2019-01-01 00:00:00]
 
         """
-        if len(mode) > 1:
-            raise ValueError(
-                "Can't provide more than one positional argument. "
-                f"Got: {', '.join(repr(x) for x in mode)}"
-            )
-
-        if not mode or "compress" in mode:
-            mode = "compress"
-        elif "envelope" in mode:
-            mode = "envelope"
-        else:
-            raise ValueError(f"Invalid value for 'mode' argument: {mode[0]!r}")
-
         # Get the indices for every domain axis in the domain, without
         # any auxiliary masks.
         domain_indices = self._indices(mode, None, False, kwargs)
@@ -1120,19 +1095,19 @@ def roll(self, axis, shift, inplace=False):
         return d
 
     def subspace(self, *mode, **kwargs):
-        """Create indices that define a subspace of the domain
-        construct.
+        """Create a subspace of the field construct.
 
-        The indices returned by this method be used to create the subspace
-        by passing them to the `subspace` method of the original domain
-        construct.
+        Creation of a new domain construct which spans a subspace of
+        the domain of an existing domain construct is achieved by
+        identifying indices based on the metadata constructs
+        (subspacing by metadata). The new domain construct is created
+        with the same properties as the original domain construct.
 
-        The subspace is defined by identifying indices based on the
-        metadata constructs.
+        **Subspacing by metadata**
 
-        Metadata constructs are selected conditions are specified on their
-        data. Indices for subspacing are then automatically inferred from
-        where the conditions are met.
+        Subspacing by metadata selects metadata constructs and
+        specifies conditions on their data. Indices for subspacing are
+        then automatically inferred from where the conditions are met.
 
         Metadata constructs and the conditions on their data are defined
         by keyword parameters.
@@ -1142,6 +1117,9 @@ def subspace(self, *mode, **kwargs):
         * Multiple domain axes may be subspaced simultaneously, and it
           doesn't matter which order they are specified in.
 
+        * Subspace criteria may be provided for size 1 domain axes that
+          are not spanned by the field construct's data.
+
         * Explicit indices may also be assigned to a domain axis
           identified by a metadata construct, with either a Python `slice`
           object, or a sequence of integers or booleans.
@@ -1156,41 +1134,21 @@ def subspace(self, *mode, **kwargs):
           acting along orthogonal dimensions, some missing data may still
           need to be inserted into the field construct's data.
 
-        .. versionadded:: 3.11.0
-
-        .. seealso:: `indices`
-
-        :Parameters:
+        **Halos**
 
-            mode: `str`, *optional*
-                There are two modes of operation, each of which provides
-                indices for a different type of subspace:
+        {{subspace halos}}
 
-                ==============  ==========================================
-                *mode*          Description
-                ==============  ==========================================
-                ``'compress'``  Return indices that identify only the
-                                requested locations.
+        .. versionadded:: 3.11.0
 
-                                This is the default mode.
+        .. seealso:: `indices`, `cf.Field.subspace`
 
-                                Note that if a multi-dimensional metadata
-                                construct is being used to define the
-                                indices then some unrequested locations
-                                may also be selected.
+        :Parameters:
 
-                ``'envelope'``  The returned subspace is the smallest that
-                                contains all of the requested locations.
+            {{mode: optional}}
 
-                ``'test'``      May be used on its own or in addition to
-                                one of the other positional arguments. Do
-                                not create a subspace, but return `True`
-                                or `False` depending on whether or not it
-                                is possible to create the specified
-                                subspace.
-                ==============  ==========================================
+                {{subspace valid modes Domain}}
 
-            kwargs: *optional*
+            kwargs: optional
                 A keyword name is an identity of a metadata construct, and
                 the keyword value provides a condition for inferring
                 indices that apply to the dimension (or dimensions)