Merge branch 'main' into idealised_example

Author: michaeldenes

README.md

@@ -13,6 +13,21 @@ The tool is based on the [`Parcels`](https://oceanparcels.org/) computational La
 conda install conda-forge::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 downloading the wind and wave data, we recommend using the [CDS API](https://cds.climate.copernicus.eu/api-how-to).
+
+To run most of the examples, you will need to update the data directories in the relevant settings `.json` file.
+
+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 [`plasticparcels` discussions page](https://github.com/OceanParcels/plasticparcels/discussions).
+
 ### Community contributions and support
 #### Contributing code
 We welcome contributions to `plasticparcels`, especially example workbooks and analyses for our [public examples page](https://plastic.oceanparcels.org/en/latest/examples.html). To contribute to the project, please submit a [pull request](https://github.com/OceanParcels/plasticparcels/pulls).

docs/examples/example_Croatian_fisheries.ipynb

@@ -5,7 +5,12 @@
    "metadata": {},
    "source": [
     "# Sensitivity of biofouling parameters - Plastic pollution from Croatian fishing vessels\n",
-    "In this example, we will use `plasticparcels` to run a basic simulation of microplastic pollution emitted from Croatian registered fishing vessels. We will use the [Open-sea fishing-related plastic emissions dataset](https://plastic.oceanparcels.org/en/latest/initialisationmaps.html#open-sea-fishing-related-plastic-emissions) to release virtual particles in ocean model grid cells, using the 3D velocity fields to advect the particles. We also include the effects of biofouling and Stokes drift on the particles. We will run two simulations, one with the default biofouling parameters, and another where we vary some of the biofouling parameters."
+    "In this example, we will use `plasticparcels` to run a basic simulation of microplastic pollution emitted from Croatian registered fishing vessels. We will use the [Open-sea fishing-related plastic emissions dataset](https://plastic.oceanparcels.org/en/latest/initialisationmaps.html#open-sea-fishing-related-plastic-emissions) to release virtual particles in ocean model grid cells, using the 3D velocity fields to advect the particles. We also include the effects of biofouling and Stokes drift on the particles. We will run two simulations, one with the default biofouling parameters, and another where we vary some of the biofouling parameters.\n",
+    "<div class=\"alert alert-block alert-info\">\n",
+    "\n",
+    "<b>Note: </b> To run this example you will need to download the hydrodynamic, physical, and biogeochemical model data described [here](https://plastic.oceanparcels.org/en/latest/index.html#required-data).\n",
+    "\n",
+    "</div>"
    ]
   },
   {

docs/examples/example_Greece_coast.ipynb

@@ -5,7 +5,12 @@
    "metadata": {},
    "source": [
     "# The pathways and fate of existing plastic pollution along Greek coastlines\n",
-    "In this example, we will use `plasticparcels` to run a basic simulation of microplastic pollution along the Greek coastline. We will use the [Current global ocean plastic concentrations dataset](https://plastic.oceanparcels.org/en/latest/initialisationmaps.html) to release virtual particles in coastal model grid cells, using the 2D surface velocity fields to advect the particles. We also include the effects of Stokes drift and wind-induced drift on the particles, but neglect any vertical motion (along with any biofouling, or vertical mixing)."
+    "In this example, we will use `plasticparcels` to run a basic simulation of microplastic pollution along the Greek coastline. We will use the [Current global ocean plastic concentrations dataset](https://plastic.oceanparcels.org/en/latest/initialisationmaps.html) to release virtual particles in coastal model grid cells, using the 2D surface velocity fields to advect the particles. We also include the effects of Stokes drift and wind-induced drift on the particles, but neglect any vertical motion (along with any biofouling, or vertical mixing).\n",
+    "<div class=\"alert alert-block alert-info\">\n",
+    "\n",
+    "<b>Note: </b> To run this example you will need to download the hydrodynamic, physical, and biogeochemical model data described [here](https://plastic.oceanparcels.org/en/latest/index.html#required-data).\n",
+    "\n",
+    "</div>"
    ]
   },
   {

docs/examples/example_Italy_coast.ipynb

@@ -5,7 +5,12 @@
    "metadata": {},
    "source": [
     "# The pathways and fate of Italian coastal plastic pollution\n",
-    "In this example, we will use `plasticparcels` to run a basic simulation of microplastic pollution along the Italian coastline. We will use the [Coastal mismanaged plastic waste emissions dataset](https://plastic.oceanparcels.org/en/latest/initialisationmaps.html) to release virtual particles in coastal model grid cells, using the 2D surface velocity fields to advect the particles. We also include the effects of Stokes drift and wind-induced drift on the particles, but neglect any vertical motion (along with any biofouling, or vertical mixing)."
+    "In this example, we will use `plasticparcels` to run a basic simulation of microplastic pollution along the Italian coastline. We will use the [Coastal mismanaged plastic waste emissions dataset](https://plastic.oceanparcels.org/en/latest/initialisationmaps.html) to release virtual particles in coastal model grid cells, using the 2D surface velocity fields to advect the particles. We also include the effects of Stokes drift and wind-induced drift on the particles, but neglect any vertical motion (along with any biofouling, or vertical mixing).\n",
+    "<div class=\"alert alert-block alert-info\">\n",
+    "\n",
+    "<b>Note: </b> To run this example you will need to download the hydrodynamic, physical, and biogeochemical model data described [here](https://plastic.oceanparcels.org/en/latest/index.html#required-data).\n",
+    "\n",
+    "</div>"
    ]
   },
   {

docs/examples/example_add_your_own_kernel.ipynb

@@ -5,7 +5,12 @@
    "metadata": {},
    "source": [
     "# Add your own behaviour kernels\n",
-    "In this example, we will show how to turn on/off existing behaviour kernels, and how to create and include your own behaviour kernel to use in `plasticparcels` simulations. We will start by importing some necessary packages."
+    "In this example, we will show how to turn on/off existing behaviour kernels, and how to create and include your own behaviour kernel to use in `plasticparcels` simulations. We will start by importing some necessary packages.\n",
+    "<div class=\"alert alert-block alert-info\">\n",
+    "\n",
+    "<b>Note: </b> To run this example you will need to download the hydrodynamic, physical, and biogeochemical model data described [here](https://plastic.oceanparcels.org/en/latest/index.html#required-data).\n",
+    "\n",
+    "</div>"
    ]
   },
   {

docs/index.rst

@@ -34,9 +34,9 @@ Required Data
 * 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>`_.
+For downloading 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.
+To run the examples, you will need to update the data directories in the relevant settings ``.json`` file.
 
 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>`_.