Merge pull request #18 from kbarnhart/barnhart_copyedits

JOSS copyedits

joss/paper.bib

@@ -35,16 +35,16 @@ @misc{delft3d
 	year = {2020}
 }
 
-@misc{Pearson1905,
+@article{Pearson1905,
 	author = {Pearson, Karl},
-	title = {Nature},
+	journal = {Nature},
 	doi = {10.1038/072342a0},
 	issn = {00280836},
 	keywords = {Humanities and Social Sciences,Science,multidisciplinary},
 	number = {1867},
 	pages = {342},
 	publisher = {Nature Publishing Group},
-	title = {{The problem of the random walk [3]}},
+	title = {The problem of the random walk},
 	volume = {72},
 	year = {1905}
 }
@@ -63,7 +63,7 @@ @article{Liang2015a
 }
 
 
-@article{Liang2015,
+@article{Liang2015b,
 	author = {Liang, M and Geleynse, N and Edmonds, D A and Passalacqua, P},
 	doi = {10.5194/esurf-3-87-2015},
 	issn = {2196632X},
@@ -124,6 +124,9 @@ @book{Kadlec2008
   title={Treatment wetlands},
   author={Kadlec, Robert H and Wallace, Scott},
   year={2008},
+  doi={10.1201/9781420012514},
+  isbn={9781420012514 },
+  address={Boca Raton, FL},
   publisher={CRC press}
 }
 
@@ -210,7 +213,7 @@ @article{Czuba2019
   number = {3},
   pages = {1849--1870},
   publisher = {Blackwell Publishing Ltd},
-  title = {{Dynamics of Surface-Water Connectivity in a Low-Gradient Meandering River Floodplain}},
+  title = {Dynamics of Surface-Water Connectivity in a Low-Gradient Meandering River Floodplain},
   url = {https://doi.org/10.1029/},
   volume = {55},
   year = {2019}
@@ -225,4 +228,4 @@ @article{Zhang2012
   year={2012},
   publisher={Wiley Online Library},
   doi={10.1029/2012GL053476}
-}
+}

joss/paper.md

@@ -24,15 +24,15 @@ bibliography: paper.bib
 
 # Summary
 
-Hydrodynamic simulations of flow through landscapes allow scientists to answer questions related to the transport of water, nutrients, pollutants, biota, and sediment through waterways [@Duan2006; @Rynne2016; @Wild-Allen2016; @Lauzon2018; @Czuba2019]. In geophysical systems, such as rivers, estuaries, and deltas, hydrodynamic models typically solve the depth-integrated ``shallow water" equations in an Eulerian reference frame, which is concerned with fluxes through a given region of space -- examples of these solvers include ANUGA [@anuga], Delft3D [@delft3d], Frehd [@Hodges2014] and others. However, the spatial and temporal characteristics of the movement of material through a landscape are often better understood using a Lagrangian reference frame [@Doyle2009], which follows the movement of individual objects or parcels. In this paper, we present an open-source Python package, *dorado*, which provides a transparent and accessible method for researchers to simulate passive Lagrangian particle transport on top of Eulerian hydrodynamic solutions. This mixed Eulerian-Lagrangian methodology adapts the routing functionality from the popular numerical model DeltaRCM [@Liang2015a; @Liang2015] for use with the outputs of any shallow-water hydrodynamic solver.
+Hydrodynamic simulations of flow through landscapes allow scientists to answer questions related to the transport of water, nutrients, pollutants, biota, and sediment through waterways [@Duan2006; @Rynne2016; @Wild-Allen2016; @Lauzon2018; @Czuba2019]. In geophysical systems, such as rivers, estuaries, and deltas, hydrodynamic models typically solve the depth-integrated "shallow water" equations in an Eulerian reference frame, which is concerned with fluxes through a given region of space -- examples of these solvers include ANUGA [@anuga], Delft3D [@delft3d], Frehd [@Hodges2014] and others. However, the spatial and temporal characteristics of the movement of material through a landscape are often better understood using a Lagrangian reference frame [@Doyle2009], which follows the movement of individual objects or parcels. In this paper, we present an open-source Python package, *dorado*, which provides a transparent and accessible method for researchers to simulate passive Lagrangian particle transport on top of Eulerian hydrodynamic solutions. This mixed Eulerian-Lagrangian methodology adapts the routing functionality from the popular numerical model DeltaRCM [@Liang2015a; @Liang2015b] for use with the outputs of any shallow-water hydrodynamic solver.
 
 # Statement of Need
 
 Existing software for tracking water parcels or particles in a Lagrangian framework typically contains complicated code structures [@freshkiss3d; @delft3d] with steep learning-curves, are proprietary [@fluent], or were developed to solve problems at very different spatial scales [@Yeung1989; @Dagestad2018] than typical riverine applications. This package fills a gap in the available methods for Lagrangian particle simulation by providing a flexible, open, and transparent framework meant for rapid application in conjunction with any landscape-scale 2D hydrodynamic model. In addition, *dorado* comes with built-in pre-processing, analysis, and plotting functionality, including methods to compute the exposure time distribution of particles to specific sub-regions of the domain, which is often of interest in ecological applications [@Kadlec2008].
 
 # Background
 
-*dorado* makes use of the weighted random walk framework [@Pearson1905] to model particle transport as a stochastic Markovian process, using a grid-centric approach that takes into account local water inertial components and surface slopes, in a manner modeled after the numerical model DeltaRCM [@Liang2015; @Liang2015a]. The random walk routing weights are sensitive to two user-specified parameters, $\gamma$ and $\theta$. The $\gamma$ parameter controls the proportional importance of water surface gradient and water velocity in determining the downstream routing direction $F^{*}$, according to:
+*dorado* makes use of the weighted random walk framework [@Pearson1905] to model particle transport as a stochastic Markovian process, using a grid-centric approach that takes into account local water inertial components and surface slopes, in a manner modeled after the numerical model DeltaRCM [@Liang2015a; @Liang2015b]. The random walk routing weights are sensitive to two user-specified parameters, $\gamma$ and $\theta$. The $\gamma$ parameter controls the proportional importance of water surface gradient and water velocity in determining the downstream routing direction $F^{*}$, according to:
 \begin{equation}
     F^{*} = \gamma F_{sfc} + (1-\gamma) F_{int}
 \end{equation}
@@ -41,11 +41,11 @@ in which $F_{sfc}$ and $F_{int}$ represent the surface gradient and inertial com
 \begin{equation}
     w_i = \frac{h_i^\theta \max \left(0, F \cdot d_i \right)}{\Delta_i}
 \end{equation}
-wherein $F$ are the routing directions, $d_i$ represents the unit vector from the current cell to its neighbor, and $\Delta_i$ is the D8 cellular distance. Here, the local flow depth acts as a resistance term -- as $\theta$ gets larger, the local routing weights have an increasingly large dependence on the water depth of the neighboring cells. By altering the two parameters $\gamma$ and $\theta$, the user has control over the randomness with which the particles are routed. For a full description of this methodology, see @Liang2015, @Liang2015a and the *dorado* documentation.
+wherein $F$ are the routing directions, $d_i$ represents the unit vector from the current cell to its neighbor, and $\Delta_i$ is the D8 cellular distance. Here, the local flow depth acts as a resistance term -- as $\theta$ gets larger, the local routing weights have an increasingly large dependence on the water depth of the neighboring cells. By altering the two parameters $\gamma$ and $\theta$, the user has control over the randomness with which the particles are routed. For a full description of this methodology, see Liang et al. [-@Liang2015a; -@Liang2015b] and the *dorado* documentation.
 
 Particle travel times are back-calculated from their locations after routing by accounting for the flow velocity, flow direction, and grid size. The time elapsed during each particle step is assumed to be proportional to the distance traveled in the direction of the mean flow, $d_{eq}$, which is equal to the step distance $\Delta_i$ projected onto a unit vector oriented in the direction of the velocity field, $\phi$, according to $d_{eq} = \Delta_i \cdot \cos(\phi)$. During a model iteration, each particle is allowed to progress a different length of time, depending on the velocity of the flow in the vicinity of each particle and the orientation of each step in relation to the mean flow direction. The travel time of each step is then modified according to a user-specified parameter, $D_c$, which acts as a dispersion coefficient.
 
-*dorado* provides functions with which users can choose to sync up the particle evolution by either number of step iterations or by individual particle travel times. In addition, *dorado* includes several post-processing functions for computing and plotting the fraction of time particles spend ``exposed" to a region of interest, otherwise known as the exposure time distribution (or residence time distribution, in steady flows) [@Kadlec2008; @Benjamin2013; @Hiatt2018]. This travel time methodology has been tested against analytical solutions for a plug-flow reactor with dispersion [@Benjamin2013], as well as against exposure time distributions from prior models of real systems [@Hiatt2018], and performed well at reproducing the observed travel times in both systems. As with all Lagrangian methods involving finite samples of particles, we expect the travel time computations to struggle to reproduce the heavy-tailed behavior observed in some systems [@Zhang2012], and expect that *dorado* will perform most accurately in advection-dominated flows.
+*dorado* provides functions with which users can choose to sync up the particle evolution by either number of step iterations or by individual particle travel times. In addition, *dorado* includes several post-processing functions for computing and plotting the fraction of time particles spend "exposed" to a region of interest, otherwise known as the exposure time distribution [or residence time distribution, in steady flows, @Kadlec2008; @Benjamin2013; @Hiatt2018]. This travel time methodology has been tested against analytical solutions for a plug-flow reactor with dispersion [@Benjamin2013], as well as against exposure time distributions from prior models of real systems [@Hiatt2018], and performed well at reproducing the observed travel times in both systems. As with all Lagrangian methods involving finite samples of particles, we expect the travel time computations to struggle to reproduce the heavy-tailed behavior observed in some systems [@Zhang2012], and expect that *dorado* will perform most accurately in advection-dominated flows.
 
 # Functionality and Ease of Use