Merge pull request #33 from OceanParcels/update_documentation

Improving the readthedocs documentation

Author: michaeldenes

docs/examples/README.md

@@ -0,0 +1,3 @@
+# Examples
+
+Up-to-date documentation on the `plasticparcels` examples can be found [here](https://plastic.oceanparcels.org/en/latest/examples.html).

docs/examples/example_Croatian_fisheries.ipynb

@@ -62,10 +62,10 @@
    "source": [
     "# Create the simulation settings\n",
     "settings['simulation'] = {\n",
-    "    'start_date': datetime.strptime('2019-01-01-00:00:00', '%Y-%m-%d-%H:%M:%S'), # Start date of simulation\n",
+    "    'startdate': datetime.strptime('2019-01-01-00:00:00', '%Y-%m-%d-%H:%M:%S'), # Start date of simulation\n",
     "    'runtime': timedelta(days=30),              # Runtime of simulation\n",
-    "    'dt_write': timedelta(hours=12),            # Timestep of output\n",
-    "    'dt_timestep': timedelta(minutes=20),       # Timestep of advection\n",
+    "    'outputdt': timedelta(hours=12),            # Timestep of output\n",
+    "    'dt': timedelta(minutes=20),                # Timestep of advection\n",
     "    }\n",
     "\n",
     "# Overwrite some settings\n",
@@ -155,8 +155,8 @@
    "outputs": [],
    "source": [
     "runtime = settings['simulation']['runtime']\n",
-    "dt_timestep = settings['simulation']['dt_timestep']\n",
-    "dt_write = settings['simulation']['dt_write']"
+    "dt = settings['simulation']['dt']\n",
+    "outputdt = settings['simulation']['outputdt']"
    ]
   },
   {
@@ -174,7 +174,7 @@
    "outputs": [],
    "source": [
     "# Create the particle file where output will be stored\n",
-    "pfile = pp.ParticleFile('example_Croatia_fisheries.zarr', pset, settings=settings, outputdt=dt_write)"
+    "pfile = pp.ParticleFile('example_Croatia_fisheries.zarr', pset, settings=settings, outputdt=outputdt)"
    ]
   },
   {
@@ -187,13 +187,13 @@
      "output_type": "stream",
      "text": [
       "INFO: Output files are stored in example_Croatia_fisheries.zarr.\n",
-      "100%|██████████| 2592000.0/2592000.0 [07:16<00:00, 5938.88it/s] \n"
+      "100%|██████████| 2592000.0/2592000.0 [07:49<00:00, 5524.98it/s]\n"
      ]
     }
    ],
    "source": [
     "# Execute the simulation\n",
-    "pset.execute(kernels, runtime=runtime, dt=dt_timestep, output_file=pfile)"
+    "pset.execute(kernels, runtime=runtime, dt=dt, output_file=pfile)"
    ]
   },
   {
@@ -284,9 +284,9 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "settings['bgc']['constants']['biofilm_density'] = 1400.0 # Biofilm density (kg/m^3)\n",
-    "settings['bgc']['constants']['collision_probability'] = 0.75          # Probability of collision with ambient algae\n",
-    "settings['bgc']['constants']['algae_mortality_rate'] = 0.80           # Mortality rate of biofilm"
+    "settings['bgc']['constants']['biofilm_density'] = 1400.0        # Biofilm density (kg/m^3)\n",
+    "settings['bgc']['constants']['collision_probability'] = 0.75    # Probability of collision with ambient algae\n",
+    "settings['bgc']['constants']['algae_mortality_rate'] = 0.80     # Mortality rate of biofilm"
    ]
   },
   {
@@ -326,7 +326,7 @@
    "outputs": [],
    "source": [
     "# Create the particle file where output will be stored\n",
-    "pfile = pp.ParticleFile('example_Croatia_fisheries_sensitivity.zarr', pset, settings=settings, outputdt=dt_write)"
+    "pfile = pp.ParticleFile('example_Croatia_fisheries_sensitivity.zarr', pset, settings=settings, outputdt=outputdt)"
    ]
   },
   {
@@ -339,13 +339,13 @@
      "output_type": "stream",
      "text": [
       "INFO: Output files are stored in example_Croatia_fisheries_sensitivity.zarr.\n",
-      "100%|██████████| 2592000.0/2592000.0 [12:43<00:00, 3394.83it/s] \n"
+      "100%|██████████| 2592000.0/2592000.0 [19:57<00:00, 2163.97it/s] \n"
      ]
     }
    ],
    "source": [
     "# Execute the simulation\n",
-    "pset.execute(kernels, runtime=runtime, dt=dt_timestep, output_file=pfile)"
+    "pset.execute(kernels, runtime=runtime, dt=dt, output_file=pfile)"
    ]
   },
   {

docs/examples/example_Greece_coast.ipynb

@@ -62,10 +62,10 @@
    "source": [
     "# Create the simulation settings\n",
     "settings['simulation'] = {\n",
-    "    'start_date': datetime.strptime('2019-06-01-00:00:00', '%Y-%m-%d-%H:%M:%S'), # Start date of simulation\n",
-    "    'runtime': timedelta(days=30),              # Runtime of simulation\n",
-    "    'dt_write': timedelta(hours=12),            # Timestep of output\n",
-    "    'dt_timestep': timedelta(minutes=20),       # Timestep of advection\n",
+    "    'startdate': datetime.strptime('2019-06-01-00:00:00', '%Y-%m-%d-%H:%M:%S'), # Start date of simulation\n",
+    "    'runtime': timedelta(days=30),          # Runtime of simulation\n",
+    "    'outputdt': timedelta(hours=12),        # Timestep of output\n",
+    "    'dt': timedelta(minutes=20),            # Timestep of advection\n",
     "    }\n",
     "\n",
     "# Overwrite some settings\n",
@@ -164,8 +164,8 @@
    "outputs": [],
    "source": [
     "runtime = settings['simulation']['runtime']\n",
-    "dt_timestep = settings['simulation']['dt_timestep']\n",
-    "dt_write = settings['simulation']['dt_write']"
+    "dt = settings['simulation']['dt']\n",
+    "outputdt = settings['simulation']['outputdt']"
    ]
   },
   {
@@ -183,7 +183,7 @@
    "outputs": [],
    "source": [
     "# Create the particle file where output will be stored\n",
-    "pfile = pp.ParticleFile('example_Greece_coast.zarr', pset, settings=settings, outputdt=dt_write)"
+    "pfile = pp.ParticleFile('example_Greece_coast.zarr', pset, settings=settings, outputdt=outputdt)"
    ]
   },
   {
@@ -196,13 +196,13 @@
      "output_type": "stream",
      "text": [
       "INFO: Output files are stored in example_Greece_coast.zarr.\n",
-      "100%|██████████| 2592000.0/2592000.0 [00:53<00:00, 48730.82it/s]\n"
+      "100%|██████████| 2592000.0/2592000.0 [00:59<00:00, 43331.55it/s]\n"
      ]
     }
    ],
    "source": [
     "# Execute the simulation\n",
-    "pset.execute(kernels, runtime=runtime, dt=dt_timestep, output_file=pfile)"
+    "pset.execute(kernels, runtime=runtime, dt=dt, output_file=pfile)"
    ]
   },
   {

docs/examples/example_Italy_coast.ipynb

@@ -57,10 +57,10 @@
    "source": [
     "# Create the simulation settings\n",
     "settings['simulation'] = {\n",
-    "    'start_date': datetime.strptime('2019-01-01-00:00:00', '%Y-%m-%d-%H:%M:%S'), # Start date of simulation\n",
-    "    'runtime': timedelta(days=30),             # Runtime of simulation, use negative if releasing particles backwards in time\n",
-    "    'dt_write': timedelta(hours=12),             # Timestep of output\n",
-    "    'dt_timestep': timedelta(minutes=20),       # Timestep of advection\n",
+    "    'startdate': datetime.strptime('2019-01-01-00:00:00', '%Y-%m-%d-%H:%M:%S'), # Start date of simulation\n",
+    "    'runtime': timedelta(days=30),             # Runtime of simulation\n",
+    "    'outputdt': timedelta(hours=12),           # Timestep of output\n",
+    "    'dt': timedelta(minutes=20),               # Timestep of advection\n",
     "    }\n",
     "\n",
     "# Subset the ocean data to just include the Mediterranean Sea\n",
@@ -210,15 +210,15 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "<function PolyTEOS10_bsq at 0x7f38b955f910>\n",
-      "<function AdvectionRK4_3D at 0x7f38ba1b2d40>\n",
-      "<function Biofouling at 0x7f38b955f880>\n",
-      "<function StokesDrift at 0x7f38b955f6d0>\n",
-      "<function unbeaching at 0x7f38b955fa30>\n",
-      "<function checkThroughBathymetry at 0x7f38b955fac0>\n",
-      "<function checkErrorThroughSurface at 0x7f38b955fbe0>\n",
-      "<function periodicBC at 0x7f38b955fb50>\n",
-      "<function deleteParticle at 0x7f38b955fc70>\n"
+      "<function PolyTEOS10_bsq at 0x7f19fefcb910>\n",
+      "<function AdvectionRK4_3D at 0x7f19ffd2ad40>\n",
+      "<function Biofouling at 0x7f19fefcb880>\n",
+      "<function StokesDrift at 0x7f19fefcb6d0>\n",
+      "<function unbeaching at 0x7f19fefcba30>\n",
+      "<function checkThroughBathymetry at 0x7f19fefcbac0>\n",
+      "<function checkErrorThroughSurface at 0x7f19fefcbbe0>\n",
+      "<function periodicBC at 0x7f19fefcbb50>\n",
+      "<function deleteParticle at 0x7f19fefcbc70>\n"
      ]
     }
    ],
@@ -245,21 +245,21 @@
      "output_type": "stream",
      "text": [
       "INFO: Output files are stored in example_Tunisia_fisheries_prebuilt.zarr.\n",
-      "100%|██████████| 2592000.0/2592000.0 [14:30<00:00, 2977.08it/s]\n"
+      "100%|██████████| 2592000.0/2592000.0 [07:48<00:00, 5529.73it/s]\n"
      ]
     }
    ],
    "source": [
     "# Define the runtime, the timestepping, and the output frequency of the simulation from the settings\n",
     "runtime = settings['simulation']['runtime']\n",
-    "dt_timestep = settings['simulation']['dt_timestep']\n",
-    "dt_write = settings['simulation']['dt_write']\n",
+    "dt = settings['simulation']['dt']\n",
+    "outputdt = settings['simulation']['outputdt']\n",
     "\n",
     "# Create the particle file where output will be stored\n",
-    "pfile = pp.ParticleFile('example_Tunisia_fisheries_prebuilt.zarr', pset, settings=settings, outputdt=dt_write)\n",
+    "pfile = pp.ParticleFile('example_Tunisia_fisheries_prebuilt.zarr', pset, settings=settings, outputdt=outputdt)\n",
     "\n",
     "# Execute the simulation\n",
-    "pset.execute(kernels, runtime=runtime, dt=dt_timestep, output_file=pfile)"
+    "pset.execute(kernels, runtime=runtime, dt=dt, output_file=pfile)"
    ]
   },
   {
@@ -359,15 +359,15 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "<function PolyTEOS10_bsq at 0x7f38b955f910>\n",
-      "<function AdvectionRK4_3D at 0x7f38ba1b2d40>\n",
-      "<function Biofouling at 0x7f38b955f880>\n",
-      "<function StokesDrift at 0x7f38b955f6d0>\n",
-      "<function unbeaching at 0x7f38b955fa30>\n",
-      "<function checkThroughBathymetry at 0x7f38b955fac0>\n",
-      "<function checkErrorThroughSurface at 0x7f38b955fbe0>\n",
-      "<function periodicBC at 0x7f38b955fb50>\n",
-      "<function deleteParticle at 0x7f38b955fc70>\n"
+      "<function PolyTEOS10_bsq at 0x7f19fefcb910>\n",
+      "<function AdvectionRK4_3D at 0x7f19ffd2ad40>\n",
+      "<function Biofouling at 0x7f19fefcb880>\n",
+      "<function StokesDrift at 0x7f19fefcb6d0>\n",
+      "<function unbeaching at 0x7f19fefcba30>\n",
+      "<function checkThroughBathymetry at 0x7f19fefcbac0>\n",
+      "<function checkErrorThroughSurface at 0x7f19fefcbbe0>\n",
+      "<function periodicBC at 0x7f19fefcbb50>\n",
+      "<function deleteParticle at 0x7f19fefcbc70>\n"
      ]
     }
    ],
@@ -392,17 +392,17 @@
      "name": "stdout",
      "output_type": "stream",
      "text": [
-      "<function PolyTEOS10_bsq at 0x7f38b955f910>\n",
-      "<function AdvectionRK4_3D at 0x7f38ba1b2d40>\n",
-      "<function Biofouling at 0x7f38b955f880>\n",
-      "<function StokesDrift at 0x7f38b955f6d0>\n",
-      "<function NorthwardDrift at 0x7f38889ba440>\n",
-      "<function EastwardDrift at 0x7f38889ba290>\n",
-      "<function unbeaching at 0x7f38b955fa30>\n",
-      "<function checkThroughBathymetry at 0x7f38b955fac0>\n",
-      "<function checkErrorThroughSurface at 0x7f38b955fbe0>\n",
-      "<function periodicBC at 0x7f38b955fb50>\n",
-      "<function deleteParticle at 0x7f38b955fc70>\n"
+      "<function PolyTEOS10_bsq at 0x7f19fefcb910>\n",
+      "<function AdvectionRK4_3D at 0x7f19ffd2ad40>\n",
+      "<function Biofouling at 0x7f19fefcb880>\n",
+      "<function StokesDrift at 0x7f19fefcb6d0>\n",
+      "<function NorthwardDrift at 0x7f19d409a4d0>\n",
+      "<function EastwardDrift at 0x7f19d409a440>\n",
+      "<function unbeaching at 0x7f19fefcba30>\n",
+      "<function checkThroughBathymetry at 0x7f19fefcbac0>\n",
+      "<function checkErrorThroughSurface at 0x7f19fefcbbe0>\n",
+      "<function periodicBC at 0x7f19fefcbb50>\n",
+      "<function deleteParticle at 0x7f19fefcbc70>\n"
      ]
     }
    ],
@@ -432,16 +432,16 @@
      "output_type": "stream",
      "text": [
       "INFO: Output files are stored in example_Tunisia_fisheries_custom.zarr.\n",
-      "100%|██████████| 2592000.0/2592000.0 [15:12<00:00, 2839.68it/s]\n"
+      "100%|██████████| 2592000.0/2592000.0 [19:57<00:00, 2164.59it/s] \n"
      ]
     }
    ],
    "source": [
     "# Create the particle file where output will be stored\n",
-    "pfile = pp.ParticleFile('example_Tunisia_fisheries_custom.zarr', pset, settings=settings, outputdt=dt_write)\n",
+    "pfile = pp.ParticleFile('example_Tunisia_fisheries_custom.zarr', pset, settings=settings, outputdt=outputdt)\n",
     "\n",
     "# Execute the simulation\n",
-    "pset.execute(kernels, runtime=runtime, dt=dt_timestep, output_file=pfile)"
+    "pset.execute(kernels, runtime=runtime, dt=dt, output_file=pfile)"
    ]
   },
   {

docs/examples/example_add_your_own_kernel.ipynb

@@ -21,9 +21,25 @@ Installation
    conda install conda-forge::plasticparcels
 
 
-Or downloaded from https://github.com/OceanParcels/PlasticParcels
+Or downloaded from https://github.com/OceanParcels/plasticparcels
 
 
+Required Data
+^^^^^^^^^^^^^
+
+``plasticparcels`` has been developed for use with data from the Copernicus Marine Service, and requires the following data to run:
+
+* Hydrodynamic model data: `MOI GLO12 (psy4v3r1) <https://www.mercator-ocean.eu/en/solutions-expertise/accessing-digital-data/product-details/?offer=4217979b-2662-329a-907c-602fdc69c3a3&system=d35404e4-40d3-59d6-3608-581c9495d86a>`_
+* Biogeochemical model data: `MOI BIO4 (biomer4v2r1) <https://www.mercator-ocean.eu/en/solutions-expertise/accessing-digital-data/product-details/?offer=8d0c01f3-81c7-0a59-0d06-602fdf63c5b6&system=dc40b324-7de7-0732-880b-5d9dcf7d344a>`_
+* Wave data: `ECMWF ERA5 Wave <https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels>`_ (specifically, the variables ``mean_wave_period``, ``peak_wave_period``, ``u_component_stokes_drift``, and ``v_component_stokes_drift``.) 
+* Wind data: `ECMWF ERA5 Wind <https://cds.climate.copernicus.eu/cdsapp#!/dataset/reanalysis-era5-single-levels>`_ (specifically, the variables ``10m_u_component_of_wind`` and ``10m_v_component_of_wind``) 
+
+For the wind and wave data, we recommend using the `CDS API <https://cds.climate.copernicus.eu/api-how-to>`_.
+
+To run the examples, you will need to update the data directories in settings ``.json`` files.
+
+Just like the ``parcels`` framework, ``plasticparcels`` can be adapted to use other hydrodynamic, biogeochemical, wave, and atmospheric models. If you require assistance, please contact us through the [Discussions page on GitHub](https://github.com/OceanParcels/plasticparcels/discussions).
+
 .. toctree::
    :maxdepth: 2
    :caption: Contents

docs/examples/example_initialisation_maps.ipynb

@@ -1,5 +1,5 @@
 # Description of algorithms for particle initialisation maps
-Included in the `PlasticParcels` package are four particle initialisation maps, along with the algorithms to create them. These maps represent best estimates for plastic pollution emissions along coastlines [@Jambeck2015](http://dx.doi.org/10.1126/science.1260352), from river sources [@Meijer2021](http://dx.doi.org/10.1126/sciadv.aaz5803), in the open-ocean from fishing-related activities [@Kroodsma2018](http://dx.doi.org/10.1126/science.aao5646), as well as a current best estimate of buoyant plastic concentrations globally [@Kaandorp2023](http://dx.doi.org/10.1038/s41561-023-01216-0).
+Included in the `plasticparcels` package are four particle initialisation maps, along with the algorithms to create them. These maps represent best estimates for plastic pollution emissions along coastlines [@Jambeck2015](http://dx.doi.org/10.1126/science.1260352), from river sources [@Meijer2021](http://dx.doi.org/10.1126/sciadv.aaz5803), in the open-ocean from fishing-related activities [@Kroodsma2018](http://dx.doi.org/10.1126/science.aao5646), as well as a current best estimate of buoyant plastic concentrations globally [@Kaandorp2023](http://dx.doi.org/10.1038/s41561-023-01216-0).
 Each initialisation map, however, requires that particles be placed in ocean grid cells, so we also provide algorithms to generate these ocean masks too.
 
 The code for these algorithims can be found in `plasticparcels/scripts/create_release_maps.py`. Below we describe each of the algorithms.
@@ -20,7 +20,7 @@ To generate a particle initialisation map of plastic pollution that enters the o
     4. Create an array with the coastal model grid-cell and its associated area, the country name, continent name, region name, and subregion name from the shapefile, and the identified population density.
 5. Combine all entries generated in Step 4.4. into one array.
 6. Load the global mismanaged plastic waste data [@Jambeck2015](http://dx.doi.org/10.1126/science.1260352), and join it to the array generated in Step 5, by 'left joining' on country name$^*$. Create an additional column 'MPW_cell', which represents the mismanaged plastic waste across the grid cell, by multiplying the mismanaged plastic waste per kilogram per day with the population density and the grid-cell area.
-7. Save the data into a `.csv` file, to be read and processed by `PlasticParcels`.
+7. Save the data into a `.csv` file, to be read and processed by `plasticparcels`.
 
 
 $^*$We pre-process the country names in the [@Jambeck2015](http://dx.doi.org/10.1126/science.1260352) data to account for small differences in the naming conventions of each country. We use $`r=50`$ km, and $`\phi`$ is chosen as the model grid width in degrees. A sample plot of the initialisation map is shown in Figure X **add link**.
@@ -36,7 +36,7 @@ To generate a particle initialisation map of plastic pollution that enters the o
     1. Compute the distance from the emission source to the center of every coastal grid cell, and identify the closest coastal grid cell.
     2. Compute the distance from the emission source to every country border point, and identify the closest country border point.
     3. Create an array with the coastal model grid-cell, the country name, continent name, region name, and subregion name of the closest border point from the Natural Earth shapefile, and the associated emissions amount.
-5. Save the data into a `.csv` file, to be read and processed by `PlasticParcels`.
+5. Save the data into a `.csv` file, to be read and processed by `plasticparcels`.
 
 
 ## Open-sea fishing-related plastic emissions <a name="fishingrelease"></a>
@@ -51,7 +51,7 @@ To generate a particle initialisation map of plastic pollution emitted into the
 6. Load (or generate) the coast mask file from the selected ocean model.
 7. Find the closest ocean grid cell for each entry in the aggregated dataset from Step 5. using a KD-Tree approach.
 8. Aggregate the data by summing the fishing hours over the following columns: country name, continent name, flag, gear type, date (month and year), ocean grid cell.
-9. Save the data into a `.csv` file, to be read and processed by `PlasticParcels`.
+9. Save the data into a `.csv` file, to be read and processed by `plasticparcels`.
 
 $^*$We use the `fleet-daily-csvs-100-v2-2020` files, which are for the year 2020 only.
 
@@ -70,4 +70,4 @@ To generate a particle initialisation map of the current best-estimate of global
 8. Interpolate the `concentration_mass_log10` to the ocean-grid cells, using  an `RegularGridInterpolator` function from `scipy.interpolate`, with the grid and data being `(lon, lat)` and `concentration_mass_log10` from the `concentration_mass_log10` dataset.
 9. For all valid concentrations identified in Step 8., identify the closest country boundary vertex from the Natural Earth shapefile.
 10. Create an array with the ocean model cell, the interpolated plastic concentration amount (converting it into a mass insteaf of a `log10` mass), and the continent name, region name, subregion name, country name, and country flag from the Natural Earth shapefile.
-11. Combine the arrays generated in Steps 6. and 10., and save the data as a `.csv` file, to be read and processed `PlasticParcels`.
+11. Combine the arrays generated in Steps 6. and 10., and save the data as a `.csv` file, to be read and processed `plasticparcels`.