forked from natcap/invest
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge branch 'main' of https://github.com/natcap/invest into bugfix/1…
…350-una-cryptic-gdal-typeerror Conflicts: HISTORY.rst tests/test_urban_nature_access.py
- Loading branch information
Showing
86 changed files
with
4,553 additions
and
4,128 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,94 @@ | ||
| # ADR-0001: Update the InVEST SDR LS Factor | ||
|
|
||
| Author: James | ||
|
|
||
| Science Lead: Rafa | ||
|
|
||
| ## Context | ||
|
|
||
| Since we released the updated InVEST SDR model in InVEST 3.1.0, we have seen a | ||
| common refrain of users and NatCap science staff noticing that the LS factor | ||
| output of SDR did not produce realistic results and that the LS factor produced | ||
| by SAGA was much more realistic. We have over the years made a couple of notable | ||
| changes to the model and to the LS factor that have altered the output including: | ||
|
|
||
| 1. The SDR model's underlying routing model was changed from d-infinity to MFD in 3.5.0 | ||
| 2. The $x$ parameter was changed in InVEST 3.8.1 from the true on-pixel aspect | ||
| $|\sin \theta|+|\cos \theta|$ (described in Zevenbergen & Thorne 1987 and repeated | ||
| in Desmet & Govers 1996) to the weighted mean of proportional flow from the | ||
| current pixel to its neighbors. | ||
| 3. A typo in a constant value in the LS factor was corrected in InVEST 3.9.1 | ||
| 4. An `l_max` parameter was exposed to the user in InVEST 3.9.1 | ||
|
|
||
| Despite these changes to the LS factor, we still received occasional reports | ||
| describing unrealistic LS factor outputs from SDR and that SAGA's LS factor | ||
| was much more realistic. | ||
|
|
||
| After diving into the SAGA source code, it turns out that there are several | ||
| important differences between the two despite both using Desmet & Govers (1996) | ||
| for their LS factor equations: | ||
|
|
||
| 1. The contributing area $A_{i,j-in}$ is not strictly defined in Desmet & | ||
| Govers (1996), it is only referred to as "the contributing area at the inlet | ||
| of a grid cell with coordinates (i, j) (m^2)". | ||
| InVEST assumes that "contributing area" is $area_{pixel} \cdot n\\_upstream\\_pixels$. | ||
| SAGA refers to this as "specific catchment area" and allows the user to choose their | ||
| specific catchment area equation, where the available options are | ||
| "contour length simply as cell size", "contour length dependent on aspect", "square | ||
| root of catchment area" and "effective flow length". | ||
| 2. SAGA uses on-pixel aspect, $|\sin \theta|+|\cos \theta|$, and does not consider | ||
| flow direction derived from a routing model when calculating the LS factor. | ||
| 3. The length exponent $m$ differs between the implementations. In SAGA, | ||
| $m = \beta / (1 + \beta)$. In InVEST, we have a discontinuous function where | ||
| $m$ is dependent on the slope of the current pixel and described as "classical USLE" | ||
| in the user's guide and discussed in Oliveira et al (2013). | ||
| 4. SAGA's flow accumulation function [`Get_Flow()`](https://github.com/saga-gis/saga-gis/blob/master/saga-gis/src/tools/terrain_analysis/ta_hydrology/Erosion_LS_Fields.cpp#L394) | ||
| only considers a pixel downstream if and only if its elevation is strictly less | ||
| than the current pixel's elevation, which implies that flow accumulation will | ||
| not navigate plateaus. InVEST's flow accumulation handles plateaus well, | ||
| which can lead to longer flow accumulation values on the same DEM. | ||
| 5. SAGA's flow accumulation function `Get_Flow()` uses D8, InVEST's flow | ||
| accumulation uses MFD. | ||
|
|
||
| It is important to note that when evaluating differences between the SAGA and InVEST | ||
| LS Factor implementations, it is _critical_ to use a hydrologically conditioned DEM such | ||
| as conditioned by Wang & Liu so that we control for differences in output due | ||
| to the presence of plateaus. | ||
|
|
||
| Once we finally understood these discrepancies, James implemented several of the | ||
| contributing area functions available in SAGA to see what might be most comparable | ||
| to the real world. Source code and a docker container for these experiments are | ||
| available at | ||
| https://github.com/phargogh/invest-ls-factor-vs-saga/blob/main/src/natcap/invest/sdr/sdr.py#L901. | ||
| Some additional discussion and notes can be viewed in the related github issue: | ||
| https://github.com/natcap/invest/issues/915. | ||
|
|
||
| ## Decision | ||
|
|
||
| After inspecting the results, Rafa decided that we should make these changes to | ||
| the LS Factor calculation: | ||
|
|
||
| 1. We will revert to using the on-pixel aspect, $|\sin \theta|+|\cos \theta|$. | ||
| This is in line with the published literature. | ||
| 2. We will convert the "contributing area" portion of the LS Factor to be | ||
| $\sqrt{ n\\_upstream\\_pixels \cdot area\_{pixel} }$. Rafa's opinion on this | ||
| is that the LS factor equations were designed for a 1-dimensional situation, | ||
| so our specific catchment area number should reflect this. | ||
|
|
||
| ## Status | ||
|
|
||
| ## Consequences | ||
|
|
||
| Once implemented and released, the LS factor outputs of SDR will be | ||
| significantly different, but they should more closely match reality. | ||
|
|
||
| We hope that there will be fewer support requests about this once the change is | ||
| released. | ||
|
|
||
| ## References | ||
|
|
||
| Zevenbergen & Thorne (1987): https://searchworks.stanford.edu/articles/edb__89861226 | ||
|
|
||
| Desmet & Govers (1996): https://searchworks.stanford.edu/articles/edsgac__edsgac.A18832564 | ||
|
|
||
| Oliveira et al (2013): http://dx.doi.org/10.5772/54439 |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,12 @@ | ||
| # Architecture/Any Decision Records | ||
|
|
||
| An ADR is a way to track decisions and their rationale in a way that is tied to | ||
| the source code, easy to digest, and written in a way that future us will | ||
| understand. An ADR consists of several sections: | ||
|
|
||
| 1. The title and ADR number (for easier sorting) | ||
| 2. Context about the problem | ||
| 3. The decision that was made and why | ||
| 4. The status of implementation | ||
| 5. Consequences of the implementation | ||
| 6. Any references (especially if describing a science/software issue) |
Oops, something went wrong.