From 18c8081188852e112a88ebcd3783d9639713be92 Mon Sep 17 00:00:00 2001 From: Mark Piper Date: Fri, 20 Sep 2024 14:16:20 -0600 Subject: [PATCH] Make a landing page for the examples (#30) * Linkify the list of examples * Add a landing page for the examples * Update text descriptions in notebooks * Make pretty * Link to rasterio license --- examples/README-bmi-geotiff.ipynb | 48 ++++++++++++ examples/README.md | 14 ++-- examples/bmi-geotiff.ipynb | 126 +++++++++++++----------------- examples/geotiff.ipynb | 64 +++++---------- 4 files changed, 129 insertions(+), 123 deletions(-) create mode 100644 examples/README-bmi-geotiff.ipynb diff --git a/examples/README-bmi-geotiff.ipynb b/examples/README-bmi-geotiff.ipynb new file mode 100644 index 0000000..2a3afa4 --- /dev/null +++ b/examples/README-bmi-geotiff.ipynb @@ -0,0 +1,48 @@ +{ + "cells": [ + { + "cell_type": "markdown", + "id": "0", + "metadata": {}, + "source": [ + "# Examples: bmi-geotiff" + ] + }, + { + "cell_type": "markdown", + "id": "1", + "metadata": {}, + "source": [ + "Here are a few examples of using the CSDMS GeoTiff data component,\n", + "*bmi-geotiff*.\n", + "\n", + "* [geotiff.ipynb](./geotiff.ipynb) and [bmi-geotiff.ipynb](./bmi-geotiff.ipynb): These Jupyter Notebooks show how to call the GeoTiff data component through its API and its BMI, respectively.\n", + "* [example-pan.py](./example-pan.py): An example Python script showing how to load and display a panchromatic image.\n", + "* [example-rgb.py](./example-rgb.py): An example Python script showing how to load and display a three-band image. The saved output is in [example-rgb.png](./example-rgb.png).\n", + "* [RGB.byte.tif](./RGB.byte.tif): A test GeoTIFF file from the [rasterio](https://github.com/rasterio/rasterio) project, used under their [license](https://github.com/rasterio/rasterio/blob/main/LICENSE.txt).\n", + "* [config.yaml](./config.yaml): A sample configuration file used to pass parameters to the GeoTiff data component." + ] + } + ], + "metadata": { + "kernelspec": { + "display_name": "CSDMS", + "language": "python", + "name": "csdms" + }, + "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.11.7" + } + }, + "nbformat": 4, + "nbformat_minor": 5 +} diff --git a/examples/README.md b/examples/README.md index f2dfbc9..a47914a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -1,12 +1,10 @@ -# Examples +# Examples: bmi-geotiff Here are a few examples of using the CSDMS GeoTiff data component, *bmi-geotiff*. -* `geotiff.ipynb` and `bmi-geotiff.ipynb`: These Jupyter Notebooks show - how to call the GeoTiff data component through its API and its BMI, respectively. -* `example-pan.py`: An example Python script showing how to load and display a panchromatic image. -* `example-rgb.py`: An example Python script showing how to load and display a three-band image. -* `example-rgb.png`: The saved output from `example-rgb.py`. -* `RGB.byte.tif`: A test GeoTIFF file [borrowed](https://github.com/rasterio/rasterio/blob/master/tests/data/RGB.byte.tif) from the [rasterio](https://github.com/rasterio/rasterio) project. -* `config.yaml`: A sample configuration file used to pass parameters to the GeoTiff data component. +* [geotiff.ipynb](./geotiff.ipynb) and [bmi-geotiff.ipynb](./bmi-geotiff.ipynb): These Jupyter Notebooks show how to call the GeoTiff data component through its API and its BMI, respectively. +* [example-pan.py](./example-pan.py): An example Python script showing how to load and display a panchromatic image. +* [example-rgb.py](./example-rgb.py): An example Python script showing how to load and display a three-band image. The saved output is in [example-rgb.png](./example-rgb.png). +* [RGB.byte.tif](./RGB.byte.tif): A test GeoTIFF file from the [rasterio](https://github.com/rasterio/rasterio) project, used under their [license](https://github.com/rasterio/rasterio/blob/main/LICENSE.txt). +* [config.yaml](./config.yaml): A sample configuration file used to pass parameters to the GeoTiff data component. diff --git a/examples/bmi-geotiff.ipynb b/examples/bmi-geotiff.ipynb index a19a6ea..d876cab 100644 --- a/examples/bmi-geotiff.ipynb +++ b/examples/bmi-geotiff.ipynb @@ -5,7 +5,7 @@ "id": "0", "metadata": {}, "source": [ - "# Read GeoTIFF data through a BMI" + "# Read GeoTIFF data with the GeoTiff data component BMI" ] }, { @@ -14,7 +14,7 @@ "metadata": {}, "source": [ "This notebook describes how to open and read data from GeoTIFF files\n", - "using a [Basic Model Interface](https://bmi.readthedocs.io/) (BMI) through the `BmiGeoTiff` class included in the `bmi-geotiff` package." + "using the [Basic Model Interface](https://bmi.readthedocs.io/) (BMI) provided in the GeoTiff data component." ] }, { @@ -29,22 +29,6 @@ "cell_type": "markdown", "id": "3", "metadata": {}, - "source": [ - "To ensure all dependencies are met, set up a conda environment using the environment file found in the root directory of this repository:\n", - "```\n", - "conda env create --file environment.yml\n", - "```\n", - "\n", - "Then install the `bmi-geotiff` package:\n", - "```\n", - "pip install -e .\n", - "```" - ] - }, - { - "cell_type": "markdown", - "id": "4", - "metadata": {}, "source": [ "Import a set of libraries for later use:" ] @@ -52,7 +36,7 @@ { "cell_type": "code", "execution_count": null, - "id": "5", + "id": "4", "metadata": {}, "outputs": [], "source": [ @@ -62,7 +46,7 @@ }, { "cell_type": "markdown", - "id": "6", + "id": "5", "metadata": {}, "source": [ "## Open a file" @@ -70,7 +54,7 @@ }, { "cell_type": "markdown", - "id": "7", + "id": "6", "metadata": {}, "source": [ "Import the `BmiGeoTiff` class from the `bmi-geotiff` package:" @@ -79,7 +63,7 @@ { "cell_type": "code", "execution_count": null, - "id": "8", + "id": "7", "metadata": {}, "outputs": [], "source": [ @@ -88,7 +72,7 @@ }, { "cell_type": "markdown", - "id": "9", + "id": "8", "metadata": {}, "source": [ "Create an instance of this class." @@ -97,7 +81,7 @@ { "cell_type": "code", "execution_count": null, - "id": "10", + "id": "9", "metadata": {}, "outputs": [], "source": [ @@ -106,7 +90,7 @@ }, { "cell_type": "markdown", - "id": "11", + "id": "10", "metadata": {}, "source": [ "Calling `help` on the instance displays all the BMI methods that are available." @@ -115,7 +99,7 @@ { "cell_type": "code", "execution_count": null, - "id": "12", + "id": "11", "metadata": {}, "outputs": [], "source": [ @@ -124,7 +108,7 @@ }, { "cell_type": "markdown", - "id": "13", + "id": "12", "metadata": {}, "source": [ "The first step in using a BMI is calling the `initialize` method.\n", @@ -136,7 +120,7 @@ { "cell_type": "code", "execution_count": null, - "id": "14", + "id": "13", "metadata": {}, "outputs": [], "source": [ @@ -146,7 +130,7 @@ { "cell_type": "code", "execution_count": null, - "id": "15", + "id": "14", "metadata": {}, "outputs": [], "source": [ @@ -155,7 +139,7 @@ }, { "cell_type": "markdown", - "id": "16", + "id": "15", "metadata": {}, "source": [ "In this case, the configuration file simply lists the path to a GeoTIFF file\n", @@ -167,7 +151,7 @@ { "cell_type": "code", "execution_count": null, - "id": "17", + "id": "16", "metadata": {}, "outputs": [], "source": [ @@ -176,7 +160,7 @@ }, { "cell_type": "markdown", - "id": "18", + "id": "17", "metadata": {}, "source": [ "The GeoTIFF file listed in the configuration file has now been opened,\n", @@ -185,7 +169,7 @@ }, { "cell_type": "markdown", - "id": "19", + "id": "18", "metadata": {}, "source": [ "## Access data through the BMI" @@ -193,7 +177,7 @@ }, { "cell_type": "markdown", - "id": "20", + "id": "19", "metadata": {}, "source": [ "Now that we've opened the GeoTIFF file, let's access the data and metadata it contains through the BMI.\n", @@ -206,7 +190,7 @@ { "cell_type": "code", "execution_count": null, - "id": "21", + "id": "20", "metadata": {}, "outputs": [], "source": [ @@ -215,7 +199,7 @@ }, { "cell_type": "markdown", - "id": "22", + "id": "21", "metadata": {}, "source": [ "The (long) names used for these variables are instances of [CSDMS Standard Names](https://csdms.colorado.edu/wiki/CSDMS_Standard_Names).\n", @@ -225,7 +209,7 @@ }, { "cell_type": "markdown", - "id": "23", + "id": "22", "metadata": {}, "source": [ "Find the data type of the raster." @@ -234,7 +218,7 @@ { "cell_type": "code", "execution_count": null, - "id": "24", + "id": "23", "metadata": {}, "outputs": [], "source": [ @@ -244,7 +228,7 @@ }, { "cell_type": "markdown", - "id": "25", + "id": "24", "metadata": {}, "source": [ "Within the BMI, functions that describe the grids that variables are defined on take an index instead of a variable name.\n", @@ -255,7 +239,7 @@ { "cell_type": "code", "execution_count": null, - "id": "26", + "id": "25", "metadata": {}, "outputs": [], "source": [ @@ -265,7 +249,7 @@ }, { "cell_type": "markdown", - "id": "27", + "id": "26", "metadata": {}, "source": [ "Then find the total size of the raster data." @@ -274,7 +258,7 @@ { "cell_type": "code", "execution_count": null, - "id": "28", + "id": "27", "metadata": {}, "outputs": [], "source": [ @@ -284,7 +268,7 @@ }, { "cell_type": "markdown", - "id": "29", + "id": "28", "metadata": {}, "source": [ "Next, get the raster data values.\n", @@ -300,7 +284,7 @@ { "cell_type": "code", "execution_count": null, - "id": "30", + "id": "29", "metadata": {}, "outputs": [], "source": [ @@ -310,7 +294,7 @@ }, { "cell_type": "markdown", - "id": "31", + "id": "30", "metadata": {}, "source": [ "Get the data." @@ -319,7 +303,7 @@ { "cell_type": "code", "execution_count": null, - "id": "32", + "id": "31", "metadata": {}, "outputs": [], "source": [ @@ -328,7 +312,7 @@ }, { "cell_type": "markdown", - "id": "33", + "id": "32", "metadata": {}, "source": [ "Note that the array is one-dimensional." @@ -337,7 +321,7 @@ { "cell_type": "code", "execution_count": null, - "id": "34", + "id": "33", "metadata": {}, "outputs": [], "source": [ @@ -346,7 +330,7 @@ }, { "cell_type": "markdown", - "id": "35", + "id": "34", "metadata": {}, "source": [ "### Reshape the data" @@ -354,7 +338,7 @@ }, { "cell_type": "markdown", - "id": "36", + "id": "35", "metadata": {}, "source": [ "Like all BMI arrays, the raster values returned from the BMI `get_value` function are flattened.\n", @@ -363,7 +347,7 @@ }, { "cell_type": "markdown", - "id": "37", + "id": "36", "metadata": {}, "source": [ "First, determine the dimensionality of the raster variable." @@ -372,7 +356,7 @@ { "cell_type": "code", "execution_count": null, - "id": "38", + "id": "37", "metadata": {}, "outputs": [], "source": [ @@ -382,7 +366,7 @@ }, { "cell_type": "markdown", - "id": "39", + "id": "38", "metadata": {}, "source": [ "Get the dimensions of the raster data, first creating an array to store their values." @@ -391,7 +375,7 @@ { "cell_type": "code", "execution_count": null, - "id": "40", + "id": "39", "metadata": {}, "outputs": [], "source": [ @@ -401,7 +385,7 @@ }, { "cell_type": "markdown", - "id": "41", + "id": "40", "metadata": {}, "source": [ "Reshape the raster data, creating a new array." @@ -410,7 +394,7 @@ { "cell_type": "code", "execution_count": null, - "id": "42", + "id": "41", "metadata": {}, "outputs": [], "source": [ @@ -420,7 +404,7 @@ { "cell_type": "code", "execution_count": null, - "id": "43", + "id": "42", "metadata": {}, "outputs": [], "source": [ @@ -429,7 +413,7 @@ }, { "cell_type": "markdown", - "id": "44", + "id": "43", "metadata": {}, "source": [ "### Get map projection information" @@ -437,7 +421,7 @@ }, { "cell_type": "markdown", - "id": "45", + "id": "44", "metadata": {}, "source": [ "The data in the GeoTIFF file are georeferenced.\n", @@ -458,7 +442,7 @@ { "cell_type": "code", "execution_count": null, - "id": "46", + "id": "45", "metadata": {}, "outputs": [], "source": [ @@ -469,7 +453,7 @@ { "cell_type": "code", "execution_count": null, - "id": "47", + "id": "46", "metadata": {}, "outputs": [], "source": [ @@ -480,7 +464,7 @@ { "cell_type": "code", "execution_count": null, - "id": "48", + "id": "47", "metadata": {}, "outputs": [], "source": [ @@ -491,7 +475,7 @@ { "cell_type": "code", "execution_count": null, - "id": "49", + "id": "48", "metadata": {}, "outputs": [], "source": [ @@ -501,7 +485,7 @@ { "cell_type": "code", "execution_count": null, - "id": "50", + "id": "49", "metadata": {}, "outputs": [], "source": [ @@ -511,7 +495,7 @@ }, { "cell_type": "markdown", - "id": "51", + "id": "50", "metadata": {}, "source": [ "## Visualize" @@ -519,7 +503,7 @@ }, { "cell_type": "markdown", - "id": "52", + "id": "51", "metadata": {}, "source": [ "Let's visualize the raster data as an image, with a little help from rasterio." @@ -528,7 +512,7 @@ { "cell_type": "code", "execution_count": null, - "id": "53", + "id": "52", "metadata": {}, "outputs": [], "source": [ @@ -537,7 +521,7 @@ }, { "cell_type": "markdown", - "id": "54", + "id": "53", "metadata": {}, "source": [ "## Conclusion" @@ -545,7 +529,7 @@ }, { "cell_type": "markdown", - "id": "55", + "id": "54", "metadata": {}, "source": [ "Last, call the BMI `finalize` function." @@ -554,7 +538,7 @@ { "cell_type": "code", "execution_count": null, - "id": "56", + "id": "55", "metadata": {}, "outputs": [], "source": [ @@ -563,7 +547,7 @@ }, { "cell_type": "markdown", - "id": "57", + "id": "56", "metadata": {}, "source": [ "This demonstration of the BMI took a lot of code to reproduce a simple result.\n", diff --git a/examples/geotiff.ipynb b/examples/geotiff.ipynb index e1bc82f..656bc54 100644 --- a/examples/geotiff.ipynb +++ b/examples/geotiff.ipynb @@ -5,7 +5,7 @@ "id": "0", "metadata": {}, "source": [ - "# Read GeoTIFF files with the `GeoTiff` class" + "# Read GeoTIFF files with the GeoTiff data component" ] }, { @@ -14,44 +14,20 @@ "metadata": {}, "source": [ "This notebook describes how to open a GeoTIFF file\n", - "with the `GeoTiff` class included in the `bmi-geotiff` package." + "with the GeoTiff data component." ] }, { "cell_type": "markdown", "id": "2", "metadata": {}, - "source": [ - "## Setup" - ] - }, - { - "cell_type": "markdown", - "id": "3", - "metadata": {}, - "source": [ - "To ensure all dependencies are met, set up a conda environment using the environment file found in the root directory of this repository:\n", - "```\n", - "conda env create --file environment.yml\n", - "```\n", - "\n", - "Then install the `bmi-geotiff` package:\n", - "```\n", - "pip install -e .\n", - "```" - ] - }, - { - "cell_type": "markdown", - "id": "4", - "metadata": {}, "source": [ "## Open a file" ] }, { "cell_type": "markdown", - "id": "5", + "id": "3", "metadata": {}, "source": [ "Import the `GeoTiff` class from the `bmi-geotiff` package:" @@ -60,7 +36,7 @@ { "cell_type": "code", "execution_count": null, - "id": "6", + "id": "4", "metadata": {}, "outputs": [], "source": [ @@ -69,7 +45,7 @@ }, { "cell_type": "markdown", - "id": "7", + "id": "5", "metadata": {}, "source": [ "`GeoTiff` uses the open source [xarray](https://xarray.pydata.org), [rioxarray](https://corteva.github.io/rioxarray/stable/), and [rasterio](https://rasterio.readthedocs.io) packages to open, read, and store data and metadata from GeoTIFF files." @@ -77,7 +53,7 @@ }, { "cell_type": "markdown", - "id": "8", + "id": "6", "metadata": {}, "source": [ "Create an instance of `GeoTiff`:" @@ -86,7 +62,7 @@ { "cell_type": "code", "execution_count": null, - "id": "9", + "id": "7", "metadata": {}, "outputs": [], "source": [ @@ -95,7 +71,7 @@ }, { "cell_type": "markdown", - "id": "10", + "id": "8", "metadata": {}, "source": [ "The `GeoTiff` class can open local or remote files.\n", @@ -109,7 +85,7 @@ { "cell_type": "code", "execution_count": null, - "id": "11", + "id": "9", "metadata": {}, "outputs": [], "source": [ @@ -119,7 +95,7 @@ }, { "cell_type": "markdown", - "id": "12", + "id": "10", "metadata": {}, "source": [ "Note that a file can also be opened on instantiation, eliminating the call to `open`." @@ -127,7 +103,7 @@ }, { "cell_type": "markdown", - "id": "13", + "id": "11", "metadata": {}, "source": [ "The data (and metadata) from the file are loaded into an `xarray` DataArray, which can be accessed through the `da` property." @@ -136,7 +112,7 @@ { "cell_type": "code", "execution_count": null, - "id": "14", + "id": "12", "metadata": {}, "outputs": [], "source": [ @@ -145,7 +121,7 @@ }, { "cell_type": "markdown", - "id": "15", + "id": "13", "metadata": {}, "source": [ "Coordinate reference system information is stored in the `spatial_ref` non-dimensional coordinate:" @@ -154,7 +130,7 @@ { "cell_type": "code", "execution_count": null, - "id": "16", + "id": "14", "metadata": {}, "outputs": [], "source": [ @@ -163,7 +139,7 @@ }, { "cell_type": "markdown", - "id": "17", + "id": "15", "metadata": {}, "source": [ "## Visualize" @@ -171,7 +147,7 @@ }, { "cell_type": "markdown", - "id": "18", + "id": "16", "metadata": {}, "source": [ "Let's visualize the data read from the file.\n", @@ -181,7 +157,7 @@ { "cell_type": "code", "execution_count": null, - "id": "19", + "id": "17", "metadata": {}, "outputs": [], "source": [ @@ -192,7 +168,7 @@ { "cell_type": "code", "execution_count": null, - "id": "20", + "id": "18", "metadata": {}, "outputs": [], "source": [ @@ -203,7 +179,7 @@ }, { "cell_type": "markdown", - "id": "21", + "id": "19", "metadata": {}, "source": [ "## Conclusion" @@ -211,7 +187,7 @@ }, { "cell_type": "markdown", - "id": "22", + "id": "20", "metadata": {}, "source": [ "The `GeoTiff` class does little more than wrap the existing functionality of xarray, rioxarray, and rasterio.\n",