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

Makefile

@@ -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"

requirements.txt

@@ -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

source/carbonstorage.rst

@@ -42,6 +42,12 @@ 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{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: carbon_value
+
+
 REDD Scenario Analysis
 ----------------------
 
@@ -71,17 +77,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.
+
+.. note:: All carbon data should be for elemental carbon, not CO\ :sub:`2`.
+
+- :investspec:`carbon lulc_cur_path`
+
+- :investspec:`carbon lulc_cur_year`
 
-- **Current Landcover Calendar Year** (required for sequestration): The year depicted by the Current LULC map, for use in economic valuation.
+- :investspec:`carbon calc_sequestration`
 
-- **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_fut_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_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.
 
  *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.
 
@@ -95,24 +109,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.
+- :investspec:`carbon do_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 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).
 
-- **Economic data** (required for valuation):
+- :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.
 
-	* **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 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.
 
-	* **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. 
+  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.
 
-	* **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. 
+  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.
 
- The value of carbon sequestration over time for a given parcel *x* is:
-
- .. 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
 --------------------
@@ -123,9 +132,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:
@@ -134,7 +143,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
 ======================