Some minor textual changes to the output tutorial

Author: erikvansebille

parcels/examples/tutorial_output.ipynb

@@ -4,16 +4,22 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Tutorial on how to handle Parcels output\n",
-    "This tutorial covers the format of the trajectory output exported by Parcels. **Parcels does not include advanced analysis or plotting functionality**, which users are suggested to write themselves to suit their research goals. Here we provide some starting points to discover the parcels output.\n",
+    "# Tutorial on how to analyse Parcels output"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "This tutorial covers the format of the trajectory output exported by Parcels. **Parcels does not include advanced analysis or plotting functionality**, which users are suggested to write themselves to suit their research goals. Here we provide some starting points to explore the parcels output files yourself.\n",
     "\n",
     "* [**Reading the output file**](#Reading-the-output-file)\n",
     "* [**Trajectory data structure**](#Trajectory-data-structure)\n",
     "* [**Analysis**](#Analysis)\n",
     "* [**Plotting**](#Plotting)\n",
     "* [**Animations**](#Animations)\n",
     "\n",
-    "First we need to create some parcels output to analyse. We simulate some particles using the setup described in the [Delay start tutorial](https://nbviewer.jupyter.org/github/OceanParcels/parcels/blob/master/parcels/examples/tutorial_delaystart.ipynb)."
+    "First we need to create some parcels output to analyse. We simulate a set of particles using the setup described in the [Delay start tutorial](https://nbviewer.jupyter.org/github/OceanParcels/parcels/blob/master/parcels/examples/tutorial_delaystart.ipynb)."
    ]
   },
   {
@@ -62,8 +68,8 @@
    "metadata": {},
    "source": [
     "## Reading the output file\n",
-    "### netCDF4\n",
-    "The [`parcels.particlefile.ParticleFile`](https://oceanparcels.org/gh-pages/html/#parcels.particlefile.ParticleFile) class creates a netCDF file to store the particle trajectories. It uses the [**`netCDF4` module**](https://unidata.github.io/netcdf4-python/netCDF4/index.html), which is also suitable to open and read the files for analysis. The [`Dataset` class](https://unidata.github.io/netcdf4-python/netCDF4/index.html#netCDF4.Dataset) opens a netCDF file in reading mode by default. Data can be accessed with the `Dataset.variables` dictionary which can return (masked) numpy arrays."
+    "### Using the netCDF4 package\n",
+    "The [`parcels.particlefile.ParticleFile`](https://oceanparcels.org/gh-pages/html/#parcels.particlefile.ParticleFile) class creates a netCDF file to store the particle trajectories. It uses the [**`netCDF4` package**](https://unidata.github.io/netcdf4-python/netCDF4/index.html), which is also suitable to open and read the files for analysis. The [`Dataset` class](https://unidata.github.io/netcdf4-python/netCDF4/index.html#netCDF4.Dataset) opens a netCDF file in reading mode by default. Data can be accessed with the `Dataset.variables` dictionary which can return (masked) numpy arrays."
    ]
   },
   {
@@ -129,8 +135,8 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### xarray\n",
-    "An often used alternative which also comes with the parcels installation is [**xarray**](http://xarray.pydata.org/en/stable/index.html). Its labelled arrays allow for intuitive and accessible handling of data stored in the netCDF format."
+    "### Using the xarray package\n",
+    "An often-used alternative to netCDF4, which also comes with the parcels installation, is [**xarray**](http://xarray.pydata.org/en/stable/index.html). Its labelled arrays allow for intuitive and accessible handling of data stored in the netCDF format."
    ]
   },
   {
@@ -203,9 +209,9 @@
    "metadata": {},
    "source": [
     "## Trajectory data structure\n",
-    "The data in the netCDF file are organised according to the [CF-conventions](http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#discrete-sampling-geometries) implemented with the [NCEI trajectory template](http://www.nodc.noaa.gov/data/formats/netcdf/v2.0/trajectoryIncomplete.cdl). The data is stored in a **two-dimensional array** with the dimensions **`traj`** and **`obs`**. Each particle trajectory is essentially stored as a time series where the coordinate data (**lon**, **lat**, **time**) are a function of the observation (`obs`).\n",
+    "The data in the netCDF file are organised according to the [CF-conventions](http://cfconventions.org/cf-conventions/v1.6.0/cf-conventions.html#discrete-sampling-geometries) implemented with the [NCEI trajectory template](http://www.nodc.noaa.gov/data/formats/netcdf/v2.0/trajectoryIncomplete.cdl). The data is stored in a **two-dimensional array** with the dimensions **`traj`** and **`obs`**. Each particle trajectory is essentially stored as a time series where the coordinate data (**`lon`**, **`lat`**, **`time`**) are a function of the observation (`obs`).\n",
     "\n",
-    "In the current output dataset we find **10 particles** and **13 observations**. Not every particle has 13 observations however; since we released particles at different times some particle trajectories are shorter than others."
+    "The output dataset used here contains **10 particles** and **13 observations**. Not every particle has 13 observations however; since we released particles at different times some particle trajectories are shorter than others."
    ]
   },
   {
@@ -241,15 +247,15 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Note how the first observation occurs at a different time for each trajectory. **`obs` != time**"
+    "Note how the first observation occurs at a different time for each trajectory. **`obs` != `time`**"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
     "## Analysis\n",
-    "Sometimes trajectories are analysed like they are stored: as individual time series. If we want to study the distance travelled as a function of time, the time we are interested in is the time relative to the start of the each particular trajectory: the array operations are simple since each trajectory is analysed as a function of `obs`. The time variable is only needed to express the results in the correct units."
+    "Sometimes, trajectories are analysed as they are stored: as individual time series. If we want to study the distance travelled as a function of time, the time we are interested in is the time relative to the start of the each particular trajectory: the array operations are simple since each trajectory is analysed as a function of **`obs`**. The time variable is only needed to express the results in the correct units."
    ]
   },
   {
@@ -260,7 +266,7 @@
    "source": [
     "x = data_xarray['lon'].values\n",
     "y = data_xarray['lat'].values\n",
-    "distance = np.cumsum(np.sqrt(np.square(np.diff(x))+np.square(np.diff(y))),axis=1) # d = (dx^2 + dy^2)^(1/2)"
+    "distance = np.cumsum(np.sqrt(np.square(np.diff(x))+np.square(np.diff(y))),axis=1)  # d = (dx^2 + dy^2)^(1/2)"
    ]
   },
   {
@@ -293,7 +299,7 @@
    "source": [
     "plt.figure()\n",
     "ax = plt.axes()\n",
-    "ax.set_ylabel('Distance travelled')\n",
+    "ax.set_ylabel('Distance travelled [m]')\n",
     "ax.set_xlabel('observation',weight='bold')\n",
     "d_plot = ax.plot(distance.transpose())\n",
     "plt.show()"
@@ -332,8 +338,8 @@
     "\n",
     "plt.figure()\n",
     "ax = plt.axes()\n",
-    "ax.set_ylabel('Distance travelled')\n",
-    "ax.set_xlabel('time [hours]',weight='bold')\n",
+    "ax.set_ylabel('Distance travelled [m]')\n",
+    "ax.set_xlabel('time since release [hours]',weight='bold')\n",
     "d_plot = ax.plot(t[1:],distance.transpose())\n",
     "plt.show()"
    ]
@@ -356,12 +362,14 @@
     "mean_lon_x = []\n",
     "mean_lat_x = []\n",
     "\n",
-    "timerange = np.arange(np.nanmin(data_xarray['time'].values), np.nanmax(data_xarray['time'].values)+np.timedelta64(delta(hours=2)), delta(hours=2)) # timerange in nanoseconds\n",
+    "timerange = np.arange(np.nanmin(data_xarray['time'].values), \n",
+    "                      np.nanmax(data_xarray['time'].values)+np.timedelta64(delta(hours=2)), \n",
+    "                      delta(hours=2))  # timerange in nanoseconds\n",
     "\n",
     "for time in timerange:\n",
-    "    if np.all(np.any(data_xarray['time']==time,axis=1)): # if all trajectories share an observation at time\n",
-    "        mean_lon_x += [np.nanmean(data_xarray['lon'].where(data_xarray['time']==time).values)]   # find the data that share the time\n",
-    "        mean_lat_x += [np.nanmean(data_xarray['lat'].where(data_xarray['time']==time).values)]    # find the data that share the time"
+    "    if np.all(np.any(data_xarray['time']==time,axis=1)):  # if all trajectories share an observation at time\n",
+    "        mean_lon_x += [np.nanmean(data_xarray['lon'].where(data_xarray['time']==time).values)]  # find the data that share the time\n",
+    "        mean_lat_x += [np.nanmean(data_xarray['lat'].where(data_xarray['time']==time).values)]  # find the data that share the time"
    ]
   },
   {
@@ -381,12 +389,14 @@
     "mean_lon_n = []\n",
     "mean_lat_n = []\n",
     "\n",
-    "timerange = np.arange(np.nanmin(time_netcdf4), np.nanmax(time_netcdf4)+delta(hours=2).total_seconds(), delta(hours=2).total_seconds()) \n",
+    "timerange = np.arange(np.nanmin(time_netcdf4), \n",
+    "                      np.nanmax(time_netcdf4)+delta(hours=2).total_seconds(), \n",
+    "                      delta(hours=2).total_seconds()) \n",
     "\n",
     "for time in timerange:\n",
-    "    if np.all(np.any(time_netcdf4 == time, axis=1)): # if all trajectories share an observation at time\n",
-    "        mean_lon_n += [np.mean(lon_netcdf4[time_netcdf4 == time])]   # find the data that share the time\n",
-    "        mean_lat_n += [np.mean(lat_netcdf4[time_netcdf4 == time])]    # find the data that share the time"
+    "    if np.all(np.any(time_netcdf4 == time, axis=1)):  # if all trajectories share an observation at time\n",
+    "        mean_lon_n += [np.mean(lon_netcdf4[time_netcdf4 == time])]  # find the data that share the time\n",
+    "        mean_lat_n += [np.mean(lat_netcdf4[time_netcdf4 == time])]  # find the data that share the time"
    ]
   },
   {
@@ -424,9 +434,9 @@
    "metadata": {},
    "source": [
     "## Plotting\n",
-    "Parcels output consists of particle trajectories through time and space. An important way to explore patterns in this information is to draw the trajectories in space. Parcels provides the [`ParticleSet.show()`](https://oceanparcels.org/gh-pages/html/#parcels.particleset.ParticleSet.show) method to quickly look at results, but users are encouraged to create their own figures, for example by using the comprehensive [**matplotlib**](https://matplotlib.org/) library. Here we show a basic setup on how to process the parcels output into trajectory plots and animations.\n",
+    "Parcels output consists of particle trajectories through time and space. An important way to explore patterns in this information is to draw the trajectories in space. Parcels provides the [`ParticleSet.show()`](https://oceanparcels.org/gh-pages/html/#parcels.particleset.ParticleSet.show) method and the [`plotTrajectoryFile`](https://oceanparcels.org/gh-pages/html/#module-scripts.plottrajectoriesfile) script to quickly plot at results, but users are encouraged to create their own figures, for example by using the comprehensive [**matplotlib**](https://matplotlib.org/) library. Here we show a basic setup on how to process the parcels output into trajectory plots and animations.\n",
     "\n",
-    "Here are some other packages to help you make beautiful figures:\n",
+    "Some other packages to help you make beautiful figures are:\n",
     "* [**cartopy**](https://scitools.org.uk/cartopy/docs/latest/), a map-drawing tool especially compatible with matplotlib\n",
     "* [**cmocean**](https://matplotlib.org/cmocean/), a set of beautiful colormaps"
    ]
@@ -486,9 +496,9 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "Plotting trajectories only shows information about how particles move in space. To discover some patterns, you want to be able to see how the particles move in both time and space. To do this matplotlib offers an [animation package](https://matplotlib.org/3.3.2/api/animation_api.html). Here we show how to use the [`FuncAnimation`](https://matplotlib.org/3.3.2/api/_as_gen/matplotlib.animation.FuncAnimation.html#matplotlib.animation.FuncAnimation) class to animate parcels trajectory data.\n",
+    "Trajectory plots like the ones above can become very cluttered for large sets of particles. To better see patterns, it's a good idea to create an animation in time and space. To do this, matplotlib offers an [animation package](https://matplotlib.org/3.3.2/api/animation_api.html). Here we show how to use the [`FuncAnimation`](https://matplotlib.org/3.3.2/api/_as_gen/matplotlib.animation.FuncAnimation.html#matplotlib.animation.FuncAnimation) class to animate parcels trajectory data.\n",
     "\n",
-    "To correctly reveal the patterns in time we must remember that [the `obs` dimension does not necessarily correspond to the `time` variable](#Trajectory-data-structure). In the animation of the particles we usually want to draw the points at each consecutive moment in time, not necessarily at each moment since the start of the trajectory. To do this we must [select the correct data](#Conditional-selection) in each rendering."
+    "To correctly reveal the patterns in time we must remember that [the `obs` dimension does not necessarily correspond to the `time` variable](#Trajectory-data-structure). In the animation of the particles, we usually want to draw the points at each consecutive moment in time, not necessarily at each moment since the start of the trajectory. To do this we must [select the correct data](#Conditional-selection) in each rendering."
    ]
   },
   {
@@ -501,7 +511,9 @@
     "from IPython.display import HTML\n",
     "\n",
     "outputdt = delta(hours=2)\n",
-    "timerange = np.arange(np.nanmin(data_xarray['time'].values), np.nanmax(data_xarray['time'].values)+np.timedelta64(outputdt), outputdt) # timerange in nanoseconds"
+    "timerange = np.arange(np.nanmin(data_xarray['time'].values),\n",
+    "                      np.nanmax(data_xarray['time'].values)+np.timedelta64(outputdt), \n",
+    "                      outputdt)  # timerange in nanoseconds"
    ]
   },
   {