Carbon Package

Model Entry Point

invest_natcap.carbon.carbon_combined.execute_30(**args)

Run the carbon model.

This can include the biophysical model, the valuation model, or both.

Parameters:
  • workspace_dir (string) – a uri to the directory that will write output and other temporary files during calculation. (required)
  • suffix (string) – a string to append to any output file name (optional)
  • do_biophysical (boolean) – whether to run the biophysical model
  • lulc_cur_uri (string) – a uri to a GDAL raster dataset (required)
  • lulc_cur_year (int) – An integer representing the year of lulc_cur used in HWP calculation (required if args contains a ‘hwp_cur_shape_uri’, or ‘hwp_fut_shape_uri’ key)
  • lulc_fut_uri (string) – a uri to a GDAL raster dataset (optional if calculating sequestration)
  • lulc_redd_uri (string) – a uri to a GDAL raster dataset that represents land cover data for the REDD policy scenario (optional).
  • lulc_fut_year (int) – An integer representing the year of lulc_fut used in HWP calculation (required if args contains a ‘hwp_fut_shape_uri’ key)
  • carbon_pools_uri (string) – a uri to a CSV or DBF dataset mapping carbon storage density to the lulc classifications specified in the lulc rasters. (required if ‘do_uncertainty’ is false)
  • hwp_cur_shape_uri (String) – Current shapefile uri for harvested wood calculation (optional, include if calculating current lulc hwp)
  • hwp_fut_shape_uri (String) – Future shapefile uri for harvested wood calculation (optional, include if calculating future lulc hwp)
  • do_uncertainty (boolean) – a boolean that indicates whether we should do uncertainty analysis. Defaults to False if not present.
  • carbon_pools_uncertain_uri (string) – as above, but has probability distribution data for each lulc type rather than point estimates. (required if ‘do_uncertainty’ is true)
  • confidence_threshold (float) – a number between 0 and 100 that indicates the minimum threshold for which we should highlight regions in the output raster. (required if ‘do_uncertainty’ is True)
  • sequest_uri (string) – uri to a GDAL raster dataset describing the amount of carbon sequestered.
  • yr_cur (int) – the year at which the sequestration measurement started
  • yr_fut (int) – the year at which the sequestration measurement ended
  • do_valuation (boolean) – whether to run the valuation model
  • carbon_price_units (string) – indicates whether the price is in terms of carbon or carbon dioxide. Can value either as ‘Carbon (C)’ or ‘Carbon Dioxide (CO2)’.
  • V (string) – value of a sequestered ton of carbon or carbon dioxide in
  • r (int) – the market discount rate in terms of a percentage
  • c (float) – the annual rate of change in the price of carbon

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir/',
    'suffix': '_results',
    'do_biophysical': True,
    'lulc_cur_uri': 'path/to/lulc_cur',
    'lulc_cur_year': 2014,
    'lulc_fut_uri': 'path/to/lulc_fut',
    'lulc_redd_uri': 'path/to/lulc_redd',
    'lulc_fut_year': 2025,
    'carbon_pools_uri': 'path/to/carbon_pools',
    'hwp_cur_shape_uri': 'path/to/hwp_cur_shape',
    'hwp_fut_shape_uri': 'path/to/hwp_fut_shape',
    'do_uncertainty': True,
    'carbon_pools_uncertain_uri': 'path/to/carbon_pools_uncertain',
    'confidence_threshold': 50.0,
    'sequest_uri': 'path/to/sequest_uri',
    'yr_cur': 2014,
    'yr_fut': 2025,
    'do_valuation': True,
    'carbon_price_units':, 'Carbon (C)',
    'V': 43.0,
    'r': 7,
    'c': 0,
}
Returns:outputs – contains names of all output files
Return type:dictionary

Carbon Combined

Integrated carbon model with biophysical and valuation components.

invest_natcap.carbon.carbon_combined.execute(args)
invest_natcap.carbon.carbon_combined.execute_30(**args)

Run the carbon model.

This can include the biophysical model, the valuation model, or both.

Parameters:
  • workspace_dir (string) – a uri to the directory that will write output and other temporary files during calculation. (required)
  • suffix (string) – a string to append to any output file name (optional)
  • do_biophysical (boolean) – whether to run the biophysical model
  • lulc_cur_uri (string) – a uri to a GDAL raster dataset (required)
  • lulc_cur_year (int) – An integer representing the year of lulc_cur used in HWP calculation (required if args contains a ‘hwp_cur_shape_uri’, or ‘hwp_fut_shape_uri’ key)
  • lulc_fut_uri (string) – a uri to a GDAL raster dataset (optional if calculating sequestration)
  • lulc_redd_uri (string) – a uri to a GDAL raster dataset that represents land cover data for the REDD policy scenario (optional).
  • lulc_fut_year (int) – An integer representing the year of lulc_fut used in HWP calculation (required if args contains a ‘hwp_fut_shape_uri’ key)
  • carbon_pools_uri (string) – a uri to a CSV or DBF dataset mapping carbon storage density to the lulc classifications specified in the lulc rasters. (required if ‘do_uncertainty’ is false)
  • hwp_cur_shape_uri (String) – Current shapefile uri for harvested wood calculation (optional, include if calculating current lulc hwp)
  • hwp_fut_shape_uri (String) – Future shapefile uri for harvested wood calculation (optional, include if calculating future lulc hwp)
  • do_uncertainty (boolean) – a boolean that indicates whether we should do uncertainty analysis. Defaults to False if not present.
  • carbon_pools_uncertain_uri (string) – as above, but has probability distribution data for each lulc type rather than point estimates. (required if ‘do_uncertainty’ is true)
  • confidence_threshold (float) – a number between 0 and 100 that indicates the minimum threshold for which we should highlight regions in the output raster. (required if ‘do_uncertainty’ is True)
  • sequest_uri (string) – uri to a GDAL raster dataset describing the amount of carbon sequestered.
  • yr_cur (int) – the year at which the sequestration measurement started
  • yr_fut (int) – the year at which the sequestration measurement ended
  • do_valuation (boolean) – whether to run the valuation model
  • carbon_price_units (string) – indicates whether the price is in terms of carbon or carbon dioxide. Can value either as ‘Carbon (C)’ or ‘Carbon Dioxide (CO2)’.
  • V (string) – value of a sequestered ton of carbon or carbon dioxide in
  • r (int) – the market discount rate in terms of a percentage
  • c (float) – the annual rate of change in the price of carbon

Example Args Dictionary:

{
    'workspace_dir': 'path/to/workspace_dir/',
    'suffix': '_results',
    'do_biophysical': True,
    'lulc_cur_uri': 'path/to/lulc_cur',
    'lulc_cur_year': 2014,
    'lulc_fut_uri': 'path/to/lulc_fut',
    'lulc_redd_uri': 'path/to/lulc_redd',
    'lulc_fut_year': 2025,
    'carbon_pools_uri': 'path/to/carbon_pools',
    'hwp_cur_shape_uri': 'path/to/hwp_cur_shape',
    'hwp_fut_shape_uri': 'path/to/hwp_fut_shape',
    'do_uncertainty': True,
    'carbon_pools_uncertain_uri': 'path/to/carbon_pools_uncertain',
    'confidence_threshold': 50.0,
    'sequest_uri': 'path/to/sequest_uri',
    'yr_cur': 2014,
    'yr_fut': 2025,
    'do_valuation': True,
    'carbon_price_units':, 'Carbon (C)',
    'V': 43.0,
    'r': 7,
    'c': 0,
}
Returns:outputs – contains names of all output files
Return type:dictionary

Carbon Biophysical

InVEST Carbon biophysical module at the “uri” level

exception invest_natcap.carbon.carbon_biophysical.MapCarbonPoolError

Bases: exceptions.Exception

A custom error for catching lulc codes from a raster that do not match the carbon pools data file

invest_natcap.carbon.carbon_biophysical.execute(args)
invest_natcap.carbon.carbon_biophysical.execute_30(**args)

This function invokes the carbon model given URI inputs of files. It will do filehandling and open/create appropriate objects to pass to the core carbon biophysical processing function. It may write log, warning, or error messages to stdout.

args - a python dictionary with at the following possible entries: args[‘workspace_dir’] - a uri to the directory that will write output

and other temporary files during calculation. (required)

args[‘suffix’] - a string to append to any output file name (optional) args[‘lulc_cur_uri’] - is a uri to a GDAL raster dataset (required) args[‘carbon_pools_uri’] - is a uri to a CSV or DBF dataset mapping carbon

storage density to the lulc classifications specified in the lulc rasters. (required if ‘do_uncertainty’ is false)
args[‘carbon_pools_uncertain_uri’] - as above, but has probability distribution
data for each lulc type rather than point estimates. (required if ‘do_uncertainty’ is true)
args[‘do_uncertainty’] - a boolean that indicates whether we should do
uncertainty analysis. Defaults to False if not present.
args[‘confidence_threshold’] - a number between 0 and 100 that indicates
the minimum threshold for which we should highlight regions in the output raster. (required if ‘do_uncertainty’ is True)
args[‘lulc_fut_uri’] - is a uri to a GDAL raster dataset (optional
if calculating sequestration)
args[‘lulc_cur_year’] - An integer representing the year of lulc_cur
used in HWP calculation (required if args contains a ‘hwp_cur_shape_uri’, or ‘hwp_fut_shape_uri’ key)
args[‘lulc_fut_year’] - An integer representing the year of lulc_fut
used in HWP calculation (required if args contains a ‘hwp_fut_shape_uri’ key)
args[‘lulc_redd_uri’] - is a uri to a GDAL raster dataset that represents
land cover data for the REDD policy scenario (optional).
args[‘hwp_cur_shape_uri’] - Current shapefile uri for harvested wood
calculation (optional, include if calculating current lulc hwp)
args[‘hwp_fut_shape_uri’] - Future shapefile uri for harvested wood
calculation (optional, include if calculating future lulc hwp)

returns a dict with the names of all output files.

Carbon Valuation

InVEST valuation interface module. Informally known as the URI level.

invest_natcap.carbon.carbon_valuation.execute(args)
invest_natcap.carbon.carbon_valuation.execute_30(**args)

This function calculates carbon sequestration valuation.

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

args[‘workspace_dir’] - a uri to the directory that will write output
and other temporary files during calculation. (required)

args[‘suffix’] - a string to append to any output file name (optional) args[‘sequest_uri’] - is a uri to a GDAL raster dataset describing the

amount of carbon sequestered (baseline scenario, if this is REDD)
args[‘sequest_redd_uri’] (optional) - uri to the raster dataset for
sequestration under the REDD policy scenario
args[‘conf_uri’] (optional) - uri to the raster dataset indicating
confident pixels for sequestration or emission

args[‘conf_redd_uri’] (optional) - as above, but for the REDD scenario args[‘carbon_price_units’] - a string indicating whether the price is

in terms of carbon or carbon dioxide. Can value either as ‘Carbon (C)’ or ‘Carbon Dioxide (CO2)’.
args[‘V’] - value of a sequestered ton of carbon or carbon dioxide in
dollars per metric ton

args[‘r’] - the market discount rate in terms of a percentage args[‘c’] - the annual rate of change in the price of carbon args[‘yr_cur’] - the year at which the sequestration measurement

started

args[‘yr_fut’] - the year at which the sequestration measurement ended

returns a dict with output file URIs.

Carbon Utilities

Useful functions for the carbon biophysical and valuation models.

invest_natcap.carbon.carbon_utils.make_suffix(model_args)

Return the suffix from the args (prepending ‘_’ if necessary).

invest_natcap.carbon.carbon_utils.setup_dirs(workspace_dir, *dirnames)

Create the requested directories, and return the pathnames.

invest_natcap.carbon.carbon_utils.sum_pixel_values_from_uri(uri)

Return the sum of the values of all pixels in the given file.

Module contents