0
# Visualization and Plotting
1

2
Built-in visualization tools for exploring spectral index behavior and parameter sensitivity. Provides heatmap visualizations showing index values across parameter ranges, enabling visual analysis of spectral index characteristics and band sensitivity.
3

4
## Capabilities
5

6
### Spectral Index Heatmaps
7

8
Creates color-encoded matrix visualizations showing all possible spectral index values across two varying parameters, with other parameters held constant.
9

10
```python { .api }
11
def heatmap(
12
    index: str,
13
    x: str,
14
    y: str,
15
    params: Optional[dict] = None,
16
    online: bool = False,
17
    **kwargs
18
):
19
    """
20
    Plot all possible index values as a color-encoded matrix.
21

22
    Parameters:
23
    - index: Spectral index name to visualize
24
    - x: Band/parameter name for x-axis  
25
    - y: Band/parameter name for y-axis
26
    - params: Dictionary of fixed parameters for other required bands/parameters
27
    - online: Whether to retrieve most recent index list from GitHub
28
    - **kwargs: Additional arguments passed to seaborn.heatmap()
29

30
    Returns:
31
    matplotlib.axes.Axes: Matplotlib Axes object with the index heatmap
32
    """
33
```
34

35
**Usage Examples:**
36

37
```python
38
import spyndex.plot
39
import matplotlib.pyplot as plt
40

41
# Simple NDVI heatmap (NIR vs Red)
42
ax = spyndex.plot.heatmap(
43
    index="NDVI",
44
    x="N",  # Near-infrared on x-axis
45
    y="R",  # Red on y-axis
46
    cmap="RdYlGn",  # Red-Yellow-Green colormap
47
    annot=True,     # Show values in cells
48
    fmt=".2f"       # Format to 2 decimal places
49
)
50
plt.title("NDVI Sensitivity Analysis")
51
plt.show()
52

53
# SAVI heatmap with fixed L parameter
54
ax = spyndex.plot.heatmap(
55
    index="SAVI",
56
    x="N",
57
    y="R", 
58
    params={"L": 0.5},  # Fixed soil adjustment factor
59
    cmap="Spectral",
60
    annot=True
61
)
62
plt.title("SAVI with L=0.5")
63
plt.show()
64

65
# EVI heatmap with multiple fixed parameters
66
ax = spyndex.plot.heatmap(
67
    index="EVI",
68
    x="N",
69
    y="R",
70
    params={
71
        "B": 0.08,  # Fixed blue reflectance
72
        "g": spyndex.constants.g.default,
73
        "C1": spyndex.constants.C1.default,
74
        "C2": spyndex.constants.C2.default,
75
        "L": spyndex.constants.L.default
76
    },
77
    cmap="viridis",
78
    cbar_kws={"label": "EVI Value"}
79
)
80
plt.title("EVI Sensitivity (NIR vs Red)")
81
plt.show()
82
```
83

84
### Parameter Space Exploration
85

86
Visualizing how spectral indices behave across different parameter combinations:
87

88
```python
89
import spyndex.plot
90
import matplotlib.pyplot as plt
91

92
# Compare different indices side by side
93
fig, axes = plt.subplots(1, 3, figsize=(15, 5))
94

95
indices = ["NDVI", "GNDVI", "RVI"]
96
titles = ["NDVI (NIR vs Red)", "GNDVI (NIR vs Green)", "RVI (NIR vs Red)"]
97

98
for i, (idx, title) in enumerate(zip(indices, titles)):
99
    if idx == "GNDVI":
100
        spyndex.plot.heatmap(
101
            index=idx,
102
            x="N", y="G",  # NIR vs Green for GNDVI
103
            cmap="RdYlGn",
104
            ax=axes[i]
105
        )
106
    else:
107
        spyndex.plot.heatmap(
108
            index=idx,
109
            x="N", y="R",  # NIR vs Red for others
110
            cmap="RdYlGn", 
111
            ax=axes[i]
112
        )
113
    axes[i].set_title(title)
114

115
plt.tight_layout()
116
plt.show()
117
```
118

119
### Sensitivity Analysis
120

121
Understanding how indices respond to different reflectance conditions:
122

123
```python
124
import spyndex.plot
125
import matplotlib.pyplot as plt
126

127
# Water index sensitivity
128
water_indices = ["NDWI", "MNDWI", "AWEIsh"]
129

130
fig, axes = plt.subplots(1, len(water_indices), figsize=(18, 6))
131

132
for i, idx in enumerate(water_indices):
133
    try:
134
        # Get required bands for this index
135
        index_obj = spyndex.indices[idx]
136
        bands = index_obj.bands
137
        
138
        # Create appropriate parameter mapping
139
        if "N" in bands and "G" in bands:
140
            spyndex.plot.heatmap(
141
                index=idx,
142
                x="N", y="G",
143
                cmap="Blues",
144
                ax=axes[i]
145
            )
146
        elif "N" in bands and "S1" in bands:
147
            spyndex.plot.heatmap(
148
                index=idx, 
149
                x="N", y="S1",
150
                cmap="Blues",
151
                ax=axes[i]
152
            )
153
        
154
        axes[i].set_title(f"{idx} Sensitivity")
155
    except:
156
        axes[i].text(0.5, 0.5, f"{idx}\nNot Available", 
157
                    ha='center', va='center', transform=axes[i].transAxes)
158

159
plt.tight_layout()
160
plt.show()
161
```
162

163
### Custom Visualization Parameters
164

165
Advanced heatmap customization using matplotlib and seaborn parameters:
166

167
```python
168
import spyndex.plot
169
import matplotlib.pyplot as plt
170
import seaborn as sns
171

172
# Highly customized heatmap
173
plt.figure(figsize=(10, 8))
174

175
ax = spyndex.plot.heatmap(
176
    index="NDVI",
177
    x="N",
178
    y="R",
179
    # Seaborn heatmap parameters
180
    cmap="RdYlGn",
181
    center=0,  # Center colormap at 0
182
    annot=True,
183
    fmt=".3f",
184
    linewidths=0.5,
185
    cbar_kws={
186
        "label": "NDVI Value",
187
        "shrink": 0.8
188
    },
189
    # Additional styling
190
    square=True,  # Square cells
191
    xticklabels=5,  # Show every 5th x-tick
192
    yticklabels=5   # Show every 5th y-tick
193
)
194

195
# Customize further with matplotlib
196
ax.set_xlabel("Near-Infrared Reflectance", fontsize=12)
197
ax.set_ylabel("Red Reflectance", fontsize=12)
198
ax.set_title("NDVI Parameter Space Analysis", fontsize=14, fontweight='bold')
199

200
# Add contour lines for specific NDVI values
201
import numpy as np
202
X, Y = np.meshgrid(np.linspace(0, 1, 11), np.linspace(0, 1, 11))
203
Z = (X - Y) / (X + Y)  # NDVI formula
204
contours = ax.contour(Z, levels=[0.2, 0.4, 0.6, 0.8], colors='black', alpha=0.4, linewidths=1)
205
ax.clabel(contours, inline=True, fontsize=8)
206

207
plt.tight_layout()
208
plt.show()
209
```
210

211
## Parameter Grid Specifications
212

213
The heatmap function uses a standard parameter grid:
214

215
- **Range**: 0.0 to 1.0 (typical reflectance range)
216
- **Resolution**: 0.1 increments (11x11 grid)  
217
- **Coverage**: All combinations of the two varying parameters
218

219
This provides comprehensive coverage of typical reflectance conditions while maintaining reasonable computational efficiency.
220

221
## Multi-Parameter Indices
222

223
For indices requiring more than two parameters, fixed values must be provided for additional parameters:
224

225
```python
226
import spyndex.plot
227

228
# EVI requires N, R, B, g, C1, C2, L
229
# Fix all but two parameters
230
spyndex.plot.heatmap(
231
    index="EVI",
232
    x="N",    # Vary NIR
233
    y="B",    # Vary Blue  
234
    params={  # Fix others
235
        "R": 0.15,
236
        "g": 2.5,
237
        "C1": 6.0,
238
        "C2": 7.5,
239
        "L": 1.0
240
    },
241
    cmap="viridis"
242
)
243

244
# SAVI with varying L parameter
245
spyndex.plot.heatmap(
246
    index="SAVI",
247
    x="N",
248
    y="L",    # Vary soil adjustment factor
249
    params={
250
        "R": 0.15  # Fix red reflectance
251
    },
252
    cmap="RdYlGn"
253
)
254
```
255

256
## Interpretation Guidelines
257

258
### Heatmap Interpretation
259

260
- **Color intensity**: Represents spectral index magnitude
261
- **Gradients**: Show sensitivity to parameter changes
262
- **Patterns**: Reveal index behavior characteristics
263
- **Boundaries**: Indicate transition zones between different surface types
264

265
### Common Patterns
266

267
- **NDVI**: Diagonal gradient from negative (bottom-right) to positive (top-left)
268
- **Water indices**: High values in specific parameter combinations indicating water presence
269
- **Vegetation indices**: Peak values in high NIR, moderate red combinations
270
- **Burn indices**: Distinctive patterns for burned vs unburned surfaces
271

272
## Integration with Analysis Workflows
273

274
Heatmaps can be integrated into broader analysis workflows:
275

276
```python
277
import spyndex.plot
278
import matplotlib.pyplot as plt
279

280
def analyze_index_sensitivity(index_name, primary_bands):
281
    """Comprehensive sensitivity analysis for a spectral index."""
282
    
283
    # Get index information
284
    index_obj = spyndex.indices[index_name]
285
    
286
    print(f"Analyzing {index_name}: {index_obj.long_name}")
287
    print(f"Formula: {index_obj.formula}")
288
    print(f"Required bands: {index_obj.bands}")
289
    print(f"Application domain: {index_obj.application_domain}")
290
    
291
    # Create heatmap
292
    fig, ax = plt.subplots(figsize=(8, 6))
293
    
294
    spyndex.plot.heatmap(
295
        index=index_name,
296
        x=primary_bands[0],
297
        y=primary_bands[1],
298
        cmap="RdYlGn",
299
        annot=True,
300
        fmt=".2f",
301
        ax=ax
302
    )
303
    
304
    ax.set_title(f"{index_name} Sensitivity Analysis")
305
    plt.tight_layout()
306
    plt.show()
307

308
# Example usage
309
analyze_index_sensitivity("NDVI", ["N", "R"])
310
analyze_index_sensitivity("GNDVI", ["N", "G"])
311
```
312

313
The plotting capabilities enable visual exploration of spectral index behavior, supporting both research applications and educational use cases in remote sensing and vegetation monitoring.