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_map. Assumes that nodata is already filtered out.

  • 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


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.

  • 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.




Execute the urban stormwater retention model.

  • 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



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.

  • 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.



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.

  • 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.



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).

  • 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 at sorted_lucodes[i].


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).

  • 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




Calculate runoff ratios from retention ratios: runoff = 1 - retention.


retention_array (numpy.ndarray) – array of stormwater retention ratios. It is assumed that the nodata value is the global FLOAT_NODATA.


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.

  • 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


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.

  • 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


2D numpy.ndarray of precipitation volumes in m^3/year