Spyndex

Awesome Spectral Indices in Python - a comprehensive library for computing spectral indices used in remote sensing applications. Spyndex implements over 200 standardized spectral indices from the Awesome Spectral Indices catalogue, providing expression evaluation capabilities compatible with multiple Python object classes including NumPy arrays, Pandas DataFrames, GeoPandas GeoDataFrames, Xarray DataArrays and Datasets, Earth Engine objects, and Planetary Computer assets.

Package Information

• Package Name: spyndex
• Version: 0.7.1
• Author: David Montero Loaiza
• Language: Python
• Installation: pip install spyndex
• Optional Earth Engine support: pip install 'spyndex[ee]'

Core Imports

import spyndex

Common imports for accessing different components:

# Core functions
from spyndex import computeIndex, computeKernel

# Catalogue access
import spyndex.indices
import spyndex.bands
import spyndex.constants

# Plotting and datasets
import spyndex.plot
import spyndex.datasets

Basic Usage

import spyndex
import numpy as np

# Compute a single spectral index with numeric values
ndvi = spyndex.computeIndex(
    index="NDVI",
    params={
        "N": 0.643,  # Near-infrared
        "R": 0.175   # Red
    }
)
print(ndvi)  # Output: 0.5721271393643031

# Compute multiple indices with numpy arrays
nir = np.random.normal(0.67, 0.12, 1000)
red = np.random.normal(0.12, 0.05, 1000)
green = np.random.normal(0.34, 0.07, 1000)

indices = spyndex.computeIndex(
    index=["NDVI", "GNDVI", "SAVI"],
    params={
        "N": nir,
        "R": red,
        "G": green,
        "L": 0.5  # SAVI soil adjustment factor
    }
)
print(indices.shape)  # Output: (3, 1000)

# Access spectral index catalogue
print(spyndex.indices.NDVI.long_name)  # "Normalized Difference Vegetation Index"
print(spyndex.indices.NDVI.formula)    # "((N-R)/(N+R))"
print(spyndex.indices.NDVI.bands)      # ('N', 'R')

# Use constants from the catalogue
l_value = spyndex.constants.L.default  # 1.0

Architecture

Spyndex is built around several key components:

• Spectral Indices Catalogue: Over 200 standardized spectral indices with metadata, formulas, and band requirements
• Expression Evaluation Engine: Dynamic evaluation of index formulas using Python's eval() with overloaded operators
• Multi-Platform Band Definitions: Comprehensive band mappings for Sentinel-2, Landsat, MODIS, and other satellite platforms
• Data Type Compatibility: Seamless integration with NumPy, Pandas, Xarray, Dask, and Earth Engine through overloaded operators
• Visualization Tools: Built-in plotting capabilities for exploring spectral index parameter spaces

Capabilities

Spectral Index Computation

Core functionality for computing single or multiple spectral indices from the standardized catalogue. Supports numeric values, NumPy arrays, Pandas DataFrames, Xarray DataArrays, Dask arrays, and Earth Engine objects.

def computeIndex(
    index: Union[str, List[str]],
    params: Optional[dict] = None,
    online: bool = False,
    returnOrigin: bool = True,
    coordinate: str = "index",
    **kwargs
) -> Any: ...

def computeKernel(
    kernel: str,
    params: Optional[dict] = None,
    **kwargs
) -> Any: ...

Spectral Index Computation

Spectral Indices Catalogue

Interactive access to the complete spectral indices catalogue with metadata, formulas, band requirements, and platform compatibility information. Provides both bulk access and individual index exploration.

class SpectralIndices(Box):
    def __repr__(self) -> str: ...
    def __str__(self) -> str: ...

class SpectralIndex:
    short_name: str
    long_name: str
    bands: tuple
    application_domain: str
    reference: str
    formula: str
    date_of_addition: str
    contributor: str
    platforms: list
    
    def compute(self, params=None, **kwargs) -> Any: ...

Spectral Indices Catalogue

Band and Platform Information

Comprehensive band definitions and platform-specific information for major satellite sensors. Includes wavelength ranges, bandwidths, and cross-platform compatibility mappings.

class Bands(Box):
    def __repr__(self) -> str: ...
    def __str__(self) -> str: ...

class Band:
    short_name: str
    long_name: str
    common_name: str
    min_wavelength: float
    max_wavelength: float
    standard: str
    sentinel2a: PlatformBand
    sentinel2b: PlatformBand
    # ... other platforms

class PlatformBand:
    platform: str
    band: str
    name: str
    wavelength: float
    bandwidth: float

Band and Platform Information

Constants and Parameters

Standardized constants used in spectral index calculations with default values and descriptions. Provides consistent parameter values across different applications and research contexts.

class Constants(Box):
    def __repr__(self) -> str: ...
    def __str__(self) -> str: ...

class Constant:
    description: str
    long_name: str
    short_name: str
    standard: str
    default: float
    value: float

Constants and Parameters

Visualization and Plotting

Built-in visualization tools for exploring spectral index behavior and parameter sensitivity. Provides heatmap visualizations showing index values across parameter ranges.

def heatmap(
    index: str,
    x: str,
    y: str,
    params: Optional[dict] = None,
    online: bool = False,
    **kwargs
): ...

Visualization and Plotting

Sample Datasets

Built-in sample datasets for testing, examples, and educational purposes. Includes both satellite imagery and spectral reflectance data in multiple formats.

def open(dataset: str) -> Any: ...

Sample Datasets

Global Objects

• spyndex.indices: SpectralIndices object containing all available spectral indices
• spyndex.bands: Bands object containing all band definitions
• spyndex.constants: Constants object containing all constants

Module Metadata

__version__: str = "0.7.1"
__author__: str = "David Montero Loaiza <dml.mont@gmail.com>"

Supported Data Types

• Numeric values (int, float)
• NumPy arrays (numpy.ndarray)
• Pandas Series and DataFrames (pandas.Series, pandas.DataFrame)
• Xarray DataArrays and Datasets (xarray.DataArray, xarray.Dataset)
• Earth Engine Images and Numbers (ee.Image, ee.Number) - requires optional dependencies
• Dask Arrays and DataFrames (dask.array.Array, dask.dataframe.DataFrame)

Error Handling

• Index validation: Raises Exception if requested spectral index is not found in catalogue
• Parameter validation: Raises Exception if required bands/parameters are missing for index computation
• Earth Engine dependencies: Raises ImportError with installation instructions if Earth Engine features are used without optional dependencies