geoahsi 1.2.5

Hyperspectral spectral analysis, expert-rule computation, and process visualization (USGS Tetracorder algorithm)

geoahsi

Hyperspectral spectral analysis · expert-rule computation · process visualization — an end-to-end engine that turns spectra into mineral identification with a fully transparent, publication-ready rendering of every expert-rule decision. Based on the USGS Tetracorder algorithm, it ships with a built-in 77-mineral expert rule library and the USGS splib06b spectral library, classifies hyperspectral imagery or individual spectra per pixel, and renders each expert-rule gate as a Nature-style PDF.

Spectral analysis ─► Expert-rule computation ─► Process visualization
continuum removal + least-squares fit   3-layer rule gating + weighted verdict   per-feature curves + every gate PASS/FAIL

Core features

1. Spectral analysis

• Continuum removal: normalize reference and unknown spectra by feature endpoints
• Closed-form 2×2 least-squares fit: each feature yields k0 / k1 / R² / absorption depth (with det==0 singularity guard — no iterations)
• Reference resampling: Gaussian resampling of USGS splib06b to target band FWHM, aligned band-by-band with the input
• Two entry points: full-scene cube (per-pixel parallel) and single spectrum

2. Expert-rule computation

Built-in 77 mineral expert rules (pure end-members + mixtures); each rule passes through three gating layers:

1. Continuum constraints (left/mean/right/ratio min/max — 8 checks)
2. Diagnostic + non-feature exclusion (not_absolute / not_relative: absorptions that must be absent)
3. Weighted constraints (min_weighted_fit / min·max_weighted_depth / min_fit_depth_product)

• Optional depth-ratio constraint (max_depth_ratio_feat1_over_feat0)
• Per-pixel outputs: best mineral, weighted fit, absorption depth, fit×depth confidence (fd), muscovite 2.2 µm absorption center
• Match a single mineral by key — returns accept/fit/fd plus which gate rejected it

3. Process visualization (Nature-style PDF, requires geoahsi[viz])

• Top-N PDF: one page per candidate mineral — all diagnostic/non-feature continuum-removed curves + k0/k1/R²/depth + constraint ranges + not-feature reference keys
• Single-mineral match PDF: per-feature curves + every expert-rule gate's PASS/FAIL verdict + final fit/depth/fd + ACCEPT/REJECT — shows exactly why a match is accepted or rejected
• Okabe-Ito colorblind-safe palette, adaptive y-axes, panel letters, shared legend, fixed GridSpec layout

Installation

pip install geoahsi                  # core: spectral analysis + expert rules + GeoTIFF
pip install 'geoahsi[viz]'           # + PDF process visualization
conda install -c conda-forge gdal    # GDAL for GeoTIFF output (install via conda)

Input: supports EMIT L2A NetCDF (auto-removes water-vapor bad bands, 285 → 244). The library bundles every resource it needs — spectral library and rule library are built-in, no external data required.

Command line:

geoahsi -i EMIT_xxx.nc -o output/                 # full scene → 3 GeoTIFFs
geoahsi -i EMIT_xxx.nc -o output/ --raw            # also emit mus_center + fd

Quick start

Full scene: spectral analysis + expert rules → GeoTIFF

from geoahsi import MicaEngine

engine = MicaEngine()                                    # zero-arg, all resources built-in
spectrum, lon, lat, w, bp = engine.load_emit("EMIT_xxx.nc")   # bad bands removed
orth, color, mus = engine.spectrum_analysis(
    spectrum, w, bp, n_workers=8,
)
engine.write_tiff("result", lon, lat, orth, color, mus)
# → result_mapping_orth.tiff        mineral classification
# → result_color_enhanced_orth.tiff depth-modulated color
# → result_mus_orth.tiff            muscovite thematic map

Single spectrum: Top-N identification + process PDF

pixel = spectrum[row, col, :]                           # already valid bands
top = engine.classify_spectrum(pixel, w, bp, top_n=10,
                               pdf_path="topN_features.pdf")
# [{"name": "calcite.8+montmorilloniteNa.2_mix_intimate", "fit": 0.9457, "fd": 0.0659}, ...]

Single spectrum vs. a single reference spectrum

r = engine.match_reference(pixel, w, bp,
                           mineral_key="calcite",        # a key from rf.json
                           pdf_path="match.pdf")          # optional process PDF
# {"name": "calcite", "fit": 0.4007, "fd": 0.0194, "accept": False}
# PDF shows: weighted: fit>=0.64 → FAIL 0.4007 (rejection reason at a glance)

Main API

Method	Description
MicaEngine.load_emit(path)	Load imagery + bad-band removal → spectrum, lon, lat, w, bp
MicaEngine.spectrum_analysis(spectrum, w, bp, n_workers, raw)	Full-scene spectral analysis + expert rules + rendering
MicaEngine.classify_spectrum(pixel, w, bp, top_n, pdf_path)	Single-spectrum Top-N identification (+ optional PDF)
MicaEngine.match_reference(pixel, w, bp, mineral_key, pdf_path)	Single spectrum vs. a specified reference (+ optional process PDF)
MicaEngine.write_tiff(prefix, lon, lat, orth, color, mus)	Write 3 GeoTIFFs (UTM projection)
MicaClassifier.classify / classify_spectrum / get_resample	Low-level three-component API (custom pipelines)
ResultRenderer.render / write_tiff / plot_features_pdf / plot_rule_match_pdf	Rendering + GeoTIFF + PDF

Built-in resources & algorithm

• USGS splib06b spectral library (21 MB), 77-mineral expert rule library rf.json, mineral RGB color table, muscovite 10-step color table — all built-in; MicaEngine() works with zero arguments
• Algorithm: continuum removal + closed-form 2×2 least-squares (R² + absorption depth) → 3-layer rule gating → weighted verdict; parabolic fit for the muscovite 2.2 µm absorption center
• Parallelism: mineral-level multiprocessing + read-only memmap sharing

Performance

Measured on a 1280×1242 EMIT scene: ~75–95 s with 8 workers, ~99.8% pixels classified; output is bit-identical to the reference Tetracorder implementation.

Acknowledgements

• USGS Tetracorder algorithm and the splib06b spectral library
• NASA EMIT hyperspectral imagery

License

MIT License (see LICENSE).