Review and edit markdown cells and comments within code cells

Author: zacdezgeo

docs/src/notebooks/eoAPI_Maxar_demo.ipynb

@@ -1,28 +1,28 @@
 {
  "cells": [
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "a0eb29a0",
    "metadata": {},
    "source": [
     "## eoAPI Demo\n",
     "\n",
     "\n",
-    "This notebook will try to go over the different [eoAPI](https://github.com/developmentseed/eoAPI) services using the latest Open data from Maxar acquired during the Hawaii fired of August 2023\n",
+    "This notebook will review the different [eoAPI](https://github.com/developmentseed/eoAPI) services using the latest Open data from Maxar acquired during the Hawaii fires of August 2023\n",
     "\n",
     "\n",
     "### Maxar Open Data\n",
     "\n",
-    "> Pre and post event high-resolution satellite imagery in support of emergency planning, risk assessment, monitoring of staging areas and emergency response, damage assessment, and recovery. These images are generated using the Maxar ARD pipeline, tiled on an organized grid in analysis-ready cloud-optimized formats.\n",
+    "> Pre and post-event high-resolution satellite imagery in support of emergency planning, risk assessment, monitoring of staging areas and emergency response, damage assessment, and recovery. These images are generated using the Maxar ARD pipeline, tiled on an organized grid in analysis-ready cloud-optimized formats.\n",
     "\n",
     "\n",
     "\n",
     "### STAC and COGs\n",
     "\n",
-    "Maxar releases open data for select sudden onset major crisis events. In addition of putting the data (as nice COGs) freely available on AWS they are also adding STAC (static) metadata alongside the images. Having the STAC items already created makes ingestion into PgSTAC database really easy (we don't have to create the items ourself and thus having to read the images).\n",
+    "Maxar releases open data for select sudden-onset major crisis events. In addition to putting the data (as nice COGs) freely available on AWS, they are also adding STAC (static) metadata alongside the images. Having the STAC items already created makes ingestion into the PgSTAC database easy (we don't have to produce the items ourselves and thus have to read the images).\n",
     "\n",
-    "\n",
-    "To learn more about how we ingest MAXAR OpenData STAC catalog into pgstac see https://github.com/vincentsarago/MAXAR_opendata_to_pgstac\n"
+    "To learn more about how we ingest Maxar OpenData STAC catalog into PgSTAC see https://github.com/vincentsarago/MAXAR_opendata_to_pgstac.\n"
    ]
   },
   {
@@ -61,17 +61,19 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "5237534c",
    "metadata": {},
    "source": [
     "## Collections\n",
     "\n",
     "\n",
-    "In this section we will:\n",
-    "- list all the collection stored in the pgSTAC database (backend of the eoapi STAC service\n",
-    "- talk about the collection metadata (and extensions)\n",
-    "- see how to visualized the collections on a Map using collection's Spatial Extent "
+    "In this section, we will:\n",
+    "\n",
+    "- List all the collections stored in the pgSTAC database (backend of the eoapi STAC service\n",
+    "- Talk about the collection metadata (and extensions)\n",
+    "- See how to visualize the collections on a Map using the collection's Spatial Extent "
    ]
   },
   {
@@ -119,11 +121,12 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "51e448c1",
    "metadata": {},
    "source": [
-    "Each collection should be in form of \n",
+    "Each collection should be in the form:\n",
     "```json\n",
     "{\n",
     "    \"id\": ...,\n",
@@ -157,7 +160,7 @@
     "}\n",
     "```\n",
     "\n",
-    "**Important**: in eoapi, we are trying to set an example of good practice which is why we choose to add `optional` extension in our collections. The `item_assets` extension is quite useful because it quickly tell what assets are found within all the collection's items. This can help creating visualization for the whole collections without knowing much about its items."
+    "**Important**: in eoapi, we are trying to set an example of good practice, so we choose to add `optional` extension in our collections. The `item_assets` extension is helpful because it quickly tells what assets are found within all the collection's items. This can help create visualizations for the whole collection without knowing much about its items."
    ]
   },
   {
@@ -414,13 +417,14 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "b2a46c84",
    "metadata": {},
    "source": [
     "### Vizualizing the collections \n",
     "\n",
-    "Each collections should have at least one spatial extent (combined) so let's use those to create a GeoJSON and add it to the map"
+    "Each collection should have at least one spatial extent (combined), so let's use those to create a GeoJSON and add it to the map:"
    ]
   },
   {
@@ -661,7 +665,7 @@
    "source": [
     "# As mentioned, the collection's spatial extent can be a combination of multiple bbox\n",
     "\n",
-    "# Here we use the `/collections/{collectionId}` endpoing\n",
+    "# Here we use the `/collections/{collectionId}` endpoint\n",
     "\n",
     "collection_info = httpx.get(\"https://stac.eoapi.dev/collections/MAXAR_Maui_Hawaii_fires_Aug_23\").json()\n",
     "\n",
@@ -699,13 +703,14 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "5fd7a387",
    "metadata": {},
    "source": [
     "#### Temporal Extent\n",
     "\n",
-    "Each collection can have spatial and temporal extent. Same as for the spatial extent, a collection can have multiple temporal extent but with it's first one representing the combined `min/max` of all the intervals."
+    "Each collection can have spatial and temporal extents. As for the spatial extent, a collection can have multiple temporal extents but with its first one representing the combined min/max of all the intervals."
    ]
   },
   {
@@ -732,14 +737,14 @@
    "metadata": {},
    "source": [
     "## Items\n",
-    "Let's checks the items for the Hawaii Fire collections: `MAXAR_Maui_Hawaii_fires_Aug_23`\n",
+    "Let's check the items for the Hawaii Fire collections: `MAXAR_Maui_Hawaii_fires_Aug_23`\n",
     "\n",
+    "In this section, we will:\n",
     "\n",
-    "In this section we will:\n",
-    "- list all items for a specific collection\n",
-    "- talk about the `limit` parameter \n",
-    "- visualize all items on a map\n",
-    "- talk about the item metadata"
+    "- List all items for a specific collection\n",
+    "- Talk about the `limit` parameter\n",
+    "- Visualize all items on a map\n",
+    "- Talk about the item metadata"
    ]
   },
   {
@@ -1061,7 +1066,7 @@
    "id": "ad0efb74",
    "metadata": {},
    "source": [
-    "As you can see bellow, the `/items` endpoints returned only 10 items. To return more data we need to either use the `pagging` mechanism or use the `limit` query parameter to get more items per requests "
+    "As you can see below, the `/items` endpoints returned only 10 items. To return more data we need to either use the `paging` mechanism or use the `limit` query parameter to get more items per request."
    ]
   },
   {
@@ -1294,13 +1299,14 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "844f4575",
    "metadata": {},
    "source": [
     "#### Find acquisition times\n",
     "\n",
-    "By definition, every item should have either a `datetime` or a `start/end_datetime` property. For the Maxar dataset, we are assuming that `datetime` are acquisition times."
+    "By definition, every item should have either a `datetime` or a `start/end_datetime` property. For the Maxar dataset, we are assuming that `datetime` is acquisition times."
    ]
   },
   {
@@ -1356,18 +1362,19 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "2693e87a",
    "metadata": {},
    "source": [
-    "Note: The `catalog_id` represent a unique acquisition Id. In our case, this mean that all items are derived from 5 different acquisitions. \n",
+    "Note: The `catalog_id` represents a unique acquisition ID. In our case, this means that all items are derived from 5 different acquisitions. \n",
     "\n",
     "> The unique identifier for the item, as assigned by the provider, Maxar. This is also referred to as the \"acquisition ID\".\n",
     "\n",
     "ref: https://ard.maxar.com/docs/select-and-order/select-stac-collection-file/#properties-object\n",
     "\n",
     "\n",
-    "Let's look back at the item's datetime. If we remove the `seconds`"
+    "Let's look back at the item's datetime. If we remove the `seconds`:"
    ]
   },
   {
@@ -1390,21 +1397,23 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "7de68313",
    "metadata": {},
    "source": [
-    "We get 5 different dates, which might correspond to 5 different aquisition (Keep this in mind for later)"
+    "We get 5 different dates, which might correspond to 5 different acquisitions (keep this in mind for later)."
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "4ca2e374",
    "metadata": {},
    "source": [
     "## Assets \n",
     "\n",
-    "So we have **123** items for the `MAXAR_Maui_Hawaii_fires_Aug_23` collection, and each item have **4** assets (this is also found at collection level in the `item_assets` extension."
+    "So we have **123** items for the `MAXAR_Maui_Hawaii_fires_Aug_23` collection, and each item has **4** assets (this is also found at the collection level in the `item_assets extension`)."
    ]
   },
   {
@@ -1484,13 +1493,14 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "7bc1a304",
    "metadata": {},
    "source": [
     "# Raster\n",
     "\n",
-    "In eoAPI we have a raster API which is connected to the PgSTAC database. The service is built using [titiler-pgstac](http://github.com/stac-utils/titiler-pgstac) and can be used to visualize `Item` or `Mosaics` (multiple items).\n",
+    "In eoAPI, we have a raster API connected to the PgSTAC database. The service is built using [titiler-pgstac](http://github.com/stac-utils/titiler-pgstac) and can be used to visualize `Item` or `Mosaics` (multiple items).\n",
     "\n",
     "\n",
     "Endpoint: https://raster.eoapi.dev"
@@ -1625,21 +1635,22 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "3a87b045",
    "metadata": {},
    "source": [
-    "The `/collections/{collectionId}/items/{itemId}/info` endpoint returned metadata for 3 assets (the raster ones). We now know a bit more about each assets (datatype, zoom levels, number of bands) which can help us for creating tiles urls.\n",
+    "The `/collections/{collectionId}/items/{itemId}/info` endpoint returned metadata for 3 assets (the raster ones). We now know a bit more about each asset (datatype, zoom levels, number of bands), which can help us create tiles urls.\n",
     "\n",
     "\n",
     "##### Asset on Map\n",
     "\n",
-    "To visualize an asset on a Map we need to construct a `Tile URL`. To ease the task we can use the raster's service `/tilejson.json` endpoint, but here are the requirement:\n",
+    "To visualize an asset on a Map, we need to construct a `Tile URL`. To ease the task we can use the raster's service `/tilejson.json` endpoint, but here are the requirements:\n",
     "\n",
     "- HAVE TO pass `assets` or `expression` parameter\n",
-    "- CAN pass `min/max zooms` (which will avoid under/overzooming)\n",
+    "- CAN pass `min/max zooms` (which will avoid under/over-zooming)\n",
     "- CAN pass `rescale` parameter if datatype is not compatible with PNG/JPEG output format\n",
-    "- CAN pass `asset_bidx` parameter to select band combination\n"
+    "- CAN pass `asset_bidx` parameter to select band combination"
    ]
   },
   {
@@ -1934,13 +1945,14 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "b6ad993a",
    "metadata": {},
    "source": [
-    "The `ms_analytic` asset has more than 3 bands and is also of `Uint16` data type, so to be able to visualize it we will need to:\n",
+    "The `ms_analytic` asset has more than 3 bands and is also of `Uint16` data type, so to be able to visualize it, we will need to:\n",
     "- select 1 or 3 bands\n",
-    "- apply some linear rescaling between min/max value (we can an approximation using the `/statistics` endpoint)"
+    "- apply some linear rescaling between min/max values (we can make an approximation using the `/statistics` endpoint)"
    ]
   },
   {
@@ -2366,17 +2378,18 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "3a02b6ae",
    "metadata": {},
    "source": [
     "## Mosaics\n",
     "\n",
-    "As mentioned and shown, with `titiler-pgstac` we can visualize item's asset but the real power of the raster api is  to be able to create virtual mosaic dynamically and merging multiple items together on the fly\n",
+    "As mentioned and shown with `titiler-pgstac`, we can visualize an item's asset, but the real power of the raster API is  to be able to create a virtual mosaic dynamically and merge multiple items on the fly.\n",
     "\n",
-    "learn more: http://github.com/stac-utils/titiler-pgstac\n",
+    "Learn more: http://github.com/stac-utils/titiler-pgstac.\n",
     "\n",
-    "Let's create `mosaics` for a specific datetime we found in previous step.\n",
+    "Let's create `mosaics` for a specific DateTime we found in the previous step.\n",
     "\n",
     "> ['2023-08-09T21:10', '2023-08-09T21:20', '2023-08-12T21:11', '2023-08-12T21:12', '2023-08-12T21:18']"
    ]
@@ -2431,6 +2444,7 @@
    ]
   },
   {
+   "attachments": {},
    "cell_type": "markdown",
    "id": "6dd5f539",
    "metadata": {},
@@ -2439,9 +2453,9 @@
     "\n",
     "```json\n",
     "{\n",
-    "    // PgSTAC accept multiple language for filter, here we will just cql2-json\n",
+    "    // PgSTAC accepts multiple languages for filtering; here we will use cql2-json\n",
     "    \"filter-lang\": 'cql2-json',\n",
-    "    // We tell PgSTAC to `register` a `search` request with the following filter\n",
+    "    // We tell PgSTAC to `register` a `search` request with the following filter:\n",
     "    \"filter\": {\n",
     "        \"op\": 'and', \n",
     "        \"args\": [\n",
@@ -2451,16 +2465,16 @@
     "                \"args\": [{\"property\": \"collection\"}, [collection_id]]\n",
     "            },\n",
     "            {\n",
-    "            // Item's datetime property HAS to intersect with the start/enddate\n",
+    "            // Item's datetime property HAS to intersect with the start/end date\n",
     "                \"op\": \"t_intersects\", \n",
     "                \"args\": [\n",
     "                    {\"property\": \"datetime\"}, [startdate, enddate]\n",
     "                ]\n",
     "            },\n",
     "            // titiler-pgstac accept some additional metadata\n",
     "            // https://stac-utils.github.io/titiler-pgstac/advanced/metadata/\n",
-    "            // One is really useful: `bounds`. When creating a mosaic, the tiler will have no idea \n",
-    "            // where the items will be prior trying to create each tile. To avoid trying to request \n",
+    "            // One is useful: `bounds`. When creating a mosaic, the tiler will have no idea \n",
+    "            // where the items will be before trying to create each tile. To avoid trying to request \n",
     "            // tiles where we know we don't have any items, we can add the collection's extent to the \n",
     "            // mosaic metadata. The tiler service will then return the bounds in the tilejson document for the \n",
     "            // client application.\n",
@@ -2475,7 +2489,7 @@
     "\n",
     "API Response:\n",
     "\n",
-    "The raster service will return a `searchid` hash (also called `mosaic id`), wich we can use to construct a tile URL."
+    "The raster service will return a `searchid` hash (also called `mosaic id`), which we can use to construct a tile URL."
    ]
   },
   {
@@ -2601,14 +2615,6 @@
     "tiles.add_to(m)\n",
     "m"
    ]
-  },
-  {
-   "cell_type": "code",
-   "execution_count": null,
-   "id": "31d3649e",
-   "metadata": {},
-   "outputs": [],
-   "source": []
   }
  ],
  "metadata": {