natcap.invest.pollination package

Submodules

natcap.invest.pollination.pollination module

Pollinator service model for InVEST.

exception natcap.invest.pollination.pollination.MissingFields

Bases: exceptions.ValueError

natcap.invest.pollination.pollination.build_uri(directory, basename, suffix=[])

Take the input directory and basename, inserting the provided suffixes just before the file extension. Each string in the suffix list will be underscore-separated.

directory - a python string folder path basename - a python string filename suffix=’’ - a python list of python strings to be separated by

underscores and concatenated with the basename just before the extension.

returns a python string of the complete path with the correct filename.

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.

natcap.invest.pollination.pollination_core module

InVEST Pollination model core module

natcap.invest.pollination.pollination_core.add_two_rasters(raster_1, raster_2, out_uri)

Add two rasters where pixels in raster_1 are not nodata. Pixels are considered to have a nodata value iff the pixel value in raster_1 is nodata. Raster_2’s pixel value is not checked for nodata.

raster_1 - a uri to a GDAL dataset raster_2 - a uri to a GDAL dataset out_uri - the uri at which to save the resulting raster.

Returns nothing.

natcap.invest.pollination.pollination_core.calculate_abundance(landuse, lu_attr, guild, nesting_fields, floral_fields, uris)

Calculate pollinator abundance on the landscape. The calculated pollinator abundance raster will be created at uris[‘species_abundance’].

landuse - a URI to a GDAL dataset of the LULC. lu_attr - a TableHandler guild - a dictionary containing information about the pollinator. All

entries are required: ‘alpha’ - the typical foraging distance in m ‘species_weight’ - the relative weight resource_n - One entry for each nesting field for each fieldname

denoted in nesting_fields. This value must be either 0 and 1, indicating whether the pollinator uses this nesting resource for nesting sites.
resource_f - One entry for each floral field denoted in
floral_fields. This value must be between 0 and 1, representing the liklihood that this species will forage during this season.
nesting_fields - a list of string fieldnames. Used to extract nesting
fields from the guild dictionary, so fieldnames here must exist in guild.
floral_fields - a list of string fieldnames. Used to extract floral
season fields from the guild dictionary. Fieldnames here must exist in guild.
uris - a dictionary with these entries:

‘nesting’ - a URI to where the nesting raster will be saved. ‘floral’ - a URI to where the floral resource raster will be saved. ‘species_abundance’ - a URI to where the species abundance raster

will be saved.

‘temp’ - a URI to a folder where temp files will be saved

Returns nothing.

natcap.invest.pollination.pollination_core.calculate_farm_abundance(species_abundance, ag_map, alpha, uri, temp_dir)

Calculate the farm abundance raster. The final farm abundance raster will be saved to uri.

species_abundance - a URI to a GDAL dataset of species abundance. ag_map - a uri to a GDAL dataset of values where ag pixels are 1

and non-ag pixels are 0.

alpha - the typical foraging distance of the current pollinator. uri - the output URI for the farm_abundance raster. temp_dir- the output folder for temp files

Returns nothing.

natcap.invest.pollination.pollination_core.calculate_service(rasters, nodata, alpha, part_wild, out_uris)

Calculate the service raster. The finished raster will be saved to out_uris[‘service_value’].

rasters - a dictionary with these entries:

‘farm_value’ - a GDAL dataset. ‘farm_abundance’ - a GDAL dataset. ‘species_abundance’ - a GDAL dataset. ‘ag_map’ - a GDAL dataset. Values are either nodata, 0 (if not an

ag pixel) or 1 (if an ag pixel).

nodata - the nodata value for output rasters. alpha - the expected distance part_wild - a number between 0 and 1 representing the proportion of all

pollination that is done by wild pollinators.
out_uris - a dictionary with these entries:
‘species_value’ - a URI. The raster created at this URI will
represent the part of the farm’s value that is attributed to the current species.
‘species_value_blurred’ - the raster created at this URI
will be a copy of the species_value raster that has had a exponential convolution filter applied to it.
‘service_value’ - a URI. The raster created at this URI will be the
calculated service value raster.

‘temp’ - a folder in which to store temp files.

Returns nothing.

natcap.invest.pollination.pollination_core.calculate_yield(in_raster, out_uri, half_sat, wild_poll, out_nodata)

Calculate the yield raster.

in_raster - a uri to a GDAL dataset out_uri -a uri for the output (yield) dataset half_sat - the half-saturation constant, a python int or float wild_poll - the proportion of crops that are pollinated by wild

pollinators. An int or float from 0 to 1.

out_nodata - the nodata value for the output raster

Returns nothing

natcap.invest.pollination.pollination_core.divide_raster(raster, divisor, uri)

Divide all non-nodata values in raster_1 by divisor and save the output raster to uri.

raster - a uri to a GDAL dataset divisor - the divisor (a python scalar) uri - the uri to which to save the output raster.

Returns nothing.

natcap.invest.pollination.pollination_core.execute_model(args)

Execute the biophysical component of the pollination model.

args - a python dictionary with at least the following entries:

‘landuse’ - a URI to a GDAL dataset ‘landuse_attributes’ - A fileio AbstractTableHandler object ‘guilds’ - A fileio AbstractTableHandler object ‘ag_classes’ - a python list of ints representing agricultural

classes in the landuse map. This list may be empty to represent the fact that no landuse classes are to be designated as strictly agricultural.

‘nesting_fields’ - a python list of string nesting fields ‘floral fields’ - a python list of string floral fields ‘do_valuation’ - a boolean indicating whether to do valuation ‘paths’ - a dictionary with the following entries:

‘workspace’ - the workspace path ‘intermediate’ - the intermediate folder path ‘output’ - the output folder path ‘temp’ - a temp folder path.

Additionally, the args dictionary should contain these URIs, which must all be python strings of either type str or else utf-8 encoded unicode.

‘ag_map’ - a URI ‘foraging_average’ - a URI ‘abundance_total’ - a URI ‘farm_value_sum’ - a URI (Required if do_valuation == True) ‘service_value_sum’ - a URI (Required if do_valuation == True)

The args dictionary must also have a dictionary containing species-specific information:

‘species’ - a python dictionary with a contained dictionary for each

species to be considered by the model. The key to each dictionary should be the species name. For example:

args[‘species’][‘Apis’] = { ... species_dictionary ... }
The species-specific dictionary must contain these elements:
‘floral’ - a URI ‘nesting’ - a URI ‘species_abundance’ - a URI ‘farm_abundance’ - a URI

If do_valuation == True, the following entries are also required to be in the species-specific dictionary:

‘farm_value’ - a URI ‘value_abundance_ratio’ - a URI ‘value_abundance_ratio_blurred’ - a URI ‘service_value’ - a URI

returns nothing.

natcap.invest.pollination.pollination_core.map_attribute(base_raster, attr_table, guild_dict, resource_fields, out_uri, list_op)

Make an intermediate raster where values are mapped from the base raster according to the mapping specified by key_field and value_field.

base_raster - a URI to a GDAL dataset attr_table - a subclass of fileio.AbstractTableHandler guild_dict - a python dictionary representing the guild row for this

species.

resource_fields - a python list of string resource fields out_uri - a uri for the output dataset list_op - a python callable that takes a list of numerical arguments

and returns a python scalar. Examples: sum; max

returns nothing.

natcap.invest.pollination.pollination_core.reclass_ag_raster(landuse_uri, out_uri, ag_classes, nodata)

Reclassify the landuse raster into a raster demarcating the agricultural state of a given pixel. The reclassed ag raster will be saved to uri.

landuse - a GDAL dataset. The land use/land cover raster. out_uri - the uri of the output, reclassified ag raster. ag_classes - a list of landuse classes that are agricultural. If an

empty list is provided, all landcover classes are considered to be agricultural.

nodata - an int or float.

Returns nothing.

Module contents