Adding reanalysis data

docs/index.md

@@ -5,7 +5,7 @@
 :hidden:
 
 Home <self>
-user-guide/index
+User Guide & Documentation <user-guide/index>
 api/index
 contributing/index
 VirtualShip Website <https://virtualship.oceanparcels.org/>

docs/user-guide/documentation/copernicus_products.md

@@ -0,0 +1,77 @@
+# Copernicus Marine products
+
+VirtualShip supports running experiments anywhere in the global ocean from 1993 through to the present day (and approximately two weeks into the future), using the suite of products available from the [Copernicus Marine Data Store](https://data.marine.copernicus.eu/products).
+
+The data sourcing task is handled by the `virtualship fetch` command. The three products relied on by `fetch` to source data for all [VirtualShip instruments](https://virtualship.readthedocs.io/en/latest/user-guide/assignments/Research_proposal_intro.html#Measurement-Options) (both physical and biogeochemical) are:
+
+1. **Reanalysis** (or "hindcast" for biogeochemistry).
+2. **Renalysis interim** (or "hindcast interim" for biogeochemistry).
+3. **Analysis & Forecast**.
+
+```{tip}
+The Copernicus Marine Service describe the differences between the three products in greater detail [here](https://help.marine.copernicus.eu/en/articles/4872705-what-are-the-main-differences-between-nearrealtime-and-multiyear-products).
+```
+
+As a general rule of thumb the three different products span different periods across the historical period to present and are intended to allow for continuity across the previous ~ 30 years.
+
+```{note}
+The ethos for automated dataset selection in `virtualship fetch` is to prioritise the Reanalysis/Hindcast products where possible (the 'work horse'), then _interim products where possible for continuity, and finally filling the very near-present (and near-future) temporal range with the Analysis & Forecast products.
+```
+
+```{warning}
+In the rare situation where the start and end times of an expedition schedule span different products *and* there is no overlap in the respective dataset timeseries, which is possible in the case of the end time being in the **Reanalysis_interim** period and the start time in the **Reanalysis** period, the **Analysis & Forecast** product will be automatically selected, as this spans back enough in time for this niche case.
+```
+
+### Data availability
+
+The following tables summarise which Copernicus product is selected by `virtualship fetch` per combination of time period and variable (see legend below).
+
+For biogeochemical variables `ph` and `phyc`, monthly products are required for hindcast and hindcast interim periods. For all other variables, daily products are available.
+
+#### Physical products
+
+| Period              | Product ID                               | Temporal Resolution | Typical Years Covered               | Variables                  |
+| :------------------ | :--------------------------------------- | :------------------ | :---------------------------------- | :------------------------- |
+| Reanalysis          | `cmems_mod_glo_phy_my_0.083deg_P1D-m`    | Daily               | ~30 years ago to ~5 years ago       | `uo`, `vo`, `so`, `thetao` |
+| Reanalysis Interim  | `cmems_mod_glo_phy_myint_0.083deg_P1D-m` | Daily               | ~5 years ago to ~2 months ago       | `uo`, `vo`, `so`, `thetao` |
+| Analysis & Forecast | `cmems_mod_glo_phy_anfc_0.083deg_P1D-m`  | Daily               | ~2 months ago to ~2 weeks in future | `uo`, `vo`, `so`, `thetao` |
+
+---
+
+#### Biogeochemical products
+
+| Period                        | Product ID                                 | Temporal Resolution | Typical Years Covered               | Variables                         | Notes                                  |
+| :---------------------------- | :----------------------------------------- | :------------------ | :---------------------------------- | :-------------------------------- | :------------------------------------- |
+| Hindcast                      | `cmems_mod_glo_bgc_my_0.25deg_P1D-m`       | Daily               | ~30 years ago to ~5 years ago       | `o2`, `chl`, `no3`, `po4`, `nppv` | Most BGC variables except `ph`, `phyc` |
+| Hindcast (monthly)            | `cmems_mod_glo_bgc_my_0.25deg_P1M-m`       | Monthly             | ~30 years ago to ~5 years ago       | `ph`, `phyc`                      | Only `ph`, `phyc` (monthly only)       |
+| Hindcast Interim              | `cmems_mod_glo_bgc_myint_0.25deg_P1D-m`    | Daily               | ~5 years ago to ~2 months ago       | `o2`, `chl`, `no3`, `po4`, `nppv` | Most BGC variables except `ph`, `phyc` |
+| Hindcast Interim (monthly)    | `cmems_mod_glo_bgc_myint_0.25deg_P1M-m`    | Monthly             | ~5 years ago to ~2 months ago       | `ph`, `phyc`                      | Only `ph`, `phyc` (monthly only)       |
+| Analysis & Forecast (O2)      | `cmems_mod_glo_bgc-bio_anfc_0.25deg_P1D-m` | Daily               | ~2 months ago to ~2 weeks in future | `o2`                              |                                        |
+| Analysis & Forecast (Chl)     | `cmems_mod_glo_bgc-pft_anfc_0.25deg_P1D-m` | Daily               | ~2 months ago to ~2 weeks in future | `chl`, `phyc`                     |                                        |
+| Analysis & Forecast (NO3/PO4) | `cmems_mod_glo_bgc-nut_anfc_0.25deg_P1D-m` | Daily               | ~2 months ago to ~2 weeks in future | `no3`, `po4`                      |                                        |
+| Analysis & Forecast (PH)      | `cmems_mod_glo_bgc-car_anfc_0.25deg_P1D-m` | Daily               | ~2 months ago to ~2 weeks in future | `ph`                              |                                        |
+| Analysis & Forecast (NPPV)    | `cmems_mod_glo_bgc-bio_anfc_0.25deg_P1D-m` | Daily               | ~2 months ago to ~2 weeks in future | `nppv`                            |                                        |
+
+---
+
+```{note}
+* "Typical Years Covered" are approximate and subject to change with new Copernicus data releases.
+* For the most up-to-date information, always consult the Copernicus Marine product documentation.
+* Certain BGC variables (`ph`, `phyc`) are only available as monthly products in hindcast and hindcast interim periods.
+```
+
+##### CMEMS variables legend
+
+| Variable Code | Full Variable Name                                            | Category       |
+| :------------ | :------------------------------------------------------------ | :------------- |
+| **uo**        | Eastward Sea Water Velocity                                   | Physical       |
+| **vo**        | Northward Sea Water Velocity                                  | Physical       |
+| **so**        | Sea Water Salinity                                            | Physical       |
+| **thetao**    | Sea Water Potential Temperature                               | Physical       |
+| **o2**        | Mole Concentration of Dissolved Molecular Oxygen in Sea Water | Biogeochemical |
+| **chl**       | Mass Concentration of Chlorophyll a in Sea Water              | Biogeochemical |
+| **no3**       | Mole Concentration of Nitrate in Sea Water                    | Biogeochemical |
+| **po4**       | Mole Concentration of Phosphate in Sea Water                  | Biogeochemical |
+| **nppv**      | Net Primary Production of Biomass                             | Biogeochemical |
+| **ph**        | Sea Water pH                                                  | Biogeochemical |
+| **phyc**      | Mole Concentration of Phytoplankton                           | Biogeochemical |

docs/user-guide/index.md

@@ -7,3 +7,11 @@ quickstart
 tutorials/index
 assignments/index
 ```
+
+# Documentation
+
+```{toctree}
+:maxdepth: 1
+
+documentation/copernicus_products.md
+```

docs/user-guide/quickstart.md

@@ -80,6 +80,10 @@ For the underway ADCP, there is a choice of using the 38 kHz OceanObserver or th
 
 ### Waypoint datetimes
 
+```{note}
+VirtualShip supports simulating experiments in the years 1993 through to the present day (and up to two weeks in the future) by leveraging the suite of products available Copernicus Marine Data Store (see [Fetch the data](#fetch-the-data)). The data download is automated based on the time period selected in the schedule. Different periods will rely on different products from the Copernicus Marine catalogue (see [Documentation](documentation/copernicus_products.md)).
+```
+
 You will need to enter dates and times for each of the sampling stations/waypoints selected in the MFP route planning stage. This can be done under _Schedule Editor_ > _Waypoints & Instrument Selection_ in the planning tool.
 
 Each waypoint has its own sub-panel for parameter inputs (click on it to expand the selection options). Here, the time for each waypoint can be inputted. There is also an option to adjust the latitude/longitude coordinates and you can add or remove waypoints.

docs/user-guide/tutorials/CTD_transects.ipynb

@@ -9,7 +9,7 @@
     "\n",
     "This notebook demonstrates a simple plotting exercise for CTD data across a transect, using the output of a VirtualShip expedition. There are example plots embedded at the end, but these will ultimately be replaced by your own versions as you work through the notebook.\n",
     "\n",
-    "We can plot physical (temperature, salinity) or biogeochemical data (oxygen, chlorophyll, primary production, phyto/zoo-plankton, nutrients, pH) as measured by the VirtualShip `CTD` and `CTD_BGC` instruments, respectively.\n",
+    "We can plot physical (temperature, salinity) or biogeochemical data (oxygen, chlorophyll, primary production, phytoplankton, nutrients, pH) as measured by the VirtualShip `CTD` and `CTD_BGC` instruments, respectively.\n",
     "\n",
     "The plot(s) we will produce are simple plots which follow the trajectory of the expedition as a function of distance from the first waypoint, and are intended to be a starting point for your analysis. \n",
     "\n",
@@ -93,7 +93,6 @@
     "- \"nitrate\"\n",
     "- \"phosphate\"\n",
     "- \"ph\"\n",
-    "- \"zooplankton\"\n",
     "- \"phytoplankton\"\n",
     "- \"primary_production\"\n",
     "- \"chlorophyll\"\n",
@@ -126,7 +125,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 75,
+   "execution_count": null,
    "id": "b32d2730",
    "metadata": {},
    "outputs": [],
@@ -162,11 +161,6 @@
     "        \"label\": \"pH\",\n",
     "        \"ds_name\": \"ph\",\n",
     "    },\n",
-    "    \"zooplankton\": {\n",
-    "        \"cmap\": cmo.algae,\n",
-    "        \"label\": r\"Total zooplankton (mmol m$^{-3}$)\",\n",
-    "        \"ds_name\": \"zooc\",\n",
-    "    },\n",
     "    \"phytoplankton\": {\n",
     "        \"cmap\": cmo.algae,\n",
     "        \"label\": r\"Total phytoplankton (mmol m$^{-3}$)\",\n",