# Scenario Generator: Proximity Based

## Summary

The proximity-based scenario generator creates a set of contrasting land use change maps that convert habitat in different spatial patterns. The user determines which habitat can be converted and what they are converted to, as well as type of pattern, based on proximity to the edge of a focal habitat. In this manner, an array of land-use change patterns can be generated, including pasture encroaching into forest from the forest edge, agriculture expanding from currently cropped areas, forest fragmentation, and many others. The resulting land-use maps can then be used as inputs to InVEST models, or other models for biodiversity or ecosystem services that are responsive to land use change.

## Introduction

In order to understand the change in biodiversity and ecosystem services (BES) resulting from change in land-use, it is often helpful to start with a scenario or a set of scenarios that exhibit different types of land-use change. Because many of the relationships between landscapes and BES are spatially-explicit, a different pattern of habitat conversion for the same total area of habitat converted can lead to very different impacts on BES. This proximity-based scenario generator creates different patterns of conversion according to user inputs designating focal habitat and converted habitat, in contrast to but potentially complementing the InVEST rule-based scenario generator that creates maps of land-use change according to user-assigned probabilities that certain transitions will occur. Thus, the intent of the InVEST proximity-based scenario generator is not to forecast actual predicted patterns of expansion, but rather to develop different patterns of land use change in order to examine the relationship between land-use change and BES, and how the relationship may differ depending on land use change assumptions.

## The Model

The tool can generate two scenarios at once (nearest to the edge and farthest from the edge of a focal habitat), for a conversion to particular habitat type for a given area. To convert to different habitat types, different habitat amounts, or to designate different focal habitats or converted habitats, the tool can be run multiple times in sequence.

### How it works

Three types of landcover must be defined: 1) Focal landcover is the landcover(s) that set the proximity rules from which the scenarios will be determined. The scenario generator will convert habitat from the edge or toward the edge of patches of these types of landcover. This does not mean it will convert these land-covers, only that it will measure distance to or from the edges in designating where the conversion will happen. 2) Convertible landcover is the landcover(s) that can be converted. These could be the same as the focal landcover(s), a subset, or completely different. 3) Replacement landcover is the landcover type to which the convertible landcovers will be converted. This can only be one landcover type per model run.

Two scenarios can then be run at a time: 1) Nearest to edge means that convertible landcover types closest to the edges of focal landcovers will be converted to the replacement landcover. 2) Farthest from edge means that convertible landcover types furthest from the edges of focal landcover types will be converted to the replacement landcover. If this scenario is chosen, the user can designate in how many steps the conversion should occur. This is relevant if the focal landcover is the same as the convertible land cover because the conversion of the focal landcover will create new edges and hence will affect the distance calculated from the edge of that landcover. If desired, the conversion can occur in several steps, each time converting the farthest from the edge of the focal landcover, causing a fragmentary pattern.

Below are some examples of the types of scenarios that can be generated by manipulating these basic inputs, using the land-cover in the sample data that ship with this model. This landcover is from MODIS, using the UMD classification (Friedl et al. 2011), which follows the following scheme: 1 – Evergreen needleleaf forest; 2 – Evergreen broadleaf forest; 3 – Deciduous needleleaf forest; 4 – Deciduous broadleaf forest; 5 – Mixed forest; 6 – Closed shrublands; 7 – Open shrublands; 8 – Woody savannas; 9 – Savannas; 10 – Grasslands; 12 – Croplands; 13 – Urban and built-up; 16 – Barren or sparsely vegetated.

Expand agriculture from forest edge inwards:

focal landcover codes: 1 2 3 4 5

convertible landcover codes: 1 2 3 4 5

replacement landcover code: 12

check “Convert Nearest to Edge”

number of steps toward conversion: 1

Expand agriculture from forest core outwards:

focal landcover codes: 1 2 3 4 5

convertible landcover codes: 1 2 3 4 5

replacement landcover code: 12

check “Convert Farthest From Edge”

number of steps toward conversion: 1

Expand agriculture by fragmenting forest:

focal landcover codes: 1 2 3 4 5

convertible landcover codes: 1 2 3 4 5

replacement landcover code: 12

check “Convert Farthest From Edge”

number of steps toward conversion: 10 (or as many steps as desired; the more steps, the more finely fragmented it will be and the longer the simulation will take)

Expand pasture into forest nearest to existing agriculture:

focal landcover codes: 12

convertible landcover codes: 1 2 3 4 5

replacement landcover code: 10

check “Convert Nearest to Edge”

number of steps toward conversion: 1

## Data Needs

The only required input data to run the proximity-based scenario generator is a base land-use/land-cover map and user-defined land cover codes pertaining to this base map to designate how the scenarios should be computed.

- workspace (directory, required): The folder where all the model’s output files will be written. If this folder does not exist, it will be created. If data already exists in the folder, it will be overwritten.

- file suffix (text, optional): Suffix that will be appended to all output file names. Useful to differentiate between model runs.

- base LULC map (raster, required): Base map from which to generate scenarios.

- area of interest (vector, polygon/multipolygon, optional): Area over which to run the conversion. Provide this input if change is only desired in a subregion of the Base LULC map.

  Prior to scenario generation, the map will be clipped to the extent of this vector.

- maximum area to convert (number, units: ha, required): Maximum area to be converted to agriculture.

  As many pixels as possible will be converted without exceeding this area.

- focal landcover codes (text, required): A space-separated list of LULC codes that are used to determine the proximity when referring to ‘towards’ or ‘away’ from the base landcover codes

- convertible landcover codes (text, required): A space-separated list of LULC codes that can be converted to agriculture.

- replacement landcover code (integer, required): The LULC code to which habitat will be converted.

  If there are multiple LULC types that are of interest for conversion, this tool should be run in sequence, choosing one type of conversion each time. A new code may be introduced if it is a novel land-use for the region or if it is desirable to track the expanded land-use as separate from historic land-use.

- convert farthest from edge (true/false): Convert the ‘convertible’ landcover codes starting at the furthest pixel from the ‘focal’ land cover areas and working inwards.

  Convertible land covers and habitat of interest land-covers may be the same, or a subset of one another, or they can be different. If they are the same, the number of steps for conversion should be specified, because the conversion of habitat within the focal land cover will create new habitat edge, resulting in a completely different pattern of conversion depending on how many steps are chosen.

- convert nearest to edge (true/false): Convert the ‘convertible’ landcover codes starting at the nearest pixels to the ‘focal’ land cover areas and working outwards.

  Convertible land covers and habitat of interest land-covers may be the same, or a subset of one another, or they can be different.

- number of conversion steps (integer, units: unitless, required): The number of steps that the simulation should take to fragment the habitat of interest in the fragmentation scenario. This parameter is used to divide the conversion simulation into equal subareas of the requested max area. During each sub-step the distance transform is recalculated from the base landcover codes. This can affect the final result if the base types are also convertible types.

  Entering a 1 means that all of the habitat conversion will occur in the center of the patch of the habitat of interest. Entering 10 will be fragmented according to a pattern of sequentially converting the pixels furthest from the edge of that habitat, over the number of steps specified by the user.

## Interpreting Results

### Final Results

- InVEST….log…txt: Each time the model is run, a text (.txt) file will appear in the Output folder. The file will list the parameter values for that run and will be named according to the model, the date and time, and the suffix.

- nearest_to_edge_<suffix>.tif: LULC raster for the scenario of conversion nearest to the edge of the focal habitat.

- farthest_from_edge_<suffix>.tif: LULC raster for the scenario of conversion farthest from the edge of the focal habitat.

- nearest_to_edge_<suffix>.csv: table listing the area (in hectares) and number of pixels for different land cover types converted for the scenario of conversion nearest to the edge of the focal habitat. Values in the original lucode column reflect landcover(s) converted by the model. The replacement lucode column reflects the landcover type to which the original landcover(s) was converted. All values in this column will be the same, as only one Replacement Landcover Code can be specified per model run.

- farthest_from_edge_<suffix>.csv: table listing the area (in hectares) and number of pixels for different land cover types converted for the scenario of conversion farthest from the edge of the focal habitat. Values in the original lucode column reflect landcover(s) converted by the model. The replacement lucode column reflects the landcover type to which the original landcover(s) was converted. All values in this column will be the same, as only one Replacement Landcover Code can be specified per model run.

### Intermediate Results

- {farthest_from_/nearest_to}_edge_distance_<suffix>.tif: This raster shows the distance (in number of pixels) of each pixel to the nearest edge of the focal landcover.

- _tmp_work_tokens: This directory stores metadata used internally to enable avoided re-computation.

## Sample Script

The following script is provided to demonstrate how the scenarios described in Section “How It Works” can be composed into a single script that’s callable from the InVEST Python API:

    import natcap.invest.scenario_generator_proximity_based

    edge_args = {
        u'aoi_path': u'C:/Users/Rich/Documents/svn_repos/invest-sample-data/scenario_proximity/scenario_proximity_aoi.shp',
        u'area_to_convert': u'20000.0',
        u'base_lulc_path': u'C:/Users/Rich/Documents/svn_repos/invest-sample-data/scenario_proximity/scenario_proximity_lulc.tif',
        u'convert_farthest_from_edge': False,
        u'convert_nearest_to_edge': True,
        u'convertible_landcover_codes': u'1 2 3 4 5',
        u'focal_landcover_codes': u'1 2 3 4 5',
        u'n_fragmentation_steps': u'1',
        u'replacement_lucode': u'12',
        u'results_suffix': 'edge',
        u'workspace_dir': u'C:\\Users\\Rich/Documents/scenario_proximity_workspace',
    }

    core_args = {
        u'aoi_path': u'C:/Users/Rich/Documents/svn_repos/invest-sample-data/scenario_proximity/scenario_proximity_aoi.shp',
        u'area_to_convert': u'20000.0',
        u'base_lulc_path': u'C:/Users/Rich/Documents/svn_repos/invest-sample-data/scenario_proximity/scenario_proximity_lulc.tif',
        u'convert_farthest_from_edge': True,
        u'convert_nearest_to_edge': False,
        u'convertible_landcover_codes': u'1 2 3 4 5',
        u'focal_landcover_codes': u'1 2 3 4 5',
        u'n_fragmentation_steps': u'1',
        u'replacement_lucode': u'12',
        u'results_suffix': 'core',
        u'workspace_dir': u'C:\\Users\\Rich/Documents/scenario_proximity_workspace',
    }

    frag_args = {
        u'aoi_path': u'C:/Users/Rich/Documents/svn_repos/invest-sample-data/scenario_proximity/scenario_proximity_aoi.shp',
        u'area_to_convert': u'20000.0',
        u'base_lulc_path': u'C:/Users/Rich/Documents/svn_repos/invest-sample-data/scenario_proximity/scenario_proximity_lulc.tif',
        u'convert_farthest_from_edge': True,
        u'convert_nearest_to_edge': False,
        u'convertible_landcover_codes': u'1 2 3 4 5',
        u'focal_landcover_codes': u'1 2 3 4 5',
        u'n_fragmentation_steps': u'10',
        u'replacement_lucode': u'12',
        u'results_suffix': 'frag',
        u'workspace_dir': u'C:\\Users\\Rich/Documents/scenario_proximity_workspace',
    }

    ag_args = {
        u'aoi_path': u'C:/Users/Rich/Documents/svn_repos/invest-sample-data/scenario_proximity/scenario_proximity_aoi.shp',
        u'area_to_convert': u'20000.0',
        u'base_lulc_path': u'C:/Users/Rich/Documents/svn_repos/invest-sample-data/scenario_proximity/scenario_proximity_lulc.tif',
        u'convert_farthest_from_edge': False,
        u'convert_nearest_to_edge': True,
        u'convertible_landcover_codes': u'12',
        u'focal_landcover_codes': u'1 2 3 4 5',
        u'n_fragmentation_steps': u'1',
        u'replacement_lucode': u'12',
        u'results_suffix': 'ag',
        u'workspace_dir': u'C:\\Users\\Rich/Documents/scenario_proximity_workspace',
    }
    if __name__ == '__main__':
        natcap.invest.scenario_generator_proximity_based.execute(edge_args)
        natcap.invest.scenario_generator_proximity_based.execute(core_args)
        natcap.invest.scenario_generator_proximity_based.execute(frag_args)
        natcap.invest.scenario_generator_proximity_based.execute(ag_args)