## Example 7: Multi-Trend Estimation

This example demonstrates piecewise linear trend estimation (`estimatemultitrend`)
on a synthetic 9-year daily up-component time series.  The series has three
distinct trend regimes separated by known break epochs:

| Segment | Period | True slope |
|---------|--------|-----------|
| 1       | year 0–3 | 0 mm/yr |
| 2       | year 3–6 | 3 mm/yr |
| 3       | year 6–9 | 1 mm/yr |

Noise is flicker (GGM, d ≈ 0.5) plus white noise, with annual and semi-annual
amplitudes taken from the ONSA up-component results in Example 6.

### Directory layout

```
obs_files/MULTITREND.mom    synthetic time series (generated by create_signal.py)
pre_files/MULTITREND.mom    after outlier removal (generated)
mom_files/MULTITREND.mom    observations + fitted model (generated)
data_figures/MULTITREND.png time-series plot with fitted model (generated)
create_signal.py            generates the synthetic time series
removeoutliers.ctl
estimatetrend.ctl
estimatespectrum.ctl
```

### Step 0 — Generate the synthetic time series

```
python3 create_signal.py
```

This writes `obs_files/MULTITREND.mom`.  The break epochs are embedded in
the file header:

```
# sampling period 1.0
# break  52639.0
# break  53734.0
```

### Step 1 — Remove spike outliers

```
removeoutliers
```

Uses `Spike_factor 3` in `removeoutliers.ctl`.  Expected: about 25 spikes
flagged.

> **Note:** For purely synthetic data with no injected outliers this step is
> not strictly necessary.  It is included here to mirror the standard workflow
> (§4.1.1) and because real data always requires it before offset detection or
> trend estimation.

### Step 2 — Estimate the piecewise linear trend

The key keyword in `estimatetrend.ctl` is `estimatemultitrend yes`.  Hector
reads the `# break` epochs from the data file header and adds a ramp function
$\max(0, t - t_{\rm break})$ for each break epoch to the design matrix,
estimating the slope change at each epoch.

```
estimatetrend -png
```

Expected output:

```
Piecewise trend segments:
  segment 1 (before 52639.0) :   0.169 mm/yr
  slope change at 52639.0  :  +3.316 +/- 0.846 mm/yr
  segment 2 (52639.0 - 53734.0) :   3.486 mm/yr
  slope change at 53734.0  :  -2.473 +/- 0.847 mm/yr
  segment 3 (53734.0 - end) :   1.013 mm/yr
```

The recovered slopes (0.17, 3.49, 1.01 mm/yr) agree well with the true values
(0, 3, 1 mm/yr).  The per-segment uncertainty of about ±0.85 mm/yr reflects
the correlated nature of flicker noise: because the noise is correlated over
timescales comparable to the segment length (3 yr), the effective number of
independent observations per segment is much smaller than the nominal count.

The `-png` flag saves `data_figures/MULTITREND.png` showing the observations
and fitted piecewise model.

### Step 3 — Inspect the power spectral density (optional)

```
estimatespectrum -model
```

Reads `mom_files/MULTITREND.mom` (residuals), computes the Welch periodogram,
and overlays the estimated GGM+White noise model PSD.
