Skip to content

API Reference

This page summarizes the public TanagerSpec API. Most users start with TanagerSpec.from_file() and then use the namespaces attached to the loaded scene.

For a map of the src/tanagerspec/ package (contributors), see Source layout.

Package Exports

from tanagerspec import TanagerSpec, IndexCatalog, download_scene, inspect_hdf
  • TanagerSpec loads and manages a Tanager hyperspectral scene.
  • IndexCatalog browses packaged spectral index definitions.
  • download_scene() streams a remote scene to disk.
  • inspect_hdf() prints an HDF5 tree for product inspection.

TanagerSpec

Load: TanagerSpec.from_file()

scene = TanagerSpec.from_file("ortho_sr_scene.h5")

Loads a Tanager-1 HDF5-EOS product and returns a TanagerSpec instance. The instance exposes:

  • dataset: hyperspectral cube with shape (bands, rows, cols).
  • properties: cube metadata, including wavelengths, FWHM, good-band mask, and units.
  • wavelengths: wavelength array in nanometers.
  • good_bands: boolean mask of wavelengths considered valid.
  • masks: loaded quality-mask datasets.
  • product_type: detected product type.
  • grid_info: CRS and affine transform for ortho products, otherwise None.
  • crs: CRS string for ortho products, or None.
  • transform: Rasterio Affine geotransform for ortho products, or None.

Summary: scene.info()

Prints product metadata and plots band status, including originally bad bands and user-dropped wavelength ranges.

scene.info(save_png="band_status.png")

Preprocess: scene.preprocess()

Applies valid-pixel masking and optional surface-reflectance clipping in place.

scene.preprocess(masking=True, clipping=True)

Drop Bands: scene.drop_bands()

Marks wavelength intervals as invalid for downstream plotting and analysis without changing cube shape.

scene.drop_bands([(400, 500), (1000, 1250)])

Denoise: scene.denoise()

Applies PCA reconstruction to reduce noise in the cube.

scene.denoise(n_components=3)

Spectral Library: scene.build_spectral_library()

Builds labeled mean spectra from pixel targets and optional spatial windows for supervised classification workflows.

library_means, df_library = scene.build_spectral_library(
    targets={"vegetation": [(col, row)], "water": [(col, row)]},
    window_size=5,
    export_csv="library.csv",
)
  • targets: dict mapping class name → list of (col, row) pixel coordinates.
  • window_size: side length of the square spatial averaging window (pixels).
  • export_csv: optional path to write the tabular library as CSV.
  • masked_band_value: marker value written into masked-band columns of the training table.
  • Returns (library_means, df_library) — per-class mean spectra and a DataFrame for supervised workflows.

Plotting: scene.plot

scene.plot is a Plotting namespace for visualization.

  • scene.plot.rgb() creates an RGB composite from presets or custom wavelengths.
  • scene.plot.hunt_pixels() opens an interactive map for selecting row/column targets.
  • scene.plot.pixel_spectra() plots spectra for named pixel targets.
  • scene.plot.roi_spectral_variability() plots mean and standard deviation spectra for a local window.
  • scene.plot.bands_correlation() plots the band-to-band correlation matrix.
  • scene.plot.bands_gallery() plots selected band images.
  • scene.plot.bands_histograms() plots per-band histograms.
  • scene.plot.animate_bands() writes a GIF across a wavelength range.
  • scene.plot.analyze_reflectance_band() plots one band and its histogram.

Analysis: scene.analysis

scene.analysis is an Analysis namespace for algorithms and derived products.

  • scene.analysis.compare_bands() compares two wavelengths with summary metrics and maps.
  • scene.analysis.band_range_presets — read-only dict of named wavelength intervals (coastal, blue, green, yellow, orange, red, red_edge, nir, visible) accepted by compare_band_range(preset=…).
  • scene.analysis.compare_band_range() compares all band pairs in a preset or custom wavelength interval.
  • scene.analysis.dim_reduction() runs PCA, ICA, MNF, or supported dimensionality-reduction methods.
  • scene.analysis.clustering() runs clustering and optionally exports a cluster GeoTIFF.
  • scene.analysis.calculate_index() calculates a cataloged spectral index.
  • scene.analysis.index_creator_lab() evaluates custom two-band index formulas.
  • scene.analysis.compare_layers() compares two array outputs (indices, bands, or any 2D layer).
  • scene.analysis.validate_indices() validates all (or a named subset of) packaged index definitions against the current cube and prints a pass/fail report.
  • scene.analysis.classify_scene() applies SAM, random forest, or neural-network classification using spectral-library inputs.

Conversion: scene.convert_to

scene.convert_to is an HDF5Converters namespace for export.

In-memory: scene.convert_to.xarray()

ds = scene.convert_to.xarray(include_secondary_cubes=False)

Returns the current scene as an in-memory xarray.Dataset containing the cube, masks, companion 2D rasters from the source HDF5, and grid information. Set include_secondary_cubes=True to also include other 3D datasets (e.g. surface_reflectance_uncertainty) whose shape matches the main cube.

File export

scene.convert_to.geotiff("scene.tif", include_extras=True)
scene.convert_to.envi_bil("scene_envi", include_extras=False)

GeoTIFF and ENVI exports write the main cube and can optionally write companion 2D datasets (include_extras=True). Ortho products provide CRS and transform metadata for georeferenced output.

Utility Modules

  • tanagerspec.io contains Tanager HDF5 loading and grid metadata extraction.
  • tanagerspec.process contains preprocessing, band dropping, and PCA denoising helpers.
  • tanagerspec.viz contains plotting backends used by scene.plot.
  • tanagerspec.analysis contains band exploration, indices, clustering, dimensionality reduction, and classification.
  • tanagerspec.converters contains GeoTIFF and ENVI export helpers.
  • tanagerspec.utils contains HDF inspection, downloads, RGB extraction, nearest-band lookup, and index catalog utilities.