add missing PEPs from the google doc archive

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

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 [<u>Software Team Burden</u>](#software-team-burden)
+and [<u>User Demand</u>](#_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
+[<u>User Demand</u>](#_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
+  ([<u>github
+  history</u>](https://github.com/natcap/invest/commits/main/src/natcap/invest/finfish_aquaculture))
+
+- Fisheries - 1 non-forced maintenance bugfix in 3 years ([<u>github
+  history</u>](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:
+
+<img src="media/image2.png" style="width:7.47455in;height:2.47367in" />
+
+#### Fisheries: 0 runs since December, 2020, except 2 runs in June, 2021:
+
+<img src="media/image1.png" style="width:7.49167in;height:2.50923in" />
+
+*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:*
+[<u>https://nbviewer.jupyter.org/github/davemfish/invest-usage-stats/blob/main/invest_usage_stats.ipynb</u>](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:
+[<u>https://community.naturalcapitalproject.org/tags/</u>](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:
+[<u>https://docs.google.com/spreadsheets/d/143HM51bD92NL6K6gs5Wialej6QCqFXDTpXoKRcQ-9D0/edit#gid=0</u>](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:
+“<span class="mark">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.”</span>
+
+## 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.

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.