Carbon Package¶
Model Entry Point¶
-
natcap.invest.carbon.carbon_combined.execute_30(**args)¶ Carbon Storage and Sequestration.
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
- per metric ton (dollars) –
- 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.
-
natcap.invest.carbon.carbon_combined.execute(args)¶ Carbon Storage and Sequestration.
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
- per metric ton (dollars) –
- 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
-
natcap.invest.carbon.carbon_combined.execute_30(**args) Carbon Storage and Sequestration.
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
- per metric ton (dollars) –
- 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
natcap.invest.carbon.carbon_biophysical.MapCarbonPoolError¶ Bases:
exceptions.ExceptionA custom error for catching lulc codes from a raster that do not match the carbon pools data file
-
natcap.invest.carbon.carbon_biophysical.execute(args)¶
-
natcap.invest.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.
-
natcap.invest.carbon.carbon_valuation.execute(args)¶
-
natcap.invest.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
startedargs[‘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.
-
natcap.invest.carbon.carbon_utils.make_suffix(model_args)¶ Return the suffix from the args (prepending ‘_’ if necessary).
-
natcap.invest.carbon.carbon_utils.setup_dirs(workspace_dir, *dirnames)¶ Create the requested directories, and return the pathnames.
-
natcap.invest.carbon.carbon_utils.sum_pixel_values_from_uri(uri)¶ Return the sum of the values of all pixels in the given file.