Merge pull request #212 from amoodie/joss_draft

add JOSS paper draft

docs/source/_resources/joss/figures/figures.py

@@ -0,0 +1,85 @@
+import numpy as np
+import matplotlib.pyplot as plt
+import matplotlib
+
+import os
+import sys
+
+import pyDeltaRCM
+from pyDeltaRCM.shared_tools import sec_in_day, day_in_yr
+
+import netCDF4 as nc
+
+# everything relative to this file
+_dir = os.path.realpath(os.path.dirname(__file__))
+
+
+if __name__ == '__main__':
+
+    # get script input argument
+    _arg = sys.argv
+    if len(_arg) == 3:
+        _input_flag = sys.argv[1].strip('-')
+    elif len(_arg) == 2:
+        _input_flag = sys.argv[1].strip('-')
+    else:
+        raise ValueError('No arguments supplied.')
+
+    # parameter choices for scaling
+    If = 10 / day_in_yr  # intermittency factor for year-scaling
+
+    # if running the computation
+    if _input_flag == 'compute':
+
+        _mdl = pyDeltaRCM.DeltaModel(
+            out_dir=_dir,
+            seed=10151919,  # JOSS, A1Z26 encoded
+            save_eta_grids=True,
+            save_dt=sec_in_day)
+
+        for i in range(4000):
+            _mdl.update()
+
+        # finalize
+        _mdl.finalize()
+
+    # if running the plotting
+    elif _input_flag == 'plot':
+
+        # set up attributes needed for plotting
+        H_SL, h, n = 0, 3, 0.3  # sea level, basin depth, surf relief
+        blues = matplotlib.cm.get_cmap('Blues_r', 64)
+        greens = matplotlib.cm.get_cmap('YlGn_r', 64)
+        combined = np.vstack((blues(np.linspace(0.1, 0.7, 5)),
+                              greens(np.linspace(0.2, 0.8, 5))))
+        cmap = matplotlib.colors.ListedColormap(combined, name='delta')
+        bounds = np.hstack(
+            (np.linspace(H_SL-h, H_SL-(n/2), 5),
+             np.linspace(H_SL, H_SL+n, 6)))
+        norm = matplotlib.colors.BoundaryNorm(bounds, len(bounds)-1)
+
+        data = nc.Dataset(os.path.join(_dir, 'pyDeltaRCM_output.nc'))
+
+        nt = 4
+        ts = np.linspace(0, data['eta'].shape[0]-1,
+                         num=nt, dtype=np.int)  # linearly interpolate ts
+
+        # make the timeseries plot
+        fig, ax = plt.subplots(1, nt, figsize=(11, 2), dpi=300)
+        for i, t in enumerate(ts):
+            ax[i].imshow(data['eta'][t, :, :], cmap=cmap, norm=norm)
+            _time = pyDeltaRCM.shared_tools.scale_model_time(
+                data['time'][t], If=If, units='years')
+            ax[i].set_title(' '.join((
+                str(np.round(_time, 1)),
+                'years')))
+            ax[i].axes.get_xaxis().set_ticks([])
+            ax[i].axes.get_yaxis().set_ticks([])
+
+        # plt.show()
+        plt.tight_layout()
+        plt.savefig(os.path.join(_dir, 'timeseries.png'), transparent=True)
+
+    # otherwise
+    else:
+        raise ValueError('Invalid argument supplied.')

docs/source/_resources/joss/paper.bib

@@ -0,0 +1,188 @@
+@article{liang_reduced_1_2015,
+	author = {Liang, M. and Voller, V. R. and Paola, C.},
+	title = {A reduced-complexity model for river delta formation -- {P}art 1: Modeling deltas with channel dynamics},
+	journal = {Earth Surface Dynamics},
+	volume = {3},
+	year = {2015},
+	number = {1},
+	pages = {67--86},
+	doi = {10.5194/esurf-3-67-2015}
+}
+
+@article{liang_reduced_2_2015,
+	author = {Liang, M. and Geleynse, N. and Edmonds, D. A. and Passalacqua, P.},
+	title = {A reduced-complexity model for river delta formation -- {P}art 2: Assessment of the flow routing scheme},
+	journal = {Earth Surface Dynamics},
+	volume = {3},
+	year = {2015},
+	number = {1},
+	pages = {87--104},
+	doi = {10.5194/esurf-3-87-2015}
+}
+
+@incollection{overeem_three_2005,
+	author = {Overeem, Irina and Syvitski, James P.M. and Hutton, Eric W.H.},
+	title = "{Three-Dimensional Numerical Modeling of Deltas}",
+	booktitle = "{River Deltas–Concepts, Models, and Examples}",
+	publisher = {SEPM Society for Sedimentary Geology},
+	year = {2005},
+	month = {01},
+	doi = {10.2110/pec.05.83.0011},
+}
+
+@article{liang_quantifying_2016,
+	author = {Liang, Man and Van Dyk, Corey and Passalacqua, Paola},
+	title = {Quantifying the patterns and dynamics of river deltas under conditions of steady forcing and relative sea level rise},
+	journal = {Journal of Geophysical Research: Earth Surface},
+	volume = {121},
+	number = {2},
+	pages = {465-496},
+	keywords = {river delta formation, sea level rise, delta metrics, numerical modeling},
+	doi = {10.1002/2015JF003653},
+	year = {2016}
+}
+
+@article{liang_how_2016,
+	author = {Liang, Man and Kim, Wonsuck and Passalacqua, Paola},
+	title = {How much subsidence is enough to change the morphology of river deltas?},
+	journal = {Geophysical Research Letters},
+	volume = {43},
+	number = {19},
+	pages = {10,266-10,276},
+	doi = {10.1002/2016GL070519},
+	year = {2016}
+}
+
+@article{lauzon_ice_2019,
+	author = {Lauzon, Rebecca and Piliouras, Anastasia and Rowland, Joel C.},
+	title = {Ice and Permafrost Effects on Delta Morphology and Channel Dynamics},
+	journal = {Geophysical Research Letters},
+	volume = {46},
+	number = {12},
+	pages = {6574-6582},
+	doi = {10.1029/2019GL082792},
+	year = {2019}
+}
+
+@article{lauzon_comparing_2018,
+	author = {Lauzon, Rebecca and Murray, A. Brad},
+	title = {Comparing the Cohesive Effects of Mud and Vegetation on Delta Evolution},
+	journal = {Geophysical Research Letters},
+	volume = {45},
+	number = {19},
+	pages = {10,437-10,445},
+	doi = {10.1029/2018GL079405},
+	year = {2018}
+}
+
+@article{piliouras_unraveling_2021,
+	author = {Piliouras, A. and Lauzon, R. and Rowland, J. C.},
+	title = {Unraveling the Combined Effects of Ice and Permafrost on Arctic Delta Morphodynamics},
+	journal = {Journal of Geophysical Research: Earth Surface},
+	volume = {126},
+	number = {4},
+	doi = {https://doi.org/10.1029/2020JF005706},
+	year = {2021}
+}
+
+@article{larsen_appropriate_2016,
+	title = {Appropriate complexity landscape modeling},
+	journal = {Earth-Science Reviews},
+	volume = {160},
+	pages = {111-130},
+	year = {2016},
+	doi = {10.1016/j.earscirev.2016.06.016},
+	author = {Laurel G. Larsen and Maarten B. Eppinga and Paola Passalacqua and Wayne M. Getz and Kenneth A. Rose and Man Liang}
+}
+
+@article{edmonds_coastal_2020,
+	title = {Coastal flooding will disproportionately impact people on river deltas},
+	journal = {Nature Communications},
+	volume = {11},
+	year = {2020},
+	doi = {10.1038/s41467-020-18531-4},
+	author = {Edmonds, Douglas A. and Caldwell, Rebecca L. and Brondizio, Eduardo S. and Siani, Sacha M. O.}
+}
+
+@article{paola_natural_2011,
+	title = {Natural {Processes} in {Delta} {Restoration}: {Application} to the {Mississippi} {Delta}},
+	volume = {3},
+	issn = {1941-1405, 1941-0611},
+	shorttitle = {Natural {Processes} in {Delta} {Restoration}},
+	doi = {10.1146/annurev-marine-120709-142856},
+	number = {1},
+	urldate = {2016-07-26},
+	journal = {Annual Review of Marine Science},
+	author = {Paola, Chris and Twilley, Robert R. and Edmonds, Douglas A. and Kim, Wonsuck and Mohrig, David and Parker, Gary and Viparelli, Enrica and Voller, Vaughan R.},
+	month = jan,
+	year = {2011},
+	pages = {67--91}
+}
+
+@article{hutton_basic_2020,
+	doi = {10.21105/joss.02317},
+	year = {2020},
+	publisher = {The Open Journal},
+	volume = {5},
+	number = {51},
+	pages = {2317},
+	author = {Eric W.h. Hutton and Mark D. Piper and Gregory E. Tucker},
+	title = {The Basic Model Interface 2.0: A standard interface for coupling numerical models in the geosciences},
+	journal = {Journal of Open Source Software}
+}
+
+@misc{BMI_pyDeltaRCM, 
+	title = {Basic Modeling Interface (BMI) wrapper to the pyDeltaRCM model},
+	url = {https://github.com/DeltaRCM/BMI_pyDeltaRCM},
+	author = {{DeltaRCM Team}}
+}
+
+@inproceedings{lam_numba_2015,
+	author = {Lam, Siu Kwan and Pitrou, Antoine and Seibert, Stanley},
+	title = {Numba: A LLVM-Based Python JIT Compiler},
+	year = {2015},
+	isbn = {9781450340052},
+	publisher = {Association for Computing Machinery},
+	address = {New York, NY, USA},
+	doi = {10.1145/2833157.2833162},
+	booktitle = {Proceedings of the Second Workshop on the LLVM Compiler Infrastructure in HPC},
+	articleno = {7},
+	numpages = {6},
+	location = {Austin, Texas}
+}
+
+@article{harris2020,
+	title = {Array Programming with {{NumPy}}},
+	author = {Harris, Charles R. and Millman, K. Jarrod and {van der Walt}, St{\'e}fan J. and Gommers, Ralf and Virtanen, Pauli and Cournapeau, David and Wieser, Eric and Taylor, Julian and Berg, Sebastian and Smith, Nathaniel J. and Kern, Robert and Picus, Matti and Hoyer, Stephan and {van Kerkwijk}, Marten H. and Brett, Matthew and Haldane, Allan and {del R{\'i}o}, Jaime Fern{\'a}ndez and Wiebe, Mark and Peterson, Pearu and {G{\'e}rard-Marchant}, Pierre and Sheppard, Kevin and Reddy, Tyler and Weckesser, Warren and Abbasi, Hameer and Gohlke, Christoph and Oliphant, Travis E.},
+	year = {2020},
+	month = sep,
+	volume = {585},
+	pages = {357--362},
+	publisher = {{Nature Publishing Group}},
+	doi = {10.1038/s41586-020-2649-2},
+	journal = {Nature},
+	language = {en},
+	number = {7825}
+}
+
+@article{hunter2007,
+	title = {Matplotlib: {{A 2D}} Graphics Environment},
+	author = {Hunter, J. D.},
+	year = {2007},
+	volume = {9},
+	pages = {90--95},
+	publisher = {{IEEE COMPUTER SOC}},
+	doi = {10.1109/MCSE.2007.55},
+	journal = {Computing in Science \& Engineering},
+	number = {3}
+}
+
+@ARTICLE{virtanen2020,
+	author = {Virtanen, Pauli and Gommers, Ralf and Oliphant, Travis E. and Haberland, Matt and Reddy, Tyler and Cournapeau, David and Burovski, Evgeni and Peterson, Pearu and Weckesser, Warren and Bright, Jonathan and {van der Walt}, St{\'e}fan J. and Brett, Matthew and Wilson, Joshua and Millman, K. Jarrod and Mayorov, Nikolay and Nelson, Andrew R. J. and Jones, Eric and Kern, Robert and Larson, Eric and Carey, C J and Polat, {\.I}lhan and Feng, Yu and Moore, Eric W. and {VanderPlas}, Jake and Laxalde, Denis and Perktold, Josef and Cimrman, Robert and Henriksen, Ian and Quintero, E. A. and Harris, Charles R. and Archibald, Anne M. and Ribeiro, Ant{\^o}nio H. and Pedregosa, Fabian and {van Mulbregt}, Paul and {SciPy 1.0 Contributors}},
+	title = {{{SciPy} 1.0: Fundamental Algorithms for Scientific Computing in Python}},
+	journal = {Nature Methods},
+	year    = {2020},
+	volume  = {17},
+	pages   = {261--272},
+	doi     = {10.1038/s41592-019-0686-2},
+}

docs/source/_resources/joss/paper.md

@@ -0,0 +1,91 @@
+---
+title: '*pyDeltaRCM*: a flexible numerical delta model'
+tags:
+  - Python
+  - sedimentology
+  - deltas
+  - stratigraphy
+authors:
+  - name: Andrew J. Moodie
+    orcid: 0000-0002-6745-036X
+    affiliation: "1"
+  - name: Jayaram Hariharan
+    orcid: 0000-0002-1343-193X
+    affiliation: "1"
+  - name: Eric Barefoot
+    orcid: 0000-0001-5770-2116
+    affiliation: "2"
+  - name: Paola Passalacqua
+    affiliation: "1"
+    orcid: 0000-0002-4763-7231
+affiliations:
+  - name: Department of Civil, Architectural, and Environmental Engineering, University of Texas at Austin, Austin, TX, USA
+    index: 1
+  - name: Department of Earth, Environmental and Planetary Sciences, Rice University, Houston, TX, USA
+    index: 2
+date: 08 June 2021
+bibliography: paper.bib
+---
+
+# Summary
+
+River deltas provide many societal benefits, and sustainability of these landforms may be impacted by human modification and global climate change.
+Reduced-complexity numerical delta models incorporate limited physical processes, allowing researchers to assess the spatiotemporal evolution of landscape response to individual processes and environmental forcings. 
+This is useful to understand, for example, shifting delta morphology due to sea-level rise, changing vegetal cover, or flooding intensity.
+As a result, many numerical delta models have been proposed in the literature, and results from these studies are difficult to compare because of various design and implementation choices.
+*pyDeltaRCM* (`v2.x`) delivers a computationally efficient and easy-to-customize implementation of the DeltaRCM numerical model [@liang_reduced_1_2015], enabling comparison and reproducibility in studies of delta change due to various environmental forcings.
+
+
+# Statement of need
+
+River deltas are societally important landforms because they provide arable land, deep inland ports, and are home to hundreds of millions of people globally [@edmonds_coastal_2020].
+Existing at the interface between landmasses and water bodies, deltas are impacted by a multitude of processes arising in both of these domains.
+For example, changes in sediment input to the delta modulate the rate at which new land is built; similarly, rising water levels in the downstream basin create flooded land.
+In addition to natural processes, human landscape modification renders deltaic environments more sensitive to global climate change into the future [@paola_natural_2011].
+Demand to understand natural delta processes, and how these processes will respond to various  environmental forcings, has led to a proliferation of numerical delta models in the literature [@overeem_three_2005].
+
+The DeltaRCM delta model [@liang_reduced_1_2015] has gained popularity among geomorphologists due to an attractive balance of computational cost, realism, and interpretability [@larsen_appropriate_2016]. 
+For example, studies have employed the DeltaRCM design to examine delta morphology and dynamism response to sea-level rise and regional subsidence [@liang_quantifying_2016; @liang_how_2016], as well as extended model design to simulate delta evolution with vegetation [@lauzon_comparing_2018] and ice and permafrost [@lauzon_ice_2019; @piliouras_unraveling_2021].
+However, comparison among these studies is difficult, owing to disparate code bases, various implementation choices, lack of version control, and proprietary software dependencies.
+
+
+# Background
+
+Here, version 2.x of *pyDeltaRCM* is introduced; *pyDeltaRCM* is a computationally efficient, free and open source, and easy-to-customize numerical delta model based on the original DeltaRCM design.
+The original DeltaRCM framework is inspired by well-understood physical phenomena, and models mass movement as a probabilistic weighted random-walk process coupled with a set of hierarchical rules; the model is extensively described in @liang_reduced_1_2015 and @liang_reduced_2_2015.
+
+This same framework is the basis for *pyDeltaRCM* v2.x, with a few modifications selected only to resolve known numerical instabilities, improve computational efficiency, and support reproducible simulations.
+*PyDeltaRCM* depends only on common Python packages `numpy` [@harris2020], `matplotlib` [@hunter2007], `scipy` [@virtanen2020], `netCDF4`, `pyyaml`, and `numba` [@lam_numba_2015].
+
+![Simulation with *pyDeltaRCM* v2.x, default parameter set, and random `seed: 10151919`. Simulation was run for 4000 timesteps, and assumes 10 days of bankfull discharge per year. \label{fig:timeseries}](figures/timeseries.png)
+
+
+# Flexible and easy to use
+
+*pyDeltaRCM* is an object-oriented package, providing the central model class `DeltaModel`.
+By creating custom model behavior as subclasses of `DeltaModel`, researchers can easily add, subtract, and modify model components without altering code that is not pertinent to the science objective.
+Importantly, separating custom code from core model code makes clear how different studies can be compared.
+The *pyDeltaRCM* documentation provides several examples for how to implement custom model behavior on top of the core `DeltaModel` object.
+
+*pyDeltaRCM* also provides infrastructure to accelerate scientific exploration, such as the ability to configure multiple simulations from a single file.
+A preprocessor orchestrates `parallel` simulations for multi-core systems (optionally), and implements several tools to support simulations exploring a parameter space.
+For example, `matrix` expansion converts lists of parameters into an n-dimensional set of simulations.
+Similarly, replicate simulations can be created via an `ensemble` specification.
+
+Reproducibility and computational efficiency were important priorities in *pyDeltaRCM* development.
+For example, to-disk logging records all parameters, system-level and version data, and random-seed information to ensure that all runs can be recreated.
+Additionally, "checkpoint" infrastructure has been added to the model, which records simulation progress during computation and can later resume model runs for further simulation.
+Finally, *pyDeltaRCM* uses `numba` for computational optimization [@lam_numba_2015], and does not depend on any proprietary software.
+
+*pyDeltaRCM* component units and integrations are thoroughly documented and tested.
+Component-level documentation describes implementation notes, whereas narratives in "Guide" and "Example" documentation describes high-level model design and best practices for model use and development.
+*pyDeltaRCM* also couples with other numerical models via the CSDMS Basic Model Interface 2.0 [@hutton_basic_2020; @BMI_pyDeltaRCM].
+
+
+# Acknowledgments
+
+We gratefully acknowledge Rebecca Lauzon and Mariela Perignon for developing an implementation of *DeltaRCM* in Python that was the basis for *pyDeltaRCM*. 
+We also thank the National Science Foundation for supporting us in developing this software, by way of a Postdoctoral Fellowship to A.M. (EAR 1952772) and a grant to J.H. and P.P. (EAR 1719670).
+
+
+# References