0
# Spyndex
1

2
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.
3

4
## Package Information
5

6
- **Package Name**: spyndex
7
- **Version**: 0.7.1
8
- **Author**: David Montero Loaiza
9
- **Language**: Python
10
- **Installation**: `pip install spyndex`
11
- **Optional Earth Engine support**: `pip install 'spyndex[ee]'`
12

13
## Core Imports
14

15
```python
16
import spyndex
17
```
18

19
Common imports for accessing different components:
20

21
```python
22
# Core functions
23
from spyndex import computeIndex, computeKernel
24

25
# Catalogue access
26
import spyndex.indices
27
import spyndex.bands
28
import spyndex.constants
29

30
# Plotting and datasets
31
import spyndex.plot
32
import spyndex.datasets
33
```
34

35
## Basic Usage
36

37
```python
38
import spyndex
39
import numpy as np
40

41
# Compute a single spectral index with numeric values
42
ndvi = spyndex.computeIndex(
43
    index="NDVI",
44
    params={
45
        "N": 0.643,  # Near-infrared
46
        "R": 0.175   # Red
47
    }
48
)
49
print(ndvi)  # Output: 0.5721271393643031
50

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

56
indices = spyndex.computeIndex(
57
    index=["NDVI", "GNDVI", "SAVI"],
58
    params={
59
        "N": nir,
60
        "R": red,
61
        "G": green,
62
        "L": 0.5  # SAVI soil adjustment factor
63
    }
64
)
65
print(indices.shape)  # Output: (3, 1000)
66

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

72
# Use constants from the catalogue
73
l_value = spyndex.constants.L.default  # 1.0
74
```
75

76
## Architecture
77

78
Spyndex is built around several key components:
79

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

86
## Capabilities
87

88
### Spectral Index Computation
89

90
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.
91

92
```python { .api }
93
def computeIndex(
94
    index: Union[str, List[str]],
95
    params: Optional[dict] = None,
96
    online: bool = False,
97
    returnOrigin: bool = True,
98
    coordinate: str = "index",
99
    **kwargs
100
) -> Any: ...
101

102
def computeKernel(
103
    kernel: str,
104
    params: Optional[dict] = None,
105
    **kwargs
106
) -> Any: ...
107
```
108

109
[Spectral Index Computation](./computation.md)
110

111
### Spectral Indices Catalogue
112

113
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.
114

115
```python { .api }
116
class SpectralIndices(Box):
117
    def __repr__(self) -> str: ...
118
    def __str__(self) -> str: ...
119

120
class SpectralIndex:
121
    short_name: str
122
    long_name: str
123
    bands: tuple
124
    application_domain: str
125
    reference: str
126
    formula: str
127
    date_of_addition: str
128
    contributor: str
129
    platforms: list
130
    
131
    def compute(self, params=None, **kwargs) -> Any: ...
132
```
133

134
[Spectral Indices Catalogue](./catalogue.md)
135

136
### Band and Platform Information
137

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

140
```python { .api }
141
class Bands(Box):
142
    def __repr__(self) -> str: ...
143
    def __str__(self) -> str: ...
144

145
class Band:
146
    short_name: str
147
    long_name: str
148
    common_name: str
149
    min_wavelength: float
150
    max_wavelength: float
151
    standard: str
152
    sentinel2a: PlatformBand
153
    sentinel2b: PlatformBand
154
    # ... other platforms
155

156
class PlatformBand:
157
    platform: str
158
    band: str
159
    name: str
160
    wavelength: float
161
    bandwidth: float
162
```
163

164
[Band and Platform Information](./bands.md)
165

166
### Constants and Parameters
167

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

170
```python { .api }
171
class Constants(Box):
172
    def __repr__(self) -> str: ...
173
    def __str__(self) -> str: ...
174

175
class Constant:
176
    description: str
177
    long_name: str
178
    short_name: str
179
    standard: str
180
    default: float
181
    value: float
182
```
183

184
[Constants and Parameters](./constants.md)
185

186
### Visualization and Plotting
187

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

190
```python { .api }
191
def heatmap(
192
    index: str,
193
    x: str,
194
    y: str,
195
    params: Optional[dict] = None,
196
    online: bool = False,
197
    **kwargs
198
): ...
199
```
200

201
[Visualization and Plotting](./plotting.md)
202

203
### Sample Datasets
204

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

207
```python { .api }
208
def open(dataset: str) -> Any: ...
209
```
210

211
[Sample Datasets](./datasets.md)
212

213
## Global Objects
214

215
- **`spyndex.indices`**: SpectralIndices object containing all available spectral indices
216
- **`spyndex.bands`**: Bands object containing all band definitions  
217
- **`spyndex.constants`**: Constants object containing all constants
218

219
## Module Metadata
220

221
```python { .api }
222
__version__: str = "0.7.1"
223
__author__: str = "David Montero Loaiza <dml.mont@gmail.com>"
224
```
225

226
## Supported Data Types
227

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

235
## Error Handling
236

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