0
# Constants and Parameters
1

2
Standardized constants used in spectral index calculations with default values and descriptions. These constants provide consistent parameter values across different applications and research contexts, ensuring reproducible results when computing spectral indices.
3

4
## Capabilities
5

6
### Global Constants Catalogue
7

8
The global `spyndex.constants` object provides access to all standardized constants used in spectral index formulas.
9

10
```python { .api }
11
class Constants(Box):
12
    """
13
    Container for all constants used in spectral index calculations.
14
    
15
    Provides dictionary-like access to individual Constant objects.
16
    """
17
    
18
    def __repr__(self) -> str:
19
        """Machine readable representation showing available constant names."""
20
        
21
    def __str__(self) -> str:
22
        """Human readable list of constant names."""
23
```
24

25
**Usage Examples:**
26

27
```python
28
import spyndex
29

30
# Access the global constants catalogue
31
print(spyndex.constants)
32
# Output: Constants(['L', 'g', 'C1', 'C2', 'kNN', 'kNR', 'kNB', 'kNRE', ..., 'sigma', 'p', 'c'])
33

34
# Get list of all constant names
35
constant_names = list(spyndex.constants.keys())
36
print(f"Total constants available: {len(constant_names)}")
37

38
# Access specific constants
39
L = spyndex.constants.L      # Canopy background adjustment
40
g = spyndex.constants.g      # Gain factor
41
C1 = spyndex.constants.C1    # Aerosol resistance coefficient 1
42
C2 = spyndex.constants.C2    # Aerosol resistance coefficient 2
43
```
44

45
### Individual Constant Objects
46

47
Each constant is represented as a Constant object containing description and default value information.
48

49
```python { .api }
50
class Constant:
51
    """
52
    Individual constant with description and default value.
53
    """
54
    
55
    description: str    # Detailed description of the constant's purpose
56
    long_name: str      # Description (alias for description)
57
    short_name: str     # Standard constant abbreviation
58
    standard: str       # Standard abbreviation (alias for short_name)
59
    default: float      # Default value for the constant
60
    value: float        # Default value (alias for default)
61
    
62
    def __repr__(self) -> str:
63
        """Machine readable representation with name and default value."""
64
        
65
    def __str__(self) -> str:
66
        """Human readable description with default value."""
67
```
68

69
**Usage Examples:**
70

71
```python
72
import spyndex
73

74
# Access individual constant
75
L_constant = spyndex.constants.L
76

77
# Explore constant properties
78
print(L_constant.short_name)    # "L"
79
print(L_constant.description)   # "Canopy background adjustment"
80
print(L_constant.default)       # 1.0
81
print(L_constant.value)         # 1.0 (alias for default)
82

83
# Display constant information
84
print(L_constant)
85
# Output: L: Canopy background adjustment
86
#         * Default value: 1.0
87

88
# Use constant in computations
89
savi_result = spyndex.computeIndex(
90
    "SAVI",
91
    params={
92
        "N": 0.67,
93
        "R": 0.12,
94
        "L": spyndex.constants.L.default
95
    }
96
)
97
```
98

99
## Common Constants
100

101
### Vegetation Index Constants
102

103
Constants commonly used in vegetation-related spectral indices:
104

105
```python
106
import spyndex
107

108
# SAVI canopy background adjustment
109
L = spyndex.constants.L
110
print(f"L (Canopy background): {L.default}")  # 1.0
111

112
# EVI coefficients
113
C1 = spyndex.constants.C1  
114
C2 = spyndex.constants.C2
115
g = spyndex.constants.g
116
print(f"C1 (Aerosol resistance): {C1.default}")  # 6.0
117
print(f"C2 (Aerosol resistance): {C2.default}")  # 7.5  
118
print(f"g (Gain factor): {g.default}")           # 2.5
119

120
# Use in EVI computation
121
evi = spyndex.computeIndex(
122
    "EVI",
123
    params={
124
        "N": 0.67,
125
        "R": 0.12,
126
        "B": 0.08,
127
        "g": g.default,
128
        "C1": C1.default,
129
        "C2": C2.default,
130
        "L": L.default
131
    }
132
)
133
```
134

135
### Kernel Constants
136

137
Constants used in kernel-based spectral indices:
138

139
```python
140
import spyndex
141

142
# Kernel parameters
143
p = spyndex.constants.p      # Polynomial kernel degree
144
c = spyndex.constants.c      # Polynomial kernel trade-off
145
sigma = spyndex.constants.sigma  # RBF kernel length-scale
146

147
print(f"p (Kernel degree): {p.default}")        # 2.0
148
print(f"c (Kernel trade-off): {c.default}")     # 1.0
149
print(f"sigma (RBF length-scale): {sigma.default}")  # 0.5
150

151
# Use in kernel computation
152
poly_kernel = spyndex.computeKernel(
153
    "poly",
154
    params={
155
        "a": 0.67,
156
        "b": 0.12,
157
        "p": p.default,
158
        "c": c.default
159
    }
160
)
161
```
162

163
### Platform-Specific Constants
164

165
Some constants are tailored for specific satellite platforms or atmospheric conditions:
166

167
```python
168
import spyndex
169

170
# Explore all constants with their descriptions
171
for name, constant in spyndex.constants.items():
172
    print(f"{name}: {constant.description} (default: {constant.default})")
173
```
174

175
## Usage in Spectral Index Computation
176

177
Constants are typically used in two ways:
178

179
### Direct Value Usage
180

181
```python
182
import spyndex
183

184
# Use default values directly
185
result = spyndex.computeIndex(
186
    "SAVI",
187
    params={
188
        "N": 0.67,
189
        "R": 0.12,
190
        "L": 0.5  # Custom value instead of default
191
    }
192
)
193

194
# Use constants object for defaults
195
result = spyndex.computeIndex(
196
    "SAVI", 
197
    params={
198
        "N": 0.67,
199
        "R": 0.12,
200
        "L": spyndex.constants.L.default
201
    }
202
)
203
```
204

205
### Keyword Arguments
206

207
```python
208
import spyndex
209

210
# Mix constants and data
211
result = spyndex.computeIndex(
212
    "EVI",
213
    N=0.67,
214
    R=0.12,
215
    B=0.08,
216
    g=spyndex.constants.g.default,
217
    C1=spyndex.constants.C1.default,
218
    C2=spyndex.constants.C2.default,
219
    L=spyndex.constants.L.default
220
)
221
```
222

223
## Parameter Sensitivity Analysis
224

225
Using constants with their metadata for parameter sensitivity studies:
226

227
```python
228
import spyndex
229
import numpy as np
230

231
# Test SAVI sensitivity to L parameter
232
nir = 0.67
233
red = 0.12
234

235
# Default L value
236
default_L = spyndex.constants.L.default
237
savi_default = spyndex.computeIndex("SAVI", N=nir, R=red, L=default_L)
238

239
# Test range of L values
240
L_values = np.linspace(0.0, 2.0, 21)
241
savi_values = []
242

243
for L_val in L_values:
244
    savi = spyndex.computeIndex("SAVI", N=nir, R=red, L=L_val)
245
    savi_values.append(savi)
246

247
print(f"SAVI with default L ({default_L}): {savi_default:.4f}")
248
print(f"SAVI range across L values: {min(savi_values):.4f} to {max(savi_values):.4f}")
249
```
250

251
## Constant Validation
252

253
The constants catalogue ensures consistent parameter usage across different applications:
254

255
```python
256
import spyndex
257

258
def validate_evi_params(N, R, B):
259
    """Compute EVI with validated standard constants."""
260
    return spyndex.computeIndex(
261
        "EVI",
262
        params={
263
            "N": N,
264
            "R": R, 
265
            "B": B,
266
            "g": spyndex.constants.g.default,      # 2.5
267
            "C1": spyndex.constants.C1.default,    # 6.0
268
            "C2": spyndex.constants.C2.default,    # 7.5
269
            "L": spyndex.constants.L.default       # 1.0
270
        }
271
    )
272

273
# Ensures reproducible EVI computation
274
evi_standard = validate_evi_params(0.67, 0.12, 0.08)
275
```
276

277
## Custom Constants
278

279
While the catalogue provides standard defaults, custom values can be used when specific research contexts require different parameter values:
280

281
```python
282
import spyndex
283

284
# Standard SAVI
285
savi_standard = spyndex.computeIndex(
286
    "SAVI",
287
    N=0.67,
288
    R=0.12,
289
    L=spyndex.constants.L.default  # 1.0
290
)
291

292
# Modified SAVI for sparse vegetation
293
savi_sparse = spyndex.computeIndex(
294
    "SAVI",
295
    N=0.67,
296
    R=0.12,
297
    L=0.25  # Lower L value for sparse canopies
298
)
299

300
print(f"Standard SAVI (L=1.0): {savi_standard:.4f}")
301
print(f"Sparse SAVI (L=0.25): {savi_sparse:.4f}")
302
```
303

304
The constants catalogue serves as both a reference for standard parameter values and a foundation for reproducible spectral index computation across different research applications and platforms.