NREL-reV 0.8.7__py3-none-any.whl → 0.9.0__py3-none-any.whl

reV/supply_curve/competitive_wind_farms.py

@@ -3,10 +3,12 @@
 Competitive Wind Farms exclusion handler
 """
 import logging
-import numpy as np
 
+import numpy as np
 from rex.utilities.utilities import parse_table
 
+from reV.utilities import SupplyCurveField
+
 logger = logging.getLogger(__name__)
 
 
@@ -33,30 +35,36 @@ class CompetitiveWindFarms:
         """
         self._wind_dirs = self._parse_wind_dirs(wind_dirs)
 
-        self._sc_gids, self._sc_point_gids, self._mask = \
-            self._parse_sc_points(sc_points, offshore=offshore)
+        self._sc_gids, self._sc_point_gids, self._mask = self._parse_sc_points(
+            sc_points, offshore=offshore
+        )
 
         self._offshore = offshore
 
         valid = np.isin(self.sc_point_gids, self._wind_dirs.index)
         if not np.all(valid):
-            msg = ("'sc_points contains sc_point_gid values that do not "
-                   "correspond to valid 'wind_dirs' sc_point_gids:\n{}"
-                   .format(self.sc_point_gids[~valid]))
+            msg = (
+                "'sc_points contains sc_point_gid values that do not "
+                "correspond to valid 'wind_dirs' sc_point_gids:\n{}".format(
+                    self.sc_point_gids[~valid]
+                )
+            )
             logger.error(msg)
             raise RuntimeError(msg)
 
         mask = self._wind_dirs.index.isin(self._sc_point_gids.keys())
         self._wind_dirs = self._wind_dirs.loc[mask]
-        self._upwind, self._downwind = self._get_neighbors(self._wind_dirs,
-                                                           n_dirs=n_dirs)
+        self._upwind, self._downwind = self._get_neighbors(
+            self._wind_dirs, n_dirs=n_dirs
+        )
 
     def __repr__(self):
         gids = len(self._upwind)
         # pylint: disable=unsubscriptable-object
         neighbors = len(self._upwind.values[0])
-        msg = ("{} with {} sc_point_gids and {} prominent directions"
-               .format(self.__class__.__name__, gids, neighbors))
+        msg = "{} with {} sc_point_gids and {} prominent directions".format(
+            self.__class__.__name__, gids, neighbors
+        )
 
         return msg
 
@@ -76,23 +84,25 @@ class CompetitiveWindFarms:
         """
         if not isinstance(keys, tuple):
             msg = ("{} must be a tuple of form (source, gid) where source is: "
-                   "'sc_gid', 'sc_point_gid',  or 'upwind', 'downwind'"
-                   .format(keys))
+                   "{}, '{}',  or 'upwind', 'downwind'"
+                   .format(keys, SupplyCurveField.SC_GID,
+                           SupplyCurveField.SC_POINT_GID))
             logger.error(msg)
             raise ValueError(msg)
 
         source, gid = keys
-        if source == 'sc_point_gid':
+        if source == SupplyCurveField.SC_POINT_GID:
             out = self.map_sc_gid_to_sc_point_gid(gid)
-        elif source == 'sc_gid':
+        elif source == SupplyCurveField.SC_GID:
             out = self.map_sc_point_gid_to_sc_gid(gid)
-        elif source == 'upwind':
+        elif source == "upwind":
             out = self.map_upwind(gid)
-        elif source == 'downwind':
+        elif source == "downwind":
             out = self.map_downwind(gid)
         else:
-            msg = ("{} must be: 'sc_gid', 'sc_point_gid',  or 'upwind', "
-                   "'downwind'".format(source))
+            msg = ("{} must be: {}, {},  or 'upwind', "
+                   "'downwind'".format(source, SupplyCurveField.SC_GID,
+                                       SupplyCurveField.SC_POINT_GID))
             logger.error(msg)
             raise ValueError(msg)
 
@@ -133,9 +143,9 @@ class CompetitiveWindFarms:
         -------
         ndarray
         """
-        sc_gids = \
-            np.concatenate([self._sc_point_gids[gid]
-                            for gid in self.sc_point_gids])
+        sc_gids = np.concatenate(
+            [self._sc_point_gids[gid] for gid in self.sc_point_gids]
+        )
 
         return sc_gids
 
@@ -181,8 +191,10 @@ class CompetitiveWindFarms:
             cardinal direction for each sc point gid
         """
         wind_dirs = cls._parse_table(wind_dirs)
+        wind_dirs = wind_dirs.rename(
+            columns=SupplyCurveField.map_from_legacy())
 
-        wind_dirs = wind_dirs.set_index('sc_point_gid')
+        wind_dirs = wind_dirs.set_index(SupplyCurveField.SC_POINT_GID)
         columns = [c for c in wind_dirs if c.endswith(('_gid', '_pr'))]
         wind_dirs = wind_dirs[columns]
 
@@ -212,21 +224,25 @@ class CompetitiveWindFarms:
             Mask array to mask excluded sc_point_gids
         """
         sc_points = cls._parse_table(sc_points)
-        if 'offshore' in sc_points and not offshore:
+        sc_points = sc_points.rename(
+            columns=SupplyCurveField.map_from_legacy())
+        if SupplyCurveField.OFFSHORE in sc_points and not offshore:
             logger.debug('Not including offshore supply curve points in '
                          'CompetitiveWindFarm')
-            mask = sc_points['offshore'] == 0
+            mask = sc_points[SupplyCurveField.OFFSHORE] == 0
             sc_points = sc_points.loc[mask]
 
-        mask = np.ones(int(1 + sc_points['sc_point_gid'].max()), dtype=bool)
+        mask = np.ones(int(1 + sc_points[SupplyCurveField.SC_POINT_GID].max()),
+                       dtype=bool)
 
-        sc_points = sc_points[['sc_gid', 'sc_point_gid']]
-        sc_gids = sc_points.set_index('sc_gid')
+        sc_points = sc_points[[SupplyCurveField.SC_GID,
+                               SupplyCurveField.SC_POINT_GID]]
+        sc_gids = sc_points.set_index(SupplyCurveField.SC_GID)
         sc_gids = {k: int(v[0]) for k, v in sc_gids.iterrows()}
 
-        sc_point_gids = \
-            sc_points.groupby('sc_point_gid')['sc_gid'].unique().to_frame()
-        sc_point_gids = {int(k): v['sc_gid']
+        groups = sc_points.groupby(SupplyCurveField.SC_POINT_GID)
+        sc_point_gids = groups[SupplyCurveField.SC_GID].unique().to_frame()
+        sc_point_gids = {int(k): v[SupplyCurveField.SC_GID]
                          for k, v in sc_point_gids.iterrows()}
 
         return sc_gids, sc_point_gids, mask
@@ -251,19 +267,30 @@ class CompetitiveWindFarms:
         downwind : pandas.DataFrame
             Downwind neighbor gids for n prominent wind directions
         """
-        cols = [c for c in wind_dirs
-                if (c.endswith('_gid') and not c.startswith('sc'))]
-        directions = [c.split('_')[0] for c in cols]
+        cols = [
+            c
+            for c in wind_dirs
+            if (c.endswith("_gid") and not c.startswith("sc"))
+        ]
+        directions = [c.split("_")[0] for c in cols]
         upwind_gids = wind_dirs[cols].values
 
-        cols = ['{}_pr'.format(d) for d in directions]
+        cols = ["{}_pr".format(d) for d in directions]
         neighbor_pr = wind_dirs[cols].values
 
         neighbors = np.argsort(neighbor_pr)[:, :n_dirs]
         upwind_gids = np.take_along_axis(upwind_gids, neighbors, axis=1)
 
-        downwind_map = {'N': 'S', 'NE': 'SW', 'E': 'W', 'SE': 'NW', 'S': 'N',
-                        'SW': 'NE', 'W': 'E', 'NW': 'SE'}
+        downwind_map = {
+            "N": "S",
+            "NE": "SW",
+            "E": "W",
+            "SE": "NW",
+            "S": "N",
+            "SW": "NE",
+            "W": "E",
+            "NW": "SE",
+        }
         cols = ["{}_gid".format(downwind_map[d]) for d in directions]
         downwind_gids = wind_dirs[cols].values
         downwind_gids = np.take_along_axis(downwind_gids, neighbors, axis=1)
@@ -338,6 +365,7 @@ class CompetitiveWindFarms:
         ----------
         sc_point_gid : int
             Supply point curve gid to get upwind neighbors
+
         Returns
         -------
         int | list
@@ -353,6 +381,7 @@ class CompetitiveWindFarms:
         ----------
         sc_point_gid : int
             Supply point curve gid to get downwind neighbors
+
         Returns
         -------
         int | list
@@ -383,8 +412,9 @@ class CompetitiveWindFarms:
 
         return out
 
-    def remove_noncompetitive_farm(self, sc_points, sort_on='total_lcoe',
-                                   downwind=False):
+    def remove_noncompetitive_farm(
+        self, sc_points, sort_on="total_lcoe", downwind=False
+    ):
         """
         Remove neighboring sc points for given number of prominent wind
         directions
@@ -407,34 +437,45 @@ class CompetitiveWindFarms:
             wind farms
         """
         sc_points = self._parse_table(sc_points)
-        if 'offshore' in sc_points and not self._offshore:
-            mask = sc_points['offshore'] == 0
+        sc_points = sc_points.rename(
+            columns=SupplyCurveField.map_from_legacy())
+        if SupplyCurveField.OFFSHORE in sc_points and not self._offshore:
+            mask = sc_points[SupplyCurveField.OFFSHORE] == 0
             sc_points = sc_points.loc[mask]
 
         sc_points = sc_points.sort_values(sort_on)
 
-        sc_point_gids = sc_points['sc_point_gid'].values.astype(int)
+        sc_point_gids = sc_points[SupplyCurveField.SC_POINT_GID].values
+        sc_point_gids = sc_point_gids.astype(int)
 
         for i in range(len(sc_points)):
             gid = sc_point_gids[i]
             if self.mask[gid]:
-                upwind_gids = self['upwind', gid]
+                upwind_gids = self["upwind", gid]
                 for n in upwind_gids:
                     self.exclude_sc_point_gid(n)
 
                 if downwind:
-                    downwind_gids = self['downwind', gid]
+                    downwind_gids = self["downwind", gid]
                     for n in downwind_gids:
                         self.exclude_sc_point_gid(n)
 
         sc_gids = self.sc_gids
-        mask = sc_points['sc_gid'].isin(sc_gids)
+        mask = sc_points[SupplyCurveField.SC_GID].isin(sc_gids)
 
         return sc_points.loc[mask].reset_index(drop=True)
 
     @classmethod
-    def run(cls, wind_dirs, sc_points, n_dirs=2, offshore=False,
-            sort_on='total_lcoe', downwind=False, out_fpath=None):
+    def run(
+        cls,
+        wind_dirs,
+        sc_points,
+        n_dirs=2,
+        offshore=False,
+        sort_on="total_lcoe",
+        downwind=False,
+        out_fpath=None,
+    ):
         """
         Exclude given number of neighboring Supply Point gids based on most
         prominent wind directions
@@ -469,8 +510,9 @@ class CompetitiveWindFarms:
             wind farms
         """
         cwf = cls(wind_dirs, sc_points, n_dirs=n_dirs, offshore=offshore)
-        sc_points = cwf.remove_noncompetitive_farm(sc_points, sort_on=sort_on,
-                                                   downwind=downwind)
+        sc_points = cwf.remove_noncompetitive_farm(
+            sc_points, sort_on=sort_on, downwind=downwind
+        )
 
         if out_fpath is not None:
             sc_points.to_csv(out_fpath, index=False)

reV/supply_curve/exclusions.py

@@ -3,14 +3,14 @@
 Generate reV inclusion mask from exclusion layers
 """
 import logging
-import numpy as np
-from scipy import ndimage
 from warnings import warn
 
+import numpy as np
 from rex.utilities.loggers import log_mem
-from reV.handlers.exclusions import ExclusionLayers
-from reV.utilities.exceptions import ExclusionLayerError
-from reV.utilities.exceptions import SupplyCurveInputError
+from scipy import ndimage
+
+from reV.handlers.exclusions import ExclusionLayers, LATITUDE, LONGITUDE
+from reV.utilities.exceptions import ExclusionLayerError, SupplyCurveInputError
 
 logger = logging.getLogger(__name__)
 
@@ -32,6 +32,7 @@ class LayerMask:
                  weight=1.0,
                  exclude_nodata=False,
                  nodata_value=None,
+                 extent=None,
                  **kwargs):
         """
         Parameters
@@ -49,39 +50,44 @@ class LayerMask:
 
             By default, ``None``.
         exclude_range : list | tuple, optional
-            Two-item list of (min threshold, max threshold) for values
-            to exclude. Mutually exclusive with other inputs - see info
-            in the description of  `exclude_values`.
-            By default, ``None``.
+            Two-item list of [min threshold, max threshold] (ends are
+            inclusive) for values to exclude. Mutually exclusive
+            with other inputs (see info in the description of
+            `exclude_values`). By default, ``None``.
         include_values : int | float | list, optional
             Single value or list of values to include. Mutually
-            exclusive with other inputs - see info in the description of
-            `exclude_values`. By default, ``None``.
+            exclusive with other inputs (see info in the description of
+            `exclude_values`). By default, ``None``.
         include_range : list | tuple, optional
-            Two-item list of (min threshold, max threshold) for values
-            to include. Mutually exclusive with other inputs - see info
-            in the description of  `exclude_values`.
-            By default, ``None``.
+            Two-item list of [min threshold, max threshold] (ends are
+            inclusive) for values to include. Mutually exclusive with
+            other inputs (see info in the description of
+            `exclude_values`). By default, ``None``.
         include_weights : dict, optional
             A dictionary of ``{value: weight}`` pairs, where the
             ``value`` in the layer that should be included with the
-            given ``weight``. Mutually exclusive with other inputs - see
-            info in the description of  `exclude_values`.
+            given ``weight``. Mutually exclusive with other inputs (see
+            info in the description of  `exclude_values`).
             By default, ``None``.
         force_include_values : int | float | list, optional
-            Force the inclusion of the given value(s). Mutually
-            exclusive with other inputs - see info in the description of
-            `exclude_values`. By default, ``None``.
+            Force the inclusion of the given value(s). This input
+            completely replaces anything provided as `include_values`
+            and is mutually exclusive with other inputs (eee info in
+            the description of `exclude_values`). By default, ``None``.
         force_include_range : list | tuple, optional
             Force the inclusion of given values in the range
-            (min threshold, max threshold). Mutually exclusive with
-            other inputs - see info in the description of
-            `exclude_values`. By default, ``None``.
+            [min threshold, max threshold] (ends are inclusive). This
+            input completely replaces anything provided as
+            `include_range` and is mutually exclusive with other inputs
+            (see info in the description of `exclude_values`).
+            By default, ``None``.
         use_as_weights : bool, optional
-            Option to use layer as final inclusion weights. If ``True``,
-            all inclusion/exclusions specifications for the layer are
-            ignored and the raw values (scaled by the `weight` input)
-            are used as weights. By default, ``False``.
+            Option to use layer as final inclusion weights (i.e.
+            1 = fully included, 0.75 = 75% included, 0.5 = 50% included,
+            etc.). If ``True``, all inclusion/exclusions specifications
+            for the layer are ignored and the raw values (scaled by the
+            `weight` input) are used as inclusion weights.
+            By default, ``False``.
         weight : float, optional
             Weight applied to exclusion layer after it is calculated.
             Can be used, for example, to turn a binary exclusion layer
@@ -98,6 +104,38 @@ class LayerMask:
             inferred when LayerMask is added to
             :class:`reV.supply_curve.exclusions.ExclusionMask`.
             By default, ``None``.
+        extent : dict, optional
+            Optional dictionary with values that can be used to
+            initialize this class (i.e. `layer`, `exclude_values`,
+            `include_range`, etc.). This dictionary should contain the
+            specifications to create a boolean mask that defines the
+            extent to which the original mask should be applied.
+            For example, suppose you specify the input the following
+            way::
+
+                input_dict = {
+                    "viewsheds": {
+                        "exclude_values": 1,
+                        "extent": {
+                            "layer": "federal_parks",
+                            "include_range": [1, 5]
+                        }
+                    }
+                }
+
+                for layer_name, kwargs in input_dict.items():
+                    layer = LayerMask(layer_name, **kwargs)
+                    ...
+
+            This would mean that you are masking out all viewshed layer
+            values equal to 1, **but only where the "federal_parks"
+            layer is equal to 1, 2, 3, 4, or 5**. Outside of these
+            regions (i.e. outside of federal park regions), the viewshed
+            exclusion is **NOT** applied. If the extent mask created by
+            these options is not boolean, an error is thrown (i.e. do
+            not specify `weight` or `use_as_weights`).
+            By default ``None``, which applies the original layer mask
+            to the full extent.
         **kwargs
             Optional inputs to maintain legacy kwargs of ``inclusion_*``
             instead of ``include_*``.
@@ -125,13 +163,14 @@ class LayerMask:
         self.nodata_value = nodata_value
 
         if weight > 1 or weight < 0:
-            msg = ('Invalide weight ({}) provided for layer {}:'
+            msg = ('Invalid weight ({}) provided for layer {}:'
                    '\nWeight must fall between 0 and 1!'.format(weight, layer))
             logger.error(msg)
             raise ValueError(msg)
 
         self._weight = weight
         self._mask_type = self._check_mask_type()
+        self.extent = LayerMask(**extent) if extent is not None else None
 
     def __repr__(self):
         msg = ('{} for "{}" exclusion, of type "{}"'
@@ -207,8 +246,7 @@ class LayerMask:
 
         if all(isinstance(x, (int, float)) for x in range_var):
             return min(range_var)
-        else:
-            return range_var[0]
+        return range_var[0]
 
     @property
     def max_value(self):
@@ -226,8 +264,7 @@ class LayerMask:
 
         if all(isinstance(x, (int, float)) for x in range_var):
             return max(range_var)
-        else:
-            return range_var[1]
+        return range_var[1]
 
     @property
     def exclude_values(self):
@@ -331,7 +368,7 @@ class LayerMask:
         contradictory
 
         Returns
-        ------
+        -------
         mask : str
             Mask type
         """
@@ -355,6 +392,16 @@ class LayerMask:
                         logger.error(msg)
                         raise ExclusionLayerError(msg)
 
+            if mask is None:
+                msg = ('Exactly one approach must be specified to create the '
+                       'inclusion mask for layer {!r}! Please specify one of: '
+                       '`exclude_values`, `exclude_range`, `include_values`, '
+                       '`include_range`, `include_weights`, '
+                       '`force_include_values`, or `force_include_range`.'
+                       .format(self.name))
+                logger.error(msg)
+                raise ExclusionLayerError(msg)
+
         if mask == 'include_weights' and self._weight < 1:
             msg = ("Values are individually weighted when using "
                    "'include_weights', the supplied weight of {} will be "
@@ -640,7 +687,7 @@ class ExclusionMask:
         Returns
         -------
         _excl_h5 : ExclusionLayers
-         """
+        """
         return self._excl_h5
 
     @property
@@ -665,7 +712,7 @@ class ExclusionMask:
         Returns
         -------
         list
-         """
+        """
         return self._layers.keys()
 
     @property
@@ -676,7 +723,7 @@ class ExclusionMask:
         Returns
         -------
          list
-         """
+        """
         return self._layers.values()
 
     @property
@@ -700,7 +747,7 @@ class ExclusionMask:
         -------
         ndarray
         """
-        return self.excl_h5['latitude']
+        return self.excl_h5[LATITUDE]
 
     @property
     def longitude(self):
@@ -711,7 +758,7 @@ class ExclusionMask:
         -------
         ndarray
         """
-        return self.excl_h5['longitude']
+        return self.excl_h5[LONGITUDE]
 
     def add_layer(self, layer, replace=False):
         """
@@ -888,34 +935,54 @@ class ExclusionMask:
 
         return mask
 
-    def _force_include(self, mask, layers, ds_slice):
-        """
-        Apply force inclusion layers
+    def _add_layer_to_mask(self, mask, layer, ds_slice, check_layers,
+                           combine_func):
+        """Add layer mask to full mask."""
+        layer_mask = self._compute_layer_mask(layer, ds_slice, check_layers)
+        if mask is None:
+            return layer_mask
 
-        Parameters
-        ----------
-        mask : ndarray | None
-            Mask to apply force inclusion layers to
-        layers : list
-            List of force inclusion layers
-        ds_slice : int | slice | list | ndarray
-            What to extract from ds, each arg is for a sequential axis.
-            For example, (slice(0, 64), slice(0, 64)) will extract a 64x64
-            exclusions mask.
-        """
-        for layer in layers:
-            layer_slice = (layer.name, ) + ds_slice
-            layer_mask = layer[self.excl_h5[layer_slice]]
-            logger.debug('Computing forced inclusions for {}. Layer has '
-                         'average value of {:.2f}'
-                         .format(layer, layer_mask.mean()))
-            log_mem(logger, log_level='DEBUG')
-            if mask is None:
-                mask = layer_mask
-            else:
-                mask = np.maximum(mask, layer_mask, dtype='float32')
+        return combine_func(mask, layer_mask, dtype='float32')
 
-        return mask
+    def _compute_layer_mask(self, layer, ds_slice, check_layers=False):
+        """Compute mask for single layer, including extent."""
+        layer_mask = self._masked_layer_data(layer, ds_slice)
+        layer_mask = self._apply_layer_mask_extent(layer, layer_mask, ds_slice)
+
+        logger.debug('Computed exclusions {} for {}. Layer has average value '
+                     'of {:.2f}.'
+                     .format(layer, ds_slice, layer_mask.mean()))
+        log_mem(logger, log_level='DEBUG')
+
+        if check_layers and not layer_mask.any():
+            msg = "Layer {} is fully excluded!".format(layer.name)
+            logger.error(msg)
+            raise ExclusionLayerError(msg)
+
+        return layer_mask
+
+    def _apply_layer_mask_extent(self, layer, layer_mask, ds_slice):
+        """Apply extent to layer mask, if any."""
+        if layer.extent is None:
+            return layer_mask
+
+        layer_extent = self._masked_layer_data(layer.extent, ds_slice)
+        if not np.array_equal(layer_extent, layer_extent.astype(bool)):
+            msg = ("Extent layer must be boolean (i.e. 0 and 1 values "
+                   "only)! Please check your extent definition for layer "
+                   "{} to ensure you are producing a boolean layer!"
+                   .format(layer.name))
+            logger.error(msg)
+            raise ExclusionLayerError(msg)
+
+        logger.debug("Filtering mask for layer %s down to specified extent",
+                     layer.name)
+        layer_mask = np.where(layer_extent, layer_mask, 1)
+        return layer_mask
+
+    def _masked_layer_data(self, layer, ds_slice):
+        """Extract masked data for layer."""
+        return layer[self.excl_h5[(layer.name, ) + ds_slice]]
 
     def _generate_mask(self, *ds_slice, check_layers=False):
         """
@@ -950,27 +1017,13 @@ class ExclusionMask:
                 if layer.force_include:
                     force_include.append(layer)
                 else:
-                    layer_slice = (layer.name, ) + ds_slice
-                    layer_mask = layer[self.excl_h5[layer_slice]]
-
-                    logger.debug('Computed exclusions {} for {}. '
-                                 'Layer has average value of {:.2f}.'
-                                 .format(layer, ds_slice, layer_mask.mean()))
-                    log_mem(logger, log_level='DEBUG')
-
-                    if check_layers and not layer_mask.any():
-                        msg = ("Layer {} is fully excluded!"
-                               .format(layer.name))
-                        logger.error(msg)
-                        raise ExclusionLayerError(msg)
-
-                    if mask is None:
-                        mask = layer_mask
-                    else:
-                        mask = np.minimum(mask, layer_mask, dtype='float32')
-
-            if force_include:
-                mask = self._force_include(mask, force_include, ds_slice)
+                    mask = self._add_layer_to_mask(mask, layer, ds_slice,
+                                                   check_layers,
+                                                   combine_func=np.minimum)
+            for layer in force_include:
+                mask = self._add_layer_to_mask(mask, layer, ds_slice,
+                                               check_layers,
+                                               combine_func=np.maximum)
 
             if self._min_area is not None:
                 mask = self._area_filter(mask, self._min_area,