Dev #8: Add ORAS5Downloader example + updates

notebook.ipynb

@@ -286,16 +286,21 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "The downloader implementation of this data in IceNet utilises the CDS API which requires registration and configuration of an API key before downloading. The registration is free, please see [the official CDS API how-to](https://cds.climate.copernicus.eu/api-how-to) for more instructions on how to set this up.\n",
-    "\n",
     ":::{note}\n",
     "Since the ERA5 and ORAS5 data downloads require registration before download, this demonstrator will only download and use observed sea ice concentration data for training.\n",
+    ":::\n",
+    "\n",
+    "### ERA5 Downloader\n",
+    "\n",
+    "The downloader implementation of this data in IceNet utilises the CDS API which requires registration and configuration of an API key before downloading. The registration is free, please see [the official CDS API how-to](https://cds.climate.copernicus.eu/api-how-to) for more instructions on how to set this up.\n",
     "\n",
     "Once the key is configured correctly, you can utilise the `ERA5Downloader` class, for example, to download climate variables and use it for training the model in addition to the sea ice concentration data that is downloaded further below.\n",
-    ":::\n",
     "\n",
     "\n",
     "```python\n",
+    "import pandas as pd\n",
+    "from icenet.data.interfaces.cds import ERA5Downloader\n",
+    "\n",
     "era5 = ERA5Downloader(\n",
     "    var_names=[\"tas\", \"zg\", \"uas\", \"vas\"],      # Name of variables to download\n",
     "    dates=[                                     # Dates to download the variable data for\n",
@@ -338,6 +343,64 @@
     "```"
    ]
   },
+  {
+   "cell_type": "markdown",
+   "metadata": {},
+   "source": [
+    "### ORAS5 Downloader\n",
+    "\n",
+    "The ORAS5 Downloader uses the Copernicus Marine toolbox which requires [registration](https://data.marine.copernicus.eu/register).\n",
+    "\n",
+    "<details close>\n",
+    "<summary>Once registered, please follow these steps to set up credentials</summary>\n",
+    "<br>\n",
+    "\n",
+    "**Option 1:**\n",
+    "\n",
+    "By defining a `~/.cmems.creds` file (i.e. in your home directory) as follows:\n",
+    "\n",
+    "```\n",
+    "[auth]\n",
+    "username = my_copernicus_marine_username\n",
+    "password = my_copernicus_marine_password\n",
+    "```\n",
+    "\n",
+    "**Option 2:**\n",
+    "\n",
+    "By setting the following environment variables:\n",
+    "\n",
+    "```bash\n",
+    "export COPERNICUSMARINE_SERVICE_USERNAME=my_copernicus_marine_username\n",
+    "export COPERNICUSMARINE_SERVICE_PASSWORD=my_copernicus_marine_password\n",
+    "```\n",
+    "\n",
+    "</details>\n",
+    "\n",
+    "Once configured, the ORAS5Downloader can used as follows:\n",
+    "\n",
+    "```python\n",
+    "import pandas as pd\n",
+    "from icenet.data.interfaces.cmems import ORAS5Downloader\n",
+    "\n",
+    "vars = [\"thetao\"]\n",
+    "\n",
+    "oras5 = ORAS5Downloader(\n",
+    "    var_names=vars,                             # Name of variables to download\n",
+    "    dates=[                                     # Dates to download the variable data for\n",
+    "        pd.to_datetime(date).date()\n",
+    "        for date in pd.date_range(\"2020-01-01\", \"2020-04-30\", freq=\"D\")\n",
+    "    ],\n",
+    "    path=\"./data\",                              # Location to download data to (default is `./data`)\n",
+    "    delete_tempfiles=True,                      # Whether to delete temporary downloaded files\n",
+    "    levels=[None for _ in vars],                # A list of None for number of variables\n",
+    "    max_threads=1,                              # Maximum number of concurrent downloads\n",
+    "    north=False,                                # Boolean: Whether require data across northern hemisphere\n",
+    "    south=True)                                 # Boolean: Whether require data across southern hemisphere\n",
+    "oras5.download()                                # Start downloading\n",
+    "oras5.regrid()\n",
+    "```"
+   ]
+  },
   {
    "cell_type": "markdown",
    "metadata": {},