InVEST: Integrated Valuation of Ecosystem Services and Tradeoffs¶

Binary Dependencies¶

InVEST itself depends only on python packages, but many of these package dependencies depend on low-level libraries or have complex build processes. In recent history, some of these packages (notably, numpy and scipy) have started to release precompiled binary packages of their own, removing the need to install these packages through a system package manager. Others, however, remain easiest to install through a package manager.

$ sudo apt-get install python-setuptools python-gdal python-h5py python-rtree python-shapely python-matplotlib python-qt4

$ sudo yum install python-setuptools gdal-python h5py python-rtree python-shapely python-matplotlib PyQt4

$ brew install gdal hdf5 spatialindex pyqt matplotlib

Python Dependencies¶

Dependencies for natcap.invest are listed in requirements.txt:

gdal>=1.11.2,<2.0
h5py>=2.3.0
matplotlib
natcap.versioner>=0.4.2
numpy>=1.11.0
pyamg>=2.2.1
pygeoprocessing>=0.3.0a17
rtree>=0.8.2
scipy>=0.14.0
shapely
setuptools>=8.0

Additionally, PyQt4 is required to use the invest cli, but is not required for development against natcap.invest. PyQt4 is not currently available from the Python Package Index, but other sources and package managers allow for straightforward installation on Windows, Mac OS X, and Linux.

Installing from Source¶

Assuming you have a C/C++ compiler installed and configured for your system, and dependencies installed, the easiest way to install InVEST as a python package is:

$ pip install natcap.invest

If you are working within virtual environments, there is a documented issue with namespaces in setuptools that may cause problems when importing packages within the natcap namespace. The current workaround is to use these extra pip flags:

$ pip install natcap.invest --egg --no-binary :all:

Installing the latest development version¶

> pip install .\natcap.invest-3.3.0.post89+nfc4a8d4de776-cp27-none-win32.whl

$ pip install hg+https://bitbucket.org/natcap/invest@develop

Installing¶

The invest cli application is installed with the natcap.invest python package. See Installing InVEST

Usage¶

To run an InVEST model from the command-line, use the invest cli single entry point:

$ invest --help
usage: invest [-h] [--version] [--list] [model]

Integrated Valuation of Ecosystem Services and Tradeoffs.InVEST (Integrated
Valuation of Ecosystem Services and Tradeoffs) is a family of tools for
quantifying the values of natural capital in clear, credible, and practical
ways. In promising a return (of societal benefits) on investments in nature,
the scientific community needs to deliver knowledge and tools to quantify and
forecast this return. InVEST enables decision-makers to quantify the
importance of natural capital, to assess the tradeoffs associated with
alternative choices, and to integrate conservation and human development.
Older versions of InVEST ran as script tools in the ArcGIS ArcToolBox
environment, but have almost all been ported over to a purely open-source
python environment.

positional arguments:
  model       The model/tool to run. Use --list to show available
              models/tools. Identifiable model prefixes may also be used.

optional arguments:
  -h, --help  show this help message and exit
  --version   show program's version number and exit
  --list      List available models

To list the available models:

$ invest --list

To launch a model:

$ invest <modelname>

3.3.1 (2016-04-14)¶

• Refactored API documentation for readability, organization by relevant topics, and to allow docs to build on invest.readthedocs.io,

• Installation of natcap.invest now requires natcap.versioner. If this is not available on the system at runtime, setuptools will make it available at runtime.

• InVEST Windows installer now includes HISTORY.rst as the changelog instead of the old InVEST_Updates_<version> files.

• Habitat suitability model is generalized and released as an API only accessible model. It can be found at natcap.invest.habitat_suitability.execute. This model replaces the oyster habitat suitability model.

  • The refactor of this model requires an upgrade to numpy >= 1.11.0.

• Fixed a crash in the InVEST CLI where calling invest without a parameter would raise an exception on linux-based systems. (Issue #3528)

• Patched an issue in Seasonal Water Yield model where a nodata value in the landcover map that was equal to MAX_INT would cause an overflow error/crash.

• InVEST NSIS installer will now optionally install the Microsoft Visual C++ 2008 redistributable on Windows 7 or earlier. This addresses a known issue on Windows 7 systems when importing GDAL binaries (Issue #3515). Users opting to install this redistributable agree to abide by the terms and conditions therein.

• Removed the deprecated subpackage natcap.invest.optimization.

• Updated the InVEST license to legally define the Natural Capital Project.

• Corrected an issue in Coastal Vulnerability where an output shapefile was being recreated for each row, and where field values were not being stored correctly.

• Updated Scenario Generator model to add basic testing, file registry support, PEP8 and PEP257 compliance, and to fix several bugs.

• Updated Crop Production model to add a simplified UI, faster runtime, and more testing.

3.3.0 (2016-03-14)¶

• Refactored Wind Energy model to use a CSV input for wind data instead of a Binary file.

• Redesigned InVEST recreation model for a single input streamlined interface, advanced analytics, and refactored outputs. While the model is still based on “photo user days” old model runs are not backward compatable with the new model or interface. See the Recreation Model user’s guide chapter for details.

  • The refactor of this model requires an upgrade to GDAL >=1.11.0 <2.0 and numpy >= 1.10.2.

• Removed nutrient retention (water purification) model from InVEST suite and replaced it with the nutrient delivery ratio (NDR) model. NDR has been available in development relseases, but has now officially been added to the set of Windows Start Menu models and the “under development” tag in its users guide has been removed. See the InVEST user’s guide for details between the differences and advantages of NDR over the old nutrient model.

• Modified NDR by adding a required “Runoff Proxy” raster to the inputs. This allows the model to vary the relative intensity of nutrient runoff based on varying precipitation variability.

• Fixed a bug in the Area Change rule of the Rule-Based Scenario Generator, where units were being converted incorrectly. (Issue #3472) Thanks to Fosco Vesely for this fix.

• InVEST Seasonal Water Yield model released.

• InVEST Forest Carbon Edge Effect model released.

• InVEST Scenario Generator: Proximity Based model released and renamed the previous “Scenario Generator” to “Scenario Generator: Rule Based”.

• Implemented a blockwise exponential decay kernel generation function, which is now used in the Pollination and Habitat Quality models.

• GLOBIO now uses an intensification parameter and not a map to average all agriculture across the GLOBIO 8 and 9 classes.

• GLOBIO outputs modified so core outputs are in workspace and intermediate outputs are in a subdirectory called ‘intermediate_outputs’.

• Fixed a crash with the NDR model that could occur if the DEM and landcover maps were different resolutions.

• Refactored all the InVEST model user interfaces so that Workspace defaults to the user’s home “Documents” directory.

• Fixed an HRA bug where stessors with a buffer of zero were being buffered by 1 pixel

• HRA enhancement which creates a common raster to burn all input shapefiles onto, ensuring consistent alignment.

• Fixed an issue in SDR model where a landcover map that was smaller than the DEM would create extraneous “0” valued cells.

• New HRA feature which allows for “NA” values to be entered into the “Ratings” column for a habitat / stressor pair in the Criteria Ratings CSV. If ALL ratings are set to NA, the habitat / stressor will be treated as having no interaction. This means in the model, that there will be no overlap between the two sources. All rows parameters with an NA rating will not be used in calculating results.

• Refactored Coastal Blue Carbon model for greater speed, maintainability and clearer documentation.

• Habitat Quality bug fix when given land cover rasters with different pixel sizes than threat rasters. Model would use the wrong pixel distance for the convolution kernel.

• Light refactor of Timber model. Now using CSV input attribute file instead of DBF file.

• Fixed clipping bug in Wave Energy model that was not properly clipping polygons correctly. Found when using global data.

• Made the following changes / updates to the coastal vulnerability model:

  • Fixed a bug in the model where the geomorphology ranks were not always being used correctly.
  • Removed the HTML summary results output and replaced with a link to a dashboard that helps visualize and interpret CV results.
  • Added a point shapefile output: ‘outputs/coastal_exposure.shp’ that is a shapefile representation of the corresponding CSV table.
  • The model UI now requires the ‘Relief’ input. No longer optional.
  • CSV outputs and Shapefile outputs based on rasters now have x, y coorinates of the center of the pixel instead of top left of the pixel.

• Turning setuptools’ zip_safe to False for consistency across the Natcap Namespace.

• GLOBIO no longer requires user to specify a keyfield in the AOI.

• New feature to GLOBIO to summarize MSA by AOI.

• New feature to GLOBIO to use a user defined MSA parameter table to do the MSA thresholds for infrastructure, connectivity, and landuse type

• Documentation to the GLOBIO code base including the large docstring for ‘execute’.

3.2.0 (2015-05-31)¶

InVEST 3.2.0 is a major release with the addition of several experimental models and tools as well as an upgrade to the PyGeoprocessing core:

• Upgrade to PyGeoprocessing v0.3.0a1 for miscelaneous performance improvements to InVEST’s core geoprocessing routines.
• An alpha unstable build of the InVEST crop production model is released with partial documentation and sample data.
• A beta build of the InVEST fisheries model is released with documentation and sample data.
• An alpha unstable build of the nutrient delivery ratio (NDR) model is available directly under InVEST’s instalation directory at invest-x86/invest_ndr.exe; eventually this model will replace InVEST’s current “Nutrient” model. It is currently undocumented and unsupported but inputs are similar to that of InVEST’s SDR model.
• An alpha unstable build of InVEST’s implementation of GLOBIO is available directly under InVEST’s instalation directory at invest-x86/invest_globio.exe. It is currently undocumented but sample data are provided.
• DelinateIT, a watershed delination tool based on PyGeoprocessing’s d-infinity flow algorithm is released as a standalone tool in the InVEST repository with documentation and sample data.
• Miscelaneous performance patches and bug fixes.

3.1.3 (2015-04-23)¶

InVEST 3.1.3 is a hotfix release patching a memory blocking issue resolved in PyGeoprocessing version 0.2.1. Users might have experienced slow runtimes on SDR or other routed models.

3.1.2 (2015-04-15)¶

InVEST 3.1.2 is a minor release patching issues mostly related to the freshwater routing models and signed GDAL Byte datasets.

• Patching an issue where some projections were not regognized and InVEST reported an UnprojectedError.
• Updates to logging that make it easier to capture logging messages when scripting InVEST.
• Shortened water yield user interface height so it doesn’t waste whitespace.
• Update PyGeoprocessing dependency to version 0.2.0.
• Fixed an InVEST wide issue related to bugs stemming from the use of signed byte raster inputs that resulted in nonsensical outputs or KeyErrors.
• Minor performance updates to carbon model.
• Fixed an issue where DEMS with 32 bit ints and INT_MAX as the nodata value nodata value incorrectly treated the nodata value in the raster as a very large DEM value ultimately resulting in rasters that did not drain correctly and empty flow accumulation rasters.
• Fixed an issue where some reservoirs whose edges were clipped to the edge of the watershed created large plateaus with no drain except off the edge of the defined raster. Added a second pass in the plateau drainage algorithm to test for these cases and drains them to an adjacent nodata area if they occur.
• Fixed an issue in the Fisheries model where the Results Suffix input was invariably initializing to an empty string.
• Fixed an issue in the Blue Carbon model that prevented the report from being generated in the outputs file.

3.1.1 (2015-03-13)¶

InVEST 3.1.1 is a major performance and memory bug patch to the InVEST toolsuite. We recommend all users upgrade to this version.

• Fixed an issue surrounding reports of SDR or Nutrient model outputs of zero values, nodata holes, excessive runtimes, or out of memory errors. Some of those problems happened to be related to interesting DEMs that would break the flat drainage algorithm we have inside RouteDEM that adjusted the heights of those regions to drain away from higher edges and toward lower edges, and then pass the height adjusted dem to the InVEST model to do all its model specific calculations. Unfortunately this solution was not amenable to some degenerate DEM cases and we have now adjusted the algorithm to treat each plateau in the DEM as its own separate region that is processed independently from the other regions. This decreases memory use so we never effectively run out of memory at a minor hit to overall runtime. We also now adjust the flow direction directly instead of adjust the dem itself. This saves us from having to modify the DEM and potentially get it into a state where a drained plateau would be higher than its original pixel neighbors that used to drain into it.

There are side effects that result in sometimes large changes to un calibrated runs of SDR or nutrient. These are related to slightly different flow directions across the landscape and a bug fix on the distance to stream calculation.

• InVEST geoprocessing now uses the PyGeoprocessing package (v0.1.4) rather than the built in functionality that used to be in InVEST. This will not affect end users of InVEST but may be of interest to users who script InVEST calls who want a standalone Python processing package for raster stack math and hydrological routing. The project is hosted at https://bitbucket.org/richpsharp/pygeoprocessing.
• Fixed an marine water quality issue where users could input AOIs that were unprojected, but output pixel sizes were specified in meters. Really the output pixel size should be in the units of the polygon and are now specified as such. Additionally an exception is raised if the pixel size is too small to generate a numerical solution that is no longer a deep scipy error.
• Added a suffix parameter to the timber and marine water quality models that append a user defined string to the output files; consistent with most of the other InVEST models.
• Fixed a user interface issue where sometimes the InVEST model run would not open a windows explorer to the user’s workspace. Instead it would open to C:User[..]My Documents. This would often happen if there were spaces in the the workspace name or “/” characters in the path.
• Fixed an error across all InVEST models where a specific combination of rasters of different cell sizes and alignments and unsigned data types could create errors in internal interpolation of the raster stacks. Often these would appear as ‘KeyError: 0’ across a variety of contexts. Usually the ‘0’ was an erroneous value introduced by a faulty interpolation scheme.
• Fixed a MemoryError that could occur in the pollination and habitat quality models when the the base landcover map was large and the biophysical properties table allowed the effect to be on the order of that map. Now can use any raster or range values with only a minor hit to runtime performance.
• Fixed a serious bug in the plateau resolution algorithm that occurred on DEMs with large plateau areas greater than 10x10 in size. The underlying 32 bit floating point value used to record small height offsets did not have a large enough precision to differentiate between some offsets thus creating an undefined flow direction and holes in the flow accumulation algorithm.
• Minor performance improvements in the routing core, in some cases decreasing runtimes by 30%.
• Fixed a minor issue in DEM resolution that occurred when a perfect plateau was encountered. Rather that offset the height so the plateau would drain, it kept the plateau at the original height. This occurred because the uphill offset was nonexistent so the algorithm assumed no plateau resolution was needed. Perfect plateaus now drain correctly. In practice this kind of DEM was encountered in areas with large bodies of water where the remote sensing algorithm would classify the center of a lake 1 meter higher than the rest of the lake.
• Fixed a serious routing issue where divergent flow directions were not getting accumulated 50% of the time. Related to a division speed optimization that fell back on C-style modulus which differs from Python.
• InVEST SDR model thresholded slopes in terms of radians, not percent thus clipping the slope tightly between 0.001 and 1%. The model now only has a lower threshold of 0.00005% for the IC_0 factor, and no other thresholds. We believe this was an artifact left over from an earlier design of the model.
• Fixed a potential memory inefficiency in Wave Energy Model when computing the percentile rasters. Implemented a new memory efficient percentile algorithm and updated the outputs to reflect the new open source framework of the model. Now outputting csv files that describe the ranges and meaning of the percentile raster outputs.
• Fixed a bug in Habitat Quality where the future output “quality_out_f.tif” was not reflecting the habitat value given in the sensitivity table for the specified landcover types.

3.1.0 (2014-11-19)¶

InVEST 3.1.0 (http://www.naturalcapitalproject.org/download.html) is a major software and science milestone that includes an overhauled sedimentation model, long awaited fixes to exponential decay routines in habitat quality and pollination, and a massive update to the underlying hydrological routing routines. The updated sediment model, called SDR (sediment delivery ratio), is part of our continuing effort to improve the science and capabilities of the InVEST tool suite. The SDR model inputs are backwards comparable with the InVEST 3.0.1 sediment model with two additional global calibration parameters and removed the need for the retention efficiency parameter in the biophysical table; most users can run SDR directly with the data they have prepared for previous versions. The biophysical differences between the models are described in a section within the SDR user’s guide and represent a superior representation of the hydrological connectivity of the watershed, biophysical parameters that are independent of cell size, and a more accurate representation of sediment retention on the landscape. Other InVEST improvements to include standard bug fixes, performance improvements, and usability features which in part are described below:

• InVEST Sediment Model has been replaced with the InVEST Sediment Delivery Ratio model. See the SDR user’s guide chapter for the difference between the two.

• Fixed an issue in the pollination model where the exponential decay function decreased too quickly.

• Fixed an issue in the habitat quality model where the exponential decay function decreased too quickly and added back linear decay as an option.

• Fixed an InVEST wide issue where some input rasters that were signed bytes did not correctly map to their negative nodata values.

• Hydropower input rasters have been normalized to the LULC size so sampling error is the same for all the input watersheds.

• Adding a check to make sure that input biophysical parameters to the water yield model do not exceed invalid scientific ranges.

• Added a check on nutrient retention in case the upstream water yield was less than 1 so that the log value did not go negative. In that case we clamp upstream water yield to 0.

• A KeyError issue in hydropower was resolved that occurred when the input rasters were at such a coarse resolution that at least one pixel was completely contained in each watershed. Now a value of -9999 will be reported for watersheds that don’t contain any valid data.

• An early version of the monthly water yield model that was erroneously included in was in the installer; it was removed in this version.

• Python scripts necessary for running the ArcGIS version of Coastal Protection were missing. They’ve since been added back to the distribution.

• Raster calculations are now processed by raster block sizes. Improvements in raster reads and writes.

• Fixed an issue in the routing core where some wide DEMs would cause out of memory errors.

• Scenario generator marked as stable.

• Fixed bug in HRA where raster extents of shapefiles were not properly encapsulating the whole AOI.

• Fixed bug in HRA where any number of habitats over 4 would compress the output plots. Now extends the figure so that all plots are correctly scaled.

• Fixed a bug in HRA where the AOI attribute ‘name’ could not be an int. Should now accept any type.

• Fixed bug in HRA which re-wrote the labels if it was run immediately without closing the UI.

• Fixed nodata masking bug in Water Yield when raster extents were less than that covered by the watershed.

• Removed hydropower calibration parameter form water yield model.

• Models that had suffixes used to only allow alphanumeric characters. Now all suffix types are allowed.

• A bug in the core platform that would occasionally cause routing errors on irregularly pixel sized rasters was fixed. This often had the effect that the user would see broken streams and/or nodata values scattered through sediment or nutrient results.

• Wind Energy:

  • Added new framework for valuation component. Can now input a yearly price table that spans the lifetime of the wind farm. Also if no price table is made, can specify a price for energy and an annual rate of change.
  • Added new memory efficient distance transform functionality
  • Added ability to leave out ‘landing points’ in ‘grid connection points’ input. If not landing points are found, it will calculate wind farm directly to grid point distances

• Error message added in Wave Energy if clip shape has no intersection

• Fixed an issue where the data type of the nodata value in a raster might be different than the values in the raster. This was common in the case of 64 bit floating point values as nodata when the underlying raster was 32 bit. Now nodata values are cast to the underlying types which improves the reliability of many of the InVEST models.

3.0.1 (2014-05-19)¶

• Blue Carbon model released.
• HRA UI now properly reflects that the Resolution of Analysis is in meters, not meters squared, and thus will be applied as a side length for a raster pixel.
• HRA now accepts CSVs for ratings scoring that are semicolon separated as well as comma separated.
• Fixed a minor bug in InVEST’s geoprocessing aggregate core that now consistently outputs correct zonal stats from the underlying pixel level hydro outputs which affects the water yield, sediment, and nutrient models.
• Added compression to InVEST output geotiff files. In most cases this reduces output disk usage by a factor of 5.
• Fixed an issue where CSVs in the sediment model weren’t open in universal line read mode.
• Fixed an issue where approximating whether pixel edges were the same size was not doing an approximately equal function.
• Fixed an issue that made the CV model crash when the coastline computed from the landmass didn’t align perfectly with that defined in the geomorphology layer.
• Fixed an issue in the CV model where the intensity of local wave exposure was very low, and yielded zero local wave power for the majority of coastal segments.
• Fixed an issue where the CV model crashes if a coastal segment is at the edge of the shore exposure raster.
• Fixed the exposure of segments surrounded by land that appeared as exposed when their depth was zero.
• Fixed an issue in the CV model where the natural habitat values less than 5 were one unit too low, leading to negative habitat values in some cases.
• Fixed an exponent issue in the CV model where the coastal vulnerability index was raised to a power that was too high.
• Fixed a bug in the Scenic Quality model that prevented it from starting, as well as a number of other issues.
• Updated the pollination model to conform with the latest InVEST geoprocessing standards, resulting in an approximately 33% speedup.
• Improved the UI’s ability to remember the last folder visited, and to have all file and folder selection dialogs have access to this information.
• Fixed an issue in Marine Water Quality where the UV points were supposed to be optional, but instead raised an exception when not passed in.

3.0.0 (2014-03-23)¶

The 3.0.0 release of InVEST represents a shift away from the ArcGIS to the InVEST standalone computational platform. The only exception to this shift is the marine coastal protection tier 1 model which is still supported in an ArcGIS toolbox and has no InVEST 3.0 standalone at the moment. Specific changes are detailed below

• A standalone version of the aesthetic quality model has been developed and packaged along with this release. The standalone outperforms the ArcGIS equivalent and includes a valuation component. See the user’s guide for details.
• The core water routing algorithms for the sediment and nutrient models have been overhauled. The routing algorithms now correctly adjust flow in plateau regions, address a bug that would sometimes not route large sections of a DEM, and has been optimized for both run time and memory performance. In most cases the core d-infinity flow accumulation algorithm out performs TauDEM. We have also packaged a simple interface to these algorithms in a standalone tool called RouteDEM; the functions can also be referenced from the scripting API in the invest_natcap.routing package.
• The sediment and nutrient models are now at a production level release. We no longer support the ArcGIS equivalent of these models.
• The sediment model has had its outputs simplified with major changes including the removal of the ‘pixel mean’ outputs, a direct output of the pixel level export and retention maps, and a single output shapefile whose attribute table contains aggregations of sediment output values. Additionally all inputs to the sediment biophysical table including p, c, and retention coefficients are now expressed as a proportion between 0 and 1; the ArcGIS model had previously required those inputs were integer values between 0 and 1000. See the “Interpreting Results” section of sediment model for full details on the outputs.
• The nutrient model has had a similar overhaul to the sediment model including a simplified output structure with many key outputs contained in the attribute table of the shapefile. Retention coefficients are also expressed in proportions between 0 and 1. See the “Interpreting Results” section of nutrient model for full details on the outputs.
• Fixed a bug in Habitat Risk Assessment where the HRA module would incorrectly error if a criteria with a 0 score (meant to be removed from the assessment) had a 0 data quality or weight.
• Fixed a bug in Habitat Risk Assessment where the average E/C/Risk values across the given subregion were evaluating to negative numbers.
• Fixed a bug in Overlap Analysis where Human Use Hubs would error if run without inter-activity weighting, and Intra-Activity weighting would error if run without Human Use Hubs.
• The runtime performance of the hydropower water yield model has been improved.
• Released InVEST’s implementation of the D-infinity flow algorithm in a tool called RouteDEM available from the start menu.
• Unstable version of blue carbon available.
• Unstable version of scenario generator available.
• Numerous other minor bug fixes and performance enhacnements.

2.6.0 (2013-12-16)¶

The 2.6.0 release of InVEST removes most of the old InVEST models from the Arc toolbox in favor of the new InVEST standalone models. While we have been developing standalone equivalents for the InVEST Arc models since version 2.3.0, this is the first release in which we removed support for the deprecated ArcGIS versions after an internal review of correctness, performance, and stability on the standalones. Additionally, this is one of the last milestones before the InVEST 3.0.0 release later next year which will transition InVEST models away from strict ArcGIS dependence to a standalone form.

Specifically, support for the following models have been moved from the ArcGIS toolbox to their Windows based standalones: (1) hydropower/water yield, (2) finfish aquaculture, (3) coastal protection tier 0/coastal vulnerability, (4) wave energy, (5) carbon, (6) habitat quality/biodiversity, (7) pollination, (8) timber, and (9) overlap analysis. Additionally, documentation references to ArcGIS for those models have been replaced with instructions for launching standalone InVEST models from the Windows start menu.

This release also addresses minor bugs, documentation updates, performance tweaks, and new functionality to the toolset, including:

• A Google doc to provide guidance for scripting the InVEST standalone models: https://docs.google.com/document/d/158WKiSHQ3dBX9C3Kc99HUBic0nzZ3MqW3CmwQgvAqGo/edit?usp=sharing
• Fixed a bug in the sample data that defined Kc as a number between 0 and 1000 instead of a number between 0 and 1.
• Link to report an issue now takes user to the online forums rather than an email address.
• Changed InVEST Sediment model standalone so that retention values are now between 0 and 1 instead of 0 and 100.
• Fixed a bug in Biodiversity where if no suffix were entered output filenames would have a trailing underscore (_) behind them.
• Added documentation to the water purification/nutrient retention model documentation about the standalone outputs since they differ from the ArcGIS version of the model.
• Fixed an issue where the model would try to move the logfile to the workspace after the model run was complete and Windows would erroneously report that the move failed.
• Removed the separation between marine and freshwater terrestrial models in the user’s guide. Now just a list of models.
• Changed the name of InVEST “Biodiversity” model to “Habitat Quality” in the module names, start menu, user’s guide, and sample data folders.
• Minor bug fixes, performance enhancements, and better error reporting in the internal infrastructure.
• HRA risk in the unstable standalone is calculated differently from the last release. If there is no spatial overlap within a cell, there is automatically a risk of 0. This also applies to the E and C intermediate files for a given pairing. If there is no spatial overlap, E and C will be 0 where there is only habitat. However, we still create a recovery potential raster which has habitat- specific risk values, even without spatial overlap of a stressor. HRA shapefile outputs for high, medium, low risk areas are now calculated using a user-defined maximum number of overlapping stressors, rather than all potential stressors. In the HTML subregion averaged output, we now attribute what portion of risk to a habitat comes from each habitat-stressor pairing. Any pairings which don’t overlap will have an automatic risk of 0.
• Major changes to Water Yield : Reservoir Hydropower Production. Changes include an alternative equation for calculating Actual Evapotranspiration (AET) for non-vegetated land cover types including wetlands. This allows for a more accurate representation of processes on land covers such as urban, water, wetlands, where root depth values aren’t applicable. To differentiate between the two equations a column ‘LULC_veg’ has been added to the Biophysical table in Hydropower/input/biophysical_table.csv. In this column a 1 indicates vegetated and 0 indicates non-vegetated.
• The output structure and outputs have also change in Water Yield : Reservoir Hydropower Production. There is now a folder ‘output’ that contains all output files including a sub directory ‘per_pixel’ which has three pixel raster outputs. The subwatershed results are only calculated for the water yield portion and those results can be found as a shapefile, ‘subwatershed_results.shp’, and CSV file, ‘subwatershed_results.csv’. The watershed results can be found in similar files: watershed_results.shp and watershed_results.csv. These two files for the watershed outputs will aggregate the Scarcity and Valuation results as well.
• The evapotranspiration coefficients for crops, Kc, has been changed to a decimal input value in the biophysical table. These values used to be multiplied by 1000 so that they were in integer format, that pre processing step is no longer necessary.
• Changing support from richsharp@stanford.edu to the user support forums at http://ncp-yamato.stanford.edu/natcapforums.

2.5.6 (2013-09-06)¶

The 2.5.6 release of InVEST that addresses minor bugs, performance tweaks, and new functionality of the InVEST standalone models. Including:

• Change the changed the Carbon biophysical table to use code field name from LULC to lucode so it is consistent with the InVEST water yield biophysical table.
• Added Monte Carlo uncertainty analysis and documentation to finfish aquaculture model.
• Replaced sample data in overlap analysis that was causing the model to crash.
• Updates to the overlap analysis user’s guide.
• Added preprocessing toolkit available under C:{InVEST install directory}utils
• Biodiversity Model now exits gracefully if a threat raster is not found in the input folder.
• Wind Energy now uses linear (bilinear because its over 2D space?) interpolation.
• Wind Energy has been refactored to current API.
• Potential Evapotranspiration input has been properly named to Reference Evapotranspiration.
• PET_mn for Water Yield is now Ref Evapotranspiration times Kc (evapotranspiration coefficient).
• The soil depth field has been renamed ‘depth to root restricting layer’ in both the hydropower and nutrient retention models.
• ETK column in biophysical table for Water Yield is now Kc.
• Added help text to Timber model.
• Changed the behavior of nutrient retention to return nodata values when the mean runoff index is zero.
• Fixed an issue where the hydropower model didn’t use the suffix inputs.
• Fixed a bug in Biodiversity that did not allow for numerals in the threat names and rasters.
• Updated routing algorithm to use a modern algorithm for plateau direction resolution.
• Fixed an issue in HRA where individual risk pixels weren’t being calculated correctly.
• HRA will now properly detect in the preprocessed CSVs when criteria or entire habitat-stressor pairs are not desired within an assessment.
• Added an infrastructure feature so that temporary files are created in the user’s workspace rather than at the system level folder.  This lets users work in a secondary workspace on a USB attached hard drive and use the space of that drive, rather than the primary operating system drive.

2.5.5 (2013-08-06)¶

The 2.5.5 release of InVEST that addresses minor bugs, performance tweaks, and new functionality of the InVEST standalone models. Including:

• Production level release of the 3.0 Coastal Vulnerability model.

  • This upgrades the InVEST 2.5.4 version of the beta standalone CV to a full release with full users guide. This version of the CV model should be used in all cases over its ArcGIS equivalent.

• Production level release of the Habitat Risk Assessment model.

  • This release upgrades the InVEST 2.5.4 beta version of the standalone habitat risk assessment model. It should be used in all cases over its ArcGIS equivalent.

• Uncertainty analysis in Carbon model (beta)

  • Added functionality to assess uncertainty in sequestration and emissions given known uncertainty in carbon pool stocks. Users can now specify standard deviations of carbon pools with normal distributions as well as desired uncertainty levels. New outputs include masks for regions which both sequester and emit carbon with a high probability of confidence. Please see the “Uncertainty Analysis” section of the carbon user’s guide chapter for more information.

• REDD+ Scenario Analysis in Carbon model (beta)

  • Additional functionality to assist users evaluating REDD and REDD+ scenarios in the carbon model. The uncertainty analysis functionality can also be used with these scenarios. Please see the “REDD Scenario Analysis” section of the carbon user’s guide chapter for more information.

• Uncertainty analysis in Finfish Aquaculture model (beta)

  • Additionally functionality to account for uncertainty in alpha and beta growth parameters as well as histogram plots showing the distribution of harvest weights and net present value. Uncertainty analysis is performed through Monte Carlo runs that normally sample the growth parameters.

• Streamlined Nutrient Retention model functionality

  • The nutrient retention module no longer requires users to explicitly run the water yield model. The model now seamlessly runs water yield during execution.

• Beta release of the recreation model

  • The recreation is available for beta use with limited documentation.

• Full release of the wind energy model

  • Removing the ‘beta’ designation on the wind energy model.

Known Issues:

• Flow routing in the standalone sediment and nutrient models has a bug that prevents routing in some (not all) landscapes. This bug is related to resolving d-infinity flow directions across flat areas. We are implementing the solution in Garbrecht and Martx (1997). In the meanwhile the sediment and nutrient models are still marked as beta until this issue is resolved.

2.5.4 (2013-06-07)¶

This is a minor release of InVEST that addresses numerous minor bugs and performance tweaks in the InVEST 3.0 models. Including:

• Refactor of Wave Energy Model:

  • Combining the Biophysical and Valuation modules into one.
  • Adding new data for the North Sea and Australia
  • Fixed a bug where elevation values that were equal to or greater than zero were being used in calculations.
  • Fixed memory issues when dealing with large datasets.
  • Updated core functions to remove any use of depracated functions

• Performance updates to the carbon model.

• Nodata masking fix for rarity raster in Biodiversity Model.

  • When computing rarity from a base landuse raster and current or future landuse raster, the intersection of the two was not being properly taken.

• Fixes to the flow routing algorithms in the sediment and nutrient retention models in cases where stream layers were burned in by ArcGIS hydro tools. In those cases streams were at the same elevation and caused routing issues.

• Fixed an issue that affected several InVEST models that occured when watershed polygons were too small to cover a pixel. Excessively small watersheds are now handled correctly

• Arc model deprecation. We are deprecating the following ArcGIS versions of our InVEST models in the sense we recommend ALL users use the InVEST standalones over the ArcGIS versions, and the existing ArcGIS versions of these models will be removed entirely in the next release.

  • Timber
  • Carbon
  • Pollination
  • Biodiversity
  • Finfish Aquaculture

Known Issues:

• Flow routing in the standalone sediment and nutrient models has a bug that prevents routing in several landscapes. We’re not certain of the nature of the bug at the moment, but we will fix by the next release. Thus, sediment and nutrient models are marked as (beta) since in some cases the DEM routes correctly.

2.5.3 (2013-03-21)¶

This is a minor release of InVEST that fixes an issue with the HRA model that caused ArcGIS versions of the model to fail when calculating habitat maps for risk hotspots. This upgrade is strongly recommended for users of InVEST 2.5.1 or 2.5.2.

2.5.2 (2013-03-17)¶

This is a minor release of InVEST that fixes an issue with the HRA sample data that caused ArcGIS versions of the model to fail on the training data. There is no need to upgrade for most users unless you are doing InVEST training.

2.5.1 (2013-03-12)¶

This is a minor release of InVEST that does not add any new models, but does add additional functionality, stability, and increased performance to one of the InVEST 3.0 standalones:

• Pollination 3.0 Beta:

  • Fixed a bug where Windows users of InVEST could run the model, but most raster outputs were filled with nodata values.

Additionally, this minor release fixes a bug in the InVEST user interface where collapsible containers became entirely non-interactive.

2.5.0 (2013-03-08)¶

This a major release of InVEST that includes new standalone versions (ArcGIS is not required) our models as well as additional functionality, stability, and increased performance to many of the existing models. This release is timed to support our group’s annual training event at Stanford University. We expect to release InVEST 2.5.1 a couple of weeks after to address any software issues that arise during the training. See the release notes below for details of the release, and please contact richsharp@stanford.edu for any issues relating to software:

• new Sediment 3.0 Beta:

  • This is a standalone model that executes an order of magnitude faster than the original ArcGIS model, but may have memory issues with larger datasets. This fix is scheduled for the 2.5.1 release of InVEST.
  • Uses a d-infinity flow algorithm (ArcGIS version uses D8).
  • Includes a more accurate LS factor.
  • Outputs are now summarized by polygon rather than rasterized polygons. Users can view results directly as a table rather than sampling a GIS raster.

• new Nutrient 3.0 Beta:

  • This is a standalone model that executes an order of magnitude faster than the original ArcGIS model, but may have memory issues with larger datasets. This fix is scheduled for the 2.5.1 release of InVEST.
  • Uses a d-infinity flow algorithm (ArcGIS version uses D8).
  • Includes a more accurate LS factor.
  • Outputs are now summarized by polygon rather than rasterized polygons. Users can view results directly as a table rather than sampling a GIS raster.

• new Wind Energy:

  • A new offshore wind energy model. This is a standalone-only model available under the windows start menu.

• new Recreation Alpha:

  • This is a working demo of our soon to be released future land and near shore recreation model. The model itself is incomplete and should only be used as a demo or by NatCap partners that know what they’re doing.

• new Habitat Risk Assessment 3.0 Alpha:

  • This is a working demo of our soon to be released 3.0 version of habitat risk assessment. The model itself is incomplete and should only be used as a demo or by NatCap partners that know what they’re doing. Users that need to use the habitat risk assessment should use the ArcGIS version of this model.

• Improvements to the InVEST 2.x ArcGIS-based toolset:

  • Bug fixes to the ArcGIS based Coastal Protection toolset.

• Removed support for the ArcGIS invest_VERSION.mxd map. We expect to transition the InVEST toolset exclusive standalone tools in a few months. In preparation of this we are starting to deprecate parts of our old ArcGIS toolset including this ArcMap document. The InVEST ArcToolbox is still available in C:InVEST_2_5_0invest_250.tbx.

• Known issues:

  • The InVEST 3.0 standalones generate open source GeoTiffs as outputs rather than the proprietary ESRI Grid format. ArcGIS 9.3.1 occasionally displays these rasters incorrectly. We have found that these layers can be visualized in ArcGIS 9.3.1 by following convoluted steps: Right Click on the layer and select Properties; click on the Symbology tab; select Stretch, agree to calculate a histogram (this will create an .aux file that Arc can use for visualization), click “Ok”, remove the raster from the layer list, then add it back. As an alternative, we suggest using an open source GIS Desktop Tool like Quantum GIS or ArcGIS version 10.0 or greater.

• The InVEST 3.0 carbon model will generate inaccurate sequestration results if the extents of the current and future maps don’t align. This will be fixed in InVEST 2.5.1; in the meanwhile a workaround is to clip both LULCs so they have identical overlaps.
• A user reported an unstable run of InVEST 3.0 water yield. We are not certain what is causing the issue, but we do have a fix that will go out in InVEST 2.5.1.
• At the moment the InVEST standalones do not run on Windows XP. This appears to be related to an incompatibility between Windows XP and GDAL, the an open source gis library we use to create and read GIS data. At the moment we are uncertain if we will be able to fix this bug in future releases, but will pass along more information in the future.

2.4.5 (2013-02-01)¶

This is a minor release of InVEST that does not add any new models, but does add additional functionality, stability, and increased performance to many of the InVEST 3.0 standalones:

• Pollination 3.0 Beta:

  • Greatly improved memory efficiency over previous versions of this model.
  • 3.0 Beta Pollination Biophysical and Valuation have been merged into a single tool, run through a unified user interface.
  • Slightly improved runtime through the use of newer core InVEST GIS libraries.
  • Optional ability to weight different species individually. This feature adds a column to the Guilds table that allows the user to specify a relative weight for each species, which will be used before combining all species supply rasters.
  • Optional ability to aggregate pollinator abundances at specific points provided by an optional points shapefile input.
  • Bugfix: non-agricultural pixels are set to a value of 0.0 to indicate no value on the farm value output raster.
  • Bugfix: sup_val_<beename>_<scenario>.tif rasters are now saved to the intermediate folder inside the user’s workspace instead of the output folder.

• Carbon Biophysical 3.0 Beta:

  • Tweaked the user interface to require the user to provide a future LULC raster when the ‘Calculate Sequestration’ checkbox is checked.
  • Fixed a bug that restricted naming of harvest layers. Harvest layers are now selected simply by taking the first available layer.

• Better memory efficiency in hydropower model.

• Better support for unicode filepaths in all 3.0 Beta user interfaces.

• Improved state saving and retrieval when loading up previous-run parameters in all 3.0 Beta user interfaces.

• All 3.0 Beta tools now report elapsed time on completion of a model.

• All 3.0 Beta tools now provide disk space usage reports on completion of a model.

• All 3.0 Beta tools now report arguments at the top of each logfile.

• Biodiversity 3.0 Beta: The half-saturation constant is now allowed to be a positive floating-point number.

• Timber 3.0 Beta: Validation has been added to the user interface for this tool for all tabular and shapefile inputs.

• Fixed some typos in Equation 1 in the Finfish Aquaculture user’s guide.

• Fixed a bug where start menu items were not getting deleted during an InVEST uninstall.

• Added a feature so that if the user selects to download datasets but the datasets don’t successfully download the installation alerts the user and continues normally.

• Fixed a typo with tau in aquaculture guide, originally said 0.8, really 0.08.

• Improvements to the InVEST 2.x ArcGIS-based toolset:

  • Minor bugfix to Coastal Vulnerability, where an internal unit of measurements was off by a couple digits in the Fetch Calculator.
  • Minor fixes to various helper tools used in InVEST 2.x models.
  • Outputs for Hargreaves are now saved as geoTIFFs.
  • Thornwaite allows more flexible entering of hours of sunlight.

2.4.4 (2012-10-24)¶

• Fixes memory errors experienced by some users in the Carbon Valuation 3.0 Beta model.
• Minor improvements to logging in the InVEST User Interface
• Fixes an issue importing packages for some officially-unreleased InVEST models.

2.4.3 (2012-10-19)¶

• Fixed a minor issue with hydropower output vaulation rasters whose statistics were not pre-calculated. This would cause the range in ArcGIS to show ther rasters at -3e38 to 3e38.
• The InVEST installer now saves a log of the installation process to InVEST_<version>install_log.txt
• Fixed an issue with Carbon 3.0 where carbon output values were incorrectly calculated.
• Added a feature to Carbon 3.0 were total carbon stored and sequestered is output as part of the running log.
• Fixed an issue in Carbon 3.0 that would occur when users had text representations of floating point numbers in the carbon pool dbf input file.
• Added a feature to all InVEST 3.0 models to list disk usage before and after each run and in most cases report a low free space error if relevant.

2.4.2 (2012-10-15)¶

• Fixed an issue with the ArcMap document where the paths to default data were not saved as relative paths. This caused the default data in the document to not be found by ArcGIS.
• Introduced some more memory-efficient processing for Biodiversity 3.0 Beta. This fixes an out-of-memory issue encountered by some users when using very large raster datasets as inputs.

2.4.1 (2012-10-08)¶

• Fixed a compatibility issue with ArcGIS 9.3 where the ArcMap and ArcToolbox were unable to be opened by Arc 9.3.

2.4.0 (2012-10-05)¶

Changes in InVEST 2.4.0

General:

This is a major release which releases two additional beta versions of the InVEST models in the InVEST 3.0 framework. Additionally, this release introduces start menu shortcuts for all available InVEST 3.0 beta models. Existing InVEST 2.x models can still be found in the included Arc toolbox.

Existing InVEST models migrated to the 3.0 framework in this release include:

• Biodiversity 3.0 Beta

  • Minor bug fixes and usability enhancements
  • Runtime decreased by a factor of 210

• Overlap Analysis 3.0 Beta

  • In most cases runtime decreased by at least a factor of 15

  • Minor bug fixes and usability enhancements

  • Split into two separate tools:

    • Overlap Analysis outputs rasters with individually-weighted pixels
    • Overlap Analysis: Management Zones produces a shapefile output.

  • Updated table format for input activity CSVs

  • Removed the “grid the seascape” step

Updates to ArcGIS models:

• Coastal vulnerability

  • Removed the “structures” option
  • Minor bug fixes and usability enhancements

• Coastal protection (erosion protection)

  • Incorporated economic valuation option
  • Minor bug fixes and usability enhancements

Additionally there are a handful of minor fixes and feature enhancements:

• InVEST 3.0 Beta standalones (identified by a new InVEST icon) may be run from the Start Menu (on windows navigate to Start Menu -> All Programs -> InVEST 2.4.0
• Bug fixes for the calculation of raster statistics.
• InVEST 3.0 wave energy no longer requires an AOI for global runs, but encounters memory issues on machines with less than 4GB of RAM. This is a known issue that will be fixed in a minor release.
• Minor fixes to several chapters in the user’s guide.
• Minor bug fix to the 3.0 Carbon model: harvest maps are no longer required inputs.
• Other minor bug fixes and runtime performance tweaks in the 3.0 framework.
• Improved installer allows users to remove InVEST from the Windows Add/Remove programs menu.
• Fixed a visualization bug with wave energy where output rasters did not have the min/max/stdev calculations on them. This made the default visualization in arc be a gray blob.

2.3.0 (2012-08-02)¶

Changes in InVEST 2.3.0

General:

This is a major release which releases several beta versions of the InVEST models in the InVEST 3.0 framework. These models run as standalones, but a GIS platform is needed to edit and view the data inputs and outputs. Until InVEST 3.0 is released the original ArcGIS based versions of these tools will remain the release.

Existing InVEST models migrated to the 3.0 framework in this release include:

• Reservoir Hydropower Production 3.0 beta

  • Minor bug fixes.

• Finfish Aquaculture

  • Minor bug fixes and usability enhancements.

• Wave Energy 3.0 beta

  • Runtimes for non-global runs decreased by a factor of 7
  • Minor bugs in interpolation that exist in the 2.x model is fixed in 3.0 beta.

• Crop Pollination 3.0 beta

  • Runtimes decreased by a factor of over 10,000

This release also includes the new models which only exist in the 3.0 framework:

• Marine Water Quality 3.0 alpha with a preliminary user’s guide.

InVEST models in the 3.0 framework from previous releases that now have a standalone executable include:

• Managed Timber Production Model
• Carbon Storage and Sequestration

Additionally there are a handful of other minor fixes and feature enhancements since the previous release:

• Minor bug fix to 2.x sedimentation model that now correctly calculates slope exponentials.
• Minor fixes to several chapters in the user’s guide.
• The 3.0 version of the Carbon model now can value the price of carbon in metric tons of C or CO2.
• Other minor bug fixes and runtime performance tweaks in the 3.0 framework.

2.2.2 (2012-03-03)¶

Changes in InVEST 2.2.2

General:

This is a minor release which fixes the following defects:

-Fixed an issue with sediment retention model where large watersheds

allowed loading per cell was incorrectly rounded to integer values.

-Fixed bug where changing the threshold didn’t affect the retention output

because function was incorrectly rounded to integer values.

-Added total water yield in meters cubed to to output table by watershed.

-Fixed bug where smaller than default (2000) resolutions threw an error about

not being able to find the field in “unitynew”. With non-default resolution, “unitynew” was created without an attribute table, so one was created by force.

-Removed mention of beta state and ecoinformatics from header of software

license.

-Modified overlap analysis toolbox so it reports an error directly in the

toolbox if the workspace name is too long.

2.2.1 (2012-01-26)¶

Changes in InVEST 2.2.1

General:

This is a minor release which fixes the following defects:

-A variety of miscellaneous bugs were fixed that were causing crashes of the Coastal Protection model in Arc 9.3. -Fixed an issue in the Pollination model that was looking for an InVEST1005 directory. -The InVEST “models only” release had an entry for the InVEST 3.0 Beta tools, but was missing the underlying runtime. This has been added to the models only 2.2.1 release at the cost of a larger installer. -The default InVEST ArcMap document wouldn’t open in ArcGIS 9.3. It can now be opened by Arc 9.3 and above. -Minor updates to the Coastal Protection user’s guide.

2.2.0 (2011-12-22)¶

In this release we include updates to the habitat risk assessment model, updates to Coastal Vulnerability Tier 0 (previously named Coastal Protection), and a new tier 1 Coastal Vulnerability tool. Additionally, we are releasing a beta version of our 3.0 platform that includes the terrestrial timber and carbon models.

See the “Marine Models” and “InVEST 3.0 Beta” sections below for more details.

Marine Models

1. Marine Python Extension Check

   This tool has been updated to include extension requirements for the new Coastal Protection T1 model. It also reflects changes to the Habitat Risk Assessment and Coastal Protection T0 models, as they no longer require the PythonWin extension.

2. Habitat Risk Assessment (HRA)

   This model has been updated and is now part of three-step toolset. The first step is a new Ratings Survey Tool which eliminates the need for Microsoft Excel when users are providing habitat-stressor ratings. This Survey Tool now allows users to up- and down-weight the importance of various criteria. For step 2, a copy of the Grid the Seascape tool has been placed in the HRA toolset. In the last step, users will run the HRA model which includes the following updates:

   • New habitat outputs classifying risk as low, medium, and high
   • Model run status updates (% complete) in the message window
   • Improved habitat risk plots embedded in the output HTML

3. Coastal Protection

   This module is now split into sub-models, each with two parts. The first sub-model is Coastal Vulnerability (Tier 0) and the new addition is Coastal Protection (Tier 1).

   Coastal Vulnerability (T0) Step 1) Fetch Calculator - there are no updates to this tool. Step 2) Vulnerability Index

   • Wave Exposure: In this version of the model, we define wave exposure for sites facing the open ocean as the maximum of the weighted average of wave’s power coming from the ocean or generated by local winds. We weight wave power coming from each of the 16 equiangular sector by the percent of time that waves occur in that sector, and based on whether or not fetch in that sector exceeds 20km. For sites that are sheltered, wave exposure is the average of wave power generated by the local storm winds weighted by the percent occurrence of those winds in each sector. This new method takes into account the seasonality of wind and wave patterns (storm waves generally come from a preferential direction), and helps identify regions that are not exposed to powerful waves although they are open to the ocean (e.g. the leeside of islands).
   • Natural Habitats: The ranking is now computed using the rank of all natural habitats present in front of a segment, and we weight the lowest ranking habitat 50% more than all other habitats. Also, rankings and protective distance information are to be provided by CSV file instead of Excel. With this new method, shoreline segments that have more habitats than others will have a lower risk of inundation and/or erosion during storms.
   • Structures: The model has been updated to now incorporate the presence of structures by decreasing the ranking of shoreline segments that adjoin structures.

   Coastal Protection (T1) - This is a new model which plots the amount of sandy beach erosion or consolidated bed scour that backshore regions experience in the presence or absence of natural habitats. It is composed of two steps: a Profile Generator and Nearshore Waves and Erosion. It is recommended to run the Profile Generator before the Nearshore Waves and Erosion model.

   Step 1) Profile Generator: This tool helps the user generate a 1-dimensional bathymetric and topographic profile perpendicular to the shoreline at the user-defined location. This model provides plenty of guidance for building backshore profiles for beaches, marshes and mangroves. It will help users modify bathymetry profiles that they already have, or can generate profiles for sandy beaches if the user has not bathymetric data. Also, the model estimates and maps the location of natural habitats present in front of the region of interest. Finally, it provides sample wave and wind data that can be later used in the Nearshore Waves and Erosion model, based on computed fetch values and default Wave Watch III data.

   Step 2) Nearshore Waves and Erosion: This model estimates profiles of beach erosion or values of rates of consolidated bed scour at a site as a function of the type of habitats present in the area of interest. The model takes into account the protective effects of vegetation, coral and oyster reefs, and sand dunes. It also shows the difference of protection provided when those habitats are present, degraded, or gone.

4. Aesthetic Quality

   This model no longer requires users to provide a projection for Overlap Analysis. Instead, it uses the projection from the user-specified Area of Interest (AOI) polygon. Additionally, the population estimates for this model have been fixed.

InVEST 3.0 Beta

The 2.2.0 release includes a preliminary version of our InVEST 3.0 beta platform. It is included as a toolset named “InVEST 3.0 Beta” in the InVEST220.tbx. It is currently only supported with ArcGIS 10. To launch an InVEST 3.0 beta tool, double click on the desired tool in the InVEST 3.0 toolset then click “Ok” on the Arc toolbox screen that opens. The InVEST 3.0 tool panel has inputs very similar to the InVEST 2.2.0 versions of the tools with the following modifications:

InVEST 3.0 Carbon:

• Fixes a minor bug in the 2.2 version that ignored floating point values in carbon pool inputs.
• Separation of carbon model into a biophysical and valuation model.
• Calculates carbon storage and sequestration at the minimum resolution of the input maps.
• Runtime efficiency improved by an order of magnitude.
• User interface streamlined including dynamic activation of inputs based on user preference, direct link to documentation, and recall of inputs based on user’s previous run.

InVEST 3.0 Timber:

• User interface streamlined including dynamic activation of inputs based on user preference, direct link to documentation, and recall of inputs based on user’s previous run.

2.1.1 (2011-10-17)¶

Changes in InVEST 2.1.1

General:

This is a minor release which fixes the following defects:

-A truncation error was fixed on nutrient retention and sedimentation model that involved division by the number of cells in a watershed. Now correctly calculates floating point division. -Minor typos were fixed across the user’s guide.

2.1 Beta (2011-05-11)¶

Updates to InVEST Beta

InVEST 2.1 . Beta

Changes in InVEST 2.1

General:

1. InVEST versioning We have altered our versioning scheme. Integer changes will reflect major changes (e.g. the addition of marine models warranted moving from 1.x to 2.0). An increment in the digit after the primary decimal indicates major new features (e.g the addition of a new model) or major revisions. For example, this release is numbered InVEST 2.1 because two new models are included). We will add another decimal to reflect minor feature revisions or bug fixes. For example, InVEST 2.1.1 will likely be out soon as we are continually working to improve our tool. 2. HTML guide With this release, we have migrated the entire InVEST users. guide to an HTML format. The HTML version will output a pdf version for use off-line, printing, etc.

MARINE MODELS

1.Marine Python Extension Check

-This tool has been updated to allow users to select the marine models they intend to run. Based on this selection, it will provide a summary of which Python and ArcGIS extensions are necessary and if the Python extensions have been successfully installed on the user.s machine.

2.Grid the Seascape (GS)

-This tool has been created to allow marine model users to generate an seascape analysis grid within a specified area of interest (AOI).

-It only requires an AOI and cell size (in meters) as inputs, and produces a polygon grid which can be used as inputs for the Habitat Risk Assessment and Overlap Analysis models.

3. Coastal Protection

• This is now a two-part model for assessing Coastal Vulnerability. The first part is a tool for calculating fetch and the second maps the value of a Vulnerability Index, which differentiates areas with relatively high or low exposure to erosion and inundation during storms.
• The model has been updated to now incorporate coastal relief and the protective influence of up to eight natural habitat input layers.
• A global Wave Watch 3 dataset is also provided to allow users to quickly generate rankings for wind and wave exposure worldwide.

4. Habitat Risk Assessment (HRA)

This new model allows users to assess the risk posed to coastal and marine habitats by human activities and the potential consequences of exposure for the delivery of ecosystem services and biodiversity. The HRA model is suited to screening the risk of current and future human activities in order to prioritize management strategies that best mitigate risk.

5. Overlap Analysis

This new model maps current human uses in and around the seascape and summarizes the relative importance of various regions for particular activities. The model was designed to produce maps that can be used to identify marine and coastal areas that are most important for human use, in particular recreation and fisheries, but also other activities.

FRESHWATER MODELS

All Freshwater models now support ArcMap 10.

Sample data:

1. Bug fix for error in Water_Tables.mdb Biophysical table where many field values were shifted over one column relative to the correct field name.
2. Bug fix for incorrect units in erosivity layer.

Hydropower:

1.In Water Yield, new output tables have been added containing mean biophysical outputs (precipitation, actual and potential evapotranspiration, water yield) for each watershed and sub-watershed.

Water Purification:

1. The Water Purification Threshold table now allows users to specify separate thresholds for nitrogen and phosphorus. Field names thresh_n and thresh_p replace the old ann_load.
2. The Nutrient Retention output tables nutrient_watershed.dbf and nutrient_subwatershed.dbf now include a column for nutrient retention per watershed/sub-watershed.
3. In Nutrient Retention, some output file names have changed.
4. The user’s guide has been updated to explain more accurately the inclusion of thresholds in the biophysical service estimates.

Sedimentation:

1. The Soil Loss output tables sediment_watershed.dbf and sediment_subwatershed.dbf now include a column for sediment retention per watershed/sub-watershed.
2. In Soil Loss, some output file names have changed.
3. The default input value for Slope Threshold is now 75.
4. The user’s guide has been updated to explain more accurately the inclusion of thresholds in the biophysical service estimates.
5. Valuation: Bug fix where the present value was not being applied correctly.

2.0 Beta (2011-02-14)¶

Changes in InVEST 2.0

InVEST 1.005 is a minor release with the following modification:

1. Aesthetic Quality

   This new model allows users to determine the locations from which new nearshore or offshore features can be seen. It generates viewshed maps that can be used to identify the visual footprint of new offshore development.

2. Coastal Vulnerability

   This new model produces maps of coastal human populations and a coastal exposure to erosion and inundation index map. These outputs can be used to understand the relative contributions of different variables to coastal exposure and to highlight the protective services offered by natural habitats.

3. Aquaculture

   This new model is used to evaluate how human activities (e.g., addition or removal of farms, changes in harvest management practices) and climate change (e.g., change in sea surface temperature) may affect the production and economic value of aquacultured Atlantic salmon.

4. Wave Energy

   This new model provides spatially explicit information, showing potential areas for siting Wave Energy conversion (WEC) facilities with the greatest energy production and value. This site- and device-specific information for the WEC facilities can then be used to identify and quantify potential trade-offs that may arise when siting WEC facilities.

5. Avoided Reservoir Sedimentation

   • The name of this model has been changed to the Sediment Retention model.
   • We have added a water quality valuation model for sediment retention. The user now has the option to select avoided dredge cost analysis, avoided water treatment cost analysis or both. The water quality valuation approach is the same as that used in the Water Purification: Nutrient Retention model.
   • The threshold information for allowed sediment loads (TMDL, dead volume, etc.) are now input in a stand alone table instead of being included in the valuation table. This adjusts the biophysical service output for any social allowance of pollution. Previously, the adjustment was only done in the valuation model.
   • The watersheds and sub-watershed layers are now input as shapefiles instead of rasters.
   • Final outputs are now aggregated to the sub-basin scale. The user must input a sub-basin shapefile. We provide the Hydro 1K dataset as a starting option. See users guide for changes to many file output names.
   • Users are strongly advised not to interpret pixel-scale outputs for hydrological understanding or decision-making of any kind. Pixel outputs should only be used for calibration/validation or model checking.

6. Hydropower Production

   • The watersheds and sub-watershed layers are now input as shapefiles instead of rasters.
   • Final outputs are now aggregated to the sub-basin scale. The user must input a sub-basin shapefile. We provide the Hydro 1K dataset as a starting option. See users guide for changes to many file output names.
   • Users are strongly advised not to interpret pixel-scale outputs for hydrological understanding or decision-making of any kind. Pixel outputs should only be used for calibration/validation or model checking.
   • The calibration constant for each watershed is now input in a stand-alone table instead of being included in the valuation table. This makes running the water scarcity model simpler.

7. Water Purification: Nutrient Retention

   • The threshold information for allowed pollutant levels (TMDL, etc.) are now input in a stand alone table instead of being included in the valuation table. This adjusts the biophysical service output for any social allowance of pollution. Previously, the adjustment was only done in the valuation model.
   • The watersheds and sub-watershed layers are now input as shapefiles instead of rasters.
   • Final outputs are now aggregated to the sub-basin scale. The user must input a sub-basin shapefile. We provide the Hydro 1K dataset as a starting option. See users guide for changes to many file output names.
   • Users are strongly advised not to interpret pixel-scale outputs for hydrological understanding or decision-making of any kind. Pixel outputs should only be used for calibration/validation or model checking.

8. Carbon Storage and Sequestration

   The model now outputs an aggregate sum of the carbon storage.

9. Habitat Quality and Rarity

   This model had an error while running ReclassByACII if the land cover codes were not sorted alphabetically. This has now been corrected and it sorts the reclass file before running the reclassification

   The model now outputs an aggregate sum of the habitat quality.

10. Pollination

    In this version, the pollination model accepts an additional parameter which indicated the proportion of a crops yield that is attributed to wild pollinators.

Introduction¶

These are the steps that will need to be taken in order to use the batch scripting framework for InVEST models available in the natcap.invest python package.

Setting up your Python environment¶

1. Install Python 2.7.11 or later.

   Python can be downloaded from here. When installing, be sure to allow python.exe to be added to the path in the installation options.

2. Put pip on the PATH.

   The pip utility for installing python packages is already included with Python 2.7.9 and later. Be sure to add C:\Python27\Scripts to the Windows PATH environment variable so that pip can be called from the command line without needing to use its full path.

   After this is done (and you’ve opened a new command-line window), you will be able to use pip at the command-line to install packages like so:

   > pip install <packagename>
   

3. Install packages needed to run InVEST.

   Most (maybe even all) of these packages can be downloaded as precompiled wheels from Christoph Gohlke’s build page. Others should be able to be installed via pip install <packagename>.

   gdal>=1.11.2,<2.0
   h5py>=2.3.0
   matplotlib
   natcap.versioner>=0.4.2
   numpy>=1.11.0
   pyamg>=2.2.1
   pygeoprocessing>=0.3.0a17
   rtree>=0.8.2
   scipy>=0.14.0
   shapely
   setuptools>=8.0
   

4. Install the InVEST python package

   4a. Download a release of the natcap.invest python package.

   • Development (“nightly”) builds
   • Releases on the python package index

   4b. Install the downloaded python package..

   • win32.whl files are prebuilt binary distributions and can be installed via pip. See the pip docs for installing a package from a wheel
   • win32-py2.7.exe files are also prebuilt binary distributions, but cannot be installed by pip. Instead, double-click the downloaded file to launch an installer.
   • .zip and .tar.gz files are source archives. See Installing from Source for details.

Creating Sample Python Scripts¶

1. Launch InVEST Model

   Once an InVEST model is selected for scripting, launch that model from the Windows Start menu. This example in this guide follows the NDR model.

2. Fill in InVEST Model Input Parameters

   Once the user interface loads, populate the inputs in the model likely to be used in the Python script. For testing purposes the default InVEST’s data is appropriate. However, if a user wishes to write a batch for several InVEST runs, it would be reasonable to populate the user interface with data for the first run.

3. Generate a sample Python Script from the User Interface

   Open the Development menu at the top of the user interface and select “Save to python script...” and save the file to a known location.

4. Execute the script in the InVEST Python Environment

   Launch a Windows PowerShell from the Start menu (type “powershell” in the search box), then invoke the Python interpreter on the InVEST Python script from that shell. In this example the Python interpreter is installed in C:\Python27\python.exe and the script was saved in C:\Users\rpsharp\Desktop\ndr.py, thus the command to invoke the interpreter is:

   > C:\Python27\python.exe C:\Users\rpsharp\Desktop\ndr.py
   

5. Output Results

   As the model executes, status information will be printed to the console. Once complete, model results can be found in the workspace folder selected during the initial configuration.

Modifying a Python Script¶

InVEST Python scripts consist of two sections:

• The argument dictionary that represents the model’s user interface input boxes and parameters.
• The call to the InVEST model itself.

For reference, consider the following script generated by the Nutrient model with default data inputs:

"""
This is a saved model run from natcap.invest.ndr.ndr.
Generated: Mon 16 May 2016 03:52:59 PM
InVEST version: 3.3.0
"""

import natcap.invest.ndr.ndr

args = {
        u'k_param': u'2',
        u'runoff_proxy_uri': u'C:\InVEST_3.3.0_x86\Base_Data\Freshwater\precip',
        u'subsurface_critical_length_n': u'150',
        u'subsurface_critical_length_p': u'150',
        u'subsurface_eff_n': u'0.8',
        u'subsurface_eff_p': u'0.8',
        u'threshold_flow_accumulation': u'1000',
        u'biophysical_table_uri': u'C:\InVEST_3.3.0_x86\WP_Nutrient_Retention\Input\water_biophysical_table.csv',
        u'calc_n': True,
        u'calc_p': True,
        u'suffix': '',
        u'dem_uri': u'C:\InVEST_3.3.0_x86\Base_Data\Freshwater\dem',
        u'lulc_uri': u'C:\InVEST_3.3.0_x86\Base_Data\Freshwater\landuse_90',
        u'watersheds_uri': u'C:\InVEST_3.3.0_x86\Base_Data\Freshwater\watersheds.shp',
        u'workspace_dir': u'C:\InVEST_3.3.0_x86\ndr_workspace',
}

if __name__ == '__main__':
    natcap.invest.ndr.ndr.execute(args)

Elements to note:

• Parameter Python Dictionary: Key elements include the ‘args’ dictionary. Note the similarities between the key values such as ‘workspace_dir’ and the equivalent “Workspace” input parameter in the user interface. Every key in the ‘args’ dictionary has a corresponding reference in the user interface.

In the example below we’ll modify the script to execute the nutrient model for a parameter study of ‘threshold_flow_accumulation’.

• Execution of the InVEST model: The InVEST API invokes models with a consistent syntax where the module name that contains the InVEST model is listed first and is followed by a function called ‘execute’ that takes a single parameter called ‘args’. This parameter is the dictionary of input parameters discussed above. In this example, the line

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

executes the nutrient model end-to-end. If the user wishes to make batch calls to InVEST, this line will likely be placed inside a loop.

Example: Threshold Flow Accumulation Parameter Study¶

This example executes the InVEST NDR model on 10 values of threshold accumulation stepping from 500 to 1000 pixels in steps of 50. To modify the script above, replace the execution call with the following loop:

#Loops through the values 500, 550, 600, ... 1000
for threshold_flow_accumulation in range(500, 1001, 50):
    #set the accumulation threshold to the current value in the loop
    args['threshold_flow_accumulation'] = threshold_flow_accumulation
    #set the suffix to be accum### for the current threshold_flow_accumulation
    args['suffix'] = 'accum' + str(threshold_flow_accumulation)
    natcap.invest.ndr.ndr.execute(args)

This loop executes the InVEST nutrient model 10 times for accumulation values 500, 550, 600, ... 1000 and adds a suffix to the output files so results can be distinguished.

Example: Invoke NDR Model on a directory of Land Cover Maps¶

In this case we invoke the InVEST nutrient model on a directory of land cover data located at C:UserRichDesktoplandcover_data. As in the previous example, replace the last line in the UI generated Python script with:

import os
landcover_dir = r'C:\User\Rich\Desktop\landcover_data'
#Loop over all the filenames in the landcover dir
for landcover_file in os.listdir(landcover_dir):
    #Point the landuse uri parameter at the directory+filename
    args['lulc_uri'] = os.path.join(landcover_dir, landcover_file)
    #Make a useful suffix so we can differentiate the results
    args['suffix'] = 'landmap' + os.path.splitext(landcover_file)[0]
    #call the nutrient model
    natcap.invest.ndr.ndr.execute(args)

This loop covers all the files located in C:\User\Rich\Desktop\landcover_data and updates the relevant lulc_uri key in the args dictionary to each of those files during execution as well as making a useful suffix so output files can be distinguished from each other.

Example: Saving model log messages to a file¶

There are many cases where you may want or need to capture all of the log messages generated by the model. When we run models through the InVEST user interface application, the UI captures all of this logging and saves it to a logfile. We can replicate this behavior through the python logging package, by adding the following code just after the import statements in the example script.

import logging
import pygeoprocessing

# Write all NDR log messages to logfile.txt
MODEL_LOGGER = natcap.invest.ndr.ndr.LOGGER
handler = logging.FileHandler('logfile.txt')
MODEL_LOGGER.addHandler(handler)

# log pygeoprocessing messages to the same logfile
PYGEO_LOGGER = pygeoprocessing.geoprocessing.LOGGER
PYGEO_LOGGER.addHandler(handler)

This will capture all logging generated by the ndr model and by pygeoprocessing, writing all messages to logfile.txt. While this is a common use case, the logging package provides functionality for many more complex logging features. For more advanced use of the python logging module, refer to the Python project’s Logging Cookbook

Summary¶

The InVEST scripting framework was designed to assist InVEST users in automating batch runs or adding custom functionality to the existing InVEST software suite. Support questions can be directed to the NatCap support forums at http://forums.naturalcapitalproject.org.

Annual Water Yield: Reservoir Hydropower Production¶

natcap.invest.hydropower.hydropower_water_yield.execute(args)¶

Annual Water Yield: Reservoir Hydropower Production.

Executes the hydropower/water_yield model

Parameters:

args['workspace_dir'] (string) – a uri to the directory that will write output and other temporary files during calculation. (required) args['lulc_uri'] (string) – a uri 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_uri'] (string) – a uri to an input raster describing the depth of “good” soil before reaching this restrictive layer (required) args['precipitation_uri'] (string) – a uri to an input raster describing the average annual precipitation value for each cell (mm) (required) args['pawc_uri'] (string) – a uri 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_uri'] (string) – a uri 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_uri'] (string) – a uri to an input shapefile of the watersheds of interest as polygons. (required) args['sub_watersheds_uri'] (string) – a uri to an input shapefile of the subwatersheds of interest that are contained in the args['watersheds_uri'] shape provided as input. (optional) args['biophysical_table_uri'] (string) – a uri 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 10 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_uri'] (string) – a uri to an input CSV table of LULC classes, showing consumptive water use for each landuse / land-cover type (cubic meters per year) (required for water scarcity) args['valuation_table_uri'] (string) – a uri to an input CSV table of hydropower stations with the following fields (required for valuation): (‘ws_id’, ‘time_span’, ‘discount’, ‘efficiency’, ‘fraction’, ‘cost’, ‘height’, ‘kw_price’)

Returns:

None

Carbon Storage and Sequestration¶

natcap.invest.carbon.carbon_combined.execute(args)¶

Carbon Storage and Sequestration.

This can include the biophysical model, the valuation model, or both.

Parameters:

workspace_dir (string) – a uri to the directory that will write output and other temporary files during calculation. (required) suffix (string) – a string to append to any output file name (optional) do_biophysical (boolean) – whether to run the biophysical model lulc_cur_uri (string) – a uri to a GDAL raster dataset (required) lulc_cur_year (int) – An integer representing the year of lulc_cur used in HWP calculation (required if args contains a ‘hwp_cur_shape_uri’, or ‘hwp_fut_shape_uri’ key) lulc_fut_uri (string) – a uri to a GDAL raster dataset (optional if calculating sequestration) lulc_redd_uri (string) – a uri to a GDAL raster dataset that represents land cover data for the REDD policy scenario (optional). lulc_fut_year (int) – An integer representing the year of lulc_fut used in HWP calculation (required if args contains a ‘hwp_fut_shape_uri’ key) carbon_pools_uri (string) – a uri to a CSV or DBF dataset mapping carbon storage density to the lulc classifications specified in the lulc rasters. (required if ‘do_uncertainty’ is false) hwp_cur_shape_uri (String) – Current shapefile uri for harvested wood calculation (optional, include if calculating current lulc hwp) hwp_fut_shape_uri (String) – Future shapefile uri for harvested wood calculation (optional, include if calculating future lulc hwp) do_uncertainty (boolean) – a boolean that indicates whether we should do uncertainty analysis. Defaults to False if not present. carbon_pools_uncertain_uri (string) – as above, but has probability distribution data for each lulc type rather than point estimates. (required if ‘do_uncertainty’ is true) confidence_threshold (float) – a number between 0 and 100 that indicates the minimum threshold for which we should highlight regions in the output raster. (required if ‘do_uncertainty’ is True) sequest_uri (string) – uri to a GDAL raster dataset describing the amount of carbon sequestered. yr_cur (int) – the year at which the sequestration measurement started yr_fut (int) – the year at which the sequestration measurement ended do_valuation (boolean) – whether to run the valuation model carbon_price_units (string) – indicates whether the price is in terms of carbon or carbon dioxide. Can value either as ‘Carbon (C)’ or ‘Carbon Dioxide (CO2)’. V (string) – value of a sequestered ton of carbon or carbon dioxide in per metric ton (dollars) – r (int) – the market discount rate in terms of a percentage c (float) – the annual rate of change in the price of carbon

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir/',
    'suffix': '_results',
    'do_biophysical': True,
    'lulc_cur_uri': 'path/to/lulc_cur',
    'lulc_cur_year': 2014,
    'lulc_fut_uri': 'path/to/lulc_fut',
    'lulc_redd_uri': 'path/to/lulc_redd',
    'lulc_fut_year': 2025,
    'carbon_pools_uri': 'path/to/carbon_pools',
    'hwp_cur_shape_uri': 'path/to/hwp_cur_shape',
    'hwp_fut_shape_uri': 'path/to/hwp_fut_shape',
    'do_uncertainty': True,
    'carbon_pools_uncertain_uri': 'path/to/carbon_pools_uncertain',
    'confidence_threshold': 50.0,
    'sequest_uri': 'path/to/sequest_uri',
    'yr_cur': 2014,
    'yr_fut': 2025,
    'do_valuation': True,
    'carbon_price_units':, 'Carbon (C)',
    'V': 43.0,
    'r': 7,
    'c': 0,
}

Returns:	outputs – contains names of all output files
Return type:	dictionary

Coastal Blue Carbon¶

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

Coastal Blue Carbon.

Parameters:

workspace_dir (str) – location into which all intermediate and output files should be placed. results_suffix (str) – a string to append to output filenames. lulc_lookup_uri (str) – filepath to a CSV table used to convert the lulc code to a name. Also used to determine if a given lulc type is a coastal blue carbon habitat. lulc_transition_matrix_uri (str) – generated by the preprocessor. This file must be edited before it can be used by the main model. The left-most column represents the source lulc class, and the top row represents the destination lulc class. carbon_pool_initial_uri (str) – the provided CSV table contains information related to the initial conditions of the carbon stock within each of the three pools of a habitat. Biomass includes carbon stored above and below ground. All non-coastal blue carbon habitat lulc classes are assumed to contain no carbon. The values for ‘biomass’, ‘soil’, and ‘litter’ should be given in terms of Megatonnes CO2 e/ ha. carbon_pool_transient_uri (str) – the provided CSV table contains information related to the transition of carbon into and out of coastal blue carbon pools. All non-coastal blue carbon habitat lulc classes are assumed to neither sequester nor emit carbon as a result of change. The ‘yearly_accumulation’ values should be given in terms of Megatonnes of CO2 e/ha-yr. The ‘half-life’ values must be given in terms of years. The ‘disturbance’ values must be given as a decimal (e.g. 0.5 for 50%) of stock distrubed given a transition occurs away from a lulc-class. lulc_baseline_map_uri (str) – a GDAL-supported raster representing the baseline landscape/seascape. lulc_transition_maps_list (list) – a list of GDAL-supported rasters representing the landscape/seascape at particular points in time. Provided in chronological order. lulc_transition_years_list (list) – a list of years that respectively correspond to transition years of the rasters. Provided in chronological order. analysis_year (int) – optional. Indicates how many timesteps to run the transient analysis beyond the last transition year. Must come chronologically after the last transition year if provided. Otherwise, the final timestep of the model will be set to the last transition year. do_economic_analysis (bool) – boolean value indicating whether model should run economic analysis. do_price_table (bool) – boolean value indicating whether a price table is included in the arguments and to be used or a price and interest rate is provided and to be used instead. price (float) – the price per Megatonne CO2 e at the base year. interest_rate (float) – the interest rate on the price per Megatonne CO2e, compounded yearly. Provided as a percentage (e.g. 3.0 for 3%). price_table_uri (bool) – if args[‘do_price_table’] is set to True the provided CSV table is used in place of the initial price and interest rate inputs. The table contains the price per Megatonne CO2e sequestered for a given year, for all years from the original snapshot to the analysis year, if provided. discount_rate (float) – the discount rate on future valuations of sequestered carbon, compounded yearly. Provided as a percentage (e.g. 3.0 for 3%).

Example Args:

args = {
    'workspace_dir': 'path/to/workspace/',
    'results_suffix': '',
    'lulc_lookup_uri': 'path/to/lulc_lookup_uri',
    'lulc_transition_matrix_uri': 'path/to/lulc_transition_uri',
    'carbon_pool_initial_uri': 'path/to/carbon_pool_initial_uri',
    'carbon_pool_transient_uri': 'path/to/carbon_pool_transient_uri',
    'lulc_baseline_map_uri': 'path/to/baseline_map.tif',
    'lulc_transition_maps_list': [raster1_uri, raster2_uri, ...],
    'lulc_transition_years_list': [2000, 2005, ...],
    'analysis_year': 2100,
    'do_economic_analysis': '<boolean>',
    'do_price_table': '<boolean>',
    'price': '<float>',
    'interest_rate': '<float>',
    'price_table_uri': 'path/to/price_table',
    'discount_rate': '<float>'
}

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 prefilled with a string indicating whether carbon accumulates or is disturbed as a result of the transition, if a transition occurs.

Parameters:	workspace_dir (string) – directory path to workspace results_suffix (string) – append to outputs directory name if provided lulc_lookup_uri (string) – filepath of lulc lookup table lulc_snapshot_list (list) – a list of filepaths to lulc rasters

Example Args:

args = {
    'workspace_dir': 'path/to/workspace_dir/',
    'results_suffix': '',
    'lulc_lookup_uri': 'path/to/lookup.csv',
    'lulc_snapshot_list': ['path/to/raster1', 'path/to/raster2', ...]
}

Coastal Vulnerability¶

natcap.invest.coastal_vulnerability.coastal_vulnerability.execute(args)¶

Coastal Vulnerability.

Parameters:

workspace_dir (string) – The path to the workspace directory on disk (required) aoi_uri (string) – Path to an OGR vector on disk representing the area of interest. (required) landmass_uri (string) – Path to an OGR vector on disk representing the global landmass. (required) bathymetry_uri (string) – Path to a GDAL raster on disk representing the bathymetry. Must overlap with the Area of Interest if if provided. (optional) bathymetry_constant (int) – An int between 1 and 5 (inclusive). (optional) relief_uri (string) – Path to a GDAL raster on disk representing the elevation within the land polygon provided. (optional) relief_constant (int) – An int between 1 and 5 (inclusive). (optional) elevation_averaging_radius (int) – a positive int. The radius around which to compute the average elevation for relief. Must be in meters. (required) mean_sea_level_datum (int) – a positive int. This input is the elevation of Mean Sea Level (MSL) datum relative to the datum of the bathymetry layer that they provide. The model transforms all depths to MSL datum by subtracting the value provided by the user to the bathymetry. This input can be used to run the model for a future sea-level rise scenario. Must be in meters. (required) cell_size (int) – Cell size in meters. The higher the value, the faster the computation, but the coarser the output rasters produced by the model. (required) depth_threshold (int) – Depth in meters (integer) cutoff to determine if fetch rays project over deep areas. (optional) exposure_proportion (float) – Minimum proportion of rays that project over exposed and/or deep areas need to classify a shore segment as exposed. (required) geomorphology_uri (string) – A OGR-supported polygon vector file that has a field called “RANK” with values between 1 and 5 in the attribute table. (optional) geomorphology_constant (int) – Integer value between 1 and 5. If layer associated to this field is omitted, replace all shore points for this layer with a constant rank value in the computation of the coastal vulnerability index. If both the file and value for the layer are omitted, the layer is skipped altogether. habitats_directory_uri (string) – Directory containing OGR-supported polygon vectors associated with natural habitats. The name of these shapefiles should be suffixed with the ID that is specified in the natural habitats CSV file provided along with the habitats (optional) habitats_csv_uri (string) – A CSV file listing the attributes for each habitat. For more information, see ‘Habitat Data Layer’ section in the model’s documentation. (required if args['habitat_directory_uri'] is provided) habitat_constant (int) – Integer value between 1 and 5. If layer associated to this field is omitted, replace all shore points for this layer with a constant rank value in the computation of the coastal vulnerability index. If both the file and value for the layer are omitted, the layer is skipped altogether. (optional) area_computed (string) – Determine if the output data is about all the coast about sheltered segments only. Either 'sheltered' or 'both' (required) suffix (string) – A string that will be added to the end of the output file. (optional) climatic_forcing_uri (string) – An OGR-supported vector containing both wind wave information across the region of interest. (optional) climatic_forcing_constant (int) – Integer value between 1 and 5. If layer to this field is omitted, replace all shore points for this layer with a constant rank value in the computation of the coastal vulnerability index. If both the file and value for the layer are omitted, the layer is skipped altogether. (optional) continental_shelf_uri (string) – An OGR-supported polygon vector delineating edges of the continental shelf. Default is global continental shelf shapefile. If omitted, the user can specify depth contour. See entry below. (optional) depth_contour (int) – Used to delineate shallow and deep areas. Continental limit is at about 150 meters. (optional) sea_level_rise_uri (string) – An OGR-supported point or polygon vector file features with “Trend” fields in the attributes table. (optional) sea_level_rise_constant (int) – Integer value between 1 and 5. If layer to this field is omitted, replace all shore points for this layer with a constant rank value in the computation of the coastal vulnerability index. If both the file and value for the layer are omitted, the layer is skipped altogether. (optional) structures_uri (string) – An OGR-supported vector file containing rigid structures to identify the portions of the coast that is armored. (optional) structures_constant (int) – Integer value between 1 and 5. If layer associated this field is omitted, replace all shore points for this layer with a constant rank value in the computation of the coastal vulnerability index. If both the file and value for the layer are omitted, the layer is skipped altogether. (optional) population_uri (string) – A GDAL-supported raster file representing the population. (required) urban_center_threshold (int) – Minimum population required to consider shore segment a population center. (required) additional_layer_uri (string) – An OGR-supported vector file representing level rise, and will be used in the computation of coastal vulnerability and coastal vulnerability without habitat. (optional) additional_layer_constant (int) – Integer value between 1 and 5. If layer to this field is omitted, replace all shore points for this layer with a constant rank value in the computation of the coastal vulnerability index. If both the file and value for the layer are omitted, the layer is skipped altogether. (optional) rays_per_sector (int) – Number of rays used to subsample the fetch distance each of the 16 sectors. (required) max_fetch (int) – Maximum fetch distance computed by the model (>=60,000m). (optional) spread_radius (int) – Integer multiple of ‘cell size’. The coast from geomorphology layer could be of a better resolution than the global landmass, so the shores do not necessarily overlap. To make them coincide, the shore from the geomorphology layer is widened by 1 or more pixels. The value should be a multiple of ‘cell size’ that indicates how many pixels the coast from the geomorphology layer is widened. The widening happens on each side of the coast (n pixels landward, and n pixels seaward). (required) population_radius (int) – Radius length in meters used to count the number people leaving close to the coast. (optional)

Note

If neither args['bathymetry_uri'] nor args['bathymetry_constant'] is provided, bathymetry is ignored altogether.

If neither args['relief_uri'] nor args['relief_constant'] is provided, relief is ignored altogether.

If neither args['geomorphology_uri'] nor args['geomorphology_constant'] is provided, geomorphology is ignored altogether.

If neither args['climatic_forcing_uri'] nor args['climatic_forcing_constant'] is provided, climatic_forcing is ignored altogether.

If neither args['sea_level_rise_uri'] nor args['sea_level_rise_constant'] is provided, sea level rise is ignored altogether.

If neither args['structures_uri'] nor args['structures_constant'] is provided, structures is ignored altogether.

If neither args['additional_layer_uri'] nor args['additional_layer_constant'] is provided, the additional layer option is ignored altogether.

Example args:

args = {
    u'additional_layer_uri': u'CoastalProtection/Input/SeaLevRise_WCVI.shp',
    u'aoi_uri': u'CoastalProtection/Input/AOI_BarkClay.shp',
    u'area_computed': u'both',
    u'bathymetry_uri': u'Base_Data/Marine/DEMs/claybark_dem/hdr.adf',
    u'cell_size': 1000,
    u'climatic_forcing_uri': u'CoastalProtection/Input/WaveWatchIII.shp',
    u'continental_shelf_uri': u'CoastalProtection/Input/continentalShelf.shp',
    u'depth_contour': 150,
    u'depth_threshold': 0,
    u'elevation_averaging_radius': 5000,
    u'exposure_proportion': 0.8,
    u'geomorphology_uri': u'CoastalProtection/Input/Geomorphology_BarkClay.shp',
    u'habitats_csv_uri': u'CoastalProtection/Input/NaturalHabitat_WCVI.csv',
    u'habitats_directory_uri': u'CoastalProtection/Input/NaturalHabitat',
    u'landmass_uri': u'Base_Data/Marine/Land/global_polygon.shp',
    u'max_fetch': 12000,
    u'mean_sea_level_datum': 0,
    u'population_radius': 1000,
    u'population_uri': u'Base_Data/Marine/Population/global_pop/w001001.adf',
    u'rays_per_sector': 1,
    u'relief_uri': u'Base_Data/Marine/DEMs/claybark_dem/hdr.adf',
    u'sea_level_rise_uri': u'CoastalProtection/Input/SeaLevRise_WCVI.shp',
    u'spread_radius': 250,
    u'structures_uri': u'CoastalProtection/Input/Structures_BarkClay.shp',
    u'urban_center_threshold': 5000,
    u'workspace_dir': u'coastal_vulnerability_workspace'
}

Returns:	None

Crop Production¶

natcap.invest.crop_production.crop_production.execute(args)¶

Crop Production.

Parameters:

args['workspace_dir'] (str) – location into which all intermediate and output files should be placed. args['results_suffix'] (str) – a string to append to output filenames args['lookup_table'] (str) – filepath to a CSV table used to convert the crop code provided in the Crop Map to the crop name that can be used for searching through inputs and formatting outputs. args['aoi_raster'] (str) – a GDAL-supported raster representing a crop management scenario. args['dataset_dir'] (str) – the provided folder should contain a set of folders and data specified in the ‘Running the Model’ section of the model’s User Guide. args['yield_function'] (str) – the method used to compute crop yield. Can be one of three: ‘observed’, ‘percentile’, and ‘regression’. args['percentile_column'] (str) – for percentile yield function, the table column name must be provided so that the program can fetch the correct yield values for each climate bin. args['fertilizer_dir'] (str) – path to folder that contains a set of GDAL-supported rasters representing the amount of Nitrogen (N), Phosphorous (P2O5), and Potash (K2O) applied to each area of land (kg/ha). args['irrigation_raster'] (str) – filepath to a GDAL-supported raster representing whether irrigation occurs or not. A zero value indicates that no irrigation occurs. A one value indicates that irrigation occurs. If any other values are provided, irrigation is assumed to occur within that cell area. args['compute_nutritional_contents'] (boolean) – if true, calculates nutrition from crop production and creates associated outputs. args['nutrient_table'] (str) – filepath to a CSV table containing information about the nutrient contents of each crop. args['compute_financial_analysis'] (boolean) – if true, calculates economic returns from crop production and creates associated outputs. args['economics_table'] (str) – filepath to a CSV table containing information related to market price of a given crop and the costs involved with producing that crop.

Example Args:

args = {
    'workspace_dir': 'path/to/workspace_dir/',
    'results_suffix': 'scenario_name',
    'lookup_table': 'path/to/lookup_table',
    'aoi_raster': 'path/to/aoi_raster',
    'dataset_dir': 'path/to/dataset_dir/',
    'yield_function': 'regression',
    'percentile_column': 'yield_95th',
    'fertilizer_dir':'path/to/fertilizer_rasters_dir/',
    'irrigation_raster': 'path/to/is_irrigated_raster',
    'compute_nutritional_contents': True,
    'nutrient_table': 'path/to/nutrition_table',
    'compute_financial_analysis': True,
    'economics_table': 'path/to/economics_table'
}

Delineateit: Watershed Delineation¶

natcap.invest.routing.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.shp - an ESRI shapefile with the points snapped to a nearby stream.
• watersheds.shp - an ESRI shapefile of watersheds determined by the d-infinity 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:

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) results_suffix (string) – This text will be appended to the end of output files to help separate multiple runs. (optional) dem_uri (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) outlet_shapefile_uri (string) – This is a vector of points representing points that the watersheds should be built around. (required) flow_threshold (int) – The number of upstream cells that must 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. (required) snap_distance (int) – Pixel Distance to Snap Outlet Points (required)

Returns:

None

Finfish Aquaculture¶

natcap.invest.finfish_aquaculture.finfish_aquaculture.execute(args)¶

Finfish Aquaculture.

This function will take care of preparing files passed into the finfish aquaculture model. It will handle all files/inputs associated with biophysical and valuation calculations and manipulations. It will create objects to be passed to the aquaculture_core.py module. It may write log, warning, or error messages to stdout.

Parameters:

workspace_dir (string) – The directory in which to place all result files. ff_farm_loc (string) – URI that points to a shape file of fishery locations farm_ID (string) – column heading used to describe individual farms. Used to link GIS location data to later inputs. g_param_a (float) – Growth parameter alpha, used in modeling fish growth, should be an int or float. g_param_b (float) – Growth parameter beta, used in modeling fish growth, should be an int or float. g_param_tau (float) – Growth parameter tau, used in modeling fish growth, should be an int or float use_uncertainty (boolean) – g_param_a_sd (float) – (description) g_param_b_sd (float) – (description) num_monte_carlo_runs (int) – water_temp_tbl (string) – URI to a CSV table where daily water temperature values are stored from one year farm_op_tbl (string) – URI to CSV table of static variables for calculations outplant_buffer (int) – This value will allow the outplanting start day to be flexible plus or minus the number of days specified here. do_valuation (boolean) – Boolean that indicates whether or not valuation should be performed on the aquaculture model p_per_kg (float) – Market price per kilogram of processed fish frac_p (float) – Fraction of market price that accounts for costs rather than profit discount (float) – Daily market discount rate

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir',
    'ff_farm_loc': 'path/to/shapefile',
    'farm_ID': 'FarmID'
    'g_param_a': 0.038,
    'g_param_b': 0.6667,
    'g_param_tau': 0.08,
    'use_uncertainty': True,
    'g_param_a_sd': 0.005,
    'g_param_b_sd': 0.05,
    'num_monte_carlo_runs': 1000,
    'water_temp_tbl': 'path/to/water_temp_tbl',
    'farm_op_tbl': 'path/to/farm_op_tbl',
    'outplant_buffer': 3,
    'do_valuation': True,
    'p_per_kg': 2.25,
    'frac_p': 0.3,
    'discount': 0.000192,
}

Fisheries¶

natcap.invest.fisheries.fisheries.execute(args, create_outputs=True)¶

Fisheries.

Parameters:

args['workspace_dir'] (str) – location into which all intermediate and output files should be placed. args['results_suffix'] (str) – a string to append to output filenames args['aoi_uri'] (str) – location of shapefile which will be used as subregions for calculation. Each region must conatin a ‘Name’ attribute (case-sensitive) matching the given name in the population parameters csv file. args['timesteps'] (int) – represents the number of time steps that the user desires the model to run. args['population_type'] (str) – specifies whether the model is age-specific or stage-specific. Options will be either “Age Specific” or “Stage Specific” and will change which equation is used in modeling growth. args['sexsp'] (str) – specifies whether or not the age and stage classes are distinguished by sex. args['harvest_units'] (str) – specifies how the user wants to get the harvest data. Options are either “Individuals” or “Weight”, and will change the harvest equation used in core. (Required if args[‘val_cont’] is True) args['do_batch'] (bool) – specifies whether program will perform a single model run or a batch (set) of model runs. args['population_csv_uri'] (str) – location of the population parameters csv. This will contain all age and stage specific parameters. (Required if args[‘do_batch’] is False) args['population_csv_dir'] (str) – location of the directory that contains the Population Parameters CSV files for batch processing (Required if args[‘do_batch’] is True) args['spawn_units'] (str) – (description) args['total_init_recruits'] (float) – represents the initial number of recruits that will be used in calculation of population on a per area basis. args['recruitment_type'] (str) – Name corresponding to one of the built-in recruitment functions {‘Beverton-Holt’, ‘Ricker’, ‘Fecundity’, Fixed}, or ‘Other’, meaning that the user is passing in their own recruitment function as an anonymous python function via the optional dictionary argument ‘recruitment_func’. args['recruitment_func'] (function) – Required if args[‘recruitment_type’] is set to ‘Other’. See below for instructions on how to create a user-defined recruitment function. args['alpha'] (float) – must exist within args for BH or Ricker Recruitment. Parameter that will be used in calculation of recruitment. args['beta'] (float) – must exist within args for BH or Ricker Recruitment. Parameter that will be used in calculation of recruitment. args['total_recur_recruits'] (float) – must exist within args for Fixed Recruitment. Parameter that will be used in calculation of recruitment. args['migr_cont'] (bool) – if True, model uses migration args['migration_dir'] (str) – if this parameter exists, it means migration is desired. This is the location of the parameters folder containing files for migration. There should be one file for every age class which migrates. (Required if args[‘migr_cont’] is True) args['val_cont'] (bool) – if True, model computes valuation args['frac_post_process'] (float) – represents the fraction of the species remaining after processing of the whole carcass is complete. This will exist only if valuation is desired for the particular species. (Required if args[‘val_cont’] is True) args['unit_price'] (float) – represents the price for a single unit of harvest. Exists only if valuation is desired. (Required if args[‘val_cont’] is True)

Example Args:

args = {
    'workspace_dir': 'path/to/workspace_dir/',
    'results_suffix': 'scenario_name',
    'aoi_uri': 'path/to/aoi_uri',
    'total_timesteps': 100,
    'population_type': 'Stage-Based',
    'sexsp': 'Yes',
    'harvest_units': 'Individuals',
    'do_batch': False,
    'population_csv_uri': 'path/to/csv_uri',
    'population_csv_dir': '',
    'spawn_units': 'Weight',
    'total_init_recruits': 100000.0,
    'recruitment_type': 'Ricker',
    'alpha': 32.4,
    'beta': 54.2,
    'total_recur_recruits': 92.1,
    'migr_cont': True,
    'migration_dir': 'path/to/mig_dir/',
    'val_cont': True,
    'frac_post_process': 0.5,
    'unit_price': 5.0,
}

Creating a User-Defined Recruitment Function

An optional argument has been created in the Fisheries Model to allow users proficient in Python to pass their own recruitment function into the program via the args dictionary.

Using the Beverton-Holt recruitment function as an example, here’s how a user might create and pass in their own recruitment function:

import natcap.invest
import numpy as np

# define input data
Matu = np.array([...])  # the Maturity vector in the Population Parameters File
Weight = np.array([...])  # the Weight vector in the Population Parameters File
LarvDisp = np.array([...])  # the LarvalDispersal vector in the Population Parameters File
alpha = 2.0  # scalar value
beta = 10.0  # scalar value
sexsp = 2   # 1 = not sex-specific, 2 = sex-specific

# create recruitment function
def spawners(N_prev):
    return (N_prev * Matu * Weight).sum()

def rec_func_BH(N_prev):
    N_0 = (LarvDisp * ((alpha * spawners(
        N_prev) / (beta + spawners(N_prev)))) / sexsp)
    return (N_0, spawners(N_prev))

# fill out args dictionary
args = {}
# ... define other arguments ...
args['recruitment_type'] = 'Other'  # lets program know to use user-defined function
args['recruitment_func'] = rec_func_BH  # pass recruitment function as 'anonymous' Python function

# run model
natcap.invest.fisheries.fisheries.execute(args)

Conditions that a new recruitment function must meet to run properly:

• The function must accept as an argument: a single numpy three-dimensional array (N_prev) representing the state of the population at the previous time step. N_prev has three dimensions: the indices of the first dimension correspond to the region (must be in same order as provided in the Population Parameters File), the indices of the second dimension represent the sex if it is specific (i.e. two indices representing female, then male if the model is ‘sex-specific’, else just a single zero index representing the female and male populations aggregated together), and the indicies of the third dimension represent age/stage in ascending order.
• The function must return: a tuple of two values. The first value (N_0) being a single numpy one-dimensional array representing the youngest age of the population for the next time step. The indices of the array correspond to the regions of the population (outputted in same order as provided). If the model is sex-specific, it is currently assumed that males and females are produced in equal number and that the returned array has been already been divided by 2 in the recruitment function. The second value (spawners) is the number or weight of the spawners created by the population from the previous time step, provided as a scalar float value (non-negative).

Example of How Recruitment Function Operates within Fisheries Model:

# input data
N_prev_xsa = [[[region0-female-age0, region0-female-age1],
               [region0-male-age0, region1-male-age1]],
              [[region1-female-age0, region1-female-age1],
               [region1-male-age0], [region1-male-age1]]]

# execute function
N_0_x, spawners = rec_func(N_prev_xsa)

# output data - where N_0 contains information about the youngest
#     age/stage of the population for the next time step:
N_0_x = [region0-age0, region1-age0] # if sex-specific, rec_func should divide by two before returning
type(spawners) is float

Fisheries: Habitat Scenario Tool¶

natcap.invest.fisheries.fisheries_hst.execute(args)¶

Fisheries: Habitat Scenario Tool.

The Fisheries Habitat Scenario Tool generates a new Population Parameters CSV File with modified survival attributes across classes and regions based on habitat area changes and class-level dependencies on those habitats.

param str args[‘workspace_dir’]:
	location into which the resultant modified Population Parameters CSV file should be placed.
param str args[‘sexsp’]:
	specifies whether or not the age and stage classes are distinguished by sex. Options: ‘Yes’ or ‘No’
param str args[‘population_csv_uri’]:
	location of the population parameters csv file. This file contains all age and stage specific parameters.
param str args[‘habitat_chg_csv_uri’]:
	location of the habitat change parameters csv file. This file contains habitat area change information.
param str args[‘habitat_dep_csv_uri’]:
	location of the habitat dependency parameters csv file. This file contains habitat-class dependency information.
param float args[‘gamma’]:
	describes the relationship between a change in habitat area and a change in survival of life stages dependent on that habitat

Returns:

None

Example Args:

args = {
    'workspace_dir': 'path/to/workspace_dir/',
    'sexsp': 'Yes',
    'population_csv_uri': 'path/to/csv',
    'habitat_chg_csv_uri': 'path/to/csv',
    'habitat_dep_csv_uri': 'path/to/csv',
    'gamma': 0.5,
}

Note:

• Modified Population Parameters CSV File saved to ‘workspace_dir/output/’

System Message: WARNING/2 (/home/docs/checkouts/readthedocs.org/user_builds/invest/envs/3.3.1/local/lib/python2.7/site-packages/natcap/invest/fisheries/fisheries_hst.py:docstring of natcap.invest.fisheries.fisheries_hst.execute, line 47)

Block quote ends without a blank line; unexpected unindent.

‘’‘

# Parse, Verify Inputs vars_dict = io.fetch_args(args)

# Convert Data vars_dict = convert_survival_matrix(vars_dict)

# Generate Modified Population Parameters CSV File io.save_population_csv(vars_dict)

def convert_survival_matrix(vars_dict):

‘’’ Creates a new survival matrix based on the information provided by the user related to habitat area changes and class-level dependencies on those habitats.

Args:

vars_dict (dictionary): see fisheries_preprocessor_io.fetch_args for

example

Returns:

vars_dict (dictionary): modified vars_dict with new Survival matrix

accessible using the key ‘Surv_nat_xsa_mod’ with element values that exist between [0,1]

Example Returns:

ret = {
    # Other Variables...

    'Surv_nat_xsa_mod': np.ndarray([...])
}

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 uri 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_uri'] (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_uri'] (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_uri'] 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_uri'] (string) – path to a integer landcover code raster args['pools_to_calculate'] (string) – one of “all” or “above_ground”. 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. If “above_ground”, this is only done with ‘c_above’. 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_shape_uri'] (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.

Returns:

None

GLOBIO¶

natcap.invest.globio.execute(args)¶

GLOBIO.

The model operates in two modes. Mode (a) generates a landcover map based on a base landcover map and information about crop yields, infrastructure, and more. Mode (b) assumes the globio landcover map is generated. These modes are used below to describe input parameters.

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 any output files args['lulc_uri'] (string) – used in “mode (a)” path to a base landcover map with integer codes args['lulc_to_globio_table_uri'] (string) – used in “mode (a)” path to table that translates the land-cover args[‘lulc_uri’] to intermediate GLOBIO classes, from which they will be further differentiated using the additional data in the model. Contains at least the following fields: ‘lucode’: Land use and land cover class code of the dataset used. LULC codes match the ‘values’ column in the LULC raster of mode (b) and must be numeric and unique. ‘globio_lucode’: The LULC code corresponding to the GLOBIO class to which it should be converted, using intermediate codes described in the example below. args['infrastructure_dir'] (string) – used in “mode (a) and (b)” a path to a folder containing maps of either gdal compatible rasters or OGR compatible shapefiles. These data will be used in the infrastructure to calculation of MSA. args['pasture_uri'] (string) – used in “mode (a)” path to pasture raster args['potential_vegetation_uri'] (string) – used in “mode (a)” path to potential vegetation raster args['pasture_threshold'] (float) – used in “mode (a)” args['intensification_fraction'] (float) – used in “mode (a)”; a value between 0 and 1 denoting proportion of total agriculture that should be classified as ‘high input’ args['primary_threshold'] (float) – used in “mode (a)” args['msa_parameters_uri'] (string) – path to MSA classification parameters args['aoi_uri'] (string) – (optional) if it exists then final MSA raster is summarized by AOI args['globio_lulc_uri'] (string) – used in “mode (b)” path to predefined globio raster.

Returns:

None

Habitat Quality¶

natcap.invest.habitat_quality.habitat_quality.execute(args)¶

Habitat Quality.

Open files necessary for the portion of the habitat_quality model.

Parameters:

workspace_dir (string) – a uri to the directory that will write output and other temporary files during calculation (required) landuse_cur_uri (string) – a uri to an input land use/land cover raster (required) landuse_fut_uri (string) – a uri to an input land use/land cover raster (optional) landuse_bas_uri (string) – a uri to an input land use/land cover raster (optional, but required for rarity calculations) threat_folder (string) – a uri to the directory that will contain all threat rasters (required) threats_uri (string) – a uri 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: ‘THREAT’,’MAX_DIST’,’WEIGHT’ (required). access_uri (string) – a uri to an input polygon shapefile containing data on the relative protection against threats (optional) sensitivity_uri (string) – a uri to an input CSV file of LULC types, whether they are considered habitat, and their sensitivity to each threat (required) half_saturation_constant (float) – a python float that determines the spread and central tendency of habitat quality scores (required) suffix (string) – a python string that will be inserted into all raster uri paths just before the file extension.

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir',
    'landuse_cur_uri': 'path/to/landuse_cur_raster',
    'landuse_fut_uri': 'path/to/landuse_fut_raster',
    'landuse_bas_uri': 'path/to/landuse_bas_raster',
    'threat_raster_folder': 'path/to/threat_rasters/',
    'threats_uri': 'path/to/threats_csv',
    'access_uri': 'path/to/access_shapefile',
    'sensitivity_uri': 'path/to/sensitivity_csv',
    'half_saturation_constant': 0.5,
    'suffix': '_results',
}

Returns:	none

Habitat Risk Assessment¶

natcap.invest.habitat_risk_assessment.hra.execute(args)¶

Habitat Risk Assessment.

This function will prepare files passed from the UI to be sent on to the hra_core module.

All inputs are required.

Parameters:

workspace_dir (string) – The location of the directory into which intermediate and output files should be placed. csv_uri (string) – The location of the directory containing the CSV files of habitat, stressor, and overlap ratings. Will also contain a .txt JSON file that has directory locations (potentially) for habitats, species, stressors, and criteria. grid_size (int) – Represents the desired pixel dimensions of both intermediate and ouput rasters. risk_eq (string) – 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’. decay_eq (string) – A string identifying the equation that should be used in calculating the decay of stressor buffer influence. This can be ‘None’, ‘Linear’, or ‘Exponential’. max_rating (int) – An int representing the highest potential value that should be represented in rating, data quality, or weight in the CSV table. max_stress (int) – This is the highest score that is used to rate a criteria within this model run. These values would be placed within the Rating column of the habitat, species, and stressor CSVs. aoi_tables (string) – A shapefile containing one or more planning regions for a given model. This will be used to get the average risk value over a larger area. Each potential region MUST contain the attribute “name” as a way of identifying each individual shape.

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir',
    'csv_uri': 'path/to/csv',
    'grid_size': 200,
    'risk_eq': 'Euclidean',
    'decay_eq': 'None',
    'max_rating': 3,
    'max_stress': 4,
    'aoi_tables': 'path/to/shapefile',
}

Returns:	None

Habitat Risk Assessment Preprocessor¶

natcap.invest.habitat_risk_assessment.hra_preprocessor.execute(args)¶

Habitat Risk Assessment Preprocessor.

Want to read in multiple hab/stressors directories, in addition to named criteria, and make an appropriate csv file.

Parameters:

args['workspace_dir'] (string) – The directory to dump the output CSV files to. (required) args['habitats_dir'] (string) – A directory of shapefiles that are habitats. This is not required, and may not exist if there is a species layer directory. (optional) args['species_dir'] (string) – Directory which holds all species shapefiles, but may or may not exist if there is a habitats layer directory. (optional) args['stressors_dir'] (string) – A directory of ArcGIS shapefiles that are stressors. (required) args['exposure_crits'] (list) – list containing string names of exposure criteria (hab-stress) which should be applied to the exposure score. (optional) args['sensitivity-crits'] (list) – List containing string names of sensitivity (habitat-stressor overlap specific) criteria which should be applied to the consequence score. (optional) args['resilience_crits'] (list) – List containing string names of resilience (habitat or species-specific) criteria which should be applied to the consequence score. (optional) args['criteria_dir'] (string) – Directory which holds the criteria shapefiles. May not exist if the user does not desire criteria shapefiles. This needs to be in a VERY specific format, which shall be described in the user’s guide. (optional)

Returns:

None

This function creates a series of CSVs within args['workspace_dir']. There will be one CSV for every habitat/species. These files will contain information relevant to each habitat or species, including all criteria. The criteria will be broken up into those which apply to only the habitat, and those which apply to the overlap of that habitat, and each stressor.

JSON file containing vars that need to be passed on to hra non-core when that gets run. Should live inside the preprocessor folder which will be created in args['workspace_dir']. It will contain habitats_dir, species_dir, stressors_dir, and criteria_dir.

Habitat Suitability¶

natcap.invest.habitat_suitability.execute(args)¶

Habitat Suitability.

Calculate habitat suitability indexes given biophysical parameters.

The objective of a habitat suitability index (HSI) is to help users identify areas within their AOI that would be most suitable for habitat restoration. The output is a gridded map of the user’s AOI in which each grid cell is assigned a suitability rank between 0 (not suitable) and 1 (most suitable). The suitability rank is generally calculated as the weighted geometric mean of several individual input criteria, which have also been ranked by suitability from 0-1. Habitat types (e.g. marsh, mangrove, coral, etc.) are treated separately, and each habitat type will have a unique set of relevant input criteria and a resultant habitat suitability map.

Parameters:

args['workspace_dir'] (string) – directory path to workspace directory for output files. args['results_suffix'] (string) – (optional) string to append to any output file names. args['aoi_path'] (string) – file path to an area of interest shapefile. args['exclusion_path_list'] (list) – (optional) a list of file paths to shapefiles which define areas which the HSI should be masked out in a final output. args['output_cell_size'] (float) – (optional) size of output cells. If not present, the output size will snap to the smallest cell size in the HSI range rasters. args['habitat_threshold'] (float) – a value to threshold the habitat score values to 0 and 1. args['hsi_ranges'] (dict) – a dictionary that describes the habitat biophysical base rasters as well as the ranges for optimal and tolerable values. Each biophysical value has a unique key in the dictionary that is used to name the mapping of biophysical to local HSI value. Each value is dictionary with keys: ‘raster_path’: path to disk for biophysical raster. ‘range’: a 4-tuple in non-decreasing order describing the “tolerable” to “optimal” ranges for those biophysical values. The endpoints non-inclusively define where the suitability score is 0.0, the two midpoints inclusively define the range where the suitability is 1.0, and the ranges above and below are linearly interpolated between 0.0 and 1.0. Example: { 'depth': { 'raster_path': r'C:/path/to/depth.tif', 'range': (-50, -30, -10, -10), }, 'temperature': { 'temperature_path': ( r'C:/path/to/temperature.tif'), 'range': (5, 7, 12.5, 16), } }

Returns:

None

Managed Timber Production¶

natcap.invest.timber.timber.execute(args)¶

Managed Timber Production.

Invoke the timber model given uri inputs specified by the user guide.

Parameters:

args['workspace_dir'] (string) – The file location where the outputs will be written (Required) args['results_suffix'] (string) – a string to append to any output file name (optional) args['timber_shape_uri'] (string) – The shapefile describing timber parcels with fields as described in the user guide (Required) args['attr_table_uri'] (string) – The CSV attribute table location with fields that describe polygons in timber_shape_uri (Required) market_disc_rate (float) – The market discount rate

Returns:

nothing

Marine Water Quality¶

natcap.invest.marine_water_quality.marine_water_quality_biophysical.execute(args)¶

Marine Water Quality.

Main entry point for the InVEST 3.0 marine water quality biophysical model.

Parameters:

args['workspace_dir'] (string) – Directory to place outputs args['results_suffix'] (string) – a string to append to any output file name (optional) args['aoi_poly_uri'] (string) – OGR polygon Datasource indicating region of interest to run the model. Will define the grid. args['land_poly_uri'] (string) – OGR polygon DataSource indicating areas where land is. args['pixel_size'] (float) – float indicating pixel size in meters of output grid. args['layer_depth'] (float) – float indicating the depth of the grid cells in meters. args['source_points_uri'] (string) – OGR point Datasource indicating point sources of pollution. args['source_point_data_uri'] (string) – csv file indicating the biophysical properties of the point sources. args['kps'] (float) – float indicating decay rate of pollutant (kg/day) args['tide_e_points_uri'] (string) – OGR point Datasource with spatial information about the E parameter args['adv_uv_points_uri'] (string) – optional OGR point Datasource with spatial advection u and v vectors.

Returns:

nothing

Nutrient Delivery Ratio¶

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

Nutrient Delivery Ratio.

Parameters:

args['workspace_dir'] (string) – path to current workspace args['dem_uri'] (string) – path to digital elevation map raster args['lulc_uri'] (string) – a path to landcover map raster args['runoff_proxy_uri'] (string) – a path to a runoff proxy raster args['watersheds_uri'] (string) – path to the watershed shapefile args['biophysical_table_uri'] (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, phosphorous 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 upstream pixels. args['_prepare'] – (optional) The preprocessed set of data created by the ndr._prepare call. This argument could be used in cases where the call to this function is scripted and can save a significant amount DEM processing runtime.

Returns:

None

Overlap Analysis¶

natcap.invest.overlap_analysis.overlap_analysis.execute(args)¶

Overlap Analysis.

This function will take care of preparing files passed into the overlap analysis model. It will handle all files/inputs associated with calculations and manipulations. It may write log, warning, or error messages to stdout.

Parameters:

args – A python dictionary created by the UI and passed to this method. It will contain the following data. args['workspace_dir'] (string) – The directory in which to place all resulting files, will come in as a string. (required) args['zone_layer_uri'] (string) – A URI pointing to a shapefile with the analysis zones on it. (required) args['grid_size'] (int) – This is an int specifying how large the gridded squares over the shapefile should be. (required) args['overlap_data_dir_uri'] (string) – URI pointing to a directory where multiple shapefiles are located. Each shapefile represents an activity of interest for the model. (required) args['do-inter'] (bool) – Boolean that indicates whether or not inter-activity weighting is desired. This will decide if the overlap table will be created. (required) args['do_intra'] (bool) – Boolean which indicates whether or not intra-activity weighting is desired. This will will pull attributes from shapefiles passed in in ‘zone_layer_uri’. (required) args['do_hubs'] (bool) – Boolean which indicates if human use hubs are desired. (required) args['overlap_layer_tbl'] (string) – URI to a CSV file that holds relational data and identifier data for all layers being passed in within the overlap analysis directory. (optional) args['intra_name'] (string) – string which corresponds to a field within the layers being passed in within overlap analysis directory. This is the intra-activity importance for each activity. (optional) args['hubs_uri'] (string) – The location of the shapefile containing points for human use hub calculations. (optional) args['decay_amt'] (float) – A double representing the decay rate of value from the human use hubs. (optional)

Returns:

None

Overlap Analysis: Management Zones¶

natcap.invest.overlap_analysis.overlap_analysis_mz.execute(args)¶

Overlap Analysis: Management Zones.

Parameters:

args – A python dictionary created by the UI and passed to this method. It will contain the following data. args['workspace_dir'] (string) – The directory in which to place all resulting files, will come in as a string. (required) args['zone_layer_loc'] (string) – A URI pointing to a shapefile with the analysis zones on it. (required) args['overlap_data_dir_loc'] (string) – URI pointing to a directory where multiple shapefiles are located. Each shapefile represents an activity of interest for the model. (required)

Returns:

None

Pollinator Abundance: Crop Pollination¶

natcap.invest.pollination.pollination.execute(args)¶

Pollinator Abundance: Crop Pollination.

Execute the pollination model from the topmost, user-accessible level.

Parameters:

workspace_dir (string) – a URI to the workspace folder. Not required to exist on disk. Additional folders will be created inside of this folder. If there are any file name collisions, this model will overwrite those files. landuse_cur_uri (string) – a URI to a GDAL raster on disk. ‘do_valuation’ - A boolean. Indicates whether valuation should be performed. This applies to all scenarios. landuse_attributes_uri (string) – a URI to a CSV on disk. See the model’s documentation for details on the structure of this table. landuse_fut_uri (string) – (Optional) a URI to a GDAL dataset on disk. If this args dictionary entry is provided, this model will process both the current and future scenarios. do_valuation (boolean) – Indicates whether the model should include valuation half_saturation (float) – a number between 0 and 1 indicating the half-saturation constant. See the pollination documentation for more information. wild_pollination_proportion (float) – a number between 0 and 1 indicating the proportion of all pollinators that are wild. See the pollination documentation for more information. guilds_uri (string) – a URI to a CSV on disk. See the model’s documentation for details on the structure of this table. ag_classes (string) – (Optional) a space-separated list of land cover classes that are to be considered as agricultural. If this input is not provided, all land cover classes are considered to be agricultural. farms_shapefile (string) – (Optional) shapefile containing points representing data collection points on the landscape. results_suffix (string) – inserted into the URI of each file created by this model, right before the file extension.

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir',
    'landuse_cur_uri': 'path/to/raster',
    'landuse_attributes_uri': 'path/to/csv',
    'landuse_fut_uri': 'path/to/raster',
    'do_valuation': 'example',
    'half_saturation': 'example',
    'wild_pollination_proportion': 'example',
    'guilds_uri': 'path/to/csv',
    'ag_classes': 'example',
    'farms_shapefile': 'example',
    'results_suffix': 'example',

}

The following args dictionary entries are optional, and will affect the behavior of the model if provided:

1. landuse_fut_uri
2. ag_classes
3. results_suffix
4. farms_shapefile

If args[‘do_valuation’] is set to True, the following args dictionary entries are also required:

1. half_saturation
2. wild_pollination_proportion

This function has no return value, though it does save a number of rasters to disk. See the user’s guide for details.

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

RouteDEM: D-Infinity Routing¶

natcap.invest.routing.routedem.execute(args)¶

RouteDEM: D-Infinity Routing.

This model exposes the pygeoprocessing d-infinity routing functionality in the InVEST model API.

Parameters:

workspace_dir (string) – The selected folder is used as the workspace where 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) dem_uri (string) – A GDAL-supported raster file containing a base Digital Elevation Model to execute the routing functionality across. (required) pit_filled_filename (string) – The filename of the output raster with pits filled in. It will go in the project workspace. (required) flow_direction_filename (string) – The filename of the flow direction raster. It will go in the project workspace. (required) flow_accumulation_filename (string) – The filename of the flow accumulation raster. It will go in the project workspace. (required) threshold_flow_accumulation (int) – The number of upstream cells that must flow into a cell before it’s classified as a stream. (required) multiple_stream_thresholds (bool) – Set to True to calculate multiple maps. If enabled, set stream threshold to the lowest amount, then set upper and step size thresholds. (optional) threshold_flow_accumulation_upper (int) – The number of upstream pixels that must flow into a cell before it’s classified as a stream. (required) threshold_flow_accumulation_stepsize (int) – The number of cells to step up from lower to upper threshold range. (required) calculate_slope (bool) – Set to True to output a slope raster. (optional) slope_filename (string) – The filename of the output slope raster. This will go in the project workspace. (required) calculate_downstream_distance (bool) – Select to calculate a distance stream raster, based on uppper threshold limit. (optional) downstream_distance_filename (string) – The filename of the output raster. It will go in the project workspace. (required)

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_uri'] (string) – path to the base landcover map args['replacment_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_uri’]. args['n_fragmentation_steps'] (string) – an int as a string indicating the number of steps to take for the fragmentation conversion args['aoi_uri'] (string) – (optional) path to a shapefile that indicates an 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}.

Returns:

None.

Scenario Generator: Rule-Based¶

natcap.invest.scenario_generator.scenario_generator.execute(args)¶

Scenario Generator: Rule-Based.

Model entry-point.

Parameters:

workspace_dir (str) – path to workspace directory suffix (str) – string to append to output files landcover (str) – path to land-cover raster transition (str) – path to land-cover attributes table calculate_priorities (bool) – whether to calculate priorities priorities_csv_uri (str) – path to priority csv table calculate_proximity (bool) – whether to calculate proximity proximity_weight (float) – weight given to proximity calculate_transition (bool) – whether to specifiy transitions calculate_factors (bool) – whether to use suitability factors suitability_folder (str) – path to suitability folder suitability (str) – path to suitability factors table weight (float) – suitability factor weight factor_inclusion (int) – the rasterization method – all touched or center points factors_field_container (bool) – whether to use suitability factor inputs calculate_constraints (bool) – whether to use constraint inputs constraints (str) – filepath to constraints shapefile layer constraints_field (str) – shapefile field containing constraints field override_layer (bool) – whether to use override layer override (str) – path to override shapefile override_field (str) – shapefile field containing override value override_inclusion (int) – the rasterization method

Example Args:

args = {
    'workspace_dir': 'path/to/dir',
    'suffix': '',
    'landcover': 'path/to/raster',
    'transition': 'path/to/csv',
    'calculate_priorities': True,
    'priorities_csv_uri': 'path/to/csv',
    'calculate_proximity': True,
    'calculate_transition': True,
    'calculate_factors': True,
    'suitability_folder': 'path/to/dir',
    'suitability': 'path/to/csv',
    'weight': 0.5,
    'factor_inclusion': 0,
    'factors_field_container': True,
    'calculate_constraints': True,
    'constraints': 'path/to/shapefile',
    'constraints_field': '',
    'override_layer': True,
    'override': 'path/to/shapefile',
    'override_field': '',
    'override_inclusion': 0
}

Added Afterwards:

d = {
    'proximity_weight': 0.3,
    'distance_field': '',
    'transition_id': 'ID',
    'percent_field': 'Percent Change',
    'area_field': 'Area Change',
    'priority_field': 'Priority',
    'proximity_field': 'Proximity',
    'suitability_id': '',
    'suitability_layer': '',
    'suitability_field': '',
}

Scenic Quality¶

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

Scenic Quality.

Warning

The Scenic Quality model is under active development and is currently unstable.

Parameters:

workspace_dir (string) – The selected folder is used as the workspace where 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) aoi_uri (string) – An OGR-supported vector file. This AOI instructs the model where to clip the input data and the extent of analysis. Users will create a polygon feature layer that defines their area of interest. The AOI must intersect the Digital Elevation Model (DEM). (required) cell_size (float) – Length (in meters) of each side of the (square) cell. (optional) structure_uri (string) – An OGR-supported vector file. The user must specify a point feature layer that indicates locations of objects that contribute to negative scenic quality, such as aquaculture netpens or wave energy facilities. In order for the viewshed analysis to run correctly, the projection of this input must be consistent with the project of the DEM input. (required) dem_uri (string) – A GDAL-supported raster file. An elevation raster layer is required to conduct viewshed analysis. Elevation data allows the model to determine areas within the AOI’s land-seascape where point features contributing to negative scenic quality are visible. (required) refraction (float) – The earth curvature correction option corrects for the curvature of the earth and refraction of visible light in air. Changes in air density curve the light downward causing an observer to see further and the earth to appear less curved. While the magnitude of this effect varies with atmospheric conditions, a standard rule of thumb is that refraction of visible light reduces the apparent curvature of the earth by one-seventh. By default, this model corrects for the curvature of the earth and sets the refractivity coefficient to 0.13. (required) pop_uri (string) – A GDAL-supported raster file. A population raster layer is required to determine population within the AOI’s land-seascape where point features contributing to negative scenic quality are visible and not visible. (optional) overlap_uri (string) – An OGR-supported vector file. The user has the option of providing a polygon feature layer where they would like to determine the impact of objects on visual quality. This input must be a polygon and projected in meters. The model will use this layer to determine what percent of the total area of each polygon feature can see at least one of the point features impacting scenic quality.optional valuation_function (string) – Either ‘polynomial’ or ‘logarithmic’. This field indicates the functional form f(x) the model will use to value the visual impact for each viewpoint. For distances less than 1 km (x<1), the model uses a linear form g(x) where the line passes through f(1) (i.e. g(1) == f(1)) and extends to zero with the same slope as f(1) (i.e. g’(x) == f’(1)). (optional) a_coefficient (float) – First coefficient used either by the polynomial or by the logarithmic valuation function. (required) b_coefficient (float) – Second coefficient used either by the polynomial or by the logarithmic valuation function. (required) c_coefficient (float) – Third coefficient for the polynomial’s quadratic term. (required) d_coefficient (float) – Fourth coefficient for the polynomial’s cubic exponent. (required) max_valuation_radius (float) – Radius beyond which the valuation is set to zero. The valuation function ‘f’ cannot be negative at the radius ‘r’ (f(r)>=0). (required)

Returns:

None

Seasonal Water Yield¶

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

Seasonal Water Yield.

This function invokes the InVEST seasonal water yield model described in “Spatial attribution of baseflow generation at the parcel level for ecosystem-service valuation”, Guswa, et. al (under review in “Water Resources Research”)

Parameters:

args['workspace_dir'] (string) – output directory for intermediate, and final files (temporary,) – 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 upstream 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: 1: A 2: B 3: C 4: D 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.

Returns:

None

Sediment Delivery Ratio¶

natcap.invest.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 upstream 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

Returns:

None.

Wave Energy¶

natcap.invest.wave_energy.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 (string) – Where the intermediate and output folder/files will be saved. (required) wave_base_data_uri (string) – Directory location of wave base data including WW3 data and analysis area shapefile. (required) analysis_area_uri (string) – 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_uri (string) – A polygon shapefile outlining a more detailed area within the analysis area. This shapefile should be projected with linear units being in meters. (required to run Valuation model) machine_perf_uri (string) – The path of a CSV file that holds the machine performance table. (required) machine_param_uri (string) – The path of a CSV file that holds the machine parameter table. (required) dem_uri (string) – The path of the Global Digital Elevation Model (DEM). (required) suffix (string) – A python string of characters to append to each output filename (optional) valuation_container (boolean) – Indicates whether the model includes valuation land_gridPts_uri (string) – A CSV file path containing the Landing and Power Grid Connection Points table. (required for Valuation) machine_econ_uri (string) – 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)

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir',
    'wave_base_data_uri': 'path/to/base_data_dir',
    'analysis_area_uri': 'West Coast of North America and Hawaii',
    'aoi_uri': 'path/to/shapefile',
    'machine_perf_uri': 'path/to/csv',
    'machine_param_uri': 'path/to/csv',
    'dem_uri': 'path/to/raster',
    'suffix': '_results',
    'valuation_container': True,
    'land_gridPts_uri': 'path/to/csv',
    'machine_econ_uri': 'path/to/csv',
    'number_of_machines': 28,
}

Wind Energy¶

natcap.invest.wind_energy.wind_energy.execute(args)¶

Wind Energy.

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

Parameters:

workspace_dir (string) – a python string which is the uri path to where the outputs will be saved (required) wind_data_uri (string) – 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_uri (string) – a uri to an OGR datasource that is of type polygon and 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_uri (string) – a uri to a GDAL dataset that has the depth values of the area of interest (required) land_polygon_uri (string) – a uri to an OGR datasource of type polygon 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_uri (string) – 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) suffix (string) – a String to append to the end of the output files (optional) turbine_parameters_uri (string) – a uri 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_uri (string) – a uri 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 (string) – a URI 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)

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir',
    'wind_data_uri': 'path/to/file',
    'aoi_uri': 'path/to/shapefile',
    'bathymetry_uri': 'path/to/raster',
    'land_polygon_uri': 'path/to/shapefile',
    'global_wind_parameters_uri': 'path/to/csv',
    'suffix': '_results',
    'turbine_parameters_uri': 'path/to/csv',
    'number_of_turbines': 10,
    'min_depth': 3,
    'max_depth': 60,
    'min_distance': 0,
    'max_distance': 200000,
    'valuation_container': True,
    'foundation_cost': 3.4,
    'discount_rate': 7.0,
    'grid_points_uri': 'path/to/csv',
    'avg_grid_distance': 4,
    'price_table': True,
    'wind_schedule': 'path/to/csv',
    'wind_price': 0.4,
    'rate_change': 0.0,

}

Returns:	None