guides/dynamic-compute/02 Interactive Computing with ImageStacks.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "fcf55c6b-c331-448c-a992-18a32c24b057",
   "metadata": {},
   "source": [
    "# Interactive Computing with Dynamic Compute - ImageStacks\n",
    "__________________\n",
    "\n",
    "In the [previous notebook](./01%20Interactive%20Computing%20with%20Mosaics.ipynb) we were introduced to interactive mapping with mosaics. Here we will explore the [`ImageStack`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.ImageStack) and its expanded functionality to analyze, filter, and manipulate aggregated stacks of raster imagery. \n",
    "\n",
    "For a more detailed look at all its classes and their available methods please visit the [`Dynamic Compute`](https://docs.descarteslabs.com/api/dynamic-compute.html) Documentation page."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ccfb9889-1cdc-454a-b46e-cc7ca680a4b8",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "import descarteslabs.dynamic_compute as dc\n",
    "from descarteslabs.dynamic_compute import ImageStack, Mosaic"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "96eb1c2f-a5ab-4ff6-a8a9-e8c8312e26c4",
   "metadata": {},
   "source": [
    "We'll start by defining an interactive viewport over the Austin, Texas metro area and add a mosaic of RGB data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "923361cb-f90b-4e98-8fc2-97ed6a47497e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "m = dc.map\n",
    "m.center = 30.2743226, -97.7387934\n",
    "m.zoom = 13"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "daeb860e-dbb4-4bc4-a4fe-3f7a68eea9e9",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "s2_mosaic = Mosaic.from_product_bands(\n",
    "    \"esa:sentinel-2:l2a:v1\",\n",
    "    \"red green blue\",\n",
    "    start_datetime=\"2023-01-01\",\n",
    "    end_datetime=\"2023-04-01\",\n",
    ")\n",
    "s2_mosaic.pick_bands(\"red green blue\").visualize(\"S2 TCC\", m)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0536e12e-80ec-4319-a329-6e0ea87c2f80",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "m"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a2593cb6-8d12-4a12-b79e-5ad6e884f2f1",
   "metadata": {},
   "source": [
    "## ImageStacks\n",
    "The first thing we notice in our map viewport is that it's full of clouds! Let's address that by first creating an [`ImageStack.from_product_bands()`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.ImageStack.from_product_bands), with the same arguments as before:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9b4848bc-38dc-4deb-bf73-908bafe81255",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "s2_stack = dc.ImageStack.from_product_bands(\n",
    "    \"esa:sentinel-2:l2a:v1\",\n",
    "    \"red green blue nir swir1\",\n",
    "    start_datetime=\"2023-01-01\",\n",
    "    end_datetime=\"2023-04-01\",\n",
    ")\n",
    "type(s2_stack)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6a9e66fe-ac90-457e-b354-490b1539fd65",
   "metadata": {},
   "source": [
    "**_Note_**: If you are coming from the legacy Workflows client, the ImageStack is analogous to an ImageCollection with full temporal aggregation capability."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "090d9858-ab42-4744-a472-6a2e4b7261b8",
   "metadata": {},
   "source": [
    "## Filtering ImageStacks\n",
    "One limitation of a mosaic is that the _aggregation component of our analysis is not present_. With a stack of data we can call [`ImageStack.filter()`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.ImageStack.filter) based off arbitrary metadata properties, such as __cloud_fraction__:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "71d638e4-dff7-446e-a234-a1f9ece9827c",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "try:\n",
    "    # this is the <1.3.0 dynamic-compute version\n",
    "    s2_stack_cloudfree = s2_stack.filter(lambda x: x.cloud_fraction < 0.2)\n",
    "except Exception:\n",
    "    # this is the >=1.3.0 dynamic-compute version\n",
    "    import descarteslabs as dl\n",
    "    s2_stack_cloudfree = s2_stack.filter(dl.catalog.properties.cloud_fraction < 0.2)\n",
    "type(s2_stack_cloudfree)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "9c8e6c64-528d-4131-ab1b-d4748f99d02f",
   "metadata": {},
   "source": [
    "## Visualizing ImageStacks\n",
    "\n",
    "If we tried calling visualize on this now we would not return any imagery, that is because we need to _reduce_ our data, in this case across it's temporal dimension. \n",
    "\n",
    "In the next cell we will call [`ImageStack.median()`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.ImageStack.median) on our filtered data before visualizing onto our map:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aff0c6c4-6fae-44cb-9683-40c1dee62c56",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "(\n",
    "    s2_stack_cloudfree.median(axis=\"images\")\n",
    "    .pick_bands(\"red green blue\")\n",
    "    .visualize(\"S2 TCC Cloudfree\", m)\n",
    ")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8be63cc4-fb7d-4f48-a203-e41ad048d9f5",
   "metadata": {},
   "source": [
    "**Note**: _There are several other operators you can use (e.g. [`min`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.ImageStack.min), [`mean`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.ImageStack.mean), [`max`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.ImageStack.max), [`std`](https://docs.descarteslabs.com/api/dynamic-compute.html#descarteslabs.dynamic_compute.ImageStack.std), etc.)_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "40c0c70c-9776-49b0-926c-9b639d3de06b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "m"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c356fbef-8994-44f4-8ce0-4fb6f5e74892",
   "metadata": {},
   "source": [
    "No more clouds!"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a1e9b5c1-81a3-4878-9577-06bac371bff0",
   "metadata": {},
   "source": [
    "## Band Ratios with ImageStacks\n",
    "\n",
    "As we've seen, the enhanced flexibility afforded when working with image stacks comes with the added complexity of needing to reduce dimensions. \n",
    "\n",
    "Here we will calculate the median [_Normalized Difference in Built-up Index_](https://d-nb.info/1195147821/34) of our cloud-free study area:\n",
    "\n",
    "$NDBI = (SWIR1 - NIR) / (SWIR1 + NIR)$"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e71978c5-7d56-4d87-8fa8-bbc27fe08581",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "nir, swir = s2_stack_cloudfree.unpack_bands(\"nir swir1\")\n",
    "ndbi = (swir - nir) / (swir + nir)\n",
    "ndbi.median(axis=\"images\").visualize(\"NDBI\", m)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "445b27a1-def5-4a28-afbb-f7a2c02942bb",
   "metadata": {},
   "outputs": [],
   "source": [
    "m"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3 (ipykernel)",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.18"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 5
}