Coastal Protection Package

Coastal Vulnerability

Coastal Vulnerability Core

Coastal Vulnerability Cython Core

Coastal Vulnerability Post Processing

Module contents

InVEST Coastal Vulnerability

natcap.invest.coastal_vulnerability.aggregate_population_density(base_shore_point_vector_path, base_population_raster_path, search_radius, model_resolution, workspace_dir, file_suffix, target_pickle_path)

Get population density within a search radius of points.

Parameters:
  • base_shore_point_vector_path (string) – path to point vector
  • base_population_raster_path (string) – path to raster with population values
  • search_radius (float) – radius in meters around each point to search for valid population pixels.
  • model_resolution (float) – distance in meters of the shore_point spacing, used here as a target pixel size in warp raster.
  • workspace_dir (string) – path to directory for intermediate files
  • file_suffix (string) – appended to any output filename.
  • target_pickle_path (string) – path to pickle file storing dict keyed by shore point fid.
Returns:

None
natcap.invest.coastal_vulnerability.assemble_results_and_calculate_exposure(risk_id_path_list, habitat_protection_path, base_point_vector_path, target_intermediate_vector_path, target_output_vector_path, target_output_csv_path)

Calculate the final exposure score, with and without habitat protection.

Parameters:
  • risk_id_path_list (list) –

    list of 3-tuples like: (‘relief.pickle’, True, ‘R_relief’)

    1. string: path to pickle with intermediate
      exposure values for a single variable
    2. bool:
      if True: variable contains values that need binning
      by percentile to convert to 1-5 ranks.

      if False: variable is already on the 1-5 rank scale.

    3. string: if not None, this variable is included in the
      final exposure score, and ‘R_name’ becomes a fieldname in target_point_vector_path.
  • habitat_protection_path (string) – path to csv file with the intermediate habitat ranks.
  • base_point_vector_path (string) – path to shore point vector.
  • target_intermediate_vector_path (string) – path to point vector populated with fields and raw values for all risk variables that require binning to ranks.
  • target_output_vector_path (string) – path to point vector populated with fields and rank values for all risk variables, final exposure, exposure without habitats, and population density.
  • target_output_csv_path (string) – path to a csv copy of target_output_vector_path.
Returns:

None.
natcap.invest.coastal_vulnerability.calculate_final_risk(output_vector_path, output_csv_path)

Apply geometric mean calculation to variables at each shore point.

This function modifies the ‘output_vector_path’ file by adding new fields.

Parameters:
  • output_vector_path (string) – path to shore point vector populated with numeric fields named with the ‘R_’ prefix. These fields are included in the geometric mean.
  • output_csv_path (string) – path to csv copy of the final ‘output_vector_path’.
Returns:

None
natcap.invest.coastal_vulnerability.calculate_geomorphology_exposure(geomorphology_vector_path, geomorphology_fill_value, base_shore_point_vector_path, model_resolution, target_pickle_path)

Join geomorphology ranks to shore points by proximity.

Buffer each shore point by half the model_resolution and find all geomorphology types present around each point. Return the average of the geomorphology ranks, unless none are present, then return the

Parameters:
  • geomorphology_vector_path (string) – path to polyline vector with an integer attribute named RANK that contains values (1, 2, 3, 4, 5).
  • geomorphology_fill_value (int) – integer in (1, 2, 3, 4, 5).
  • base_shore_point_vector_path (string) – path to point vector
  • model_resolution (float) – distance in meters of the shore_point spacing.
  • target_pickle_path (string) – path to pickle file storing dict keyed by point fid.
Returns:

None
natcap.invest.coastal_vulnerability.calculate_habitat_rank(habitat_pickle_list, target_habitat_protection_path)

Combine dicts of habitat ranks into a dataframe and calcuate Rhab.

Parameters:
  • habitat_pickle_list (list) – list of file paths to pickled dictionaries in the form of: {‘habitat_id’: {<fid0>: 5, <fid1>.: 5, <fid2>: 5}}
  • target_habitat_protection_path (string) –

    path to a csv file with a row for each shore point, and a header like:

    ’fid’,’kelp’,’eelgrass’,’coral’,’R_hab’
Returns:

None
natcap.invest.coastal_vulnerability.calculate_relief_exposure(base_shore_point_vector_path, base_dem_path, dem_averaging_radius, model_resolution, workspace_dir, file_suffix, target_relief_pickle_path)

Calculate average of DEM pixels within a radius of shore points.

Parameters:
  • base_shore_point_vector_path (string) – path to a shore point vector.
  • base_dem_path (string) – path to a DEM raster.
  • dem_averaging_radius (float) – distance in meters
  • model_resolution (float) – distance in meters of the shore_point spacing, used here as a target pixel size in warp raster.
  • workspace_dir (string) – path to a directory for intermediate files
  • file_suffix (string) – to be appended to output filenames
  • target_relief_pickle_path (string) – path to pickle file storing dict keyed by shore point fid.
Returns:

None.
natcap.invest.coastal_vulnerability.calculate_surge_exposure(base_shore_point_vector_path, shelf_contour_path, aoi_vector_path, target_surge_pickle_path)

Calculate surge potential as distance to nearest point on a contour.

Parameters:
  • base_shore_point_vector_path (string) – path to a point shapefile to for relief point analysis.
  • shelf_contour_path (string) – path to a polyline vector.
  • aoi_vector_path (string) – path to a polygon vector.
  • target_surge_pickle_path (string) – path to pickle file storing dict keyed by shore point fid.
Returns:

None.
natcap.invest.coastal_vulnerability.calculate_wave_exposure(base_fetch_point_vector_path, max_fetch_distance, target_wave_exposure_pickle_path)

Calculate wave exposure values at each shore point.

Parameters:
  • base_fetch_point_vector_path (string) – path to a point shapefile that contains 16 ‘WavP_[direction]’ fields, ‘WavPPCT[direction]’ fields, ‘fdist_[direction]’ fields, a single H, and a single T field.
  • max_fetch_distance (float) – max fetch distance before a wind fetch ray is terminated.
  • target_wave_exposure_pickle_path (string) – path to pickle file storing dict keyed by shore point fid.
Returns:

None
natcap.invest.coastal_vulnerability.calculate_wind_exposure(base_shore_point_vector_path, landmass_polygon_pickle_path, landmass_line_rtree_path, landmass_lines_pickle_path, workspace_dir, file_suffix, max_fetch_distance, target_shore_point_vector_path, target_wind_exposure_pickle_path)

Calculate wind exposure for each shore point.

Parameters:
  • base_shore_point_vector_path (string) – path to a point vector with WWIII variables in the table.
  • landmass_polygon_pickle_path (string) – path to pickle storing shapely polygon geometry of the landmass.
  • landmass_line_rtree_path (string) – path to rtree file indexing bounds of line geometries.
  • landmass_lines_pickle_path (string) – path to pickle storing list of shapely line geometries. List index must match index of landmass_line_rtree_path.
  • workspace_dir (string) – path to a directory for intermediate files
  • file_suffix (string) – to be appended to output filenames
  • max_fetch_distance (float) – maximum fetch distance for a ray in meters.
  • target_shore_point_vector_path (string) – path to target point file, will be a copy of base_shore_point_vector_path’s geometry with an ‘REI’ (relative exposure index) field added.
  • target_wind_exposure_pickle_path (string) – path to pickle file storing dict keyed by shore point fid, with wind exposure values.
Returns:

None
natcap.invest.coastal_vulnerability.clip_and_project_raster(base_raster_path, clipping_box, target_srs_wkt, model_resolution, working_dir, file_suffix, target_raster_path)

Clip a raster to a box in the raster’s native SRS, then reproject.

Parameters:
  • base_raster_path (string) – path to a gdal raster
  • clipping_box (list) – sequence of floats that are coordinates in the target_srs [minx, miny, maxx, maxy]
  • target_srs_wkt (string) – well-known-text spatial reference system
  • model_resolution (float) – value for target pixel size
  • working_dir (string) – path to directory for intermediate files
  • file_suffix (string) – appended to any output filename.
  • target_raster_path (string) – path to clipped and warped raster.
Returns:

None
natcap.invest.coastal_vulnerability.clip_and_project_vector(base_vector_path, clipping_box, target_srs_wkt, tmp_vector_path, target_vector_path)

Clip a vector to a box in the vector’s native SRS, then reproject.

Parameters:
  • base_vector_path (string) – path to polygon or multipolygon type vector
  • clipping_box (list) – sequence of floats that are coordinates in the target_srs [minx, miny, maxx, maxy]
  • target_srs_wkt (string) – well-known-text spatial reference system
  • tmp_vector_path (string) – path to clipped but unprojected .gpkg vector
  • target_vector_path (string) – path to clipped and projected .gpkg vector
Returns:

None
natcap.invest.coastal_vulnerability.execute(args)

InVEST Coastal Vulnerability Model.

For points along a coastline, evaluate the relative exposure of points to coastal hazards based on up to eight biophysical hazard indices. Also quantify the role of habitats in reducing the hazard. Optionally summarize the population density in proximity to each shore point.

Parameters:
  • args['workspace_dir'] (string) – (required) a path to the directory that will write output and other temporary files during calculation.
  • args['results_suffix'] (string) – (optional) appended to any output filename.
  • args['aoi_vector_path'] (string) – (required) path to a polygon vector that is projected in a coordinate system with units of meters. The polygon should intersect the landmass and the shelf contour line.
  • args['model_resolution'] (string) – (required) distance in meters. Points are spaced along the coastline at intervals of this distance.
  • args['landmass_vector_path'] (string) – (required) path to a polygon vector representing landmasses in the region of interest.
  • args['wwiii_vector_path'] (string) – (required) path to a point vector containing wind and wave information across the region of interest.
  • args['max_fetch_distance'] (string) – (required) maximum distance in meters to extend rays from shore points. Points with rays equal to this distance will accumulate ocean-driven wave exposure along those rays and local-wind-driven wave exposure along the shorter rays.
  • args['shelf_contour_vector_path'] (string) – (required) path to a polyline vector delineating edges of the continental shelf or other bathymetry contour.
  • args['dem_path'] (string) – (required) path to a raster representing the elevation on land in the region of interest.
  • args['dem_averaging_radius'] (int or float) – (required) a value >= 0. The radius in meters around each shore point in which to compute the average elevation.
  • args['habitat_table_path'] (string) –

    (rqeuired) path to a CSV file with the following four fields:

    ’id’: unique string to represent each habitat ‘path’: absolute or relative path to a polygon vector ‘rank’: integer from 1 to 5 representing the relative
    protection offered by this habitat
    ’protection distance (m)’: integer or float used as a
    search radius around each shore point.
  • args['geomorphology_vector_path'] (string) – (optional) path to a polyline vector that has a field called “RANK” with values from 1 to 5 in the attribute table.
  • args['geomorphology_fill_value'] (int) – (optional) a value from 1 to 5 that will be used as a geomorphology rank for any points not proximate to the geomorphology_vector_path.
  • args['population_rater_path'] (string) – (optional) path a raster with values of total population per pixel.
  • args['population_radius'] (int or float) – (optional) a value >= 0. The radius in meters around each shore point in which to compute the population density.
  • args['slr_vector_path'] (string) – (optional) path to point vector containing the field args[‘slr_field’].
  • args['slr_field'] (string) – name of a field in args[‘slr_vector_path’] containing numeric values.
  • args['n_workers'] (int) – (optional) The number of worker processes to use for processing this model. If omitted, computation will take place in the current process.
Returns:

None
natcap.invest.coastal_vulnerability.geometry_to_lines(geometry)

Convert a geometry object to a list of lines.

natcap.invest.coastal_vulnerability.interpolate_sealevelrise_points(base_shore_point_vector_path, slr_points_vector_path, slr_fieldname, target_pickle_path)

Spatial join of sea-level rise data to shore points.

Finds nearest sea-level points to each shore point and calculates a weighted average of values with inverse-distance weights.

Parameters:
  • base_shore_point_vector_path (string) – path to point vector
  • slr_points_vector_path (string) – path to point vector containing the field slr_fieldname.
  • slr_fieldname (string) – name of a field containing numeric values
  • target_pickle_path (string) – path to pickle file storing dict keyed by point fid.
Returns:

None
natcap.invest.coastal_vulnerability.interpolate_shore_points(aoi_vector_path, landmass_lines_pickle_path, model_resolution, target_vector_path)

Create points along a polyline geometry at a specified interval.

Parameters:
  • aoi_vector_path (string) – path to polygon vector used to define boundaries for adding points.
  • landmass_lines_pickle_path (string) – path to pickle file containing list of shapely linestrings
  • model_resolution (float) – distance in meters for the point’s spacing
  • target_vector_path (string) – path to .gpkg point vector
Returns:

None
natcap.invest.coastal_vulnerability.interpolate_wwiii_to_shore(base_shore_point_vector_path, wwiii_vector_path, target_shore_point_vector_path)

Spatial join of Wave Watch 3 data to shore points.

Finds nearest WW3 points to each shore point and calculates a weighted average of values with distance weights.

Parameters:
  • base_shore_point_vector_path (string) – path to point vector
  • wwiii_vector_path (string) – path to point shapefile representing the Wave Watch III data.
  • target_shore_point_vector_path (string) – path to point vector file with interpolated wwiii data.
Returns:

None
natcap.invest.coastal_vulnerability.polygon_to_lines(geometry)

Return a list of shapely lines given higher order shapely geometry.

natcap.invest.coastal_vulnerability.prepare_landmass_line_index(landmass_vector_path, target_polygon_pickle_path, target_lines_pickle_path, target_rtree_path)

Prepare landmass polygon geometry for line operations.

Converts landmass polygons to lines used in shore point interpolation and saves spatial index of lines for fast intersections. Also saves unioned geometry polygons for fast point-in-polygon checks.

Parameters:
  • landmass_vector_path (string) – path to polygon vector
  • target_polygon_pickle_path (string) – path to pickle storing shapely polygon geometry.
  • target_lines_pickle_path (string) – path to pickle storing list of shapely line geometries
  • target_rtree_path (string) – path to rtree file indexing bounds of line geometries.
Returns:

None
natcap.invest.coastal_vulnerability.search_for_habitat(base_shore_point_vector_path, search_radius, habitat_rank, habitat_id, habitat_vector_path, target_habitat_pickle_path)

Search for habitat polygon within a radius of each shore point.

If habitat is present within the search radius, assign the habitat_rank to the shore point FID. If habitat is not present, assign rank of 5.

Parameters:
  • base_shore_point_vector_path (string) – path to a shore point vector.
  • search_radius (integer) – distance around each point to search for habitat. units match units from base_shore_point_vector SRS.
  • habitat_rank (integer) – from 1 to 5 representing the relative protection offered by this habitat (5 = no protection).
  • habitat_id (string) – unique string to represent each habitat.
  • habitat_vector_path (string) – path to a polygon vector.
  • target_habitat_pickle_path (string) –

    path to pickle file storing a dict keyed by shore point FID, nested in a dict keyed by habitat_id:

    {‘habitat_id’: {<fid0>: 5, <fid1>.: 5, <fid2>: 5}}
Returns:

None