docs improvements and updates

docs/src/examples.md

@@ -1,11 +1,11 @@
 
 ## Examples
 
-The four examples outlined below form a tutorial of sorts, and thus complement the [User Guide](@ref). They rely on `flow_fields.jl` to define grids and ingest velocity fields. The main goal is to provide a useful jumping off point in order to configure `IndividualDisplacements.jl` for new problems.
+The four examples outlined below form a tutorial of sorts that complements the [User Guide](@ref). They hopefully provide a useful jumping off point in order to configure `IndividualDisplacements.jl` for new problems.
 
-Output is in [DataFrames](https://juliadata.github.io/DataFrames.jl/latest/) tabular format which comes with powerful and convenient analysis methods. Plotting results in space and time can be done as in `recipes_plots.jl`, `recipes_makie.jl`, and `recipes_pyplot.jl` -- see the examples.
+Output from is `IndividualDisplacements.jl` is in [DataFrames.jl](https://juliadata.github.io/DataFrames.jl/latest/) tabular format which comes with powerful and convenient analysis methods. They can  readily be plotted in space and time using e.g. `Plots.jl` or `Makie.jl`.
 
-To run an example, the recommended method is to copy the corresponding `notebook (code)` link, paste into the [Pluto.jl](https://github.com/fonsp/Pluto.jl/wiki/🔎-Basic-Commands-in-Pluto) prompt, and click `open`.
+To rerun an example yourself, the recommended method is to copy the corresponding `notebook (code)` link, paste it into the [Pluto.jl](https://github.com/fonsp/Pluto.jl/wiki/🔎-Basic-Commands-in-Pluto) prompt, and click `open`.
 
 ## Simple Two-Dimensional Flow
 
@@ -43,15 +43,18 @@ The flow field is based on a data-constrained ocean model solution. The problem
 
 A simulation of particles that follow the three-dimensional ocean circulation. This example illustrates (1) the 3D case in a relatistic configuration, (2) tracking the advent or origin of a water patch, and (3) multifacted visualizations in 3D.
 
-The flow field is based on a data-constrained, realistic, ocean model. The problem configuration mimics, albeit very approximately, ocean tracers / coumpounds transported by water masses .
+The flow field is based on a data-constrained, realistic, ocean model. The problem configuration mimics, albeit very approximately, ocean tracers / coumpounds transported by water masses.
 
 ## Additional Examples
 
-- Interactive UI (Pluto.jl) : [notebook (html)](interactive_UI.html) ➭ [notebook (code)](https://github.com/JuliaClimate/IndividualDisplacements.jl/blob/master/examples/worldwide/interactive_UI.jl)
+- Interactivity : [notebook (html)](interactive_UI.html) ➭ [notebook (code)](https://github.com/JuliaClimate/IndividualDisplacements.jl/blob/master/examples/worldwide/interactive_UI.jl)
+- Atmosphere : [notebook (html)](https://gaelforget.github.io/MITgcmTools.jl/dev/examples/HS94_particles.html) ➭ [notebook (code)](https://raw.githubusercontent.com/gaelforget/MITgcmTools.jl/master/examples/HS94_particles.jl)
+- MITgcm : [Particle cloud](../particle_cloud/index.html), [Detailed look](../detailed_look/index.html) 
+- Plotting : [Plots.jl](https://github.com/JuliaClimate/IndividualDisplacements.jl/blob/master/examples/jupyter/recipes_plots.jl), [Makie.jl](https://github.com/JuliaClimate/IndividualDisplacements.jl/blob/master/examples/jupyter/recipes_makie.jl), [PyPlot.jl](https://github.com/JuliaClimate/IndividualDisplacements.jl/blob/master/examples/jupyter/recipes_pyplot.jl)
 
-- Particle cloud (MITgcm) : [notebook (html)](../particle_cloud/index.html) ➭ [notebook (code)](https://github.com/JuliaClimate/IndividualDisplacements.jl/blob/master/examples/basics/particle_cloud.jl)
+## Animations
 
-- Detailed look (MITgcm) : [notebook (html)](../detailed_look/index.html) ➭ [notebook (code)](https://github.com/JuliaClimate/IndividualDisplacements.jl/blob/master/examples/basics/detailed_look.jl)
+Below are animations of results generated in [Global Ocean Circulation](@ref) and [Three Dimensional Pathways](@ref).
 
 [![simulated particle movie (5m)](https://user-images.githubusercontent.com/20276764/84766999-b801ad80-af9f-11ea-922a-610ad8a257dc.png)](https://youtu.be/W5DNqJG9jt0)
 

docs/src/index.md

@@ -1,10 +1,10 @@
 # IndividualDisplacements.jl
 
-[IndividualDisplacements.jl](https://github.com/JuliaClimate/IndividualDisplacements.jl) computes elementary point displacements over a gridded Earth domain (e.g. a climate model `C-grid`). A typical application is the simulation and analysis of materials moving through atmospheric flows (e.g. dust or chemicals) or oceanic flows (e.g. plastics or planktons).
+[IndividualDisplacements.jl](https://github.com/JuliaClimate/IndividualDisplacements.jl) computes elementary point displacements over gridded domains. Inter-operability with global climate model output (on [Arakawa](https://en.wikipedia.org/wiki/Arakawa_grids) `C-grids` in general) that can be represented via [MeshArrays.jl](https://github.com/JuliaClimate/MeshArrays.jl) (see [these docs](https://juliaclimate.github.io/MeshArrays.jl/dev/)) is a central goal of [IndividualDisplacements.jl](https://github.com/JuliaClimate/IndividualDisplacements.jl). 
 
-Inter-operability with common climate model grids and their representation in [MeshArrays.jl](https://github.com/JuliaClimate/MeshArrays.jl) is a central element ([docs](https://juliaclimate.github.io/MeshArrays.jl/dev/)). [IndividualDisplacements.jl](https://github.com/JuliaClimate/IndividualDisplacements.jl) can also read and plot trajectories using [MIT General Circulation Model](https://mitgcm.readthedocs.io/en/latest/?badge=latest) output or [Ocean Drifting Buoy](https://doi.org/10.1002/2016JC011716) data ([movie](https://youtu.be/82HPnYBtoVo)). It was originally developed using [ECCOv4](https://eccov4.readthedocs.io/en/latest/) and [CBIOMES](https://cbiomes.readthedocs.io/en/latest/) ocean model simulations ([Forget et al. 2015](https://doi.org/10.5194/gmd-8-3071-2015), [Forget, 2018](http://doi.org/10.5281/zenodo.1343303)).
+The initial example suite relies on gridded ocean transports estimated in [OCCA](https://doi.org/10.7910/DVN/RNXA2A) ([Forget 2010](http://dx.doi.org/10.1175/2009JPO4043.1)), [ECCOv4](https://eccov4.readthedocs.io/en/latest/) ([Forget et al. 2015](https://doi.org/10.5194/gmd-8-3071-2015)), and [CBIOMES](https://cbiomes.readthedocs.io/en/latest/) ([Forget, 2018](http://doi.org/10.5281/zenodo.1343303)). For the Atmosphere, an additional example based on an idealized model simulation is provided in [MITgcmTools.jl](https://gaelforget.github.io/MITgcmTools.jl/dev/). 
 
-[![simulated particle movie (95m)](https://user-images.githubusercontent.com/20276764/90925145-ca90cc80-e3be-11ea-8eed-559307dcb925.png)](https://youtu.be/tsdf4fmYt1k)
+Typical applications include the simulation and analysis of materials moving through atmospheric flows (e.g. dust or chemicals) or oceanic flows (e.g. plastics or planktons). An illustration of the type of observations that [IndividualDisplacements.jl](https://github.com/JuliaClimate/IndividualDisplacements.jl) can simulate is provided below. These data collected by [Ocean Drifting Buoy](https://doi.org/10.1002/2016JC011716) can be accessed via [OceanRobots.jl](https://gaelforget.github.io/OceanRobots.jl/dev/).
 
 [![Global Drifter Program data](https://user-images.githubusercontent.com/20276764/90924860-41799580-e3be-11ea-96bd-9a5784d00ecc.png)](https://youtu.be/82HPnYBtoVo)
 

docs/src/workflow.md

@@ -10,7 +10,7 @@ As documented in the **examples**, the typical worflow is:
 1. set up `FlowFields` data structure
 1. set up `Individuals` with initial position `📌`
 1. displace `Individuals` (by	`∫🚄dt`) according to `FlowFields`
-1. post-process (`🔧`) and record (`🔴`) results
+1. post-process (`🔧`) and record diagnostics in `🔴`
 1. go back to `step 2` and continue if needed
 
 The data structures for steps `1` and `2` are documented below. Both steps `3` and `4` normally take place as part of `∫!` which post-processes results, using 🔧, records them in 🔴, and updates individual positions 📌 at the end. As a [DataFrame](https://juliadata.github.io/DataFrames.jl/latest/), 🔴 is easily manipulated, plotted, or saved in step `4` (or after the fact).

src/API.jl

@@ -141,7 +141,10 @@ default_postproc = (x->x)
 The velocity function 🚄 typically computes velocity at individual positions (📌 to start) within the 
 specified space-time domain by interpolating gridded variables (provided via 𝑃). Individual trajectories 
 are computed by integrating (∫) interpolated velocities through time. Normally, integration is done by 
-calling ∫! which updates 📌 at the end and records results in 🔴 via 🔧. Unicode cheatsheet:
+calling ∫! which updates 📌 at the end and records results in 🔴 via 🔧. Ancillary data, for use in 
+🔧 for example, can be provided in 𝐷 and metadata stored in 𝑀.
+
+Unicode cheatsheet:
 
 - 📌=`\\:pushpin:<tab>`,          🔴=`\\:red_circle:<tab>`, 🆔=`\\:id:<tab>`
 - 🚄=`\\:bullettrain_side:<tab>`, ∫=`\\int<tab>`,          🔧=`\\:wrench:<tab>`