InVEST (Integrated Valuation of Ecosystem Services and Tradeoffs)

In recent versions of the Wind Energy model, rasterized outputs have been removed to prevent invalid data interpolation in areas outside the input wind data coverage.

Instead of looking for .tif files, users should retrieve all model results—including power density, harvested energy, and valuation data—from the wind_energy_points.shp vector file. Each point in this shapefile corresponds to a row in the input Wind Data Points CSV and contains the summarized values for that specific geographic coordinate.

### Expected Output Mapping

| Previous Raster Output | New Location in `wind_energy_points.shp` |
| :--- | :--- |
| `density_W_per_m2.tif` | Point attribute |
| `harvested_energy_MWhr_per_yr.tif` | Point attribute |
| `carbon_emissions_tons.tif` (Valuation) | Point attribute |
| `levelized_cost_price_per_kWh.tif` (Valuation) | Point attribute |
| `npv.tif` (Valuation) | Point attribute |

InVEST supports plugins at both the Python library level and the Workbench UI level.

Python Level

When natcap.invest is imported, it automatically searches for installed Python packages that follow the plugin pattern. A package is identified as a plugin if:

1. Its package name begins with invest.
2. It contains the required attributes (such as MODEL_SPEC) described in the plugin developer's guide.

Once identified, these plugins are recorded in natcap.invest.models and are accessible via natcap.invest just like core models.

Workbench Level

In the InVEST Workbench, plugins are installed via the "Manage Plugins" window. Users can provide a Git URL or a local path. The installation process follows these steps:

1. Download pyproject.toml (if using a Git URL).
2. Parse metadata from pyproject.toml.
3. Create a micromamba environment containing python, git, and dependencies specified in tool.natcap.invest.conda_dependencies within the pyproject.toml.
4. Install the plugin into that environment using pip.
5. Import the plugin and access metadata from MODEL_SPEC.
6. Save the plugin information to the workbench settings store.

Note on Versioning: The Workbench identifies plugins using a hash of the model_id (from MODEL_SPEC) and the package.version (from pyproject.toml). This allows multiple versions of the same plugin to be installed simultaneously. However, at the Python level, only one plugin with the same package name can be active at a time.

InVEST containers can be referenced using different types of tags. For scientific reproducibility, it is strongly recommended to use a SHA256 digest rather than a moving tag like latest.

Available referencing methods:

1. SHA256 Digest (Recommended for reproducibility): Refers to a specific, immutable version of the container.
   • Example: ghcr.io/natcap/invest@sha256:8a4a3c621c09e1df74821efa0eb8e2cd90ea6e228e393e953cb4ea0ff8d37454
2. InVEST Version Tag: Refers to a specific InVEST release.
   • Example: ghcr.io/natcap/invest:3.16.2
3. Git Commit SHA256: Refers to the specific git revision of the natcap/invest repository used to build the container.
   • Example: ghcr.io/natcap/invest:e756a7a43d598f2130199bf1c9ad4d2df4975cfd
4. latest Tag: Points to the most recent build. Do not use this for reproducible analyses.
   • Example: ghcr.io/natcap/invest:latest

InVEST Python scripts consist of two primary components:

1. The argument dictionary (args): A dictionary where keys represent the model's input parameters (matching the UI labels) and values represent the input data or settings.
2. The model execution call: A call to the model's execute function, which takes the args dictionary as its single parameter.

API Pattern: Every InVEST model follows a consistent syntax: [module_name].execute(args). For example, the Nutrient Delivery Ratio (NDR) model is invoked via natcap.invest.ndr.ndr.execute(args).

Output Registry: As of version 3.17.0, the execute function returns a dictionary summarizing all produced output files. This dictionary maps output IDs (defined in the model's MODEL_SPEC) to their absolute file paths, allowing for programmatic access to results.

import natcap.invest.ndr.ndr

args = {
    'biophysical_table_path': 'path/to/table.csv',
    'dem_path': 'path/to/dem.tif',
    # ... other parameters
}

if __name__ == '__main__':
    # execute returns a dictionary of output paths
    outputs = natcap.invest.ndr.ndr.execute(args)