Updates to communicate new raster output units (InVEST #1270) #158

emilyanndavis · 2025-02-08T01:09:38Z

Updates the following User Guide pages:

Carbon
Crop Production
Forest Carbon
NDR
SDR

to reflect the changes made in InVEST PR #1717 (see also InVEST #1270).

…ure/1270-per-hectare-outputs

emilyanndavis · 2025-02-12T18:10:37Z

source/en/carbon_edge.rst

-Stouffer, P., Gascon, C., Bierregaard, R., Laurance, S., Sampaio, E.,
-2002. Ecosystem decay of Amazonian forest fragments: a 22-year
+Stouffer, P., Gascon, C., Bierregaard, R., Laurance, S., Sampaio, E., 2002.
+Ecosystem decay of Amazonian forest fragments: a 22-year
 investigation. Conservation Biology 16, 605–618.


In a previous commit, 2002. was somehow converted to 1. in my code editor. My theory is, the line beginning with 2002. was interpreted as a list item, so I moved 2002. to the end of the previous line to prevent this from happening in the future.

… into feature/1270-per-hectare-outputs

emilyanndavis · 2025-02-18T18:15:09Z

source/en/carbon_edge.rst

-      summarizes the total carbon (column *c_sum*) and mean carbon per
-      ha (column *c_ha_mean*) in the area polygons defined. Values are
-      in Mg.
+-  **Parameter log**. Each time the model is run, a text (.txt) file will appear in the *Workspace*. The file will list the parameter values for that run and will be named according to the service, the date and time. When contacting NatCap about errors in a model run, please include the parameter log.


No substantive changes to this paragraph, only formatting.

emilyanndavis · 2025-02-18T18:16:57Z

source/en/carbon_edge.rst

-      in Mg.
+-  **Parameter log**. Each time the model is run, a text (.txt) file will appear in the *Workspace*. The file will list the parameter values for that run and will be named according to the service, the date and time. When contacting NatCap about errors in a model run, please include the parameter log.
+
+-  **carbon_map_[Suffix].tif**. A map of carbon stock, with the amount in forest derived from the regression based on distance to forest edge, and the amount in non-forest classes according to the biophysical table. Units are metric tons per hectare (Mg/ha).


Removed "per pixel" and removed the note about how values change with pixel size (no longer relevant since values are no longer per pixel).

emilyanndavis · 2025-02-18T18:17:43Z

source/en/carbon_edge.rst

+
+-  **carbon_map_[Suffix].tif**. A map of carbon stock, with the amount in forest derived from the regression based on distance to forest edge, and the amount in non-forest classes according to the biophysical table. Units are metric tons per hectare (Mg/ha).
+
+-  **aggregated_carbon_stocks_[Suffix].shp**: If service areas of interest are provided by the user, this output shapefile summarizes the total carbon (column *c_sum*) and mean carbon per ha (column *c_ha_mean*) in the area polygons defined. Values are in metric tons (Mg).


Changed "Mg" to "metric tons (Mg)", for clarity.

jagoldstein

I suggested some changes, the most frequent and relevant being replacing Mg with t.

I'm less confident about formatting when listing units of measure, but I was going for some consistency with the "Data Needs" sections. Of course, these aren't consistent across model chapters, but it would be great if they were!

source/en/carbon_edge.rst

jagoldstein · 2025-02-18T20:20:03Z

source/en/carbon_edge.rst

-      in Mg.
+-  **Parameter log**. Each time the model is run, a text (.txt) file will appear in the *Workspace*. The file will list the parameter values for that run and will be named according to the service, the date and time. When contacting NatCap about errors in a model run, please include the parameter log.
+
+-  **carbon_map_[Suffix].tif**. A map of carbon stock, with the amount in forest derived from the regression based on distance to forest edge, and the amount in non-forest classes according to the biophysical table. Units are metric tons per hectare (Mg/ha).


Suggested change

- **carbon_map_[Suffix].tif**. A map of carbon stock, with the amount in forest derived from the regression based on distance to forest edge, and the amount in non-forest classes according to the biophysical table. Units are metric tons per hectare (Mg/ha).

- **carbon_map_[Suffix].tif**. A map of carbon stock, with the amount in forest derived from the regression based on distance to forest edge, and the amount in non-forest classes according to the biophysical table. Units are metric tons per hectare (t/ha).

Mg notation should be removed all together and replaced with t as "megagrams" are being replaced with "tons". Listing "Mg" as the abbreviation for "metric tons" would likely only add to users' confusion.

source/en/carbon_edge.rst

source/en/sdr.rst

jagoldstein · 2025-02-18T20:37:35Z

source/en/sdr.rst


-        * **avoid_eros** (units: tons/watershed/year): The sum of avoided local erosion in the watershed (Sum of :math:`AER_i` from :eq:`aer_i` over the watershed area)
+        * **avoid_eros** (units: metric tons/watershed/year): The sum of avoided local erosion in the watershed (Sum of :math:`AER_i` from :eq:`aer_i` over the watershed area)


Suggested change

* **avoid_eros** (units: metric tons/watershed/year): The sum of avoided local erosion in the watershed (Sum of :math:`AER_i` from :eq:`aer_i` over the watershed area)

* **avoid_eros** (units: t/(watershed*year)): The sum of avoided local erosion in the watershed (Sum of :math:`AER_i` from :eq:`aer_i` over the watershed area)

My usual inclination is to spell things out as much as possible, and consistently. So personally I'd be more in favor of "metric tons/(watershed*year)" (or "metric tons/watershed/year", which reads a little more clearly to me, but let's pick one way of writing it and do it consistently throughout the UG). If I was a beginner with the models, I'm not sure I'd know what "t" stands for.

jagoldstein · 2025-02-18T20:37:53Z

source/en/sdr.rst


-        * **sed_dep** (units: tons/watershed/year): Total amount of sediment deposited on the landscape in each watershed, which does not enter the stream. (Sum of :math:`T_i` from :eq:`ti` over the watershed area)
+        * **sed_dep** (units: metric tons/watershed/year): Total amount of sediment deposited on the landscape in each watershed, which does not enter the stream. (Sum of :math:`T_i` from :eq:`ti` over the watershed area)


Suggested change

* **sed_dep** (units: metric tons/watershed/year): Total amount of sediment deposited on the landscape in each watershed, which does not enter the stream. (Sum of :math:`T_i` from :eq:`ti` over the watershed area)

* **sed_dep** (units: t/(watershed*year)): Total amount of sediment deposited on the landscape in each watershed, which does not enter the stream. (Sum of :math:`T_i` from :eq:`ti` over the watershed area)

My usual inclination is to spell things out as much as possible, and consistently. So personally I'd be more in favor of "metric tons/(watershed*year)" (or "metric tons/watershed/year", which reads a little more clearly to me, but let's pick one way of writing it and do it consistently throughout the UG). If I was a beginner with the models, I'm not sure I'd know what "t" stands for.

jagoldstein · 2025-02-18T20:38:15Z

source/en/sdr.rst

@@ -507,9 +507,9 @@ Interpreting Results

    * **d_up.tif**: upslope factor of the index of connectivity (Eq. :eq:`d_up`)

-    * **e_prime.tif**: sediment downslope deposition, the amount of sediment from a given pixel that does not reach a stream (Eq. :eq:`eprime`)
+    * **e_prime.tif**: sediment downslope deposition, the amount of sediment from a given pixel that does not reach a stream (Eq. :eq:`eprime`). Units: metric tons/hectare/year.


Suggested change

* **e_prime.tif**: sediment downslope deposition, the amount of sediment from a given pixel that does not reach a stream (Eq. :eq:`eprime`). Units: metric tons/hectare/year.

* **e_prime.tif**: sediment downslope deposition, the amount of sediment from a given pixel that does not reach a stream (Eq. :eq:`eprime`). Units: t/(ha*year).

My usual inclination is to spell things out as much as possible, and consistently. So personally I'd be more in favor of "metric tons/(hectare*year)" (or "metric tons/hectare/year", which reads a little more clearly to me, but let's pick one way of writing it and do it consistently throughout the UG). If I was a beginner with the models, I'm not sure I'd know what "t" stands for.

I am convinced and concur with Stacie that it's best to spell out to remove any doubt.

source/en/sdr.rst

…and update punctuation & wording where needed Co-authored-by: Jesse Goldstein <[email protected]>

jagoldstein

These updates make sense to me. AFAICT they accurately describe the updated models that will produce per hectare raster results, no longer per pixel.

newtpatrol

Looks great to me! If any confusion arises with public users, we can always make changes later.

emilyanndavis added 7 commits February 6, 2025 15:08

Carbon: update output units (InVEST #1270)

3e53fab

Merge branch 'main' of github.com:natcap/invest.users-guide into feat…

73392db

…ure/1270-per-hectare-outputs

Forest Carbon: update output units (InVEST #1270)

a56aac6

Crop Production: update output units (InVEST #1270)

41df393

NDR: update output units (InVEST #1270)

31af80d

SDR: update output units & unit conversion guidance (InVEST #1270)

72e0962

Crop Production: update tons to metric tons, for clarity (InVEST #1270)

3f4c1bc

emilyanndavis mentioned this pull request Feb 11, 2025

Convert per-pixel values to per-hectare values in raster outputs of multiple models natcap/invest#1717

Merged

9 tasks

Revert unwanted change to references list

1a68ba7

emilyanndavis commented Feb 12, 2025

View reviewed changes

Merge branch 'release/3.15.0' of github.com:natcap/invest.users-guide…

ded5d45

… into feature/1270-per-hectare-outputs

emilyanndavis commented Feb 18, 2025

View reviewed changes

jagoldstein requested review from jagoldstein and newtpatrol February 18, 2025 19:11

jagoldstein requested changes Feb 18, 2025

View reviewed changes

Add/modify abbreviations for clarity, spell out units where helpful, …

7601b02

…and update punctuation & wording where needed Co-authored-by: Jesse Goldstein <[email protected]>

emilyanndavis requested a review from jagoldstein February 20, 2025 19:29

jagoldstein approved these changes Feb 20, 2025

View reviewed changes

newtpatrol approved these changes Feb 21, 2025

View reviewed changes

emilyanndavis merged commit 27c1eb9 into natcap:release/3.15.0 Feb 21, 2025
1 check passed

emilyanndavis deleted the feature/1270-per-hectare-outputs branch February 21, 2025 16:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Updates to communicate new raster output units (InVEST #1270) #158

Updates to communicate new raster output units (InVEST #1270) #158

emilyanndavis commented Feb 8, 2025 •

edited

Loading

emilyanndavis Feb 12, 2025

emilyanndavis Feb 18, 2025

emilyanndavis Feb 18, 2025

emilyanndavis Feb 18, 2025

jagoldstein left a comment

jagoldstein Feb 18, 2025

jagoldstein Feb 18, 2025

newtpatrol Feb 19, 2025

jagoldstein Feb 18, 2025

newtpatrol Feb 19, 2025

jagoldstein Feb 18, 2025

newtpatrol Feb 19, 2025

jagoldstein Feb 19, 2025

jagoldstein left a comment

newtpatrol left a comment


		- carbon_map_[Suffix].tif. A map of carbon stock, with the amount in forest derived from the regression based on distance to forest edge, and the amount in non-forest classes according to the biophysical table. Units are metric tons per hectare (Mg/ha).

		- aggregated_carbon_stocks_[Suffix].shp: If service areas of interest are provided by the user, this output shapefile summarizes the total carbon (column c_sum) and mean carbon per ha (column c_ha_mean) in the area polygons defined. Values are in metric tons (Mg).


		* avoid_eros (units: tons/watershed/year): The sum of avoided local erosion in the watershed (Sum of :math:`AER_i` from :eq:`aer_i` over the watershed area)
		* avoid_eros (units: metric tons/watershed/year): The sum of avoided local erosion in the watershed (Sum of :math:`AER_i` from :eq:`aer_i` over the watershed area)

	* avoid_eros (units: metric tons/watershed/year): The sum of avoided local erosion in the watershed (Sum of :math:`AER_i` from :eq:`aer_i` over the watershed area)
	* avoid_eros (units: t/(watershed*year)): The sum of avoided local erosion in the watershed (Sum of :math:`AER_i` from :eq:`aer_i` over the watershed area)


		* sed_dep (units: tons/watershed/year): Total amount of sediment deposited on the landscape in each watershed, which does not enter the stream. (Sum of :math:`T_i` from :eq:`ti` over the watershed area)
		* sed_dep (units: metric tons/watershed/year): Total amount of sediment deposited on the landscape in each watershed, which does not enter the stream. (Sum of :math:`T_i` from :eq:`ti` over the watershed area)

	* sed_dep (units: metric tons/watershed/year): Total amount of sediment deposited on the landscape in each watershed, which does not enter the stream. (Sum of :math:`T_i` from :eq:`ti` over the watershed area)
	* sed_dep (units: t/(watershed*year)): Total amount of sediment deposited on the landscape in each watershed, which does not enter the stream. (Sum of :math:`T_i` from :eq:`ti` over the watershed area)

	* e_prime.tif: sediment downslope deposition, the amount of sediment from a given pixel that does not reach a stream (Eq. :eq:`eprime`). Units: metric tons/hectare/year.
	* e_prime.tif: sediment downslope deposition, the amount of sediment from a given pixel that does not reach a stream (Eq. :eq:`eprime`). Units: t/(ha*year).

Updates to communicate new raster output units (InVEST #1270) #158

Updates to communicate new raster output units (InVEST #1270) #158

Conversation

emilyanndavis commented Feb 8, 2025 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jagoldstein left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jagoldstein left a comment

Choose a reason for hiding this comment

newtpatrol left a comment

Choose a reason for hiding this comment

emilyanndavis commented Feb 8, 2025 •

edited

Loading