fix backwards figure and hard wrapping recommendation

Author: reint-fischer

docs/development/docsguide.md

@@ -2,8 +2,8 @@
 
 ## Vision
 
-We believe a clear documentation is important to community building, reproducibility, and transparency in our open-source 
-project. To make it easier to write our documentation in a consistent way, here we outline a brief vision for our 
+We believe a clear documentation is important to community building, reproducibility, and transparency in our open-source
+project. To make it easier to write our documentation in a consistent way, here we outline a brief vision for our
 documentation based heavily on a few common resources.
 
 ```{note}
@@ -19,7 +19,7 @@ TODO: outline functions of the documentation based on resources
 
 ## Notebook execution
 
-We run the notebooks in our documentation using [MyST-NB](https://myst-nb.readthedocs.io/en/latest/index.html). Here is 
+We run the notebooks in our documentation using [MyST-NB](https://myst-nb.readthedocs.io/en/latest/index.html). Here is
 a table showing the latest notebook execution:
 
 ```{nb-exec-table}
@@ -28,17 +28,17 @@ a table showing the latest notebook execution:
 
 ## Style guide
 
-- **Write out `parcels.class.method` in tutorials and how-to guides** so that we can see which classes and methods are 
-part of Parcels. Because in the alternative (using `from parcels import class`) the use of `class` in a cell further 
-along is not obviously part of `parcels`.
-- [**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid): 
-tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, which is fine because 
-we want readers to see the changes to a specific class or method in the context of the simulation, e.g. `Particle` and 
-`Kernel` are often customised together, which must be defined before the `ParticleSet.execute()`. We try to limit each 
-page in the documentation to a small number of examples.
+- **Write out `parcels.class.method` in tutorials and how-to guides** so that we can see which classes and methods are
+  part of Parcels. Because in the alternative (using `from parcels import class`) the use of `class` in a cell further
+  along is not obviously part of `parcels`.
+- [**Avoid too much Repitition In Documentation**](https://www.writethedocs.org/guide/writing/docs-principles/#arid):
+  tutorials and how-to guides notebooks will often have repetition of the general **Parcels** steps, which is fine because
+  we want readers to see the changes to a specific class or method in the context of the simulation, e.g. `Particle` and
+  `Kernel` are often customised together, which must be defined before the `ParticleSet.execute()`. We try to limit each
+  page in the documentation to a small number of examples.
 - **Import packages at the top of the section in which they are first used** to show what they are used for.
-- **Write documentation in first person plural ("we").** In our open source code, tutorials and guides can be written 
-by any developer or user, so the documentation teaches all of us how to do something with Parcels. Sometimes it can be 
-more natural to take on the tone of a teacher, writing to a student/learner, in which case it is okay to use "you". 
-Please refrain from using impersonal subjects such as "the user".
+- **Write documentation in first person plural ("we").** In our open source code, tutorials and guides can be written
+  by any developer or user, so the documentation teaches all of us how to do something with Parcels. Sometimes it can be
+  more natural to take on the tone of a teacher, writing to a student/learner, in which case it is okay to use "you".
+  Please refrain from using impersonal subjects such as "the user".
 - We recommend hard wrapping prose in markdown so that reading it becomes easier in any editor.

docs/getting_started/tutorial_quickstart.md

@@ -6,14 +6,14 @@ kernelspec:
 
 # Quickstart tutorial
 
-Welcome to the **Parcels** quickstart tutorial, in which we will go through all the necessary steps to run a simulation. 
-The code in this notebook can be used as a starting point to run Parcels in your own environment. Along the way we will 
-familiarize ourselves with some specific classes and methods. If you are ever confused about one of these and want to 
+Welcome to the **Parcels** quickstart tutorial, in which we will go through all the necessary steps to run a simulation.
+The code in this notebook can be used as a starting point to run Parcels in your own environment. Along the way we will
+familiarize ourselves with some specific classes and methods. If you are ever confused about one of these and want to
 read more, we have a [concepts overview](concepts_overview.md) discussing them in more detail. Let's dive in!
 
 ## Imports
 
-Parcels depends on `xarray`, expecting inputs in the form of [`xarray.Dataset`](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html) 
+Parcels depends on `xarray`, expecting inputs in the form of [`xarray.Dataset`](https://docs.xarray.dev/en/stable/generated/xarray.Dataset.html)
 and writing output files that can be read with xarray.
 
 ```{code-cell}
@@ -24,8 +24,8 @@ import parcels
 
 ## Input flow fields: `FieldSet`
 
-A Parcels simulation of Lagrangian trajectories of virtual particles requires two inputs; the first is a set of 
-hydrodynamics fields in which the particles are tracked. Here we provide an example using a subset of the 
+A Parcels simulation of Lagrangian trajectories of virtual particles requires two inputs; the first is a set of
+hydrodynamics fields in which the particles are tracked. Here we provide an example using a subset of the
 [Global Ocean Physics Reanalysis](https://doi.org/10.48670/moi-00021) from the Copernicus Marine Service.
 
 ```{code-cell}
@@ -38,11 +38,11 @@ ds_fields.load()  # load the dataset into memory
 ds_fields
 ```
 
-As we can see, the reanalysis dataset contains eastward velocity `uo`, northward velocity `vo`, potential temperature 
+As we can see, the reanalysis dataset contains eastward velocity `uo`, northward velocity `vo`, potential temperature
 (`thetao`) and salinity (`so`) fields.
 
-These hydrodynamic fields need to be stored in a `parcels.FieldSet` object. Parcels provides tooling to parse many types 
-of models or observations into such a `parcels.FieldSet` object. Here, we use `FieldSet.from_copernicusmarine()`, which 
+These hydrodynamic fields need to be stored in a `parcels.FieldSet` object. Parcels provides tooling to parse many types
+of models or observations into such a `parcels.FieldSet` object. Here, we use `FieldSet.from_copernicusmarine()`, which
 recognizes the standard names of a velocity field:
 
 ```{code-cell}
@@ -58,12 +58,12 @@ velocity = ds_fields.isel(time=0, depth=0).plot.quiver(x="longitude", y="latitud
 
 ## Input virtual particles: `ParticleSet`
 
-Now that we have created a `parcels.FieldSet` object from the hydrodynamic data, we need to provide our second input: 
+Now that we have created a `parcels.FieldSet` object from the hydrodynamic data, we need to provide our second input:
 the virtual particles for which we will calculate the trajectories.
 
-We need to create a `parcels.ParticleSet` object with the particles' initial time and position. The `parcels.ParticleSet` 
-object also needs to know about the `FieldSet` in which the particles "live". Finally, we need to specify the type of 
-`parcels.Particle` we want to use. The default particles have `time`, `z`, `lat`, and `lon`, but you can easily add 
+We need to create a `parcels.ParticleSet` object with the particles' initial time and position. The `parcels.ParticleSet`
+object also needs to know about the `FieldSet` in which the particles "live". Finally, we need to specify the type of
+`parcels.Particle` we want to use. The default particles have `time`, `z`, `lat`, and `lon`, but you can easily add
 other `Variables` such as size, temperature, or age to create your own particles to mimic plastic or an [ARGO float](../user_guide/examples/tutorial_Argofloats.ipynb).
 
 ```{code-cell}
@@ -89,9 +89,9 @@ ax.scatter(lon,lat,s=40,c='w',edgecolors='r');
 
 ## Compute: `Kernel`
 
-After setting up the input data and particle start locations and times, we need to specify what calculations to do with 
-the particles. These calculations, or numerical integrations, will be performed by what we call a `Kernel`, operating on 
-all particles in the `ParticleSet`. The most common calculation is the advection of particles through the velocity field. 
+After setting up the input data and particle start locations and times, we need to specify what calculations to do with
+the particles. These calculations, or numerical integrations, will be performed by what we call a `Kernel`, operating on
+all particles in the `ParticleSet`. The most common calculation is the advection of particles through the velocity field.
 Parcels comes with a number of standard kernels, from which we will use the Runge-Kutta advection kernel `AdvectionRK2`:
 
 ```{note}
@@ -104,26 +104,26 @@ kernels = [parcels.kernels.AdvectionEE]
 
 ## Prepare output: `ParticleFile`
 
-Before starting the simulation, we must define where and how frequent we want to write the output of our simulation. 
+Before starting the simulation, we must define where and how frequent we want to write the output of our simulation.
 We can define this in a `ParticleFile` object:
 
 ```{code-cell}
 output_file = parcels.ParticleFile("output-quickstart.zarr", outputdt=np.timedelta64(1, "h"))
 ```
 
-The output files are in `.zarr` [format](https://zarr.readthedocs.io/en/stable/), which can be read by `xarray`. 
-See the [Parcels output tutorial](./tutorial_output.ipynb) for more information on the zarr format. We want to choose 
+The output files are in `.zarr` [format](https://zarr.readthedocs.io/en/stable/), which can be read by `xarray`.
+See the [Parcels output tutorial](./tutorial_output.ipynb) for more information on the zarr format. We want to choose
 the `outputdt` argument so that it captures the smallest timescales of our interest.
 
 ## Run Simulation: `ParticleSet.execute()`
 
-Finally, we can run the simulation by _executing_ the `ParticleSet` using the specified list of `kernels`. 
+Finally, we can run the simulation by _executing_ the `ParticleSet` using the specified list of `kernels`.
 Additionally, we need to specify:
 
 - the `runtime`: for how long we want to simulate particles.
-- the `dt`: the timestep with which to perform the numerical integration in the `kernels`. Depending on the numerical 
-integration scheme, the accuracy of our simulation will depend on `dt`. Read [this notebook](https://github.com/Parcels-code/10year-anniversary-session2/blob/8931ef69577dbf00273a5ab4b7cf522667e146c5/advection_and_windage.ipynb) 
-to learn more about numerical accuracy.
+- the `dt`: the timestep with which to perform the numerical integration in the `kernels`. Depending on the numerical
+  integration scheme, the accuracy of our simulation will depend on `dt`. Read [this notebook](https://github.com/Parcels-code/10year-anniversary-session2/blob/8931ef69577dbf00273a5ab4b7cf522667e146c5/advection_and_windage.ipynb)
+  to learn more about numerical accuracy.
 
 ```{note}
 TODO: add Michaels 10-years Parcels notebook to the user guide
@@ -148,8 +148,8 @@ ds_particles = xr.open_zarr("output-quickstart.zarr")
 ds_particles
 ```
 
-The 10 particle trajectories are stored along the `trajectory` dimension, and each trajectory contains 25 observations 
-(initial values + 24 hourly timesteps) along the `obs` dimension. The [working with Parcels output tutorial](./tutorial_output.ipynb) 
+The 10 particle trajectories are stored along the `trajectory` dimension, and each trajectory contains 25 observations
+(initial values + 24 hourly timesteps) along the `obs` dimension. The [working with Parcels output tutorial](./tutorial_output.ipynb)
 provides more detail about the dataset and how to analyse it.
 
 Let's verify that Parcels has computed the advection of the virtual particles!
@@ -159,6 +159,7 @@ import matplotlib.pyplot as plt
 
 # plot positions and color particles by number of observation
 scatter = plt.scatter(ds_particles.lon.T, ds_particles.lat.T, c=np.repeat(ds_particles.obs.values,npart))
+plt.scatter(ds_particles.lon[:,0],ds_particles.lat[:,0],facecolors="none",edgecolors='r') # starting positions
 plt.scatter(lon,lat,facecolors="none",edgecolors='r') # starting positions
 plt.xlim(31,33)
 plt.ylabel("Latitude [deg N]")
@@ -167,17 +168,17 @@ plt.colorbar(scatter, label="Observation number")
 plt.show()
 ```
 
-That looks good! The virtual particles released in a line along the 32nd meridian (dark blue) have been advected by the 
+That looks good! The virtual particles released in a line along the 32nd meridian (dark blue) have been advected by the
 flow field.
 
 ## Running a simulation backwards in time
 
-Now that we know how to run a simulation, we can easily run another and change one of the settings. We can trace back 
-the particles from their current to their original position by running the simulation backwards in time. To do so, we 
+Now that we know how to run a simulation, we can easily run another and change one of the settings. We can trace back
+the particles from their current to their original position by running the simulation backwards in time. To do so, we
 can simply make `dt` < 0.
 
 ```{note}
-We have not edited the `ParticleSet`, which means that the new simulation will start with the particles at their current 
+We have not edited the `ParticleSet`, which means that the new simulation will start with the particles at their current
 location!
 ```
 
@@ -201,7 +202,7 @@ When we check the output, we can see that the particles have returned to their o
 ds_particles_back = xr.open_zarr("output-backwards.zarr")
 
 scatter = plt.scatter(ds_particles_back.lon.T, ds_particles_back.lat.T, c=np.repeat(ds_particles_back.obs.values,npart))
-plt.scatter(lon,lat,facecolors="none",edgecolors='r') # starting positions
+plt.scatter(ds_particles_back.lon[:,0],ds_particles_back.lat[:,0],facecolors="none",edgecolors='r') # starting positions
 plt.xlabel("Longitude [deg E]")
 plt.xlim(31,33)
 plt.ylabel("Latitude [deg N]")