Integrated Valuation of Ecosystem Services and Tradeoffs

A family of tools for quantifying the values of natural capital in clear, credible, and practical ways.
https://github.com/natcap/invest

Category: Sustainable Development
Sub Category: Sustainable Investment

Keywords

ecosystem-services geospatial gis

Keywords from Contributors

climate-model simulator measure tensor feature-toggle feature-flag sequencer unit-testing featured training

Last synced: about 13 hours ago
JSON representation

Repository metadata

InVEST®: models that map and value the goods and services from nature that sustain and fulfill human life.

• Host: GitHub
• URL: https://github.com/natcap/invest
• Owner: natcap
• License: apache-2.0
• Created: 2020-01-29T22:22:07.000Z (about 5 years ago)
• Default Branch: main
• Last Pushed: 2025-04-22T22:03:23.000Z (4 days ago)
• Last Synced: 2025-04-25T13:05:56.636Z (1 day ago)
• Topics: ecosystem-services, geospatial, gis
• Language: Python
• Homepage:
• Size: 83.5 MB
• Stars: 186
• Watchers: 11
• Forks: 82
• Open Issues: 166
• Releases: 24
• Metadata Files:
  • Readme: README.rst
  • Changelog: HISTORY.rst
  • Contributing: CONTRIBUTING.md
  • License: LICENSE.txt

README.rst

          InVEST: 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.

.. note::
    **This repository is for InVEST 3.2.1 and later**

    This replaces our Google Code project formerly
    located at http://code.google.com/p/invest-natcap.  If you are looking to build
    InVEST <= 3.2.0, use the archived release-framework repository at
    https://bitbucket.org/natcap/invest-natcap.release-framework, and the InVEST repository
    at https://bitbucket.org/natcap/invest-natcap.invest-3.


General Information
-------------------

* Website: https://naturalcapitalproject.stanford.edu/software/invest
* Source code: https://github.com/natcap/invest
* Issue tracker: https://github.com/natcap/invest/issues
* Users' guide: https://storage.googleapis.com/releases.naturalcapitalproject.org/invest-userguide/latest/index.html
* API documentation: http://invest.readthedocs.io/en/latest/


Dependencies
------------

OS-specific installation instructions are found either online at
http://invest.readthedocs.io/en/latest/installing.html or locally at ``doc/api-docs/installing.rst``.

.. note::
    The ``make`` commands for InVEST require a BASH shell environment. Windows
    users can use Git Bash within the Git for Windows suite. More information
    can be found at https://gitforwindows.org

Managing python dependencies
++++++++++++++++++++++++++++
We recommend using a virtual environment to manage your python dependencies, and there is
a Makefile target to assist with this::

    $ make env
    $ source env/bin/activate

Or on Windows, use the following instead from a CMD prompt::

    > make env
    > .\env\bin\activate

This makefile target is included for convenience. It uses ``conda`` and installs packages from ``conda-forge``.
It also uses the `-p` flag with `conda create`, creating a `./env` folder containing the environment.

Using a different environment folder name
"""""""""""""""""""""""""""""""""""""""""
If you prefer a different path for your environment, you may pass the environment path as
a parameter to make::

    $ make ENV=myEnv env

You could then activate the environment created at ``./myEnv``.


Using a different environment management tool
"""""""""""""""""""""""""""""""""""""""""""""
You may of course choose to manage your own virtual environment without using the Makefile.

We suggest using ``conda`` or ``mamba`` and ``conda-forge``.

``requirements.txt``, ``requirements-dev.txt`` and ``requirements-docs.txt`` list the python
dependencies needed.

Installing ``natcap.invest`` from local source code
"""""""""""""""""""""""""""""""""""""""""""""""""""
From an activated virtual environment, it's safest to uninstall any existing installation
and then install `natcap.invest`::

    $ pip uninstall natcap.invest
    $ make install

In practice, it can be convenient to use an "editable install" instead to avoid needing
to uninstall & re-install after making changes to source code::

   $ pip install -e .

Note that with an editable install any changes to non-Python (Cython, C++) files will
require compilation using one of the above installation methods.

*The Workbench is not part of the* ``natcap.invest`` *Python package. See*
``workbench/readme.md`` *for developer details.*

A successful ``natcap.invest`` installation will include the InVEST CLI::

    $ invest list

Building InVEST Distributions
-----------------------------

Once the required tools and packages are available, we can build InVEST.
On Windows, you must indicate the location of the GDAL libraries with the environment
variable ``NATCAP_INVEST_GDAL_LIB_PATH``. If you are using conda to manage dependencies
as we recommend, you can add ``NATCAP_INVEST_GDAL_LIB_PATH="$CONDA_PREFIX/Library"`` to
the commands below. (On Mac and Linux, the gdal library path is determined for you
automatically using ``gdal-config``, which isn't available on Windows.)


Building ``natcap.invest`` python package
+++++++++++++++++++++++++++++++++++++++++

A Makefile target has been created for your convenience::

    $ make python_packages

This will create a wheel for your platform and a zip source archive in ``dist/``.
Both of these files (``dist/natcap.invest*.whl`` and ``dist/natcap.invest*.zip``)
can be installed by pip.

Building python packages without GNU make
"""""""""""""""""""""""""""""""""""""""""
Python distributions may be built with the standard distutils/setuptools commands::

    $ python -m pip install build
    $ python -m build --wheel
    $ python -m build --sdist

InVEST Standalone Binaries
++++++++++++++++++++++++++

Once the appropriate dependencies are available, InVEST can also be built as a
standalone application::

    $ make binaries

An important detail about building binaries is that ``natcap.invest`` must be
installed as a wheel to ensure that the distribution information is in the
correct location.

This will create a directory at ``dist/invest`` holding the application binaries
and relevant shared libraries.

Binaries cannot be cross-compiled for other operating systems.


InVEST Workbench
++++++++++++++++++++++++

See developer instructions at ``workbench/readme.md``.



Building InVEST Documentation
-----------------------------

User's Guide
++++++++++++

To build the user's guide::

    $ make userguide

This will build HTML and PDF documentation, writing them to ``dist/userguide``
and ``dist/InVEST_*_Documentation.pdf``, respectively.

The User's Guide is maintained in a separate git repository. InVEST will build
the User's Guide with the commit defined in the ``Makefile``::

   GIT_UG_REPO                 := https://github.com/natcap/invest.users-guide
   GIT_UG_REPO_PATH            := doc/users-guide
   GIT_UG_REPO_REV             := f203ec069f9f03560c9a85b268e67ebb6b994953


API Documentation
+++++++++++++++++

To build the ``natcap.invest`` python API documentation and developer's guide::

    $ make apidocs

This will build an HTML version of the API documentation, writing it to
``dist/apidocs``.


InVEST Sample Data
------------------

InVEST is typically distributed with sample data, though, in the interest of
disk space, these data are not included in any of the standard installers.  To
build zip archives of the sample data::

    $ make sampledata

This will write the data zipfiles to ``dist/data``. ``git`` command is needed.

Sample data is tracked in a ``git-lfs`` repo and will be packaged based on the commit
defined in the ``Makefile``::

   GIT_SAMPLE_DATA_REPO        := https://bitbucket.org/natcap/invest-sample-data.git
   GIT_SAMPLE_DATA_REPO_PATH   := $(DATA_DIR)/invest-sample-data
   GIT_SAMPLE_DATA_REPO_REV    := 0f8b41557753dad3670ba8220f41650b51435a93

Tests
-----

InVEST includes a battery of tests to ensure software quality.

Model tests
+++++++++++

To run tests on the suite of Ecosystem Service models in InVEST::

    $ make test

Tests depend on test data that is tracked in a ``git-lfs`` repo defined in the ``Makefile``::

   GIT_TEST_DATA_REPO          := https://bitbucket.org/natcap/invest-test-data.git
   GIT_TEST_DATA_REPO_PATH     := $(DATA_DIR)/invest-test-data
   GIT_TEST_DATA_REPO_REV      := 324abde73e1d770ad75921466ecafd1ec6297752

Test data (and Sample Data) can be retrieved using::

   $ make fetch


Changing how GNU make runs tests
++++++++++++++++++++++++++++++++

The InVEST Makefile setup depends on ``pytest`` and ``coverage`` to display
line coverage and produce HTML and XML reports.  You can force ``make`` to use
``coverage`` with a different test runner by setting a parameter at the
command line.  For example, to run the tests with ``nose``::

    $ make TESTRUNNER=nose test


Running tests on binaries
+++++++++++++++++++++++++++++++++++

This repository includes a python script to automatically
execute and check the exit status of all InVEST models, running on the
installed InVEST sample data. Once all sample data have been fetched
and binaries built on the target computer::

    $ make invest_autotest


Copyright and license information
---------------------------------

A file called ``LICENSE.txt`` should have accompanied this distribution.  If it
is missing, the license may be found on our project page,
https://github.com/natcap/invest

        

---

Owner metadata

• Name: The Natural Capital Project
• Login: natcap
• Email:
• Kind: organization
• Description: Pioneering science, technology, and partnerships that enable people and nature to thrive.
• Website: naturalcapitalproject.stanford.edu
• Location: United States
• Twitter: natcapproject
• Company:
• Icon url: https://avatars.githubusercontent.com/u/7783885?v=4
• Repositories: 59
• Last ynced at: 2024-01-28T19:30:43.006Z
• Profile URL: https://github.com/natcap

---

GitHub Events

Total

• Create event: 10
• Release event: 3
• Issues event: 194
• Watch event: 22
• Delete event: 7
• Issue comment event: 248
• Push event: 174
• Gollum event: 17
• Pull request review comment event: 372
• Pull request event: 268
• Pull request review event: 496
• Fork event: 14

Last Year

• Create event: 10
• Release event: 3
• Issues event: 194
• Watch event: 22
• Delete event: 7
• Issue comment event: 248
• Push event: 174
• Gollum event: 17
• Pull request review comment event: 372
• Pull request event: 268
• Pull request review event: 496
• Fork event: 14

---

Committers metadata

Last synced: 4 days ago

Name	Email	Commits
James Douglass	j****s@s****u	5027
davemfish	d****h@g****m	3029
emlys	e****h@s****u	2431
Rich Sharp	r****p@g****m	2052
Joanna Lin	c****4@g****m	875
Doug	d****4@g****m	736
Will Bierbower	w****w@s****u	244
dcdenu4	d****l@l****t	207
Emily Davis	e****s@s****u	156
Claire Simpson	c****n@s****u	109
Will Bierbower	w****r@g****m	66
Emily	e****y@E****l	33
Megan Nissel	m****l@g****m	16
GitHub Actions		15
omahs	7****s	2
Tom Saleeba	t****a@g****m	1
Will Bierbower	w****2@u****u	1
Rolf Simoes	r****s@o****g	1
newtpatrol	6****l	1

Committer domains:

• stanford.edu: 5
• opengeohub.org: 1
• umbc.edu: 1

---

Issue and Pull Request metadata

Last synced: 1 day ago

More stats: https://issues.ecosyste.ms/repositories/lookup?url=https://github.com/natcap/invest

---

---

---

Package metadata

• Total packages: 2
• Total downloads:
  • pypi: 4,601 last-month
• Total dependent packages: 2 (may contain duplicates)
• Total dependent repositories: 8 (may contain duplicates)
• Total versions: 40
• Total maintainers: 4

---

Dependencies

Score: 17.24513730170149