InVEST Model Entry Points¶

All InVEST models share a consistent python API:

Every InVEST model has a corresponding module or subpackage in the natcap.invest package

The model modules contain a function called execute

The execute function takes a single argument (args), a dictionary that stores all data inputs and configuration options for the model

This dictionary contains an entry, 'workspace_dir', which is a path to the folder where the model will create its output files

Other required and optional entries in the dictionary are specific to each model

To run a model, import the model’s execute function and then call it with the correct parameters. For example, a script for the Carbon model might look like

import natcap.invest.carbon
args = {
    'workspace_dir': 'path/to/workspace'
    # Other arguments, as needed for Carbon.
}

natcap.invest.carbon.execute(args)

For examples of scripting a model run, or multiple successive model runs, see Creating Sample Python Scripts.

Annual Water Yield ¶

natcap.invest.annual_water_yield.execute(args)

Annual Water Yield: Reservoir Hydropower Production.

Executes the hydropower/annual water yield model

Parameters:

args['workspace_dir'] (string) – a path to the directory that will write output and other temporary files during calculation. (required)
args['lulc_path'] (string) – a path to a land use/land cover raster whose LULC indexes correspond to indexes in the biophysical table input. Used for determining soil retention and other biophysical properties of the landscape. (required)
args['depth_to_root_rest_layer_path'] (string) – a path to an input raster describing the depth of “good” soil before reaching this restrictive layer (required)
args['precipitation_path'] (string) – a path to an input raster describing the average annual precipitation value for each cell (mm) (required)
args['pawc_path'] (string) – a path to an input raster describing the plant available water content value for each cell. Plant Available Water Content fraction (PAWC) is the fraction of water that can be stored in the soil profile that is available for plants’ use. PAWC is a fraction from 0 to 1 (required)
args['eto_path'] (string) – a path to an input raster describing the annual average evapotranspiration value for each cell. Potential evapotranspiration is the potential loss of water from soil by both evaporation from the soil and transpiration by healthy Alfalfa (or grass) if sufficient water is available (mm) (required)
args['watersheds_path'] (string) – a path to an input shapefile of the watersheds of interest as polygons. (required)
args['sub_watersheds_path'] (string) – a path to an input shapefile of the subwatersheds of interest that are contained in the args['watersheds_path'] shape provided as input. (optional)
args['biophysical_table_path'] (string) – a path to an input CSV table of land use/land cover classes, containing data on biophysical coefficients such as root_depth (mm) and Kc, which are required. A column with header LULC_veg is also required which should have values of 1 or 0, 1 indicating a land cover type of vegetation, a 0 indicating non vegetation or wetland, water. NOTE: these data are attributes of each LULC class rather than attributes of individual cells in the raster map (required)
args['seasonality_constant'] (float) – floating point value between 1 and 30 corresponding to the seasonal distribution of precipitation (required)
args['results_suffix'] (string) – a string that will be concatenated onto the end of file names (optional)
args['demand_table_path'] (string) – (optional) if a non-empty string, a path to an input CSV table of LULC classes, showing consumptive water use for each landuse / land-cover type (cubic meters per year) to calculate water scarcity.
args['valuation_table_path'] (string) – (optional) if a non-empty string, a path to an input CSV table of hydropower stations with the following fields to calculate valuation: ‘ws_id’, ‘time_span’, ‘discount’, ‘efficiency’, ‘fraction’, ‘cost’, ‘height’, ‘kw_price’ Required if calculate_valuation is True.
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

Carbon Storage and Sequestration ¶

natcap.invest.carbon.execute(args)

Carbon.

Calculate the amount of carbon stocks given a landscape, or the difference due to a future change, and/or the tradeoffs between that and a REDD scenario, and calculate economic valuation on those scenarios.

The model can operate on a single scenario, a combined present and future scenario, as well as an additional REDD scenario.

Parameters:

args['workspace_dir'] (string) – a path to the directory that will write output and other temporary files during calculation.
args['results_suffix'] (string) – appended to any output file name.
args['lulc_cur_path'] (string) – a path to a raster representing the current carbon stocks.
args['calc_sequestration'] (bool) – if true, sequestration should be calculated and ‘lulc_fut_path’ and ‘do_redd’ should be defined.
args['lulc_fut_path'] (string) – a path to a raster representing future landcover scenario. Optional, but if present and well defined will trigger a sequestration calculation.
args['do_redd'] (bool) – if true, REDD analysis should be calculated and ‘lulc_redd_path’ should be defined
args['lulc_redd_path'] (string) – a path to a raster representing the alternative REDD scenario which is only possible if the args[‘lulc_fut_path’] is present and well defined.
args['carbon_pools_path'] (string) – path to CSV or that indexes carbon storage density to lulc codes. (required if ‘do_uncertainty’ is false)
args['lulc_cur_year'] (int/string) – an integer representing the year of args[‘lulc_cur_path’] used if args[‘do_valuation’] is True.
args['lulc_fut_year'] (int/string) – an integer representing the year of args[‘lulc_fut_path’] used in valuation if it exists. Required if args[‘do_valuation’] is True and args[‘lulc_fut_path’] is present and well defined.
args['do_valuation'] (bool) – if true then run the valuation model on available outputs. Calculate NPV for a future scenario or a REDD scenario and report in final HTML document.
args['price_per_metric_ton_of_c'] (float) – Is the present value of carbon per metric ton. Used if args[‘do_valuation’] is present and True.
args['discount_rate'] (float) – Discount rate used if NPV calculations are required. Used if args[‘do_valuation’] is present and True.
args['rate_change'] (float) – Annual rate of change in price of carbon as a percentage. Used if args[‘do_valuation’] is present and True.
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.

Coastal Blue Carbon ¶

natcap.invest.coastal_blue_carbon.coastal_blue_carbon.execute(args)

Coastal Blue Carbon.

Parameters:

args['workspace_dir'] (string) – the path to a workspace directory where outputs should be written.
args['results_suffix'] (string) – (optional) If provided, a string suffix that will be added to each output filename.
args['n_workers'] (int) – (optional) If provided, the number of workers to pass to taskgraph.
args['landcover_snapshot_csv'] (string) – The path to a transitions CSV table containing transition years and the LULC rasters representing that year. Required for transition analysis.
args['analysis_year'] (int) – the year of the final analysis.
args['do_economic_analysis'] (bool) – Whether to do valuation.
args['use_price_table'] (bool) – Whether to use a table of annual carbon prices for valuation. Defaults to False.
args['price_table_path'] (string) – The path to a table of prices to use for valuation. Required if args['use_price_table'] is True.
args['inflation_rate'] (number) – The rate of inflation. The number provided is multiplied by 0.01 to compute the actual rate of inflation. Required if args['use_price_table'] is False.
args['price'] (number) – The carbon price. Required if args['use_price_table'] is False.
args['discount_rate'] (number) – The discount rate. The number provided is multiplied by 0.01 to compute the actual discount rate. Required if args['do_economic_analysis'].
args['biophysical_table_path'] (string) – The path to the biophysical table on disk. This table has many required columns. See MODEL_SPEC for the required columns.
args['landcover_transitions_table'] (string) – The path to the landcover transitions table, indicating the behavior of carbon when the landscape undergoes a transition.

Returns:

None.

Coastal Blue Carbon Preprocessor ¶

natcap.invest.coastal_blue_carbon.preprocessor.execute(args)

Coastal Blue Carbon Preprocessor.

The preprocessor accepts a list of rasters and checks for cell-transitions across the rasters. The preprocessor outputs a CSV file representing a matrix of land cover transitions, each cell pre-filled with a string indicating whether carbon accumulates or is disturbed as a result of the transition, if a transition occurs.

Parameters:

args['workspace_dir'] (string) – directory path to workspace
args['results_suffix'] (string) – append to outputs directory name if provided
args['lulc_lookup_table_path'] (string) – filepath of lulc lookup table
args['landcover_csv_path'] (string) – filepath to a CSV containing the year and filepath to snapshot rasters on disk. The years may be in any order, but must be unique.

Returns:

None

Coastal Vulnerability ¶

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

Crop Pollination ¶

natcap.invest.pollination.execute(args)

Pollination.

Parameters:

args['workspace_dir'] (string) – a path to the output workspace folder. Will overwrite any files that exist if the path already exists.
args['results_suffix'] (string) – string appended to each output file path.
args['landcover_raster_path'] (string) – file path to a landcover raster.
args['guild_table_path'] (string) –
file path to a table indicating the bee species to analyze in this model run. Table headers must include:
- ’species’: a bee species whose column string names will
  be referred to in other tables and the model will output analyses per species.
- one or more columns matching _NESTING_SUITABILITY_PATTERN
  with values in the range [0, 1] indicating the suitability of the given species to nest in a particular substrate.
- one or more columns matching _FORAGING_ACTIVITY_RE_PATTERN
  with values in the range [0, 1] indicating the relative level of foraging activity for that species during a particular season.
- _ALPHA_HEADER the sigma average flight distance of that bee
  species in meters.
- ’relative_abundance’: a weight indicating the relative
  abundance of the particular species with respect to the sum of all relative abundance weights in the table.
args['landcover_biophysical_table_path'] (string) –
path to a table mapping landcover codes in args[‘landcover_path’] to indexes of nesting availability for each nesting substrate referenced in guilds table as well as indexes of abundance of floral resources on that landcover type per season in the bee activity columns of the guild table.

All indexes are in the range [0, 1].
Columns in the table must be at least
- ’lucode’: representing all the unique landcover codes in
  the raster ast args[‘landcover_path’]
- For every nesting matching _NESTING_SUITABILITY_PATTERN in the guild stable, a column matching the pattern in _LANDCOVER_NESTING_INDEX_HEADER.
- For every season matching _FORAGING_ACTIVITY_RE_PATTERN in the guilds table, a column matching the pattern in _LANDCOVER_FLORAL_RESOURCES_INDEX_HEADER.
args['farm_vector_path'] (string) –
(optional) path to a single layer polygon shapefile representing farms. If present will trigger the farm yield component of the model.

The layer must have at least the following fields:
- season (string): season in which the farm needs pollination
- crop_type (string): a text field to identify the crop type for
  summary statistics.
- half_sat (float): a real in the range [0, 1] representing
  the proportion of wild pollinators to achieve a 50% yield of that crop.
- p_dep (float): a number in the range [0, 1]
  representing the proportion of yield dependent on pollinators.
- p_managed (float): proportion of pollinators that come from
  non-native/managed hives.
- fr_[season] (float): one or more fields that match this pattern
  such that season also matches the season headers in the biophysical and guild table. Any areas that overlap the landcover map will replace seasonal floral resources with this value. Ranges from 0..1.
- n_[substrate] (float): One or more fields that match this
  pattern such that substrate also matches the nesting substrate headers in the biophysical and guild table. Any areas that overlap the landcover map will replace nesting substrate suitability with this value. Ranges from 0..1.
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

Crop Production: Percentile ¶

natcap.invest.crop_production_percentile.execute(args)

Crop Production Percentile.

This model will take a landcover (crop cover?) map and produce yields, production, and observed crop yields, a nutrient table, and a clipped observed map.

Parameters:

args['workspace_dir'] (string) – output directory for intermediate, temporary, and final files
args['results_suffix'] (string) – (optional) string to append to any output file names
args['landcover_raster_path'] (string) – path to landcover raster
args['landcover_to_crop_table_path'] (string) –
path to a table that converts landcover types to crop names that has two headers:
- lucode: integer value corresponding to a landcover code in args[‘landcover_raster_path’].
- crop_name: a string that must match one of the crops in args[‘model_data_path’]/climate_bin_maps/[cropname]_* A ValueError is raised if strings don’t match.
args['aggregate_polygon_path'] (string) – path to polygon shapefile that will be used to aggregate crop yields and total nutrient value. (optional, if value is None, then skipped)
args['model_data_path'] (string) –
path to the InVEST Crop Production global data directory. This model expects that the following directories are subdirectories of this path:
- climate_bin_maps (contains [cropname]_climate_bin.tif files)
- climate_percentile_yield (contains [cropname]_percentile_yield_table.csv files)
Please see the InVEST user’s guide chapter on crop production for details about how to download these data.
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.

Crop Production: Regression ¶

natcap.invest.crop_production_regression.execute(args)

Crop Production Regression.

This model will take a landcover (crop cover?), N, P, and K map and produce modeled yields, and a nutrient table.

Parameters:

args['workspace_dir'] (string) – output directory for intermediate, temporary, and final files
args['results_suffix'] (string) – (optional) string to append to any output file names
args['landcover_raster_path'] (string) – path to landcover raster
args['landcover_to_crop_table_path'] (string) –
path to a table that converts landcover types to crop names that has two headers:
- lucode: integer value corresponding to a landcover code in args[‘landcover_raster_path’].
- crop_name: a string that must match one of the crops in args[‘model_data_path’]/climate_regression_yield_tables/[cropname]_* A ValueError is raised if strings don’t match.
args['fertilization_rate_table_path'] (string) – path to CSV table that contains fertilization rates for the crops in the simulation, though it can contain additional crops not used in the simulation. The headers must be ‘crop_name’, ‘nitrogen_rate’, ‘phosphorus_rate’, and ‘potassium_rate’, where ‘crop_name’ is the name string used to identify crops in the ‘landcover_to_crop_table_path’, and rates are in units kg/Ha.
args['aggregate_polygon_path'] (string) – path to polygon vector that will be used to aggregate crop yields and total nutrient value. (optional, if value is None, then skipped)
args['model_data_path'] (string) –
path to the InVEST Crop Production global data directory. This model expects that the following directories are subdirectories of this path:
- climate_bin_maps (contains [cropname]_climate_bin.tif files)
- climate_percentile_yield (contains [cropname]_percentile_yield_table.csv files)
Please see the InVEST user’s guide chapter on crop production for details about how to download these data.

Returns:

None.

DelineateIt ¶

natcap.invest.delineateit.delineateit.execute(args)

DelineateIt: Watershed Delineation.

This ‘model’ provides an InVEST-based wrapper around the pygeoprocessing routing API for watershed delineation.

Upon successful completion, the following files are written to the output workspace:

snapped_outlets.gpkg - A GeoPackage with the points snapped to a nearby stream.

watersheds.gpkg - a GeoPackage of watersheds determined by the D8 routing algorithm.

stream.tif - a GeoTiff representing detected streams based on the provided flow_threshold parameter. Values of 1 are streams, values of 0 are not.

Parameters:

args['workspace_dir'] (string) – The selected folder is used as the workspace all intermediate and output files will be written.If the selected folder does not exist, it will be created. If datasets already exist in the selected folder, they will be overwritten. (required)
args['results_suffix'] (string) – This text will be appended to the end of output files to help separate multiple runs. (optional)
args['dem_path'] (string) – A GDAL-supported raster file with an elevation for each cell. Make sure the DEM is corrected by filling in sinks, and if necessary burning hydrographic features into the elevation model (recommended when unusual streams are observed.) See the ‘Working with the DEM’ section of the InVEST User’s Guide for more information. (required)
args['outlet_vector_path'] (string) – This is a vector representing geometries that the watersheds should be built around. Required if args['detect_pour_points'] is False; not used otherwise.
args['snap_points'] (bool) – Whether to snap point geometries to the nearest stream pixel. If True, args['flow_threshold'] and args['snap_distance'] must also be defined.
args['flow_threshold'] (int) – The number of upslope cells that must flow into a cell before it’s considered part of a stream such that retention stops and the remaining export is exported to the stream. Used to define streams from the DEM.
args['snap_distance'] (int) – Pixel Distance to Snap Outlet Points
args['skip_invalid_geometry'] (bool) – Whether to crash when an invalid geometry is passed or skip it, including all valid geometries in the vector to be passed to delineation. If False, this tool will crash if an invalid geometry is found. If True, invalid geometries will be left out of the vector to be delineated. Default: True
args['detect_pour_points'] (bool) – Whether to run the pour point detection algorithm. If True, detected pour points are used instead of outlet_vector_path geometries. Default: False
args['n_workers'] (int) – The number of worker processes to use with taskgraph. Defaults to -1 (no parallelism).

Returns:

None

Forest Carbon Edge Effect ¶

natcap.invest.forest_carbon_edge_effect.execute(args)

Forest Carbon Edge Effect.

InVEST Carbon Edge Model calculates the carbon due to edge effects in tropical forest pixels.

Parameters:

args['workspace_dir'] (string) – a path to the directory that will write output and other temporary files during calculation. (required)
args['results_suffix'] (string) – a string to append to any output file name (optional)
args['n_nearest_model_points'] (int) – number of nearest neighbor model points to search for
args['aoi_vector_path'] (string) – (optional) if present, a path to a shapefile that will be used to aggregate carbon stock results at the end of the run.
args['biophysical_table_path'] (string) –
a path to a CSV table that has at least the fields ‘lucode’ and ‘c_above’. If args['compute_forest_edge_effects'] == True, table must also contain an ‘is_tropical_forest’ field. If args['pools_to_calculate'] == 'all', this table must contain the fields ‘c_below’, ‘c_dead’, and ‘c_soil’.
- lucode: an integer that corresponds to landcover codes in the raster args['lulc_raster_path']
- is_tropical_forest: either 0 or 1 indicating whether the landcover type is forest (1) or not (0). If 1, the value in c_above is ignored and instead calculated from the edge regression model.
- c_above: floating point number indicating tons of above ground carbon per hectare for that landcover type
- {'c_below', 'c_dead', 'c_soil'}: three other optional carbon pools that will statically map landcover types to the carbon densities in the table.
Example:
lucode,is_tropical_forest,c_above,c_soil,c_dead,c_below 0,0,32.8,5,5.2,2.1 1,1,n/a,2.5,0.0,0.0 2,1,n/a,1.8,1.0,0.0 16,0,28.1,4.3,0.0,2.0
Note the “n/a” in c_above are optional since that field is ignored when is_tropical_forest==1.
args['lulc_raster_path'] (string) – path to a integer landcover code raster
args['pools_to_calculate'] (string) – if “all” then all carbon pools will be calculted. If any other value only above ground carbon pools will be calculated and expect only a ‘c_above’ header in the biophysical table. If “all” model expects ‘c_above’, ‘c_below’, ‘c_dead’, ‘c_soil’ in header of biophysical_table and will make a translated carbon map for each based off the landcover map.
args['compute_forest_edge_effects'] (boolean) – if True, requires biophysical table to have ‘is_tropical_forest’ forest field, and any landcover codes that have a 1 in this column calculate carbon stocks using the Chaplin-Kramer et. al method and ignore ‘c_above’.
args['tropical_forest_edge_carbon_model_vector_path'] (string) –
path to a shapefile that defines the regions for the local carbon edge models. Has at least the fields ‘method’, ‘theta1’, ‘theta2’, ‘theta3’. Where ‘method’ is an int between 1..3 describing the biomass regression model, and the thetas are floating point numbers that have different meanings depending on the ‘method’ parameter. Specifically,
- method 1 (asymptotic model):
  biomass = theta1 - theta2 * exp(-theta3 * edge_dist_km)
- method 2 (logarithmic model):
  # NOTE: theta3 is ignored for this method biomass = theta1 + theta2 * numpy.log(edge_dist_km)
- method 3 (linear regression):
  biomass = theta1 + theta2 * edge_dist_km
args['biomass_to_carbon_conversion_factor'] (string/float) – Number by which to multiply forest biomass to convert to carbon in the edge effect calculation.
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

Habitat Quality ¶

natcap.invest.habitat_quality.execute(args)

Habitat Quality.

This model calculates habitat degradation and quality for the current LULC as described in the InVEST user’s guide. Optionally execute calculates habitat degradation and quality for a future LULC and habitat rarity for current and future LULC.

Parameters:

args (dict) – a key, value mapping for the habitat quality inputs.
args['workspace_dir'] (string) – a path to the directory that will write output and other temporary files (required)
args['lulc_cur_path'] (string) – a path to an input land use/land cover raster (required)
args['lulc_fut_path'] (string) – a path to an input land use/land cover raster (optional)
args['lulc_bas_path'] (string) – a path to an input land use/land cover raster (optional, but required for rarity calculations)
args['threats_table_path'] (string) – a path to an input CSV containing data of all the considered threats. Each row is a degradation source and each column a different attribute of the source with the following names (case-insensitive): ‘THREAT’,’MAX_DIST’,’WEIGHT’, ‘DECAY’, ‘CUR_PATH’ (required) ‘BASE_PATH’, ‘FUT_PATH’ (optional).
args['access_vector_path'] (string) – a path to an input polygon shapefile containing data on the relative protection against threats (optional)
args['sensitivity_table_path'] (string) – a path to an input CSV file of LULC types, whether they are considered habitat, and their sensitivity to each threat (required)
args['half_saturation_constant'] (float) – a python float that determines the spread and central tendency of habitat quality scores (required)
args['results_suffix'] (string) – a python string that will be inserted into all raster path paths just before the file extension.
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

Habitat Risk Assessment ¶

natcap.invest.hra.execute(args)

Habitat Risk Assessment.

Parameters:

args['workspace_dir'] (str) – a path to the output workspace folder. It will overwrite any files that exist if the path already exists.
args['results_suffix'] (str) – a string appended to each output file path. (optional)
args['info_table_path'] (str) – a path to the CSV or Excel file that contains the name of the habitat (H) or stressor (s) on the NAME column that matches the names in criteria_table_path. Each H/S has its corresponding vector or raster path on the PATH column. The STRESSOR BUFFER (meters) column should have a buffer value if the TYPE column is a stressor.
args['criteria_table_path'] (str) – a path to the CSV or Excel file that contains the set of criteria ranking of each stressor on each habitat.
args['resolution'] (int) – a number representing the desired pixel dimensions of output rasters in meters.
args['max_rating'] (str, int or float) – a number representing the highest potential value that should be represented in rating in the criteria scores table.
args['risk_eq'] (str) – a string identifying the equation that should be used in calculating risk scores for each H-S overlap cell. This will be either ‘Euclidean’ or ‘Multiplicative’.
args['decay_eq'] (str) – a string identifying the equation that should be used in calculating the decay of stressor buffer influence. This can be ‘None’, ‘Linear’, or ‘Exponential’.
args['aoi_vector_path'] (str) – a path to the shapefile containing one or more planning regions used to get the average risk value for each habitat-stressor combination over each area. Optionally, if each of the shapefile features contain a ‘name’ field, it will be used as a way of identifying each individual shape.
args['n_overlapping_stressors'] (number) – This number will be used in risk reclassification instead of the calculated maximum number of stressor layers that overlap.
args['n_workers'] (int) – the number of worker processes to use for processing this model. If omitted, computation will take place in the current process. (optional)
args['visualize_outputs'] (bool) – if True, create output GeoJSONs and save them in a visualization_outputs folder, so users can visualize results on the web app. Default to True if not specified. (optional)

Returns:

None.

Nutrient Delivery Ratio ¶

natcap.invest.ndr.ndr.execute(args)

Nutrient Delivery Ratio.

Parameters:

args['workspace_dir'] (string) – path to current workspace
args['dem_path'] (string) – path to digital elevation map raster
args['lulc_path'] (string) – a path to landcover map raster
args['runoff_proxy_path'] (string) – a path to a runoff proxy raster
args['watersheds_path'] (string) – path to the watershed shapefile
args['biophysical_table_path'] (string) –
path to csv table on disk containing nutrient retention values.

For each nutrient type [t] in args[‘calc_[t]’] that is true, must contain the following headers:

’load_[t]’, ‘eff_[t]’, ‘crit_len_[t]’

If args[‘calc_n’] is True, must also contain the header ‘proportion_subsurface_n’ field.
args['calc_p'] (boolean) – if True, phosphorus is modeled, additionally if True then biophysical table must have p fields in them
args['calc_n'] (boolean) – if True nitrogen will be modeled, additionally biophysical table must have n fields in them.
args['results_suffix'] (string) – (optional) a text field to append to all output files
args['threshold_flow_accumulation'] – a number representing the flow accumulation in terms of upslope pixels.
args['k_param'] (number) – The Borselli k parameter. This is a calibration parameter that determines the shape of the relationship between hydrologic connectivity.
args['subsurface_critical_length_n'] (number) – The distance (traveled subsurface and downslope) after which it is assumed that soil retains nutrient at its maximum capacity, given in meters. If dissolved nutrients travel a distance smaller than Subsurface Critical Length, the retention efficiency will be lower than the Subsurface Maximum Retention Efficiency value defined. Setting this value to a distance smaller than the pixel size will result in the maximum retention efficiency being reached within one pixel only. Required if calc_n.
args['subsurface_eff_n'] (number) – The maximum nutrient retention efficiency that can be reached through subsurface flow, a floating point value between 0 and 1. This field characterizes the retention due to biochemical degradation in soils. Required if calc_n.
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.

Returns:

None

RouteDEM ¶

natcap.invest.routedem.execute(args)

RouteDEM: Hydrological routing.

This model exposes the pygeoprocessing D8 and Multiple Flow Direction routing functionality as an InVEST model.

This tool will always fill pits on the input DEM.

Parameters:

args['workspace_dir'] (string) – output directory for intermediate, temporary, and final files
args['results_suffix'] (string) – (optional) string to append to any output file names
args['dem_path'] (string) – path to a digital elevation raster
args['dem_band_index'] (int) – Optional. The band index to operate on. If not provided, band index 1 is assumed.
args['algorithm'] (string) – The routing algorithm to use. Must be one of ‘D8’ or ‘MFD’ (case-insensitive). Required when calculating flow direction, flow accumulation, stream threshold, and downslope distance.
args['calculate_flow_direction'] (bool) – If True, model will calculate flow direction for the filled DEM.
args['calculate_flow_accumulation'] (bool) – If True, model will calculate a flow accumulation raster. Only applies when args[‘calculate_flow_direction’] is True.
args['calculate_stream_threshold'] (bool) – if True, model will calculate a stream classification layer by thresholding flow accumulation to the provided value in args['threshold_flow_accumulation']. Only applies when args[‘calculate_flow_accumulation’] and args[‘calculate_flow_direction’] are True.
args['threshold_flow_accumulation'] (int) – The number of upslope cells that must flow into a cell before it’s classified as a stream.
args['calculate_downslope_distance'] (bool) – If True, and a stream threshold is calculated, model will calculate a downslope distance raster in units of pixels. Only applies when args[‘calculate_flow_accumulation’], args[‘calculate_flow_direction’], and args[‘calculate_stream_threshold’] are all True.
args['calculate_slope'] (bool) – If True, model will calculate a slope raster from the DEM.
args['calculate_stream_order'] – If True, model will create a vector of the Strahler stream order.
args['calculate_subwatersheds'] – If True, the model will create a vector of subwatersheds.
args['n_workers'] (int) – The n_workers parameter to pass to the task graph. The default is -1 if not provided.

Returns:

None

Scenario Generator: Proximity Based ¶

natcap.invest.scenario_gen_proximity.execute(args)

Scenario Generator: Proximity-Based.

Main entry point for proximity based scenario generator model.

Parameters:

args['workspace_dir'] (string) – output directory for intermediate, temporary, and final files
args['results_suffix'] (string) – (optional) string to append to any output files
args['base_lulc_path'] (string) – path to the base landcover map
args['replacement_lucode'] (string or int) – code to replace when converting pixels
args['area_to_convert'] (string or float) – max area (Ha) to convert
args['focal_landcover_codes'] (string) – a space separated string of landcover codes that are used to determine the proximity when refering to “towards” or “away” from the base landcover codes
args['convertible_landcover_codes'] (string) – a space separated string of landcover codes that can be converted in the generation phase found in args[‘base_lulc_path’].
args['n_fragmentation_steps'] (string) – an int as a string indicating the number of steps to take for the fragmentation conversion
args['aoi_path'] (string) – (optional) path to a shapefile that indicates area of interest. If present, the expansion scenario operates only under that AOI and the output raster is clipped to that shape.
args['convert_farthest_from_edge'] (boolean) – if True will run the conversion simulation starting from the furthest pixel from the edge and work inwards. Workspace will contain output files named ‘toward_base{suffix}.{tif,csv}.
args['convert_nearest_to_edge'] (boolean) – if True will run the conversion simulation starting from the nearest pixel on the edge and work inwards. Workspace will contain output files named ‘toward_base{suffix}.{tif,csv}.
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.

Scenic Quality ¶

natcap.invest.scenic_quality.scenic_quality.execute(args)

Scenic Quality.

Parameters:

args['workspace_dir'] (string) – (required) output directory for intermediate, temporary, and final files.
args['results_suffix'] (string) – (optional) string to append to any output file.
args['aoi_path'] (string) – (required) path to a vector that indicates the area over which the model should be run.
args['structure_path'] (string) – (required) path to a point vector that has the features for the viewpoints. Optional fields: ‘WEIGHT’, ‘RADIUS’ / ‘RADIUS2’, ‘HEIGHT’
args['dem_path'] (string) – (required) path to a digital elevation model raster.
args['refraction'] (float) – (required) number indicating the refraction coefficient to use for calculating curvature of the earth.
args['do_valuation'] (bool) – (optional) indicates whether to compute valuation. If False, per-viewpoint value will not be computed, and the summation of valuation rasters (vshed_value.tif) will not be created. Additionally, the Viewshed Quality raster will represent the weighted sum of viewsheds. Default: False.
args['valuation_function'] (string) – The type of economic function to use for valuation. One of “linear”, “logarithmic”, or “exponential”.
args['a_coef'] (float) – The “a” coefficient for valuation. Required if args['do_valuation'] is True.
args['b_coef'] (float) – The “b” coefficient for valuation. Required if args['do_valuation'] is True.
args['max_valuation_radius'] (float) – Past this distance from the viewpoint, the valuation raster’s pixel values will be set to 0. Required if args['do_valuation'] is True.
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

Seasonal Water Yield ¶

natcap.invest.seasonal_water_yield.seasonal_water_yield.execute(args)

Seasonal Water Yield.

Parameters:

args['workspace_dir'] (string) – output directory for intermediate, temporary, and final files
args['results_suffix'] (string) – (optional) string to append to any output files
args['threshold_flow_accumulation'] (number) – used when classifying stream pixels from the DEM by thresholding the number of upslope cells that must flow into a cell before it’s considered part of a stream.
args['et0_dir'] (string) – required if args[‘user_defined_local_recharge’] is False. Path to a directory that contains rasters of monthly reference evapotranspiration; units in mm.
args['precip_dir'] (string) – required if args[‘user_defined_local_recharge’] is False. A path to a directory that contains rasters of monthly precipitation; units in mm.
args['dem_raster_path'] (string) – a path to a digital elevation raster
args['lulc_raster_path'] (string) – a path to a land cover raster used to classify biophysical properties of pixels.
args['soil_group_path'] (string) – required if args[‘user_defined_local_recharge’] is False. A path to a raster indicating SCS soil groups where integer values are mapped to soil types
args['aoi_path'] (string) – path to a vector that indicates the area over which the model should be run, as well as the area in which to aggregate over when calculating the output Qb.
args['biophysical_table_path'] (string) – path to a CSV table that maps landcover codes paired with soil group types to curve numbers as well as Kc values. Headers must include ‘lucode’, ‘CN_A’, ‘CN_B’, ‘CN_C’, ‘CN_D’, ‘Kc_1’, ‘Kc_2’, ‘Kc_3’, ‘Kc_4’, ‘Kc_5’, ‘Kc_6’, ‘Kc_7’, ‘Kc_8’, ‘Kc_9’, ‘Kc_10’, ‘Kc_11’, ‘Kc_12’.
args['rain_events_table_path'] (string) – Not required if args[‘user_defined_local_recharge’] is True or args[‘user_defined_climate_zones’] is True. Path to a CSV table that has headers ‘month’ (1-12) and ‘events’ (int >= 0) that indicates the number of rain events per month
args['alpha_m'] (float or string) – required if args[‘monthly_alpha’] is false. Is the proportion of upslope annual available local recharge that is available in month m.
args['beta_i'] (float or string) – is the fraction of the upgradient subsidy that is available for downgradient evapotranspiration.
args['gamma'] (float or string) – is the fraction of pixel local recharge that is available to downgradient pixels.
args['user_defined_local_recharge'] (boolean) – if True, indicates user will provide pre-defined local recharge raster layer
args['l_path'] (string) – required if args[‘user_defined_local_recharge’] is True. If provided pixels indicate the amount of local recharge; units in mm.
args['user_defined_climate_zones'] (boolean) – if True, user provides a climate zone rain events table and a climate zone raster map in lieu of a global rain events table.
args['climate_zone_table_path'] (string) – required if args[‘user_defined_climate_zones’] is True. Contains monthly precipitation events per climate zone. Fields must be “cz_id”, “jan”, “feb”, “mar”, “apr”, “may”, “jun”, “jul”, “aug”, “sep”, “oct”, “nov”, “dec”.
args['climate_zone_raster_path'] (string) – required if args[‘user_defined_climate_zones’] is True, pixel values correspond to the “cz_id” values defined in args[‘climate_zone_table_path’]
args['monthly_alpha'] (boolean) – if True, use the alpha
args['monthly_alpha_path'] (string) – required if args[‘monthly_alpha’] is True. A CSV file.
args['n_workers'] (int) – (optional) indicates the number of processes to devote to potential parallel task execution. A value < 0 will use a single process, 0 will be non-blocking scheduling but single process, and >= 1 will make additional processes for parallel execution.

Returns:

None.

Sediment Delivery Ratio ¶

natcap.invest.sdr.sdr.execute(args)

Sediment Delivery Ratio.

This function calculates the sediment export and retention of a landscape using the sediment delivery ratio model described in the InVEST user’s guide.

Parameters:

args['workspace_dir'] (string) – output directory for intermediate, temporary, and final files
args['results_suffix'] (string) – (optional) string to append to any output file names
args['dem_path'] (string) – path to a digital elevation raster
args['erosivity_path'] (string) – path to rainfall erosivity index raster
args['erodibility_path'] (string) – a path to soil erodibility raster
args['lulc_path'] (string) – path to land use/land cover raster
args['watersheds_path'] (string) – path to vector of the watersheds
args['biophysical_table_path'] (string) – path to CSV file with biophysical information of each land use classes. contain the fields ‘usle_c’ and ‘usle_p’
args['threshold_flow_accumulation'] (number) – number of upslope pixels on the dem to threshold to a stream.
args['k_param'] (number) – k calibration parameter
args['sdr_max'] (number) – max value the SDR
args['ic_0_param'] (number) – ic_0 calibration parameter
args['drainage_path'] (string) – (optional) path to drainage raster that is used to add additional drainage areas to the internally calculated stream layer
args['l_max'] (number) – the maximum allowed value of the slope length parameter (L) in the LS factor. If the calculated value of L exceeds ‘l_max’ it will be clamped to this value.
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.

Returns:

None.

Urban Cooling ¶

natcap.invest.urban_cooling_model.execute(args)

Urban Cooling.

Parameters:

args['workspace_dir'] (str) – path to target output directory.
args['results_suffix'] (string) – (optional) string to append to any output file names
args['t_ref'] (str/float) – reference air temperature.
args['lulc_raster_path'] (str) – path to landcover raster. This raster must be in a linearly-projected CRS.
args['ref_eto_raster_path'] (str) – path to evapotranspiration raster.
args['aoi_vector_path'] (str) – path to desired AOI.
args['biophysical_table_path'] (str) – table to map landcover codes to Shade, Kc, and Albedo values. Must contain the fields ‘lucode’, ‘kc’, and ‘green_area’. If args['cc_method'] == 'factors', then this table must also contain the fields ‘shade’ and ‘albedo’. If args['cc_method'] == 'intensity', then this table must also contain the field ‘building_intensity’.
args['green_area_cooling_distance'] (float) – Distance (in m) over which large green areas (> 2 ha) will have a cooling effect.
args['t_air_average_radius'] (float) – radius of the averaging filter for turning T_air_nomix into T_air.
args['uhi_max'] (float) – Magnitude of the UHI effect.
args['do_energy_valuation'] (bool) – if True, calculate energy savings valuation for buildings.
args['do_productivity_valuation'] (bool) – if True, calculate work productivity valuation based on humidity and temperature.
args['avg_rel_humidity'] (float) – (optional, depends on ‘do_productivity_valuation’) Average relative humidity (0-100%).
args['building_vector_path'] – (str) (optional, depends on ‘do_energy_valuation’) path to a vector of building footprints that contains at least the field ‘type’.
args['energy_consumption_table_path'] (str) – (optional, depends on ‘do_energy_valuation’) path to a table that maps building types to energy consumption. Must contain at least the fields ‘type’ and ‘consumption’.
args['cc_method'] (str) – Either “intensity” or “factors”. If “intensity”, then the “building_intensity” column must be present in the biophysical table. If “factors”, then args['cc_weight_shade'], args['cc_weight_albedo'], args['cc_weight_eti'] may be set to alternative weights if desired.
args['cc_weight_shade'] (str/float) – floating point number representing the relative weight to apply to shade when calculating the cooling index. Default: 0.6
args['cc_weight_albedo'] (str/float) – floating point number representing the relative weight to apply to albedo when calculating the cooling index. Default: 0.2
args['cc_weight_eti'] (str/float) – floating point number representing the relative weight to apply to ETI when calculating the cooling index. Default: 0.2

Returns:

None.

Urban Flood Risk Mitigation ¶

natcap.invest.urban_flood_risk_mitigation.execute(args)

Urban Flood Risk Mitigation.

The model computes the peak flow attenuation for each pixel, delineates areas benefiting from this service, then calculates the monetary value of potential avoided damage to built infrastructure.

Parameters:

args['workspace_dir'] (string) – a path to the directory that will write output and other temporary files during calculation.
args['results_suffix'] (string) – appended to any output file name.
args['aoi_watersheds_path'] (string) – path to a shapefile of (sub)watersheds or sewersheds used to indicate spatial area of interest.
args['rainfall_depth'] (float) – depth of rainfall in mm.
args['lulc_path'] (string) – path to a landcover raster.
args['soils_hydrological_group_raster_path'] (string) – Raster with values equal to 1, 2, 3, 4, corresponding to soil hydrologic group A, B, C, or D, respectively (used to derive the CN number).
args['curve_number_table_path'] (string) – path to a CSV table that contains at least the headers ‘lucode’, ‘CN_A’, ‘CN_B’, ‘CN_C’, ‘CN_D’.
args['built_infrastructure_vector_path'] (string) – (optional) path to a vector with built infrastructure footprints. Attribute table contains a column ‘Type’ with integers (e.g. 1=residential, 2=office, etc.).
args['infrastructure_damage_loss_table_path'] (string) – (optional) path to a CSV table with columns ‘Type’ and ‘Damage’ with values of built infrastructure type from the ‘Type’ field in args['built_infrastructure_vector_path'] and potential damage loss (in currency/m^2).
args['n_workers'] (int) – (optional) 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.

Returns:

None.

Urban Nature Access ¶

natcap.invest.urban_nature_access.execute(args)

Urban Nature Access.

Parameters:

args['workspace_dir'] (string) – (required) Output directory for intermediate, temporary and final files.
args['results_suffix'] (string) – (optional) String to append to any output file.
args['n_workers'] (int) – (optional) The number of worker processes to use for executing the tasks of this model. If omitted, computation will take place in the current process.
args['lulc_raster_path'] (string) – (required) A string path to a GDAL-compatible land-use/land-cover raster containing integer landcover codes. Must be linearly projected in meters.
args['lulc_attribute_table'] (string) –
(required) A string path to a CSV with the following columns:
- lucode: (required) the integer landcover code represented.
- urban_nature: (required) a proportion (0-1) representing how much of this landcover type is urban nature. 0 indicates none of this type’s area is urban nature, 1 indicates all of this type’s area is urban nature.
- search_radius_m: (conditionally required) the search radius for this urban nature LULC class in meters. Required for all urban nature LULC codes if args['search_radius_mode'] == RADIUS_OPT_URBAN_NATURE
args['population_raster_path'] (string) – (required) A string path to a GDAL-compatible raster where pixels represent the population of that pixel. Must be linearly projected in meters.
args['admin_boundaries_vector_path'] (string) – (required) A string path to a GDAL-compatible vector containing polygon areas of interest, typically administrative boundaries. If this vector has any fields with fieldnames beginning with "pop_", these will be treated as representing the proportion of the population within an admin unit belonging to the given population group. The name of the population group (everything other than a leading "pop_") must uniquely identify the group.
args['urban_nature_demand'] (number) – (required) A positive, nonzero number indicating the required urban_nature, in m² per capita.
args['decay_function'] (string) – (required) The selected kernel type. Must be one of the keys in KERNEL_TYPES.
args['search_radius_mode'] (string) – (required). The selected search radius mode. Must be one of RADIUS_OPT_UNIFORM, RADIUS_OPT_URBAN_NATURE, or RADIUS_OPT_POP_GROUP.
args['search_radius'] (number) – Required if args['search_radius_mode'] == RADIUS_OPT_UNIFORM. The search radius in meters to use in the analysis.
args['population_group_radii_table'] (string) – (optional) A table associating population groups with a search radius for that population group. Population group fieldnames must match population group fieldnames in the aoi vector.
args['aggregate_by_pop_group'] (bool) – Whether to aggregate statistics by population groups in the target vector. This is implied when running the model with args['search_radius_mode'] == RADIUS_OPT_POP_GROUP

Returns:

None

Urban Stormwater Retention ¶

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

Visitation: Recreation and Tourism ¶

natcap.invest.recreation.recmodel_client.execute(args)

Recreation.

Execute recreation client model on remote server.

Parameters:

args['workspace_dir'] (string) – path to workspace directory
args['aoi_path'] (string) – path to AOI vector
args['hostname'] (string) – FQDN to recreation server
args['port'] (string or int) – port on hostname for recreation server
args['start_year'] (string) – start year in form YYYY. This year is the inclusive lower bound to consider points in the PUD and regression.
args['end_year'] (string) – end year in form YYYY. This year is the inclusive upper bound to consider points in the PUD and regression.
args['grid_aoi'] (boolean) – if true the polygon vector in args['aoi_path'] should be gridded into a new vector and the recreation model should be executed on that
args['grid_type'] (string) – optional, but must exist if args[‘grid_aoi’] is True. Is one of ‘hexagon’ or ‘square’ and indicates the style of gridding.
args['cell_size'] (string/float) – optional, but must exist if args['grid_aoi'] is True. Indicates the cell size of square pixels and the width of the horizontal axis for the hexagonal cells.
args['compute_regression'] (boolean) – if True, then process the predictor table and scenario table (if present).
args['predictor_table_path'] (string) –
required if args[‘compute_regression’] is True. Path to a table that describes the regression predictors, their IDs and types. Must contain the fields ‘id’, ‘path’, and ‘type’ where:
- ’id’: is a <=10 character length ID that is used to uniquely describe the predictor. It will be added to the output result shapefile attribute table which is an ESRI Shapefile, thus limited to 10 characters.
- ’path’: an absolute or relative (to this table) path to the predictor dataset, either a vector or raster type.
- ’type’: one of the following,
  ’raster_mean’: mean of values in the raster under the response polygon
  
  ’raster_sum’: sum of values in the raster under the response polygon
  
  ’point_count’: count of the points contained in the response polygon
  
  ’point_nearest_distance’: distance to the nearest point from the centroid of the response polygon
  
  ’line_intersect_length’: length of lines that intersect with the response polygon in projected units of AOI
  
  ’polygon_area’: area of the polygon contained within response polygon in projected units of AOI
  
  ’polygon_percent_coverage’: percent (0-100) of area of overlap between the predictor and each AOI grid cell
args['scenario_predictor_table_path'] (string) – (optional) if present runs the scenario mode of the recreation model with the datasets described in the table on this path. Field headers are identical to args['predictor_table_path'] and ids in the table are required to be identical to the predictor list.
args['results_suffix'] (string) – optional, if exists is appended to any output file paths.

Returns:

None

Wave Energy Production ¶

natcap.invest.wave_energy.execute(args)

Wave Energy.

Executes both the biophysical and valuation parts of the wave energy model (WEM). Files will be written on disk to the intermediate and output directories. The outputs computed for biophysical and valuation include: wave energy capacity raster, wave power raster, net present value raster, percentile rasters for the previous three, and a point shapefile of the wave points with attributes.

Parameters:

workspace_dir (str) – Where the intermediate and output folder/files will be saved. (required)
wave_base_data_path (str) – Directory location of wave base data including WAVEWATCH III (WW3) data and analysis area shapefile. (required)
analysis_area (str) – A string identifying the analysis area of interest. Used to determine wave data shapefile, wave data text file, and analysis area boundary shape. (required)
aoi_path (str) – A polygon OGR vector outlining a more detailed area within the analysis area. This vector should be projected with linear units being in meters. (required to run Valuation model)
machine_perf_path (str) – The path of a CSV file that holds the machine performance table. (required)
machine_param_path (str) – The path of a CSV file that holds the machine parameter table. (required)
dem_path (str) – The path of the Global Digital Elevation Model (DEM). (required)
results_suffix (str) – A python string of characters to append to each output filename (optional)
valuation_container (boolean) – Indicates whether the model includes valuation
land_gridPts_path (str) – A CSV file path containing the Landing and Power Grid Connection Points table. (required for Valuation)
machine_econ_path (str) – A CSV file path for the machine economic parameters table. (required for Valuation)
number_of_machines (int) – An integer specifying the number of machines for a wave farm site. (required for Valuation)
n_workers (int) – The number of worker processes to use for processing this model. If omitted, computation will take place in the current process. (optional)

Wind Energy Production ¶

natcap.invest.wind_energy.execute(args)

Wind Energy.

This module handles the execution of the wind energy model given the following dictionary:

Parameters:

workspace_dir (str) – a path to the output workspace folder (required)
wind_data_path (str) – path to a CSV file with the following header [‘LONG’,’LATI’,’LAM’, ‘K’, ‘REF’]. Each following row is a location with at least the Longitude, Latitude, Scale (‘LAM’), Shape (‘K’), and reference height (‘REF’) at which the data was collected (required)
aoi_vector_path (str) – a path to an OGR polygon vector that is projected in linear units of meters. The polygon specifies the area of interest for the wind data points. If limiting the wind farm bins by distance, then the aoi should also cover a portion of the land polygon that is of interest (optional for biophysical and no distance masking, required for biophysical and distance masking, required for valuation)
bathymetry_path (str) – a path to a GDAL raster that has the depth values of the area of interest (required)
land_polygon_vector_path (str) – a path to an OGR polygon vector that provides a coastline for determining distances from wind farm bins. Enabled by AOI and required if wanting to mask by distances or run valuation
global_wind_parameters_path (str) – a float for the average distance in kilometers from a grid connection point to a land connection point (required for valuation if grid connection points are not provided)
results_suffix (str) – a str to append to the end of the output files (optional)
turbine_parameters_path (str) – a path to a CSV file that holds the turbines biophysical parameters as well as valuation parameters (required)
number_of_turbines (int) – an integer value for the number of machines for the wind farm (required for valuation)
min_depth (float) – a float value for the minimum depth for offshore wind farm installation (meters) (required)
max_depth (float) – a float value for the maximum depth for offshore wind farm installation (meters) (required)
min_distance (float) – a float value for the minimum distance from shore for offshore wind farm installation (meters) The land polygon must be selected for this input to be active (optional, required for valuation)
max_distance (float) – a float value for the maximum distance from shore for offshore wind farm installation (meters) The land polygon must be selected for this input to be active (optional, required for valuation)
valuation_container (boolean) – Indicates whether model includes valuation
foundation_cost (float) – a float representing how much the foundation will cost for the specific type of turbine (required for valuation)
discount_rate (float) – a float value for the discount rate (required for valuation)
grid_points_path (str) – a path to a CSV file that specifies the landing and grid point locations (optional)
avg_grid_distance (float) – a float for the average distance in kilometers from a grid connection point to a land connection point (required for valuation if grid connection points are not provided)
price_table (boolean) – a bool indicating whether to use the wind energy price table or not (required)
wind_schedule (str) – a path to a CSV file for the yearly prices of wind energy for the lifespan of the farm (required if ‘price_table’ is true)
wind_price (float) – a float for the wind energy price at year 0 (required if price_table is false)
rate_change (float) – a float as a percent for the annual rate of change in the price of wind energy. (required if price_table is false)
n_workers (int) – The number of worker processes to use for processing this model. If omitted, computation will take place in the current process. (optional)

Returns:

None