Documenting the new shape subsetting

cis/data_io/gridded_data.py

@@ -323,9 +323,29 @@ def collapsed(self, coords, how=None, **kwargs):
 
     def subset(self, **kwargs):
         """
-        Subset the CommonData object based on the specified constraints
-        :param kwargs:
-        :return:
+        Subset the data based on the specified constraints. Note that the limits are inclusive.
+
+        The subset region is defined by passing keyword arguments for each dimension to be subset over, each argument
+        must be a slice, or have two entries (a maximum and a minimum). Datetime objects can be used to specify upper
+        and lower datetime limits, or a single PartialDateTime object can be used to specify a datetime range.
+
+        The keyword keys are used to find the relevant coordinate, they are looked for in order of name, standard_name,
+        axis and var_name.
+
+        For example:
+            data.subset(x=[0, 80], y=slice(10, 50))
+
+        or:
+            data.aggregate(t=PartialDateTime(2008,9))
+
+
+        A shape keyword can also be supplied as a WKT string or shapely object to subset in lat/lon by an arbitrary
+        shape. In this case the lat/lon bounds are taken as the bounding box of the shape. Note that the shape of the
+        output remains the same, but a mask is applied to the data over the relevant coordinates. Only 2-dimensional
+        datasets are supported at this time.
+
+        :param kwargs: The constraints for each coordinate dimension
+        :return CommonData:
         """
         from cis.subsetting.subset import subset, GriddedSubsetConstraint
         return subset(self, GriddedSubsetConstraint, **kwargs)

cis/data_io/ungridded_data.py

@@ -748,9 +748,27 @@ def set_longitude_range(self, range_start):
 
     def subset(self, **kwargs):
         """
-        Subset the CommonData object based on the specified constraints
-        :param kwargs:
-        :return:
+        Subset the data based on the specified constraints. Note that the limits are inclusive.
+
+        The subset region is defined by passing keyword arguments for each dimension to be subset over, each argument
+        must be a slice, or have two entries (a maximum and a minimum). Datetime objects can be used to specify upper
+        and lower datetime limits, or a single PartialDateTime object can be used to specify a datetime range.
+
+        The keyword keys are used to find the relevant coordinate, they are looked for in order of name, standard_name,
+        axis and var_name.
+
+        For example:
+            data.subset(x=[0, 80], y=slice(10, 50))
+
+        or:
+            data.aggregate(t=PartialDateTime(2008,9))
+
+
+        A shape keyword can also be supplied as a WKT string or shapely object to subset in lat/lon by an arbitrary
+        shape. In this case the lat/lon bounds are taken as the bounding box of the shape.
+
+        :param kwargs: The constraints for each coordinate dimension
+        :return CommonData:
         """
         from cis.subsetting.subset import subset, UngriddedSubsetConstraint
         return subset(self, UngriddedSubsetConstraint, **kwargs)

cis/subsetting/subset.py

@@ -14,6 +14,8 @@ def subset(data, constraint, **kwargs):
     Helper function for constraining a CommonData or CommonDataList object (data) given a SubsetConstraint
     class, the constraints should be specified using the kwargs of the form coord: [min, max]
 
+    A shape keyword can also be supplied as a WKT string or shapely object to subset in lat/lon by an arbitrary shape.
+
     :param CommonData or CommonDataList data: The data to subset
     :param class SubsetConstraint constraint: A SubsetConstraint class to do the constraining
     :param kwargs: The limits as slices or length 2 tuples of max and min.
@@ -290,5 +292,6 @@ def _get_ungridded_subset_region_indices(ungridded_data, region):
 
 
 def _get_gridded_subset_region_indices(gridded_data, region):
+    # Using X and Y is a bit more general than lat and lon - the shapefiles needn't actually represent lat/lon
     x, y = np.meshgrid(gridded_data.coord(axis='X').points, gridded_data.coord(axis='Y').points)
     return _get_indices_for_lat_lon_points(x.flat, y.flat, region)

doc/whats_new_1.5.rst

@@ -38,4 +38,6 @@ CIS 1.5.1 fixes
 
 CIS 1.5.2 fixes
 ===============
+ * Gridded and ungridded datasets can now be subset to an arbitrary lat/lon (shapely) shape.
  * Slicing and copying Coords now preserves the axis
+ * Fixed an issue where subsetting gridded data over multiple coordinates sometimes resulted in an error