- »
- InVEST Model Entry Points
- Edit on GitHub
All InVEST models share a consistent python API:
The model has a function called
executethat takes a single pythondict ("args") as its argument.This arguments dict contains an entry,
'workspace_dir', whichpoints to the folder on disk where all files created by the modelshould be saved.
Calling a model requires importing the model’s execute function and thencalling the model with the correct parameters. For example, if you wereto call the Carbon Storage and Sequestration model, your script mightinclude
import natcap.invest.carbon.carbon_combinedargs = { 'workspace_dir': 'path/to/workspace' # Other arguments, as needed for Carbon.}natcap.invest.carbon.carbon_combined.execute(args)
For examples of scripts that could be created around a model run,or multiple successive model runs, see Creating Sample Python Scripts.
Available Models and Tools:
Annual Water Yield: Reservoir Hydropower Production
Carbon
Coastal Blue Carbon
Coastal Blue Carbon Preprocessor
Coastal Vulnerability
Crop Production Percentile
Crop Production Regression
DelineateIt: Watershed Delineation
Execute the urban stormwater retention model
Forest Carbon Edge Effect
GLOBIO
Habitat Quality
Habitat Risk Assessment
Nutrient Delivery Ratio
Pollination
Recreation
RouteDEM: Hydrological routing
Scenario Generator: Proximity-Based
Scenic Quality
Seasonal Water Yield
Sediment Delivery Ratio
Urban Cooling
Urban Flood Risk Mitigation
Wave Energy
Wind Energy
Annual Water Yield: Reservoir Hydropower Production¶
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 writeoutput and other temporary files during calculation. (required)
args['lulc_path'] (string) – a path to a land use/land cover rasterwhose LULC indexes correspond to indexes in the biophysical tableinput. Used for determining soil retention and other biophysicalproperties of the landscape. (required)
args['depth_to_root_rest_layer_path'] (string) – a path to an inputraster describing the depth of “good” soil before reaching thisrestrictive layer (required)
args['precipitation_path'] (string) – a path to an input rasterdescribing the average annual precipitation value for each cell(mm) (required)
args['pawc_path'] (string) – a path to an input raster describing theplant available water content value for each cell. Plant AvailableWater Content fraction (PAWC) is the fraction of water that can bestored 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 theannual average evapotranspiration value for each cell. Potentialevapotranspiration is the potential loss of water from soil byboth evaporation from the soil and transpiration by healthyAlfalfa (or grass) if sufficient water is available (mm)(required)
args['watersheds_path'] (string) – a path to an input shapefile of thewatersheds of interest as polygons. (required)
args['sub_watersheds_path'] (string) – a path to an input shapefile ofthe 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 tableof land use/land cover classes, containing data on biophysicalcoefficients such as root_depth (mm) and Kc, which are required.A column with header LULC_veg is also required which shouldhave values of 1 or 0, 1 indicating a land cover type ofvegetation, a 0 indicating non vegetation or wetland, water.NOTE: these data are attributes of each LULC class rather thanattributes of individual cells in the raster map (required)
args['seasonality_constant'] (float) – floating point value between1 and 30 corresponding to the seasonal distribution ofprecipitation (required)
args['results_suffix'] (string) – a string that will be concatenatedonto the end of file names (optional)
args['demand_table_path'] (string) – (optional) if a non-empty string,a path to an input CSVtable of LULC classes, showing consumptive water use for eachlanduse / land-cover type (cubic meters per year) to calculatewater scarcity.
args['valuation_table_path'] (string) – (optional) if a non-emptystring, a path to an input CSV table ofhydropower stations with the following fields to calculatevaluation: ‘ws_id’, ‘time_span’, ‘discount’, ‘efficiency’,‘fraction’, ‘cost’, ‘height’, ‘kw_price’Required if
calculate_valuationis True.args['n_workers'] (int) – (optional) The number of worker processes touse for processing this model. If omitted, computation will takeplace in the current process.
- Returns
None
Carbon¶
natcap.invest.carbon.execute(args)Carbon.
Calculate the amount of carbon stocks given a landscape, or the differencedue to a future change, and/or the tradeoffs between that and a REDDscenario, and calculate economic valuation on those scenarios.
The model can operate on a single scenario, a combined present and futurescenario, as well as an additional REDD scenario.
- Parameters
args['workspace_dir'] (string) – a path to the directory that willwrite 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 thecurrent carbon stocks.
args['calc_sequestration'] (bool) – if true, sequestration shouldbe calculated and ‘lulc_fut_path’ and ‘do_redd’ should be defined.
args['lulc_fut_path'] (string) – a path to a raster representing futurelandcover scenario. Optional, but if present and well definedwill trigger a sequestration calculation.
args['do_redd'] (bool) – if true, REDD analysis should be calculatedand ‘lulc_redd_path’ should be defined
args['lulc_redd_path'] (string) – a path to a raster representing thealternative REDD scenario which is only possible if theargs[‘lulc_fut_path’] is present and well defined.
args['carbon_pools_path'] (string) – path to CSV or that indexes carbonstorage density to lulc codes. (required if ‘do_uncertainty’ isfalse)
args['lulc_cur_year'] (int/string) – an integer representing the yearof args[‘lulc_cur_path’] used if args[‘do_valuation’]is True.
args['lulc_fut_year'] (int/string) – an integer representing the yearof args[‘lulc_fut_path’] used in valuation if it exists.Required if args[‘do_valuation’] is True andargs[‘lulc_fut_path’] is present and well defined.
args['do_valuation'] (bool) – if true then run the valuation model onavailable outputs. Calculate NPV for a future scenario or a REDDscenario and report in final HTML document.
args['price_per_metric_ton_of_c'] (float) – Is the present value ofcarbon per metric ton. Used if args[‘do_valuation’] is presentand True.
args['discount_rate'] (float) – Discount rate used if NPV calculationsare required. Used if args[‘do_valuation’] is present andTrue.
args['rate_change'] (float) – Annual rate of change in price of carbonas a percentage. Used if args[‘do_valuation’] is present andTrue.
args['n_workers'] (int) – (optional) The number of worker processes touse for processing this model. If omitted, computation will takeplace 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 whereoutputs should be written.
args['results_suffix'] (string) – (optional) If provided, a stringsuffix that will be added to each output filename.
args['n_workers'] (int) – (optional) If provided, the number of workersto pass to
taskgraph.args['landcover_snapshot_csv'] (string) – The path to a transitionsCSV table containing transition years and the LULC rastersrepresenting 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 carbonprices for valuation. Defaults to
False.args['price_table_path'] (string) – The path to a table of prices to usefor valuation. Required if
args['use_price_table']isTrue.args['inflation_rate'] (number) – The rate of inflation. The numberprovided is multiplied by
0.01to compute the actual rate ofinflation. Required ifargs['use_price_table']isFalse.args['price'] (number) – The carbon price. Required if
args['use_price_table']isFalse.args['discount_rate'] (number) – The discount rate. The number providedis multiplied by
0.01to compute the actual discount rate.Required ifargs['do_economic_analysis'].args['biophysical_table_path'] (string) – The path to the biophysicaltable on disk. This table has many required columns. See
ARGS_SPECfor the required columns.args['landcover_transitions_table'] (string) – The path to the landcovertransitions table, indicating the behavior of carbon when thelandscape 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-transitionsacross the rasters. The preprocessor outputs a CSV file representing amatrix of land cover transitions, each cell pre-filled with a stringindicating whether carbon accumulates or is disturbed as a result of thetransition, if a transition occurs.
- Parameters
args['workspace_dir'] (string) – directory path to workspace
args['results_suffix'] (string) – append to outputs directory name ifprovided
args['lulc_lookup_table_path'] (string) – filepath of lulc lookup table
args['landcover_csv_path'] (string) – filepath to a CSV containing theyear and filepath to snapshot rasters on disk. The years may be inany 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 pointsto coastal hazards based on up to eight biophysical hazard indices.Also quantify the role of habitats in reducing the hazard. Optionallysummarize the population density in proximity to each shore point.
- Parameters
args['workspace_dir'] (string) – (required) a path to the directory thatwill write output and other temporary files during calculation.
args['results_suffix'] (string) – (optional) appended to any outputfilename.
args['aoi_vector_path'] (string) – (required) path to a polygon vectorthat is projected in a coordinate system with units of meters.The polygon should intersect the landmass and the shelf contourline.
args['model_resolution'] (string) – (required) distance in meters.Points are spaced along the coastline at intervals of thisdistance.
args['landmass_vector_path'] (string) – (required) path to a polygonvector representing landmasses in the region of interest.
args['wwiii_vector_path'] (string) – (required) path to a point vectorcontaining wind and wave information across the region of interest.
args['max_fetch_distance'] (string) – (required) maximum distancein meters to extend rays from shore points. Points with rays equalto this distance will accumulate ocean-driven wave exposure alongthose rays and local-wind-driven wave exposure along the shorterrays.
args['bathymetry_raster_path'] (string) – (required) path to a rasterrepresenting the depth below sea level, in negative meters. Shouldcover the area extending outward from the AOI to themax_fetch_distance.
args['shelf_contour_vector_path'] (string) – (required) path to apolyline vector delineating edges of the continental shelfor other bathymetry contour.
args['dem_path'] (string) – (required) path to a raster representing theelevation 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 computethe average elevation.
args['habitat_table_path'] (string) – (required) path to a CSV file withthe 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 relativeprotection offered by this habitat;‘protection distance (m)’: integer or float used as a searchradius around each shore point.
args['geomorphology_vector_path'] (string) – (optional) path to apolyline vector that has a field called “RANK” with values from1 to 5 in the attribute table.
args['geomorphology_fill_value'] (int) – (optional) a value from 1 to 5that will be used as a geomorphology rank for any points notproximate to the geomorphology_vector_path.
args['population_raster_path'] (string) – (optional) path a raster withvalues 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 computethe population density.
args['slr_vector_path'] (string) – (optional) path to point vectorcontaining 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 touse for processing this model. If omitted, computation will takeplace 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 clippedobserved map.
- Parameters
args['workspace_dir'] (string) – output directory for intermediate,temporary, and final files
args['results_suffix'] (string) – (optional) string to append to anyoutput file names
args['landcover_raster_path'] (string) – path to landcover raster
args['landcover_to_crop_table_path'] (string) –
path to a table thatconverts landcover types to crop names that has two headers:
lucode: integer value corresponding to a landcover code inargs[‘landcover_raster_path’].
crop_name: a string that must match one of the crops inargs[‘model_data_path’]/climate_bin_maps/[cropname]_*A ValueError is raised if strings don’t match.
args['aggregate_polygon_path'] (string) – path to polygon shapefilethat will be used to aggregate crop yields and total nutrientvalue. (optional, if value is None, then skipped)
args['model_data_path'] (string) –
path to the InVEST Crop Productionglobal data directory. This model expects that the followingdirectories 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 fordetails about how to download these data.
args['n_workers'] (int) – (optional) The number of worker processes touse for processing this model. If omitted, computation will takeplace 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 andproduce 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 anyoutput file names
args['landcover_raster_path'] (string) – path to landcover raster
args['landcover_to_crop_table_path'] (string) –
path to a table thatconverts landcover types to crop names that has two headers:
lucode: integer value corresponding to a landcover code inargs[‘landcover_raster_path’].
crop_name: a string that must match one of the crops inargs[‘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 tablethat 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 thename 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 vectorthat will be used to aggregate crop yields and total nutrientvalue. (optional, if value is None, then skipped)
args['model_data_path'] (string) –
path to the InVEST Crop Productionglobal data directory. This model expects that the followingdirectories 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 fordetails about how to download these data.
- Returns
None.
DelineateIt: Watershed Delineation¶
natcap.invest.delineateit.delineateit.execute(args)DelineateIt: Watershed Delineation.
This ‘model’ provides an InVEST-based wrapper around the pygeoprocessingrouting API for watershed delineation.
Upon successful completion, the following files are written to theoutput workspace:
snapped_outlets.gpkg- A GeoPackage with the points snappedto a nearby stream.watersheds.gpkg- a GeoPackage of watersheds determinedby the D8 routing algorithm.stream.tif- a GeoTiff representing detected streams based onthe providedflow_thresholdparameter. Values of 1 arestreams, values of 0 are not.
- Parameters
args['workspace_dir'] (string) – The selected folder is used as theworkspace all intermediate and output files will be written.If theselected folder does not exist, it will be created. If datasetsalready exist in the selected folder, they will be overwritten.(required)
args['results_suffix'] (string) – This text will be appended to the endof output files to help separate multiple runs. (optional)
args['dem_path'] (string) – A GDAL-supported raster file with anelevation for each cell. Make sure the DEM is corrected by fillingin sinks, and if necessary burning hydrographic features into theelevation model (recommended when unusual streams are observed.)See the ‘Working with the DEM’ section of the InVEST User’s Guidefor more information. (required)
args['outlet_vector_path'] (string) – This is a vector representinggeometries 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 thenearest stream pixel. If
True,args['flow_threshold']andargs['snap_distance']must also be defined.args['flow_threshold'] (int) – The number of upstream cells that mustinto a cell before it’s considered part of a stream such thatretention 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 aninvalid geometry is passed or skip it, including all validgeometries in the vector to be passed to delineation.If
False, this tool will crash if an invalid geometry isfound. IfTrue, invalid geometries will be left out ofthe vector to be delineated. Default: Trueargs['detect_pour_points'] (bool) – Whether to run the pour pointdetection algorithm. If True, detected pour points are used insteadof outlet_vector_path geometries. Default: False
args['n_workers'] (int) – The number of worker processes to use withtaskgraph. Defaults to -1 (no parallelism).
- Returns
None
Execute the urban stormwater retention model¶
natcap.invest.stormwater.execute(args)Execute the urban stormwater retention model.
- Parameters
args['workspace_dir'] (str) – path to a directory to write intermediateand final outputs. May already exist or not.
args['results_suffix'] (str, optional) – string to append to all outputfile names from this model run
args['n_workers'] (int) – if present, indicates how many workerprocesses should be used in parallel processing. -1 indicatessingle 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 pixelvalues 1, 2, 3, 4 correspond to groups A, B, C, D
args['precipitation_path'] (str) – path to raster of total annualprecipitation in millimeters
args['biophysical_table'] (str) – path to biophysical table with columns‘lucode’, ‘EMC_x’ (event mean concentration mg/L) for eachpollutant 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 ratioadjustment 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 roadcenterlines. Only used if args[‘adjust_retention_ratios’] is True.
args['aggregate_areas_path'] (str) – Optional path to polygon vector ofareas to aggregate results over.
args['replacement_cost'] (float) – Cost to replace stormwater retentiondevices in units currency per cubic meter
- 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 intropical forest pixels.
- Parameters
args['workspace_dir'] (string) – a path to the directory that will writeoutput and other temporary files during calculation. (required)
args['results_suffix'] (string) – a string to append to any output filename (optional)
args['n_nearest_model_points'] (int) – number of nearest neighbor modelpoints to search for
args['aoi_vector_path'] (string) – (optional) if present, a path to ashapefile that will be used to aggregate carbon stock results atthe end of the run.
args['biophysical_table_path'] (string) –
a path to a CSV table that hasat least the fields ‘lucode’ and ‘c_above’. If
args['compute_forest_edge_effects'] == True, table mustalso contain an ‘is_tropical_forest’ field. Ifargs['pools_to_calculate'] == 'all', this table must containthe fields ‘c_below’, ‘c_dead’, and ‘c_soil’.lucode: an integer that corresponds to landcover codes inthe rasterargs['lulc_raster_path']is_tropical_forest: either 0 or 1 indicating whether thelandcover type is forest (1) or not (0). If 1, the valueinc_aboveis ignored and instead calculated from theedge regression model.c_above: floating point number indicating tons of aboveground carbon per hectare for that landcover type{'c_below', 'c_dead', 'c_soil'}: three other optionalcarbon pools that will statically map landcover types to thecarbon densities in the table.
Example:
lucode,is_tropical_forest,c_above,c_soil,c_dead,c_below0,0,32.8,5,5.2,2.11,1,n/a,2.5,0.0,0.02,1,n/a,1.8,1.0,0.016,0,28.1,4.3,0.0,2.0
Note the “n/a” in
c_aboveare optional since that fieldis ignored whenis_tropical_forest==1.args['lulc_raster_path'] (string) – path to a integer landcover coderaster
args['pools_to_calculate'] (string) – if “all” then all carbon poolswill be calculted. If any other value only above ground carbonpools will be calculated and expect only a ‘c_above’ header inthe biophysical table. If “all” model expects ‘c_above’,‘c_below’, ‘c_dead’, ‘c_soil’ in header of biophysical_table andwill make a translated carbon map for each based off the landcovermap.
args['compute_forest_edge_effects'] (boolean) – if True, requiresbiophysical table to have ‘is_tropical_forest’ forest field, andany landcover codes that have a 1 in this column calculate carbonstocks 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 carbonedge models. Has at least the fields ‘method’, ‘theta1’, ‘theta2’,‘theta3’. Where ‘method’ is an int between 1..3 describing thebiomass regression model, and the thetas are floating point numbersthat 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 methodbiomass = 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 bywhich to multiply forest biomass to convert to carbon in the edgeeffect calculation.
args['n_workers'] (int) – (optional) The number of worker processes touse for processing this model. If omitted, computation will takeplace in the current process.
- Returns
None
GLOBIO¶
natcap.invest.globio.execute(args)GLOBIO.
The model operates in two modes. Mode (a) generates a landcover mapbased on a base landcover map and information about crop yields,infrastructure, and more. Mode (b) assumes the globio landcovermap is generated. These modes are used below to describe inputparameters.
- Parameters
args['workspace_dir'] (string) – output directory for intermediate,temporary, and final files
args['predefined_globio'] (boolean) – if True then “mode (b)” else“mode (a)”
args['results_suffix'] (string) – (optional) string to append to anyoutput files
args['lulc_path'] (string) – used in “mode (a)” path to a base landcovermap with integer codes
args['lulc_to_globio_table_path'] (string) –
used in “mode (a)” path totable that translates the land-cover args[‘lulc_path’] tointermediate GLOBIO classes, from which they will be furtherdifferentiated using the additional data in the model. Containsat least the following fields:
’lucode’: Land use and land cover class code of the datasetused. LULC codes match the ‘values’ column in the LULCraster of mode (b) and must be numeric and unique.
’globio_lucode’: The LULC code corresponding to the GLOBIO classto which it should be converted, using intermediate codesdescribed in the example below.
args['infrastructure_dir'] (string) – used in “mode (a) and (b)” a pathto a folder containing maps of either gdal compatible rasters orOGR compatible shapefiles. These data will be used in theinfrastructure to calculation of MSA.
args['pasture_path'] (string) – used in “mode (a)” path to pastureraster
args['potential_vegetation_path'] (string) – used in “mode (a)” path topotential vegetation raster
args['pasture_threshold'] (float) – used in “mode (a)”
args['intensification_fraction'] (float) – a value between 0 and 1denoting proportion of total agriculture that should be classifiedas ‘high input’
args['primary_threshold'] (float) – used in “mode (a)”
args['msa_parameters_path'] (string) – path to MSA classificationparameters
args['aoi_path'] (string) – (optional) if it exists then final MSAraster is summarized by AOI
args['globio_lulc_path'] (string) – used in “mode (b)” path topredefined globio raster.
args['n_workers'] (int) – (optional) The number of worker processes touse for processing this model. If omitted, computation will takeplace 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 LULCas described in the InVEST user’s guide. Optionally
executecalculateshabitat degradation and quality for a future LULC and habitat rarity forcurrent 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 willwrite output and other temporary files (required)
args['lulc_cur_path'] (string) – a path to an input land use/landcover raster (required)
args['lulc_fut_path'] (string) – a path to an input land use/landcover raster (optional)
args['lulc_bas_path'] (string) – a path to an input land use/landcover raster (optional, but required for rarity calculations)
args['threats_table_path'] (string) – a path to an input CSVcontaining data of all the considered threats. Each row is adegradation source and each column a different attribute of thesource 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 polygonshapefile containing data on the relative protection againstthreats (optional)
args['sensitivity_table_path'] (string) – a path to an input CSV fileof LULC types, whether they are considered habitat, and theirsensitivity to each threat (required)
args['half_saturation_constant'] (float) – a python float thatdetermines the spread and central tendency of habitat qualityscores (required)
args['results_suffix'] (string) – a python string that will be insertedinto all raster path paths just before the file extension.
args['n_workers'] (int) – (optional) The number of worker processes touse for processing this model. If omitted, computation will takeplace 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 filepath. (optional)
args['info_table_path'] (str) – a path to the CSV or Excel file thatcontains the name of the habitat (H) or stressor (s) on the
NAMEcolumn that matches the names in criteria_table_path.Each H/S has its corresponding vector or raster path on thePATHcolumn. TheSTRESSOR BUFFER (meters)column shouldhave a buffer value if theTYPEcolumn is a stressor.args['criteria_table_path'] (str) – a path to the CSV or Excel file thatcontains the set of criteria ranking of each stressor on eachhabitat.
args['resolution'] (int) – a number representing the desired pixeldimensions of output rasters in meters.
args['max_rating'] (str, int or float) – a number representing thehighest potential value that should be represented in rating in thecriteria scores table.
args['risk_eq'] (str) – a string identifying the equation that should beused in calculating risk scores for each H-S overlap cell. Thiswill be either ‘Euclidean’ or ‘Multiplicative’.
args['decay_eq'] (str) – a string identifying the equation that shouldbe used in calculating the decay of stressor buffer influence. Thiscan be ‘None’, ‘Linear’, or ‘Exponential’.
args['aoi_vector_path'] (str) – a path to the shapefile containing oneor more planning regions used to get the average risk value foreach habitat-stressor combination over each area. Optionally, ifeach of the shapefile features contain a ‘name’ field, it willbe used as a way of identifying each individual shape.
args['n_workers'] (int) – the number of worker processes touse for processing this model. If omitted, computation will takeplace in the current process. (optional)
args['visualize_outputs'] (bool) – if True, create output GeoJSONs andsave them in a visualization_outputs folder, so users can visualizeresults 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 diskcontaining nutrient retention values.
For each nutrient type [t] in args[‘calc_[t]’] that is true, mustcontain 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 inthem
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 toall output files
args['threshold_flow_accumulation'] – a number representing the flowaccumulation in terms of upstream pixels.
args['k_param'] (number) – The Borselli k parameter. This is acalibration parameter that determines the shape of therelationship between hydrologic connectivity.
args['subsurface_critical_length_n'] (number) – The distance (traveledsubsurface and downslope) after which it is assumed that soilretains nutrient at its maximum capacity, given in meters. Ifdissolved nutrients travel a distance smaller than SubsurfaceCritical Length, the retention efficiency will be lower than theSubsurface Maximum Retention Efficiency value defined. Setting thisvalue to a distance smaller than the pixel size will result in themaximum retention efficiency being reached within one pixel only.Required if
calc_n.args['subsurface_eff_n'] (number) – The maximum nutrient retentionefficiency that can be reached through subsurface flow, a floatingpoint value between 0 and 1. This field characterizes the retentiondue to biochemical degradation in soils. Required if
calc_n.args['n_workers'] (int) – if present, indicates how many workerprocesses should be used in parallel processing. -1 indicatessingle process mode, 0 is single process but non-blocking mode,and >= 1 is number of processes.
- Returns
None
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 outputfile path.
args['landcover_raster_path'] (string) – file path to a landcoverraster.
args['guild_table_path'] (string) –
file path to a table indicatingthe bee species to analyze in this model run. Table headersmust include:
- ’species’: a bee species whose column string names will
be referred to in other tables and the model will outputanalyses per species.
- one or more columns matching _NESTING_SUITABILITY_PATTERN
with values in the range [0.0, 1.0] indicating thesuitability of the given species to nest in a particularsubstrate.
- one or more columns matching _FORAGING_ACTIVITY_RE_PATTERN
with values in the range [0.0, 1.0] indicating therelative level of foraging activity for that speciesduring 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 thesum of all relative abundance weights in the table.
args['landcover_biophysical_table_path'] (string) –
path to a tablemapping landcover codes in args[‘landcover_path’] to indexes ofnesting availability for each nesting substrate referenced inguilds table as well as indexes of abundance of floral resourceson that landcover type per season in the bee activity columns ofthe guild table.
All indexes are in the range [0.0, 1.0].
- 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_PATTERNin the guild stable, a column matching the pattern in_LANDCOVER_NESTING_INDEX_HEADER.
For every season matching _FORAGING_ACTIVITY_RE_PATTERNin the guilds table, a column matchingthe pattern in _LANDCOVER_FLORAL_RESOURCES_INDEX_HEADER.
args['farm_vector_path'] (string) –
(optional) path to a single layerpolygon shapefile representing farms. If present will trigger thefarm 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.0, 1.0] representing
the proportion of wild pollinators to achieve a 50% yieldof that crop.
- p_dep (float): a number in the range [0.0, 1.0]
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 thebiophysical and guild table. Any areas that overlap thelandcover map will replace seasonal floral resources withthis value. Ranges from 0..1.
- n_[substrate] (float): One or more fields that match this
pattern such that substrate also matches the nestingsubstrate headers in the biophysical and guild table. Anyareas that overlap the landcover map will replace nestingsubstrate suitability with this value. Ranges from 0..1.
args['n_workers'] (int) – (optional) The number of worker processes touse for processing this model. If omitted, computation will takeplace in the current process.
- Returns
None
Recreation¶
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 yearis the inclusive lower bound to consider points in the PUD andregression.
args['end_year'] (string) – end year in form YYYY. This yearis the inclusive upper bound to consider points in the PUD andregression.
args['grid_aoi'] (boolean) – if true the polygon vector in
args['aoi_path']should be gridded into a new vector and therecreation model should be executed on thatargs['grid_type'] (string) – optional, but must exist ifargs[‘grid_aoi’] is True. Is one of ‘hexagon’ or ‘square’ andindicates the style of gridding.
args['cell_size'] (string/float) – optional, but must exist if
args['grid_aoi']is True. Indicates the cell size of squarepixels and the width of the horizontal axis for the hexagonalcells.args['compute_regression'] (boolean) – if True, then process thepredictor table and scenario table (if present).
args['predictor_table_path'] (string) –
required ifargs[‘compute_regression’] is True. Path to a table thatdescribes the regression predictors, their IDs and types. Mustcontain the fields ‘id’, ‘path’, and ‘type’ where:
’id’: is a <=10 character length ID that is used to uniquelydescribe the predictor. It will be added to the outputresult shapefile attribute table which is an ESRIShapefile, thus limited to 10 characters.
’path’: an absolute or relative (to this table) path to thepredictor dataset, either a vector or raster type.
’type’: one of the following,
’raster_mean’: mean of values in the raster under theresponse polygon
’raster_sum’: sum of values in the raster under theresponse polygon
’point_count’: count of the points contained in theresponse polygon
’point_nearest_distance’: distance to the nearest pointfrom the response polygon
’line_intersect_length’: length of lines that intersectwith the response polygon in projected units of AOI
’polygon_area’: area of the polygon contained withinresponse polygon in projected units of AOI
’polygon_percent_coverage’: percent (0-100) of area ofoverlap between the predictor and each AOI grid cell
args['scenario_predictor_table_path'] (string) – (optional) ifpresent runs the scenario mode of the recreation model with thedatasets described in the table on this path. Field headersare identical to
args['predictor_table_path']and ids in thetable are required to be identical to the predictor list.args['results_suffix'] (string) – optional, if exists is appended toany output file paths.
- Returns
None
RouteDEM: Hydrological routing¶
natcap.invest.routedem.execute(args)RouteDEM: Hydrological routing.
This model exposes the pygeoprocessing D8 and Multiple Flow Directionrouting 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 anyoutput 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 beone of ‘D8’ or ‘MFD’ (case-insensitive). Required when calculatingflow direction, flow accumulation, stream threshold, and downstreamdistance.
args['calculate_flow_direction'] (bool) – If True, model will calculateflow direction for the filled DEM.
args['calculate_flow_accumulation'] (bool) – If True, model willcalculate a flow accumulation raster. Only applies whenargs[‘calculate_flow_direction’] is True.
args['calculate_stream_threshold'] (bool) – if True, model willcalculate a stream classification layer by thresholding flowaccumulation to the provided value in
args['threshold_flow_accumulation']. Only applies whenargs[‘calculate_flow_accumulation’] andargs[‘calculate_flow_direction’] are True.args['threshold_flow_accumulation'] (int) – The number of upstreamcells that must flow into a cell before it’s classified as astream.
args['calculate_downstream_distance'] (bool) – If True, and a streamthreshold is calculated, model will calculate a downstreamdistance raster in units of pixels. Only applies whenargs[‘calculate_flow_accumulation’],args[‘calculate_flow_direction’], andargs[‘calculate_stream_threshold’] are all True.
args['calculate_slope'] (bool) – If True, model will calculate aslope raster from the DEM.
args['n_workers'] (int) – The
n_workersparameter to pass tothe task graph. The default is-1if 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 anyoutput files
args['base_lulc_path'] (string) – path to the base landcover map
args['replacement_lucode'] (string or int) – code to replace whenconverting pixels
args['area_to_convert'] (string or float) – max area (Ha) to convert
args['focal_landcover_codes'] (string) – a space separated string oflandcover codes that are used to determine the proximity whenrefering to “towards” or “away” from the base landcover codes
args['convertible_landcover_codes'] (string) – a space separated stringof landcover codes that can be converted in the generation phasefound in args[‘base_lulc_path’].
args['n_fragmentation_steps'] (string) – an int as a string indicatingthe number of steps to take for the fragmentation conversion
args['aoi_path'] (string) – (optional) path to a shapefile thatindicates area of interest. If present, the expansion scenariooperates only under that AOI and the output raster is clipped tothat shape.
args['convert_farthest_from_edge'] (boolean) – if True will run theconversion simulation starting from the furthest pixel from theedge and work inwards. Workspace will contain output files named‘toward_base{suffix}.{tif,csv}.
args['convert_nearest_to_edge'] (boolean) – if True will run theconversion simulation starting from the nearest pixel on theedge and work inwards. Workspace will contain output files named‘toward_base{suffix}.{tif,csv}.
args['n_workers'] (int) – (optional) The number of worker processes touse for processing this model. If omitted, computation will takeplace 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 forintermediate, temporary, and final files.
args['results_suffix'] (string) – (optional) string to append to anyoutput file.
args['aoi_path'] (string) – (required) path to a vector thatindicates the area over which the model should be run.
args['structure_path'] (string) – (required) path to a point vectorthat has the features for the viewpoints. Optional fields:‘WEIGHT’, ‘RADIUS’ / ‘RADIUS2’, ‘HEIGHT’
args['dem_path'] (string) – (required) path to a digital elevation modelraster.
args['refraction'] (float) – (required) number indicating the refractioncoefficient to use for calculating curvature of the earth.
args['do_valuation'] (bool) – (optional) indicates whether to computevaluation. If
False, per-viewpoint value will not be computed,and the summation of valuation rasters (vshed_value.tif) will notbe created. Additionally, the Viewshed Quality raster willrepresent the weighted sum of viewsheds. Default:False.args['valuation_function'] (string) – The type of economicfunction to use for valuation. One of “linear”, “logarithmic”,or “exponential”.
args['a_coef'] (float) – The “a” coefficient for valuation. Requiredif
args['do_valuation']isTrue.args['b_coef'] (float) – The “b” coefficient for valuation. Requiredif
args['do_valuation']isTrue.args['max_valuation_radius'] (float) – Past this distancefrom the viewpoint, the valuation raster’s pixel values will be setto 0. Required if
args['do_valuation']isTrue.args['n_workers'] (int) – (optional) The number of worker processes touse for processing this model. If omitted, computation will takeplace 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 anyoutput files
args['threshold_flow_accumulation'] (number) – used when classifyingstream pixels from the DEM by thresholding the number of upstreamcells that must flow into a cell before it’s consideredpart of a stream.
args['et0_dir'] (string) – required ifargs[‘user_defined_local_recharge’] is False. Path to a directorythat contains rasters of monthly reference evapotranspiration;units in mm.
args['precip_dir'] (string) – required ifargs[‘user_defined_local_recharge’] is False. A path to a directorythat 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 usedto classify biophysical properties of pixels.
args['soil_group_path'] (string) – required ifargs[‘user_defined_local_recharge’] is False. A path to a rasterindicating SCS soil groups where integer values are mapped to soiltypes
args['aoi_path'] (string) – path to a vector that indicates the areaover which the model should be run, as well as the area in which toaggregate over when calculating the output Qb.
args['biophysical_table_path'] (string) – path to a CSV table that mapslandcover codes paired with soil group types to curve numbers aswell 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 ifargs[‘user_defined_local_recharge’] is True orargs[‘user_defined_climate_zones’] is True. Path to a CSV tablethat has headers ‘month’ (1-12) and ‘events’ (int >= 0) thatindicates the number of rain events per month
args['alpha_m'] (float or string) – required if args[‘monthly_alpha’] isfalse. Is the proportion of upslope annual available localrecharge that is available in month m.
args['beta_i'] (float or string) – is the fraction of the upgradientsubsidy that is available for downgradient evapotranspiration.
args['gamma'] (float or string) – is the fraction of pixel localrecharge that is available to downgradient pixels.
args['user_defined_local_recharge'] (boolean) – if True, indicates userwill provide pre-defined local recharge raster layer
args['l_path'] (string) – required ifargs[‘user_defined_local_recharge’] is True. If provided pixelsindicate the amount of local recharge; units in mm.
args['user_defined_climate_zones'] (boolean) – if True, user providesa climate zone rain events table and a climate zone raster map inlieu of a global rain events table.
args['climate_zone_table_path'] (string) – required ifargs[‘user_defined_climate_zones’] is True. Contains monthlyprecipitation 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 ifargs[‘user_defined_climate_zones’] is True, pixel values correspondto 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 processesto devote to potential parallel task execution. A value < 0 willuse a single process, 0 will be non-blocking scheduling butsingle process, and >= 1 will make additional processes forparallel 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 landscapeusing the sediment delivery ratio model described in the InVEST user’sguide.
- Parameters
args['workspace_dir'] (string) – output directory for intermediate,temporary, and final files
args['results_suffix'] (string) – (optional) string to append to anyoutput file names
args['dem_path'] (string) – path to a digital elevation raster
args['erosivity_path'] (string) – path to rainfall erosivity indexraster
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 withbiophysical information of each land use classes. contain thefields ‘usle_c’ and ‘usle_p’
args['threshold_flow_accumulation'] (number) – number of upstream pixelson 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 thatis used to add additional drainage areas to the internallycalculated stream layer
args['n_workers'] (int) – if present, indicates how many workerprocesses should be used in parallel processing. -1 indicatessingle process mode, 0 is single process but non-blocking mode,and >= 1 is number of processes.
args['biophysical_table_lucode_field'] (str) – optional, if existsuse this instead of ‘lucode’.
- 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 anyoutput file names
args['t_ref'] (str/float) – reference air temperature.
args['lulc_raster_path'] (str) – path to landcover raster. This rastermust 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 toShade, 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’. Ifargs['cc_method'] == 'intensity', then thistable must also contain the field ‘building_intensity’.args['green_area_cooling_distance'] (float) – Distance (in m) overwhich large green areas (> 2 ha) will have a cooling effect.
args['t_air_average_radius'] (float) – radius of the averaging filterfor 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 savingsvaluation for buildings.
args['do_productivity_valuation'] (bool) – if True, calculate workproductivity 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 thatcontains 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 toenergy 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 bepresent in the biophysical table. If “factors”, then
args['cc_weight_shade'],args['cc_weight_albedo'],args['cc_weight_eti']may be set to alternative weightsif desired.args['cc_weight_shade'] (str/float) – floating point numberrepresenting the relative weight to apply to shade whencalculating the cooling index. Default: 0.6
args['cc_weight_albedo'] (str/float) – floating point numberrepresenting the relative weight to apply to albedo whencalculating the cooling index. Default: 0.2
args['cc_weight_eti'] (str/float) – floating point numberrepresenting the relative weight to apply to ETI whencalculating 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, delineatesareas benefiting from this service, then calculates the monetary value ofpotential avoided damage to built infrastructure.
- Parameters
args['workspace_dir'] (string) – a path to the directory that willwrite 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 ofinterest.
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 withvalues equal to 1, 2, 3, 4, corresponding to soil hydrologic groupA, B, C, or D, respectively (used to derive the CN number).
args['curve_number_table_path'] (string) – path to a CSV table thatcontains at least the headers ‘lucode’, ‘CN_A’, ‘CN_B’, ‘CN_C’,‘CN_D’.
args['built_infrastructure_vector_path'] (string) – (optional) path toa vector with built infrastructure footprints. Attribute tablecontains 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 valuesof built infrastructure type from the ‘Type’ field in
args['built_infrastructure_vector_path']and potential damageloss (in currency/m^2).args['n_workers'] (int) – (optional) if present, indicates how manyworker processes should be used in parallel processing. -1indicates single process mode, 0 is single process butnon-blocking mode, and >= 1 is number of processes.
- Returns
None.
Wave Energy¶
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 outputdirectories. 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 thewave points with attributes.
- Parameters
workspace_dir (str) – Where the intermediate and output folder/fileswill be saved. (required)
wave_base_data_path (str) – Directory location of wave base dataincluding WAVEWATCH III (WW3) data and analysis area shapefile.(required)
analysis_area (str) – A string identifying the analysis area ofinterest. Used to determine wave data shapefile, wave data textfile, and analysis area boundary shape. (required)
aoi_path (str) – A polygon OGR vector outlining a more detailed areawithin the analysis area. This vector should be projected withlinear units being in meters. (required to run Valuation model)
machine_perf_path (str) – The path of a CSV file that holds themachine performance table. (required)
machine_param_path (str) – The path of a CSV file that holds themachine 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 outputfilename (optional)
valuation_container (boolean) – Indicates whether the model includesvaluation
land_gridPts_path (str) – A CSV file path containing the Landing andPower Grid Connection Points table. (required for Valuation)
machine_econ_path (str) – A CSV file path for the machine economicparameters table. (required for Valuation)
number_of_machines (int) – An integer specifying the number of machinesfor a wave farm site. (required for Valuation)
n_workers (int) – The number of worker processes to use for processingthis model. If omitted, computation will take place in the currentprocess. (optional)
Wind Energy¶
natcap.invest.wind_energy.execute(args)Wind Energy.
This module handles the execution of the wind energy modelgiven 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 locationwith at least the Longitude, Latitude, Scale (‘LAM’),Shape (‘K’), and reference height (‘REF’) at which the data wascollected (required)
aoi_vector_path (str) – a path to an OGR polygon vector that isprojected in linear units of meters. The polygon specifies thearea of interest for the wind data points. If limiting the windfarm bins by distance, then the aoi should also cover a portionof the land polygon that is of interest (optional for biophysicaland no distance masking, required for biophysical and distancemasking, required for valuation)
bathymetry_path (str) – a path to a GDAL raster that has the depthvalues of the area of interest (required)
land_polygon_vector_path (str) – a path to an OGR polygon vector thatprovides a coastline for determining distances from wind farm bins.Enabled by AOI and required if wanting to mask by distances or runvaluation
global_wind_parameters_path (str) – a float for the average distancein kilometers from a grid connection point to a land connectionpoint (required for valuation if grid connection points are notprovided)
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 theturbines biophysical parameters as well as valuation parameters(required)
number_of_turbines (int) – an integer value for the number of machinesfor the wind farm (required for valuation)
min_depth (float) – a float value for the minimum depth for offshorewind farm installation (meters) (required)
max_depth (float) – a float value for the maximum depth for offshorewind farm installation (meters) (required)
min_distance (float) – a float value for the minimum distance from shorefor offshore wind farm installation (meters) The land polygon mustbe selected for this input to be active (optional, required forvaluation)
max_distance (float) – a float value for the maximum distance from shorefor offshore wind farm installation (meters) The land polygon mustbe selected for this input to be active (optional, required forvaluation)
valuation_container (boolean) – Indicates whether model includesvaluation
foundation_cost (float) – a float representing how much the foundationwill cost for the specific type of turbine (required for valuation)
discount_rate (float) – a float value for the discount rate (requiredfor valuation)
grid_points_path (str) – a path to a CSV file that specifies thelanding and grid point locations (optional)
avg_grid_distance (float) – a float for the average distance inkilometers 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 energyprice table or not (required)
wind_schedule (str) – a path to a CSV file for the yearly prices ofwind 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 changein the price of wind energy. (required if price_table is false)
n_workers (int) – The number of worker processes to use for processingthis model. If omitted, computation will take place in the currentprocess. (optional)
- Returns
None
