diff --git a/HISTORY.rst b/HISTORY.rst index 71214591b0..5eb71f8807 100644 --- a/HISTORY.rst +++ b/HISTORY.rst @@ -44,6 +44,10 @@ Unreleased Changes ``pygeoprocessing.get_raster_info`` and ``pygeoprocessing.get_vector_info``. https://github.com/natcap/invest/issues/1645 + * The scripting page of the InVEST API documentation has been updated to + reflect changes in how InVEST is installed on modern systems, and also to + include images of the InVEST workbench instead of just broken links. + https://github.com/natcap/invest/issues/1660 * Workbench * Several small updates to the model input form UI to improve usability and visual consistency (https://github.com/natcap/invest/issues/912). diff --git a/doc/api-docs/conf.py b/doc/api-docs/conf.py index 52205cf614..46b1e83993 100644 --- a/doc/api-docs/conf.py +++ b/doc/api-docs/conf.py @@ -187,7 +187,7 @@ natcap.invest.carbon.execute(args) For examples of scripting a model run, or multiple successive model runs, -see :ref:`CreatingSamplePythonScripts`. +see :ref:`CreatingPythonScripts`. .. contents:: Available Models and Tools: diff --git a/doc/api-docs/scripting.rst b/doc/api-docs/scripting.rst index 393ddd2ef4..442a63375a 100644 --- a/doc/api-docs/scripting.rst +++ b/doc/api-docs/scripting.rst @@ -20,98 +20,71 @@ InVEST models from the command-line. Setting up your Python environment ================================== -1. **Install Python 3.6 or later.** +We recommend using the ``conda`` or ``mamba`` package manager to create an +environment. The easiest way to do so is to execute the following command:: - Python can be `downloaded from here `_. When installing, - be sure to allow ``python.exe`` to be added to the path in the installation options. + mamba create -n invest-env -c conda-forge natcap.invest +This will create a new environment called ``invest-env`` with the latest +released versions of python and ``natcap.invest``, as well as all dependencies +needed to execute ``natcap.invest``. -2. **Put pip on the PATH.** +Alternate installation methods are available. Please see the :ref:`installing` +guide for further instructions on setting up your python environment and +installing the ``natcap.invest`` package. - The ``pip`` utility for installing python packages is already included with - Python 2.7.9 and later. Be sure to add ``C:\Python37\Scripts`` (or your custom - install location) to the Windows PATH environment variable so that ``pip`` can - be called from the command line without needing to use its full path. +.. _CreatingPythonScripts: - 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:: +======================= +Creating Python Scripts +======================= - > pip install +1. **Launch InVEST Workbench and Open the Selected Model** -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 ``. - - .. This ..include:: part will automatically pull the contents of requirements.txt - and include the file from line 9 through the end. - - .. include:: ../../requirements.txt - :literal: - :start-line: 9 - - -4. **Install the InVEST python package** - - 4a. Download a release of the ``natcap.invest`` python package. - - * `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 - `_ - * ``.zip`` and ``.tar.gz`` files are source archives. - See :ref:`installing` for details, including how to - install specific development versions of ``natcap.invest``. - - -.. _CreatingSamplePythonScripts: - -============================== -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. + Once you have selected an InVEST model to script, launch the workbench and + select the model from the list of available models. This guide will follow + the Nutrient Delivery Ratio (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. + data is appropriate. However, if you wish to write a script to execute + several InVEST model runs in sequence, it would be reasonable to populate + the user interface with data for the first run in the sequence. -3. **Generate a sample Python Script from the User Interface** +3. **Generate a 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. + In the model interface, select *"Save as..."* in the left-hand menu bar, + *"Python script"* in the dialog box, and then save the file to a known location. -|2w7pilj.png| + |workbench_save_as.png| + |modal_save_as.png| -.. |2w7pilj.png| image:: https://bitbucket.org/repo/ag8qdk/images/3205488039-2w7pilj.png +.. |workbench_save_as.png| image:: scripting/workbench_save_as.png +.. |modal_save_as.png| image:: scripting/modal_save_as.png 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:\Python37\python.exe`` and the script was saved in - ``C:\Users\rpsharp\Desktop\ndr.py``, thus the command to invoke the - interpreter is:: + Launch a shell of your choice and activate your InVEST environment you + created earlier. We will use the Windows command prompt ``cmd.exe`` for an + example, but the same commands should work on Powershell, bash and zsh. If + you created an environment called ``invest-env``, you would activate it with + ``conda`` like so:: - > C:\Python37\python.exe C:\Users\rpsharp\Desktop\ndr.py + > conda activate invest-env -|34ecba0.png| + You will know your environment activated correctly when you see the + environment name at the beginning of your shell prompt. For example:: -.. |34ecba0.png| image:: https://bitbucket.org/repo/ag8qdk/images/2939811460-34ecba0.png + (invest-env) C:\Users\demo > + + Once the environment has been activated, we can run the python script we + saved in the previous step. Suppose we're on Windows and the script was + saved to ``C:\Users\demo\Desktop\ndr.py``, the command to run the script + would be:: + + (invest-env) C:\Users\demo > python C:\Users\demo\Desktop\ndr.py 5. **Output Results** @@ -133,50 +106,68 @@ For reference, consider the following script generated by the Nutrient model wit .. code-block:: python - """ - 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 - """ + # coding=UTF-8 + # ----------------------------------------------- + # Generated by InVEST 3.14.2 on Wed Oct 23 10:49:40 2024 + # Model: Nutrient Delivery Ratio + + import logging + import sys import natcap.invest.ndr.ndr + import natcap.invest.utils + + LOGGER = logging.getLogger(__name__) + root_logger = logging.getLogger() + + handler = logging.StreamHandler(sys.stdout) + formatter = logging.Formatter( + fmt=natcap.invest.utils.LOG_FMT, + datefmt='%m/%d/%Y %H:%M:%S ') + handler.setFormatter(formatter) + logging.basicConfig(level=logging.INFO, handlers=[handler]) 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', + 'biophysical_table_path': 'C:\\Users\demo\invest-sample-data\\NDR\\biophysical_table_gura.csv', + 'calc_n': True, + 'calc_p': True, + 'dem_path': 'C:\\Users\demo\invest-sample-data\\NDR\\DEM_gura.tif', + 'k_param': '2', + 'lulc_path': 'C:\\Users\demo\invest-sample-data\\NDR\land_use_gura.tif', + 'results_suffix': 'gura', + 'runoff_proxy_path': 'C:\\Users\demo\invest-sample-data\\NDR\precipitation_gura.tif', + 'subsurface_critical_length_n': '200', + 'subsurface_eff_n': '0.8', + 'threshold_flow_accumulation': '1000', + 'watersheds_path': 'C:\\Users\demo\invest-sample-data\\NDR\watershed_gura.shp', + 'workspace_dir': 'C:\\Users\demo\invest-sample-data\\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. -|95zj7p.png| +Elements to note: -.. |95zj7p.png| image:: https://bitbucket.org/repo/ag8qdk/images/22613179-95zj7p.png +* *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’.`` + 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 +* *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)`` + 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. + 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 @@ -212,7 +203,7 @@ example, replace the last line in the UI generated Python script with: .. code-block:: python import os - landcover_dir = r'C:\User\Rich\Desktop\landcover_data' + landcover_dir = r'C:\User\demo\Desktop\landcover_data' if __name__ == '__main__': #Loop over all the filenames in the landcover dir @@ -225,43 +216,31 @@ example, replace the last line in the UI generated Python script with: 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. +``C:\User\demo\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. - +When you save a model run to a python script, InVEST will automatically include +code to write all logging to your console while it executes. But sometimes, +it's useful to save log messages from the model to a file. This can be done by +adding a few lines of code to the script, just after the existing logging +code: .. code-block:: python - import logging - import pygeoprocessing - - # Write all NDR log messages to logfile.txt - MODEL_LOGGER = logging.getLogger('natcap.invest.ndr') - handler = logging.FileHandler('logfile.txt') - MODEL_LOGGER.addHandler(handler) - - # log pygeoprocessing messages to the same logfile - PYGEO_LOGGER = logging.getLogger('pygeoprocessing') - PYGEO_LOGGER.addHandler(handler) + file_handler = logging.FileHandler('logfile.txt') + root_logger.addHandler(file_handler) -This will capture all logging generated by the ``ndr`` model and by -``pygeoprocessing``, writing all messages to ``logfile.txt``. While +This will capture all logging generated by any python package that executes +while running the ``ndr`` model 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 `_ +`Logging Cookbook `_ ===================================== Example: Enabling Parallel Processing @@ -306,7 +285,8 @@ Using the parameter study example, this might look like: Internationalization ==================== -If you use the InVEST python API to access model names, ``MODEL_SPEC``s, or validation messages, you can translate those strings using ``gettext``: +If you use the InVEST python API to access model names, ``MODEL_SPEC`` s, or +validation messages, you can translate those strings using ``gettext``: .. code-block:: python diff --git a/doc/api-docs/scripting/modal_save_as.png b/doc/api-docs/scripting/modal_save_as.png new file mode 100644 index 0000000000..b5f84c1bad Binary files /dev/null and b/doc/api-docs/scripting/modal_save_as.png differ diff --git a/doc/api-docs/scripting/workbench_save_as.png b/doc/api-docs/scripting/workbench_save_as.png new file mode 100644 index 0000000000..2d3a6525d1 Binary files /dev/null and b/doc/api-docs/scripting/workbench_save_as.png differ