Update to DEA Notebooks Template

.devcontainer/devcontainer.json

@@ -0,0 +1,33 @@
+{
+  "name": "dea-notebooks",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+  "features": {
+    "ghcr.io/devcontainers/features/python:1": {
+      "version": "3.11",
+      "installJupyterlab": true
+    }
+  },
+  "postCreateCommand": "pip install -r requirements.txt",
+  "postStartCommand": "nohup jupyter lab --ip 0.0.0.0 --port 8888 --no-browser --NotebookApp.token='' > /tmp/jupyter.log 2>&1 &",
+  "forwardPorts": [8888],
+  "portsAttributes": {
+    "8888": {
+      "label": "JupyterLab",
+      "onAutoForward": "openBrowser"
+    }
+  },
+  "hostRequirements": {
+    "cpus": 4,
+    "memory": "16gb",
+    "storage": "15gb"
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "ms-python.python",
+        "ms-toolsai.jupyter",
+        "charliermarsh.ruff"
+      ]
+    }
+  }
+}

DEA_notebooks_template.ipynb

@@ -1,54 +1,104 @@
 {
  "cells": [
   {
-   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### General advice (delete this cell before submitting for review)\n",
+    "<!-- DEA Notebook Header -->\n",
+    "<div style=\"font-family:'Segoe UI',Roboto,sans-serif; line-height:1.6; color:CanvasText; padding:32px;\">\n",
+    "\n",
+    "<img src=\"https://raw.githubusercontent.com/GeoscienceAustralia/dea-notebooks/stable/Supplementary_data/dea_logo_wide.jpg\" alt=\"DEA Notebooks logo\" style=\"width:86.5%;\">\n",
+    "\n",
+    "<h1>Descriptive title that follows notebook filename</h1>\n",
+    "\n",
+    "<p>\n",
+    "🔎 Visit <a href=\"https://knowledge.dea.ga.gov.au\">DEA's Knowledge Hub</a> for detailed technical information about the datasets and concepts used in this notebook.\n",
+    "</p>\n",
+    "\n",
+    "<p>\n",
+    "<span style=\"display:inline-block; font-size:12px; background:rgba(59,130,246,0.15); border-radius:12px; padding:3px 10px; margin-right:6px;\">🟢 Beginner</span>\n",
+    "<span style=\"display:inline-block; font-size:12px; background:rgba(16,185,129,0.15); border-radius:12px; padding:3px 10px; margin-right:6px;\">⚡ Runtime: ~10 mins</span>\n",
+    "<span style=\"display:inline-block; font-size:12px; background:rgba(107,114,128,0.15); border-radius:12px; padding:3px 10px; margin-right:6px;\">🗓️ Updated: 2025-08</span>\n",
+    "</p>\n",
+    "\n",
+    "<!-- Products - REQUIRED -->\n",
+    "<div style=\"margin-bottom:12px; padding:12px; background:rgba(59,130,246,0.08); border:1px solid rgb(59,130,246); border-radius:8px; max-width:85%;\">\n",
+    "<b>📦 Products used</b><br>\n",
+    "<a href=\"https://knowledge.dea.ga.gov.au/data/category/sentinel-2a-analysis-ready-data/\">ga_s2am_ard_3</a>, \n",
+    "<a href=\"https://knowledge.dea.ga.gov.au/data/category/sentinel-2b-analysis-ready-data/\">ga_s2bm_ard_3</a>, \n",
+    "<a href=\"https://knowledge.dea.ga.gov.au/data/category/sentinel-2c-analysis-ready-data/\">ga_s2cm_ard_3</a>, \n",
+    "<a href=\"https://knowledge.dea.ga.gov.au/data/category/landsat-5-analysis-ready-data/\">ga_ls5t_ard_3</a>, \n",
+    "<a href=\"https://knowledge.dea.ga.gov.au/data/category/landsat-7-analysis-ready-data/\">ga_ls7e_ard_3</a>, \n",
+    "<a href=\"https://knowledge.dea.ga.gov.au/data/category/landsat-8-analysis-ready-data/\">ga_ls8c_ard_3</a>\n",
+    "</div>\n",
+    "\n",
+    "<!-- Special requirements - OPTIONAL, delete if not required -->\n",
+    "<div style=\"margin-bottom:12px; padding:12px; background:rgba(59,130,246,0.08); border:1px solid rgb(59,130,246); border-radius:8px; max-width:85%;\">\n",
+    "<b>⚙️ Special requirements</b><br>\n",
+    "Optional notes, e.g. If running on the NCI, ensure that <code>module load otps</code> is run prior to launching this notebook.\n",
+    "</div>\n",
+    "\n",
+    "<!-- Prerequisites - OPTIONAL, delete if not required -->\n",
+    "<div style=\"margin-bottom:12px; padding:12px; background:rgba(59,130,246,0.08); border:1px solid rgb(59,130,246); border-radius:8px; max-width:85%;\">\n",
+    "<b>🧾 Prerequisites</b><br>\n",
+    "Optional list of prerequisite notebooks or background knowledge, e.g. Run the XYZ notebook before running this.\n",
+    "</div>\n",
+    "\n",
+    "<!-- Citing - OPTIONAL, delete if not required -->\n",
+    "<div style=\"margin-bottom:12px; padding:12px; background:rgba(59,130,246,0.08); border:1px solid rgb(59,130,246); border-radius:8px; max-width:85%;\">\n",
+    "<b>📝 Citation</b><br>\n",
+    "Optional description of any notebook-specific acknowledgement/citation requirements, e.g. Please cite Krause et al. (2021) when using the results of this notebook.\n",
+    "</div>\n",
+    "\n",
+    "<!-- Important notes - OPTIONAL, delete if not required and use sparingly -->\n",
+    "<div style=\"margin-bottom:12px; padding:12px; background:rgba(251,191,36,0.15); border:1px solid rgb(251,191,36); border-radius:8px; max-width:85%;\">\n",
+    "<b>⚠️ Important</b><br>\n",
+    "Optional important notes to be highlighted, e.g. This notebook is not to be used for safety of life decisions.\n",
+    "</div>\n",
+    "\n",
+    "<!-- How to run - REQUIRED -->\n",
+    "<div style=\"margin-bottom:12px; padding:12px; background:rgba(16,185,129,0.1); border:1px solid rgb(16,185,129); border-radius:8px; max-width:85%;\">\n",
+    "<b>🚀 How you can run this notebook</b><br>\n",
     "\n",
-    "* Update the **Compatibility** line depending on whether the notebook is compatible with the `NCI` and `DEA Sandbox` environments (e.g. \"Notebook currently compatible with the `DEA Sandbox` environment only\" or \"Notebook currently compatible with the `NCI` environment only\")\n",
-    "* When adding **Products used**, embed the hyperlink to that specific product on the DEA Explorer using the `[product_name](product url)` syntax.\n",
-    "* When writing in Markdown cells, start each sentence on a **new line**. This makes it easy to see changes through git commits.\n",
-    "* Use Australian English in markdown cells and code comments.\n",
-    "* See the [Knowledge Hub formatting troubleshooting guide](https://github.com/GeoscienceAustralia/dea-notebooks/wiki/Troubleshooting-Knowledge-Hub-formatting) to ensure your formatting will display properly on the [DEA Knowledge Hub](https://knowledge.dea.ga.gov.au/). Things to be aware of:\n",
-    "    * Sphinx is highly sensitive to bulleted lists:\n",
-    "        * Ensure that there is an empty line between any preceding text and the list\n",
-    "        * Only use the `*` bullet (`-` is not recognised)\n",
-    "        * Sublists must be indented by 4 spaces        \n",
-    "    * Two kinds of formatting cannot be used simultaneously:\n",
-    "        * Hyperlinked code: \\[\\`code_format\\`](hyperlink) fails\n",
-    "        * Bolded code: \\*\\*\\`code_format\\`\\*\\* fails\n",
-    "    * Headers must appear in heirachical order (`#`, `##`, `###`, `####`) and there can only be one title (`#`).\n",
-    "* Use the [PEP8 standard](https://www.python.org/dev/peps/pep-0008/) for code. To make sure all code in the notebook is consistent, you can use the `jupyterlab_code_formatter` tool: select each code cell, then click `Edit` and then one of the `Apply X Formatter` options (`YAPF` or `Black` are recommended). This will reformat the code in the cell to a consistent style.\n",
-    "* For additional guidance, refer to the style conventions and layouts in approved `develop` branch notebooks. Examples include:\n",
-    "    * [How_to_guides/Using_load_ard.ipynb](../How_to_guides/Using_load_ard.ipynb)\n",
-    "    * [Real_world_examples/Coastal_erosion.ipynb](../Real_world_examples/Coastal_erosion.ipynb)\n",
-    "    * [Tools/dea_tools/datahandling.py](../Tools/dea_tools/datahandling.py)\n",
-    "* In the final notebook cell, include a set of relevant tags which are used to build the DEA User Guide's [Tag Index](https://knowledge.dea.ga.gov.au/genindex/). \n",
-    "Use all lower-case (unless the tag is an acronym), separate words with spaces (unless it is the name of an imported module), and [re-use existing tags](https://github.com/GeoscienceAustralia/dea-notebooks/wiki/List-of-tags).\n",
-    "Ensure the tags cell below is in `Raw` format, rather than `Markdown` or `Code`.\n",
+    "- <b>DEA Sandbox:</b> Eligible users can sign up for the <a href=\"https://sandbox.dea.ga.gov.au/\">DEA Sandbox</a> that provides free compute and a managed Python environment.\n",
     "\n",
-    "---\n"
+    "- <b>Personal computer:</b> This notebook loads DEA data using <code>odc-stac</code>. Data streams via the internet, so can be run locally after installing the required <a href=\"https://pypi.org/project/dea-tools/\">DEA Tools</a> Python package, e.g. <code>pip install dea-tools[notebooks]</code>.\n",
+    "\n",
+    "<!-- - <b>Run this notebook online:</b> Click on the badge below to launch a GitHub Codespaces instance to run the notebook from your browser. See this <a href=\"\">wiki page</a> for more information.\n",
+    "\n",
+    "  <a href=\"https://codespaces.new/GeoscienceAustralia/dea-notebooks/tree/template?quickstart=1\" target=\"_blank\">\n",
+    "    <img src=\"https://img.shields.io/badge/Codespaces-Open-blue?logo=github\" alt=\"Open in GitHub Codespaces\" style=\"height:25px;\">\n",
+    "  </a>\n",
+    "</div> -->\n",
+    "\n",
+    "</div>\n"
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "# Descriptive title that follows notebook filename <img align=\"right\" src=\"./Supplementary_data/dea_logo.jpg\">\n",
-    "\n",
-    "* **[Sign up to the DEA Sandbox](https://app.sandbox.dea.ga.gov.au/)** to run this notebook interactively from a browser\n",
-    "* **Compatibility:** Notebook currently compatible with both the `NCI` and `DEA Sandbox` environments\n",
-    "* **Products used:** \n",
-    "[ga_s2am_ard_3](https://explorer.dea.ga.gov.au/products/ga_s2am_ard_3), \n",
-    "[ga_s2bm_ard_3](https://explorer.dea.ga.gov.au/products/ga_s2bm_ard_3),\n",
-    "[ga_s2cm_ard_3](https://explorer.dea.ga.gov.au/products/ga_s2cm_ard_3),\n",
-    "[ga_ls5t_ard_3](https://explorer.dea.ga.gov.au/products/ga_ls5t_ard_3),\n",
-    "[ga_ls7e_ard_3](https://explorer.dea.ga.gov.au/products/ga_ls7e_ard_3),\n",
-    "[ga_ls8c_ard_3](https://explorer.dea.ga.gov.au/products/ga_ls8c_ard_3)\n",
-    "* **Special requirements:** An _optional_ description of any special requirements, e.g. If running on the [NCI](https://nci.org.au/), ensure that `module load otps` is run prior to launching this notebook\n",
-    "* **Prerequisites:** An _optional_ list of any notebooks that should be run or content that should be understood prior to launching this notebook\n"
+    "> ### General advice (delete this cell before submitting for review)\n",
+    ">\n",
+    "> * When adding **Products used**, embed the hyperlink to that specific product page on the [DEA Knowledge Hub](https://knowledge.dea.ga.gov.au/data/) using the `[product ID](product url)` syntax.\n",
+    "> * When writing in Markdown cells, start each sentence on a **new line**. This makes it easy to see changes through Git commits.\n",
+    "> * Use Australian English in markdown cells and code comments.\n",
+    "> * See the [Knowledge Hub formatting troubleshooting guide](https://github.com/GeoscienceAustralia/dea-notebooks/wiki/Troubleshooting-Knowledge-Hub-formatting) to ensure your formatting will display properly on the [DEA Knowledge Hub](https://knowledge.dea.ga.gov.au/). Things to be aware of:\n",
+    ">     * Sphinx is highly sensitive to bulleted lists:\n",
+    ">         * Ensure that there is an empty line between any preceding text and the list\n",
+    ">         * Only use the `*` bullet (`-` is not recognised)\n",
+    ">         * Sublists must be indented by 4 spaces        \n",
+    ">     * Two kinds of formatting cannot be used simultaneously:\n",
+    ">         * Hyperlinked code: \\[\\`code_format\\`](hyperlink) fails\n",
+    ">         * Bolded code: \\*\\*\\`code_format\\`\\*\\* fails\n",
+    ">     * Headers must appear in heirachical order (`#`, `##`, `###`, `####`) and there can only be one title (`#`).\n",
+    "> * Use the [PEP8 standard](https://www.python.org/dev/peps/pep-0008/) for code. To make sure all code in the notebook is consistent, you can use the `jupyterlab_code_formatter` tool: select each code cell, then click `Edit` and then one of the `Apply X Formatter` options (`YAPF` or `Black` are recommended). This will reformat the code in the cell to a consistent style.\n",
+    "> * For additional guidance, refer to the style conventions and layouts in approved `develop` branch notebooks. Examples include:\n",
+    ">     * [How_to_guides/Using_load_ard.ipynb](../How_to_guides/Using_load_ard.ipynb)\n",
+    ">     * [Real_world_examples/Coastal_erosion.ipynb](../Real_world_examples/Coastal_erosion.ipynb)\n",
+    ">     * [Tools/dea_tools/datahandling.py](../Tools/dea_tools/datahandling.py)\n",
+    ">"
    ]
   },
   {
@@ -80,69 +130,60 @@
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "## Getting started\n",
-    "\n",
-    "Provide any particular instructions that the user might need, e.g. To run this analysis, run all the cells in the notebook, starting with the \"Load packages\" cell. "
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "### Load packages\n",
+    "## Load packages\n",
     "Import Python packages that are used for the analysis.\n",
     "\n",
-    "Use standard import commands; some are shown below. \n",
-    "Begin with any `iPython` magic commands, followed by standard Python packages, then any additional functionality you need from the `Tools` directory."
+    "Use standard import commands; some are shown below.\n",
+    "Begin with any `iPython` magic commands (if required), followed by standard Python packages, then any additional functionality from the `dea_tools` Python package."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 1,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
-    "%matplotlib inline\n",
+    "import pystac_client\n",
+    "import odc.stac\n",
     "\n",
-    "import datacube\n",
-    "import matplotlib.pyplot as plt\n",
     "import numpy as np\n",
     "import pandas as pd\n",
     "import xarray as xr\n",
+    "import matplotlib.pyplot as plt\n",
     "\n",
-    "import sys\n",
-    "sys.path.insert(1, '../Tools/')\n",
     "from dea_tools.plotting import rgb\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Connect to the datacube\n",
+    "## Connect to DEA's STAC API\n",
+    "\n",
+    "This allows us to search for data using DEA's STAC API (refer to the [SpatioTemporal Asset Catalogue guide](https://knowledge.dea.ga.gov.au/guides/setup/gis/stac/) for details).\n",
     "\n",
-    "Connect to the datacube so we can access DEA data.\n",
-    "The `app` parameter is a unique name for the analysis which is based on the notebook file name."
+    "To load data, we must also configure access to DEA's Amazon S3 buckets using `odc.stac.configure_s3_access`.\n",
+    "If launching a Dask client (e.g. `dea_tools.dask.create_local_dask_cluster()`), this is done automatically."
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 2,
-   "metadata": {
-    "jupyter": {
-     "source_hidden": true
-    }
-   },
+   "execution_count": null,
+   "metadata": {},
    "outputs": [],
    "source": [
-    "dc = datacube.Datacube(app='DEA_notebooks_template')"
+    "# Configure data access\n",
+    "odc.stac.configure_s3_access(cloud_defaults=True, aws_unsigned=True)\n",
+    "\n",
+    "# Connect to STAC API\n",
+    "catalog = pystac_client.Client.open(\"https://explorer.dea.ga.gov.au/stac\")\n"
    ]
   },
   {
    "cell_type": "markdown",
    "metadata": {},
    "source": [
-    "### Analysis parameters\n",
+    "## Analysis parameters\n",
     "\n",
     "An *optional* section to inform the user of any parameters they'll need to configure to run the notebook:\n",
     "\n",
@@ -152,7 +193,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 3,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -174,7 +215,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 4,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -192,7 +233,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 5,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -210,7 +251,7 @@
   },
   {
    "cell_type": "code",
-   "execution_count": 6,
+   "execution_count": null,
    "metadata": {},
    "outputs": [],
    "source": [
@@ -232,43 +273,17 @@
     "**Contact:** If you need assistance, please post a question on the [Open Data Cube Discord chat](https://discord.com/invite/4hhBQVas5U) or on the [GIS Stack Exchange](https://gis.stackexchange.com/questions/ask?tags=open-data-cube) using the `open-data-cube` tag (you can view previously asked questions [here](https://gis.stackexchange.com/questions/tagged/open-data-cube)).\n",
     "If you would like to report an issue with this notebook, you can file one on [GitHub](https://github.com/GeoscienceAustralia/dea-notebooks).\n",
     "\n",
-    "**Last modified:** September 2021\n",
-    "\n",
-    "**Compatible datacube version:** "
+    "**Last tested:**\n"
    ]
   },
   {
    "cell_type": "code",
-   "execution_count": 7,
+   "execution_count": null,
    "metadata": {},
-   "outputs": [
-    {
-     "name": "stdout",
-     "output_type": "stream",
-     "text": [
-      "1.8.19\n"
-     ]
-    }
-   ],
-   "source": [
-    "print(datacube.__version__)"
-   ]
-  },
-  {
-   "cell_type": "markdown",
-   "metadata": {},
-   "source": [
-    "## Tags\n",
-    "<!-- Browse all available tags on the DEA User Guide's [Tags Index](https://knowledge.dea.ga.gov.au/genindex/) -->"
-   ]
-  },
-  {
-   "cell_type": "raw",
-   "metadata": {
-    "raw_mimetype": "text/restructuredtext"
-   },
+   "outputs": [],
    "source": [
-    "**Tags**: :index:`template`, :index:`sandbox compatible`, "
+    "from datetime import datetime\n",
+    "datetime.today().strftime('%Y-%m-%d')"
    ]
   }
  ],
@@ -288,7 +303,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.10.15"
+   "version": "3.10.18"
   },
   "widgets": {
    "application/vnd.jupyter.widget-state+json": {

requirements.txt

@@ -0,0 +1,4 @@
+## dea-tools will install most required packages
+dea-tools[notebooks]>0.4
+dask-labextension
+jupyter-resource-usage