Exploring Real-World Tanager-1 Data

Welcome to the first lesson in module 2.

In Lessons 2 and 3 of the previous module, we created a synthetic dataset and used it to learn the fundamental principles of HDF5.

In this lesson, we transition to working with real, operational Tanager-1 Science Data.

While the real data files are significantly larger and the hierarchy is more complex, the underlying mechanics remain identical. So, you will use the same workflows you have learned to work with real data.

Let’s begin!

Data Acquisition: Selecting a Scene¶

To analyze real data, we need to retrieve a sample from the Planet Tanager STAC Catalog.

💡 For this lesson, we’ve selected a specific scene and the Basic Surface Reflectance (basic_sr_hdf5) asset so everyone follows the same example. Tanager-1 captures the full spectral fingerprint of the Earth across many domains (Agriculture, Water, Mineralogy, etc.). If you prefer a different theme or location, follow the Open Data STAC tutorial to pick your own scene, then either copy the asset URL into the download cell or download the file to your workspace. The workflow you learn here applies to any Tanager-1 data you choose.

Pilliga, Narrabri Shire Council, New South Wales, 2388, Australia

Navigating Real Tanager-1 Hierarchies¶

As you remember from the previous lesson, if we tried to check f.keys() manually for every folder, it would take forever.

Instead, we will deploy an upgraded version of our Recursive Tree print_structure function.

What’s upgraded:

Interesting! Scroll through the output you just generated. You will see dozens of groups and datasets.

Do not get overwhelmed!

This is a standard HDF-EOS layout. Let’s break down exactly what we found.

The Roots

You will see two main groups within the root of HDF5 file: HDFEOS/ and HDFEOS INFORMATION/.

• HDFEOS/: This is the most extensive group. It contains all the actual scientific datasets (📄).

• HDFEOS INFORMATION/: This largely contains structural metadata.

The Critical Paths

If you look closer at the map, you will find the two main groups that contain the data we most care about:

1. HDFEOS/SWATHS/HYP/Data Fields/: This holds the science data (Reflectance, Cloud Masks, etc.).

2. HDFEOS/SWATHS/HYP/Geolocation Fields/: This holds the location data (Latitude, Longitude, Time).

The Attributes

The map also reveals the attributes (metadata). Remember, attributes are stored as Key-Value pairs.

Example: One of the attributes of the surface_reflectance dataset is named wavelengths (Key), and its value is a list of numbers representing the center wavelengths for each spectral band.

Understanding the Data Fields¶

Here is the breakdown of the HDFEOS/SWATHS/HYP/Data Fields/ group, organized into a single clear table.

Tanager Basic SR Data Fields¶

This helps you decide which datasets you actually need.

Data Extraction¶

Now that we know the paths, we can perform a targeted extraction. We will load two items:

1. The surface reflectance cube — the 3D array (bands × rows × columns)

2. The wavelengths attribute — metadata that tells us which band corresponds to which wavelength

This is not the end — we are going to explore Tanager-1 data deeply and the other assets in the rest of this module.

Visualizing the Data¶

In the previous step, we extracted the full 3D cube and isolated a single 2D layer we named band_image (Band 50) for visualization.

Now, let’s visualize that specific slice.

Bonus: Understanding Image Contrast¶

Did you notice the image may look faint, washed our, or lacking detail? Did you notice there is a single very bright pixel group at the top of the image, while the rest of the scene appears darker and flat?

What is happening? Because Tanager is highly sensitive, it captures a large dynamic range. A single scene can contain incredibly dark features right alongside very bright ones. Some pixels in the scene may have genuinely extreme reflectance values — bright surfaces like clouds, bare soil, or specular highlights can reflect much more light than surrounding vegetation or water. Even a small number of these outlier pixels is enough to pull the displayed maximum far above the typical scene values, compressing most of the landscape into a narrow, indistinguishable band of gray.

Why the image looks low-contrast by default¶

Most visualization tools map data values to grayscale like this:

• the minimum value → black

• the maximum value → white

If your array contains even a few unusually bright (or dark) outliers, the color mapping is forced to span that full range. As a result, the majority of pixels — the ones that actually represent the majority of the landscape — get squeezed into a narrow band of gray. That compression makes the image look flat and hides structure.

How plt.imshow() works?¶

When you call plt.imshow(band_image, cmap="gray"), Matplotlib has to convert your numeric values into screen brightness. It does this in two steps:

1. Normalize (scale) your data to a 0–1 range

2. Map 0 → black and 1 → white using the chosen colormap (here, grayscale)

By default, imshow() chooses the scaling limits from your array:

• the minimum value → black (0)

• the maximum value → white (1)

Figure 1 illustrates this mapping:

If your array contains even a few unusually bright (or dark) outliers, as was the case here, those extreme values become the max (or min).

How we fix it¶

To improve visibility, we usually don’t want to change the scientific values stored in band_image, those reflectance numbers are meaningful and should remain untouched for analysis.

Instead, we need to take control of our visual contrast. In practice, this is done by choosing better display limits plt.imshow():

• vmin = the value we want to appear black

• vmax = the value we want to appear white

Everything between vmin and vmax is stretched across the full grayscale range, and anything outside is clipped.

To choose good vmin and vmax, we first need to understand the distribution of reflectance values in band_image. So, we will plot a histogram and box-plot for the pixel values of the sliced band.

Interpreting the histogram¶

Interesting! The histogram reveals several important patterns, especially the distribution of values spanning roughly 0.0018 → 0.3178. From the histogram, we can see that:

• Most pixels are concentrated in a relatively small range (the tall cluster on the left and the main body of the distribution).

• The distribution is not uniform; it is multi-modal (it has several bumps/peaks). This confirms that the image likely contains multiple land-cover types with different reflectance characteristics.

• There is a long right tail extending toward higher reflectance values. These pixels are relatively rare, but they push the maximum value upward.

While the histogram gives us a strong sense of the overall distribution, the box plot confirms the outlier behavior: the upper whisker reaches into the brighter part of the scene, and the many points above it are outliers. These outliers extend up toward the maximum (~0.32), meaning there are some very bright pixels compared to the rest of the image.

Why this matters for contrast¶

Now we can see why the default image looked faint, as we mentioned imshow() by default maps min → black and max → white. So, in our case the maximum is pulled upward by a small number of very bright outliers. That forces the majority of pixels (the landscape signal) to occupy only a small fraction of the grayscale, making the image look flat and low-contrast.

What we do next¶

Instead of using the absolute minimum and maximum, we will choose vmin and vmax from the main bulk of the distribution, typically using percentiles (e.g., the 2nd and 98th, or the 1st and 99th). This prevents rare outliers from dominating the display scaling and allows most landscape pixels to spread across the full grayscale range.

Next, we’ll compute percentiles and use them for plt.imshow(..., vmin=..., vmax=...), then compare the old plot with the new one.

Notice the difference: the 2–98% stretch dramatically improves contrast. Field boundaries, texture, and subtle land-cover transitions that were hidden or difficult to see in the default view become clearly visible.

Beyond contrast: using vmin/vmax to explore the data¶

So far, we used vmin and vmax to improve the visual contrast of the image. But this same technique is useful for something even more powerful: data exploration.

By deliberately choosing a narrow value range (a “window”), we can make the map behave like a highlight tool:

• Pixels inside the chosen range become visible and detailed.

• Pixels outside the range get clipped to black or white and become less informative.

• This helps us isolate and inspect specific reflectance ranges that may correspond to different surface types.

In other words, this isn’t only about “making the image prettier”, it’s a way to connect the histogram to the geography.

Why this works especially well here (multi-modal histogram)¶

Our histogram is multi-modal, meaning it has several peaks. In remote sensing, this often happens because the scene contains multiple land-cover types, each with its own typical reflectance range (for example: water, vegetation, bare soil, built-up areas, clouds, etc.).

Each “bump” in the histogram is often a mixture of one or more surface classes. By selecting a small window around a peak—and plotting the map using that same window, we can start answering questions like:

• Where are the pixels that belong to this peak located?

• What land features do they represent?

• Does this peak correspond to fields, roads, water, or something else?

Let’s explore the strongest peak¶

Looking at the histogram, the tallest spike contains a huge number of pixels. That makes it a perfect starting point: it likely represents the dominant surface type in the scene.

In this next step, we’ll “zoom in” on that peak by choosing a tight vmin/vmax window (like 0.019 → 0.040) and then plotting:

1. The spatial map using that window

2. The histogram showing exactly which part of the distribution we are viewing

Can you see what happened? By focusing on this narrow reflectance window, we’ve revealed fine spatial detail that was previously buried in very dark gray tones. Features that looked nearly uniform in the default view now separate into distinct textures and boundaries. That’s the real power of histogram-guided visualization: it helps you connect value ranges to real land patterns.

I encourage you to experiment:¶

• Move the window to the next bump in the histogram

• Try a window over the right tail (brighter surfaces)

• Try a window over the dark tail (very low-reflectance features)

Each time you shift the window, ask yourself: Which parts of the scene become clearer now—and what might they represent? This is how you translate histogram peaks into meaningful land features.

🧰 Starting Your Toolkit¶

You just used two pieces of code that you will reach for in every remaining lesson:

1. print_structure — audit any Tanager-1 HDF5 file’s hierarchy and attributes.

2. The loading recipe — open the file, point at a dataset, read its values, and read its attributes (here, the wavelengths).

This is the course’s build-your-own-toolkit assignment. Instead of re-typing these every time, you will package them into reusable functions kept in a single Toolkit cell that grows lesson by lesson, by the end of the course it is your own hyperspectral analysis library.

Below is the skeleton of your first two tools: print_structure and a general loader, load_hdf5. The signatures and docstrings are given, your job is to fill in the bodies using the code you wrote above. Notice the loader is written to generalize that recipe: rather than hard-coding the surface_reflectance cube and the single wavelengths attribute, it loads any dataset at data_path and hands back its data plus all of its properties (attributes) as a dict, so the very same function will later load masks, geometry layers, and Ortho cubes without a rewrite. An optional band= argument lets it lazily read a single 2-D band straight from disk when you don’t need the whole cube.

Your Toolkit also starts with one function we wrote for you: download_tanager_data, the packaged version of the download cell you ran above. You don’t implement this one, just call it at the top of every lesson that needs data. It travels with your Toolkit from the next lesson on.

Provided for you: download_tanager_data¶

You don’t implement this one, it’s the packaged version of the download cell you ran at the top of this lesson. It fetches a scene’s .h5 file (and skips the download when the file is already on disk). Keep it at the top of your Toolkit and call it whenever a lesson needs data.

Summary & Next Steps¶

Congratulations. You have successfully navigated the transition from synthetic training data to Operational Satellite Imagery.

In this lesson, you achieved four critical milestones:

1. Acquisition: You retrieved a massive Tanager-1 dataset from Planet’s Open STAC catalog.

2. Audit: You used recursive mapping to penetrate the complex HDF-EOS hierarchy.

3. Extraction: You identified the key dataset in the file—the Reflectance Cube and its spectral wavelengths.

4. Visualization: You converted raw 3D arrays into a visible map of the Earth’s surface.

…and you started your Toolkit with print_structure and load_tanager_hdf5.

But we ignored something important.

When you looked at the STAC Catalog, you saw a confusing list of other files: ortho_reflectance, basic_radiance, geolocation_array.

• Should you use Basic or Ortho?

• Do you need Radiance or Reflectance?

Next Up: In the next lesson, we will decode the Tanager-1 asset ecosystem. We will learn exactly which file to pick for your specific science goal and how to use the Visual and UDM assets to quality-check your data before you process it.

See you in Lesson 2 of Module 2: The Tanager-1 Asset Ecosystem!