natcap.invest.stormwater¶
Stormwater Retention.
- natcap.invest.stormwater.adjust_op(ratio_array, avg_ratio_array, near_connected_lulc_array, near_road_array)¶
Apply the retention ratio adjustment algorithm to an array of ratios.
This is meant to be used with raster_calculator. Assumes that the nodata value for all four input arrays is the global FLOAT_NODATA.
- Parameters:
ratio_array (numpy.ndarray) – 2D array of stormwater retention ratios
avg_ratio_array (numpy.ndarray) – 2D array of averaged ratios
near_connected_lulc_array (numpy.ndarray) – 2D boolean array where 1 means this pixel is near a directly-connected LULC area
near_road_array (numpy.ndarray) – 2D boolean array where 1 means this pixel is near a road centerline
- Returns:
2D numpy array of adjusted retention ratios. Has the same shape as
retention_ratio_array
.
- natcap.invest.stormwater.aggregate_results(base_aggregate_areas_path, target_vector_path, srs_wkt, aggregations)¶
Aggregate outputs into regions of interest.
- Parameters:
base_aggregate_areas_path (str) – path to vector of polygon(s) to aggregate over. This is the original input.
target_vector_path (str) – path to write out the results. This will be a copy of the base vector with added fields, reprojected to the target WKT and saved in geopackage format.
srs_wkt (str) – a Well-Known Text representation of the target spatial reference. The base vector is reprojected to this spatial reference before aggregating the rasters over it.
aggregations (list[tuple(str,str,str)]) – list of tuples describing the datasets to aggregate. Each tuple has 3 items. The first is the path to a raster to aggregate. The second is the field name for this aggregated data in the output vector. The third is either ‘mean’ or ‘sum’ indicating the aggregation to perform.
- Returns:
None
- natcap.invest.stormwater.execute(args)¶
Execute the urban stormwater retention model.
- Parameters:
args['workspace_dir'] (str) – path to a directory to write intermediate and final outputs. May already exist or not.
args['results_suffix'] (str, optional) – string to append to all output file names from this model run
args['n_workers'] (int) – if present, indicates how many worker processes should be used in parallel processing. -1 indicates single process mode, 0 is single process but non-blocking mode, and >= 1 is number of processes.
args['lulc_path'] (str) – path to LULC raster
args['soil_group_path'] (str) – path to soil group raster, where pixel values 1, 2, 3, 4 correspond to groups A, B, C, D
args['precipitation_path'] (str) – path to raster of total annual precipitation in millimeters
args['biophysical_table'] (str) – path to biophysical table with columns ‘lucode’, ‘EMC_x’ (event mean concentration mg/L) for each pollutant x, ‘RC_y’ (retention coefficient) and ‘PE_y’ (percolation coefficient) for each soil group y, and ‘is_connected’ if args[‘adjust_retention_ratios’] is True
args['adjust_retention_ratios'] (bool) – If True, apply retention ratio adjustment algorithm.
args['retention_radius'] (float) – If args[‘adjust_retention_ratios’] is True, use this radius in the adjustment algorithm.
args['road_centerliens_path'] (str) – Path to linestring vector of road centerlines. Only used if args[‘adjust_retention_ratios’] is True.
args['aggregate_areas_path'] (str) – Optional path to polygon vector of areas to aggregate results over.
args['replacement_cost'] (float) – Cost to replace stormwater retention devices in units currency per cubic meter
- Returns:
None
- natcap.invest.stormwater.is_near(input_path, radius, distance_path, out_path)¶
Make binary raster of which pixels are within a radius of a ‘1’ pixel.
- Parameters:
input_path (str) – path to a binary raster where ‘1’ pixels are what we’re measuring distance to, in this case roads/connected areas
radius (float) – distance in pixels which is considered “near”. pixels this distance or less from a ‘1’ pixel are marked ‘1’ in the output. Distances are measured centerpoint to centerpoint.
distance_path (str) – path to write out the raster of distances
out_path (str) – path to write out the final thresholded raster. Pixels marked ‘1’ are near to a ‘1’ pixel in the input, pixels marked ‘0’ are not.
- Returns:
None
- natcap.invest.stormwater.lookup_ratios(lulc_path, soil_group_path, ratio_lookup, sorted_lucodes, output_path)¶
Look up retention/percolation ratios from LULC codes and soil groups.
- Parameters:
lulc_array (numpy.ndarray) – 2D array of LULC codes
soil_group_array (numpy.ndarray) – 2D array with the same shape as
lulc_array
. Values in {1, 2, 3, 4} corresponding to soil groups A, B, C, and D.ratio_lookup (numpy.ndarray) – 2D array where rows correspond to sorted LULC codes and the 4 columns correspond to soil groups A, B, C, D in order. Shape: (number of lulc codes, 4).
sorted_lucodes (list[int]) – List of LULC codes sorted from smallest to largest. These correspond to the rows of
ratio_lookup
.output_path (str) – path to a raster to write out the result. has the same shape as the lulc and soil group rasters. Each value is the corresponding ratio for that LULC code x soil group pair.
- Returns:
None
- natcap.invest.stormwater.make_search_kernel(raster_path, radius)¶
Make a search kernel for a raster that marks pixels within a radius.
- Parameters:
raster_path (str) – path to a raster to make kernel for. It is assumed that the raster has square pixels.
radius (float) – distance around each pixel’s centerpoint to search in raster coordinate system units
- Returns:
2D boolean numpy.ndarray. ‘1’ pixels are within
radius
of the center pixel, measured centerpoint-to-centerpoint. ‘0’ pixels are outside the radius. The array dimensions are as small as possible while still including the entire radius.
- natcap.invest.stormwater.pollutant_load_op(lulc_array, lulc_nodata, volume_array, sorted_lucodes, emc_array)¶
Calculate pollutant loads from EMC and stormwater volumes.
Used for both actual pollutant load (where volume_array is the runoff volume) and avoided pollutant load (where volume_array is the retention volume).
- Parameters:
lulc_array (numpy.ndarray) – 2D array of LULC codes
lulc_nodata (int) – nodata value for the LULC array
volume_array (numpy.ndarray) – 2D array of stormwater volumes, with the same shape as
lulc_array
. It is assumed that the volume nodata value is the global FLOAT_NODATA.sorted_lucodes (numpy.ndarray) – 1D array of the LULC codes in order from smallest to largest
emc_array (numpy.ndarray) – 1D array of pollutant EMC values for each lucode.
emc_array[i]
is the EMC for the LULC class atsorted_lucodes[i]
.
- Returns:
2D numpy.ndarray with the same shape as
lulc_array
. Each value is the avoided pollutant load on that pixel in kg/yr, or FLOAT_NODATA if any of the inputs have nodata on that pixel.
- natcap.invest.stormwater.raster_average(raster_path, radius, kernel_path, out_path)¶
Average pixel values within a radius.
Make a search kernel where a pixel has ‘1’ if its centerpoint is within the radius of the center pixel’s centerpoint. For each pixel in a raster, center the search kernel on top of it. Then its “neighborhood” includes all the pixels that are below a ‘1’ in the search kernel. Add up the neighborhood pixel values and divide by how many there are.
This accounts for edge pixels and nodata pixels. For instance, if the kernel covers a 3x3 pixel area centered on each pixel, most pixels will have 9 valid pixels in their neighborhood, most edge pixels will have 6, and most corner pixels will have 4. Edge and nodata pixels in the neighborhood don’t count towards the total (denominator in the average).
- Parameters:
raster_path (str) – path to the raster file to average
radius (float) – distance to average around each pixel’s centerpoint in raster coordinate system units
kernel_path (str) – path to write out the search kernel raster, an intermediate output required by pygeoprocessing.convolve_2d
out_path (str) – path to write out the averaged raster output
- Returns:
None
- natcap.invest.stormwater.retention_to_runoff_op(retention_array)¶
Calculate runoff ratios from retention ratios: runoff = 1 - retention.
- Parameters:
retention_array (numpy.ndarray) – array of stormwater retention ratios. It is assumed that the nodata value is the global FLOAT_NODATA.
- Returns:
numpy.ndarray of stormwater runoff ratios
- natcap.invest.stormwater.retention_value_op(retention_volume_array, replacement_cost)¶
Multiply retention volumes by the retention replacement cost.
- Parameters:
retention_volume_array (numpy.ndarray) – 2D array of retention volumes. Assumes that the retention volume nodata value is the global FLOAT_NODATA.
replacement_cost (float) – Replacement cost per cubic meter of water
- Returns:
numpy.ndarray of retention values with the same dimensions as the input
- natcap.invest.stormwater.volume_op(ratio_array, precip_array, precip_nodata, pixel_area)¶
Calculate stormwater volumes from precipitation and ratios.
- Parameters:
ratio_array (numpy.ndarray) – 2D array of stormwater ratios. Assuming that its nodata value is the global FLOAT_NODATA.
precip_array (numpy.ndarray) – 2D array of precipitation amounts in millimeters/year
precip_nodata (float) – nodata value for the precipitation array
pixel_area (float) – area of each pixel in m^2
- Returns:
2D numpy.ndarray of precipitation volumes in m^3/year