Overview#

The library#

All functionality in xlandsat is available from the base namespace of the xlandsat package. This means that you can access all of them with a single import:

# xlandsat is usually imported as xls
import xlandsat as xls

Download a sample scene#

As an example, lets download a tar archive of a Landsat 8 scene of the Brumadinho tailings dam disaster that happened in 2019 in Brazil. The archive is available on figshare at https://doi.org/10.6084/m9.figshare.21665630 and includes scenes from before and after the disaster as both the full scene and a cropped version.

We’ll use the functions in xlandsat.datasets to download the scenes from before and after the disaster to our computer. To save space and bandwidth, these are cropped versions of the full Landsat scenes.

path_before = xls.datasets.fetch_brumadinho_before()
path_after = xls.datasets.fetch_brumadinho_after()
print(path_before)
print(path_after)

/home/runner/.cache/pooch/LC08_L2SP_218074_20190114_20200829_02_T1-cropped.tar.gz
/home/runner/.cache/pooch/LC08_L2SP_218074_20190130_20200829_02_T1-cropped.tar.gz

Tip

Running the code above will only download the data once. We use Pooch to handle the downloads and it’s smart enough to check if the file already exists on your computer. See pooch.retrieve for more information.

See also

If you want to use the full scenes instead of the cropped version, use pooch.retrieve to fetch them from the figshare archive https://doi.org/10.6084/m9.figshare.21665630.

Load the scenes#

Now that we have paths to the tar archives of the scenes, we can use xlandsat.load_scene to read the bands and metadata directly from the archives (without unpacking):

before = xls.load_scene(path_before)
before

<xarray.Dataset>
Dimensions:   (easting: 400, northing: 300)
Coordinates:
  * easting   (easting) float64 5.835e+05 5.835e+05 ... 5.954e+05 5.955e+05
  * northing  (northing) float64 -2.232e+06 -2.232e+06 ... -2.223e+06 -2.223e+06
Data variables:
    blue      (northing, easting) float16 0.07288 0.07373 ... 0.06506 0.06653
    green     (northing, easting) float16 0.09851 0.099 ... 0.0835 0.08716
    red       (northing, easting) float16 0.1035 0.1041 ... 0.07959 0.08423
    nir       (northing, easting) float16 0.2803 0.2749 0.3203 ... 0.2118 0.2267
    swir1     (northing, easting) float16 0.2467 0.2474 0.2147 ... 0.172 0.1769
    swir2     (northing, easting) float16 0.1571 0.1571 0.1281 ... 0.1171 0.1206
Attributes: (12/19)
    Conventions:                CF-1.8
    title:                      Landsat 8 scene from 2019-01-14 (path/row=218...
    digital_object_identifier:  https://doi.org/10.5066/P9OGBGM6
    origin:                     Image courtesy of the U.S. Geological Survey
    landsat_product_id:         LC08_L2SP_218074_20190114_20200829_02_T1
    processing_level:           L2SP
    ...                         ...
    ellipsoid:                  WGS84
    date_acquired:              2019-01-14
    scene_center_time:          12:57:13.1804960Z
    wrs_path:                   218
    wrs_row:                    74
    mtl_file:                   GROUP = LANDSAT_METADATA_FILE\n  GROUP = PROD...

And the after scene:

after = xls.load_scene(path_after)
after

<xarray.Dataset>
Dimensions:   (easting: 400, northing: 300)
Coordinates:
  * easting   (easting) float64 5.844e+05 5.844e+05 ... 5.963e+05 5.964e+05
  * northing  (northing) float64 -2.232e+06 -2.232e+06 ... -2.223e+06 -2.223e+06
Data variables:
    blue      (northing, easting) float16 0.0686 0.07043 ... 0.05823 0.0564
    green     (northing, easting) float16 0.1027 0.09839 ... 0.07593 0.07043
    red       (northing, easting) float16 0.09778 0.09778 ... 0.06799 0.06177
    nir       (northing, easting) float16 0.2988 0.2715 0.2881 ... 0.2637 0.251
    swir1     (northing, easting) float16 0.2311 0.2274 0.2316 ... 0.1608 0.142
    swir2     (northing, easting) float16 0.145 0.1442 0.144 ... 0.09961 0.08655
Attributes: (12/19)
    Conventions:                CF-1.8
    title:                      Landsat 8 scene from 2019-01-30 (path/row=218...
    digital_object_identifier:  https://doi.org/10.5066/P9OGBGM6
    origin:                     Image courtesy of the U.S. Geological Survey
    landsat_product_id:         LC08_L2SP_218074_20190130_20200829_02_T1
    processing_level:           L2SP
    ...                         ...
    ellipsoid:                  WGS84
    date_acquired:              2019-01-30
    scene_center_time:          12:57:09.1851220Z
    wrs_path:                   218
    wrs_row:                    74
    mtl_file:                   GROUP = LANDSAT_METADATA_FILE\n  GROUP = PROD...

Did you notice?

If you look carefully at the coordinates for each scene, you may notice that they don’t exactly coincide in area. That’s OK since xarray knows how to take the pixel coordinates into account when doing mathematical operations like calculating indices and differences between scenes.

Plot some reflectance bands#

Now we can use the xarray.DataArray.plot method to make plots of individual bands with matplotlib. A bonus is that xarray uses the metadata that xlandsat.load_scene inserts into the scene to automatically add labels and annotations to the plot.

import matplotlib.pyplot as plt

fig, (ax1, ax2) = plt.subplots(2, 1, figsize=(10, 12))

# Make the pseudocolor plots of the near infrared band
before.nir.plot(ax=ax1)
after.nir.plot(ax=ax2)

# Set the title using metadata from each scene
ax1.set_title(f"Before: {before.attrs['title']}")
ax2.set_title(f"After: {after.attrs['title']}")

# Set the aspect to equal so that pixels are squares, not rectangles
ax1.set_aspect("equal")
ax2.set_aspect("equal")

plt.show()
_images/overview_4_0.png

What now?#

Learn more about what you can do with xlandsat and xarray:

By getting the data into an xarray.Dataset, xlandsat opens the door for a huge range of operations. You now have access to everything that xarray can do: interpolation, reduction, slicing, grouping, saving to cloud-optimized formats, and much more. So go off and do something cool!