Merge pull request #4 from elbeejay/doc-edits

Doc edits

README.md

@@ -7,8 +7,6 @@
     <img src="docs/source/examples/images/logo.gif" alt="Particle routing on Lidar-derived bathymetry" width="65%"></a>
 </div>
 
-v1.0.0
-
 dorado is a Python package for simulating passive Lagrangian particle transport over flow-fields from any 2D shallow-water hydrodynamic model using a weighted random walk methodology.
 
 For user guides and detailed examples, refer to the [documentation](https://passah2o.github.io/dorado/index.html).
@@ -34,3 +32,6 @@ For additional installation options and instructions, refer to the [documentatio
 
 ## Contributing
 We welcome contributions to the dorado project. Please open an issue or a pull request if there is functionality you would like to see or propose. Refer to our [contributing guide](https://passah2o.github.io/dorado/misc/contributing.html) for more information.
+
+## Funding Acknowledgments
+This work was supported in part by NSF EAR-1719670, the NSF GRFP under grant DGE-1610403 and the NASA Earth Venture Suborbital-3 Program as part of the Delta-X mission.

docs/source/background/index.rst

@@ -10,6 +10,10 @@ Motivation
 
 By developing `dorado` as a standalone python package, we hope to simplify the simulation of Lagrangian particle transport so that it may be applied to the results from any hydrodynamic simulation.
 
+Name
+----
+The name `dorado` is inspired by the `fish <https://en.wikipedia.org/wiki/Salminus_brasiliensis>`_.
+
 Theory
 ------
 Particle transport is simulated through the use of a weighted random walk framework [4]_. In particular, we apply methods similar to those used in the numerical model DeltaRCM [5]_ [6]_, to weight the random walk by the local water slopes and the water discharge components.
@@ -18,37 +22,37 @@ Particle transport is simulated through the use of a weighted random walk framew
 
 The weights for the random walk are sensitive to 2 parameters, :math:`{\gamma}` and :math:`{\theta}`.
 
-The routing direction F* is the estimate of the local downstream of the flow [5]. This direction F* is comprised of :math:`{F_{sfc}}`, and :math:`{F_{int}}`, calculated based on the water surface gradient and the discharge respectively. The proportional combination of these directional components is dictated by the parameter :math:`{\gamma}`:
+The routing direction (F*) is the estimate of the local downstream of the flow [5]. This direction F* is comprised of :math:`{F_{sfc}}`, and :math:`{F_{int}}`, calculated based on the water surface gradient and the discharge respectively. The proportional combination of these directional components is dictated by the parameter :math:`{\gamma}`:
 
 .. math::
 
       F^{*} = \gamma F_{sfc} + (1-\gamma) F_{int}
 
-In this way, the :math:`{\gamma}` parameter controls the proportional dependence of water surface slope and water discharge on the downstream direction. A :math:`{\gamma}` of 0 means that the water slope is ignored when determining the downstream flow direction, and a :math:`{\gamma}`: of 1 means that the discharge values (the flow field) is ignored.
+In this way, the :math:`{\gamma}` parameter controls the proportional dependence of water surface slope and water discharge on the downstream direction. A :math:`{\gamma}` of 0 means that the water slope is ignored when determining the downstream flow direction, and a :math:`{\gamma}` of 1 means that the discharge values (the flow field) is ignored.
 
 The second weighting parameter, :math:`{\theta}` modifies the routing weight for the random walk based on the local water depth value. The routing weights for each neighboring cell are calculated per [5], using the following equation:
 
 .. math::
 
       w_i = \frac{\frac{1}{R_i} \text{max} \left(0, F \cdot d_i \right)}{\Delta_i}
 
-The resistance value, :math:`{R_i}`, is computed using the local water depth, :math:`{h_i}` and the parameter :math:`{\theta}`:
+The resistance value (:math:`{R_i}`) is computed using the local water depth (:math:`{h_i}`) and the parameter :math:`{\theta}`:
 
 .. math::
 
       R_i = \frac{1}{h_i^\theta}
 
 When :math:`{\theta}` is 0, then the local depth values are not impacting the weighting factor associated with each cell. As :math:`{\theta}` gets larger, the local routing weights have an increasingly large dependence on the water depth of the neighboring cells.
 
-To measure the travel times associated with the particles as they move through the flow field, both the flow velocity and the direction of the flow are taken into account. As the particles are routed on a grid, there is a loss of accuracy due to the assumption that particles are located in the center of grid cells. To account for this 'lost time', a diffusive coefficient, :math:`{dc}` is applied to introduce some diffusivity to the travel time values.
+To measure the travel times associated with the particles as they move through the flow field, both the flow velocity and the direction of the flow are taken into account. As the particles are routed on a grid, there is a loss of accuracy due to the assumption that particles are located in the center of grid cells. To account for this 'lost time', a diffusive coefficient (:math:`{dc}`) is applied to introduce some diffusivity to the travel time values.
 
-The travel time calculation is based on the effective distance the particle travels in the orientation of the mean flow at the particle's location. This effective or projected distance (:math:`{d_{eq}}`) is computed using the definition of a vector projection based on the actual distance being traveled (:math:`{\Delta}`) and the orientation of travel relative to the mean flow vector (:math:`{\phi}`).
+The travel time calculation is based on the effective distance the particle travels in the orientation of the mean flow at the particle's location. This effective or projected distance (:math:`{d_{eq}}`) is computed using the definition of a vector projection based on the actual distance being traveled (:math:`{\Delta}`) and the orientation of travel relative to the mean flow vector (:math:`{\phi}`):
 
 .. math::
 
      d_{eq} = \Delta \times \cos{\phi}
 
-The travel time (:math:`{T_t}`) is then calculated based on this effective distance (:math:`{d_{eq}}`) and the average of the inverted velocity values at the origin cell location (:math:`{o}`) and the new cell location (:math:`{i}`) for the particle. To re-introduce diffusivity lost due to the gridded scheme used in `dorado`, the travel time is also modulated by a user-specified diffusivity coefficient :math:`{dc}` which is multiplied by a sample from a uniform distribution centered at 0.
+The travel time (:math:`{T_t}`) is then calculated based on this effective distance (:math:`{d_{eq}}`) and the average of the inverted velocity values at the origin cell location (:math:`{o}`) and the new cell location (:math:`{i}`) for the particle. To re-introduce diffusivity lost due to the gridded scheme used in `dorado`, the travel time is also modulated by a user-specified diffusivity coefficient (:math:`{dc}`) which is multiplied by a sample from a uniform distribution centered at 0:
 
 .. math::
 

docs/source/examples/example12.rst

@@ -30,6 +30,6 @@ Now that the basic parameters have been established, we will apply the `unsteady
    >>> walk_data = unsteady_plots(params, 26, 75., 'unsteady_data',
    >>>                            'csv', 'unsteady_output')
 
-If you run the example, data and figures will be placed in a subdirectory called `unsteady_output`. Below, there is an animation of the particles moving on the varying flow field. We can see that when the flow is inverted our 'tide' pushes the particles back towards the inlet channel.
+If you run the example, data and figures will be placed in a subdirectory called `unsteady_output`. Below, there is an animation of the particles moving on the varying flow field. We can see that when the flow is inverted, our 'tide' pushes the particles back towards the inlet channel.
 
 .. image:: images/example12/unsteady_example.gif

docs/source/examples/example13.rst

@@ -134,7 +134,7 @@ same size as our model’s extent. To use this function, we need to
 provide: - Our list of ``coordinates`` (as tuples). - The unstructured
 data we want to be gridded (here we start with ``depth``). - The desired
 grid size of the resulting rasters (here we’re using :math:`1 m`,
-because the test model was on very high-resolution lidar data). - The
+because the test model was on high-resolution lidar data). - The
 number of :math:`k` nearest neighbors to use in the interpolation. If
 :math:`k=1`, we use only the nearest datapoint, whereas higher values
 (default is :math:`k=3`) interpolate the data into a smoother result.
@@ -218,11 +218,11 @@ Otherwise, if you’re loading data from e.g. a GeoTIFF, the lower left
 corner will be stored in the .tif metadata and can be accessed by GIS
 software or gdalinfo (if the user has GDAL) - The dimensions of the
 raster, accessible via ``np.shape(raster)`` - The grid size of the
-raster (here :math:`1m`)
+raster (here :math:`1m`).
 
 **Note:** this coordinate transform flips the orientation of the unit
-vectors (i.e. :math:`y_{index} = x` and :math:`x_{index} = -y`) as well
-as returning raster indices. This is convenient for the internal
+vectors (i.e. :math:`y_{index} = x` and :math:`x_{index} = -y`) and
+returns raster indices. This is convenient for the internal
 functions of ``particle_tools.py``, but may cause confusion with
 plotting or interpreting later if locations are not translated back into
 spatial coordinates. (Don’t worry, we will convert back later!)
@@ -323,7 +323,7 @@ iterations and return the travel history to us in the ``walk_data``
 dict. This dict is organized into ``['xinds']``, ``['yinds']``, and
 ``['travel_times']``, which are then indexed by particle ID, and then
 finally iteration number. (e.g. ``walk_data['xinds'][5][10]`` will
-return the xindex for the 6th particle’s 11th iteration)
+return the xindex for the 6th particle’s 11th iteration).
 
 .. code:: ipython
 
@@ -371,7 +371,7 @@ number.
 
 
 **Note:** There exists an equivalent function, ``get_time_state()``,
-which performs a similar function by slicing ``walk_data`` along a given
+which slices ``walk_data`` along a given
 travel time, in case there is interest in viewing the particles in sync.
 
 As a brief aside, the particle routing can also be run in an *unsteady*
@@ -382,7 +382,7 @@ up their propagation with an unsteady flow field that updates every so
 often (e.g. every 30 minutes). This can be done either with the
 ``unsteady_plots()`` routine, or by interacting with ``run_iteration()``
 directly. The commented-out block of code below shows an example of what
-an unsteady case might look like had we used more timesteps from the
+an unsteady case might look like, had we used more timesteps from the
 model output.
 
 .. code:: ipython
@@ -485,8 +485,8 @@ ROI, all those times are counted.
 
 **Note:** For a representative ETD, it is important to run a *lot* of
 particles. A large sample size is needed to obtain a realistic
-distribution (and smooth plots). Depending on the domain, I recommend at
-least :math:`O(10^3)`
+distribution (and smooth plots). Depending on the domain, we recommend at
+least :math:`O(10^3)`.
 
 First, let’s generate and visualize the ROI:
 

docs/source/index.rst

@@ -50,3 +50,11 @@ API Reference and Contributing Guidelines
    misc/license
    misc/contributing
    apiref/index
+
+
+Funding Acknowledgments
+#######################
+.. toctree::
+   :maxdepth: 1
+
+   misc/acknowledgments

docs/source/misc/acknowledgments.rst

@@ -0,0 +1,7 @@
+.. _acknowledgments:
+
+===============
+Acknowledgments
+===============
+
+This work was supported in part by NSF EAR-1719670, the NSF GRFP under grant DGE-1610403 and the NASA Earth Venture Suborbital-3 Program as part of the Delta-X mission.

docs/source/userguide/index.rst

@@ -7,7 +7,7 @@ User Guide
 Overview
 --------
 
-The basic workflow when using `dorado`, can be summarized in two steps.
+The basic workflow when using `dorado` can be summarized in two steps:
 
 1. Initialize parameters using the `particle_track.params` class and provide information about the domain, where and how many particles are going to be seeded, and adjust any parameters as desired.
 
@@ -26,7 +26,7 @@ Defining the parameters is require prior to doing any particle routing. Initiati
    >>> import dorado.particle_track as pt
    >>> params = pt.params()
 
-After establishing the parameter class, information about the domain must be provided, as well as information about where the particles are going to be seeded and how many particles should be used. As `dorado` is a generic package designed to be used with a variety of input datasets or model outputs, we have tried to make the required input parameters as flexible as possible however some values **must** be provided.
+After establishing the parameter class, information about the domain must be provided, as well as information about where the particles are going to be seeded and how many particles should be used. As `dorado` is a generic package designed to be used with a variety of input datasets or model outputs, we have tried to make the required input parameters as flexible as possible, however some values **must** be provided.
 
 Required Parameters
 ^^^^^^^^^^^^^^^^^^^

dorado/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "0.9.3"
+__version__ = "1.0.0"
 
 from . import particle_tools
 from . import parallel_routing

dorado/parallel_routing.py

@@ -3,7 +3,7 @@
 Parallel functionality using multiprocessing (included with Python).
 For local parallelization using CPU cores.
 
-Project Homepage: https://github.com/
+Project Homepage: https://github.com/passaH2O/dorado
 """
 from __future__ import division, print_function, absolute_import
 from builtins import range, map

dorado/particle_tools.py

@@ -2,7 +2,7 @@
 """
 Particle tools to manage the internal functions related to the routing.
 
-Project Homepage: https://github.com/
+Project Homepage: https://github.com/passaH2O/dorado
 """
 from __future__ import division, print_function, absolute_import
 from builtins import range, map
@@ -47,7 +47,7 @@ class Tools():
     do a single iteration of the particle transport (**run_iteration**)
 
     """
-    
+
     # random pick seeding location
     def random_pick_seed(self, choices, probs=None):
         """Randomly pick a number from array of choices.

dorado/particle_track.py

@@ -6,7 +6,7 @@
 parameters of the domain as well as iterative movement of the particles
 through the domain.
 
-Project Homepage: https://github.com/
+Project Homepage: https://github.com/passaH2O/dorado
 """
 from __future__ import division, print_function, absolute_import
 from builtins import range

dorado/routines.py

@@ -2,7 +2,7 @@
 """
 Higher level methods for routing and visualizing tracer particles.
 
-Project Homepage: https://github.com/
+Project Homepage: https://github.com/passaH2O/dorado
 """
 from __future__ import division, print_function, absolute_import
 from builtins import range

joss/paper.bib

@@ -50,6 +50,7 @@ @misc{Pearson1905
 }
 
 @article{Liang2015a,
+    author = {Liang, M and Voller, V R and Paola, C},
 	doi = {10.5194/esurf-3-67-2015},
 	issn = {2196632X},
 	journal = {Earth Surface Dynamics},
@@ -61,6 +62,7 @@ @article{Liang2015a
 	year = {2015}
 }
 
+
 @article{Liang2015,
 	author = {Liang, M and Geleynse, N and Edmonds, D A and Passalacqua, P},
 	doi = {10.5194/esurf-3-87-2015},
@@ -82,3 +84,145 @@ @misc{fluent
 	year = {2020}
 }
 
+@article{Hodges2014,
+    author = {Hodges, Ben R.},
+    doi = {10.1016/j.ocemod.2014.02.007},
+    issn = {14635003},
+    journal = {Ocean Modelling},
+    month = {may},
+    pages = {1--19},
+    publisher = {Elsevier BV},
+    title = {{A new approach to the local time stepping problem for scalar transport}},
+    volume = {77},
+    year = {2014}
+}
+
+@article{Doyle2009,
+  title={Alternative reference frames in river system science},
+  author={Doyle, Martin W and Ensign, Scott H},
+  journal={BioScience},
+  volume={59},
+  number={6},
+  pages={499--510},
+  year={2009},
+  publisher={American Institute of Biological Sciences Circulation, AIBS, 1313 Dolley~…},
+  doi={10.1525/bio.2009.59.6.8}
+}
+
+@article{Yeung1989,
+  title={Lagrangian statistics from direct numerical simulations of isotropic turbulence},
+  author={Yeung, Pui-Kuen and Pope, Stephen B},
+  journal={Journal of Fluid Mechanics},
+  volume={207},
+  pages={531--586},
+  year={1989},
+  publisher={Cambridge University Press},
+  doi={10.1017/S0022112089002697}
+}
+
+@book{Kadlec2008,
+  title={Treatment wetlands},
+  author={Kadlec, Robert H and Wallace, Scott},
+  year={2008},
+  publisher={CRC press}
+}
+
+@book{Benjamin2013,
+  title={Water quality engineering: Physical/chemical treatment processes},
+  author={Benjamin, Mark M and Lawler, Desmond F},
+  year={2013},
+  publisher={John Wiley \& Sons}
+}
+
+@article{Hiatt2018,
+  title={Channel-island connectivity affects water exposure time distributions in a coastal river delta},
+  author={Hiatt, Matthew and Casta{\~n}eda-Moya, Edward and Twilley, Robert and Hodges, Ben R and Passalacqua, Paola},
+  journal={Water Resources Research},
+  volume={54},
+  number={3},
+  pages={2212--2232},
+  year={2018},
+  publisher={Wiley Online Library},
+  doi={10.1002/2017WR021289}
+}
+
+@article{Lauzon2018,
+  author = {Lauzon, Rebecca and Murray, A. Brad},
+  doi = {10.1029/2018GL079405},
+  issn = {19448007},
+  journal = {Geophysical Research Letters},
+  month = {oct},
+  number = {19},
+  pages = {10,437--10,445},
+  publisher = {John Wiley & Sons, Ltd},
+  title = {Comparing the Cohesive Effects of Mud and Vegetation on Delta Evolution},
+  url = {https://onlinelibrary.wiley.com/doi/abs/10.1029/2018GL079405},
+  volume = {45},
+  year = {2018}
+}
+
+@article{Wild-Allen2016,
+  author = {Wild-Allen, Karen and Andrewartha, John},
+  doi = {10.1016/j.marchem.2016.05.011},
+  issn = {03044203},
+  journal = {Marine Chemistry},
+  month = {oct},
+  pages = {12--26},
+  publisher = {Elsevier B.V.},
+  title = {Connectivity between estuaries influences nutrient transport, cycling and water quality},
+  volume = {185},
+  year = {2016}
+}
+
+@article{Rynne2016,
+  author = {Rynne, Patrick and Reniers, Ad and van de Kreeke, Jacobus and MacMahan, Jamie},
+  doi = {10.1016/j.ecss.2016.02.001},
+  issn = {02727714},
+  journal = {Estuarine, Coastal and Shelf Science},
+  month = {apr},
+  pages = {108--120},
+  publisher = {Academic Press},
+  title = {The effect of tidal exchange on residence time in a coastal embayment},
+  volume = {172},
+  year = {2016}
+}
+
+@article{Duan2006,
+  author = {Duan, Jennifer G. and Nanda, S. K.},
+  doi = {10.1016/j.jhydrol.2005.11.055},
+  issn = {00221694},
+  journal = {Journal of Hydrology},
+  month = {aug},
+  number = {3-4},
+  pages = {426--437},
+  publisher = {Elsevier},
+  title = {Two-dimensional depth-averaged model simulation of suspended sediment concentration distribution in a groyne field},
+  volume = {327},
+  year = {2006}
+}
+
+@article{Czuba2019,
+  author = {Czuba, Jonathan A. and David, Scott R. and Edmonds, Douglas A. and Ward, Adam S.},
+  doi = {10.1029/2018WR023527},
+  issn = {19447973},
+  journal = {Water Resources Research},
+  month = {mar},
+  number = {3},
+  pages = {1849--1870},
+  publisher = {Blackwell Publishing Ltd},
+  title = {{Dynamics of Surface-Water Connectivity in a Low-Gradient Meandering River Floodplain}},
+  url = {https://doi.org/10.1029/},
+  volume = {55},
+  year = {2019}
+}
+
+@article{Zhang2012,
+  title={Linking fluvial bed sediment transport across scales},
+  author={Zhang, Yong and Meerschaert, Mark M and Packman, Aaron I},
+  journal={Geophysical Research Letters},
+  volume={39},
+  number={20},
+  year={2012},
+  publisher={Wiley Online Library},
+  doi={10.1029/2012GL053476}
+}