# gri-plot Demonstrations

This module demonstrates the plotting capabilities provided by `gri-plot`, a lightweight
visualization library in the GRI FOSS ecosystem.

## Available gri-plot Functions

### 1. `scatter()` - Plotly Scatter Plots

Simple one-liner wrapper for Plotly scatter plots with flexible input formats.

**Features:**
- Variable-length trace input: `(y,)`, `(x, y)`, or `(x, y, trace_args_dict)`
- Multiple traces via positional arguments
- Layout customization via kwargs
- Dark template by default

**Example:**
```python
from gri_plot import scatter
import numpy as np

x = np.linspace(0, 10, 100)
y1 = np.sin(x)
y2 = np.cos(x)

# Multiple traces with custom styling
scatter(
    (x, y1, {"name": "sin(x)"}),
    (x, y2, {"name": "cos(x)"}),
    title="Trigonometric Functions",
    xaxis_title="x",
    yaxis_title="y"
)
```

### 2. `scatter_map()` - Geographic Scatter Maps

Geographic visualization using Plotly with ArcGIS World Imagery base layer.

**Features:**
- Takes lat/lon sequences: `scatter_map((lats, lons), ...)`
- Auto-centers map based on data bounds
- Custom marker sizes and colors per dataset
- Configurable zoom level

**Example:**
```python
from gri_plot import scatter_map
import numpy as np

# Random points near Denver
lats = 39.7392 + np.random.randn(50) * 0.01
lons = -104.9903 + np.random.randn(50) * 0.01

scatter_map(
    (lats, lons),
    zoom=14,
    marker_sizes=[8],
    marker_colors=["#ff6b6b"]
)
```

### 3. `plot_ellipsoid()` - 3D Ellipsoid Visualization

Visualizes covariance matrices as 3D ellipsoids using Matplotlib.

**Features:**
- Takes ellipsoid specs: `(center, covariance, label?)`
- Eigenvalue decomposition for proper orientation
- Automatic color cycling
- Optional recentering to origin

**Example:**
```python
from gri_plot import plot_ellipsoid
import numpy as np

# Define a 3x3 covariance matrix
cov = np.array([
    [100, 20, 10],
    [20, 50, 5],
    [10, 5, 25]
])
center = np.array([0, 0, 0])

plot_ellipsoid(
    (center, cov, "Uncertainty"),
    axis_labels=["East (m)", "North (m)", "Up (m)"]
)
```

## Demos

Each demo is a single self-contained file that generates synthetic data and produces a plot.

| Script | Description | gri-plot function |
|--------|-------------|-------------------|
| `scatter.py` | Basic scatter plot | `scatter()` |
| `scatter_map.py` | Geographic map with points | `scatter_map()` |
| `ellipsoid.py` | 3D covariance visualization | `plot_ellipsoid()` |
| `asf_qq.py` | Scale factor Q-Q plot (empirical vs Rayleigh) | `scatter()` |
| `asf_hist.py` | Scale factor histogram with theoretical overlay | `scatter()` |

### Scale Factor Background

The ASF (Average Scale Factor) demos visualize `gri_utils.stats.scale_factor`, which
measures how well reported uncertainty ellipses match actual errors:

- **ASF = 1.0**: Perfect calibration (ellipses match reality)
- **ASF > 1.0**: Underestimated uncertainties (ellipses too small)
- **ASF < 1.0**: Overestimated uncertainties (ellipses too large)

The Q-Q plot compares sorted empirical norms against theoretical Rayleigh quantiles.
The histogram shows the distribution of ellipse norms with theoretical overlay.

## Running Demos

```bash
# From gri-sandbox root
python -m gri_sandbox.plots.scatter
python -m gri_sandbox.plots.scatter_map
python -m gri_sandbox.plots.ellipsoid
python -m gri_sandbox.plots.asf_qq
python -m gri_sandbox.plots.asf_hist
```

## Package Integration

These plotting utilities integrate well with other GRI FOSS packages:

| Package | Integration |
|---------|-------------|
| **gri-utils** | Scale factor visualization, distance comparisons |
| **gri-pos** | Visualize position solutions on maps |
| **gri-ell** | Plot uncertainty ellipsoids from covariance matrices |
| **gri-signal** | Display filtered signals and spectral analysis |
| **gri-tropo/gri-iono** | Show atmospheric corrections over time/space |
