hsdar-py: Modern Hyperspectral Data Analysis for Vegetation Stress

Author: Abdallah Abdelmajeed, Poznan University of Life Sciences
ORCID: 0000-0002-3662-1824
License: GPL-3.0-or-later | Version: 1.0.0

---

Overview

hsdar-py is the Python implementation of the modernized hsdarModern package for hyperspectral data analysis in vegetation science. It provides clean-room implementations of radiative transfer models (PROSPECT, PROSAIL, SCOPE) and spectral index calculations following FAIR data principles.

Key Features

• PROSPECT: Leaf-level optical properties simulation
• PROSAIL: Canopy reflectance modeling with 2-stream approximation
• SCOPE: Full soil-canopy-atmosphere coupled model with fluorescence
• Spectral Indices: NDVI, NDWI, NDRE, SIF, and 20+ vegetation indices
• Data Formats: ENVI, GeoTIFF, NetCDF, HDF5, and image files
• Modern Architecture: Python 3.9+ compatible, type-hinted

---

Installation

Standard (PyPI)

pip install hsdar-py

From Source

git clone https://github.com/abdallah-abdelmajeed/hsdar-py.git
cd hsdar-py
pip install -e .

With Plotting Support

pip install hsdar-py[plotting]

Conda (via conda-forge)

conda install -c conda-forge hsdar-py

---

Quick Start Examples

Example 1: Leaf-Level PROSPECT Simulation

import numpy as np
from hsdar_py import prospect

# Simulate leaf reflectance for typical vegetation
wavelengths = np.arange(400, 901, 5)  # 400-900 nm at 5nm resolution
reflectance, transmittance = prospect(
    N=1.5,       # Leaf structure parameter
    Cab=45.0,    # Chlorophyll content (μg/cm²)
    Car=15.0,    # Carotenoids (μg/cm²)
    Cw=0.015,    # Water content (cm)
    Cm=0.01      # Dry matter (g/cm²)
)

print(f"Spectral range: {wavelengths[0]}-{wavelengths[-1]} nm")
print(f"Bands: {len(wavelengths)}")

Example 2: Canopy PROSAIL Modeling

from hsdar_py import sail_canopy_reflectance
import numpy as np

wl = np.arange(400, 901, 5)
for lai in [1.0, 3.0, 5.0]:
    refl = sail_canopy_reflectance(wl, LAI=lai, rsoil=0.2)
    print(f"LAI={lai}: Mean reflectance = {np.mean(refl):.3f}")

Example 3: SCOPE with Fluorescence

from hsdar_py import scope

# Simulate stressed vs healthy vegetation
wl = np.arange(400, 2501, 1)

healthy = scope(N=1.5, Cab=45, LAI=3.0, vmax=80, Jmax=120)
stressed = scope(N=1.5, Cab=25, LAI=3.0, vmax=60, Jmax=80)

print(f"Healthy SIF 760nm: {healthy['SIF']['SIF_760']:.4f}")
print(f"Stressed SIF 760nm: {stressed['SIF']['SIF_760']:.4f}")
print(f"Healthy GPP: {healthy['GPP']:.4f}")
print(f"Stressed GPP: {stressed['GPP']:.4f}")

Example 4: Real Data from Open Repository

import pandas as pd
from hsdar_py import vegetation_indices

# Load a publicly available spectral library (e.g., USGS)
# url = "https://example.org/vegetation_spectra.csv"
# df = pd.read_csv(url)

# Synthetic example
wl = np.arange(400, 901, 5)
df = pd.DataFrame({
    'wavelength': wl,
    'reflectance': np.where(wl < 700, 0.05, 0.45)
})
vi = vegetation_indices(df)
print(vi.head())

---

FAIR Metadata Implementation

Findable

• DOI: 10.5281/zenodo.XXXXXXX (to be assigned)
• GitHub: https://github.com/abdallah-abdelmajeed/hsdar-py
• ORCID: 0000-0002-3662-1824

Accessible

• Standard protocols: HTTPS, FTP
• Data formats: NetCDF, GeoTIFF, ENVI, CSV
• PyPI: pip install hsdar-py

Interoperable

• Controlled vocabularies: GCMD, CF conventions
• Data types: CF-NetCDF, HDF5
• Formats: Standard spectral data formats

Reusable

• Clear usage license: GPL-3.0
• Detailed provenance: prov.json
• Validation scripts included

---

Testing

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# With coverage
pytest --cov=hsdar_py --cov-report=html

---

References

1. Jacquemoud, S., et al. (2009). PROSAIL simulations. Remote Sensing of Environment.
2. Féret, J.-B., et al. (2008). Combining PROSPECT and SAIL models. JGR.
3. Rautiainen, M., et al. (2015). SCOPE model description. arXiv:1501.02105.

---

Support

• GitHub Issues: https://github.com/abdallah-abdelmajeed/hsdar-py/issues
• Documentation: https://abdallah-abdelmajeed.github.io/hsdar-py/
• Contact: abdallah.abdelmajeed@up.poznan.pl