diff --git a/README.md b/README.md index 5db9ec7..9f13dc9 100644 --- a/README.md +++ b/README.md @@ -1,15 +1,21 @@ # PEPs: Platform Enhancement Proposals The archive of Enhancement Proposals for the Natural Capital Project's Science -& Technology Platform. +& Technology Platform. [Original PEP documents are typically drafted as +Google Docs and can be found here](https://drive.google.com/drive/u/1/folders/1vM8NZEs8vsENKnTxVqzqc0bzmHeMWL85) ## PEP index Format is: `[pep file name] - [Short human description] - [Complete | In Progress | Accepted | Rejected]` -- **[pep-0013](https://github.com/natcap/peps/blob/main/pep-0013.md)** - Add an InVEST Mental Health Model - In Progress -- **[pep-0012](https://github.com/natcap/peps/blob/main/pep-0012.md)** - Supporting both D8 and MFD algorithms in InVEST routed models and tools - Complete -- **[pep-0011](https://github.com/natcap/peps/blob/main/pep-0011.md)** - Deprecate the GLOBIO model - Complete -- **[pep-0010](https://github.com/natcap/peps/blob/main/pep-0010.md)** - Revising SDR Indicators - Complete +- **[pep-0010](https://github.com/natcap/peps/blob/main/pep-0010.md)** - Add an InVEST Stormwater Retention Model - Complete +- **[pep-0011](https://github.com/natcap/peps/blob/main/pep-0011.md)** - Translating the InVEST UI - Complete +- **[pep-0012](https://github.com/natcap/peps/blob/main/pep-0012.md)** - Add an InVEST Urban Nature Access Model - Complete +- **[pep-0013](https://github.com/natcap/peps/blob/main/pep-0013.md)** - Revising SDR Indicators - Complete +- **[pep-0014](https://github.com/natcap/peps/blob/main/pep-0014.md)** - Deprecate the Fisheries models - Complete +- **[pep-0015](https://github.com/natcap/peps/blob/main/pep-0015.md)** - Deprecate the GLOBIO model - Complete +- **[pep-0016](https://github.com/natcap/peps/blob/main/pep-0016.md)** - Supporting both D8 and MFD algorithms in InVEST routed models and tools - Complete +- **[pep-0017](https://github.com/natcap/peps/blob/main/pep-0017.md)** - Add Urban Cooling Model Calibration - Rejected` +- **[pep-0018](https://github.com/natcap/peps/blob/main/pep-0018.md)** - Add an InVEST Mental Health Model - Complete` ## Steps for archiving Google Doc PEPs 1) Download google doc as docx diff --git a/pep-0010.md b/pep-0010.md index 170d525..382d9f5 100644 --- a/pep-0010.md +++ b/pep-0010.md @@ -1,244 +1,138 @@ -# Revising SDR Indicators - -Contacts: -* Primary: Rafa -* Contributors: Lisa, Adrian, Hector, Jesse, James, Stacie, Rafa, Doug, Emily - -## Abstract - -The SDR model is one of the most widely applied InVEST models (Mandle and -Natural Capital Project, 2021). Yet, it comes with a number of -assumptions and creates a number of output indicators that are deprecated, -poorly documented, and do not meet the current needs. This has also -led to a rising number of user forum inquiries about the -functioning of the model and how to interpret the resulting -indicators. This PEP results from an in-depth review of model -assumptions done by a group of expert NatCap users, scientists, and -software engineers, and aims at streamlining the SDR model by (1) -revising some indicators to reflect the conceptual understanding of the -science team about model processes, based on the current -state-of-science and (2) reducing the number of indicators to those -which are most useful to current users. - -## Motivation - -Two of the most widely appreciated benefits of sediment retention by vegetation -are 1) improved water quality from avoided sediment export from hillslopes to -waterways, and 2) maintenance of soil fertility from avoided topsoil erosion. -The current SDR model lacks indicators that clearly and comprehensively -represent these services, despite the demand for such indicators both in NatCap -applications and from users on our forum. This PEP would introduce two new -sediment retention indicators that more comprehensively capture the ecosystem -service being provided, one from the perspective of water quality and one from -the perspective of soil fertility. In the case of sediment retention for water -quality, we propose an indicator for sediment retention services for water -quality that captures the ability of vegetation to both keep sediment from -eroding and to trap sediment originating upslope. We also propose dropping -several current model outputs that do not address the service as directly and -are either (1) deprecated (were kept in the model at some point to ensure -backward compatibility), or (2) could be calculated by users -with a scenario approach (e.g., ask the user to run a “bare-soil” scenario, -rather than having it predetermined/fixed in the code), or (3) -do not fully represent what the PEP authors agreed that they should be -representing. These could still be calculated if desired from -intermediate outputs or by running an additional scenario. - -This proposal would additionally alter the current calculation of the -deposition and flux indicators that track trapping of sediment that -erodes onto a pixel in order to make them more consistent with the -conceptual processes the SDR model represents. Beyond those code -updates, this PEP would also update the User Guide to harmonize -terminology and improve clarity for users (including some new -visualizations and description of use cases). - -We thus propose that these revisions of SDR are better tackled through -a PEP (and joint effort of the science team), rather than a piece-meal -approach to solving individual problems with indicators and the User -Guide in response to user/staff requests. - - -The revised SDR model seems to be highly aligned with the general PEP -guidelines: - -* Actionable: The SDR model has been shown to be relevant to many different - stakeholders, decision problems, and scales -* Generalizable: The tool has been run from hyper-local case studies to global - scales -* Innovation: The revised model will produce new indicators which, based on our - own experiences and questions received on the User Forum, will be very useful - for decision support (e.g., Retention indicator) and that a normal user could - not easily calculate. The new indicators will further respond to issues that - have been repeatedly raised in the User Forum. -* Credibility: - * The proposed changes have been vetted by the science and software team, and - seem to be more aligned with the model's intention (e.g., as described in - the User Guide). - * Similar to current SDR, the revised indicators we propose are mostly - conceptual and hard to validate. Yet, the revised indicators are more aligned - with the intention of what is described in the User Guide, avoid violating - sediment mass balances (e.g. that more sediment is retained than what is - eroded) and allow users to track sediment mass balance through the model in - a way that was not possible before. -* Generalizability: as per above, the model has been shown to be useful in many - settings and decision contexts. -* Feasibility: Calculation of all indicators will be possible within the - existing model framework ([James has already implemented these changes in a - fork of InVEST](https://github.com/natcap/invest/compare/main...phargogh:task/sdr-retreat-2022-03-22-rework-downslope-deposition-equations)). - -Additional criteria that might be relevant - -* Demonstrated interest: There are many threads on the forum where users ask - for clarification regarding existing indicators -* Novelty: The proposed changes will make the model more consistent compared to - what we have and will produce indicators that are otherwise hard to obtain by - users from “raw” SDR outputs. -* Maintenance: The models will be maintained as part of InVEST, just like - previous versions of SDR. Usability: SDR has been proven to be usable across - scales, geographies, and decision making contexts. - -## Support - -No additional support is needed beyond what is done for InVEST. Some additional -help might be required for forum users inquiring about changes, although we -expect this to be offset by the reduction in time required to respond to forum -posts asking for clarification on the current set of model outputs/indicators. - -## Specification - -This PEP proposes the following changes, which we outline here and specify in -more detail below: - -1. **Update the calculation of intermediate parameters R (deposition) and F (flux).** - Currently R and F are calculated such that sediment that erodes from a pixel - (as calculated by the Revised Universal Soil Loss Equation or RUSLE) can - then be trapped by vegetation on that same pixel. This is conceptually - inconsistent: the role of vegetation for reducing erosion and sediment - runoff from a pixel is already captured in RUSLE’s C factor (Wischmeier and - Smith, 1978). By allowing for immediate sediment trapping on - the same pixel, this amounts to double-counting the role of vegetation. We - propose updating the calculation so that all sediment that erodes from a - pixel goes to the next downslope pixel in proportion to the proportion of - water flowing into the next downslope pixel, where it can either be trapped - or continue flowing downslope. This change will not affect estimates of - water quality for any given scenario relative to the current formulation of - the model; it will lead to some change in the attribution of where sediment - retention services are being provided on the landscape. Rename the - indicator “R” (which is also used in the USLE equation) to “T” for “trapped - sediment”, or “trapping”. -2. **Create a new output and indicator for sediment retention services for - water quality called "Avoided Export".** - The raster output represents vegetation’s contribution to both avoided - erosion from a pixel and trapping of sediments originating on upslope - pixels, e.g., the service of a pixel from the perspective of downstream - water user. -3. **Create a new output and indicator for sediment retention services for soil - fertility called "Avoided Erosion".** - This raster output represents avoided erosion benefits to that pixel, e.g., - from the perspective of maintaining soil fertility. -4. **Drop 2 legacy sediment retention indices currently included in the model.** - One of the frequently asked questions on the User Forum is what metric - people should use for the sediment retention “service”, and we have not - historically had a solid answer, because neither of the “retention” outputs - are very useful. They are indices only (not quantities), compared against a - hypothetical entirely barren landscape (which is unrealistic), and one of - the indices has no explanation at all given in the User Guide, so no current - NatCapper actually knows what it means. Removing these, and adding clear - guidance about calculating retention to the User Guide (see #5) would - significantly reduce confusion. -5. **Updates to the User's Guide** - to reflect the above changes, harmonize terminology and variable names and - provide a conceptual figure for visualizing the modeling steps and related - outputs. We will also more clearly explain what’s happening in the different - modeling steps and present options and use cases for quantifying the - retention “service” from model outputs, informed by common questions on the - User Forum. - -The required technical changes to address those 5 points are detailed below: - -1. **Update the calculation of the intermediate parameters R (deposition) and F (flux).** - * Update the $R$ (deposition) calculation so that it does not include export - from pixel i. Basically removing the $E_i’$ from the equation below so that a - pixel cannot retain the sediment that erodes directly from itself (note: - equation numbers are matched to the User Guide). Thus from - - $$ R_i = dR_i \cdot \left(\sum_{j \in {pixels\ that\ drain\ to\ i}}F_j \cdot p(i,j)\right) + E_i' $$ - - Revise to - - $$ R_i = dR_i \cdot \left(\sum_{j \in {pixels\ that\ drain\ to\ i}}F_j \cdot p(i,j)\right) $$ - - Rename the indicator from “R” (which is used in the USLE equation) to “T” - for “trapped sediment”, or “trapping”. - - * Update $F$ (flux) calculation so that all export/erosion originating from - that pixel goes on to the next downslope pixel or pixels (rather than just - a fraction). Thus from - - $$ F_i = (1 - dR_i) \cdot \left(\sum_{j \in {pixels\ that\ drain\ to\ i}}F_j \cdot p(i,j)\right) + E_i' $$ - - Revise to - - $$ F_i = (1 - dR_i) \cdot \left(\sum_{j \in {pixels\ that\ drain\ to\ i}}F_j \cdot p(i,j)\right) $$ - - In addition, we would rename variable $R$ (deposition) to $T$ (for - sediment trapping), to avoid confusion with the $R$ variable - name already used previously in the calculation of the $RUSLE$, and update - variable names in the User Guide for consistency and clarity. -2. **Create new ecosystem service indicator output (raster) called “ Avoided Export”** - representing vegetation’s contribution to avoided erosion from a pixel and - trapping of sediments originating upslope (the service from the perspective - of a water user): - - $$ TR_i = (RKLS_i - USLE_i) \cdot SDR_ + R_i $$ - - Where: - * $TR_i$ is Total Retention - * $RKLS$ is basically $USLE_i$ minus the $C$ and $P$ - factors which represent the benefits of vegetation and good management - practices. - - The watershed-level outputs of the model would also be updated to include - this indicator as follows: remove "sed_retent" and add the sum of "Total - Retention" per polygon and the sum of "Local Erosion Control" per polygon. -3. **Create new ecosystem service indicator output (raster) called “Avoided Erosion”** - representing avoided erosion benefits to that pixel, from the perspective of - soil loss: - - $$ AE_i = RKLS_i - USLE_i $$ - - note (in the User Guide) that $R_i$ ($T_i$ in the new nomenclature) - could be added separately if trapping of sediment originating upslope could - mitigate erosion on a downslope pixel (e.g., if high quality soil is eroded - from upslope) -4. **Drop 2 legacy sediment retention indices currently included in the model** - Described in the section "Legacy" in the user's guide. -5. **Updates to User Guide (can happen separately from the code changes requested above):** - * Update the User Guide to reflect changes in equations 78 and 79 (and - associated, more explanatory, text) - * Add use cases to the User Guide for applying different outputs - * Add a figure showing conceptually what the different variables in the - model are and how they relate to a toy landscape and which variables - are output as the retention indicators given above. - - ![The fate of sediment](pep-0010/fate-of-sediment.png "The fate of sediment") - -## Open Issues - -There is an additional issue with the LS factor, which James will address -separately. The current LS factor values are very high compared to what is -obtained from other software, e.g., SAGA. The SAGA LS factor also results in -more realistic results when compared to sediment observations. - -## References -Mandle, Lisa and Natural Capital Project. (2021). Database of publications -using InVEST and other Natural Capital Project software. Stanford Digital -Repository. Available at: https://purl.stanford.edu/bb284rg5424 - -Wischmeier, W. H., & Smith, D. D. (1978). Predicting rainfall erosion losses - -a guide to conservation planning. Predicting Rainfall Erosion Losses. United -States Department of Agriculture. - - - - - +This PEP has been exported to MarkDown from the original PEP [Google +Doc](https://docs.google.com/document/d/1IwFJCvI9wjQX_st5zUU5j5tnLwyhsCzylCPpJNmN-VA/edit?tab=t.0), +and is stored as a [word document in this +repo](./pep-0010/Stormwater_Retention_PEP_for_public_comment.docx) + +Version 0.2 approved by PSC on Oct. 30, 2020 + +Platform Enhancement Proposal (PEP) Template 0.2 + +See the PEP guidelines +[here](https://docs.google.com/document/d/1GOZKXsNfP7PHTjhKRgzx6bmcJHwOloyrSDvkOfx7fhk/edit?usp=sharing) +for the criteria by which PEPs will be evaluated. + +**Contacts:** + +Model designer: Perrine Hamel (perrine.hamel@ntu.edu.sg), Ben Janke +(janke024@umn.edu) + +Urban team: Eric Lonsdorf, Anne Guerry, Chris Nootenboom + +# Abstract + +**This proposal is for a new model, “Stormwater Retention”**, which +provides for the analysis of annual scale retention of stormwater volume +and associated pollutants (or nutrients) in stormwater runoff, with +particular applicability to urban landscapes. We would like it to be +added to InVEST as one of the new Urban components. The model is +complete, and already available as a stand-alone module on the Joint +Test Platform (JTP) created by the Chinese Academy of Science, but +integration into InVEST is needed to be a fully featured InVEST model +(e.g. broader audience, ability to run in batch mode for multiple +cities, etc.). The model has been tested against observations in several +Twin Cities, MN watersheds, and a design doc is complete. + +# Motivation + +This model has been in development for a couple years, with the goal of developing a model that could predict ecosystem services in cities of annual scale retention of stormwater and associated pollutants (nutrients in particular), and potential groundwater recharge. It is intended to fill a gap in the current collection of runoff models in InVEST: + +1. *Seasonal Water Yield*, which was developed primarily for non-urban watersheds, has a parameterization that is focused on partitioning rainfall into surface runoff and quickflow (sub-surface runoff), which is difficult to predict in urban watersheds with so much infrastructure below ground; + +2. *Nutrient Delivery Ratio*, whose parameters (retention length and nutrient inputs in particular) can be difficult to determine in highly heterogeneous urban landscapes, as UMN’s Nat Cap team encountered in work with the US Golf Association; + +3. *Urban Flood Mitigation*, which is focused on single or extreme events rather than annual-scale retention of urban runoff. + +Similar to the *Urban Flood Mitigation* model, it was also desired to: (1) have a single model for prediction of important urban ecosystem services (stormwater retention, potential groundwater recharge), rather than having to combine two models that were a potentially poor fit to urban landscapes (SWY and NDR) (*criteria: novelty*), and (2) leverage commonly available water quality and GIS data, allowing the model to capture the effects of at least some of the unique features of urban landscapes (paved areas in particular) (*criteria: usability*). + +# Novelty and Usability + +To these ends, the Stormwater Retention model +uses land cover and hydrologic soil group as the primary inputs, with a +biophysical table assigning runoff coefficients (volume of runoff +normalized by volume of rainfall) and pollutant concentrations as a +function of land cover and/or hydrologic soil group. It includes an +option to use street centerlines as a proxy for storm drain locations, +serving to increase the runoff coefficients (reducing retention) for +land cover cells in proximity to roadways, which “short circuit” flow +paths in urban watersheds due to direct connection to drainage systems. +Runoff coefficients and pollutant concentrations are typically available +from literature and databases such as the International BMP Database, or +may be available for some cities from their own data collection. We +provide guidance in the [design +document](https://drive.google.com/file/d/1rXM49wxmb2g0foo-W2Md27AyalYFVD6_/view?usp=sharing) +(see “Specification” section) for determining runoff coefficients from a +simple SWMM model using a city’s local climate data, in the absence of +literature values. + +# Demonstrated Interest + +There has been and will be high demand for the +Stormwater Retention model within several scopes of work. The initial +tool was refined (and to some degree tested) within our own project with +the US Golf Association, in which we have applied the model along with +several other InVEST models to seven cities in the U.S. Several CAS +collaborators have expressed interest in using the model, and Perrine +Hamel, the original author of the model, intends to use it in her work +at Nanyang Technological University in Singapore (through JTP, or +preferably through InVEST). Model results have also been presented to +various groups in workshops and scientific meetings. + +Finally, while a version of the model exists in CAS’s JTP framework, it +was never intended to be a permanent home for the model. Fixing bugs is +difficult with software engineers located in China, and the +implementation has been buggy (though functional). It is also not +possible to run in a batch script or to do scenario building within the +JTP framework, so broad applicability of the JTP version is limited. + +# Credibility + +The model has been tested in the Twin Cities (MN) through +application to roughly 12 gauged urban and peri-urban watersheds with +observations of discharge and water quality (nitrogen and phosphorus +loads). While not a rigorous test of the model, it did perform +reasonably well in its default use case against observations. These +results are currently being worked into a paper describing the model. + +# Support + +The model should not require much long-term support beyond what is +needed for most models, i.e. its inputs will not need to be updated year +to year, for example. It will need a new entry in the InVEST user’s +manual, and a sample data set could be provided from examples that have +already been completed. In the absence of locally-available runoff +coefficients needed for the model, we have suggested using SWMM to +develop coefficients and have described this process in our design +document; an example could be provided from our own use cases. Some +training materials currently exist for the model, which have been used +in several training workshops, so additional development of materials +should not be needed. + +# Specification + +The design document for this model can be found [here (version for +public +comment)](https://drive.google.com/file/d/1rXM49wxmb2g0foo-W2Md27AyalYFVD6_/view?usp=sharing). +It is the same as the version originally submitted in September 2020, +but some details have been added to page 3 on the use of a retention +length/radius for retention modification (in place of just using +adjacent cells). This is based on discussion with Rich over email in +September, and relevant parts of that commentary are in the design +document for reference. + +## Technical Details + +Test data, with a table of contents and powerpoint describing +intermediate outputs, can be found +[here](https://drive.google.com/drive/folders/1uCxfhZ4pGsJMrhoAvVPvmKjTewGlQmnd?usp=sharing). + +# Open Issues + +While a PEP is in draft, ideas can come up which warrant further +discussion. Those ideas should be recorded so people know that they are +being thought about but do not have a concrete resolution. This helps +make sure all issues required for the PEP to be ready for consideration +are complete and reduces duplicating prior discussion. + +# References + +Any additional helpful references not included in the above document. diff --git a/pep-0010/DesignDocument - InVEST stormwater_clean_Dec2020r1 for public comment.docx b/pep-0010/DesignDocument - InVEST stormwater_clean_Dec2020r1 for public comment.docx new file mode 100644 index 0000000..8e8867a Binary files /dev/null and b/pep-0010/DesignDocument - InVEST stormwater_clean_Dec2020r1 for public comment.docx differ diff --git a/pep-0010/Stormwater_Retention_PEP_for_public_comment.docx b/pep-0010/Stormwater_Retention_PEP_for_public_comment.docx new file mode 100644 index 0000000..509f83c Binary files /dev/null and b/pep-0010/Stormwater_Retention_PEP_for_public_comment.docx differ diff --git a/pep-0011.md b/pep-0011.md index befb9ac..ed1e58a 100644 --- a/pep-0011.md +++ b/pep-0011.md @@ -1,102 +1,284 @@ -[This PEP has been modified from the origainl PEP Google Doc](https://docs.google.com/document/d/1w_B0GYc4TPR4wARbRC3satC3H7w9RT9woIfXBl1Fyh4/edit?usp=sharing) - -# Platform Enhancement Proposal: Deprecate the GLOBIO model - -## Contacts - -Software Team, primary contact Emily Soth (esoth@stanford.edu) - -## Abstract - -This is a proposal to deprecate the InVEST GLOBIO model. - - -As described below, I argue that this model meets all the deprecation criteria. -But the primary argument for deprecating this model is that it’s been made obsolete. -Earlier this year, PBL Netherlands (the creator of GLOBIO) published an open -source command line tool for GLOBIO. It’s hard to justify continuing to -maintain our outdated implementation when a reference implementation (i.e., -a definitive version reflecting the designers’ intent) is available. - -## Motivation - -**Criteria for evaluating models or tools to be deprecated:** - * ES science credibility: has the science changed/advanced such that this - no longer represents our current understanding - * **The InVEST model implements an outdated version of GLOBIO.** GLOBIO is a - biodiversity model published by PBL Netherlands Environmental Assessment Agency. - The InVEST GLOBIO model is an implementation of GLOBIO version 3 - (paper published 2009). PBL has since released multiple minor version - updates (3.x), and then a version 4 in 2019. - * **It no longer provides new functionality.** An open source GLOBIO4 command - line tool is now available to install from the - [GLOBIO4 source code repository on GitHub.](https://github.com/GLOBIO4/GlobioModelPublic) - Since that was made available, the InVEST model - no longer meets the novelty criteria for a new model. [a] - * A GLOBIO3 reference implementation may have once been available, but I - wasn’t able to find it online. The InVEST GLOBIO model was created - because at the time, the reference GLOBIO tool was difficult to run - and/or didn’t fit into existing workflows. It’s not clear if it would - meet our criteria for a new model today. - - - * User demand: actionability of information for application/uptake, current - usage stats - how “popular” of a model is it? - * Usage logging: Per our usage logging statistics, GLOBIO is **one of the - least used models**. Only Wave Energy, and Urban Stormwater (which has - been around for less than a year), have had fewer runs. This chart - shows monthly GLOBIO runs over time compared against highly used models. - * It’s also worth noting that we have not received any requests to - update the model, even though it’s been out of date for a decade. - - - ![InVEST model usage](pep-0011/invest-model-usage.png "InVEST model usage") - - - * Science support available - does anyone on staff have the knowledge/expertise - to maintain and answer questions - * **Science and software support is lacking**. The [InVEST Model Supporters - page](https://github.com/natcap/invest/wiki/InVEST-Model-Supporters) - lists Becky as the primary contact for GLOBIO. I've reached out to - get her opinion, and she supports deprecating the model. Parts of the - model documentation and user guide are unclear, and the software team - doesn’t understand it well enough to make significant updates or refactor - the code if that were needed. - * Software team burden: user support required, how broken is it, what % time - is required to maintain it - * Very little user support is required because the model is rarely used. - There are just 4 questions tagged with GLOBIO on our forum. The last - was almost a year ago. - * There are three open issues related to GLOBIO: - * It expects that specific LULC codes 8 and 9 will be provided - ([#771](https://github.com/natcap/invest/issues/771)) - * It only accepts .tif and .shp inputs - ([#632](https://github.com/natcap/invest/issues/632)) - * The test suite is inadequate - ([#409](https://github.com/natcap/invest/issues/409)) - * Some maintenance and updates require modifying all models, so keeping - this model around has an ongoing cost. - - -## Support -Deprecating this model will slightly reduce the long term maintenance and support -required for InVEST and the user’s guide, as well as translation. - - -## References -_Original GLOBIO 3 paper_: -Alkemade, R., van Oorschot, M., Miles, L. et al. GLOBIO3: A Framework to -Investigate Options for Reducing Global Terrestrial Biodiversity Loss. -Ecosystems 12, 374–390 (2009). -https://doi-org.stanford.idm.oclc.org/10.1007/s10021-009-9229-5 - - -_GLOBIO 4 paper_: -Schipper, AM, Hilbers, JP, Meijer, JR, et al. Projecting terrestrial -biodiversity intactness with GLOBIO 4. Glob Change Biol. 2020; 26: 760– 771. -https://doi-org.stanford.idm.oclc.org/10.1111/gcb.14848 - -### Google Doc comments -[a] This seems the main reason for deprecation: if there is an open source, -scriptable version provided by PBL, who are the main developers, it seems -futile for us to maintain an outdated parallel version. +Version 0.2 approved by PSC on Oct. 30, 2020 + +Platform Enhancement Proposal (PEP) Template 0.2 + +Note: Expect iteration on this to get to the right level of detail +necessary to assess the science/software complexity of the request. + +See the PEP guidelines +[here](https://docs.google.com/document/d/1GOZKXsNfP7PHTjhKRgzx6bmcJHwOloyrSDvkOfx7fhk/edit?usp=sharing) +for the criteria by which PEPs will be evaluated. + +# Abstract + +A short (~200 word) description of the technical issue being addressed, +and whether this fits into the category of data, utility, model, +tailored tool or some combination. + +At present, the only way to offer InVEST in a language other than +English is to modify the source code, translate text to the target +language and then re-build and re-release the software with the new +translations, a process that is both expensive and tedious. With an +initial nontrivial investment of the software team’s time, InVEST can be +modified to allow translated text to be “swapped in” according to the +user’s choice of language. The proposed mechanism would allow for extra +languages to be trivially added to InVEST, and fall back to English when +a translated piece of text is not available or is out of date. + +The real commitment here, and the need for PSC review, is that +implementing this requires an ongoing organizational commitment to +maintaining the translations. + +While there is no existing PSC/PEP category suitable for this proposal, +there is demonstrated demand from colleagues at CAS for a Chinese +translation and likely demand (certainly interest) for a Spanish +translation from NatCappers working with partners in Latin America. + +# Motivation + +Explain why existing software/platform functionality is inadequate to +address the problem that this PEP solves; for each feature type (data, +utility, model, or tailored tool) describe how it meets the listed +criteria in the [PEP +Guidelines](https://docs.google.com/document/d/1GOZKXsNfP7PHTjhKRgzx6bmcJHwOloyrSDvkOfx7fhk/edit?usp=sharing) + +Translating InVEST is a problem independent of all other pieces of +software on the Platform and there is no alternative solution that so +neatly solves the problem. Maintaining centralized translation +infrastructure for InVEST will keep translation costs low by clarifying +which pieces of text need to be re-translated after they have been +updated, and will enable the organization to support additional +languages as needed to fulfil its strategic objectives. + +While there is no good fit for the existing PEP feature type +classifications, this feature meets the PEP criteria in at least the +following ways: + +1. **Decision relevant, High impact**. This feature has the potential + to expand our user base to include those who do not have a grasp of + technical English. Within China alone, the perceived impact of this + was enough for CAS to go through the trouble of translating and + re-building InVEST for their own use[^1]. + +2. **Generalizability.** As described, this feature is general enough + that any language can be supported, including without any + involvement by the Natural Capital Project. + +3. **Feasibility**. The technical details of the implementation have + been + [prototyped](https://github.com/phargogh/prototype-python-i18n-gettext) + and we have prior experience with translating OPAL, an application + built with a similar stack. Maintaining the translations is also + feasible provided that NatCap is willing to commit resources to this + maintenance. + +# Support + +Detail additional long-term support that will be required because of +this change. Can include updates to documentation, MOOC, training +program, software team user support, etc. + +Translating InVEST requires that NatCap commit to supporting two +complementary efforts: + +1. The software “plumbing” that allows for translated text to be seen + by a user who requests an alternate translation. + +2. The accuracy and completeness of the translated text, for each + target language. + +The costs of the software implementation are front-loaded in this +project, but will require some maintenance going forward. The +maintenance and support of translations is by far the larger cost. See +below ([Required Maintenance](#required-maintenance)) for details +and example costs. + +# Specification + +This is the heart of the PEP, it should be complete enough that an +engineer and or manager can estimate resources needed to implement the +PEP. And if relevant it should include any backwards compatibility +issues -- i.e. is this a change to routing that will make the results of +SDR different in future versions than past versions? + +## Technical Details + +This should include any mathematical models, references to papers, +necessary input/testing data, desired outputs, prototype scripts, or any +other relevant information. + +### How this will Work + +InVEST and the User’s Guide will use GNU Gettext to swap in translated +text when a translated piece of text is available. This approach has +been [prototyped +here](https://github.com/phargogh/prototype-python-i18n-gettext) and +has the following advantages: + +- Translation text will be stored in a standard plain-text format that + can be shared easily and tracked as it is changed over time. This + avoids vendor lock-in, allows us to compare translations across InVEST + versions, and makes for easier editing of these files. + +- If a piece of translated text is not available, the English version + will be used instead. Thus, NatCap has the flexibility to prioritize + translating certain parts of InVEST and the User’s Guide if needed. + +- Additional languages can be added with near-trivial software team + effort. + +- An informed user can provide their own “message catalog”, bypassing + any need to directly involve NatCap in the creation and distribution + of 3rd-party translations and is a backup option in case NatCap is no + longer able to maintain translations. + +### Required Software Work + +A more detailed breakdown of expected work and anticipated costs is +available in [this +doc](https://docs.google.com/document/d/1MJQeTg40wpuk5TwLGyhxbMEWHpsDt5rZMG0nsY0Kbm8/edit#), +but has been summarized below for clarity and convenience. + +#### Establish a Single Source of Truth + +In order to keep translation costs low, the software team plans to +reduce the duplication of information across the InVEST application and +the User’s Guide, such as in the description of inputs and outputs. This +consolidation means that the same information can be displayed in the +Workbench, the Qt UI (until it is deprecated), and the User’s Guide, +enabling corrections and updates to this text to be reflected across all +displays. It also means that this text will only need to be translated +once, reducing costs. + +#### Implement User Interface Components for Language Selection + +With InVEST using a queryable, single source of truth for user-facing +text, all interfaces will need to be updated to: + +1. Allow the user to select their language of choice, given a list of + available languages + +2. Allow an informed user to input a custom message catalog via a + graphical dialog + +3. Support the use of translations in a way that is appropriate and + sensible for the interface in question. How this is reflected in the + Workbench will be different from the Qt UI. + +#### Support Multiple Languages in the User’s Guide + +InVEST’s Users Guide will also be translated via GNU Gettext. This +carries all of the same advantages of using GNU Gettext in InVEST, +including a graceful fallback to English when a translation for a +specific piece of text is not available. + +In order to simplify the translation of the User’s Guide, there are +several functional updates to all model chapters that must be made: + +1. Content describing model inputs and outputs in detail must be + updated to draw their text from InVEST itself. + +2. Graphics containing meaningful text should be adapted in order to + have their text translated effectively. + +3. The online version of the User’s Guide will be subdivided into each + established language, with one build per language, and the user will + have a clear way to select their desired language. All supported + languages will be rebuilt when the English version is edited. + +#### Revisit the Accuracy of User’s Guide Content + +Given the cost of translation, it may be worth revisiting the content of +each User’s Guide chapter to ensure it is up-to-date before translating. + +### Required Initial Translation + +Exactly how much of the User’s Guide is translated is a question of +priority for NatCap. Given the fallback to English, NatCap may elect to +iteratively translate InVEST and/or the User’s Guide according to +funding and/or other factors. + +To translate the User’s Guide in its entirety will incur an up-front +cost of approximately USD \$20,000[^2], but could easily be higher +depending on the translation service used. + +### Required Maintenance + +The single largest cost of this project is the maintenance of the +translations, both for accuracy and completeness. All new InVEST models +and any textual updates to user-facing text will need to be translated. + +One of the benefits of the proposed translations system is that it will +highlight when a block of text has been changed. Thus, we need only +verify the accuracy of translations for any text that has changed, and +this will help reduce costs. If no text has changed between InVEST +versions, then there will be no need to engage a translator for that +version. + +Example costs of translation: + +- A new model is added to InVEST with a User’s Guide chapter. + + - Up-front cost of translating the User’s Guide depends on length and + target language(s). Example quotes below are from + [https://translated.com](https://translated.com), + [https://www.onehourtranslation.com/](https://www.onehourtranslation.com/), + assuming scientific subject matter, editing and translation into + Chinese (simplified). + + - Shortest model chapter: Urban Flood Risk Mitigation (1263 words) + \$250-\$330 + + - Longest model chapter: HRA (12880 words) \$2450-\$3350 + + - Up-front cost of translating the User Interface: + + - Shortest model UI: CBC Preprocessor (158 words) \$25-\$35 + + - Longest model UI: Wind Energy (1117 words) \$221-\$230 + +- A model is deprecated, removed from InVEST. + + - Minor cost of software time to remove the model. + + - No translation time required. + +- An edit is made to a User’s Guide chapter to clarify an input. + + - The costs here will depend on the length, but the cost for + translation and editing quoted is around \$0.10 - \$0.15 per word. + +# Open Issues + +While a PEP is in draft, ideas can come up which warrant further +discussion. Those ideas should be recorded so people know that they are +being thought about but do not have a concrete resolution. This helps +make sure all issues required for the PEP to be ready for consideration +are complete and reduces duplicating prior discussion. + +## Timing of Translations + +Because of the cost of translation into each target language, it may be +cheaper to send a batch of textual changes to translators rather than +attempting to translate each small change as it happens. + +I propose that we engage a translator with each minor version of InVEST +(e.g. InVEST 3.10, 3.11). This may render some translations out-of-date +between bugfix releases. + +# References + +Any additional helpful references not included in the above document. + +[^1]: The CAS translation was quickly rendered out of date. In the time + it took for CAS staff to translate and re-build InVEST, NatCap had + issued several bugfix releases, which would then take additional CAS + time to re-translate. Translations as proposed works around this + issue. + +[^2]: This is assuming a User’s Guide word count of 131,834 (via find + doc/users-guide/source -name "\*.rst" \| xargs wc -w) at a cost of + USD \$0.15 per word. In practice, this word count includes much of + what will be translated as a part of InVEST’s descriptions of inputs + and outputs and so the cost reflected here may, in fact, include + much of what is currently in InVEST User Interface. diff --git a/pep-0011/PEP for public comment - Translating the InVEST UI.docx b/pep-0011/PEP for public comment - Translating the InVEST UI.docx new file mode 100644 index 0000000..f71dfbb Binary files /dev/null and b/pep-0011/PEP for public comment - Translating the InVEST UI.docx differ diff --git a/pep-0012.md b/pep-0012.md index 37cef45..aa3cb53 100644 --- a/pep-0012.md +++ b/pep-0012.md @@ -1,207 +1,284 @@ -[This PEP has been modified from the origainl PEP Google Doc](https://docs.google.com/document/d/1cyqcHuyhtW3-IkJVdzNDamJx90I4k1raDJRKzrfv6eM) - -PEP template Version 0.2 approved by PSC on Oct. 30, 2020 - -Platform Enhancement Proposal (PEP) - -# Supporting both D8 and MFD algorithms in InVEST routed models and tools - -Note: Expect iteration on this to get to the right level of detail -necessary to assess the science/software complexity of the request. - -See the PEP guidelines -[here](https://docs.google.com/document/d/1GOZKXsNfP7PHTjhKRgzx6bmcJHwOloyrSDvkOfx7fhk/edit?usp=sharing) -for the criteria by which PEPs will be evaluated. - -# Contacts - -Stacie is the main contact, with input from James, Dave, Rafa, Lisa and -Jesse. - -# Abstract - -The routed freshwater models (Seasonal Water Yield (SWY), Nutrient -Delivery Ratio (NDR), and Sediment Delivery Ratio (SDR)) and related -tools (DelineateIt (DI) and RouteDEM (RD)) are not consistent in their -use of routing algorithm. This PEP would make these models and tools -consistent, and enhance functionality, by updating them all to provide a -user-selectable option between D8 and multiple flow direction (MFD) -routing algorithms. - -# Motivation - -As of InVEST 3.13.0, the routed freshwater models (NDR, SDR, and SWY) -use the MFD routing algorithm, and do not provide any other algorithm -options. Meanwhile, DelineateIt only uses the D8 algorithm, and does not -provide any other options, and RouteDEM provides the option to use -either MFD or D8. - -Along with simply being inconsistent, these differences lead to several -practical issues. Importantly for modeling, when using DelineateIt to -create watersheds that are input to a routed freshwater model, it is -possible/likely that its D8 algorithm creates streams and derivative -watersheds that are different from the freshwater model's MFD result. -This would then cause a spatial mismatch between the watershed input and -the hydrologic network generated by SWY/NDR/SDR, and thus lead to -erroneous aggregated results. - -It's also confusing for users. The algorithm difference between tools -has come up several times on the User Forum, for example -[here](https://community.naturalcapitalproject.org/t/in-the-swy-model-is-it-possible-to-use-simple-d8-flow-direction-instead-of-mfd/1791) -and -[here](https://community.naturalcapitalproject.org/t/why-ndr-model-generate-streams-bigger-than-routedem/2028). - -There are reasons to support both algorithms. MFD had historically been -adopted for the freshwater models, since conceptually MFD provides a -better representation of hydrologic processes than D8. But some seminal -papers have shown that there is little to no benefit of MFD for medium -resolution DEMs (on the order of 10s of meters), which is the resolution -most often used for InVEST modeling. MFD can be useful to create a good -water mask because it spreads flow out nicely over flat areas such as -lakes and broad stream channels. However, this same spreading comes with -negative effects, often creating streams that are much wider than -reality (especially when considering that a pixel is usually at least 30 -meters in width). Not only does this look visually incorrect in -resulting maps, but it's usually the case that there is no model output -within the stream network, so we are missing results in the very -important riparian zone, and sometimes over very large areas of the -landscape. This makes it difficult, if not impossible, to model riparian -buffers in a land cover scenario (which is commonly done), with any hope -of being realistic relative to the actual landscape, or the land -use/land cover map. This problem has come up several times during the -course of NatCap projects, and has been asked about [on the user -forum](https://community.naturalcapitalproject.org/t/riparian-buffer-values-issues-because-of-ndr-output-streams-wider-than-in-reality/2269). - -D8 is standard in hydrology modeling, and generally creates streams that -are much thinner, by definition 1 pixel in width, which is what users -expect, as well as allowing for better representation of the riparian -zone. There is an existing related GitHub enhancement - [Allow -DelineateIt to do MFD watershed -delineation](https://github.com/natcap/invest/issues/440) - -which includes "In practice when we\'ve published global results run -with MFD we\'ve had to re-run them with D8 to be comparable to others." -So providing the option to choose between algorithms, and documentation -to help users choose, will allow us to select the option that is better -suited to our modeling purposes, and provide compatibility with -non-InVEST models. - -Following is a comparison of the stream network created by RouteDEM with -D8 and MFD, same DEM and threshold flow accumulation, in our Gura sample -data watershed. The D8 streams are 1-3 pixels in size, while the MFD -streams are much wider, which doesn't match reality. Also note that the -networks look somewhat different, so the difference in algorithm affects -not only the width, but also the stream shape and tributaries. The third -image shows the area of MFD streams overlaid with the land use/land -cover map, illustrating how much of the landscape will end up with -modeled NoData values within the MFD stream network. - -![RouteDEM D8](pep-0012/RouteDEM-D8-streams-Gura.png) - -![RouteDEM MFD](pep-0012/RouteDEM-MFD-streams-Gura.png) - -![MFD stream area](pep-0012/MFD-stream-area-lulc-relative.png) - -As an enhancement to existing models, this PEP follows these Guidelines: - -- **Actionable**: Applies to some of our most-used models. - -- **Credibility**: The D8 algorithm is very commonly used for - > hydrologic modeling, and users have specifically asked for a D8 - > option, due to it being a standard, and its creation of a - > narrower/more intuitive stream network. - -- **Generalizability**: Either algorithm may be used with any DEM in - > any area of interest. - -- **Feasibility**: InVEST code already exists for implementing both D8 - > and MFD algorithms, and RouteDEM already provides the option to - > choose between them in the Workbench user interface. - -# Support - -The InVEST User Guide chapters for all 5 tools will need to be updated -to reflect the algorithm options, provide examples, and note the pros -and cons of each. This is a one-time task. - -Maintaining parallel implementations of custom routing functions in -InVEST will require additional maintenance effort over the long term. - -Providing both routing options may reduce NatCap analyst and software -team time needed to explain the current limitations/mis-match and -workarounds on the forum. - -No additional support is anticipated, beyond current InVEST, User Guide, -and user forum maintenance. - -# Specification - -The following software changes would need to be implemented for the SWY, -NDR, and SDR models, as well as DelineateIt: - -- Add the option to choose between MFD and D8 algorithms to their - > Workbench interface. - -- Modify model code to implement the user-selected algorithm within - > each model. - -User Guide chapters for SWY, NDR, SDR, DI, and RouteDEM: - -- Update text in the Data Needs section to reflect the new input - > options (RouteDEM already has this). - -- Create a new section called something like Routing Algorithm - > Selection with example graphics to illustrate the difference in - > stream networks generated by each algorithm, and noting the pros - > and cons of each. - -## Technical Details - -The code for both MFD and D8 already exists in InVEST, as does code that -provides the option to choose between the algorithms in the Workbench -interface. However, - -- The D8 InVEST model implementations were made some time ago, which - > means that they are out of sync with the last few years\' changes - > to the routed models including the major update to sediment - > deposition. So this will need to be updated by the software team. - -- The D8 InVEST model implementations do not have software tests. The - > software team will need to add some when this becomes available in - > InVEST. - -- DelineateIt is currently only available with the D8 algorithm. An - > MFD watershed delineation routine will need to be written and - > tested by the software team. - -Specific changes that will need to be made include: - -- \[InVEST\] Updates to the routed models (SDR, NDR, SWY) to: - - - Allow the user to select their choice of routing model: D8 or - > MFD - - - Update custom routed model functionality to add D8 versions - - - Write software tests to cover the new D8 functionality in - > addition to the MFD - -- \[InVEST User Guide\] Update the documentation around this change - - - Which routing model should be selected? What are the tradeoffs - > with each routing model? (Stacie will do this). - - - Add the new invest_spec RST directive to the models' RST so that - > MODEL_SPEC descriptions can be pulled in. - - - Coordinate with translation teams to update the user's guide for - > these changes. - -- \[pygeoprocessing\] - - - Implement and test an MFD version of watershed delineation. - -# Open Issues - -None known at this time. - -# References +Version 0.1 submitted to PSC by July 19, 2021 + +Platform Enhancement Proposal (PEP) Urban Nature Access model + +# **Contacts** + +Lisa Mandle (lmandle@stanford.edu) + +Roy Remme +([r.p.remme@cml.leidenuniv.nl](mailto:r.p.remme@cml.leidenuniv.nl)) + +Hongxiao Liu (michellewinter@126.com) + +Perrine Hamel (perrine.hamel@ntu.edu.sg) + +# **Abstract** + +**This proposal is for a new model, “Urban Nature Access”**, which +provides for the analysis of supply and demand of urban nature for +recreation and health in cities, addressing both availability and +accessibility of nature. The model is complementary to the existing +InVEST Recreation model, with a specific relevance for densely populated +urban contexts where nature is scarce in relation to demand from +inhabitants. The model can be used as an access indicator related to +both recreation and health benefits, without data and analysis +challenges that are often linked to such benefits. We would like it to +be added to InVEST as one of the new urban components. The model is +complete, and already available as a stand-alone module on the Joint +Test Platform (JTP) created by the Chinese Academy of Science, but +integration into InVEST is needed to be a fully featured InVEST model +(e.g., broader audience, ability to run in batch mode for multiple +cities, etc.). The model has been tested in a case study for Paris +([Liu et al., under +review](https://docs.google.com/document/d/1wFEYemZAhSxG3eYGLfpyhWJYPYTYPTSb/edit?usp=drive_web&ouid=103875878077182489213&rtpof=true), +[Hamel et al., +2021](https://www.nature.com/articles/s42949-021-00027-9)), and a +[design +doc](https://docs.google.com/document/d/19RIs7eNEnHz4WAGbqZ7g2Bu5fyesLGQd/edit?usp=drive_web&ouid=103875878077182489213&rtpof=true) +is complete. + +# **Motivation** + +A key issue for many urban planners and decision-makers is understanding +whether there are sufficient amounts of urban nature for inhabitants to +enjoy recreational opportunities in and around cities and benefit from +the potential health benefits. The current set of InVEST models only +tackle this issue to a very limited extent, and therefore we propose to +develop such a model in the InVEST suite. The proposed model links to, +but also fills a gap, in NatCap’s work revolving around recreation and +health, as those approaches currently have clear limitations: + +1. *Recreation;* This InVEST model estimates visitation based on a + database of Flickr photos. This database is no longer being updated, + and the representativeness of this database in global and urban + contexts is not optimal. The model is not adequate for many urban + areas, either because Flickr photos often depict non-natural areas + in cities, or because the database is insufficiently filled for + certain cities or areas within cities. + +2. *Mental and physical health;* Key fundamental research has been done + for both mental health ([Bratman et al., + 2019](https://advances.sciencemag.org/CONTENT/5/7/EAAX0903.abstract)) + and physical health and physical activity ([Remme et al., + 2021](https://www.pnas.org/content/118/22/e2018472118.short)), + resulting in model frameworks. However, applicable models are not + yet available in InVEST. Tailored models require intensive data + collection and research and approaches have not yet been generalized + to enable direct analysis of the health effects of green space + within cities around the world. Both model frameworks include nature + availability and accessibility as important determinants of nature + exposure, which then yields health benefits. Modeling nature + availability and accessibility as proposed here therefore represents + a useful proxy for assessing potential health benefits. + +The limited applicability of the *Recreation* model in urban contexts +and the lack of health-related models in InVEST fuelled the desire to +create a model that could inform researchers and policy makers on the +accessibility of urban nature, as a first order proxy for assessing +recreational and health benefits. This model would (1) use commonly +available datasets in urban areas in order to stimulate applicability in +data poor regions *(criterion: usability)*, and (2) cater towards the +specific interest of decision makers in densely populated urban areas by +explicitly linking metrics for supply of urban nature and related demand +*(criterion: novelty)*. + +*Novelty:* The *Urban Nature Access model* will be an addition to the +current ecosystem service modelling landscape as urban nature access +models are missing. As part of the study submitted to Land Use Policy, +we reviewed existing tools and models regarding recreation and access, +and we did not identify any available tools that model supply and use of +urban nature similar to the approach we describe here. Additionally, +this model would be one of the first InVEST models to couple aspects of +supply and demand for an ecosystem service. The model applies an +advanced method to calculate supply of urban nature. It allows users to +analyze the supply of surrounding green space to each pixel, by applying +the two step floating catchment area approach (2SFCA). This method +calculates the supply of green space within a given distance of a +populated pixel, and then aggregates this supply back to the given +populated pixel, while accounting for supply in pixels with overlapping +search areas. Demand is calculated based on a user-defined demand +threshold (m2 green space/capita). The model offers the opportunity to +analyze supply and demand for different sub-populations, such as +different age groups or ethnicities, as well as for different urban +green space types (e.g., urban parks or forests). These extensions of +the basic model support analyses related to equity and can provide +valuable insights to city planners and researchers when pursuing the +establishment of greener and more equitable cities. + +*Usability:* To stimulate usability the *Urban Nature Access model* +makes use of three widely available types of data. First, a vector layer +with administrative boundaries. This can be either the boundary of the +study area, or a further subdivision into for example neighborhoods. +Second, a urban nature dataset (e.g., from land cover/land use maps, +city planning maps, or satellite-derived indices), which is commonly +available in either vector or high-resolution raster format at city or +(sub)national level, or through for example OpenStreetMap +([www.openstreetmap.org](http://www.openstreetmap.org)). This +data can be used with a single class for urban nature, or with a +subdivision into multiple types of nature (e.g., city park, urban +forest, and waterfront). Third, a spatial population dataset, which is +available globally through for example the WorldPop database at 100m +resolution ([www.worldpop.org](http://www.worldpop.org)), or +through more local sources, ideally enabling the identification of +sub-populations (e.g., based on gender, age, or ethnicity). Given the +public character of the required data, the model can be applied in most +cities around the world. Further information on required and optional +data is described in the design document listed under the section +Specification. + +*Demonstrated interest:* There is a broad interest in applying models +related to urban nature access related to recreation and health benefits +and urban nature supply in urban projects, both within NatCap and by +external users. Understanding where changes in urban nature will affect +people, and whom they will affect is a key question in both urban +planning and research projects. We have already applied the proposed +model in several of our own projects (e.g., in Paris, Guangzhou, and +Shenzhen - accessed through the Joint Test Platform (JTP), developed by +CAS for collaboration with Stanford and UMN). Additionally, we have +received requests from multiple external parties from around the globe +to apply the model. Multiple international researchers that attended our +urban InVEST workshops in 2019 and 2020 enquired about the availability +of the model. A prominent example was the request to get access to the +model for an analysis of 775 European cities as part of a large EU +project (Naturvation). Unfortunately, we could not commit to this +request using the JTP version of the model, so Naturvation ended up +using only the InVEST urban cooling and flood mitigation models. + +While a version of the model exists in CAS’s JTP, that was never +intended to be a permanent home for the model. Fixing bugs is difficult +with software engineers located in China, and the implementation has +been buggy and lacks transparency (though it is functional for those who +persevere). It is also not possible to run in a batch script or to do +scenario building within the JTP framework, so broad applicability of +the JTP version is limited. + +*Credibility:* The model has been developed and tested in a case study +for Paris, France, led by Hongxiao Liu. The study assesses supply and +demand for urban green space, using open access data for supply (land +cover and a population raster). Demand was modelled using policy +guidelines and additional demand data from CIRED’s IDEFESE project. A +manuscript for this study is currently under review at Land Use Policy +(Liu et al., under review). A predecessor of this model has also been +applied in Guangzhou, China, and published in Landscape and Urban +Planning ([Liu et al., +2020](https://www.sciencedirect.com/science/article/pii/S0169204619314240)). +The proposed model is an advancement on that published approach, which +did not apply the 2SFCA calculation. In addition, we recently applied +the model in a NatCap project for the World Bank in Guangzhou, China, +where we have quantified the ecosystem services of the city’s largest +wetland. These preliminary studies show that the model can identify +areas that have insufficient green spaces, is sensitive to changes in +greenspace area, enables comparison between different urban planning +scenarios, and that impacts of changes in greenspace on specific +demographic groups can be explored with sufficient data. + +# **Support** + +The model should not require much long-term support beyond what is +needed for most models, i.e. its inputs will not need to be updated year +to year, for example. It will need a new entry in the InVEST user’s +manual, and a sample data set could be provided from examples that have +already been completed. The model has not yet been used in training +workshops (aside from general notifications of its development), so +training materials would need to be developed if it were to be included +in the MOOC or InVEST training sessions. + +# + +# **Specification** + +The design document for this model can be found [here (version for +public +comment)](https://docs.google.com/document/d/19RIs7eNEnHz4WAGbqZ7g2Bu5fyesLGQd/edit?usp=drive_web&ouid=103875878077182489213&rtpof=true). +This design document illustrates the model design as it has been applied +in the Paris case study. + +## **Technical Details** + +[Test +data](https://drive.google.com/drive/folders/197ZOnGAUgzL-NQzoheb9IyMKIUsVIZcN) +for the Paris case study have been made available for testing and +developing the model. Please note that this test data is available only +for testing and developing the model, and may only be used internally by +NatCap. Data may not be shared or used as test data for external users. + +The data folder includes a +[spreadsheet](https://docs.google.com/spreadsheets/d/1l0u49hjTGe1e0kgcqJ_KDLF8-vf5HImw/edit#gid=1220004868) +with basic information on the data, data on administrative boundaries +(communes \[districts\]), three population datasets (total population, +female population, and older adults), and a LULC dataset for greenspace +types. The JTP version of the model is available +[here](http://47.252.8.167:8081/JTP/main.html) as the Daily +Recreation model. + +# **Open Issues** + +In autumn 2020 the design document was discussed with Rich and James, +and several issues for further discussion emerged. Key issues that were +discussed were the following: + +- *LULC as vector or raster:* City planners seem to apply vector data + more often, meaning that this may generally be more easily accessible + to users. However, InVEST models more commonly use raster data as LULC + input, and users that will apply multiple models are likely to have + access to a raster format. High-resolution satellite imagery (e.g., + Sentinel 2) is an important source for defining urban green space that + is often not captured in vector data (e.g., street trees or pocket + parks). The JTP version of the model and the Paris case study both + apply raster data to define urban green space. + +- *Euclidean vs. network distance:* The current design document applies + Euclidean distance to set search radii. Euclidean distance provides a + simple, yet potentially skewed, metric for accessibility. An + alternative would be to add an optional calculation that applies + network analysis along roads instead of Euclidean distance. However, a + road network analysis requires additional data, while Euclidean + distance is still frequently used in scientific research. Euclidean + distance was used in both the Paris and Guangzhou case studies. + +# **References** + +Bratman, G.N., Anderson, C.B., Berman, M.G., Cochran, B., de Vries, S., +Flanders, J., Folke, C., Frumkin, H., Gross, J.J., Hartig, T., Kahn, +P.H., Kuo, M., Lawler, J.J., Levin, P.S., Lindahl, T., Meyer-Lindenberg, +A., Mitchell, R., Ouyang, Z., Roe, J., Scarlett, L., Smith, J.R., van +den Bosch, M., Wheeler, B.W., White, M.P., Zheng, H., Daily, G.C., 2019. +Nature and mental health: An ecosystem service perspective. Sci. Adv. 5, +eaax0903. +[https://doi.org/10.1126/sciadv.aax0903](https://doi.org/10.1126/sciadv.aax0903) + +Hamel, P., Guerry, A.D., Polasky, S., Han, B., Douglass, J.A., Hamann, +M., Janke, B., Kuiper, J.J., Levrel, H., Liu, H., Lonsdorf, E., +McDonald, R.I., Nootenboom, C., Ouyang, Z., Remme, R.P., Sharp, R.P., +Tardieu, L., Viguié, V., Xu, D., Zheng, H., Daily, G.C., 2021. Mapping +the benefits of nature in cities with the InVEST software. Npj Urban +Sustain. 1, 25. +[https://doi.org/10.1038/s42949-021-00027-9](https://doi.org/10.1038/s42949-021-00027-9) + +Liu H., Hamel, P., Tardieu, L., Remme, R.P., Han, B., Ren, H., under +review. A geospatial model of nature-based recreation for urban +planning: case study of Paris, France. Submitted to Land Use Policy. +(available +[here](https://docs.google.com/document/d/1wFEYemZAhSxG3eYGLfpyhWJYPYTYPTSb/edit?usp=drive_web&ouid=103875878077182489213&rtpof=true)) + +Liu, H., Remme, R.P., Hamel, P., Nong, H., Ren, H., 2020. Supply and +demand assessment of urban recreation service and its implication for +greenspace planning-A case study on Guangzhou. Landsc. Urban Plan. 203, +103898. +[https://doi.org/10.1016/j.landurbplan.2020.103898](https://doi.org/10.1016/j.landurbplan.2020.103898) + +Nootenboom, C., E. Lonsdorf, R. Remme, R. Griffin, B. Han, T. Wu, and A. +Guerry (2021). Assessment of key ecosystem services provided by the +Haizhu National Wetland Park in Guangzhou, Guangdong, China. [Haizhu +Wetland Report for the World +Bank.](https://docs.google.com/document/d/1DBgQnuIRL3do2t_DfeZp6SJdaqgA6DmMuC_ZlPWqsX0/edit) + +Remme, R.P., Frumkin, H., Guerry, A.D., King, A.C., Mandle, L., Sarabu, +C., Bratman, G.N., Giles-Corti, B., Hamel, P., Han, B., Hicks, J.L., +James, P., Lawler, J.J., Lindahl, T., Liu, H., Lu, Y., Oosterbroek, B., +Paudel, B., Sallis, J.F., Schipperijn, J., Sosič, R., de Vries, S., +Wheeler, B.W., Wood, S.A., Wu, T., Daily, G.C., 2021. An ecosystem +service perspective on urban nature, physical activity, and health. +PNAS. +[https://doi.org/10.1073/pnas.2018472118](https://doi.org/10.1073/pnas.2018472118) diff --git a/pep-0012/PEP_Urban_Nature_Access_model_for_public_comment.docx b/pep-0012/PEP_Urban_Nature_Access_model_for_public_comment.docx new file mode 100644 index 0000000..034ca79 Binary files /dev/null and b/pep-0012/PEP_Urban_Nature_Access_model_for_public_comment.docx differ diff --git a/pep-0013.md b/pep-0013.md index 9b796a7..170d525 100644 --- a/pep-0013.md +++ b/pep-0013.md @@ -1,434 +1,244 @@ -This PEP has been exported to MarkDown from the original PEP [Google -Doc](https://docs.google.com/document/d/1ykd4mst3Y-wuMm1QxBqEMib5LVxZ1748kkshRLjNzKM/edit?tab=t.0), -and is stored as a [word document in this -repo](./pep-0013/pep-urban-mental-health-model.docx) - -PSC is scheduled on 2025-06-23 - -Last updated on: 2025-05-12 - -# Platform Enhancement Proposal (PEP) InVEST Urban Mental Health Model - -See the PEP guidelines -[here](https://docs.google.com/document/d/1GOZKXsNfP7PHTjhKRgzx6bmcJHwOloyrSDvkOfx7fhk/edit?usp=sharing) -for the criteria by which PEPs will be evaluated. - -See [design -doc](./pep-0013/invest-mental-health-model-design-doc-v0.3.0.docx). - -# Contacts - -Yingjie Li -([yingjieli@stanford.edu](mailto:yingjieli@stanford.edu)) - -Anders Rydstrom -([anders.rydstrom@stanford.edu](mailto:anders.rydstrom@stanford.edu)) - -Yougeng Lu -([yougengl@stanford.edu](mailto:yougengl@stanford.edu)) - -Anne Guerry -([anne.guerry@stanford.edu](mailto:anne.guerry@stanford.edu)) - -Lisa Mandle ([lmandle@stanford.edu](mailto:lmandle@stanford.edu)) - -# Abstract - -We propose a new model—the Urban Mental Health Model—for inclusion in -the InVEST suite to estimate how urban nature (e.g., greenspaces) -contributes to improved mental health outcomes. This model addresses a -key technical gap in the current InVEST toolkit by directly linking -nature exposure to mental health outcomes such as depression and anxiety -using effect sizes derived from recent meta-analyses [(Liu et al. -2023)](https://www.zotero.org/google-docs/?qmGvGj)(Li et al., 2025). -The model relies on widely available global datasets—including NDVI, -tree canopy cover, land use and land cover, gridded population, and -baseline mental health prevalence rates—making it applicable to cities -worldwide. The basis for the model has been tested in several research -case studies, including in San Francisco and Italy [(Giannico et al. -2024)](https://www.zotero.org/google-docs/?UdWRjb), demonstrating -its ability to estimate preventable mental health cases and associated -societal cost savings under alternative greening scenarios. This tool -also builds upon and extends the Urban Nature Access model by providing -quantitative estimates of health benefits, supporting more targeted and -equity-informed urban planning. Interest in this model is growing -rapidly across global partners, including the Global Gross Ecosystem -Product (GEP) project. While already operational as a standalone module -(See the [design -doc](./pep-0013/invest-mental-health-model-design-doc-v0.3.0.docx), -full integration into InVEST will enhance usability, allow batch -processing, and improve accessibility for a global audience. This -proposal falls under the category of model development. - -# Motivation - -A core motivation behind the development of the InVEST model suite is to -empower decision-makers and urban planners with tools to quantify how -different forms of natural capital—such as water bodies, forests, and -parks—support human well-being through ecosystem services like carbon -sequestration, urban cooling, and flood risk reduction. These insights -enable governments and organizations to make informed, strategic -investments in nature that sustain and enhance the flow of benefits to -people over time. - -However, there is currently no InVEST model that explicitly quantifies -the mental health benefits provided by urban nature. Given the -increasing recognition of mental health as a critical component of -public health—and the growing body of evidence linking greenspace -exposure to improved mental well-being—this represents a significant gap -among the InVEST models [(Bratman et al. -2019)](https://www.zotero.org/google-docs/?wMb8gY). The proposed -Urban Mental Health Model addresses this need by providing a mechanism -for cities to assess how changes in urban greening can influence -population-level mental health outcomes and reduce societal healthcare -costs related to mental disorders. By offering spatially explicit -estimates of these benefits, the model can inform more targeted, -equitable, and cost-effective urban greening strategies. - -This model builds on and complements the Urban Nature Access model, -which evaluates the spatial distribution of greenspace supply relative -to population demand within cities. While the Access model identifies -areas with over- or under-provision of greenspace, it does not link this -access to concrete health outcomes such as depression or anxiety. The -model fills this critical gap by providing a direct, quantifiable link -between residential greenspace exposure and mental health benefits, -offering a novel contribution to the InVEST toolkit (criterion: -novelty). - -Ultimately, this model will help cities better design, prioritize, and -implement urban nature interventions that advance both environmental and -public health goals—especially in underserved communities where green -infrastructure investment can yield the greatest human impact. - -## Novelty: - -Previous InVEST models provide estimates of existing ecosystem services -and can also create scenarios for future changes. However, the potential -effect of current and future ecosystem services on human health is not a -part of output from the models. Instead, this has to be inferred but -using other data and science linking ecosystem services to human health -outcomes. The InVEST Urban Mental Health Model will be the first InVEST -model that can directly measure the effect of existing and changes in -ecosystem services like urban nature on human health, in this case -mental health. - -The estimates for the association between greenspace indexes and mental -health outcomes is based on comprehensive meta-analyses of studies that -have been published in peer-reviewed scientific journals -[(Rojas-Rueda et al. 2019; Liu et al. -2023)](https://www.zotero.org/google-docs/?1xcg1S). The model -provides users with three flexible options for estimating changes in -nature exposure and the associated health outcomes, allowing adaptation -to a variety of planning and research contexts. For example, users can -define a tree cover target to simulate a greening scenario, in which -tree canopy cover and Normalized Difference Vegetation Index (NDVI) -serve as the primary inputs. Alternatively, users may provide baseline -and future (or counterfactual) land use/land cover (LULC) maps to -estimate changes in nature exposure based on projected or proposed -landscape transformations. - -Users can select a range of mental health outcomes—such as depression or -anxiety as outcomes in the model. These outcomes are assessed using -widely recognized clinical and self-report instruments. For example, the -exemplified depression indicator was measured using the Center for -Epidemiologic Studies Depression Scale (CES-D), the Patient Health -Questionnaire (PHQ), the Diagnostic and Statistical Manual of Mental -Disorders, Fourth Edition (DSM-IV) criteria, the Geriatric Depression -Scale (GDS), the Beck Depression Inventory (BDI), the Hospital Anxiety -and Depression Scale—Depression subscale (HADS-D), the Four-Dimensional -Symptom Questionnaire (4DSQ), and the Inventory of Depressive -Symptomatology (IDS). These validated tools allow for robust and -comparable assessments of mental health across diverse populations and -study contexts. - -## Usability: - -To maximize the model’s usability and global applicability, we have -designed the Urban Mental Health Model to rely primarily on publicly -available and widely used datasets. This ensures that users from a -variety of institutional, geographic, and technical backgrounds can -apply the model with minimal barriers. Below, we describe the core input -data required to run the model: - -- **Administrative boundaries (vector)**: A polygon layer representing - the spatial units for analysis. These can range from an entire city to - subdivisions such as neighborhoods, districts, or census tracts. This - spatial structure enables aggregation and comparison of population - exposure and health outcomes. - -- **Spatial population data (raster)**: Global population datasets such - as WorldPop (www.worldpop.org) offer gridded population estimates at - resolutions as fine as 100 meters. More localized datasets may also be - used to improve accuracy and context relevance. - -- **NDVI (raster)**: NDVI serves as the core proxy for nature exposure - in the model. Freely available from multiple sources, including Google - Earth Engine, MODIS - (https://modis.gsfc.nasa.gov/data/dataprod/mod13.php), and Sentinel-2, - NDVI data capture the relative abundance and density of vegetation - across the study area. - -- **Tree canopy cover (raster)**: Tree cover provides an additional - measure of green infrastructure and exposure quality. Global datasets - such as the Global Tree Canopy Cover Version 4 - (https://gee-community-catalog.org/projects/global_tcc/) offer - consistent and free access to tree canopy estimates at high - resolution. - -- **LULC data (raster or vector):** These datasets offer additional - context on greenspace types and urban environments. Sources include - national datasets like NLCD for the U.S. (https://www.mrlc.gov/data) - and global sources such as ESA WorldCover - (https://esa-worldcover.org/), which provide LULC information at high - spatial resolution. - -- **Baseline health risk data (vector)**: Spatially explicit prevalence - rates for mental health outcomes (e.g., depression, anxiety,) are - essential for calculating preventable cases. These can be obtained - from local or national health agencies such as the Centers for Disease - Control and Prevention (CDC), or global sources where available. If - health data are in tabular format, they can be joined to the - corresponding spatial administrative units. Where high-resolution data - are unavailable, users may apply rates from broader regional levels as - approximations. - -- **Health effect size table (.csv or .xlsx)**: We provide example - effect sizes derived from a global meta-analysis, including measures - such as risk ratios or odds ratios for various outcomes. Users are - encouraged to substitute these with region-specific dose-response - functions where available, to reflect local epidemiological data. - -- **Health cost table (.csv or .xlsx)**: To estimate economic benefits, - we include a sample data with country- and illness-specific societal - costs per case (in 2018 USD PPP). Users may input more detailed, local - cost estimates if available. For global or cross-country comparisons, - we recommend harmonizing cost units to ensure consistency across - regions. - -Thanks to the use of open-access and globally available datasets, this -model is applicable to the vast majority of cities worldwide. Further -guidance on required and optional inputs is available in the model’s -Design Document, referenced under the Specification section. - -## Demonstrated interest: - -The overarching goal of the InVEST model suite is to “map and value the -goods and services from nature that sustain and fulfill human life.” To -date, InVEST models have enabled users to quantify several ecosystem -services, for example, coastal flood mitigation, soil retention, and -urban cooling. While these outputs can be used to infer potential -benefits to human health, doing so requires users to possess -domain-specific knowledge and access to external datasets that link -environmental changes to health outcomes. This limits broader -accessibility and undercuts the integrated decision-support value InVEST -seeks to provide. The proposed Urban Mental Health Model aims to close -this gap by directly estimating the relationship between urban nature -and mental health outcomes. This is a timely and critical addition. Poor -mental health imposes a substantial burden globally, with estimated -costs reaching \$5 trillion USD per year by 2019—approximately 3.8% of -global GDP [(Arias et al. -2022)](https://www.zotero.org/google-docs/?4wI9bc)—and this burden -is expected to continue rising. Urban green space, including street tree -biodiversity and neighborhood greenness, has been consistently linked to -improved mental health outcomes, such as reduced antidepressant usage -[(Stenfors et al. -2024)](https://www.zotero.org/google-docs/?4MfSsr). By modeling -these relationships, the new InVEST module will allow planners, -researchers, and decision-makers to quantify how investments in urban -nature can mitigate mental health challenges at both neighborhood and -city scales. - -There is strong and growing interest in such a model, both within the -Natural Capital Project and among external collaborators. Key urban -planning and conservation questions—such as where changes in urban -nature will influence mental health and whom they will benefit—can be -addressed more directly with this tool. The preliminary framework has -been applied to urban projects in Guangzhou [(World Bank -2022)](https://www.zotero.org/google-docs/?S7hbhx), San Francisco -(on going), and Italy [(Giannico et al. -2024)](https://www.zotero.org/google-docs/?XfGr83), and interest has -expanded beyond our immediate network. For example, participants in -InVEST training workshops in 2023 and 2024 from diverse global -institutions expressed keen interest in the model’s release. Notably, -there has been a formal request to include this model in the Global -Gross Ecosystem Product (GEP) project led by Steve Polasky—a -collaborative effort where we have committed to providing this -functionality. - -A beta version of the model was previously developed by the urban team. -While this version is functional and has been piloted in small-scale -applications, it suffers from limited computational efficiency, -unresolved bugs, and low transparency in implementation. As such, it is -not yet suitable for wide-scale adoption or integration with the broader -InVEST suite. There is a clear and pressing need for a robust, -well-documented, and user-friendly version of the Urban Mental Health -Model. Importantly, its development aligns with prior commitments we’ve -made to funders and partners, and it represents a natural evolution of -InVEST’s capacity to support equitable, health-oriented urban -sustainability planning. - -## Credibility: - -The Urban Mental Health Model builds on a growing body of empirical -evidence and has been developed and tested through multiple case -studies, demonstrating both its scientific rigor and practical -applicability. - -The model was first applied in a published case study in Italy -[(Giannico et al. -2024)](https://www.zotero.org/google-docs/?rR76WQ), which estimated -preventable premature deaths by increasing residential green space using -open-access greenness data (e.g., NDVI). This study supported the -framework’s ability to quantify health outcomes from urban nature -exposure and was published in the high-impact journal Nature -Communications, lending credibility to the model’s scientific -foundations. - -A second case study—currently underway in San Francisco, USA and led by -Yingjie Li—further refines the model to estimate preventable cases of -depression and the associated avoided healthcare costs resulting from -increased neighborhood greenness. This work builds upon the Italy -framework with enhanced methods and a broader set of input variables. A -manuscript describing this application is currently in preparation (Li -et al., in prep.). - -Additionally, an earlier version of the model was applied in Guangzhou, -China [(World Bank -2022)](https://www.zotero.org/google-docs/?k3kdyq). That predecessor -model used a fixed effect size derived from a single empirical study and -was not capable of estimating preventable cases or monetized health -benefits. In contrast, the current proposed model improves substantially -upon this early version by incorporating a meta-analytic effect size -from multiple studies, the ability to estimate spatially explicit -preventable mental health cases, and integration of country-specific -healthcare cost parameters for over 40 countries. - -We are also working in collaboration with the NatCap TEEMs (The -Earth-Economy Modelers) team at the University of Minnesota to ensure -accurate and consistent incorporation of health cost indicators. These -enhancements enable the model to support comparisons across different -urban greening scenarios, providing planners and policymakers with -actionable estimates of both health and economic co-benefits. - -# **Support** - -The Urban Mental Health Model is expected to require only minimal -ongoing support, consistent with the maintenance needs of most InVEST -models. Notably, the model's input data—such as LULC and demographic -layers—are not expected to require frequent updates, enabling stable, -long-term use without annual revisions. We provided sample effect size -data for depression and anxiety based on global meta-analyses. As time -and funding permit, our team may expand this dataset. Users are -encouraged to update the health effect size table to reflect other -health indicators or incorporate more granular local data, allowing for -flexible and context-specific applications. - -To support user adoption, a new entry will be added to the InVEST User’s -Guide, and a sample dataset—based on completed case studies such as San -Francisco—can be provided to facilitate testing and onboarding. - -Although the model has not yet been featured in formal training -workshops, aside from general announcements about its development, -dedicated training materials will be needed to support its inclusion in -the InVEST MOOC and other educational or capacity-building sessions. - -# Specification - -## Technical Details - -The design document for the Urban Mental Health Model is available -[here (version for public -comment)](./pep-0013/invest-mental-health-model-design-doc-v0.3.0.docx). -This document outlines the conceptual framework, data requirements, and -methodological steps of the model, using the San Francisco case study as -a reference application. It serves as a foundational resource for -understanding how the model links urban nature characteristics to -population-level mental health indicators. - -Both the model code and test dataset for the San Francisco case study -are publicly available on GitHub: -[https://github.com/natcap/invest-mental-health](https://github.com/natcap/invest-mental-health). -This repository includes a working prototype of the model and a curated -data folder containing: - -- A data inventory README file describing each input dataset, including - file name, format, description, source, spatial resolution, and any - preprocessing steps. - -- A list of sample data, including - - - Administrative boundaries at the district level (e.g., census - tract). - - - LULC rasters and LULC attribute table distinguishing multiple types - of land covers. - - - NDVI rasters and a Google Earth Engine script for generating NDVI - rasters from the Landsat image collection (1986–present). - - - Population data to allow spatial weighting of mental health - outcomes; - - - Health effect size table - - - Baseline health prevalence rate data - - - Health cost rate data. - -Together, these materials provide a transparent and reproducible example -for testing and adapting the model in other urban contexts. - -## Documentation - -- InVEST User Guide will be provided once the design document is - approved by PSC. - -- A presentation (PowerPoint) will be provided for training material and - graphics. - -## Sample data - -Sample data and related documentation (data sources, location of study -area) will be provided by [Yingjie -Li](mailto:YingjieLi.edu@gmail.com). +# Revising SDR Indicators + +Contacts: +* Primary: Rafa +* Contributors: Lisa, Adrian, Hector, Jesse, James, Stacie, Rafa, Doug, Emily + +## Abstract + +The SDR model is one of the most widely applied InVEST models (Mandle and +Natural Capital Project, 2021). Yet, it comes with a number of +assumptions and creates a number of output indicators that are deprecated, +poorly documented, and do not meet the current needs. This has also +led to a rising number of user forum inquiries about the +functioning of the model and how to interpret the resulting +indicators. This PEP results from an in-depth review of model +assumptions done by a group of expert NatCap users, scientists, and +software engineers, and aims at streamlining the SDR model by (1) +revising some indicators to reflect the conceptual understanding of the +science team about model processes, based on the current +state-of-science and (2) reducing the number of indicators to those +which are most useful to current users. + +## Motivation + +Two of the most widely appreciated benefits of sediment retention by vegetation +are 1) improved water quality from avoided sediment export from hillslopes to +waterways, and 2) maintenance of soil fertility from avoided topsoil erosion. +The current SDR model lacks indicators that clearly and comprehensively +represent these services, despite the demand for such indicators both in NatCap +applications and from users on our forum. This PEP would introduce two new +sediment retention indicators that more comprehensively capture the ecosystem +service being provided, one from the perspective of water quality and one from +the perspective of soil fertility. In the case of sediment retention for water +quality, we propose an indicator for sediment retention services for water +quality that captures the ability of vegetation to both keep sediment from +eroding and to trap sediment originating upslope. We also propose dropping +several current model outputs that do not address the service as directly and +are either (1) deprecated (were kept in the model at some point to ensure +backward compatibility), or (2) could be calculated by users +with a scenario approach (e.g., ask the user to run a “bare-soil” scenario, +rather than having it predetermined/fixed in the code), or (3) +do not fully represent what the PEP authors agreed that they should be +representing. These could still be calculated if desired from +intermediate outputs or by running an additional scenario. + +This proposal would additionally alter the current calculation of the +deposition and flux indicators that track trapping of sediment that +erodes onto a pixel in order to make them more consistent with the +conceptual processes the SDR model represents. Beyond those code +updates, this PEP would also update the User Guide to harmonize +terminology and improve clarity for users (including some new +visualizations and description of use cases). + +We thus propose that these revisions of SDR are better tackled through +a PEP (and joint effort of the science team), rather than a piece-meal +approach to solving individual problems with indicators and the User +Guide in response to user/staff requests. + + +The revised SDR model seems to be highly aligned with the general PEP +guidelines: + +* Actionable: The SDR model has been shown to be relevant to many different + stakeholders, decision problems, and scales +* Generalizable: The tool has been run from hyper-local case studies to global + scales +* Innovation: The revised model will produce new indicators which, based on our + own experiences and questions received on the User Forum, will be very useful + for decision support (e.g., Retention indicator) and that a normal user could + not easily calculate. The new indicators will further respond to issues that + have been repeatedly raised in the User Forum. +* Credibility: + * The proposed changes have been vetted by the science and software team, and + seem to be more aligned with the model's intention (e.g., as described in + the User Guide). + * Similar to current SDR, the revised indicators we propose are mostly + conceptual and hard to validate. Yet, the revised indicators are more aligned + with the intention of what is described in the User Guide, avoid violating + sediment mass balances (e.g. that more sediment is retained than what is + eroded) and allow users to track sediment mass balance through the model in + a way that was not possible before. +* Generalizability: as per above, the model has been shown to be useful in many + settings and decision contexts. +* Feasibility: Calculation of all indicators will be possible within the + existing model framework ([James has already implemented these changes in a + fork of InVEST](https://github.com/natcap/invest/compare/main...phargogh:task/sdr-retreat-2022-03-22-rework-downslope-deposition-equations)). + +Additional criteria that might be relevant + +* Demonstrated interest: There are many threads on the forum where users ask + for clarification regarding existing indicators +* Novelty: The proposed changes will make the model more consistent compared to + what we have and will produce indicators that are otherwise hard to obtain by + users from “raw” SDR outputs. +* Maintenance: The models will be maintained as part of InVEST, just like + previous versions of SDR. Usability: SDR has been proven to be usable across + scales, geographies, and decision making contexts. + +## Support + +No additional support is needed beyond what is done for InVEST. Some additional +help might be required for forum users inquiring about changes, although we +expect this to be offset by the reduction in time required to respond to forum +posts asking for clarification on the current set of model outputs/indicators. + +## Specification + +This PEP proposes the following changes, which we outline here and specify in +more detail below: + +1. **Update the calculation of intermediate parameters R (deposition) and F (flux).** + Currently R and F are calculated such that sediment that erodes from a pixel + (as calculated by the Revised Universal Soil Loss Equation or RUSLE) can + then be trapped by vegetation on that same pixel. This is conceptually + inconsistent: the role of vegetation for reducing erosion and sediment + runoff from a pixel is already captured in RUSLE’s C factor (Wischmeier and + Smith, 1978). By allowing for immediate sediment trapping on + the same pixel, this amounts to double-counting the role of vegetation. We + propose updating the calculation so that all sediment that erodes from a + pixel goes to the next downslope pixel in proportion to the proportion of + water flowing into the next downslope pixel, where it can either be trapped + or continue flowing downslope. This change will not affect estimates of + water quality for any given scenario relative to the current formulation of + the model; it will lead to some change in the attribution of where sediment + retention services are being provided on the landscape. Rename the + indicator “R” (which is also used in the USLE equation) to “T” for “trapped + sediment”, or “trapping”. +2. **Create a new output and indicator for sediment retention services for + water quality called "Avoided Export".** + The raster output represents vegetation’s contribution to both avoided + erosion from a pixel and trapping of sediments originating on upslope + pixels, e.g., the service of a pixel from the perspective of downstream + water user. +3. **Create a new output and indicator for sediment retention services for soil + fertility called "Avoided Erosion".** + This raster output represents avoided erosion benefits to that pixel, e.g., + from the perspective of maintaining soil fertility. +4. **Drop 2 legacy sediment retention indices currently included in the model.** + One of the frequently asked questions on the User Forum is what metric + people should use for the sediment retention “service”, and we have not + historically had a solid answer, because neither of the “retention” outputs + are very useful. They are indices only (not quantities), compared against a + hypothetical entirely barren landscape (which is unrealistic), and one of + the indices has no explanation at all given in the User Guide, so no current + NatCapper actually knows what it means. Removing these, and adding clear + guidance about calculating retention to the User Guide (see #5) would + significantly reduce confusion. +5. **Updates to the User's Guide** + to reflect the above changes, harmonize terminology and variable names and + provide a conceptual figure for visualizing the modeling steps and related + outputs. We will also more clearly explain what’s happening in the different + modeling steps and present options and use cases for quantifying the + retention “service” from model outputs, informed by common questions on the + User Forum. + +The required technical changes to address those 5 points are detailed below: + +1. **Update the calculation of the intermediate parameters R (deposition) and F (flux).** + * Update the $R$ (deposition) calculation so that it does not include export + from pixel i. Basically removing the $E_i’$ from the equation below so that a + pixel cannot retain the sediment that erodes directly from itself (note: + equation numbers are matched to the User Guide). Thus from + + $$ R_i = dR_i \cdot \left(\sum_{j \in {pixels\ that\ drain\ to\ i}}F_j \cdot p(i,j)\right) + E_i' $$ + + Revise to + + $$ R_i = dR_i \cdot \left(\sum_{j \in {pixels\ that\ drain\ to\ i}}F_j \cdot p(i,j)\right) $$ + + Rename the indicator from “R” (which is used in the USLE equation) to “T” + for “trapped sediment”, or “trapping”. + + * Update $F$ (flux) calculation so that all export/erosion originating from + that pixel goes on to the next downslope pixel or pixels (rather than just + a fraction). Thus from + + $$ F_i = (1 - dR_i) \cdot \left(\sum_{j \in {pixels\ that\ drain\ to\ i}}F_j \cdot p(i,j)\right) + E_i' $$ + + Revise to + + $$ F_i = (1 - dR_i) \cdot \left(\sum_{j \in {pixels\ that\ drain\ to\ i}}F_j \cdot p(i,j)\right) $$ + + In addition, we would rename variable $R$ (deposition) to $T$ (for + sediment trapping), to avoid confusion with the $R$ variable + name already used previously in the calculation of the $RUSLE$, and update + variable names in the User Guide for consistency and clarity. +2. **Create new ecosystem service indicator output (raster) called “ Avoided Export”** + representing vegetation’s contribution to avoided erosion from a pixel and + trapping of sediments originating upslope (the service from the perspective + of a water user): + + $$ TR_i = (RKLS_i - USLE_i) \cdot SDR_ + R_i $$ + + Where: + * $TR_i$ is Total Retention + * $RKLS$ is basically $USLE_i$ minus the $C$ and $P$ + factors which represent the benefits of vegetation and good management + practices. + + The watershed-level outputs of the model would also be updated to include + this indicator as follows: remove "sed_retent" and add the sum of "Total + Retention" per polygon and the sum of "Local Erosion Control" per polygon. +3. **Create new ecosystem service indicator output (raster) called “Avoided Erosion”** + representing avoided erosion benefits to that pixel, from the perspective of + soil loss: + + $$ AE_i = RKLS_i - USLE_i $$ + + note (in the User Guide) that $R_i$ ($T_i$ in the new nomenclature) + could be added separately if trapping of sediment originating upslope could + mitigate erosion on a downslope pixel (e.g., if high quality soil is eroded + from upslope) +4. **Drop 2 legacy sediment retention indices currently included in the model** + Described in the section "Legacy" in the user's guide. +5. **Updates to User Guide (can happen separately from the code changes requested above):** + * Update the User Guide to reflect changes in equations 78 and 79 (and + associated, more explanatory, text) + * Add use cases to the User Guide for applying different outputs + * Add a figure showing conceptually what the different variables in the + model are and how they relate to a toy landscape and which variables + are output as the retention indicators given above. + + ![The fate of sediment](pep-0010/fate-of-sediment.png "The fate of sediment") + +## Open Issues + +There is an additional issue with the LS factor, which James will address +separately. The current LS factor values are very high compared to what is +obtained from other software, e.g., SAGA. The SAGA LS factor also results in +more realistic results when compared to sediment observations. + +## References +Mandle, Lisa and Natural Capital Project. (2021). Database of publications +using InVEST and other Natural Capital Project software. Stanford Digital +Repository. Available at: https://purl.stanford.edu/bb284rg5424 + +Wischmeier, W. H., & Smith, D. D. (1978). Predicting rainfall erosion losses - +a guide to conservation planning. Predicting Rainfall Erosion Losses. United +States Department of Agriculture. -# References -[Arias D, Saxena S, Verguet S (2022) Quantifying the global burden of -mental disorders and their economic value. eClinicalMedicine 54:. -https://doi.org/10.1016/j.eclinm.2022.101675](https://www.zotero.org/google-docs/?ouZCCy) -[Bratman GN, Anderson CB, Berman MG, et al (2019) Nature and mental -health: An ecosystem service perspective. Science Advances 5:eaax0903. -https://doi.org/10.1126/sciadv.aax0903](https://www.zotero.org/google-docs/?ouZCCy) -[Giannico OV, Sardone R, Bisceglia L, et al (2024) The mortality impacts -of greening Italy. Nat Commun 15:10452. -https://doi.org/10.1038/s41467-024-54388-7](https://www.zotero.org/google-docs/?ouZCCy) -[Liu Z, Chen X, Cui H, et al (2023) Green space exposure on depression -and anxiety outcomes: A meta-analysis. Environmental Research -231:116303. -https://doi.org/10.1016/j.envres.2023.116303](https://www.zotero.org/google-docs/?ouZCCy) - -[Rojas-Rueda D, Nieuwenhuijsen MJ, Gascon M, et al (2019) Green spaces -and mortality: a systematic review and meta-analysis of cohort studies. -The Lancet Planetary Health 3:e469–e477. -https://doi.org/10.1016/S2542-5196(19)30215-3](https://www.zotero.org/google-docs/?ouZCCy) - -[Stenfors CUD, Rådmark L, Stengård J, et al (2024) More green, less -depressed: Residential greenspace is associated with lower -antidepressant redemptions in a nationwide population-based study. -Landscape and Urban Planning 249:105109. -https://doi.org/10.1016/j.landurbplan.2024.105109](https://www.zotero.org/google-docs/?ouZCCy) - -[World Bank (2022) Assessment of Key Ecosystem Services Provided by the -Haizhu National Wetland Park in Guangzhou, China. World Bank, -Washington, DC](https://www.zotero.org/google-docs/?ouZCCy) - -\## manually added references later - -Li, Y., Mao, Y., Mandle, L., Rydström, A., Remme, R., Lan, X., Wu, T., -Song, C., Lu, Y., Nadeau, K., Meyer-Lindenberg, A., Daily, G., Guerry, -A. (2025) Global meta-analysis reveals broad spectrum mental health -benefits of urban nature exposure. Nature Cities. diff --git a/pep-0010/fate-of-sediment.png b/pep-0013/fate-of-sediment.png similarity index 100% rename from pep-0010/fate-of-sediment.png rename to pep-0013/fate-of-sediment.png diff --git a/pep-0014.md b/pep-0014.md new file mode 100644 index 0000000..d7a28d7 --- /dev/null +++ b/pep-0014.md @@ -0,0 +1,185 @@ +The Software Team + +Primary contact: Dave Fisher - davefisher@stanford.edu + +# Abstract + +This is a proposal to deprecate two InVEST models: Finfish Aquaculture & +Fisheries. These two are proposed because they meet at least three of +the four criteria for deprecation given by the PSC: 1) data indicates +they are not being used 2) the state of their code makes them an +unusually high burden to maintain, and 3) they lack scientific support +within NatCap. + +In this proposal’s [Software Team Burden](#software-team-burden) +and [User Demand](#_ar8l6i7vth7w) sections, we illustrate that +these two models have a particularly poor “maintenance-to-usefulness” +ratio. That is, they are equal or more burdensome to maintain than the +average InVEST model, and they are used by the community much less. + +“Deprecate” has a specific meaning: to end maintenance, support, and +distribution of a piece of software at a specific date in the future. +Deprecated InVEST models are still available to download as part of +older releases of InVEST, but they are not supported/maintained. + +The deprecation date is not too important, but we propose it coincide +with the next non-bugfix release of InVEST (version 3.10). + +# Motivation + +Software team resources are finite. As NatCap and the PSC approve new +software projects & features, the overall maintenance burden grows. It +is worth assessing if we are maintaining software that is not useful, +and if we are, we should consider deprecating that software to free up +resources for higher impact projects. + +**Criteria for evaluating models or tools to be deprecated (as given by +the PSC):** + +- ES science credibility: has the science changed/advanced such that + this no longer represents our current understanding + +- User demand: actionability of information for application/uptake, + current usage stats - how “popular” of a model is it? + +- Science support available - does anyone on staff have the + knowledge/expertise to maintain and answer questions + +- Software team burden: user support required, how broken is it, what % + time is required to maintain it + +## Software Team Burden + +There are a number of maintenance tasks that must be applied to all +InVEST models individually. Here we list some typical examples from the +recent past and some expected in the near future. Tasks like this will +always be part of the maintenance workload, so it’s important to weigh +these costs against the benefits of publishing the software (see +[User Demand](#_ar8l6i7vth7w) section). + +- Migrating all code (source code and test code) from python2 to + python3. *Complete*. This typically involved dozens of fixes per model + wherever the python API changed. + +- Compatibility changes after major changes to libraries we depend on. + *Ongoing*. Similar to the python migration, these tasks are smaller in + scale but happen more frequently. All InVEST models use python + libraries like gdal, pygeoprocessing, pandas, and others. Whenever + they have non-backward-compatible changes, we are forced to update how + we use these libraries across InVEST. + +- New cross-model InVEST features. *Ongoing*. Sometimes we need to add + structure to every model in order to support features like: + + - input data validation + + - auto-generated User’s Guide content + + - new user-interface (the Workbench) + +- Foreign language translations. *Upcoming*. There are maintenance costs + in the form of code changes within every InVEST model to allow the + translated text substitutions. But in this case there are also clear + monetary costs of the translation itself for every additional model & + User’s Guide chapter to be translated. + +The Finfish & Fisheries models stand out as more burdensome to maintain +than most InVEST models because their software design has never really +been modernized in the same way we have done for other models. They have +been brought along for the compatibility changes, but their +implementations are needlessly complex relative to the actual +computations they need to do. Basically, these models are overdue for a +refactor if we were to keep them around. + +For these models, nearly all changes to the source code in recent years +has been forced maintenance -- the type described above that must be +applied to all models -- rather than model-specific bugfixes or +enhancements that are common for well-used models. + +**Data from our invest github repository:** + +- Finfish - 100% of changes were forced maintenance in past 6 years + ([github + history](https://github.com/natcap/invest/commits/main/src/natcap/invest/finfish_aquaculture)) + +- Fisheries - 1 non-forced maintenance bugfix in 3 years ([github + history](https://github.com/natcap/invest/commits/main/src/natcap/invest/fisheries)) + +## + +## User demand: + +**Data from invest usage stats.** Each time someone runs an invest model +from the user-interface, we log the model, version, date & time, in a +database[^1]. Here are some plots of use over time: + +#### Finfish: 0 runs since January, 2021: + + + +#### Fisheries: 0 runs since December, 2020, except 2 runs in June, 2021: + + + +*The y-axis is different from the previous plot because Fisheries +monthly runs peaked at levels similar to the most popular models before +dropping to 0!* + +*Interactive versions of these plots for all InVEST models are here:* +[https://nbviewer.jupyter.org/github/davemfish/invest-usage-stats/blob/main/invest_usage_stats.ipynb](https://nbviewer.jupyter.org/github/davemfish/invest-usage-stats/blob/main/invest_usage_stats.ipynb) + +**Data from our forum**, where we tag all threads with the model that is +being discussed. These counts go back ~2.5 years, since we switched to +the current forum platform. Counts of all models are here: +[https://community.naturalcapitalproject.org/tags/](https://community.naturalcapitalproject.org/tags/) + +- Finfish Aquaculture - 0 threads + +- Fisheries - 2 threads + +*Forum data does not give a complete picture of demand, it’s more a +measure of demand for support, which might be a function of overall +model popularity, ease of use, etc.* + +## Science Support available: + +According to our spreadsheet: +[https://docs.google.com/spreadsheets/d/143HM51bD92NL6K6gs5Wialej6QCqFXDTpXoKRcQ-9D0/edit#gid=0](https://docs.google.com/spreadsheets/d/143HM51bD92NL6K6gs5Wialej6QCqFXDTpXoKRcQ-9D0/edit#gid=0) + +**We do not have a science lead for these models.** The spreadsheet +references Katie (now an alum), but also includes the caveat: +“We don't have the right person on staff to be the +"Science Lead", so have someone who is assigned to fill in the gap. +\[They\] can be thought of as on the hook (with help from the +peer-reviewer), but if heavy stuff comes up, this is a gap.” + +## ES Science credibility: + +No issues about scientific credibility were raised in this proposal +because the authors are not experts in these domains and have not +attempted to assess the science in these models. + +It would be valuable to get scientific feedback on these models. We may +find them to be totally valid, and that could be considered a reason to +continue maintaining them despite low usage numbers. + +# Support + +Unlike basically any other PEP, this one has no long-term support costs! +Up-front costs include about a day of engineer time at or near the +future “deprecation date” to modify repositories, documentation, and +website. + +# Specification + +Not Applicable + +# Open Issues + +# References + +- + +[^1]: Since the usage logging endpoint is on a google-hosted URL, it is + highly likely that the majority of InVEST users in China are not + recorded by this system or represented in the usage stats. diff --git a/pep-0014/Proposed_InVEST_Deprecations_Finfish_and_Fisheries.docx b/pep-0014/Proposed_InVEST_Deprecations_Finfish_and_Fisheries.docx new file mode 100644 index 0000000..77071b2 Binary files /dev/null and b/pep-0014/Proposed_InVEST_Deprecations_Finfish_and_Fisheries.docx differ diff --git a/pep-0015.md b/pep-0015.md new file mode 100644 index 0000000..befb9ac --- /dev/null +++ b/pep-0015.md @@ -0,0 +1,102 @@ +[This PEP has been modified from the origainl PEP Google Doc](https://docs.google.com/document/d/1w_B0GYc4TPR4wARbRC3satC3H7w9RT9woIfXBl1Fyh4/edit?usp=sharing) + +# Platform Enhancement Proposal: Deprecate the GLOBIO model + +## Contacts + +Software Team, primary contact Emily Soth (esoth@stanford.edu) + +## Abstract + +This is a proposal to deprecate the InVEST GLOBIO model. + + +As described below, I argue that this model meets all the deprecation criteria. +But the primary argument for deprecating this model is that it’s been made obsolete. +Earlier this year, PBL Netherlands (the creator of GLOBIO) published an open +source command line tool for GLOBIO. It’s hard to justify continuing to +maintain our outdated implementation when a reference implementation (i.e., +a definitive version reflecting the designers’ intent) is available. + +## Motivation + +**Criteria for evaluating models or tools to be deprecated:** + * ES science credibility: has the science changed/advanced such that this + no longer represents our current understanding + * **The InVEST model implements an outdated version of GLOBIO.** GLOBIO is a + biodiversity model published by PBL Netherlands Environmental Assessment Agency. + The InVEST GLOBIO model is an implementation of GLOBIO version 3 + (paper published 2009). PBL has since released multiple minor version + updates (3.x), and then a version 4 in 2019. + * **It no longer provides new functionality.** An open source GLOBIO4 command + line tool is now available to install from the + [GLOBIO4 source code repository on GitHub.](https://github.com/GLOBIO4/GlobioModelPublic) + Since that was made available, the InVEST model + no longer meets the novelty criteria for a new model. [a] + * A GLOBIO3 reference implementation may have once been available, but I + wasn’t able to find it online. The InVEST GLOBIO model was created + because at the time, the reference GLOBIO tool was difficult to run + and/or didn’t fit into existing workflows. It’s not clear if it would + meet our criteria for a new model today. + + + * User demand: actionability of information for application/uptake, current + usage stats - how “popular” of a model is it? + * Usage logging: Per our usage logging statistics, GLOBIO is **one of the + least used models**. Only Wave Energy, and Urban Stormwater (which has + been around for less than a year), have had fewer runs. This chart + shows monthly GLOBIO runs over time compared against highly used models. + * It’s also worth noting that we have not received any requests to + update the model, even though it’s been out of date for a decade. + + + ![InVEST model usage](pep-0011/invest-model-usage.png "InVEST model usage") + + + * Science support available - does anyone on staff have the knowledge/expertise + to maintain and answer questions + * **Science and software support is lacking**. The [InVEST Model Supporters + page](https://github.com/natcap/invest/wiki/InVEST-Model-Supporters) + lists Becky as the primary contact for GLOBIO. I've reached out to + get her opinion, and she supports deprecating the model. Parts of the + model documentation and user guide are unclear, and the software team + doesn’t understand it well enough to make significant updates or refactor + the code if that were needed. + * Software team burden: user support required, how broken is it, what % time + is required to maintain it + * Very little user support is required because the model is rarely used. + There are just 4 questions tagged with GLOBIO on our forum. The last + was almost a year ago. + * There are three open issues related to GLOBIO: + * It expects that specific LULC codes 8 and 9 will be provided + ([#771](https://github.com/natcap/invest/issues/771)) + * It only accepts .tif and .shp inputs + ([#632](https://github.com/natcap/invest/issues/632)) + * The test suite is inadequate + ([#409](https://github.com/natcap/invest/issues/409)) + * Some maintenance and updates require modifying all models, so keeping + this model around has an ongoing cost. + + +## Support +Deprecating this model will slightly reduce the long term maintenance and support +required for InVEST and the user’s guide, as well as translation. + + +## References +_Original GLOBIO 3 paper_: +Alkemade, R., van Oorschot, M., Miles, L. et al. GLOBIO3: A Framework to +Investigate Options for Reducing Global Terrestrial Biodiversity Loss. +Ecosystems 12, 374–390 (2009). +https://doi-org.stanford.idm.oclc.org/10.1007/s10021-009-9229-5 + + +_GLOBIO 4 paper_: +Schipper, AM, Hilbers, JP, Meijer, JR, et al. Projecting terrestrial +biodiversity intactness with GLOBIO 4. Glob Change Biol. 2020; 26: 760– 771. +https://doi-org.stanford.idm.oclc.org/10.1111/gcb.14848 + +### Google Doc comments +[a] This seems the main reason for deprecation: if there is an open source, +scriptable version provided by PBL, who are the main developers, it seems +futile for us to maintain an outdated parallel version. diff --git a/pep-0011/invest-model-usage.png b/pep-0015/invest-model-usage.png similarity index 100% rename from pep-0011/invest-model-usage.png rename to pep-0015/invest-model-usage.png diff --git a/pep-0016.md b/pep-0016.md new file mode 100644 index 0000000..37cef45 --- /dev/null +++ b/pep-0016.md @@ -0,0 +1,207 @@ +[This PEP has been modified from the origainl PEP Google Doc](https://docs.google.com/document/d/1cyqcHuyhtW3-IkJVdzNDamJx90I4k1raDJRKzrfv6eM) + +PEP template Version 0.2 approved by PSC on Oct. 30, 2020 + +Platform Enhancement Proposal (PEP) + +# Supporting both D8 and MFD algorithms in InVEST routed models and tools + +Note: Expect iteration on this to get to the right level of detail +necessary to assess the science/software complexity of the request. + +See the PEP guidelines +[here](https://docs.google.com/document/d/1GOZKXsNfP7PHTjhKRgzx6bmcJHwOloyrSDvkOfx7fhk/edit?usp=sharing) +for the criteria by which PEPs will be evaluated. + +# Contacts + +Stacie is the main contact, with input from James, Dave, Rafa, Lisa and +Jesse. + +# Abstract + +The routed freshwater models (Seasonal Water Yield (SWY), Nutrient +Delivery Ratio (NDR), and Sediment Delivery Ratio (SDR)) and related +tools (DelineateIt (DI) and RouteDEM (RD)) are not consistent in their +use of routing algorithm. This PEP would make these models and tools +consistent, and enhance functionality, by updating them all to provide a +user-selectable option between D8 and multiple flow direction (MFD) +routing algorithms. + +# Motivation + +As of InVEST 3.13.0, the routed freshwater models (NDR, SDR, and SWY) +use the MFD routing algorithm, and do not provide any other algorithm +options. Meanwhile, DelineateIt only uses the D8 algorithm, and does not +provide any other options, and RouteDEM provides the option to use +either MFD or D8. + +Along with simply being inconsistent, these differences lead to several +practical issues. Importantly for modeling, when using DelineateIt to +create watersheds that are input to a routed freshwater model, it is +possible/likely that its D8 algorithm creates streams and derivative +watersheds that are different from the freshwater model's MFD result. +This would then cause a spatial mismatch between the watershed input and +the hydrologic network generated by SWY/NDR/SDR, and thus lead to +erroneous aggregated results. + +It's also confusing for users. The algorithm difference between tools +has come up several times on the User Forum, for example +[here](https://community.naturalcapitalproject.org/t/in-the-swy-model-is-it-possible-to-use-simple-d8-flow-direction-instead-of-mfd/1791) +and +[here](https://community.naturalcapitalproject.org/t/why-ndr-model-generate-streams-bigger-than-routedem/2028). + +There are reasons to support both algorithms. MFD had historically been +adopted for the freshwater models, since conceptually MFD provides a +better representation of hydrologic processes than D8. But some seminal +papers have shown that there is little to no benefit of MFD for medium +resolution DEMs (on the order of 10s of meters), which is the resolution +most often used for InVEST modeling. MFD can be useful to create a good +water mask because it spreads flow out nicely over flat areas such as +lakes and broad stream channels. However, this same spreading comes with +negative effects, often creating streams that are much wider than +reality (especially when considering that a pixel is usually at least 30 +meters in width). Not only does this look visually incorrect in +resulting maps, but it's usually the case that there is no model output +within the stream network, so we are missing results in the very +important riparian zone, and sometimes over very large areas of the +landscape. This makes it difficult, if not impossible, to model riparian +buffers in a land cover scenario (which is commonly done), with any hope +of being realistic relative to the actual landscape, or the land +use/land cover map. This problem has come up several times during the +course of NatCap projects, and has been asked about [on the user +forum](https://community.naturalcapitalproject.org/t/riparian-buffer-values-issues-because-of-ndr-output-streams-wider-than-in-reality/2269). + +D8 is standard in hydrology modeling, and generally creates streams that +are much thinner, by definition 1 pixel in width, which is what users +expect, as well as allowing for better representation of the riparian +zone. There is an existing related GitHub enhancement - [Allow +DelineateIt to do MFD watershed +delineation](https://github.com/natcap/invest/issues/440) - +which includes "In practice when we\'ve published global results run +with MFD we\'ve had to re-run them with D8 to be comparable to others." +So providing the option to choose between algorithms, and documentation +to help users choose, will allow us to select the option that is better +suited to our modeling purposes, and provide compatibility with +non-InVEST models. + +Following is a comparison of the stream network created by RouteDEM with +D8 and MFD, same DEM and threshold flow accumulation, in our Gura sample +data watershed. The D8 streams are 1-3 pixels in size, while the MFD +streams are much wider, which doesn't match reality. Also note that the +networks look somewhat different, so the difference in algorithm affects +not only the width, but also the stream shape and tributaries. The third +image shows the area of MFD streams overlaid with the land use/land +cover map, illustrating how much of the landscape will end up with +modeled NoData values within the MFD stream network. + +![RouteDEM D8](pep-0012/RouteDEM-D8-streams-Gura.png) + +![RouteDEM MFD](pep-0012/RouteDEM-MFD-streams-Gura.png) + +![MFD stream area](pep-0012/MFD-stream-area-lulc-relative.png) + +As an enhancement to existing models, this PEP follows these Guidelines: + +- **Actionable**: Applies to some of our most-used models. + +- **Credibility**: The D8 algorithm is very commonly used for + > hydrologic modeling, and users have specifically asked for a D8 + > option, due to it being a standard, and its creation of a + > narrower/more intuitive stream network. + +- **Generalizability**: Either algorithm may be used with any DEM in + > any area of interest. + +- **Feasibility**: InVEST code already exists for implementing both D8 + > and MFD algorithms, and RouteDEM already provides the option to + > choose between them in the Workbench user interface. + +# Support + +The InVEST User Guide chapters for all 5 tools will need to be updated +to reflect the algorithm options, provide examples, and note the pros +and cons of each. This is a one-time task. + +Maintaining parallel implementations of custom routing functions in +InVEST will require additional maintenance effort over the long term. + +Providing both routing options may reduce NatCap analyst and software +team time needed to explain the current limitations/mis-match and +workarounds on the forum. + +No additional support is anticipated, beyond current InVEST, User Guide, +and user forum maintenance. + +# Specification + +The following software changes would need to be implemented for the SWY, +NDR, and SDR models, as well as DelineateIt: + +- Add the option to choose between MFD and D8 algorithms to their + > Workbench interface. + +- Modify model code to implement the user-selected algorithm within + > each model. + +User Guide chapters for SWY, NDR, SDR, DI, and RouteDEM: + +- Update text in the Data Needs section to reflect the new input + > options (RouteDEM already has this). + +- Create a new section called something like Routing Algorithm + > Selection with example graphics to illustrate the difference in + > stream networks generated by each algorithm, and noting the pros + > and cons of each. + +## Technical Details + +The code for both MFD and D8 already exists in InVEST, as does code that +provides the option to choose between the algorithms in the Workbench +interface. However, + +- The D8 InVEST model implementations were made some time ago, which + > means that they are out of sync with the last few years\' changes + > to the routed models including the major update to sediment + > deposition. So this will need to be updated by the software team. + +- The D8 InVEST model implementations do not have software tests. The + > software team will need to add some when this becomes available in + > InVEST. + +- DelineateIt is currently only available with the D8 algorithm. An + > MFD watershed delineation routine will need to be written and + > tested by the software team. + +Specific changes that will need to be made include: + +- \[InVEST\] Updates to the routed models (SDR, NDR, SWY) to: + + - Allow the user to select their choice of routing model: D8 or + > MFD + + - Update custom routed model functionality to add D8 versions + + - Write software tests to cover the new D8 functionality in + > addition to the MFD + +- \[InVEST User Guide\] Update the documentation around this change + + - Which routing model should be selected? What are the tradeoffs + > with each routing model? (Stacie will do this). + + - Add the new invest_spec RST directive to the models' RST so that + > MODEL_SPEC descriptions can be pulled in. + + - Coordinate with translation teams to update the user's guide for + > these changes. + +- \[pygeoprocessing\] + + - Implement and test an MFD version of watershed delineation. + +# Open Issues + +None known at this time. + +# References diff --git a/pep-0012/MFD-stream-area-lulc-relative.png b/pep-0016/MFD-stream-area-lulc-relative.png similarity index 100% rename from pep-0012/MFD-stream-area-lulc-relative.png rename to pep-0016/MFD-stream-area-lulc-relative.png diff --git a/pep-0012/RouteDEM-D8-streams-Gura.png b/pep-0016/RouteDEM-D8-streams-Gura.png similarity index 100% rename from pep-0012/RouteDEM-D8-streams-Gura.png rename to pep-0016/RouteDEM-D8-streams-Gura.png diff --git a/pep-0012/RouteDEM-MFD-streams-Gura.png b/pep-0016/RouteDEM-MFD-streams-Gura.png similarity index 100% rename from pep-0012/RouteDEM-MFD-streams-Gura.png rename to pep-0016/RouteDEM-MFD-streams-Gura.png diff --git a/pep-0017.md b/pep-0017.md new file mode 100644 index 0000000..15b8a1f --- /dev/null +++ b/pep-0017.md @@ -0,0 +1,194 @@ +Version 1.0 approved by PSC on Nov. 28, 2023 + +Platform Enhancement Proposal (PEP) Template v1.0 + +Note: Expect iteration on this to get to the right level of detail +necessary to assess the science/software complexity of the request. + +See the PEP guidelines +[here](https://docs.google.com/document/d/1GOZKXsNfP7PHTjhKRgzx6bmcJHwOloyrSDvkOfx7fhk/edit?usp=sharing) +for the criteria by which PEPs will be evaluated. + +# Contacts + +Emma Ramsay () + +Perrine Hamel () + +# Abstract + +*A short (~200 word) description of the technical issue being addressed, +and whether this fits into the category of data, utility, model, +tailored tool or some combination.* + +The Urban Cooling model estimates urban air temperatures and the cooling +provided by vegetation. The model parameters are based on the +biophysical processes of cooling from vegetation but, in practice, these +can vary considerably based on the geographical and biophysical context +of a city. There is an existing calibration tool, implemented in a +python package, to calibrate the model parameters based on observed +temperature data. However, the tool is currently not user friendly and +the workflow is not streamlined with InVEST which has limited its +application. Here we propose to incorporate the calibration tool into +the InVEST Workbench to improve usability and improve the Urban Cooling +model performance for different contexts. This PEP involves adding a +stand-alone tool to the InVEST Urban Cooling model so we address the +relevant criteria for both. + +# Motivation + +*Explain why existing software/platform functionality is inadequate to +address the problem that this PEP solves; for each feature type (data, +utility, model, or tailored tool) describe how it meets the listed +criteria in the [PEP +Guidelines](https://docs.google.com/document/d/1GOZKXsNfP7PHTjhKRgzx6bmcJHwOloyrSDvkOfx7fhk/edit?usp=sharing)* + +The Urban Cooling model estimates the cooling provided by urban +vegetation. The model is based on the biophysical processes through +which vegetation reduces temperatures (shade, albedo and +evapotranspiration) as well as the cooling effect of large green spaces +and spatial air mixing. The user guide recommends parameters based on +empirical data from the literature, but these can vary significantly +depending on the geographical and biophysical context of the study city. +Previously, an automated calibration tool was developed to calibrate the +model parameters based on observed temperature data1. The +algorithm maximises R2 (or minimises error statistics RMSE +and MAE) between observed temperature data and estimated temperature +values using simulated annealing optimisation. The tool is currently +implemented as a python package +() but is +difficult to use on a Windows machine and likely inaccessible to many +InVEST users. Peer-reviewed case studies in France, USA and Singapore +have applied the calibration algorithm and found that it improves the +performance of the Urban Cooling model2,3. + +Here we propose to incorporate the calibration tool into the InVEST +Workbench to streamline its application and improve the overall +performance of the Urban Cooling model. This PEP involves adding a +stand-alone tool to the InVEST Urban Cooling model so we address the +relevant criteria for both. + +Models in InVEST + +- **Credibility** – the calibration tool has been tested in case-studies + in France, USA and Singapore, all published in peer-review + papers2,3 + + + +- **Novelty** – the calibration tool would improve the usability and + performance of the Urban Cooling model. There is not currently a + user-friendly pipeline to calibrate the model parameters with observed + data. + +- **Maintenance** – the code is already documented in a GitHub + repository and would only need to be implemented in to the InVEST + workbench. Note: Perrine can act as science lead given history with + using the tool including in publications 2,3 above. + +- **Usability** – the calibration tool relies on user input observed + temperature data (e.g., from weather stations or microclimate + sensors). The observed temperature data is at the users discretion and + will vary depending on the application. There is growing availability + of such data globally as cities expand meteorological networks to + better capture urban areas and crowd-sourcing alternatives become more + popular + +Tailored user interfaces and stand-alone tools + +- **Prototype:** The calibration tool is already implemented as a python + package and its usability has been demonstrated across multiple + published case studies. + +- **Scale of impact:** the tool would be useful for a range of users and + allow broader application of the Urban Cooling model, tailored to + different cities contexts. The tool would improve the geographic scope + of the model by improving its performance in different contexts (e.g., + tropical vs temperate climates). + +- **Uncertainty:** The calibration tool reduces the uncertainty of the + Urban Cooling model by calibrating parameters based on observed data. + This improves the credibility of results for decision-making. + +# Support + +*Detail additional long-term support that will be required because of +this change. Can include updates to documentation, MOOC, training +program, software team user support, etc.* + +No additional long-term support is required. Short-term support would +include updates to the User Guide and some additional user support via +forums. + +# Specification + +*This is the heart of the PEP, it should be complete enough that an +engineer and or manager can estimate resources needed to implement the +PEP. And if relevant it should include any backwards compatibility +issues -- i.e. is this a change to routing that will make the results of +SDR different in future versions than past versions?* + +All code is documented here: +. + +## Technical Details + +This should include any mathematical models, references to papers, +necessary input/testing data, desired outputs, prototype scripts, or any +other relevant information. + +All code is documented here: +. + +## Documentation + +*Describe the documentation that will be created to support users and +trainers, and who will create the documentation. Depending on the nature +of the PEP, this may include:* + +- *InVEST User Guide updates (for proposals related to InVEST models and + tools)* + +- *Its own independent User Guide/README (for independent tools)* + +- *User-friendly graphics providing visual representations of how it + works (which can be used in the User Guide and/or training materials)* + +- *Especially for new models, a presentation (PowerPoint or Gslides) + providing basic training material and graphics* + +The calibration tool is already documented in a stand alone user guide +(). +We envision incorporating this information into the InVEST Urban Cooling +model User Gudie. + +## Sample data + +Sample data are provided at the GitHub page. Alternatively, sample data +from Paris (ref.2) can be provided. + +# Open Issues + +*While a PEP is in draft, ideas can come up which warrant further +discussion. Those ideas should be recorded so people know that they are +being thought about but do not have a concrete resolution. This helps +make sure all issues required for the PEP to be ready for consideration +are complete and reduces duplicating prior discussion.* + +# References + +Reference list + +1\. Bosch, M. *et al.* A spatially-explicit approach to simulate urban +heat islands in complex urban landscapes. (2020) +doi:10.5194/gmd-2020-174. + +2\. Hamel, P. *et al.* Calibrating and validating the Integrated +Valuation of Ecosystem Services and Tradeoffs (InVEST) urban cooling +model: case studies in France and the United States. *Geoscientific +Model Development* **17**, 4755–4771 (2024). + +3\. Ramsay, E. E. *et al.* Assessing a decision-support tool to estimate +the cooling potential and economic savings from urban vegetation in +Singapore. *Sustainable Cities and Society* 106337 (2025) +doi:10.1016/j.scs.2025.106337. diff --git a/pep-0017/NatCap_PEP_UCM_calibration.docx b/pep-0017/NatCap_PEP_UCM_calibration.docx new file mode 100644 index 0000000..56b07b7 Binary files /dev/null and b/pep-0017/NatCap_PEP_UCM_calibration.docx differ diff --git a/pep-0018.md b/pep-0018.md new file mode 100644 index 0000000..9b796a7 --- /dev/null +++ b/pep-0018.md @@ -0,0 +1,434 @@ +This PEP has been exported to MarkDown from the original PEP [Google +Doc](https://docs.google.com/document/d/1ykd4mst3Y-wuMm1QxBqEMib5LVxZ1748kkshRLjNzKM/edit?tab=t.0), +and is stored as a [word document in this +repo](./pep-0013/pep-urban-mental-health-model.docx) + +PSC is scheduled on 2025-06-23 + +Last updated on: 2025-05-12 + +# Platform Enhancement Proposal (PEP) InVEST Urban Mental Health Model + +See the PEP guidelines +[here](https://docs.google.com/document/d/1GOZKXsNfP7PHTjhKRgzx6bmcJHwOloyrSDvkOfx7fhk/edit?usp=sharing) +for the criteria by which PEPs will be evaluated. + +See [design +doc](./pep-0013/invest-mental-health-model-design-doc-v0.3.0.docx). + +# Contacts + +Yingjie Li +([yingjieli@stanford.edu](mailto:yingjieli@stanford.edu)) + +Anders Rydstrom +([anders.rydstrom@stanford.edu](mailto:anders.rydstrom@stanford.edu)) + +Yougeng Lu +([yougengl@stanford.edu](mailto:yougengl@stanford.edu)) + +Anne Guerry +([anne.guerry@stanford.edu](mailto:anne.guerry@stanford.edu)) + +Lisa Mandle ([lmandle@stanford.edu](mailto:lmandle@stanford.edu)) + +# Abstract + +We propose a new model—the Urban Mental Health Model—for inclusion in +the InVEST suite to estimate how urban nature (e.g., greenspaces) +contributes to improved mental health outcomes. This model addresses a +key technical gap in the current InVEST toolkit by directly linking +nature exposure to mental health outcomes such as depression and anxiety +using effect sizes derived from recent meta-analyses [(Liu et al. +2023)](https://www.zotero.org/google-docs/?qmGvGj)(Li et al., 2025). +The model relies on widely available global datasets—including NDVI, +tree canopy cover, land use and land cover, gridded population, and +baseline mental health prevalence rates—making it applicable to cities +worldwide. The basis for the model has been tested in several research +case studies, including in San Francisco and Italy [(Giannico et al. +2024)](https://www.zotero.org/google-docs/?UdWRjb), demonstrating +its ability to estimate preventable mental health cases and associated +societal cost savings under alternative greening scenarios. This tool +also builds upon and extends the Urban Nature Access model by providing +quantitative estimates of health benefits, supporting more targeted and +equity-informed urban planning. Interest in this model is growing +rapidly across global partners, including the Global Gross Ecosystem +Product (GEP) project. While already operational as a standalone module +(See the [design +doc](./pep-0013/invest-mental-health-model-design-doc-v0.3.0.docx), +full integration into InVEST will enhance usability, allow batch +processing, and improve accessibility for a global audience. This +proposal falls under the category of model development. + +# Motivation + +A core motivation behind the development of the InVEST model suite is to +empower decision-makers and urban planners with tools to quantify how +different forms of natural capital—such as water bodies, forests, and +parks—support human well-being through ecosystem services like carbon +sequestration, urban cooling, and flood risk reduction. These insights +enable governments and organizations to make informed, strategic +investments in nature that sustain and enhance the flow of benefits to +people over time. + +However, there is currently no InVEST model that explicitly quantifies +the mental health benefits provided by urban nature. Given the +increasing recognition of mental health as a critical component of +public health—and the growing body of evidence linking greenspace +exposure to improved mental well-being—this represents a significant gap +among the InVEST models [(Bratman et al. +2019)](https://www.zotero.org/google-docs/?wMb8gY). The proposed +Urban Mental Health Model addresses this need by providing a mechanism +for cities to assess how changes in urban greening can influence +population-level mental health outcomes and reduce societal healthcare +costs related to mental disorders. By offering spatially explicit +estimates of these benefits, the model can inform more targeted, +equitable, and cost-effective urban greening strategies. + +This model builds on and complements the Urban Nature Access model, +which evaluates the spatial distribution of greenspace supply relative +to population demand within cities. While the Access model identifies +areas with over- or under-provision of greenspace, it does not link this +access to concrete health outcomes such as depression or anxiety. The +model fills this critical gap by providing a direct, quantifiable link +between residential greenspace exposure and mental health benefits, +offering a novel contribution to the InVEST toolkit (criterion: +novelty). + +Ultimately, this model will help cities better design, prioritize, and +implement urban nature interventions that advance both environmental and +public health goals—especially in underserved communities where green +infrastructure investment can yield the greatest human impact. + +## Novelty: + +Previous InVEST models provide estimates of existing ecosystem services +and can also create scenarios for future changes. However, the potential +effect of current and future ecosystem services on human health is not a +part of output from the models. Instead, this has to be inferred but +using other data and science linking ecosystem services to human health +outcomes. The InVEST Urban Mental Health Model will be the first InVEST +model that can directly measure the effect of existing and changes in +ecosystem services like urban nature on human health, in this case +mental health. + +The estimates for the association between greenspace indexes and mental +health outcomes is based on comprehensive meta-analyses of studies that +have been published in peer-reviewed scientific journals +[(Rojas-Rueda et al. 2019; Liu et al. +2023)](https://www.zotero.org/google-docs/?1xcg1S). The model +provides users with three flexible options for estimating changes in +nature exposure and the associated health outcomes, allowing adaptation +to a variety of planning and research contexts. For example, users can +define a tree cover target to simulate a greening scenario, in which +tree canopy cover and Normalized Difference Vegetation Index (NDVI) +serve as the primary inputs. Alternatively, users may provide baseline +and future (or counterfactual) land use/land cover (LULC) maps to +estimate changes in nature exposure based on projected or proposed +landscape transformations. + +Users can select a range of mental health outcomes—such as depression or +anxiety as outcomes in the model. These outcomes are assessed using +widely recognized clinical and self-report instruments. For example, the +exemplified depression indicator was measured using the Center for +Epidemiologic Studies Depression Scale (CES-D), the Patient Health +Questionnaire (PHQ), the Diagnostic and Statistical Manual of Mental +Disorders, Fourth Edition (DSM-IV) criteria, the Geriatric Depression +Scale (GDS), the Beck Depression Inventory (BDI), the Hospital Anxiety +and Depression Scale—Depression subscale (HADS-D), the Four-Dimensional +Symptom Questionnaire (4DSQ), and the Inventory of Depressive +Symptomatology (IDS). These validated tools allow for robust and +comparable assessments of mental health across diverse populations and +study contexts. + +## Usability: + +To maximize the model’s usability and global applicability, we have +designed the Urban Mental Health Model to rely primarily on publicly +available and widely used datasets. This ensures that users from a +variety of institutional, geographic, and technical backgrounds can +apply the model with minimal barriers. Below, we describe the core input +data required to run the model: + +- **Administrative boundaries (vector)**: A polygon layer representing + the spatial units for analysis. These can range from an entire city to + subdivisions such as neighborhoods, districts, or census tracts. This + spatial structure enables aggregation and comparison of population + exposure and health outcomes. + +- **Spatial population data (raster)**: Global population datasets such + as WorldPop (www.worldpop.org) offer gridded population estimates at + resolutions as fine as 100 meters. More localized datasets may also be + used to improve accuracy and context relevance. + +- **NDVI (raster)**: NDVI serves as the core proxy for nature exposure + in the model. Freely available from multiple sources, including Google + Earth Engine, MODIS + (https://modis.gsfc.nasa.gov/data/dataprod/mod13.php), and Sentinel-2, + NDVI data capture the relative abundance and density of vegetation + across the study area. + +- **Tree canopy cover (raster)**: Tree cover provides an additional + measure of green infrastructure and exposure quality. Global datasets + such as the Global Tree Canopy Cover Version 4 + (https://gee-community-catalog.org/projects/global_tcc/) offer + consistent and free access to tree canopy estimates at high + resolution. + +- **LULC data (raster or vector):** These datasets offer additional + context on greenspace types and urban environments. Sources include + national datasets like NLCD for the U.S. (https://www.mrlc.gov/data) + and global sources such as ESA WorldCover + (https://esa-worldcover.org/), which provide LULC information at high + spatial resolution. + +- **Baseline health risk data (vector)**: Spatially explicit prevalence + rates for mental health outcomes (e.g., depression, anxiety,) are + essential for calculating preventable cases. These can be obtained + from local or national health agencies such as the Centers for Disease + Control and Prevention (CDC), or global sources where available. If + health data are in tabular format, they can be joined to the + corresponding spatial administrative units. Where high-resolution data + are unavailable, users may apply rates from broader regional levels as + approximations. + +- **Health effect size table (.csv or .xlsx)**: We provide example + effect sizes derived from a global meta-analysis, including measures + such as risk ratios or odds ratios for various outcomes. Users are + encouraged to substitute these with region-specific dose-response + functions where available, to reflect local epidemiological data. + +- **Health cost table (.csv or .xlsx)**: To estimate economic benefits, + we include a sample data with country- and illness-specific societal + costs per case (in 2018 USD PPP). Users may input more detailed, local + cost estimates if available. For global or cross-country comparisons, + we recommend harmonizing cost units to ensure consistency across + regions. + +Thanks to the use of open-access and globally available datasets, this +model is applicable to the vast majority of cities worldwide. Further +guidance on required and optional inputs is available in the model’s +Design Document, referenced under the Specification section. + +## Demonstrated interest: + +The overarching goal of the InVEST model suite is to “map and value the +goods and services from nature that sustain and fulfill human life.” To +date, InVEST models have enabled users to quantify several ecosystem +services, for example, coastal flood mitigation, soil retention, and +urban cooling. While these outputs can be used to infer potential +benefits to human health, doing so requires users to possess +domain-specific knowledge and access to external datasets that link +environmental changes to health outcomes. This limits broader +accessibility and undercuts the integrated decision-support value InVEST +seeks to provide. The proposed Urban Mental Health Model aims to close +this gap by directly estimating the relationship between urban nature +and mental health outcomes. This is a timely and critical addition. Poor +mental health imposes a substantial burden globally, with estimated +costs reaching \$5 trillion USD per year by 2019—approximately 3.8% of +global GDP [(Arias et al. +2022)](https://www.zotero.org/google-docs/?4wI9bc)—and this burden +is expected to continue rising. Urban green space, including street tree +biodiversity and neighborhood greenness, has been consistently linked to +improved mental health outcomes, such as reduced antidepressant usage +[(Stenfors et al. +2024)](https://www.zotero.org/google-docs/?4MfSsr). By modeling +these relationships, the new InVEST module will allow planners, +researchers, and decision-makers to quantify how investments in urban +nature can mitigate mental health challenges at both neighborhood and +city scales. + +There is strong and growing interest in such a model, both within the +Natural Capital Project and among external collaborators. Key urban +planning and conservation questions—such as where changes in urban +nature will influence mental health and whom they will benefit—can be +addressed more directly with this tool. The preliminary framework has +been applied to urban projects in Guangzhou [(World Bank +2022)](https://www.zotero.org/google-docs/?S7hbhx), San Francisco +(on going), and Italy [(Giannico et al. +2024)](https://www.zotero.org/google-docs/?XfGr83), and interest has +expanded beyond our immediate network. For example, participants in +InVEST training workshops in 2023 and 2024 from diverse global +institutions expressed keen interest in the model’s release. Notably, +there has been a formal request to include this model in the Global +Gross Ecosystem Product (GEP) project led by Steve Polasky—a +collaborative effort where we have committed to providing this +functionality. + +A beta version of the model was previously developed by the urban team. +While this version is functional and has been piloted in small-scale +applications, it suffers from limited computational efficiency, +unresolved bugs, and low transparency in implementation. As such, it is +not yet suitable for wide-scale adoption or integration with the broader +InVEST suite. There is a clear and pressing need for a robust, +well-documented, and user-friendly version of the Urban Mental Health +Model. Importantly, its development aligns with prior commitments we’ve +made to funders and partners, and it represents a natural evolution of +InVEST’s capacity to support equitable, health-oriented urban +sustainability planning. + +## Credibility: + +The Urban Mental Health Model builds on a growing body of empirical +evidence and has been developed and tested through multiple case +studies, demonstrating both its scientific rigor and practical +applicability. + +The model was first applied in a published case study in Italy +[(Giannico et al. +2024)](https://www.zotero.org/google-docs/?rR76WQ), which estimated +preventable premature deaths by increasing residential green space using +open-access greenness data (e.g., NDVI). This study supported the +framework’s ability to quantify health outcomes from urban nature +exposure and was published in the high-impact journal Nature +Communications, lending credibility to the model’s scientific +foundations. + +A second case study—currently underway in San Francisco, USA and led by +Yingjie Li—further refines the model to estimate preventable cases of +depression and the associated avoided healthcare costs resulting from +increased neighborhood greenness. This work builds upon the Italy +framework with enhanced methods and a broader set of input variables. A +manuscript describing this application is currently in preparation (Li +et al., in prep.). + +Additionally, an earlier version of the model was applied in Guangzhou, +China [(World Bank +2022)](https://www.zotero.org/google-docs/?k3kdyq). That predecessor +model used a fixed effect size derived from a single empirical study and +was not capable of estimating preventable cases or monetized health +benefits. In contrast, the current proposed model improves substantially +upon this early version by incorporating a meta-analytic effect size +from multiple studies, the ability to estimate spatially explicit +preventable mental health cases, and integration of country-specific +healthcare cost parameters for over 40 countries. + +We are also working in collaboration with the NatCap TEEMs (The +Earth-Economy Modelers) team at the University of Minnesota to ensure +accurate and consistent incorporation of health cost indicators. These +enhancements enable the model to support comparisons across different +urban greening scenarios, providing planners and policymakers with +actionable estimates of both health and economic co-benefits. + +# **Support** + +The Urban Mental Health Model is expected to require only minimal +ongoing support, consistent with the maintenance needs of most InVEST +models. Notably, the model's input data—such as LULC and demographic +layers—are not expected to require frequent updates, enabling stable, +long-term use without annual revisions. We provided sample effect size +data for depression and anxiety based on global meta-analyses. As time +and funding permit, our team may expand this dataset. Users are +encouraged to update the health effect size table to reflect other +health indicators or incorporate more granular local data, allowing for +flexible and context-specific applications. + +To support user adoption, a new entry will be added to the InVEST User’s +Guide, and a sample dataset—based on completed case studies such as San +Francisco—can be provided to facilitate testing and onboarding. + +Although the model has not yet been featured in formal training +workshops, aside from general announcements about its development, +dedicated training materials will be needed to support its inclusion in +the InVEST MOOC and other educational or capacity-building sessions. + +# Specification + +## Technical Details + +The design document for the Urban Mental Health Model is available +[here (version for public +comment)](./pep-0013/invest-mental-health-model-design-doc-v0.3.0.docx). +This document outlines the conceptual framework, data requirements, and +methodological steps of the model, using the San Francisco case study as +a reference application. It serves as a foundational resource for +understanding how the model links urban nature characteristics to +population-level mental health indicators. + +Both the model code and test dataset for the San Francisco case study +are publicly available on GitHub: +[https://github.com/natcap/invest-mental-health](https://github.com/natcap/invest-mental-health). +This repository includes a working prototype of the model and a curated +data folder containing: + +- A data inventory README file describing each input dataset, including + file name, format, description, source, spatial resolution, and any + preprocessing steps. + +- A list of sample data, including + + - Administrative boundaries at the district level (e.g., census + tract). + + - LULC rasters and LULC attribute table distinguishing multiple types + of land covers. + + - NDVI rasters and a Google Earth Engine script for generating NDVI + rasters from the Landsat image collection (1986–present). + + - Population data to allow spatial weighting of mental health + outcomes; + + - Health effect size table + + - Baseline health prevalence rate data + + - Health cost rate data. + +Together, these materials provide a transparent and reproducible example +for testing and adapting the model in other urban contexts. + +## Documentation + +- InVEST User Guide will be provided once the design document is + approved by PSC. + +- A presentation (PowerPoint) will be provided for training material and + graphics. + +## Sample data + +Sample data and related documentation (data sources, location of study +area) will be provided by [Yingjie +Li](mailto:YingjieLi.edu@gmail.com). + +# References + +[Arias D, Saxena S, Verguet S (2022) Quantifying the global burden of +mental disorders and their economic value. eClinicalMedicine 54:. +https://doi.org/10.1016/j.eclinm.2022.101675](https://www.zotero.org/google-docs/?ouZCCy) + +[Bratman GN, Anderson CB, Berman MG, et al (2019) Nature and mental +health: An ecosystem service perspective. Science Advances 5:eaax0903. +https://doi.org/10.1126/sciadv.aax0903](https://www.zotero.org/google-docs/?ouZCCy) + +[Giannico OV, Sardone R, Bisceglia L, et al (2024) The mortality impacts +of greening Italy. Nat Commun 15:10452. +https://doi.org/10.1038/s41467-024-54388-7](https://www.zotero.org/google-docs/?ouZCCy) + +[Liu Z, Chen X, Cui H, et al (2023) Green space exposure on depression +and anxiety outcomes: A meta-analysis. Environmental Research +231:116303. +https://doi.org/10.1016/j.envres.2023.116303](https://www.zotero.org/google-docs/?ouZCCy) + +[Rojas-Rueda D, Nieuwenhuijsen MJ, Gascon M, et al (2019) Green spaces +and mortality: a systematic review and meta-analysis of cohort studies. +The Lancet Planetary Health 3:e469–e477. +https://doi.org/10.1016/S2542-5196(19)30215-3](https://www.zotero.org/google-docs/?ouZCCy) + +[Stenfors CUD, Rådmark L, Stengård J, et al (2024) More green, less +depressed: Residential greenspace is associated with lower +antidepressant redemptions in a nationwide population-based study. +Landscape and Urban Planning 249:105109. +https://doi.org/10.1016/j.landurbplan.2024.105109](https://www.zotero.org/google-docs/?ouZCCy) + +[World Bank (2022) Assessment of Key Ecosystem Services Provided by the +Haizhu National Wetland Park in Guangzhou, China. World Bank, +Washington, DC](https://www.zotero.org/google-docs/?ouZCCy) + +\## manually added references later + +Li, Y., Mao, Y., Mandle, L., Rydström, A., Remme, R., Lan, X., Wu, T., +Song, C., Lu, Y., Nadeau, K., Meyer-Lindenberg, A., Daily, G., Guerry, +A. (2025) Global meta-analysis reveals broad spectrum mental health +benefits of urban nature exposure. Nature Cities. diff --git a/pep-0013/invest-mental-health-model-design-doc-v0.3.0.docx b/pep-0018/invest-mental-health-model-design-doc-v0.3.0.docx similarity index 100% rename from pep-0013/invest-mental-health-model-design-doc-v0.3.0.docx rename to pep-0018/invest-mental-health-model-design-doc-v0.3.0.docx diff --git a/pep-0013/pep-urban-mental-health-model.docx b/pep-0018/pep-urban-mental-health-model.docx similarity index 100% rename from pep-0013/pep-urban-mental-health-model.docx rename to pep-0018/pep-urban-mental-health-model.docx