Merge pull request #40 from IMMM-SFA/feature/paper

Feature/paper
IMMM-SFA · Dec 29, 2023 · 4c2b188 · 4c2b188
2 parents 311aa5d + 7f6d417
commit 4c2b188
Show file tree

Hide file tree

Showing 4 changed files with 295 additions and 0 deletions.
diff --git a/.github/workflows/draft-pdf.yml b/.github/workflows/draft-pdf.yml
@@ -0,0 +1,23 @@
+on: [push]
+
+jobs:
+  paper:
+    runs-on: ubuntu-latest
+    name: Paper Draft
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v2
+      - name: Build draft PDF
+        uses: openjournals/openjournals-draft-action@master
+        with:
+          journal: joss
+          # This should be the path to the paper within your repo.
+          paper-path: paper/paper.md
+      - name: Upload
+        uses: actions/upload-artifact@v1
+        with:
+          name: paper
+          # This is the output path where Pandoc will write the compiled
+          # PDF. Note, this should be the same directory as the input
+          # paper.md
+          path: paper/paper.pdf
diff --git a/paper/JOSS.png b/paper/JOSS.png
diff --git a/paper/paper.bib b/paper/paper.bib
@@ -0,0 +1,203 @@
+@article{christensen2004effects,
+  title={The effects of climate change on the hydrology and water resources of the Colorado River basin},
+  author={Christensen, Niklas S and Wood, Andrew W and Voisin, Nathalie and Lettenmaier, Dennis P and Palmer, Richard N},
+  journal={Climatic change},
+  volume={62},
+  pages={337--363},
+  year={2004},
+  doi = {10.1023/B:CLIM.0000013684.13621.1f},
+  publisher={Springer}
+}
+
+@article{bass2023aridification,
+  title={Aridification of Colorado River Basin's snowpack regions has driven water losses despite ameliorating effects of vegetation},
+  author={Bass, Benjamin and Goldenson, Naomi and Rahimi, Stefan and Hall, Alex},
+  journal={Water Resources Research},
+  volume={59},
+  number={7},
+  pages={e2022WR033454},
+  year={2023},
+  doi = {10.1029/2022WR033454},
+  publisher={Wiley Online Library}
+}
+
+@article{salehabadi2020future,
+  title={The future hydrology of the Colorado River Basin},
+  author={Salehabadi, Homa and Tarboton, David and Kuhn, Eric and Udall, Brad and Wheeler, Kevin and Rosenberg, David and Goeking, Sara and Schmidt, John C},
+  journal={The Future of the Colorado River Project},
+  year={2020},
+  publisher={Utah State University, Quinney College of Natural Resources Center for~�}
+}
+
+@article{hadjimichael2020defining,
+  title={Defining robustness, vulnerabilities, and consequential scenarios for diverse stakeholder interests in institutionally complex river basins},
+  author={Hadjimichael, Antonia and Quinn, Julianne and Wilson, Erin and Reed, Patrick and Basdekas, Leon and Yates, David and Garrison, Michelle},
+  journal={Earth's Future},
+  volume={8},
+  number={7},
+  pages={e2020EF001503},
+  year={2020},
+  doi = {10.1029/2020EF001503},
+  publisher={Wiley Online Library}
+}
+
+@article{kopytkovskiy2015climate,
+  title={Climate-change impacts on water resources and hydropower potential in the Upper Colorado River Basin},
+  author={Kopytkovskiy, M and Geza, M and McCray, JE},
+  journal={Journal of Hydrology: Regional Studies},
+  volume={3},
+  pages={473--493},
+  year={2015},
+  doi = {10.1016/j.ejrh.2015.02.014},
+  publisher={Elsevier}
+}
+
+@article{milly2020colorado,
+  title={Colorado River flow dwindles as warming-driven loss of reflective snow energizes evaporation},
+  author={Milly, Paul CD and Dunne, Krista A},
+  journal={Science},
+  volume={367},
+  number={6483},
+  pages={1252--1255},
+  year={2020},
+  doi = {10.1126/science.aay9187},
+  publisher={American Association for the Advancement of Science}
+}
+
+@article{miller2021will,
+  title={How will baseflow respond to climate change in the upper Colorado River Basin?},
+  author={Miller, Olivia L and Miller, Matthew P and Longley, Patrick C and Alder, Jay R and Bearup, Lindsay A and Pruitt, Tom and Jones, Daniel K and Putman, Annie L and Rumsey, Christine A and McKinney, Tim},
+  journal={Geophysical Research Letters},
+  volume={48},
+  number={22},
+  pages={e2021GL095085},
+  year={2021},
+  doi = {10.1029/2021GL095085},
+  publisher={Wiley Online Library}
+}
+
+@article{hadjimichael2020advancing,
+  title={Advancing diagnostic model evaluation to better understand water shortage mechanisms in institutionally complex river basins},
+  author={Hadjimichael, Antonia and Quinn, Julianne and Reed, Patrick},
+  journal={Water Resources Research},
+  volume={56},
+  number={10},
+  pages={e2020WR028079},
+  year={2020},
+  doi = {10.1029/2020WR028079},
+  publisher={Wiley Online Library}
+}
+
+@article{lempert2002new,
+  title={A new decision sciences for complex systems},
+  author={Lempert, Robert J},
+  journal={Proceedings of the National Academy of Sciences},
+  volume={99},
+  number={suppl\_3},
+  pages={7309--7313},
+  year={2002},
+  doi = {10.1073/pnas.082081699},
+  publisher={National Acad Sciences}
+}
+
+@misc{kwakkel2016coping,
+  title={Coping with the wickedness of public policy problems: approaches for decision making under deep uncertainty},
+  author={Kwakkel, Jan H and Walker, Warren E and Haasnoot, Marjolijn},
+  journal={Journal of Water Resources Planning and Management},
+  volume={142},
+  number={3},
+  pages={01816001},
+  year={2016},
+  doi = {10.1061/(ASCE)WR.1943-5452.0000626},
+  publisher={American Society of Civil Engineers}
+}
+
+@article{walker2003dealing,
+  title={Dealing with uncertainty in policy analysis and policymaking},
+  author={Walker, WE and Marchau, VAWJ},
+  journal={Integrated Assessment},
+  volume={4},
+  number={1},
+  pages={1--4},
+  year={2003},
+  doi = {10.1076/iaij.4.1.1.16462},
+  publisher={Taylor \& Francis}
+}
+
+@book{marchau2019decision,
+  title={Decision making under deep uncertainty: from theory to practice},
+  author={Marchau, Vincent AWJ and Walker, Warren E and Bloemen, Pieter JTM and Popper, Steven W},
+  year={2019},
+  doi = {10.1287/opre.41.3.435},
+  publisher={Springer Nature}
+}
+
+@article{bankes1993exploratory,
+  title={Exploratory modeling for policy analysis},
+  author={Bankes, Steve},
+  journal={Operations research},
+  volume={41},
+  number={3},
+  pages={435--449},
+  year={1993},
+  doi = {10.1287/opre.41.3.435},
+  publisher={INFORMS}
+}
+
+@techreport{CWCB-2023,
+    author = {CWCB},
+    title = {The Colorado Water Plan},
+    institution = {Colorado Water Conservation Board},
+    year = {2023}
+}
+
+@article{Flavelle2023,
+ author  = {Flavelle, Christoper},
+ date    = {2023-05-22},
+ title   = {A Breakthrough Deal to Keep the Colorado River From Going Dry, for Now},
+ journal = {The New York Times},
+ url     = {https://www.nytimes.com/2023/05/22/climate/colorado-river-deal.html},
+ urldate = {2023-05-22}
+}
+
+@article{labadie2006modsim,
+  title={MODSIM: decision support system for integrated river basin management},
+  author={Labadie, John W},
+  year={2006}
+}
+
+@article{draper2004calsim,
+  title={CalSim: Generalized model for reservoir system analysis},
+  author={Draper, Andrew J and Mun{\'e}var, Armin and Arora, Sushil K and Reyes, Erik and Parker, Nancy L and Chung, Francis I and Peterson, Lloyd E},
+  journal={Journal of Water Resources Planning and Management},
+  volume={130},
+  number={6},
+  pages={480--489},
+  year={2004},
+  doi = {10.1061/(ASCE)0733-9496(2004)130:6(480},
+  publisher={American Society of Civil Engineers}
+}
+
+@article{zeff2021california,
+  title={California's food-energy-water system: An open source simulation model of adaptive surface and groundwater management in the Central Valley},
+  author={Zeff, Harrison B and Hamilton, Andrew L and Malek, Keyvan and Herman, Jonathan D and Cohen, Jonathan S and Medellin-Azuara, Josue and Reed, Patrick M and Characklis, Gregory W},
+  journal={Environmental Modelling \& Software},
+  volume={141},
+  pages={105052},
+  year={2021},
+  doi = {10.1016/j.envsoft.2021.105052},
+  publisher={Elsevier}
+}
+
+@article{yates2005weap21,
+  title={WEAP21--A demand-, priority-, and preference-driven water planning model: part 1: model characteristics},
+  author={Yates, David and Sieber, Jack and Purkey, David and Huber-Lee, Annette},
+  journal={Water international},
+  volume={30},
+  number={4},
+  pages={487--500},
+  year={2005},
+  doi = {10.1080/02508060508691893},
+  publisher={Taylor \& Francis}
+}
+
diff --git a/paper/paper.md b/paper/paper.md
@@ -0,0 +1,69 @@
+---
+title: 'statemodify: a Python framework to facilitate accessible exploratory modeling for discovering drought vulnerabilities'
+tags:
+  - Python
+  - StateMod
+authors:
+  - name: Rohini S. Gupta
+    orcid: 0000-0003-3538-0675
+    affiliation: 1
+  - name: Chris R. Vernon
+    orcid: 0000-0002-3406-6214
+    affiliation: 2
+  - name: Travis Thurber
+    orcid: 0000-0002-4370-9971
+    affiliation: 2
+  - name: David F. Gold
+    orcid: 0000-0002-0854-1819
+    affiliation: 1  
+  - name: Zachary M. Hirsch
+    orcid: 0009-0007-5356-5354
+    affiliation: 3      
+  - name: Antonia Hadjimichael
+    orcid: 0000-0001-7330-6834
+    affiliation: 4 
+  - name: Patrick M. Reed
+    orcid: 0000-0002-7963-6102
+    affiliation: 1
+
+
+affiliations:
+ - name: Department of Civil and Environmental Engineering, Cornell University, 527 College Ave, Hollister Hall, Ithaca, NY, 14853, USA
+   index: 1
+ - name: Pacific Northwest National Laboratory, Richland, WA., USA
+   index: 2
+ - name: Department of Environmental Sciences and Engineering, Gillings School of Global Public Health,University of North Carolina at Chapel Hill, Chapel Hill, NC., USA
+   index: 3   
+ - name: Department of Geosciences, Penn State University, State College, PA., USA
+   index: 4   
+date: 15 December 2023
+bibliography: paper.bib
+---
+
+# Summary
+The Colorado River Basin (CRB) is experiencing an unprecedented water shortage crisis brought upon by a combination of factors arising from interactions across the region's coupled human and natural systems. Allocation of water to the seven states that rely on the Colorado River was settled in the Colorado River Compact of 1922 during a period now known to be characterized by atypically high flows [@christensen2004effects]. Since then, aridification due to anthropogenic-driven warming has steadily reduced the overall water supply available in the basin, with a 10% decrease in the river's flow occurring over just the past two decades [@bass2023aridification]. The river is further strained by increasing demands associated with a growing population and diverse multi-sectoral demands. Navigating these challenges also requires accounting for the complex prior appropriation water rights system governing water allocation across the region's diverse users. 
+
+The state of Colorado's West Slope basins are a critical component of the Colorado River System and reflect the broader challenges faced by the entire basin. The six West Slope basins – the Upper Colorado, Yampa, White, San Juan, Dolores, and Gunnison basins – comprise the headwaters of the Colorado River and contribute over 60% of the inflow to Lake Powell in an average year [@salehabadi2020future]. The West Slope basins represent an essential part of the State of Colorado's economy, supporting a multibillion-dollar tourism industry, providing water for roughly 800,000 acres of irrigated farmland, and sending drinking water across the continental divide to major metropolitan areas in eastern Colorado [@CWCB-2023]. Uncertainty stemming from climate change and institutional response plays a dominant role in evaluations of future deliveries to Lake Powell and characterization of the basin users' vulnerabilities [@hadjimichael2020advancing; @hadjimichael2020defining; @salehabadi2020future]. Recent studies estimate that changes in temperature and precipitation may result in streamflows that are between 5% and 80% lower by the end of the 21st century when compared to the historical record [@kopytkovskiy2015climate; @milly2020colorado; @miller2021will]. Institutional responses to changes in flow, such as changes to reservoir operations and water rights structures, are difficult to predict and model using traditional probabilistic methods [@hadjimichael2020advancing; @hadjimichael2020defining]. This difficulty in accurately characterizing key system inputs with known probability distributions is often described as conditions of "deep uncertainty" [@lempert2002new; @kwakkel2016coping]. 
+
+To account for the deeply uncertain future conditions in the West Slope basins, approaches are needed that can help facilitate an understanding of vulnerabilities across many plausible future scenarios [@lempert2002new; @walker2003dealing; @marchau2019decision]. Exploratory modeling is one such approach that uses computational experiments to understand a range of possible model behaviors [@bankes1993exploratory]. In the West Slope basins, exploratory modeling can be done with StateMod, a highly resolved, open source, regional water allocation model developed and maintained jointly by the Colorado Water Conservation Board (CWCB) and the Colorado Division of Water Resources (DWR) that is currently used to support water use assessments for the State of Colorado. The input files of StateMod can be manipulated to develop hypothetical scenarios to assess how changes in hydrology, water rights, or infrastructure impact regional water shortages, streamflow, or reservoir levels. 
+
+StateMod is written in Fortran and conducting large ensemble exploratory modeling with it, on high-performance computing (HPC) resources, requires familiarity with Linux. Due to the model's complexity, there are also nontrivial computational challenges in comprehensively sampling the model's input space and managing the outputs of interest, especially for large ensembles. These challenges limit its use among researchers and broader operational users. Thus, we develop `statemodify`, a Python-based package and framework that allows users to easily interact with StateMod using Python exclusively. The user can implement `statemodify` functions to manipulate StateMod's input files to develop alternative demand, hydrology, infrastructure, and institutional scenarios for Colorado's West Slope basins and run these scenarios through StateMod. We also create methods to compress and extract model output into easily readable data frames and provide guidance on analysis and visualization of output in a series of Jupyter notebooks that step through the functionality of the package. 
+
+
+# Design and Functionality
+
+Figure 1 illustrates a typical `statemodify` workflow along with the corresponding functions that can be utilized in each step. Documentation of all functions (including helper functions that are not described in the figure) can be found in the `statemodify` [API](https://immm-sfa.github.io/statemodify/reference/api.html#input-modification). 
+
+
+![`statemodify` workflow](JOSS.png)
+
+# Statement of Need
+
+Sustainable management of Colorado's West Slope basins is necessary to support inflow into the Colorado River and, by extension, the 40 million people that depend on it for water, hydropower, agriculture, and recreation [@Flavelle2023]. Because it is unknown how the future will manifest in the West Slope, exploratory modeling with StateMod is a valuable approach to comprehensively identify the most important drivers of change and vulnerabilities to different stakeholders. Sustainable management of the region will also ultimately require combining expert knowledge across diverse groups, ranging from federal and state institutions who are prescribing larger policy and conservation efforts down to the practical knowledge acquired from individual stakeholders, many of whom have livelihoods that have been supported by the river for many generations. In an effort to better maintain StateMod and expand their user base, CWCB and DWR have developed the CDSS Open Source Initiative ([OpenCDSS](https://opencdss.state.co.us/opencdss/)), which provides Java-based [TSTool](https://opencdss.state.co.us/opencdss/tstool/) and [StateDMI](https://opencdss.state.co.us/opencdss/statedmi/) software to create and modify StateMod input files. The `statemodify` package seeks to complement and expand this toolset to accommodate large ensemble exploratory modeling and a Linux-based workflow and to provide additional options to develop more targeted file adjustments and richer streamflow scenarios. The use of Python for all `statemodify` methods as well as the ease of interacting through Jupyter notebooks can further broaden the user base that can interact with StateMod and serve as a sandbox environment for quickly testing hypotheses that a user might have without the user needing to invest large amounts of time to learn how to use StateMod and develop a workflow. Examples of such questions could be: *What happens to user shortages in the Gunnison if evaporation rates were to change over the Blue Mesa Reservoir? If user X gains a more senior water right, does this have a bigger impact on reducing their shortages than shifts to a wetter hydroclimate?* 
+
+Though `statemodify` focuses on Colorado's West Slope basins, this case study is representative of a broader group of institutionally complex basins that are experiencing extreme conditions due to their own regionally-specific deep uncertainties. Discovering vulnerabilities of users in these regions will likely require similar finely resolved models along with extensive computational resources (i.e. see CalSim [@draper2004calsim], WEAP21 [@yates2005weap21], MODSIM [@labadie2006modsim], CALFEWS [@zeff2021california]). If a user has access to a given model's input and output files, many of the methods introduced in `statemodify` could be adapted for adjusting input files and compressing and visualizing the output files. It is important to note that not every user has access to the computational resources required to do exploratory modeling. At this point in time, those users are unable to participate in this type of modeling effort. To help overcome this barrier, we demonstrate `statemodify` and the associated notebooks in containers hosted by [MSD-LIVE](https://msdlive.org/) that allow any user to conduct a small-scale analysis. Users can also use the associated Dockerfile to download and compile StateMod and run the same Jupyter notebooks on their own personal computers or HPC resources. Work is currently in progress to connect `statemodify` with cloud platforms, such as Amazon Web Services, Microsoft Azure, and Google Cloud, which provide more accessible tiers of computing to students and researchers who do not have access to HPC. Overall, the `statemodify` framework will not only broaden the user base that can interact with StateMod, but also can serve as a guide on how to make exploratory modeling accessible to diverse groups whose inclusion can lead to more robust basin management.        
+
+# Acknowledgements
+This research was supported by the U.S. Department of Energy, Office of Science, as part of research in MultiSector Dynamics, Earth and Environmental System Modeling Program.
+
+# References