# Longitudinal Analysis (M3)

The Longitudinal Analysis module processes all cross-sections along the alignment to identify spatial trends in excavation quality. While M1 and M2 evaluate individual sections in isolation, M3 reveals patterns across the tunnel length -- quality degradation, systematic biases, and problem zones.

## Analysis scope

Longitudinal analysis operates on all sections within the selected chainage range that have both measured data (for the chosen line definition) and a valid template. Sections without data or without a template assignment are skipped silently.

The analysis produces:

- Per-section quality metrics and compliance results (M1 + M2 for every section)
- Linear trend regression of RMS deviation vs chainage
- Deviation heatmap grid

## Longitudinal deviation profile

The RMS deviation for each section is plotted against chainage to produce a longitudinal deviation profile. This chart shows how excavation quality varies along the tunnel:

- **Flat profile** with low RMS: consistent, controlled excavation
- **Rising profile**: quality degrading with advancing chainage (possible equipment wear, ground change)
- **Spikes**: isolated problem sections (geological anomalies, blasting incidents)

## Section ranking

Sections are ranked by quality grade and RMS deviation. The worst sections appear at the top, making it easy to identify the most critical locations that require attention. The ranking includes:

- Station (chainage)
- Section name
- Quality grade (A/B/C/D)
- RMS deviation (mm)
- Excavation ratio (%)
- Compliance status (PASS/FAIL)
- Overbreak area (m^2^)

## Deviation heatmap

```{figure} ../_static/images/analytics_heatmap.svg
:alt: Deviation heatmap schematic
:width: 90%

Deviation heatmap: X-axis shows chainage, Y-axis shows horizontal offset from the tunnel axis, color intensity represents deviation magnitude.
```

The deviation heatmap provides a 2D visualization of deviations across the entire tunnel:

- **X-axis**: Chainage (station along the alignment)
- **Y-axis**: Horizontal offset from the tunnel axis (meters)
- **Color**: Deviation magnitude (mm)

The color scale uses a diverging scheme:

| Color | Range | Meaning |
|-------|-------|---------|
| Blue | < -50 mm | Severe underbreak |
| Light blue | -50 to -20 mm | Moderate underbreak |
| White | -20 to +20 mm | Within tolerance |
| Light red | +20 to +100 mm | Moderate overbreak |
| Red | > +100 mm | Severe overbreak |

The Y-axis uses horizontal offset position (distance from the tunnel axis), not polar angle. This provides a natural spatial representation where left-wall deviations appear on the left side and right-wall deviations on the right.

### Dashboard heatmap panel

The same underlying grid drives the **section heatmap panel** on the Analytics dashboard. The panel's toggle button cycles through three colour modes:

| Mode | Purpose | Scale |
|------|---------|-------|
| **Grade** | Worst absolute deviation in the bin. | Green → yellow → orange → red (Grade A → D thresholds). |
| **Tolerance** | Bin's relation to the USL/LSL corridor. | Blue (above USL), red (below LSL), green (in corridor). |
| **Clearance** | Sector pass/fail reused from {doc}`clearance`. | Green (pass), red (fail), grey (no data). |

All three modes use the same axis convention: **Invert / R-Wall / Crown / L-Wall / Invert** on the Y-axis, bottom to top, matching the walking direction when stepping into the tunnel along increasing chainage. The X-axis is chainage. Hovering a cell shows the section name, chainage, bin centre angle and the mode-specific value.

When the alignment's **View Along Decreasing Chainage** setting is on, the heatmap mirrors with the section sketch. Bottom to top then reads **Invert / L-Wall / Crown / R-Wall / Invert**, and the panel shows "View: decreasing chainage". The same mirror is applied to the grade, tolerance, and clearance heatmap pages in the PDF reports.

### Heatmap construction

The offset range is divided into bins (default 36). For each section-bin pair, the deviation with the largest absolute magnitude is retained. Empty bins (no measured points at that offset for that section) are marked as no-data and rendered transparent.

```{tip}
The heatmap is particularly effective for identifying directional biases. A persistent red band on one side of the tunnel may indicate a systematic drilling offset that should be corrected in the excavation procedure.
```

## Deviation trend

A linear regression of RMS deviation against chainage produces three values:

| Parameter | Interpretation |
|-----------|----------------|
| **Slope** | Rate of quality change per meter of chainage (mm/m). Positive = quality degrading. |
| **Intercept** | Baseline RMS at chainage zero (extrapolated) |
| **R^2^** | Goodness of fit. High R^2^ with positive slope = systematic quality degradation. Low R^2^ = random variation, no clear trend. |

```{note}
The trend regression is most meaningful when the tunnel is excavated sequentially from low to high chainage. If sections were excavated in non-sequential order (e.g., from both portals), the chainage trend may not reflect temporal quality changes.
```

## Convergence monitoring

When re-measurements are available at the same chainage (multiple survey campaigns), the longitudinal module can track ground movement over time. By comparing deviations at the same station across different measurement dates, convergence patterns become visible:

- **Inward movement**: Increasing underbreak over time indicates ground convergence
- **Stable profile**: No change between campaigns confirms ground stability
- **Differential movement**: Asymmetric changes suggest non-uniform ground loading

```{warning}
Convergence analysis requires that re-measurement sections are recorded at identical stations. Small chainage offsets between campaigns will produce misleading results because the comparison is station-based, not interpolated.
```