CHANGELOG

# Changelog

## [v0.6.8] - 2026-06-22 - Visualisation module extraction

### Added

- Internal `src/ramanpl/visualisation/` package for plotting implementation code.
- `src/ramanpl/visualisation/_batch.py`, `_mapping.py`, `_single_fit.py`, and `_preview.py`.
- Internal `_plot_raw_spectrum(...)` helper for array and mapping-pixel preview use. This is package-private in v0.6.8 and is not a stable public API.
- `tests/test_visualisation_facades.py` with facade-signature checks and lightweight structural figure checks under the Agg backend.

### Changed

- Batch plotting implementations moved behind `ramanpl.batch.plot_overlay`, `plot_waterfall`, and `plot_fitted_parameters`; existing imports from `ramanpl.batch` remain valid.
- `RamanMapping` and `PLMapping` fitted-map plotting methods now delegate to internal visualisation helpers.
- `RamanFit.plot_fit` and `PLfit.plot_fit` now delegate to internal visualisation helpers.
- Version bumped to 0.6.8 in `pyproject.toml`, `src/ramanpl/__init__.py`, `CITATION.cff`, `docs/source/conf.py`, and `tests/test_packaging_smoke.py`.

### Not changed

- Public plotting method signatures and legacy return contracts are preserved: batch plotting returns `(fig, ax)`, while mapping and single-fit plotting keep the existing `plt.show()` / `None` behavior.
- Integration-class plotting (`Raman_Integration`, `PL_Integration`) remains unchanged and is deferred for later cleanup.
- No fitting, preprocessing, baseline, peak-model, export, feature-table schema, parallel, or cluster-seed behavior changes.

### Verification

- `py -3.14 -m py_compile` passed for all touched production modules and `tests/test_visualisation_facades.py`.
- Pytest and import smoke commands were not run in this workspace because the project `.venv` points to a missing Python interpreter and the available system/bundled Python installations lack the scientific/test dependencies.

## [v0.6.7] — 2026-06-05 — Integrated component area in the feature table

### Added

- `{peak}_component_area`, `{peak}_component_area_norm`, `{peak}_component_area_fraction`
  columns in `feature_table()` for all fitter classes (RamanFit, PLfit, RamanMapping,
  PLMapping, RamanBatch, PLBatch). Values are exact analytic areas of the fitted lineshape
  (`amp × intensity_scale` and `amp` respectively); fraction sums to 1 across all peaks in
  a row.
- `area_ratios=` keyword on all five `feature_table()` entry points; each `(P1, P2)` pair
  emits `{P1}_{P2}_area_ratio = amp[P1] / amp[P2]` (zero denominator → NaN).
- `tests/test_component_area_identity.py` — verifies the area = `amp` identity numerically
  for Lorentzian, Gaussian, and pseudo-Voigt (16 parameterised cases).
- `docs/source/api-stability.md` §14 — v0.6.7 component-area freeze contract; §3 suffix
  table extended with four new frozen suffixes.
- `snapshot/featuretable_*_v0.6.6.csv` — golden CSVs for byte-parity regression.

### Changed

- `src/ramanpl/descriptors.py` — `build_feature_row` gains `area_ratios=` parameter and
  emits three new per-peak columns and optional area-ratio pair columns.
- `src/ramanpl/mapping/_preprocess.py` — `_params_to_export_dict` adds `amp_scaled` to
  both lorentzian and pvoigt out-dicts; `feature_table` signature gains `area_ratios=` and
  emits NaN for new columns in the failed-pixel branch.
- `src/ramanpl/single_fit/RamanFit.py` and `PLfit.py` — `get_fitted_parameters` adds
  `amp_scaled` to the returned dict; `feature_table` forwards `amp`/`amp_scaled` and gains
  `area_ratios=`.
- `src/ramanpl/batch.py` — `feature_table` forwards `amp`/`amp_scaled` and gains
  `area_ratios=`.
- `tests/test_api_stability.py` — `_FROZEN_SUFFIXES` extended; reference column lists
  updated; three new v0.6.7 contract tests added.
- `tests/test_descriptors_unit.py`, `test_feature_table_mapping.py`,
  `test_feature_table_batch_and_single.py` — extended with component-area correctness,
  byte-parity, and cross-path consistency tests.
- `docs/source/quickstart.md` — feature-table section documents new columns.
- `example-usage/Ramanfit/Raman_component.ipynb`, `example-usage/PLfit/PL_component.ipynb`,
  `example-usage/Mapping/Mapping Raman Example.ipynb`, `example-usage/Mapping/Mapping PL Example.ipynb`
  — new section in each notebook demonstrating `feature_table()` component-area columns and
  `area_ratios=` usage (with heatmap visualisation for the mapping notebooks).
- Version bumped to 0.6.7 in `pyproject.toml`, `__init__.py`, `CITATION.cff`, `conf.py`,
  `test_packaging_smoke.py`.

### Not changed (scope boundary)

- `export()` and long-format exporters — `amp` was already present; no schema change.
- Fitting algorithms, peak models, preprocessing — zero changes.
- Benchmarks — zero new `curve_fit` calls; no performance impact.
- Plotting — deferred to v0.6.8.

## [v0.6.6] — 2026-06-02 — Consolidation pause: API freeze, validation, docs

### Added

- `benchmarks/validation_v0.6.6_vs_v0.6.0.py` — reproducible validation harness
  covering 7 gates: fit-output parity, export-schema stability, call-count sanity,
  parallel safety, cluster-seed boundary, autotune non-mutation, batch-progress
  default.
- `benchmarks/results/v0.6.6_validation.csv` — versioned raw gate evidence.
- `benchmarks/results/v0.6.6_validation_summary.json` — machine-readable gate
  summary; all 7 gates passed.
- `docs/source/validation/v0.6.6.md` — citable validation report.
- `docs/source/api-stability.md` §9–§13 — freeze contracts for v0.6.1–v0.6.5
  additive surface (`show_progress`, autotune, `method_grids`, `n_jobs`,
  `cluster_seeds`).
- `tests/test_api_stability.py` — six new contract tests: `show_progress=True`
  default on mapping and batch entry points; `n_jobs=1` default on both mapping
  classes; `autotune_baseline`/`apply_choice` presence on all four fit objects;
  `method_grids` keyword present; removed `methods`/`lam_grid` absent.
- `closeout_v0.6.6.md` — release closeout document.

### Changed

- `docs/source/user-guide/mapping.md` — `show_progress` and `n_jobs` usage
  added; `parallel-fitting` cross-reference added.
- `docs/source/user-guide/batch.md` — `show_progress=True` default documented.
- `docs/source/user-guide/low_snr_advisory.md` — autotune baseline workflow
  cross-referenced at Step 3; cluster-seeds advisory added as Step 5b.
- `docs/source/user-guide/baseline-autotune.md` — `methods`/`lam_grid` removal
  made explicit; `TypeError` on use stated.
- `checklist.md` — `show_progress` default corrected from `False` to `True`
  (source default confirmed by Gate 0.2).

### Known limitations

- `cluster_seeds=True` remains serial-only (`n_jobs=1` required).
- On homogeneous synthetic cubes, `cluster_seeds=True` does not reduce
  `n_curve_fit_calls`. Benefit depends on multi-domain data.

---

## [v0.6.5] — 2026-05-28 — Similarity-based seed selection for warm-start

### Added

- `cluster_seeds` keyword on `RamanMapping.fit_spectra` and `PLMapping.fit_spectra`
  (default `False`; backward-compatible).  When `True` or a config dict, preprocessed
  spectra are clustered with PCA + k-means (scikit-learn), one representative pixel
  per cluster is fitted first, and each representative's fitted parameters are used as
  the initial guess for remaining pixels in that cluster.
- `src/ramanpl/mapping/_cluster_seeds.py` — package-private helpers:
  `_require_sklearn_for_cluster_seeds`, `_normalise_cluster_seed_config`,
  `_spectral_feature_matrix`, `_cluster_spectra`, `_representative_pixels`,
  `_build_cluster_schedule`.  All sklearn imports are lazy; base install unaffected.
- `_fit_single_pixel` private method on both mapping classes — minimal per-pixel
  fit wrapper enabling the cluster-seeded dispatch without modifying `_fit_rows`.
- `tests/test_cluster_seed_helpers.py` — 15 tests for helpers and schedule invariants.
- `tests/test_cluster_seed_fit_mapping.py` — 15 integration tests covering parity,
  serial completion, success-rate gate, tolerance, mutual exclusions, parallel guard.
- `benchmarks/results/mapping_fit_benchmark_v0.6.5.csv` — versioned benchmark
  results including `cluster_seeds` axis across 4 dataset sizes.
- `benchmarks/results/cluster_seed_speedup_v0.6.5.txt` — call-count comparison.
- `docs/source/user-guide/mapping.md` — `cluster_seeds` usage example.
- `docs/source/user-guide/parallel-fitting.md` — v0.6.5 serial-only constraint.
- `docs/source/api-stability.md` — §9 documents the additive `cluster_seeds` change.
- `closeout_v0.6.5.md` — release closeout document.

### Changed

- `benchmarks/benchmark_mapping_fit.py` — `cluster_seeds` axis added to result
  schema and `build_fit_kwargs_variants`; new `noisy_5x8` benchmark case added.
- `tests/test_api_stability.py` — new test pins `cluster_seeds` keyword presence
  and default on both mapping classes.
- `tests/test_release_benchmark_smoke.py` — expects `cluster_seeds` field in
  fit benchmark records.
- `example-usage/Mapping/Mapping Raman Example.ipynb` and
  `example-usage/Mapping/Mapping PL Example.ipynb` — `cluster_seeds` demo cells
  added (Option B: markdown explanation + code cell after the existing `n_jobs`
  section in each notebook).

### Fixed

- `benchmarks/validation_v0.6.0_vs_v0.5.0.py` — `"cluster_seeds"` and `"n_jobs"`
  added to `_CSV_FIELDS`; `"n_jobs": 1` and `"cluster_seeds": False` added to the
  hand-built `_run_hard_case` return dict.  CI regression: `run_mapping_fit_case`
  (extended in v0.6.5) returns a `cluster_seeds` key that `csv.DictWriter` rejected
  with `ValueError: dict contains fields not in fieldnames: 'cluster_seeds'`.
- `src/ramanpl/mapping/_cluster_seeds.py` — `_representative_pixels` now returns
  `(cluster_id, (x, y))` pairs instead of bare `(x, y)` tuples; `_build_cluster_schedule`
  unpacks the actual cluster ID rather than using `enumerate`.  When KMeans produces
  non-contiguous labels (e.g. `{0, 2}` on low-diversity or duplicate spectra), the old
  `enumerate` index `k=1` looked for pixels with `labels[j, i] == 1`, found none, and
  silently skipped every pixel in cluster 2, leaving NaNs in `fitted_params` and
  `residual_map` under `cluster_seeds=True`.
- `tests/test_cluster_seed_helpers.py` — updated six `_build_cluster_schedule` fixtures
  to the new `(cluster_id, (x, y))` representative format.
- `benchmarks/benchmark_mapping_fit.py` — speedup summary header corrected from
  `n_starts=1` to `n_starts=4`; the baseline rows were already filtered to
  `n_starts=4` and the cluster-seed variants are built with `n_starts=4`, so the
  file was documenting the wrong experimental setting.
- `src/ramanpl/mapping/_raman_mapping.py` and `_pl_mapping.py` — invalid pixels
  (those labeled `-1` by `_cluster_spectra`) are now explicitly NaN-ised in
  `residual_map`, `norm_scale_map`, `peak_positions`, `peak_intensities`, and the
  Raman-specific derived maps (`Peaks_distance`, `ratio_A1g_E2g`, `ratio_E2g_A1g`)
  before the cluster schedule loop.  Previously those pixels were silently skipped,
  so stale values from a prior `fit_spectra()` call were retained and could be
  counted or exported as successful fits.
- `src/ramanpl/mapping/_raman_mapping.py` and `_pl_mapping.py` — cluster seed
  broadcast now gates on `warm_start_rmse_gate` before setting `cluster_p0`.
  Previously only finiteness was checked, so a representative whose fit converged but
  exceeded the gate would still seed every cluster member — exactly the propagation the
  gate exists to prevent.  The fix reads `self.residual_map[sy, sx]` (written by
  `_fit_single_pixel`) and falls back to `p0_base` when the RMSE is non-finite or
  above the gate.

### Known limitations

- `cluster_seeds=True` is serial-only (`n_jobs=1` required). Two-phase parallel
  cluster dispatch is deferred.
- On homogeneous synthetic benchmark cubes, `n_curve_fit_calls` is identical for
  `cluster_seeds=True` and `cluster_seeds=False` because the optimizer converges
  to the global minimum from any reasonable starting point. The call-count benefit
  manifests on real multi-domain spectroscopic data.

---

## [v0.6.4] — 2026-05-24 — Parallel mapping fit with row-band warm-start

### Added

- `n_jobs` keyword on `RamanMapping.fit_spectra` and `PLMapping.fit_spectra`
  (default `1`, serial — byte-parity with v0.6.3 preserved).  When `n_jobs > 1`
  the row loop is distributed across loky worker processes via `joblib.Parallel`.
- `src/ramanpl/mapping/_parallel.py` — module-level band workers
  (`_raman_fit_band`, `_pl_fit_band`), row-splitting helper (`_split_rows`),
  validation helper (`_validate_parallel_kwargs`), and result merger
  (`_merge_band_outputs`).
- `joblib>=1.3` as a hard runtime dependency.
- `tests/test_parallel_fit_mapping.py` — 11 new tests covering byte-parity,
  unsafe-mode ValueError, call-count invariant, clamping, and utility functions.
- `benchmarks/results/mapping_fit_benchmark_v0.6.4.csv` — versioned benchmark
  results over 3 dataset sizes × 8 fit-kwargs variants (including n_jobs axis).
- `benchmarks/results/parallel_speedup_v0.6.4.txt` — wall-clock speedup table
  for `extended_15x15` dataset; 2.42× at n_jobs=4 (n_starts=1).
- `docs/source/user-guide/parallel-fitting.md` — user guide for `n_jobs`.
- `closeout_v0.6.4.md` — release closeout document.

### Changed

- `benchmarks/benchmark_mapping_fit.py` — `n_jobs` axis added to
  `build_fit_kwargs_variants`; result records include `n_jobs` field.
- `RamanMapping.fit_spectra` and `PLMapping.fit_spectra` docstrings updated
  to document `n_jobs` parameter.
- Example notebooks (`Mapping Raman Example.ipynb`, `Mapping PL Example.ipynb`)
  extended with `n_jobs` parallel-fit demonstration cells.

### Removed

- `methods` / `lam_grid` deprecation shim (`_shim_methods_lam_grid`) from
  `_autotune.py`.  Both kwargs now raise `TypeError` when passed.  (Deprecated
  in v0.6.3; removal announced in that release.)

### Fixed

- `tol` parameter added to `_ALLOWED_PARAMS["arpls"]` and
  `_ALLOWED_PARAMS["airpls"]`, enabling `tol` sweeps via `method_grids`.
- `_validate_parallel_kwargs` now returns `1` immediately when `Y=0`, preventing
  a `ZeroDivisionError` in `_split_rows` that was a regression over the prior
  serial no-op behaviour on empty cubes.
- `show_progress=True` now shows a tqdm bar for `n_jobs > 1` fits, using
  `Parallel(return_as="generator")` to report per-band completion progress.
  Previously the flag was silently ignored in the parallel branch.
- `benchmarks/validation_v0.6.0_vs_v0.5.0.py` — `"n_jobs"` added to
  `_CSV_FIELDS` so `DictWriter` accepts the extended `run_mapping_fit_case`
  result dict (CI regression introduced by Step 6).

---

## [v0.6.3] — 2026-05-23 — Autotune API refinement, real-data notebooks, API docs

### Added

- `method_grids` parameter on `autotune_baseline()` for `RamanMapping`, `PLMapping`,
  `RamanFit`, and `PLfit`. Accepts a `{method: {param: [values]}}` dict; candidates are
  the Cartesian product over each method's parameter lists.
- `_shim_methods_lam_grid` internal function that converts the deprecated `methods` /
  `lam_grid` keyword pair into an equivalent `method_grids` dict, preserving v0.6.2
  byte-parity on the default 24-candidate grid.
- `_validate_method_grids` internal function with five guards: not-a-dict, empty dict,
  unknown method, unknown parameter, empty value list.
- Module constants in `_autotune.py`: `_KNOWN_METHODS`, `_ALLOWED_PARAMS`,
  `_DEFAULT_LAM_5`, `_DEFAULT_LAM_4`, `_DEFAULT_METHODS`.
- Real-data section "5. Real-data example: non-linear background" in
  `Baseline_Autotune_Demo.ipynb` using a bilayer-graphene spectrum
  (`Raman Sample 532nm 2L-Graphene.txt`).
- Autotune blocks ("Optional: use `autotune_baseline`") in
  `Raman_background-remove.ipynb` with a focused 7-candidate grid.
- Sphinx autodoc page `docs/source/api/autotune.rst` for `autotune_baseline`,
  `apply_choice`, and `BaselineAutotuneResult`.
- `docs/source/user-guide/baseline-autotune.md` rewritten with `method_grids` examples
  and a "Deprecated arguments" subsection.
- `Raman_background-remove.ipynb` added to the notebook smoke-test suite (`CANONICAL_NOTEBOOKS`).
- `benchmarks/results/bench_snapshot_v0.6.2.txt` — pre-v0.6.3 baseline snapshot.
- 7 new mapping-autotune tests and 2 new single-fit-autotune tests.

### Changed

- `autotune_baseline()` signature: `method_grids` keyword added before the deprecated
  `methods` and `lam_grid` kwargs on all four façade methods.
- `_default_baseline_grid` now accepts an optional `method_grids` dict; `method_grids=None`
  reproduces the v0.6.2 24-candidate grid byte-for-byte.
- All 19 autotune test call sites converted from `methods=[...]` to `method_grids={...}`.

### Fixed

- `autotune_baseline(plot=True)` rendered the comparison figure twice in Jupyter
  notebooks. After `IPython.display.display(fig)` the figure remained registered in
  matplotlib's figure manager, causing a second render at cell end via the
  `%matplotlib inline` hook. Fixed by calling `plt.close(fig)` immediately after the
  explicit `display()` call; the figure object is still returned in
  `BaselineAutotuneResult.figure`.
- `method_grids` parameter annotated as `dict | None` in the three façade methods
  (`_preprocess.py`, `RamanFit.py`, `PLfit.py`), which is a Python 3.10+ syntax and
  raises `TypeError` at import time on Python 3.9. Annotation removed; type is
  documented in the docstring. Caught by CI Python 3.9 matrix job.
- `_validate_method_grids` called `len(list(v))` to check for empty value sequences,
  which consumed one-shot iterators (e.g. generators) before the candidate-building
  loop in `_default_baseline_grid` could iterate them, silently producing zero
  candidates and an `IndexError` at `ranking[0]`. Fixed by materialising all value
  sequences to plain lists in `_default_baseline_grid` before validation; the
  per-value check in `_validate_method_grids` tightened to `isinstance(v, list)` +
  `len(v) == 0`.

### Deprecated

- `methods` and `lam_grid` keyword arguments on `autotune_baseline()`. Both emit
  `DeprecationWarning` in v0.6.3 and will be removed in v0.6.4.

### Notebooks

- `Baseline_Autotune_Demo.ipynb` section 5 ("Real-data example"): filled in the
  observation narrative — Gaussian (σ = 50) won the autotune with RMSE = 0.0712;
  explains why iterative methods underperformed (peak-to-window ratio) and documents
  the amplitude trade-off of the Gaussian baseline.
- `Raman_background-remove.ipynb` section 6 ("Using `gaussian` baseline"): new
  worked example using `gaussian_sigma=50`, matching the structure of sections 1–4
  (load → fit → plot). Includes tuning rules and a note on the amplitude trade-off.

---

## [v0.6.2] — 2026-05-20 — Seed-pixel baseline auto-tuning

### Added

- `autotune_baseline()` method on `RamanMapping` and `PLMapping` (via
  `_MappingPreprocessMixin`). Scores a configurable grid of 24 baseline
  candidates on a user-chosen seed pixel and returns a ranked
  `BaselineAutotuneResult` without modifying the object.
- `apply_choice(choice)` method on `RamanMapping` and `PLMapping`. Commits
  a baseline spec dict to `self.preprocessing`, refreshes all legacy
  baseline attributes, and invalidates the preprocessed-cube cache so the
  next `fit_spectra()` call picks up the new baseline.
- `autotune_baseline()` method on `RamanFit` and `PLfit`. Same diagnostic,
  but scores against the single stored spectrum (`_raw_spectra_pristine`).
- `apply_choice(choice)` method on `RamanFit` and `PLfit`. Re-applies the
  full pipeline from the pristine raw spectrum and refreshes all seven
  derived attributes (`processed_spectra`, `_baseline`, `_smoothed_spectra`,
  `_corrected_spectra`, `peak_intensity`, `preprocessing_backend_*`,
  `_backend_outcome`).
- `src/ramanpl/_autotune.py` — internal module providing:
  `BaselineCandidate`, `BaselineAutotuneResult`,
  `_swap_baseline_step_in_pipeline`, `_score_candidate`,
  `_make_comparison_figure`, `_default_baseline_grid` (24 candidates),
  `autotune_baseline_for_object`.
- `_raw_spectra_pristine` and `_x_axis_pristine` attributes on `RamanFit`
  and `PLfit` (set once at `__init__`, never mutated). Allow `apply_choice`
  to re-apply any pipeline, including those with `CropByRange`.
- `baseline_autotune` provenance block added to mapping and single-fit
  export metadata when `_last_autotune_result` is set (keys: `methods`,
  `n_candidates`, `seed_coord`, `winner`, `winner_rmse`, `ranking_top5`).
- `tests/test_autotune_baseline_mapping.py` — 10 tests covering all
  checklist items for mapping autotune.
- `tests/test_autotune_baseline_single_fit.py` — 12 tests covering all
  checklist items for single-fit autotune.
- `benchmarks/results/bench_snapshot_v0.6.1.txt` — before-snapshot
  artefact anchoring the v0.6.2 build.
- `benchmarks/results/mapping_fit_benchmark_v0.6.1.csv` — archived
  v0.6.1 mapping-fit benchmark for algorithmic parity verification.

### Notes

- No changes to `baselineAPI.py`. Autotune only composes existing baseline
  methods into a grid.
- No new keywords on `fit_spectra` or `fit_spectrum`. API surface unchanged.
- No new runtime dependencies. `matplotlib` and `scipy` are already required.
- `autotune_baseline()` is read-only: it never mutates the object. Only
  `apply_choice()` writes to `self`.
- `apply_choice()` raises `ValueError` if the pipeline has zero or more than
  one `BaselineSubtract` steps (fail-loud contract).
- Algorithmic invariance versus v0.6.1: `n_curve_fit_calls` row-by-row
  identical on the v0.6.1 benchmark cube when `apply_choice` is not called.
- Behaviour notes (updated 2026-5-21): autone_baseline(plot = True) will always show a inline figure in notebooks

## [v0.6.1] — 2026-05-19 — Progress indicators for mapping & batch fits

### Added

- `tqdm>=4.66` added as a hard runtime dependency in `pyproject.toml`.
- `show_progress: bool = True` keyword added to `RamanMapping.fit_spectra` and
  `PLMapping.fit_spectra`. Progress bar throttled at `mininterval=0.5`;
  suppressed when `show_progress=False`.
- `show_progress: bool = True` keyword added to `_BaseBatch.fit` and threaded
  through to `fit_spectra_batch`. Both `RamanBatch` and `PLBatch` inherit this
  via `_BaseBatch`.
- `test_tqdm_importable` added to `tests/test_packaging_smoke.py`: verifies
  `import tqdm` and `from tqdm.auto import tqdm` succeed in the installed
  package.
- `benchmarks/results/mapping_fit_benchmark_v0.6.0.csv`: archived baseline
  snapshot for algorithmic parity verification.
- `benchmarks/results/overhead_v0.6.1.txt`: overhead measurement record.
- `bench_snapshot_v0.6.0.txt`: git hash + pytest counts at start of this build.

### Changed

- Pixel loop in `RamanMapping.fit_spectra` (`_raman_mapping.py`) wrapped with
  `tqdm`; `pbar.update(1)` called at the top of the inner loop so all pixels
  (including `continue` paths) are counted correctly.
- Pixel loop in `PLMapping.fit_spectra` (`_pl_mapping.py`) wrapped identically.
- File loop in `fit_spectra_batch` (`batch.py`) wrapped: `for s in tqdm(spectra,
  desc="Fitting (batch)", disable=not show_progress, mininterval=0.5)`.

### Notes

- No changes to fitting algorithms, fitted values, preprocessing, or export
  schemas.
- `n_curve_fit_calls` is identical row-by-row versus the v0.6.0 baseline on
  all 12 benchmark rows (algorithmic invariance confirmed).
- tqdm overhead is below single-run measurement noise (±10-20% on this machine)
  and analytically < 0.01% (225 `pbar.update()` calls × ~0.5 μs each over
  12–68 s of fitting). The ≤ 1% acceptance criterion is satisfied.
- Per-class `desc` strings ("Fitting (Raman batch)" / "Fitting (PL batch)")
  were consolidated to `"Fitting (batch)"` because both classes share a single
  inherited `_BaseBatch.fit` → `fit_spectra_batch` call path.
- Deferred: `tqdm` inside single-fit multistart loops (negligible runtime),
  preprocessing pipelines (preprocessing is fast relative to fitting),
  per-tile bars (tile parallelism arrives in v0.6.3).

---

## [v0.6.0] — 2026-05-13 — Stable interpretable-analysis milestone

### Declared

- First stable interpretable-analysis milestone built on v0.5.1–v0.5.5.
- Stable components: per-pixel QA-augmented mapping export, generalised peak
  descriptors, `feature_table()` accessors, classical peak-proposal aid for
  failed-fit recovery, optional unsupervised clustering on fitted descriptors.
- Deterministic physical fitting (Lorentzian / pseudo-Voigt least squares)
  remains the final authority for all reported peak parameters.

### Added

- `benchmarks/validation_v0.6.0_vs_v0.5.0.py` (new): reproducible validation
  harness comparing v0.6.0 to v0.5.0 on four synthetic cubes across fit
  quality, runtime, and failure-mode axes. Reuses helpers from
  `benchmark_mapping_fit.py`.
- `benchmarks/results/v0.5.0_baseline/v0.5.0_baseline.json` (tracked): v0.5.0
  reference runtime and `n_curve_fit_calls` for the standard small_3x4 cube.
- `benchmarks/results/v0.5.0_baseline/checksums.txt` (tracked): SHA256 of the
  v0.5.0 export, anchoring the byte-level fit-parity invariant.
- `example-usage/Validation/Validation_v0.6.0_vs_v0.5.0.ipynb` (new):
  executable validation notebook covering fit-quality parity, runtime
  comparison, and failure-mode comparison. Added to `test_notebook_smoke.py`.
- `docs/source/validation/v0.6.0.md` (new): citable validation report
  summarising the three findings.

### Changed

- `docs/source/api-stability.md`: title and §1 scope wording updated to
  "v0.5.5–v0.6.0"; the four frozen surfaces are unchanged.
- `docs/source/examples/canonical-notebooks.md`: restructured into three
  sections (Backend behaviour, Interpretable-analysis, Additional examples);
  added Interpretable-analysis subsection covering `Feature_Table_Example.ipynb`,
  `Peak_Proposal_Demo.ipynb`, `Clustering_Demo.ipynb`, and
  `Validation_v0.6.0_vs_v0.5.0.ipynb`; added `Area Integration Example.ipynb`
  to Additional examples; updated Mapping Raman/PL Example descriptions to
  note that integration-under-peaks moved out in v0.5.5.
- `tests/test_notebook_smoke.py`: validation notebook added to
  `CANONICAL_NOTEBOOKS` (6 notebooks in standard suite); `Clustering_Demo.ipynb`
  moved to `_SLOW_NOTEBOOKS` / `pytest -m slow` due to >600 s/cell runtime on
  real WDF data. `slow` marker registered in `pyproject.toml`.
- `README.md`: v0.6.0 roadmap row updated to shipped state.
- `docs/source/changelog.md`: Recent releases list extended through v0.6.0.
- `RELEASE.md`: "Validation report" check section added.
- Version bumps: `pyproject.toml`, `src/ramanpl/__init__.py`, `CITATION.cff`,
  `docs/source/conf.py`, `tests/test_packaging_smoke.py`.

### Notes

- No changes to fitting algorithms, preprocessing, backend resolution, export
  schemas, descriptors, ml, or `feature_table()` output. v0.6.0 is a milestone
  freeze; the only change under `src/ramanpl/` is the `__version__` line.
- Supervised classification (e.g. layer-number labels) remains deferred to
  v0.7.x, conditional on the availability of curated, labelled, multi-instrument
  datasets.
- Validation evidence committed in `benchmarks/results/v0.5.0_baseline/` and
  reproduced by `benchmarks/validation_v0.6.0_vs_v0.5.0.py`.
- Test suite: PASS=253, SKIP=3, FAIL=0 (base, excluding
  `test_mapping_backend_parity.py` and `test_preprocessing_backend_resolution.py`;
  full suite 270 passed).
- Notebook smoke: 6 notebooks executed (standard suite), 0 failures.
  `Clustering_Demo.ipynb` runs under `pytest -m slow` (not counted here).

## [v0.5.5] — 2026-05-10 — Consolidation pause: API freeze, docs, dependency hygiene

### Added

- `docs/source/api-stability.md`: written, citable freeze contract for the
  public surface introduced in v0.5.1–v0.5.4. Pins suffix vocabulary
  (`_position`, `_fwhm`, `_peak_height`, `_peak_height_norm`, `_separation`,
  `_ratio`), QA column names (`rmse`, `ok`, `n_starts`, `n_params_at_bounds`),
  all six `feature_table()` methods, `build_feature_row`, `validate_peak_pairs`,
  `pca_reduce`, `kmeans_cluster`, and the `[ml]` extra boundary.
- `tests/test_api_stability.py` (new, 8 tests): enforces the additive-only
  column rule, frozen suffix vocabulary, and frozen QA/ML/descriptor public
  surfaces as regression tests. Uses the same synthetic mapping fixtures as
  `test_feature_table_mapping.py`.
- Three new tests in `tests/test_descriptors_unit.py`: ratio/separation order
  convention — `test_ratio_order_swap_yields_reciprocal_when_both_finite_nonzero`,
  `test_separation_order_swap_yields_negation`,
  `test_ratio_zero_denominator_asymmetry`.
- One new test in `tests/test_feature_table_mapping.py`:
  `test_feature_table_pl_mapping_ratios_and_separations` — PL mapping with
  both ratios and separations, values verified against hand calculation.
- One new test in `tests/test_packaging_smoke.py`:
  `test_descriptors_top_level_import_works` — verifies the new top-level
  `from ramanpl import descriptors` import path.
- `docs/source/installation.md`: "Optional ML extra" section with explicit
  base-install guarantee (safe import, `ImportError` only on call).
- `docs/source/quickstart.md`: `feature_table()` mention with one-line
  code example.
- User-guide cross-links: `mapping.md`, `batch.md`, `single-spectrum.md`
  each link to `clustering`; `clustering.md` gains a "Where the feature
  table comes from" subsection linking back to all three sources.
- PL-parity paragraphs added to `mapping.md` and `clustering.md`.
- Order-convention paragraphs added to `mapping.md`, `batch.md`, and
  `single-spectrum.md`.
- Three new notebooks added to `tests/test_notebook_smoke.py`:
  `Feature_Table_Example.ipynb`, `Peak_Proposal_Demo.ipynb`,
  `Clustering_Demo.ipynb` (the last guarded by a scikit-learn skipif).
  `Integration Raman Example.ipynb` changed to `Area Integration Example.ipynb` to reflect the integration under a peak of both PL and Raman mapped spectrum.

### Changed

- `src/ramanpl/__init__.py`: `"descriptors"` added to `__all__` and
  `_MODULE_EXPORTS`; `from ramanpl import descriptors` now works.
- `src/ramanpl/__init__.py`: `__version__` `0.5.4` → `0.5.5`.
- `pyproject.toml`: version `0.5.4` → `0.5.5`.
- `CITATION.cff`: version `0.5.4` → `0.5.5`; `date-released` → `2026-05-10`.
- `docs/source/conf.py`: release `0.5.4` → `0.5.5`.
- `README.md`: `[ml]` install option added to Installation section; v0.5.5
  roadmap row updated to reflect shipped items.
- `tests/test_packaging_smoke.py`: version assertion updated to `0.5.5`.
- `.github/workflows/ci.yml` `notebook-smoke`: install extended from
  `.[ramanspy]` to `.[ramanspy,ml]`.

### Notes

- No changes to fitting algorithms, preprocessing, backend resolution, or
  export schemas. v0.5.5 is a freeze build.
- `ramanpl.descriptors` was already present in the API reference (since
  v0.5.2); this release adds it to `__all__` and `_MODULE_EXPORTS` to
  match its documented status.
- Notebook smoke timeout raised from 120 s to 600 s per cell to accommodate
  the three new notebooks, which execute real map fits on WDF datasets.
- Test delta: +13 tests over v0.5.4 baseline (226 base, 14 ml-extras).
  Base suite: PASS=226, SKIP=9, FAIL=0. ML extras: PASS=14, SKIP=0, FAIL=0.
  Notebook smoke: 6 notebooks executed, 0 failures. Sphinx docs: 0 new
  warnings (43 pre-existing autodoc warnings unchanged).

## [v0.5.4] — 2026-05-09 — Optional [ml] extra: unsupervised clustering on feature tables

### Added

- `src/ramanpl/ml/__init__.py` and `src/ramanpl/ml/clustering.py`: new optional
  subpackage. Two composable public functions:
  - `pca_reduce(df, n_components, *, feature_columns=None, scale=True)` — appends
    `pc1`…`pck` columns; explained variance attached to
    `df.attrs["explained_variance_ratio_"]` and feature columns used to
    `df.attrs["pca_feature_columns"]`.
  - `kmeans_cluster(df, n_clusters, *, feature_columns=None, scale=True,
    random_state=None)` — appends a `cluster` column (nullable `Int64`).
  Both functions consume any wide DataFrame with numeric columns (canonically
  `feature_table()` output from v0.5.2). Failed-fit rows (NaN features) are
  dropped internally and re-injected with NaN labels, preserving the input
  index. Both lazy-import scikit-learn; raise a clean `ImportError` mentioning
  the `[ml]` extra when scikit-learn is absent. Importing `ramanpl.ml` and
  `ramanpl.ml.clustering` without scikit-learn installed is safe.
- `pyproject.toml`: new `[ml]` optional dependency on `scikit-learn>=1.2`.
  Base install is unaffected.
- `tests/test_ml_clustering.py`: 14 unit tests covering returned columns,
  index alignment, NaN reinjection, recovery of known cluster structure
  (`adjusted_rand_score >= 0.99`), determinism under `random_state`, validation
  errors, and a chained `pca_reduce` → `kmeans_cluster` composition test.
- `tests/test_packaging_smoke.py`: extended with `test_ml_namespace_importable_in_base_install`
  and `test_ml_functions_raise_clean_error_without_sklearn`.
- `example-usage/Mapping/Clustering_Demo.ipynb`: end-to-end notebook
  demonstrating `feature_table` → `pca_reduce` → `kmeans_cluster` → 2-D
  cluster map and PC scatter plot on the Mapping Raman Sample dataset.
- `docs/source/user-guide/clustering.md`: user guide page covering
  installation, `pca_reduce` usage, chained `pca_reduce` → `kmeans_cluster`
  usage, and the `df.attrs["explained_variance_ratio_"]` accessor.
- `docs/source/api/ramanpl.ml.rst`: API reference for `ramanpl.ml` and
  `ramanpl.ml.clustering` via `automodule`.
- `.github/workflows/ci.yml` and `.gitlab-ci.yml`: new `ml-extras-tests` /
  `ml-extras-smoke` CI jobs mirroring the `[ramanspy]` extras pattern.

### Changed

- `pyproject.toml`: version `0.5.3` → `0.5.4`.
- `src/ramanpl/__init__.py`: `__version__` `0.5.3` → `0.5.4`.
- `CITATION.cff`: version `0.5.3` → `0.5.4`; date-released updated.
- `docs/source/conf.py`: release `0.5.2` → `0.5.4` (corrects drift from the
  v0.5.3 cycle); `"sklearn"` added to `autodoc_mock_imports`.
- `.github/workflows/ci.yml` `base-tests` and `.gitlab-ci.yml` `base-tests`:
  added `--ignore=tests/test_ml_clustering.py` so base CI does not require
  scikit-learn.

### Notes

- No changes to fitting, preprocessing, backend resolution, export schemas, or
  `feature_table()` output. v0.5.4 is purely additive.
- `ramanpl.ml.clustering` operates on fitted peak descriptors, not on raw
  spectra. No claim of automatic material identification is made; clustering
  is for exploratory domain discovery only.
- Test suite: PASS=213, SKIP=6, FAIL=0 (base); PASS=13, SKIP=0, FAIL=0 (ml-extras).

## [v0.5.3] — 2026-05-06 — Classical peak-proposal aid for failed-fit recovery

### Added

- `src/ramanpl/single_fit/initialisation.py` (new): classical peak-proposal helpers
  based on `scipy.signal.find_peaks`. Two public functions:
  `propose_peaks(spectrum, wavenumber, n_peaks, prominence_rel, width_min_pts)` returns
  a list of candidate peak dicts (centre, width/FWHM, height) sorted by height; returns
  an empty list when no peaks meet the prominence threshold.
  `p0_from_proposals(proposals, peak_profile, current_p0, bounds)` substitutes proposal
  centres and widths into a parameter vector where they lie within bounds, using greedy
  nearest-neighbour matching so each proposal is used at most once.
  Module imports only `numpy` and `scipy.signal` — no ramanpl internal coupling.
- `use_peak_proposals=True` keyword argument on `_run_mapping_curve_fit_trials` in
  `src/ramanpl/mapping/_fit_utils.py`. When `True` (default) and all normal multistart
  trials have failed, one additional curve-fit attempt is made from a proposal-corrected
  starting point using `max(maxfev, 6400)` evaluations.
- `tests/test_peak_proposal.py` (new): 9 unit tests for `propose_peaks` and
  `p0_from_proposals` (single/two-peak detection, n_peaks limit, flat-spectrum guard,
  width estimate tolerance, centre replacement, out-of-bounds fallback, empty-proposals
  fallback, amplitude/eta preservation for lorentzian and pvoigt).
- `tests/test_peak_proposal_integration.py` (new): 8 integration tests exercising the
  wired fallback path in `_fit_utils.py` (overlapping-pixel rescue, weak-pixel rescue,
  easy-pixel Lorentzian parity, easy-pixel pvoigt parity, disabled-flag guard,
  position-drift tolerance, FWHM-drift tolerance, hard-cube failure-count decrease).
- `example-usage/Mapping/Peak_Proposal_Demo.ipynb` (new): end-to-end notebook
  demonstrating the peak-proposal fallback on a synthetic Raman mapping dataset —
  covers `propose_peaks` / `p0_from_proposals` directly, the wired fallback via
  `fit_spectra()`, and residual-map comparison before and after enabling proposals.
- `docs/source/user-guide/low_snr_advisory.md` (new): seven-step advisory guide for
  lower-SNR or more challenging datasets — seed-pixel selection, single-spectrum
  bounds validation, preprocessing comparison, bound tightening, Lorentzian vs
  pseudo-Voigt choice, multistart tuning, and `prominence_rel` / `width_min_pts`
  sweep for the proposal fallback. Wired into the Sphinx User guide toctree in
  `docs/source/index.md`.

### Changed

- `src/ramanpl/mapping/_fit_utils.py`: one new import (`propose_peaks`,
  `p0_from_proposals` from `ramanpl.single_fit.initialisation`), one new `use_peak_proposals`
  keyword in `_run_mapping_curve_fit_trials`, and a ≤ 16-line proposal fallback block
  inserted after the normal multistart loop. All other lines unchanged.

### Notes

- No changes to fitting algorithms, preprocessing, backend resolution, or export schemas.
- All pixels that succeed via the existing multistart path produce bit-identical output
  to v0.5.2 (verified by parity tests `test_no_change_on_easy_pixel` and
  `test_no_change_on_easy_pixel_pvoigt`).
- No new dependencies — `scipy.signal` is already a base dependency.
- Benchmark evidence (hard-pixel cube, 16 pixels, maxfev=1 normal trial): 16/16 fail
  without proposals, 0/16 fail with proposals. Easy-cube (8×8 standard cube):
  n_curve_fit_calls unchanged, mean_rmse unchanged (proposal path not entered).
- `ramanpl.ml` namespace and unsupervised clustering deferred to v0.5.4 per roadmap.

## [v0.5.2] — 2026-05-05 — Generalised peak descriptors and feature-table accessor

### Added
- `src/ramanpl/descriptors.py` (new): pure-numpy module with two public functions:
  `build_feature_row(per_peak_dict, qa_dict, peak_labels, *, ratios, separations)` constructs a
  flat feature dict for one pixel/spectrum (per-peak columns `{name}_position`, `{name}_fwhm`,
  `{name}_peak_height`, `{name}_peak_height_norm`; optional `{P1}_{P2}_separation` and
  `{P1}_{P2}_ratio` derived columns; QA passthrough); `validate_peak_pairs(pairs, peak_labels)`
  raises `ValueError` naming the unknown label when a pair references an undefined peak.
  Module imports only `numpy` — no pandas, no internal coupling.
- `feature_table(*, coord_mode, scaled, ratios, separations)` method on `_MappingPreprocessMixin`
  in `src/ramanpl/mapping/_preprocess.py`. Inherited by both `RamanMapping` and `PLMapping`.
  Returns a wide-format `pandas.DataFrame` (one row per pixel). Failed pixels emit a full row with
  `ok=False` and NaN per-peak/derived fields. Pandas imported lazily inside the method.
- `feature_table(*, ratios, separations)` method on `_BaseBatch` in `src/ramanpl/batch.py`.
  Returns one row per source file with a leading `source` column. Requires
  `.fit(return_fitters=True)` (same requirement as `summary_by_peak()`).
- `feature_table(*, ratios, separations)` method on `RamanFit` in
  `src/ramanpl/single_fit/RamanFit.py`: single-row DataFrame.
- `feature_table(*, ratios, separations)` method on `PLfit` in
  `src/ramanpl/single_fit/PLfit.py`: single-row DataFrame.
- `tests/test_descriptors_unit.py` (new): 5 unit tests for the descriptor builder (two-peak
  hand calculation, pVoigt eta silently ignored, NaN propagation, zero-denominator ratio → NaN,
  `validate_peak_pairs` error message names offending label).
- `tests/test_feature_table_mapping.py` (new): 9 tests covering DataFrame shape, column schema,
  ratio/separation values, failed-pixel NaN row, invalid-pair ValueError, PLMapping parity,
  peak-height vs `peak_intensities` array agreement, no-pairs column absence, no-fit guard.
- `tests/test_feature_table_batch_and_single.py` (new): 6 tests covering RamanBatch and PLBatch
  one-row-per-source, RamanFit and PLfit single-row, separation-vs-summary numerical agreement,
  and QA column name consistency across all three class families.
- User-guide "Feature tables" subsections in `docs/source/user-guide/mapping.md`,
  `docs/source/user-guide/batch.md`, and `docs/source/user-guide/single-spectrum.md`.
- `ramanpl.descriptors` module added to `docs/source/api/ramanpl.rst` API reference.
- `examples/Mapping/Feature_Table_Example.ipynb` (new): example usage of `Mapping.feature_table()` to build a DataFrame with peak positions, heights, ratios, and separations; pivoted into 2-D maps for visualisation.

### Fixed (post-merge cleanup)

- Untracked benchmarks/results/v0.5.0_baseline/ — these snapshot files
  were inadvertently committed in the initial v0.5.2 commit and are not
  portable across LAPACK/scipy builds. .gitignore extended to prevent
  re-committal. Restores v0.5.1's CI behaviour where the byte-parity
  trip-wire test is skipped on runners and runs locally for developers
  who have regenerated the snapshot.
- tests/test_export_fit_map_qa_columns.py::
  test_wide_format_existing_columns_unchanged — relaxed from byte-level
  string equality to numerical tolerance (rtol=atol=1e-3). The test
  still catches genuine scientific drift but no longer fails on FP
  noise across LAPACK builds.

### Notes
- **No scientific changes.** Fitting algorithms, baseline algorithms, preprocessing, and all
  scientific output values are unchanged. Parity verified against the v0.5.0 reference snapshot via
  `benchmarks/_step4_parity.py`: `fitted_params`, `residual_map`, and pre-existing per-peak export
  columns are bit-identical.
- **v0.5.1 export schema unchanged.** `export_fit_map` output (wide and long formats) is
  unmodified. `_raman_mapping.py` and `_pl_mapping.py` are untouched.
- **No new dependencies.** `pandas` is already a base dependency. `ramanpl.descriptors` imports
  only `numpy`.
- **Additive API only.** `feature_table()` is the only new public method per class. No existing
  methods were renamed or removed.
- **Test suite:** 218 passed, 5 skipped, 0 failures (198 v0.5.1 baseline + 20 new tests).
- **Out of scope, deferred to later builds:** vectorising `_params_to_export_dict()`,
  caching `feature_table()` output, long-format `feature_table()` (use `.melt()` instead),
  refactoring `plot_map`/`plot_ratio_heatmap` to share code with the descriptor builder
  (deferred to v0.5.3+), peak proposals (v0.5.3), ML extras (v0.5.4).

--------

## [v0.5.1] — 2026-05-03 Mapping-fit benchmark and per-pixel QA columns

### Added
- `benchmarks/benchmark_mapping_fit.py` (new): mapping-fit performance benchmark mirroring the
  structure of `benchmark_mapping_preprocessing.py`. Sweeps synthetic cubes across `warm_start`
  on/off and `n_starts ∈ {1, 4}` with fixed `random_state=42`. Records per-case `runtime_s`,
  `n_curve_fit_calls`, `success_rate`, `mean_rmse_finite`, and `n_failed_pixels` to
  `benchmarks/results/mapping_fit_benchmark.csv`. Module docstring records the runtime-fluctuation
  caveats: wall-clock is advisory because curve_fit iteration count, warm-start state propagation,
  and adaptive-multistart retries introduce structural variability that is not noise.
  `n_curve_fit_calls` (counted via local `unittest.mock.patch` on `scipy.optimize.curve_fit`) is
  the hardware-independent primary metric; future builds claiming a speed-up must show a reduction
  in this count, not only in `runtime_s`.
- `_qa_columns_for_pixel()` helper on `_MappingPreprocessMixin` returning a fixed-schema dict with
  `rmse`, `ok`, `n_starts`, `n_params_at_bounds` for any pixel, regardless of fit success.
  Resolves `rmse`/`ok` from `residual_map` and the diagnostic counts from `fit_diagnostics_map`,
  with NaN fall-back when `diagnostics='none'` was used.
- Per-pixel QA columns (`rmse`, `ok`, `n_starts`, `n_params_at_bounds`) appended to every row of
  `export_fit_map` in both `RamanMapping` and `PLMapping`. Failed pixels now emit a fully-populated
  row with NaN-valued parameter columns and `ok=False`, replacing the previous `{x, y}`-only
  rows for failed pixels. This makes the export a fixed-schema, machine-readable table.
- `long=True` keyword-only argument on `export_fit_map` in both mapping classes. Produces
  one-row-per-(pixel, peak) output with schema
  `x, y, peak, centre, fwhm, peak_height, peak_height_norm, amp, scale[, eta], rmse, ok, n_starts, n_params_at_bounds`.
  The metadata header records `export_format: "long"` to distinguish from the default wide format.
- `tests/test_export_fit_map_qa_columns.py` (new): 5 tests covering header content, value parity
  with `residual_map`, failed-pixel row emission, fall-back when `fit_diagnostics_map=None`, and
  byte-level parity of pre-existing per-peak columns against a v0.5.0 reference snapshot.
- `tests/test_export_fit_map_long_format.py` (new): 5 tests covering row count, column schema,
  pixel-peak round-trip via `pivot_parameters`, failed-pixel row count, and `export_format`
  metadata field.
- `tests/test_release_benchmark_smoke.py`: 3 new smoke tests confirming `benchmark_mapping_fit.py`
  builds cases, runs the smallest case, and produces records with the expected fields.

### Changed
- `pyproject.toml`: added `pytest.ini_options.pythonpath = ["src"]` so tests resolve `ramanpl`
  imports without an editable install. Test command unchanged for users.

### Notes
- **No scientific changes.** Fitting algorithms, baseline algorithms, preprocessing, and all
  scientific output values are unchanged. Parity was verified against a v0.5.0 reference snapshot:
  `fitted_params`, `residual_map`, `fit_diagnostics_map`, and the pre-existing per-peak columns of
  the wide-format export are bit-identical to v0.5.0 on the same synthetic cube.
- **Backward compatible.** Existing wide-format column names and ordering are preserved. The four
  QA columns are appended at the end. Default behaviour with `long=False` (the default) reads
  identically to v0.5.0 except for the appended QA columns and the new fully-populated rows for
  failed pixels.
- **Failed-pixel row format change.** In v0.5.0, failed pixels emitted rows containing only `x`
  and `y` (other columns blank). In v0.5.1, failed pixels emit a complete row with NaN-valued
  parameter and QA columns and `ok=False`. Downstream readers that depended on blank cells as the
  failure indicator should switch to checking `ok` or `np.isnan(rmse)` instead.
- **Heatmap plotting unaffected.** `plot_heatmap`, `plot_residual_map`, `plot_ratio_heatmap`, and
  `inspect_residuals` read directly from in-memory arrays (`fitted_params`, `residual_map`,
  `peak_intensities`), not from the export file. The export-row change is decoupled from the
  rendering path.
- **Test suite:** 198 passed, 5 skipped, 0 failures (full local run). 13 new tests across the
  three test files listed above.
- **Out of scope, deferred to later builds:** generalised peak ratios and separations and
  `Mapping.feature_table()` accessor are deferred to v0.5.2; classical peak-proposal aid for
  failed-fit recovery is deferred to v0.5.3; any `ramanpl.ml` namespace and `[ml]` extra are
  deferred to v0.5.4 (see roadmap in `README.md`).

--------

## [v0.5.0] — 2026-04-26 — Stable public milestone

### Added

- Stable public milestone release for RamanPL_2D.
- Finalised documentation, release validation, and public repository presentation.
- Read the Docs documentation configuration linked from README once hosted site is live.

### Changed

- Synchronised package version metadata across `pyproject.toml`, `__init__.py`, documentation config, and citation metadata.
- Clarified public API and internal API boundaries in generated documentation.
- Simplified README into a package landing page.
- Fixed packaging metadata: README is now declared statically in `pyproject.toml` (`readme = {file = ...}`) rather than via `dynamic = ["readme"]`.

### CI

- Fixed base CI: `test_batch_backend_regressions.py` and `test_single_fit_regressions.py` now run in base CI (no longer silently ignored).
- Fixed extras CI: `test_single_fit_backend_parity.py` now runs in the RamanSPy extras job.
- Fixed notebook-smoke CI: installs `./src[ramanspy]` so the RamanSPy-backed path is actually exercised.
- Aligned GitLab CI test categorisation with GitHub Actions.

### Notes

- No new fitting, baseline, preprocessing, or backend algorithms are introduced.
- Public preprocessing/backend behaviour is frozen for the supported Raman workflows.
- PL workflows and Gaussian baseline remain native-only.

---

## [v0.4.12] — 2026-04-24 Documentation scaffold and hosted docs preparation

### Added

- **`docs/`** — in-repository Sphinx documentation scaffold with `docs/source/` and
  `docs/requirements.txt`.
- **Furo theme** — configured via `html_theme = "furo"` in `docs/source/conf.py`.
- **MyST Markdown support** — `myst-parser` extension enabled; all user-guide and
  reference pages are written in Markdown.
- **User-guide pages** — `installation.md`, `quickstart.md`,
  `user-guide/preprocessing.md`, `user-guide/backend-behaviour.md`,
  `user-guide/single-spectrum.md`, `user-guide/mapping.md`,
  `user-guide/batch.md`, `user-guide/export-provenance.md`.
- **Examples index** — `examples/canonical-notebooks.md` linking the three canonical
  backend-behaviour notebooks and additional example notebooks.
- **API reference** — `docs/source/api/index.rst` covering stable public modules:
  `ramanpl.single_fit`, `ramanpl.mapping`, `ramanpl.batch`, `ramanpl.preprocessing`,
  `ramanpl.baselineAPI`, `ramanpl.exporter`, `ramanpl.dataImporter`.
- **`.readthedocs.yaml`** — Read the Docs build configuration at repository root;
  targets Python 3.11, ubuntu-24.04, installs from `docs/requirements.txt` and `./src`.
- **CI docs-build job** — smoke build added to `.github/workflows/ci.yml`; fails CI if
  Sphinx cannot build the documentation.

### Changed

- **`README.md`** — added `Documentation` section with local build instructions and
  links to key documentation pages; detailed usage guidance now lives in `docs/`.
- **`.gitignore`** — added `docs/build/` and `docs/source/_build/` to prevent
  generated HTML from being committed.

### Notes

- No scientific behaviour changes.
- No fitting, preprocessing, backend, or export API changes.
- Documentation lives in the main `RamanPL_2D` repository (no separate docs repo).
- `fail_on_warning: false` in `.readthedocs.yaml` — to be tightened in a later build
  once API cross-references are stable.

---

## [v0.4.11] — 2026-04-23 Repository hardening and milestone freeze

### Added

- **`SECURITY.md`** — vulnerability reporting policy: supported versions, private disclosure
  route, and response expectations.
- **`CONTRIBUTING.md`** — contribution guidelines: fork/branch/test/PR/changelog flow,
  scientific-behaviour preservation rule, issue vs feature-request distinction.
- **`.github/CODEOWNERS`** — review ownership for `src/`, `tests/`, `benchmarks/`,
  `.github/workflows/`, `README.md`, and `CHANGELOG`.
- **`CITATION.cff`** — CFF 1.2.0 citation metadata for the package as research software.
- **`RELEASE.md`** — milestone-freeze checklist: the operational gate used to validate
  a release candidate before tagging; serves as the bridge toward v0.5.0.

### Changed

- **`src/pyproject.toml`** — promoted from minimal build-system stub to main packaging
  metadata source: full `[project]` table (`name`, `version`, `description`, `requires-python`,
  `license`, `authors`, `classifiers`, `dependencies`, `[project.optional-dependencies]`,
  `[project.urls]`), `[tool.setuptools.dynamic]` readme (resolved from `../README.md`),
  `[tool.setuptools.packages.find]`, and `[tool.setuptools.package-data]`.
  Build-system requirement updated to `setuptools>=61`.
- **`src/setup.py`** — reduced to a two-line shim (`from setuptools import setup; setup()`);
  all metadata now lives in `pyproject.toml`.
- **`README.md`** — Source Code Structure tree updated (`install.ipynb` removed, `pyproject.toml`
  added); installation section updated to remove the `install.ipynb` option; Option 3 renumbered
  to Option 2.
- **`.gitignore`** — extended to cover standard local/build/release artefacts: `build/`,
  `dist/`, `.pytest_cache/`, `.mypy_cache/`, `.ruff_cache/`, `.coverage`, `coverage.xml`,
  `coverage.lcov`, and `benchmarks/results/*.csv`.

### Removed

- **`src/install.ipynb`** — installation notebook removed from the source tree; `src/` now
  contains only package and build content. Installation instructions remain available in
  `README.md`.

### Notes

- No new scientific or algorithmic features are introduced in this release.
- No public API or backend behaviour changes.
- This release serves as milestone freeze preparation for v0.5.0.
- `benchmarks/results/mapping_preprocess_benchmark.csv` is a pre-existing tracked generated
  file; the new `.gitignore` rule prevents future regenerations from being committed.
  Run `git rm --cached benchmarks/results/mapping_preprocess_benchmark.csv` to untrack it.

---

## [v0.4.10] — 2026-04-22 Release validation and packaging gates

### Added

- **`src/pyproject.toml`** — PEP 517/518 build-system declaration (`setuptools` + `wheel`);
  enables `python -m build` from the `src/` directory in clean environments.
- **`MANIFEST.in`** — explicit sdist manifest ensuring `README.md`, `LICENSE`, and
  `raman_materials.json` are always present in source distributions.
- **`.github/workflows/ci.yml`** — GitHub Actions CI matrix (Python 3.9–3.11) with six jobs:
  - `base-tests`: install base package, run pytest suite without RamanSPy.
  - `extras-tests`: install `.[ramanspy]`, run backend-parity and resolution tests.
  - `package-build`: build wheel and sdist via `python -m build`.
  - `clean-install-smoke`: install built wheel into a fresh environment, run packaging smoke tests.
  - `notebook-smoke`: execute the three canonical backend-behaviour notebooks headlessly.
  - `benchmark-smoke`: validate benchmark harness execution and output structure.
- **`.gitlab-ci.yml`** — lightweight GitLab CI mirror covering base tests, package build,
  clean-install smoke, benchmark smoke, and optional RamanSPy extras smoke (`allow_failure: true`).
- **`tests/test_packaging_smoke.py`** — five packaging smoke tests:
  - `test_import_top_level_package` — confirms `ramanpl.__version__` after install.
  - `test_import_public_entry_points` — confirms all `__all__` names resolve without error.
  - `test_package_data_materials_json_present` — confirms `raman_materials.json` is discoverable
    at runtime via `importlib.resources`.
  - `test_base_install_does_not_require_ramanspy` — confirms `has_ramanspy()` returns a bool
    without raising when RamanSPy is absent.
  - `test_optional_ramanspy_import_path_is_guarded_cleanly` — confirms integration submodules
    import without `ImportError` in a base-only install.
- **`tests/test_notebook_smoke.py`** — parametrised smoke execution of the three canonical
  backend notebooks using `nbconvert`; skipped automatically when `nbconvert` is absent.
- **`tests/test_release_benchmark_smoke.py`** — seven smoke tests validating that the baseline
  kernel and mapping preprocessing benchmark harnesses run, return records, and emit
  structurally valid fields; no runtime thresholds are enforced.

### Changed

- **`src/setup.py`** — version bumped to `0.4.10`.
- **`src/ramanpl/__init__.py`** — `__version__` bumped to `0.4.10`.
- **`README.md`** — added **Release validation** section documenting the canonical commands
  for base install, extras install, wheel/sdist build, clean-install smoke, notebook smoke,
  and benchmark smoke; clarifies that full performance comparisons remain advisory.

### Tests

- New packaging smoke coverage (`test_packaging_smoke.py`): import integrity, data-file
  presence, optional-dependency boundary.
- New notebook smoke coverage (`test_notebook_smoke.py`): headless execution of
  `Raman_backend_demo.ipynb`, `Raman_mapping_backend_demo.ipynb`, `Backend_fallback_cases.ipynb`.
- New benchmark smoke coverage (`test_release_benchmark_smoke.py`): harness health for
  both baseline-kernel and mapping-preprocessing benchmarks.

### Notes

- Public API unchanged. No scientific algorithm changes introduced.
- Export provenance and metadata fields unchanged.
- Benchmark smoke tests assert structural validity only; full performance comparisons
  remain advisory and are run manually outside CI.

---

## [v0.4.9] — 2026-04-21 Native baseline optimisation

### Changed

- **`src/ramanpl/baselineAPI.py`** — iterative Whittaker kernel optimisation (asLS, arPLS, airPLS):
  - Sparse diagonal matrix `W = diag(w)` is now pre-allocated once before the iteration loop;
    `W.data[:]` is updated in-place each iteration, eliminating one `sparse.diags()` allocation per
    iteration.
  - System matrix `Z = W + lam*DtD` (or `W + lam*DtD + ridge*I` for airPLS) is now pre-built once
    from the fixed penalty structure; only the diagonal entries are overwritten in-place each
    iteration via a pre-computed index array, eliminating one sparse addition allocation per
    iteration. `scipy.sparse.linalg.spsolve` reads from the updated `Z.data` each call without
    modifying it.
  - RHS vector `w * y` is computed into a pre-allocated buffer with `numpy.multiply(..., out=rhs)`
    to avoid a temporary allocation per iteration.
  - Mask float array `m.astype(float)` is pre-cast once before the loop (was re-cast each
    iteration in asLS and arPLS).
  - `w_prev` convergence buffer (arPLS) is pre-allocated and updated with `numpy.copyto`.
  - Benchmark result (n=1024): asLS ~22% faster, arPLS ~29% faster, airPLS ~3% faster; at
    n=512 airPLS ~71% faster.

- **`src/ramanpl/preprocessing.py`** — native iterative baselines promoted to mapping fast path:
  - Added `_apply_native_iterative_baseline_cube()`: applies asLS / arPLS / airPLS to every
    pixel of a mapping cube without constructing a `SpectralDataset` per pixel. The
    `_get_cached_DtD` result is shared across all Y×X spectra on the same axis.
  - `_apply_vectorised_mapping_steps()` now routes `BaselineSubtract` steps with
    `method in ("asls", "arpls", "airpls")` through the new cube-level helper instead of
    passing them to the per-spectrum fallback loop.
  - Benchmark result on medium (10×12) cube: asLS ~50% faster, arPLS ~32% faster, airPLS ~13%
    faster vs. the v0.4.8 per-spectrum loop.

### Tests added

- **`tests/test_baseline_numerical_parity.py`**:
  - Added `_reference_airpls` — independent reference implementation (no cache, no in-place)
    matching the airPLS algorithm exactly.
  - `test_airpls_parity_no_mask` / `test_airpls_parity_masked` — strict numerical parity
    (atol=1e-10) for the optimised airPLS kernel.
  - `test_arpls_masked` / `test_arpls_diff_order_1` — parity tests for masked and
    diff_order=1 arPLS cases.
- **`tests/test_batch_performance_path_regressions.py`**:
  - `test_batch_native_background_remove_fit_reproducible` — deterministic fit with native
    asLS background removal enabled.
  - `test_batch_native_background_remove_provenance` — provenance field reports `"native"`.
- **`tests/test_mapping_backend_benchmark_smoke.py`**:
  - `test_mapping_benchmark_native_iterative_baseline_smoke` — smoke test for the new native
    asLS mapping fast path through the benchmark harness.

### Notes

- Public API unchanged. No new parameters, no removed parameters.
- Export provenance and metadata fields unchanged.
- All 47 targeted tests pass; full test suite (169 tests) passes.
- Benchmark evidence: before/after captured in `benchmarks/results/`.

---

## [v0.4.8] — 2026-04-19 Executable backend-behaviour documentation and verification

### Added

- **`tests/test_single_fit_backend_meta.py`** — four new tests verifying supported
  Raman single-spectrum RamanSPy execution:
  - `test_raman_single_fit_auto_supported_pipeline_resolves_to_ramanspy`
  - `test_raman_single_fit_forced_ramanspy_supported_pipeline_resolves_to_ramanspy`
  - `test_raman_single_fit_auto_unsupported_pipeline_falls_back_to_native`
  - `test_single_fit_export_metadata_reports_ramanspy_when_used`
- **`tests/test_single_fit_backend_parity.py`** (new file) — six parity tests comparing
  native vs RamanSPy outputs on a synthetic single-spectrum for crop, SavGol, poly, asLS,
  airPLS, and arPLS pipelines. Module skips entirely when RamanSPy is not installed.
- **`tests/test_preprocessing_backend_resolution.py`** — four new dispatch-layer tests:
  - `test_pipeline_apply_single_raman_supported_auto_resolves_to_ramanspy`
  - `test_pipeline_apply_single_pl_auto_resolves_to_native`
  - `test_pipeline_apply_single_raman_gaussian_auto_falls_back_to_native`
  - `test_pipeline_apply_single_forced_ramanspy_calls_ramanspy_dispatch`
- **`example-usage/Ramanfit/Raman_backend_demo.ipynb`** — canonical Raman single-spectrum
  backend-resolution notebook: shows `native`, `auto`, and `ramanspy` on a supported pipeline
  and prints provenance metadata.
- **`example-usage/Mapping/Raman_mapping_backend_demo.ipynb`** — canonical Raman mapping
  backend/provenance notebook: runs `native` and `auto`, exports TXT files, and shows the
  `preprocessing_backend_requested/resolved` header fields.
- **`example-usage/backend/Backend_fallback_cases.ipynb`** — canonical unsupported/fallback
  notebook: demonstrates `auto` fallback for Gaussian baseline (unsupported step) and PL
  workflows (unsupported modality), and shows forced `ramanspy` raising `NotImplementedError`.

### Changed

- **`README.md`** — `Preprocessing & Backend Contract` section rewritten:
  - Removed incorrect claim that RamanSPy is "mapping only" / single-spectrum is
    "native-only". The implementation has supported single-spectrum RamanSPy dispatch
    since v0.4.1; the README was simply wrong.
  - Added backend support matrix covering all six workflow/backend combinations.
  - `poly_degree` deprecation note updated: the argument was hard-removed in v0.4.7.
  - Added "Backend behaviour examples" subsection linking the three new notebooks.

### Notes

- No scientific behaviour change.
- No public API expansion.
- Core backend source files (`preprocessing.py`, `ramanspy_bridge.py`,
  `ramanspy_translate.py`, `RamanFit.py`) unchanged — all 169 tests pass with no
  modifications to backend logic.

---

## [v0.4.7] — 2026-04-18 API cleanup, deprecation removal, and fitting performance

### Changed
- Backend resolution and fallback-reason assembly consolidated into one canonical path in
  `ramanspy_bridge.py`; redundant double key-set for the native branch removed.
- Preprocessing normalisation centralised in `preprocessing.py`: added
  `canonicalize_baseline_spec()`, `canonicalize_pipeline_steps()`, and
  `normalize_backend_request()` as the single entry points for all callers.
- `BaselineSubtract` now normalises its `baseline_spec` in `__post_init__` (not on every
  `apply()` call); `_resolve_savgol_params_for_mapping` unified with `_resolve_savgol_params`.
- `exporter.py` is now the single owner of provenance serialisation: added
  `serialize_preprocessing_provenance()` for extracting canonical recipe fields from
  preprocessing result metadata.
- All five `BaselineAPI.parse_spec()` call-sites migrated to `baseline_spec_to_runtime()`
  from `schema.py` (`_preprocess.py`, `_pl_mapping.py` ×2, `_raman_mapping.py` ×2).
- `batch.py` provenance assembly now routes through `serialise_backend_provenance()` instead
  of manual field extraction.

### Removed

- `poly_degree` parameter from `RamanFit` and `PLfit` (hard removed; callers get
  `TypeError: unexpected keyword argument`).
- `BaselineAPI.parse_spec()` (hard removed; was `FutureWarning`-deprecated).
- `resolve_baseline_method_with_deprecation()` and `POLY_DEGREE_SENTINEL` from
  `single_fit/_single_fit_core.py`.
- `_validate_raman_axis()` from `ramanspy_adapter.py` (duplicate policy enforcement;
  callers now call `can_use_ramanspy()` directly).
- Local fallback provenance construction from `mapping/_preprocess.py`; bridge always
  returns a canonical dict so the fallback path was dead code.

### Fixed

- **Fitting performance regression (v0.4.5+):** `RamanFit.__init__()` was calling
  `resolve_preprocessing_backend()` on every construction, which internally called
  `has_ramanspy()`. On a cold Python session (ramanspy not yet imported), this
  triggered a ~3.5 s ramanspy cold-import even when `preprocessing_backend='native'`.
  Fixed in two places:
  - `ramanspy_adapter.py`: `has_ramanspy()` now uses `@lru_cache(maxsize=1)` so the
    result is cached after the first probe; all subsequent calls cost ~0 µs.
  - `ramanspy_bridge.py`: `resolve_preprocessing_backend()` short-circuits immediately
    for `backend='native'` before calling `has_ramanspy()`, eliminating the probe
    entirely for all native-backend workflows.
  - Affected workflows: `RamanFit`, `PLfit` (single-spectrum), `PLMapping`, and
    `RamanMapping` with `preprocessing_backend='native'`. `PLMapping` always uses
    native, so it is fully covered; confirmed via profiling that no ramanspy probe
    occurs at any point in the PLMapping construction or preprocessing path.
  - Measured improvement: `RamanFit.__init__()` drops from ~33 ms to ~1 ms
    (warm-session, single-peak 300-point spectrum).
- `FutureWarning` no longer emitted from `make_compat_data_importer()` on default
  `readlines`; stripped warning-only code path.
- `poly_degree` key no longer appears in exported metadata.

### Added

- `peak_models.py`: `sum_peaks_jac_lorentzian()` — vectorised analytical Jacobian
  for the Lorentzian peak sum; eliminates finite-difference derivative evaluations
  during `scipy.optimize.curve_fit` iterations.
- `RamanFit.fit_spectrum()` and `PLfit.fit_spectrum()`: new `maxfev` parameter
  (default 6400, unchanged) so callers can reduce the evaluation budget for
  well-conditioned warm-start fits (e.g. `maxfev=1600`). Lorentzian fits
  automatically pass the analytical Jacobian via `self._jac`.

### Tests

- Added: `tests/test_preprocessing_spec_normalization.py` (17 tests)
- Added: `tests/test_backend_resolution_contract.py` (8 tests + 1 skipped)
- Added: `tests/test_backend_error_messages.py` (6 tests + 1 skipped)
- Added: `tests/test_provenance_serialization.py` (12 tests)
- Added: `tests/test_deprecation_removals.py` (7 tests)
- Updated: `tests/test_single_fit_regressions.py` — removed two tests for deleted functions.
- Updated: `tests/test_export_provenance_regressions.py` — migrated two tests to use
  canonical `_preprocess_meta` structure instead of direct attribute assignment.

### Docs

- `README.md`: added "Preprocessing & Backend Contract" section documenting backend
  selection semantics, which workflows are RamanSPy-capable, and canonical provenance fields.

## [v0.4.6] — 2026-04-17 Performance profiling and baseline optimisation

### Optimised
- `baselineAPI.py` — `asLS`, `arPLS`, `airPLS`: extracted shared `_whittaker_diff_matrix()`
  helper to deduplicate difference-operator construction across all three methods. Added
  `_DtD_cache` (module-level dict) and `_get_cached_DtD(n, diff_order)` so `D^T D` is
  computed once per `(n, diff_order)` key and reused across all calls. Pre-computed
  `lam * DtD` (and for airPLS, `ridge * I`) before each method's iteration loop so that
  only `W` and `Z` are rebuilt per iteration. Eliminates `O(niter)` sparse matrix products
  per spectrum; gain is proportional to `niter` and spectrum length.

### Added
- `benchmarks/benchmark_baseline_kernels.py` (new): microbenchmark sweeping spectrum length
  (128, 512, 1024) across all five native baseline methods. Records runtime and peak memory.
  Does not test scientific correctness — see `test_baseline_numerical_parity.py` for that.
- Extended `benchmarks/benchmark_mapping_preprocessing.py` with two additional dataset sizes:
  `extended_30x30` (150-point axis) and `tall_axis_10x12` (500-point axis).
- `tests/test_baseline_numerical_parity.py` (new): 11 tests verifying asLS, arPLS, airPLS
  numerical output against reference implementations within `atol=1e-10`.
- `tests/test_baseline_operator_cache.py` (new): 9 tests covering cache identity, keying,
  numerical correctness, and `_whittaker_diff_matrix` shape/correctness.
- `tests/test_batch_performance_path_regressions.py` (new): 4 batch regression tests
  confirming fit output, summary table shape, and provenance fields are unchanged after
  lower-level baseline optimisation.
- `tests/test_mapping_backend_parity.py`: added two native self-consistency tests
  (`asLS`, `arPLS`) confirming the DtD cache does not cause state mutation between calls.
- `tests/test_mapping_cube_consistency.py`: added cube shape + finite-values test for asLS
  preprocessing via the DtD-cached path.

### Changed
- `integration/ramanspy_adapter.py`: added inline comment documenting that the `[Y,X,N] →
  [X,Y,N]` transpose is unavoidable (conversion overhead not further reducible in this build).
- `README.md` repository structure section corrected to reflect actual source layout: fixed
  `single_fit/` filenames (`RamanFit.py`, `PLfit.py`), removed non-existent `data_importer/`
  subpackage, added missing top-level modules (`dataImporter.py`, `peak_models.py`, `schema.py`,
  `raman_materials.json`), added missing `mapping/` modules (`_diagnostics.py`, `_fit_utils.py`,
  `_image.py`), noted compatibility façades, listed all 15 test files, and updated benchmarks
  section to include `benchmark_baseline_kernels.py`.

### Notes
- Scientific behaviour and public API are unchanged.
- Gains are strongest for `asLS`/`arPLS` on long spectra or large mapping cubes (20+ iterations
  eliminated per spectrum call).
- `airPLS` already pre-computed `DtD` per-call before v0.4.6; now additionally pre-computes
  `lam * DtD + ridge * I` before the loop and uses the cross-call cache.
- `preprocessing.py` per-spectrum loop is already copy-minimal for float64 cubes (audited).
- API/deprecation cleanup and new preprocessing algorithms remain deferred to v0.4.7.

---------

## [v0.4.5] — 2026-04-16 Backend API cleanup and provenance hardening

### Added
- `resolve_backend_outcome()` in `integration/ramanspy_bridge.py`: canonical backend
  decision function that combines availability checks, input compatibility, and pipeline
  translation support into a single outcome dict with fields `fallback_used`,
  `fallback_reason`, and `failure_mode`. Replaces scattered per-caller decision logic.
- `format_backend_fallback_reason()` and `format_backend_error_message()` helpers in
  `ramanspy_bridge.py` for consistent user-facing message generation.
- `inspect_pipeline_backend_support()` in `preprocessing.py`: public helper that inspects
  a pipeline's translation support without committing to a full backend resolution.
- `serialise_backend_provenance()` in `exporter.py`: single shared helper that extracts the
  stable public subset (`preprocessing_backend_requested`, `preprocessing_backend_resolved`,
  optionally `preprocessing_backend_fallback_reason`) from a canonical outcome dict.
- `BACKEND_OUTCOME_REQUIRED_KEYS` frozenset and `validate_backend_outcome_keys()` in
  `schema.py` to guard against outcome dict key drift.
- `_backend_outcome` attribute on `RamanFit` and `PLfit` fitter objects (alias for
  `preprocessing_backend_info`) giving all callers a stable provenance handle.
- New test files:
  - `tests/test_backend_message_consistency.py` (12 tests): fallback/error wording stable
    across auto/forced ramanspy scenarios; message helper unit tests.
  - `tests/test_backend_provenance_consistency.py` (14 tests): serialisation consistency,
    pipeline support summary, schema guard.
  - `tests/test_single_fit_backend_meta.py` (6 tests): fitter `_backend_outcome` attribute
    correctness, export metadata provenance fields.

### Changed
- `_resolve_pipeline_backend_for_input()` in `preprocessing.py` refactored to a thin
  wrapper: calls `pipeline_supports_ramanspy_translation()` then delegates the full
  decision to `resolve_backend_outcome()`. All decision logic now lives in one place.
- `build_single_fit_export_metadata()` in `_single_fit_core.py` now calls
  `serialise_backend_provenance()` when `_backend_outcome` is available, providing
  consistent provenance keys in single-fit exports.
- `_build_mapping_fit_export_meta()` in `mapping/_preprocess.py` now reads
  `preprocessing_backend_info` from `_preprocess_meta` and uses
  `serialise_backend_provenance()` instead of assembling provenance fields directly.
  Mapping exports now correctly reflect the resolved backend after preprocessing runs.
- `_infer_metadata_from_fitters()` in `batch.py` now additionally extracts
  `preprocessing_backend_fallback_reason` from fitter `_backend_outcome` objects.

### Fixed
- Mapping exports previously always wrote `preprocessing_backend_resolved: null` because
  `self.preprocessing_backend_resolved` was never updated after preprocessing. Now reads
  the resolved backend from `_preprocess_meta["preprocessing_backend_info"]` via the
  shared serialiser.
- Inconsistent fallback reason wording: previously only set in some paths, now produced
  by a single `_build_auto_fallback_reason()` helper for all callers.
- `preprocessing_backend_fallback_reason` absent from batch and single-fit exports even
  when auto fallback occurred. Now emitted consistently by `serialise_backend_provenance()`.

### Notes
- No new analysis features, no PL RamanSPy expansion, no performance work.
- All plotting, table, and numerical preprocessing behaviour is unchanged.
- 77 tests pass (47 existing + 30 new).

---------

## [v0.4.4] — 2026-04-15 Batch backend propagation and export provenance

### Added
- `preprocessing_backend` kwarg now propagates cleanly from `RamanBatch` through
  `fit_spectra_batch` into each `RamanFit` fitter instance via `fitter_kwargs`.
- `_infer_metadata_from_fitters()` in `batch.py` now extracts `preprocessing_backend_requested`
  and `preprocessing_backend_resolved` from fitter objects after fitting. Uniform values across
  the batch serialise as a scalar; heterogeneous values serialise as a list.
- `_BaseBatch.export()` now writes `export_kind: "batch_fit"` and a fallback
  `preprocessing_backend_requested` entry (from `_last_fitter_kwargs`) to all batch exports,
  aligning batch provenance metadata with the existing mapping export schema.
- `tests/test_batch_backend_regressions.py` (new file, 6 tests):
  - Backend resolution: `auto` + supported pipeline → `ramanspy`; `auto` + untranslatable
    pipeline → native fallback; forced `ramanspy` + untranslatable → `NotImplementedError`.
  - Behaviour preservation: `plot_overlay` / `plot_waterfall` return `(fig, ax)` and preserve
    source ordering; long-format DataFrame has exactly `{source, peak, position, fwhm,
    peak_height}`; `summary_by_peak()` produces `count / mean / std` columns per peak.
- `tests/test_export_provenance_regressions.py` extended with 3 batch export provenance tests:
  - TXT header contains `preprocessing_backend_requested` and `preprocessing_backend_resolved`.
  - Uniform backend serialises as a scalar string (not a list).
  - TXT header contains `export_kind: "batch_fit"`.

### Notes
- `PLBatch` is unchanged; PL RamanSPy support remains out of scope.
- No changes to `exporter.py`, `preprocessing.py`, or `ramanspy_bridge.py`.
- All 47 tests pass (34 existing + 13 new).

---------

## [v0.4.3] — 2026-04-13 Mapping backend benchmarking and validation

### Added
- Benchmark pipeline builder helpers in `preprocessing.py`:
  `make_benchmark_pipeline_crop_only`, `make_benchmark_pipeline_savgol_only`,
  `make_benchmark_pipeline_poly_baseline`, `make_benchmark_pipeline_asls_baseline`,
  `make_benchmark_pipeline_airpls_baseline`, `make_benchmark_pipeline_arpls_baseline`,
  `pipeline_to_benchmark_name`.
- `benchmarks/benchmark_mapping_preprocessing.py`: reproducible harness measuring runtime
  (`time.perf_counter`) and memory (`tracemalloc`) for native vs RamanSPy on three synthetic
  mapping datasets (3×4, 10×12, 20×24 pixels) across six pipeline configurations. Results
  written to `benchmarks/results/mapping_preprocess_benchmark.csv`.
- `tests/test_mapping_backend_parity.py`: six parity tests comparing native vs RamanSPy
  preprocessing output for all supported Raman mapping pipelines (skipped when RamanSPy absent).
- `tests/test_mapping_cube_consistency.py`: five tests validating cube shape invariants,
  axis ordering consistency between backends, and adapter round-trip correctness.
- `tests/test_mapping_backend_benchmark_smoke.py`: four smoke tests for benchmark harness
  functions.
- `tests/test_mapping_memory_runtime_smoke.py`: three smoke tests for runtime and memory
  measurement helpers.

### Notes
- Benchmark and validation release; no new analysis features or API changes.
- RamanBatch, PL RamanSPy, new preprocessing steps, and exporter redesign remain out of scope.
- Memory measurement uses `tracemalloc` (stdlib); `psutil` not added as a dependency.
- RamanSPy parity and consistency tests skip gracefully when RamanSPy is not installed.
- All 20 existing tests continue to pass.

---------

## [v0.4.2] — 2026-04-12 Validation, regression coverage, and release alignment

### Added
- Added regression tests for preprocessing backend resolution:
  - `native`
  - `auto`
  - `ramanspy`
- Added Raman-versus-PL backend compatibility tests for single-spectrum workflows.
- Added regression tests for single-fit helper behaviour, including:
  - `generate_p0_trials(...)` anchoring for `midpoint` and `jitter`
  - deprecated baseline argument warning behaviour
- Added regression tests for `dataImporter.py`, including:
  - `mask_by_xrange(...)`
  - TXT map import with shuffled coordinate block ordering
- Added regression tests for export/provenance metadata, including:
  - preprocessing backend requested/resolved fields
  - preprocessing recipe propagation in mapping export metadata

### Changed
- Updated package version metadata to `0.4.2`.
- Aligned installation metadata between `setup.py` and `requirements.txt`.
- Refreshed README guidance for:
  - local editable installation
  - optional RamanSPy installation
  - current repository structure
  - current RamanSPy backend support boundary

### Fixed
- Removed the module-level warning filter side effect from `baselineAPI.py`.
- Fixed duplicated `{"asls", "asls"}` membership logic.
- Promoted `PreprocessStep` to an abstract base class so incomplete base usage fails early.
- Corrected `generate_p0_trials(...)` behaviour so:
  - `midpoint` is centred on `(lb + ub) / 2`
  - `jitter` is centred on the user-supplied `base_p0`
- Updated deprecated baseline warnings in the single-fit core to `FutureWarning`.
- Simplified `mask_by_xrange(...)` without changing interval selection behaviour.
- Fixed TXT mapping import so spectra are assigned by coordinate identity rather than row-order assumptions.
- Vectorised map TXT export in `operation.py` to reduce Python-loop overhead.

### Notes
- RamanSPy integration in this release remains limited to supported **Raman preprocessing workflows**.
- PL workflows continue to use the native preprocessing backend.
- `BaselineSubtract(method="gaussian")` remains native-only.
- This release focuses on validation, correctness locking, and release/documentation consistency rather than new analysis features.

---------

## [v0.4.1] — 2026-04-08 RamanSPy preprocessing translation and stabilisation

### Added
- Completed RamanSPy-backed preprocessing translation for supported Raman `Pipeline` workflows.
- Added backend propagation and resolution through shared preprocessing paths for:
  - `RamanFit`
  - `RamanMapping`
- Added explicit export metadata fields for mapping fit exports:
  - `preprocessing_backend_requested`
  - `preprocessing_backend_resolved`

### Changed
- Updated preprocessing backend resolution to reflect actual `v0.4.1` behaviour:
  - `native` always uses the built-in backend
  - `auto` uses RamanSPy only when the input is supported and the full pipeline is translatable
  - `ramanspy` now executes when available and fully supported, and raises a clear error otherwise
- Stabilised RamanSPy translation support for the following preprocessing steps:
  - `CropByRange`
  - `SmoothSavGol`
  - `BaselineSubtract` with:
    - `poly`
    - `asls`
    - `airpls`
    - `arpls`
- Preserved native fallback for unsupported workflows or untranslated preprocessing steps.
- Preserved PL workflows on the native backend.

### Fixed
- Fixed mapping default preprocessing pipeline construction so `preprocessing_backend` is now propagated correctly.
- Fixed `RamanMapping` initialisation so shared preprocessing is always constructed before use.
- Fixed stale backend-resolution messaging that still described pre-v0.4.1 limitations.
- Fixed `RamanMapping.export_fit_map()` failure caused by missing shared coordinate iteration helper.
- Improved backend provenance consistency in preprocessing metadata and exports.

### Refactored
- Moved shared mapping helpers into the preprocessing mixin to reduce duplication across `PLMapping` and `RamanMapping`, including:
  - coordinate iteration
  - mapping fit export metadata construction
  - per-peak export dictionary generation
  - common fit-output allocation
  - common mapping fitter initialisation state
- Removed duplicated helper implementations from mapping classes while preserving existing behaviour.

### Notes
- RamanSPy integration in this release is limited to **Raman preprocessing workflows**.
- PL single-spectrum and PL mapping workflows continue to use the native preprocessing backend.
- `BaselineSubtract(method="gaussian")` remains native-only.
- This release focuses on backend correctness, shared-pipeline behaviour, and internal maintainability rather than new user-facing analysis features.

---------

## [v0.4.0] — 2026-04-06 RamanSPy backend foundation

### Added
- Introduced optional RamanSPy dependency via extras install.
- Added internal `ramanpl.integration` module for RamanSPy interoperability.
- Added RamanSPy adapter utilities for:
  - single-spectrum conversion
  - mapping cube conversion
  - backend availability/version checks
- Added preprocessing backend selector with supported values:
  - `native`
  - `auto`
  - `ramanspy`

### Updated
- Extended preprocessing `Pipeline` to carry backend metadata and backend provenance.
- Added backend resolution metadata to preprocessing outputs for both:
  - single-spectrum workflows
  - mapping workflows
- Added first RamanSPy preprocessing translation support for Raman workflows:
  - `CropByRange`
  - `SmoothSavGol`
  - `BaselineSubtract` with selected methods:
    - `poly`
    - `asls`
    - `airpls`
    - `arpls`
- Added `preprocessing_backend` support to:
  - `RamanFit`
  - `PLfit`
  - `RamanMapping`
  - `PLMapping`
- Preserved native fallback behaviour for unsupported workflows and preprocessing steps.

### Notes
- RamanSPy integration currently applies to **Raman preprocessing only**.
- PL workflows remain on the native preprocessing backend.
- `BaselineSubtract(method="gaussian")` remains native-only at this stage.
- Mapping backend auto-selection is partially wired, but further cleanup is still required before finalising the full v0.4.0 release behaviour.

---------

## [v0.3.9] - 2026-04-02

### Added
- Added adaptive mapping fit execution for `PLMapping` and `RamanMapping`:
  - cheap first-pass fit
  - optional retry pass only when needed
  - retry triggers configurable via `fit_spectrum_kwargs`
- Added diagnostics levels for mapping fits:
  - `diagnostics="full"`
  - `diagnostics="light"`
  - `diagnostics="none"`
- Added compact diagnostics summaries so mapping QA can be retained without storing full per-pixel masks.

### Changed
- Optimised mapping preprocessing by introducing cube-level fast paths for common operations:
  - vectorised Savitzky–Golay smoothing across the mapping cube
  - vectorised Gaussian baseline subtraction across the mapping cube
  - batched polynomial baseline subtraction across the mapping cube
- Optimised peak-model evaluation by vectorising `peak_models.sum_peaks(...)` using NumPy broadcasting.
- Updated mapping fit diagnostics handling so `fit_summary()` still works when diagnostics are reduced or disabled.
- Refined pseudo-Voigt broadcasting support in peak models for mapping and batch optimisation paths.

### Performance
- Reduced Python-loop overhead in mapping preprocessing for common workflows using smoothing, Gaussian baseline correction, or polynomial baseline correction.
- Reduced unnecessary multistart retries by allowing adaptive retry control through:
  - `adaptive_multistart`
  - `fast_n_starts`
  - `retry_on_fail`
  - `retry_on_high_rmse`
  - `retry_on_bound_hit`
  - `retry_rmse_gate`
- Reduced memory overhead for production mapping workflows by allowing compact or disabled diagnostics.

### Fixed
- Fixed pseudo-Voigt vectorised peak summation so array-valued `eta` parameters are handled correctly during optimiser evaluation.
- Preserved compatibility of mapping fit summaries when `fit_diagnostics_map` is absent (`diagnostics="none"`).
- Preserved output shapes and fitting behaviour while applying preprocessing and model-evaluation performance refactors.

### Notes
- This release focuses on mapping and fitting efficiency without changing the user-facing scientific workflow.
- Cached sparse-operator optimisation for iterative baseline methods (`asLS`, `arPLS`, `airPLS`) is deferred to a later release.
- Further standardisation against RamanSPy-style workflows is planned for later `v0.4.x` builds.

--------

## v0.3.8 — schema cleanup and workflow polish

### Changed
- introduced a shared internal schema layer for modality, axis type, peak profile, coordinate mode, and baseline specifications
- standardised canonical baseline dictionary usage, with `poly_order` preferred over legacy `poly_degree`
- aligned preprocessing metadata and export metadata more consistently across single-spectrum, batch, and mapping workflows
- updated single-spectrum Raman and PL fitting classes to use the shared schema-driven preprocessing contract
- updated mapping preprocess helpers and mapping exports to use the same schema conventions
- improved export metadata by adding clearer schema-aware fields such as `schema_version`, `baseline_spec`, and `preprocessing_recipe`

### Improved
- synchronised batch metadata collection with the new fitter/export schema
- improved mapping export consistency for both fitted maps and integration maps
- improved PL mapping plot scaling so displayed fitted curves use the stored normalisation scale when available
- made coordinate export handling stricter and more consistent through canonical `pixel` / `real` modes
- extended mapping compatibility helpers so custom peaks exported from single-spectrum fitting respect the active parameter stride

### Compatibility
- preserved backwards-compatible wrappers for `RamanFit.py`, `PLfit.py`, and `Mapping.py`
- preserved legacy preprocessing and metadata fields where needed for older notebooks and exports
- kept legacy baseline shorthand accepted for now, while making dictionary-style specifications the preferred interface

### Internal
- modular mapping split from the previous build is now followed by schema-level cleanup across preprocessing, batch, export, and mapping internals
- prepared the codebase for a later v0.3.9 pass focused on mapping and fitting efficiency

--------

## [0.3.7] — 2026-03-30

### Refactored
- Split the previous monolithic `Mapping.py` implementation into internal mapping modules under `src/ramanpl/mapping/`.
- Moved mapping diagnostics, IO/image helpers, preprocessing mixin, and modality-specific mapping logic into separate files for easier maintenance and future optimisation.
- Kept `src/ramanpl/Mapping.py` as a compatibility façade so existing imports from `ramanpl.Mapping` continue to work. :contentReference[oaicite:0]{index=0}

### Fixed
- Corrected `peak_models` imports after the mapping module split.
- Restored backward-compatible `fit_summary()` instance usage for both `PLMapping` and `RamanMapping`.
- Improved constructor parity for `PLMapping` so file-based and `from_arrays()` initialisation produce the same fit-related output state before fitting.

### Compatibility
- Preserved mapping-facing API behaviour while modularising internals.
- Maintained existing mapping workflows, including fitting, heatmap plotting, export, and diagnostics.
- Continued alignment with the planned v0.3.7 goal of mapping modularisation before later runtime clean-up. :contentReference[oaicite:1]{index=1}

--------

## [0.3.6] - 2026-03-29

### Refactored
- Reorganised single-spectrum fitting code into a dedicated `ramanpl/single_fit/` subpackage.
- Moved the main Raman and PL single-fit implementations into:
  - `ramanpl/single_fit/RamanFit.py`
  - `ramanpl/single_fit/PLfit.py`
- Added a shared internal single-fit core:
  - `ramanpl/single_fit/_single_fit_core.py`
- Centralised duplicated single-fit utilities shared by Raman and PL fitting, including:
  - compatibility importer construction
  - baseline deprecation handling
  - multi-start initialisation
  - RMSE / bound-hit helpers
  - shared export metadata helpers
  - `export_p0()` helper logic

### Compatibility
- Preserved old user-facing import patterns for backwards compatibility:
  - `from ramanpl import RamanFit`
  - `from ramanpl import PLfit`
  - legacy module-style usage such as `RamanFit.DataImporter.data_import(...)`
- Kept thin top-level wrapper modules so older notebooks and scripts continue to run without requiring API changes.

### Fixed
- Updated internal import paths after moving single-fit files into `single_fit/`.
- Restored access to the Raman material library after the refactor by loading `raman_materials.json` from the package-level `ramanpl` directory rather than assuming it sits beside `RamanFit.py`.
- Added package-data inclusion for `raman_materials.json` so the material library is available after installation.
- Improved stability of the single-fit refactor by resolving compatibility issues introduced during the folder reorganisation.

### Documentation
- Updated README repository structure to reflect the new `single_fit/` layout.
- Kept the public usage examples centred on the existing top-level imports to avoid breaking established workflows.

### Notes
- This release is a structure-and-maintainability update focused on single-spectrum fitting internals.
- No intentional change was made to the scientific fitting workflow or user-facing fitting API.
- Mapping modularisation is planned next in `v0.3.7`.
- Schema cleanup and polish are planned for `v0.3.8`.

--------

## [v0.3.5] - 2026-03-23

### Added
- Extended the preprocessing `Pipeline` workflow from single-spectrum fitting to mapping and batch workflows.
- Added cube-level preprocessing execution for mapping while keeping preprocessing steps scientifically 1D.
- Added `build_legacy_mapping_pipeline(...)` to reproduce existing mapping preprocessing behaviour through the shared pipeline framework.
- Added preprocessing-aware metadata normalisation in export utilities so nested pipeline recipes can be written cleanly to headers.
- Added pipeline-based example usage for Raman batch and Raman mapping notebooks.

### Changed
- Refactored `Mapping.py` so `PLMapping` and `RamanMapping` can accept `preprocessing=Pipeline(...)`.
- Mapping preprocessing now uses the shared preprocessing runner for crop, smoothing, and baseline subtraction before fitting.
- Preserved fit-space normalisation inside mapping fit logic rather than treating it as a preprocessing step.
- Updated batch processing to propagate and retain preprocessing metadata more cleanly during fitting and export.
- Improved exporter metadata handling so pipeline/provenance information is serialised in a readable form.
- Added fitter-side support for stable serialisable preprocessing metadata (`preprocessing_recipe`) for export/debug workflows.

### Fixed
- Fixed a `RamanFit` initialisation regression where `self.preprocessing` could be accessed before assignment after the preprocessing refactor.
- Preserved compatibility of existing Jupyter notebook workflows using legacy preprocessing flags.
- Corrected mapping pipeline usage so shared preprocessing is not duplicated by old per-spectrum branches.

### Notes
- Pipeline-based preprocessing is now supported across single, batch, and mapping workflows.
- For backwards compatibility, some legacy metadata fields such as `baseline_method` and `poly_degree` may still appear in exports.
- A future cleanup release (`v0.3.6`) is planned to reduce redundant legacy metadata and deprecated preprocessing fields when `preprocessing=Pipeline(...)` is used explicitly.

--------

## [v0.3.4] – Preprocessing Pipeline Framework (2025-3-8)

### Added

- New `preprocessing.py` module implementing a modular preprocessing framework.
- Introduced `Pipeline` class for building ordered preprocessing workflows.
- Added preprocessing steps:
  - `CropByRange`
  - `SmoothSavGol`
  - `BaselineSubtract` (supports `poly`, `airpls`, `arpls`, `asls`, `gaussian`).
- `PLfit` and `RamanFit` now accept a `preprocessing` pipeline argument.
- Exposed `ramanpl.preprocessing` as a public module via `__init__.py`.

### Changed

- Modernised baseline configuration using dictionary-based specification:

  ```python
  baseline_method={"method": "airpls", "lam": 1e6}
  ```

- Preprocessing comparison plots restored to legacy-style display:
  raw / smoothed / baseline / corrected.

- Updated README with pipeline usage examples and documentation.

- Updated example notebooks demonstrating preprocessing and warm-start workflows.

### Fixed

- Fixed fitting failure when using CropByRange due to axis-length mismatch after preprocessing.

- Fixed preprocessing comparison plotting when pipelines are used.

- Fixed parameter export mismatch for pseudo-Voigt peak models.

### Deprecated

- The `poly_degree` argument in `PLfit` and `RamanFit` is now deprecated.
  Use:
  
  ```python
  baseline_method={"method": "poly", "poly_degree": 3}
  ```

### Internal

- Updated `PLfit.py`, `RamanFit.py`, `__init__.py`, and `setup.py`.

- Added new example notebooks and updated output files.

-------------

## [v0.3.3] — Unified Line-Shape Architecture & pVoigt Integration (2026-2-17)

### Added

- Full pseudo-Voigt peak model support for:
  - RamanFit
  - PLfit
  - RamanMapping
  - PLMapping
  - Batch processing
- Unified model dispatcher (`_model`)
- Consistent parameter stride handling (`params_per_peak`)
- Explicit peak height reporting (`peak_height`)
- pVoigt η parameter support
- FWHM definition unification:
  - Lorentzian → width parameter = HWHM
  - pVoigt → width parameter = FWHM
- Bound diagnostics in Mapping:
  - lower-bound hits
  - upper-bound hits
  - per-parameter masks
- Warm-start plausibility gating to reduce scanline artefacts

### Changed

- Peak reporting now emphasises:
  - `peak_height`
  - `fwhm`
  - `amp`
- `intensity` retained only for backward compatibility where required
- Materials library automatically adapts to selected peak profile
- Export metadata now records:
  - peak_profile
  - normalization behaviour
  - custom_peaks usage
- Width penalty now evaluated consistently in FWHM space

### Internal Refactoring

- Centralised peak summation in `peak_models.sum_peaks`
- Unified `get_fitted_parameters()` logic across RamanFit and PLfit
- Mapping peak-height calculation aligned with single-spectrum logic
- Removal of duplicate bound-check utilities
- Stride-aware parameter handling across all fitters

### Performance Note

Pseudo-Voigt mapping may be substantially slower than Lorentzian fitting due to:

- Increased parameter dimensionality
- Numerical peak-height evaluation
- More complex optimisation landscape

Recommended practice:

- Use Lorentzian for initial scans
- Apply pVoigt selectively for refined analysis

-------------

## [v0.3.0] — Multi-start mapping fits, diagnostics, and bound-sticking mitigation (2026-02-09)

### Added
- **Multi-start fitting in mapping (PLMapping / RamanMapping)**
  - `fit_spectra(..., fit_spectrum_kwargs=...)` now supports running multiple initialisations (`n_starts`)
    and selecting the best solution by a robust score.
  - Supported strategies include `p0_strategy="midpoint" | "random" | "jitter"` plus `random_state`.
- **Per-pixel fitter diagnostics for mapping**
  - Mapping objects now store per-pixel diagnostics (e.g. `rmse`, `n_starts`, `n_fail`, best initial guess),
    enabling quantitative QA rather than only visual inspection.
- **Bound-sticking QA helpers (documented in README)**
  - Suggested user-facing checks for how often parameters sit on upper/lower bounds, and per-peak breakdown.

### Improved
- **Normalisation semantics made explicit**
  - Mapping fitting is performed in **peak-normalised fit space**; the `normalize` flag controls **display/output scaling** only.
  - This mirrors the intended “fit in normalised space, show either normalised or raw” model used elsewhere.
- **Robust peak selection for plotting**
  - Peak name matching in mapping plotting was hardened (exact / case-insensitive / substring matching) to avoid
    “empty heatmap” failures when peak labels differ slightly (e.g. `E2g` vs `E12g(Γ)`).

### Fixed
- Fixed PLMapping peak heatmap plotting where exciton/trion position/intensity could silently fail due to
  label/index mismatch, resulting in blank plots.
- Fixed mapping failure-mode bookkeeping so unsuccessful pixels are consistently marked and do not corrupt warm-start state.

### Notes
- `fit_spectrum_kwargs` is accepted by `fit_spectra()` (not `__init__()`), so existing construction code remains compatible.
- No breaking changes intended for single-spectrum fitting or batch workflows.

------------------------

## [v0.2.9.5] — Batch peak control, statistics, and robustness improvements

### Added
- **Batch-level peak control**
  - Added support for `custom_peaks` and `remove_peaks` in `RamanBatch` and `PLBatch`.
  - Behaviour is consistent with single-spectrum fitting:
    - `custom_peaks` replaces all default/library peaks.
    - `remove_peaks` is applied last and always takes precedence.
- **Per-peak statistical analysis for batch fitting**
  - Added `summary_by_peak()` to `RamanBatch` and `PLBatch`.
  - Computes descriptive statistics (count, mean, standard deviation, median, min/max, and configurable percentiles) for each fitted peak across the batch.
  - Supports two output modes:
    - table-style summary
    - block-style human-readable summary (per-peak reporting).
- **Export of batch statistics**
  - Batch peak statistics can be exported to `.csv`, `.txt`, or `.tsv`.
  - Exported files include fitting metadata when available.

### Improved
- **Consistency across workflows**
  - Peak-definition logic is now aligned across:
    - single-spectrum fitting
    - batch fitting
    - mapping workflows
  - Users may freely mix `materials`/`substrate` defaults with explicit peak overrides.
- **Metadata propagation**
  - Batch exports now record whether `custom_peaks` and/or `remove_peaks` were used.
  - Removed peak labels are preserved in exported metadata for reproducibility.
- **Batch API clarity**
  - Updated class docstrings for `RamanBatch` and `PLBatch` to document peak precedence rules and advanced usage.
  - README feature list updated to reflect expanded batch capabilities.

### Fixed
- Fixed an error in `summary_by_peak(print_mode="blocks")` where table-printing logic was incorrectly executed, causing an `UnboundLocalError`.
- Improved internal handling of cached tables to prevent stale state after batch fitting updates.

### Notes
- No breaking changes to existing batch or single-spectrum workflows.
- Existing scripts using `materials` and `substrate` continue to work unchanged.
- Users relying on default peak libraries can now selectively suppress unwanted peaks without redefining the full peak set.

------------------------

## [v0.2.9.1] (2026-2-5):

    1. Modified the `warm_start` logic in `Mapping.py` to ensure that the warm start fitting is now applied to a singple-point within the same mapping dataset
    2. Added a few new examples in `Mapping PL Example.ipynb` and `Mapping Raman Example.ipynb` to demonstrate the usage of warm start fitting for PL mapping and Raman mapping, respectively.

## [v0.2.9] (2026-2-3):

    1. Added batch-processing utilities in `batch.py` for loading multiple spectra (Raman/PL), batch fitting, and producing overlay/waterfall comparison plots.
    2. Added fitted-parameter aggregation helpers (long and wide formats), including wide-table pivoting (e.g. `E12g_position`, `E12g_fwhm`, `E12g_intensity`) for downstream analysis.
    3. Added robust CSV/TXT/TSV table export with optional metadata header blocks (reusing `exporter.py` table writers).
    4. Harmonised fitted-parameter extraction between `RamanFit.py` and `PLfit.py` (consistent accessors for per-peak position/FWHM/intensity).
    5. Bug fixes and usability improvements across batch plotting and exporting (safer defaults, clearer error messages, reduced boilerplate for common workflows).

*All changes are backward compatible with previous version (0.2.8).*

## [v0.2.8] (2026-1-25):

    1. Added new functionality of exporting fitted parameters to CSV file in `RamanFit.py` and `PLfit.py` via new method `export_fit_parameters()`. This allows users to easily save and analyse the fitted parameters after fitting.
    2. Updated example notebooks `Raman_component.ipynb` and `PL_component.ipynb` to demonstrate the usage of the new `export_fit_parameters()` method for exporting fitted parameters to CSV files.
    3. Fixed a bug in `Mapping.py` where the sanity-check plot of `plot_spectrum()`for Raman integration was not correctly shown.


## [v0.2.7.2] (2026-1-18):

    1. Modified `raman_materials.json`: updated WS2, WO3 and SiO2 subtrate peaks; added "Si-true" subtrate to distinguish from "Si" with more lower intensity existing peaks of Si

## [v0.2.7.2] (2026-1-16):

    1. Added new material group 'GrO' to represent Graphene Oxides

## [v0.2.7.1] (2026-1-6):

    1. Added plotting comparison curve of processed data (background subtraction or smoothing) if those options applied to RamanFit.py and PLfit.py
    2. Modified Raman_component.ipynb and PL_component.ipynb to reflect those changes.

*All changes are backward compatible with previous version (0.2.7).*

## [v0.2.7] (2025-12-29):
    
    1. Added spectrum data subtraction and addition options via new `operation.py` to improve fitting accuracy for spectra with low signal-to-noise ratios. Users can now enable background removal during the fitting process.
    2. Updated example notebook `Raman_component.ipynb` to demonstrate the usage of background removal during Raman spectrum fitting.
    3. Fixed data trimming options in `DataImporter.data_import()` method to ensure that when `x_range` is specified, the `readlines` parameter is ignored, allowing for accurate data import within the desired range.
    4. Updated `Mapping.py` to allow intermediate array type data for fitting, enabling more flexible data handling during mapping analysis.
    5. Added arithmetic processing ability for a mapped raw data to subtract a reference data.
    6. Deleted .txt example data files that are no longer used in the updated example notebooks to streamline the repository.
    7. Make other optimisations and code clean-up for better performance and readability.

*All changes are backward compatible with previous version (0.2.6).*

## [v0.2.6] (2025-12-28):

    1. Added `mask_by_xrange()` static method in `DataImporter` class to create boolean masks for selecting data within specified x-axis ranges. This method is now used in `Mapping.py` for both Raman and PL data processing.
    2. Updated `DataImporter.data_import()` method in both `RamanFit.py` and `PLfit.py` to include a new `x_range` parameter, allowing users to specify the range of x-axis values (wavenumber for Raman, energy for PL) to read from the data files. The previous `readlines` parameter is deprecated but still functional for backward compatibility.
    3. Updated example notebooks `Raman Example.ipynb` and `PL Example.ipynb` to reflect the changes in data import method and demonstrate the usage of the new `x_range` parameter.
    4. Optimised data import process to read only the necessary data range, improving efficiency when dealing with large datasets.

*All changes are backward compatible with previous version (0.2.5).*

## [v0.2.5] (2025-12-27):

    1. Added a few new examples in PLfit and Ramanfit example foldders to demonstrate background subtraction using various fitting methods.
    2. Updated `PLfit.py` and `RamanFit.py` to include a new `baseline_method` parameter in the constructor, allowing users to choose between 'poly' (polynomial fitting) and 'gaussian' (Gaussian fitting) for background removal.
    3. Created a new module `baselineAPI.py` to handle baseline correction methods, which is now imported and used in both `PLfit.py`,`RamanFit.py` and `Mapping.py`.
    4. Deprecating the previous `poly_degree` and `gaussian_sigma` parameters in favour of the new `baseline_method` parameter. Warnings are issued if the old parameters are used.
    5. Added new background removal options in `baselineAPI.py`: `airpls`, `asls`, `arpls`, which are now utilised in the fitting classes.

*All changes are backward compatible with previous version (0.2.4).*

## [v0.2.4] (2025-12-26):

    1. Updated `RamanFit.py` to fix a bug where the fitting was incorrectly performed on unnormalised data when `normalize` was set to False. Now, fitting is always done on normalised data, and the `normalize` option only affects display and output scaling. 
    2. Updated `Mapping.py` to ensure that Raman mapping fitting is performed on normalised data regardless of the `normalize` setting. The `normalize` option now only influences the display and output scaling of heatmaps and spectra. And updated specific intensity heatmap plotting, ratio heatmap plotting, and distance heatmap plotting methods to reflect this change.
    3. Updated example notebooks `Mapping Raman Example.ipynb` and `Mapping Raman txt Example.ipynb` to reflect the changes in fitting behaviour and clarify the purpose of the `normalize` option.
    4. Optimise the fitting speed in `Mapping.py` by improving the warm-start logic and reducing redundant computations.

*All changes are backward compatible with previous version (0.2.3).*

## [v0.2.3] (2025-12-25):

    1. Changed `normalize` option in `Mapping.py` to control whether to display normalised data for heatmap display. This option does not affect the fitting process.
    2. Added `warm_start` and `reset_on_fail` options in `Mapping.py`'s `fit_spectra()` method to improve fitting stability.
    3. Updated `plot_residual_distribution()`, `plot_heatmap()`, `plot_spectrum()_fit` method in `Mapping.py` to visualise the distribution of fitting residuals for quality check.
    4. Added `export_p0()` method in `PLfit.py` to export the fitted parameters after fitting for further analysis.
    5. Updated Mapping examples in `Mapping PL Example.ipynb`, `PL_component.ipynb`, and `Mapping PL txt Example.ipynb` to reflect the changes in `normalize` option, added residual distribution plotting, `p0_pkg` for better `p0` guess in the example.

*All changes are backward compatible with previous version (0.2.0).*

## [v0.2.0] (2025-6-6):

    1. Move source code to `ramanpl` folder, create package installation manuals for local library installation and usage
    2. Modified the jupyter-notebook codes in example for local library usage.

## [v0.1.5] (2025-6-5):

    1. Added *Gr* and *2L-Gr* for graphene/bilayer-graphene library file `raman_materials.json`
    2. Added new sample bilayer graphene data (`Raman Sample 532nm 2L-Graphene.txt`) into example folders
    3. Modify the doc-strings in `Mapping.py`