natcap.invest.coastal_vulnerability

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

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_intermediate_csv_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: This variable is used as the fieldname in

      target_output_vector_path. And if the string includes the prefix R_, the variable is included in the final exposure equation.

  • 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, target_missing_data_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 geomorphology_fill_value.

Parameters:
  • geomorphology_vector_path (string) – path to polyline vector with an integer attribute named RANK that contains values in (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 shore_id.

  • target_missing_data_path (string) – path to create point vector showing which points received the geomorphology fill value because no geomorphology segments were found within the search radius.

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: { <id0>: 5, <id1>: 5, <id2>: 5 }

  • target_habitat_protection_path (string) – path to a csv file with a row for each shore point, and a header like: ‘shore_id’,’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 id.

Returns:

None.

natcap.invest.coastal_vulnerability.calculate_surge_exposure(base_shore_point_vector_path, shelf_contour_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.

  • target_surge_pickle_path (string) – path to pickle file storing dict keyed by shore point id.

Returns:

None.

natcap.invest.coastal_vulnerability.calculate_wave_exposure(base_fetch_point_vector_path, max_fetch_distance, target_wave_vector_path, 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, V10PCT_[direction] fields, ‘fdist_[direction]’ fields, ‘fdepth_[direction]’ fields.

  • max_fetch_distance (float) – max fetch distance before a wind fetch ray is terminated.

  • target_wave_vector_path (string) – path to GPKG vector that this function creates to store intermediate ocean-wave and local-wind-driven-wave energy values.

  • target_wave_exposure_pickle_path (string) – path to pickle file storing dict mapping each shore point’s shore_id to its wave exposure

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, bathymetry_raster_path, target_fetch_rays_path, 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.

  • bathymetry_raster_path (string) – path to bathymetry raster that has already had positive pixel values clamped to 0.

  • target_fetch_rays_path (string) – path to target line string file representing the rays cast in 16 directions around each shore point

  • 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 that maps each shore point’s shore_id to the REI value at that point.

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.compute_wave_height(Un, Fn, dn)

Compute Wave Height by User Guide eq 10.

This equation may not be suitable for wind speed values < 1 m/s The WWIII database tends to include some 0s, otherwise values > 2.

Parameters:
  • Un (float) – wind velocity in meters per second.

  • Fn (float) – fetch ray length in meters.

  • dn (float) – water depth in negative meters.

Returns:

Wave height in meters

Return type:

Float

natcap.invest.coastal_vulnerability.compute_wave_period(Un, Fn, dn)

Compute Wave Period by User Guide eq 10.

This equation may not be suitable for wind speed values < 1 m/s The WWIII database tends to include some 0s, otherwise values > 2.

Parameters:
  • Un (float) – wind velocity in meters per second.

  • Fn (float) – fetch ray length in meters.

  • dn (float) – water depth in negative meters.

Returns:

Wave period in seconds

Return type:

Float

natcap.invest.coastal_vulnerability.construct_field_list(basename)

Return list of strings with compass degree suffix on a basename.

This is useful for constructing fieldnames that appear in the WWIII table and passing them to _copy_point_vector_geom_to_gpkg.

natcap.invest.coastal_vulnerability.execute(args)

Coastal Vulnerability.

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['bathymetry_raster_path'] (string) – (required) path to a raster representing the depth below sea level, in negative meters. Should cover the area extending outward from the AOI to the max_fetch_distance.

  • 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) – (required) 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_raster_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.extract_bathymetry_along_ray(ray_geometry, bathy_gt, bathy_nodata, bathy_band)

Extract valid raster values along a ray.

Extract bathymetry values at points along a ray. Points are interpolated along the ray at an interval equal to the rasters pixel size, and points are explicitly placed at each ray endpoint.

If only nodata values are extracted along the entire length of the ray, expand the extraction window as needed on the final ray point, until some valid pixels are found.

Parameters:
  • ray_geometry (ogr.wkbLineString) – The ray along which to extract values

  • bathy_gt (list) – The bathymetry raster’s geotransform

  • bathy_nodata (number) – The bathymetry raster’s nodata value

  • bathy_band (gdal raster band) – An open gdal raster band containing the bathymetry values

Raises:

ValueError if an extraction point is outside the bounds of the raster.

Returns:

A list of the non-nodata pixel values extracted at each point.

natcap.invest.coastal_vulnerability.geometry_to_lines(geometry, include_interiors=True)

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 mapping each shore point’s shore_id to the distance-weighted average sea level rise at nearby SLR points.

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.mask_positive_values_op(depth_array, nodata)

Convert positive values to nodata for bathymetry.

natcap.invest.coastal_vulnerability.polygon_to_lines(geometry, include_interiors=True)

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

natcap.invest.coastal_vulnerability.prepare_landmass_line_index_and_interpolate_shore_points(aoi_vector_path, landmass_vector_path, model_resolution, target_points_path, target_polygon_pickle_path, target_lines_pickle_path, target_rtree_path)

Prepare landmass for line operations and interpolate shore points.

Converts landmass polygons to lines and creates shore points by interpolating at a specified interval over those lines. Saves spatial index of lines for fast intersections. Also saves unioned geometry polygons for fast point-in-polygon checks.

Parameters:
  • aoi_vector_path (string) – path to polygon vector used to define boundaries for adding points.

  • landmass_vector_path (string) – path to polygon vector

  • model_resolution (float) – distance in meters for the point’s spacing

  • target_points_path (string) – path to .gpkg point 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_raster_habitat(base_shore_point_vector_path, search_radius, habitat_rank, habitat_id, habitat_raster_path, target_habitat_pickle_path, model_resolution, workspace_dir, file_suffix)

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

If habitat is present within the search radius, assign the habitat_rank to the shore point ID. 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_raster_path (string) – path to a raster where 0 and nodata represent absence of habitat, all other values represent presence.

  • target_habitat_pickle_path (string) – path to pickle file storing a dict keyed by shore point ID: { <id0>: 5, <id1>: 5, <id2>: 5}

  • model_resolution (float) – to be the target pixel size in case habitat rasters are unprojected.

  • file_suffix (string) – to be appended to output filenames

Returns:

None

natcap.invest.coastal_vulnerability.search_for_vector_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 ID. 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 ID: { <id0>: 5, <id1>: 5, <id2>: 5 }

Returns:

None

natcap.invest.coastal_vulnerability.warp_and_mask_bathymetry(bathymetry_raster_path, target_srs_wkt, clipping_box, model_resolution, working_dir, file_suffix, target_negative_bathy_path)

Mask non-negative values from bathymetry, and warp to AOI SRS.

Parameters:
  • bathymetry_raster_path (string) – path to a gdal raster

  • target_srs_wkt (string) – well-known-text spatial reference system

  • clipping_box (list) – sequence of floats that are coordinates in the target_srs [minx, miny, maxx, maxy]

  • 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_negative_bathy_path (string) – path to clipped and warped raster.

Returns:

None

natcap.invest.coastal_vulnerability.zero_negative_values(depth_array, nodata)

Convert negative values to zero for relief.