Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Consolidate text between UG and args spec (part 1 of 3) #42

Merged
merged 25 commits into from
Nov 20, 2021
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
25 commits
Select commit Hold shift + click to select a range
812cb5e
test commit
emlys Jul 16, 2021
07879aa
start using investspec role in carbon and cbc pages
emlys Jul 16, 2021
321f9fc
draft of consolidating CV
emlys Jul 17, 2021
f4a11ab
consolidate delineateit
emlys Aug 4, 2021
0f482ed
improve format
emlys Aug 19, 2021
fa68760
update input types
emlys Aug 19, 2021
e9dc9ef
undo changes to gha workflow
emlys Aug 19, 2021
3d0c1ff
remove commented out lines"
emlys Aug 19, 2021
794dbf4
minor edits
emlys Aug 19, 2021
460cabd
include columns in tables for CBC, CV
emlys Aug 20, 2021
b3f49f2
minor cv edits
emlys Aug 20, 2021
81822d9
list out columns in crop production
emlys Aug 20, 2021
bf6d9a7
point to corresponding invest branch in requirements
emlys Aug 24, 2021
9f68222
Update source/input_types.rst
emlys Aug 30, 2021
8564db4
clean up
emlys Aug 30, 2021
eff9a91
remove old comment in cv about small coastline features
emlys Aug 31, 2021
eee8531
Merge branch 'release/3.10' into task/31/models-A-D
emlys Sep 1, 2021
b319575
update to 10 crops only
emlys Sep 3, 2021
a5a855c
update requirement to natcap/invest release/3.10
emlys Sep 13, 2021
fe28bde
Merge branch 'example/generate-docs' into task/31/models-A-D
emlys Sep 13, 2021
6fb2d0f
undo outdated changes to workflow, makefile
emlys Sep 22, 2021
5db4d07
add variable definitions for carbon equation
emlys Nov 17, 2021
6310bbf
Update source/delineateit.rst
emlys Nov 17, 2021
732d02f
remove question marks
emlys Nov 17, 2021
eb3b6bf
Merge branch 'task/31/models-A-D' of https://github.com/emlys/invest.…
emlys Nov 17, 2021
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion Makefile
Original file line number Diff line number Diff line change
Expand Up @@ -20,7 +20,7 @@ help:
@echo " html to make standalone HTML files"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " linkcheck to check all external links for integrity"
@echo " invest-sample-data to check out the invest-sample-data repo"
@echo " $(GIT_SAMPLE_DATA_REPO_PATH) to check out the invest-sample-data repo"
@echo " prep_sampledata to create modified tables in invest-sample-data that display nicely"
@echo " test_investspec to run unit tests for the custom Sphinx extension"
@echo " demo_investspec to run a demo using the custom Sphinx extension"
Expand Down
2 changes: 1 addition & 1 deletion requirements.txt
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
git-lfs
git+https://github.com/emlys/invest.git@task/invest.users-guide/30
git+https://github.com/natcap/invest.git@release/3.10
pint
setuptools_scm
sphinx
67 changes: 45 additions & 22 deletions source/carbonstorage.rst
Original file line number Diff line number Diff line change
Expand Up @@ -42,6 +42,26 @@ Outputs of the model are expressed as Mg of carbon per pixel, and if desired, th

The valuation model estimates the economic value of sequestration (not storage) as a function of the amount of carbon sequestered, the monetary value of each unit of carbon, a monetary discount rate, and the change in the value of carbon sequestration over time. Thus, valuation can only be done in the carbon model if you have a future scenario. Valuation is applied to sequestration, not storage, because market prices relate only to carbon sequestration. Discount rates are multipliers that typically reduce the value of carbon sequestration over time. The first type of discounting, the standard economic procedure of financial discounting, reflects the fact that people typically value immediate benefits more than future benefits due to uncertainty and assumed economic inflation over time. The second discount rate adjusts the social value of carbon sequestration over time. This value will change as the impact of carbon emissions on expected climate change-related damages changes. If we expect carbon sequestered today to have a greater impact on climate change mitigation than carbon sequestered in the future this second discount rate should be positive. On the other hand, if we expect carbon sequestered today to have less of an impact on climate change mitigation than carbon sequestered in the future, this second discount rate should be negative.

The value of carbon sequestration over time for a given parcel *x* is:

.. math:: value\_seq_x=V\frac{s_x}{q-p}\sum^{q-p-1}_{t=0}\frac{1}{\left(1+\frac{r}{100}\right)^t\left(1+\frac{c}{100}\right)^t}
:label: carbon_value

where

* :math:`V` is the price per metric ton of carbon

* :math:`s_x` is the amount of carbon, in metric tons, sequestered on parcel :math:`x`

* :math:`q` is the future year

* :math:`p` is the current year

* :math:`r` is the yearly market discount rate for the carbon price

* :math:`c` is the yearly rate of change in the price of carbon


REDD Scenario Analysis
----------------------

Expand Down Expand Up @@ -71,17 +91,25 @@ Finally, while most sequestration follows a nonlinear path such that carbon is s
Data Needs
==========

- **Current land use/land cover** (required): Raster of LULC for each pixel, where each unique integer represents a different class. *All values in this raster MUST have corresponding entries in the Carbon Pools table.*
.. note:: All spatial inputs must be in the same projected coordinate system and in linear meter units.

- **Current Landcover Calendar Year** (required for sequestration): The year depicted by the Current LULC map, for use in economic valuation.
.. note:: All carbon data should be for elemental carbon, not CO\ :sub:`2`.

- **Carbon pools** (required): A CSV (comma-separated values) table of LULC classes, containing data on carbon stored in each of the four fundamental pools for each LULC class. If information on some carbon pools is not available, pools can be estimated from other pools, or omitted by leaving all values for the pool equal to 0. The table must contain the following columns:
- :investspec:`carbon lulc_cur_path`

* **lucode**: Unique integer for each LULC class (e.g., 1 for forest, 3 for grassland, etc.) *Every value in the LULC map MUST have a corresponding "lucode" value in the Carbon Pool table.*
* **c_above**: Carbon density in aboveground biomass [units: megagrams/hectare]
* **c_below**: Carbon density in belowground biomass [units: megagrams/hectare]
* **c_soil**: Carbon density in soil [units: megagrams/hectare]
* **c_dead**: Carbon density in dead matter [units: megagrams/hectare]
- :investspec:`carbon lulc_cur_year`

- :investspec:`carbon calc_sequestration`

- :investspec:`carbon lulc_fut_path`

- :investspec:`carbon lulc_fut_year`

- :investspec:`carbon do_redd`

- :investspec:`carbon lulc_redd_path`

- :investspec:`carbon carbon_pools_path` If information on some carbon pools is not available, pools can be estimated from other pools, or omitted by leaving all values for the pool equal to 0.
emlys marked this conversation as resolved.
Show resolved Hide resolved

*Example:* Hypothetical study with five LULC classes. Class 1 (Forest) contains the most carbon in all pools. In this example, carbon stored in above- and below-ground biomass differs strongly among land use classes, but carbon stored in soil varies less dramatically.

Expand All @@ -95,24 +123,19 @@ Data Needs
5 Open/urban 5 5 15 2
====== ================== ======= ======= ====== ======

- **Future landcover** (required for sequestration and valuation): Raster of LULC for each pixel, where each unique integer represents a different class. *All values in this raster MUST have corresponding entries in the Carbon Pools table.*

- **Future Landcover Calendar Year** (required for valuation): The year depicted by the Future LULC map, for use in economic valuation.

- **REDD Policy** (required for REDD sequestration and valuation): Raster of LULC for each pixel, where each unique integer represents a different class. *All values in this raster MUST have corresponding entries in the Carbon Pools table.*
- :investspec:`carbon do_valuation`

- **Economic data** (required for valuation):
- :investspec:`carbon price_per_metric_ton_of_c` This is :math:`V` in equation :eq:`carbon_value`. For applications interested in estimating the total value of carbon sequestration, we recommend value estimates based on damage costs associated with the release of an additional ton of carbon - the social cost of carbon (SCC). Stern (2007), Tol (2009), and Nordhaus (2007a) present estimates of SCC. For example, two SCC estimates we have used from Tol (2009) are $66 and $130 (in 2010 US dollars) (Polasky et al. 2010).

* **Price/Metric ton of carbon** (:math:`V` in the equation below): Price given in currency per metric ton of elemental carbon (not CO\ :sub:`2`). For applications interested in estimating the total value of carbon sequestration, we recommend value estimates based on damage costs associated with the release of an additional ton of carbon - the social cost of carbon (SCC). Stern (2007), Tol (2009), and Nordhaus (2007a) present estimates of SCC. For example, two SCC estimates we have used from Tol (2009) are $66 and $130 (in 2010 US dollars) (Polasky et al. 2010).
- :investspec:`carbon discount_rate` This is :math:`r` in equation :eq:`carbon_value`. One default value is 7% per year, which is one of the market discount rates recommended by the U.S. government for cost-benefit evaluation of environmental projects. However, this rate will depend on the country and landscape being evaluated, and should be selected based on local requirements. Philosophical arguments have been made for using a lower discount rate when modeling climate change related dynamics, which users may consider using. If the rate is set equal to 0% then monetary values are not discounted.

* **Market discount in Price of Carbon** (:math:`r` in the equation below): An integer percentage value which reflects society's preference for immediate benefits over future benefits. One default value is 7% per year, which is one of the market discount rates recommended by the U.S. government for cost-benefit evaluation of environmental projects. However, this rate will depend on the country and landscape being evaluated, and should be selected based on local requirements. Philosophical arguments have been made for using a lower discount rate when modeling climate change related dynamics, which users may consider using. If the rate is set equal to 0% then monetary values are not discounted.
- :investspec:`carbon rate_change` This is :math:`c` in equation :eq:`carbon_value`. This adjusts the value of sequestered carbon as the impact of emissions on expected climate change-related damages changes over time.

* **Annual rate of change in the price of carbon** (:math:`c` in the equation below): An integer percentage value which adjusts the value of sequestered carbon as the impact of emissions on expected climate change-related damages changes over time. Setting this rate greater than 0% suggests that the societal value of carbon sequestered in the future is less than the value of carbon sequestered now. It has been widely argued that GHG emissions need to be curtailed immediately to avoid crossing a GHG atmospheric concentration threshold that would lead to a 3 degree Celsius or greater change in global average temperature by 2105. Some argue that such a temperature change would lead to major disruptions in economies across the world (Stern et al. 2006). Therefore, any mitigation in GHG emissions that occurs many years from now may have no effect on whether or not this crucial concentration threshold is passed. If this is the case, C sequestration in the far future would be relatively worthless and a carbon discount rate greater than zero is warranted. Alternatively, setting the annual rate of change less than 0% (e.g., -2%) suggests that the societal value of carbon sequestered in the future is greater than the value of carbon sequestered now (this is a separate issue than the value of money in the future, a dynamic accounted for with the market discount rate). This may be the case if the damages associated with climate change in the future accelerate as the concentration of GHGs in the atmosphere increases.
Setting this rate greater than 0% suggests that the societal value of carbon sequestered in the future is less than the value of carbon sequestered now. It has been widely argued that GHG emissions need to be curtailed immediately to avoid crossing a GHG atmospheric concentration threshold that would lead to a 3 degree Celsius or greater change in global average temperature by 2105. Some argue that such a temperature change would lead to major disruptions in economies across the world (Stern et al. 2006). Therefore, any mitigation in GHG emissions that occurs many years from now may have no effect on whether or not this crucial concentration threshold is passed. If this is the case, C sequestration in the far future would be relatively worthless and a carbon discount rate greater than zero is warranted.

The value of carbon sequestration over time for a given parcel *x* is:
Alternatively, setting the annual rate of change less than 0% (e.g., -2%) suggests that the societal value of carbon sequestered in the future is greater than the value of carbon sequestered now (this is a separate issue than the value of money in the future, a dynamic accounted for with the market discount rate). This may be the case if the damages associated with climate change in the future accelerate as the concentration of GHGs in the atmosphere increases.

.. math:: value\_seq_x=V\frac{sequest_x}{yr\_fut-yr\_cur}\sum^{yr\_fut-yr\_cur-1}_{t=0}\frac{1}{\left(1+\frac{r}{100}\right)^t\left(1+\frac{c}{100}\right)^t}
:label: (cs. 1)

Interpreting Results
--------------------
Expand All @@ -123,9 +146,9 @@ Interpreting Results
* **report_[Suffix].html:** This file presents a summary of all data computed by the model. It also includes descriptions of all other output files produced by the model, so it is a good place to begin exploring and understanding model results. Because this is an HTML file, it can be opened with any web browser.

* **tot_c_cur_[Suffix].tif/tot_c_fut_[Suffix].tif/tot_c_redd_[Suffix].tif**: Rasters showing the amount of carbon stored in Mg in each pixel for the current, future, and REDD scenarios. It is a sum of all of the carbon pools provided by the biophysical table.

* **delta_cur_fut_[Suffix].tif**/**delta_cur_redd_[Suffix].tif**: Rasters showing the difference in carbon stored between the future/REDD landscape and the current landscape. The values are in Mg per pixel. In this map some values may be negative and some positive. Positive values indicate sequestered carbon, negative values indicate carbon that was lost.

* **npv_fut_[Suffix].tif**/**npv_redd_[Suffix].tif**:** Rasters showing the economic value of carbon sequestered between the current and the future/REDD landscape dates. The units are in currency per pixel.

* **[Workspace]\\intermediate_outputs** folder:
Expand All @@ -134,7 +157,7 @@ Interpreting Results
* **c_below_[Suffix].tif**: Raster of belowground carbon values, mapped from the Carbon Pools table to the LULC.
* **c_dead_[Suffix].tif**: Raster of dead carbon values, mapped from the Carbon Pools table to the LULC.
* **c_soil_[Suffix].tif**: Raster of soil carbon values, mapped from the Carbon Pools table to the LULC.
* **_tmp_work_tokens**: This directory stores metadata used iternally to enable avoided re-computation. No model results are stored here.
* **_tmp_work_tokens**: This directory stores metadata used internally to enable avoided re-computation. No model results are stored here.

Appendix: Data Sources
======================
Expand Down
Loading