Add sample data for Manaus, Brazil (#49)

The scene shows the merger of the black Negro river and the brown
Amazonas river. Use it on the homepage and the README.

README.md

@@ -25,29 +25,33 @@ manipulation, processing, and visualization.
 
 ## Example
 
-Here's a quick example of loading this [Landsat 8 scene from the Brumadinho
-tailings dam disaster in Brazil](https://doi.org/10.6084/m9.figshare.21665630.v1):
+Here's a quick example of loading this
+[Landsat 9 scene from the city of Manaus, Brazil](https://doi.org/10.6084/m9.figshare.24167235.v1),
+which is where the Amazonas and Negro river merge:
 
 ```python
 import xlandsat as xls
+import matplotlib.pyplot as plt
 
-# Download a cropped Landsat 8 scene from the Brumadinho dam disaster
-# (Brazil). The function downloads it and returns the path to the .tar file
-# containing the scene.
-path = xls.datasets.fetch_brumadinho_after()
+# Download a sample Landsat 9 scene in EarthExplorer format
+path_to_scene_file = xls.datasets.fetch_manaus()
 
-# Load the scene directly from the archive (no need to unpack it)
-scene = xls.load_scene(path)
+# Load the data from the file into an xarray.Dataset
+scene = xls.load_scene(path_to_scene_file)
 
-# Make an RGB composite and stretch the contrast
-rgb = xls.composite(scene, rescale_to=[0.03, 0.2])
+# Make an RGB composite as an xarray.DataArray
+rgb = xls.composite(scene, rescale_to=[0.02, 0.2])
 
-# Plot the composite
+# Plot the composite using xarray's plotting machinery
 rgb.plot.imshow()
+
+# Annotate the plot with the rich metadata xlandsat adds to the scene
+plt.title(f"{rgb.attrs['title']}\n{rgb.attrs['long_name']}")
+plt.axis("scaled")
+plt.show()
 ```
 
-<img src="https://raw.githubusercontent.com/compgeolab/xlandsat/main/doc/_static/readme-example.jpg"
-     alt="RGB map showing the flooded plain after the dam collapse as light brown" width="100%">
+<img src="https://raw.githubusercontent.com/compgeolab/xlandsat/main/doc/_static/readme-example.jpg" alt="RGB image showing the city on the left and the black waters of the Negro river merging with the brown waters of the Amazonas river" width="100%">
 
 ## Project goals
 
@@ -56,8 +60,10 @@ rgb.plot.imshow()
   user and xarray.
 
 Our goal is **not** to provide a solution for large-scale data processing.
-Instead, our target is smaller scale analysis done on individual computers. For
-cloud-based data processing, see the [Pangeo Project](https://pangeo.io).
+Instead, our target is smaller scale analysis done on individual computers.
+
+* For cloud-based data processing, see the [Pangeo Project](https://pangeo.io).
+* For other satellites and more powerful features, use [Satpy](https://github.com/pytroll/satpy).
 
 ## Project status
 

doc/api/index.rst

@@ -42,5 +42,6 @@ Sample datasets
     datasets.fetch_brumadinho_before
     datasets.fetch_liverpool
     datasets.fetch_liverpool_panchromatic
+    datasets.fetch_manaus
     datasets.fetch_momotombo
     datasets.fetch_roraima

doc/index.rst

@@ -30,21 +30,25 @@ Here's a quick example:
 .. jupyter-execute::
 
     import xlandsat as xls
+    import matplotlib.pyplot as plt
 
-    # Download a cropped Landsat 8 scene from the Brumadinho dam disaster
-    # (Brazil). The function downloads it and returns the path to the .tar file
-    # containing the scene.
-    path = xls.datasets.fetch_brumadinho_after()
+    # Download a sample Landsat 9 scene in EarthExplorer format
+    path_to_scene_file = xls.datasets.fetch_manaus()
 
-    # Load the scene directly from the archive (no need to unpack it)
-    scene = xls.load_scene(path)
+    # Load the data from the file into an xarray.Dataset
+    scene = xls.load_scene(path_to_scene_file)
 
-    # Make an RGB composite and stretch the contrast
-    rgb = xls.composite(scene, rescale_to=[0.03, 0.2])
+    # Make an RGB composite as an xarray.DataArray
+    rgb = xls.composite(scene, rescale_to=[0.02, 0.2])
 
-    # Plot the composite
+    # Plot the composite using xarray's plotting machinery
     rgb.plot.imshow()
 
+    # Annotate the plot with the rich metadata xlandsat adds to the scene
+    plt.title(f"{rgb.attrs['title']}\n{rgb.attrs['long_name']}")
+    plt.axis("scaled")
+    plt.show()
+
 
 ----
 
@@ -130,10 +134,12 @@ Here's a quick example:
 .. admonition:: Looking for large-scale cloud-based processing?
     :class: seealso
 
-    Our goal is not to provide a solution for large-scale data processing. The
-    target is smaller scale analysis done on individual computers (which is
-    probably the main way EarthExplorer is used). For cloud-based data
-    processing, see the `Pangeo Project <https://pangeo.io/>`__.
+    Our goal is **not** to provide a solution for large-scale data processing.
+    Our target is smaller scale analysis done on individual computers (which is
+    probably the main way EarthExplorer is used).
+
+    * For cloud-based data processing, see the `Pangeo Project <https://pangeo.io/>`__.
+    * For other satellites and more powerful features, use `Satpy <https://github.com/pytroll/satpy>`__.
 
 
 .. toctree::

xlandsat/datasets.py

@@ -28,6 +28,8 @@
         "LC08_L2SP_017051_20151205_20200908_02_T1-cropped.tar.gz": "md5:8cc2e4c15e65940a7152fc1c8b412aa9",
         # Roraima
         "LC08_L2SP_232056_20151004_20200908_02_T1-cropped.tar.gz": "md5:f236a8b024aa4a4c62bee294d3bd737f",
+        # Manaus
+        "LC09_L2SP_231062_20230723_20230802_02_T1-cropped.tar.gz": "md5:ffe2003e665dc7a1a3155011f700a61d",
     },
 )
 
@@ -250,3 +252,36 @@ def fetch_roraima(untar=False):
         The path to the downloaded `.tar` file that contains the scene.
     """
     return _fetch("LC08_L2SP_232056_20151004_20200908_02_T1-cropped.tar.gz", untar)
+
+
+def fetch_manaus(untar=False):
+    """
+    Download a sample scene from Manaus, Brazil
+
+    Manaus is located in the Brazilian Amazon. The scene shows a part of the
+    city and the meeting of the Amazon and Negro rivers.
+
+    This is a cropped version of a Landsat 9 scene from 2023/07/23, during
+    the annual Amazon river floods.
+
+    The scene was downloaded from `USGS Earth Explorer
+    <https://earthexplorer.usgs.gov/>`__. Original data are in the public
+    domain and are redistributed here in accordance with the `Landsat Data
+    Distribution Policy
+    <https://www.usgs.gov/media/files/landsat-data-distribution-policy>`__.
+
+    Source: https://doi.org/10.6084/m9.figshare.24167235.v1
+    (`CC0 <https://creativecommons.org/publicdomain/zero/1.0/>`__)
+
+    Parameters
+    ----------
+    untar : bool
+        If True, unpack the tar archive after downloading and return a path to
+        the folder containing the unpacked files instead. Default is False.
+
+    Returns
+    -------
+    path : str
+        The path to the downloaded `.tar` file that contains the scene.
+    """
+    return _fetch("LC09_L2SP_231062_20230723_20230802_02_T1-cropped.tar.gz", untar)

xlandsat/tests/test_datasets.py

@@ -13,6 +13,7 @@
     fetch_brumadinho_before,
     fetch_liverpool,
     fetch_liverpool_panchromatic,
+    fetch_manaus,
     fetch_momotombo,
     fetch_roraima,
 )
@@ -26,6 +27,7 @@ def test_fetching_functions(untar):
         fetch_brumadinho_before,
         fetch_liverpool,
         fetch_liverpool_panchromatic,
+        fetch_manaus,
         fetch_momotombo,
         fetch_roraima,
     ]