eemkit 0.1.0__py3-none-any.whl

eemkit/corrections/scatter.py

@@ -0,0 +1,191 @@
+"""Removal of Rayleigh and Raman scatter, and interpolation of the gaps.
+
+Four bands are handled, each centred on a line of the (ex, em) plane:
+
+==============  ===========================================
+band            centre (nm)
+==============  ===========================================
+``rayleigh1``   em = ex
+``raman1``      em = 1e7 / (1e7 / ex - shift)
+``rayleigh2``   em = 2 ex
+``raman2``      em = 2 * raman1 centre
+==============  ===========================================
+
+``shift`` is the O-H stretching Raman shift of water in cm^-1. Each band is
+removed between ``centre - below`` and ``centre + above``. Optionally the
+region below first-order Rayleigh (em < ex - offset), where no fluorescence
+can occur, is set to zero; Thygesen et al. (2004, Chemometr. Intell. Lab.
+Syst. 71:97-106) showed that such zeros stabilise PARAFAC.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+
+import numpy as np
+import xarray as xr
+
+from eemkit.core.history import has_step, with_history
+from eemkit.corrections._common import require_not_done, require_vars
+from eemkit.errors import CorrectionError
+
+BANDS = ("rayleigh1", "raman1", "rayleigh2", "raman2")
+
+
+def raman_emission(ex: np.ndarray, shift_cm1: float) -> np.ndarray:
+    """Emission wavelength (nm) of the water Raman line excited at ``ex`` (nm)."""
+    ex = np.asarray(ex, dtype=float)
+    return 1e7 / (1e7 / ex - shift_cm1)
+
+
+def scatter_mask(
+    ex: np.ndarray,
+    em: np.ndarray,
+    widths: Mapping[str, tuple[float, float]],
+    raman_shift_cm1: float | None = None,
+) -> xr.DataArray:
+    """Boolean (ex, em) mask, True inside any of the bands listed in ``widths``.
+
+    ``widths`` maps band names to ``(below, above)`` in nm. A Raman band
+    requires ``raman_shift_cm1``.
+    """
+    unknown = set(widths) - set(BANDS)
+    if unknown:
+        raise ValueError(f"unknown scatter band(s) {sorted(unknown)}; use {BANDS}")
+    if any(b.startswith("raman") for b in widths) and raman_shift_cm1 is None:
+        raise ValueError("raman_shift_cm1 is required to remove Raman scatter")
+    ex = np.asarray(ex, dtype=float)
+    em = np.asarray(em, dtype=float)
+    centres = {"rayleigh1": ex, "rayleigh2": 2 * ex}
+    if raman_shift_cm1 is not None:
+        r = raman_emission(ex, raman_shift_cm1)
+        centres.update(raman1=r, raman2=2 * r)
+    mask = np.zeros((ex.size, em.size), dtype=bool)
+    for band, (below, above) in widths.items():
+        if below < 0 or above < 0:
+            raise ValueError(f"{band}: widths must be non-negative")
+        c = centres[band][:, None]
+        mask |= (em[None, :] >= c - below) & (em[None, :] <= c + above)
+    return xr.DataArray(mask, dims=("ex", "em"), coords={"ex": ex, "em": em})
+
+
+def remove_scatter(
+    ds: xr.Dataset,
+    *,
+    widths: Mapping[str, tuple[float, float]],
+    raman_shift_cm1: float | None = None,
+    zero_below_rayleigh: float | None = None,
+    variables: tuple[str, ...] = ("intensity",),
+) -> xr.Dataset:
+    """Set scatter bands to NaN (and optionally the region below Rayleigh to 0).
+
+    Parameters
+    ----------
+    widths
+        ``{band: (below_nm, above_nm)}`` for the bands to remove; see module doc.
+    raman_shift_cm1
+        Raman shift of water, needed for Raman bands.
+    zero_below_rayleigh
+        If given, intensities at ``em < ex - zero_below_rayleigh`` are set to 0
+        instead of NaN (applied after the bands, so it never overrides a band
+        lying above that limit).
+    variables
+        Data variables to process.
+
+    Notes
+    -----
+    The removed region is stored as ``scatter_mask(ex, em)``.
+    """
+    step = "remove_scatter"
+    require_vars(ds, *variables, step=step)
+    require_not_done(ds, step)
+    mask = scatter_mask(ds["ex"].values, ds["em"].values, widths, raman_shift_cm1)
+    out = ds.copy()
+    zero = None
+    if zero_below_rayleigh is not None:
+        zero = ds["em"] < ds["ex"] - zero_below_rayleigh
+    for name in variables:
+        v = ds[name].where(~mask)
+        if zero is not None:
+            v = xr.where(zero, 0.0, v)
+        out[name] = v.transpose(*ds[name].dims).assign_attrs(ds[name].attrs)
+    out["scatter_mask"] = mask.assign_attrs(long_name="removed scatter region")
+    return with_history(out, step, widths={k: list(v) for k, v in widths.items()},
+                        raman_shift_cm1=raman_shift_cm1,
+                        zero_below_rayleigh=zero_below_rayleigh, variables=list(variables))
+
+
+INTERP_METHODS = ("em", "ex", "both")
+
+
+def _fill_rows(a: np.ndarray, x: np.ndarray) -> np.ndarray:
+    """Linear interpolation of interior NaN gaps along the last axis (no extrapolation)."""
+    out = a.copy()
+    for row in out.reshape(-1, a.shape[-1]):
+        ok = np.isfinite(row)
+        if ok.sum() < 2 or ok.all():
+            continue
+        lo, hi = np.flatnonzero(ok)[[0, -1]]
+        gap = ~ok
+        gap[:lo] = gap[hi + 1:] = False
+        row[gap] = np.interp(x[gap], x[ok], row[ok])
+    return out
+
+
+def interpolate_missing(
+    ds: xr.Dataset,
+    *,
+    method: str,
+    variables: tuple[str, ...] = ("intensity",),
+) -> xr.Dataset:
+    """Fill NaN gaps in each EEM by linear interpolation between measured points.
+
+    Parameters
+    ----------
+    method
+        ``"em"``: along emission within each excitation scan; ``"ex"``: along
+        excitation at each emission wavelength; ``"both"``: mean of the two
+        estimates where both exist, otherwise whichever exists.
+
+    Notes
+    -----
+    Only gaps bracketed by measured values are filled; gaps at the edge of
+    the EEM stay NaN. The coordinates ``n_interpolated(sample)`` and
+    ``n_still_missing(sample)`` count filled and remaining values.
+    """
+    step = "interpolate_missing"
+    require_vars(ds, *variables, step=step)
+    if not has_step(ds, "remove_scatter"):
+        raise CorrectionError(f"{step}: nothing to interpolate; run remove_scatter first")
+    if method not in INTERP_METHODS:
+        raise ValueError(f"method must be one of {INTERP_METHODS}")
+    ex, em = ds["ex"].values, ds["em"].values
+    out = ds.copy()
+    counts: dict[str, list[int]] = {}
+    for name in variables:
+        da = ds[name].transpose(..., "ex", "em")
+        vals = da.values
+        along_em = _fill_rows(vals, em)
+        along_ex = np.swapaxes(_fill_rows(np.swapaxes(vals, -1, -2), ex), -1, -2)
+        if method == "em":
+            new = along_em
+        elif method == "ex":
+            new = along_ex
+        else:
+            with np.errstate(invalid="ignore"):
+                new = np.where(np.isfinite(along_em) & np.isfinite(along_ex),
+                               (along_em + along_ex) / 2,
+                               np.where(np.isfinite(along_em), along_em, along_ex))
+        gap_before = np.isnan(vals).reshape(-1, ex.size * em.size).sum(axis=1)
+        gap_after = np.isnan(new).reshape(-1, ex.size * em.size).sum(axis=1)
+        vals = new
+        filled = [int(v) for v in gap_before - gap_after]
+        left = [int(v) for v in gap_after]
+        out[name] = (da.dims, vals, da.attrs)
+        out[name] = out[name].transpose(*ds[name].dims)
+        counts[name] = filled
+        if name == "intensity" and "sample" in da.dims:
+            out = out.assign_coords(n_interpolated=("sample", filled),
+                                    n_still_missing=("sample", left))
+    return with_history(out, step, method=method, variables=list(variables),
+                        total_interpolated={k: int(sum(v)) for k, v in counts.items()})

eemkit/corrections/spectral.py

@@ -0,0 +1,117 @@
+"""Instrument spectral correction (excitation and emission correction factors).
+
+The Cary Eclipse was operated with 'Corrected spectra OFF', so intensities
+contain the wavelength response of lamp, monochromators and detector.
+Correction factors are instrument-specific and must be measured (e.g. with
+certified reference fluorophores); eemkit ships none and never invents them.
+
+Factors are read from two-column text files (wavelength in nm, factor) and
+applied **multiplicatively** by default: ``F_corr = F_obs * Xc(ex) * Mc(em)``.
+If your files hold divisors (e.g. an instrument response or lamp reference
+spectrum), pass ``convention="divide"``: ``F_corr = F_obs / Xr(ex) / Mr(em)``.
+Until applied, ``ds.attrs["spectral_correction"]`` is ``"none"``; data
+recorded with the instrument's own correction ON are refused.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import numpy as np
+import xarray as xr
+
+from eemkit.core.history import with_history
+from eemkit.corrections._common import require_not_after, require_not_done, require_vars
+from eemkit.errors import CorrectionError, FileFormatError
+
+NOT_CORRECTED = "none"
+
+
+def read_correction_file(path: str | Path) -> tuple[np.ndarray, np.ndarray]:
+    """Read ``wavelength, factor`` pairs; header lines and ``,;`` or whitespace separators ok."""
+    path = Path(path)
+    wl, f = [], []
+    for n, line in enumerate(path.read_text(encoding="utf-8-sig").splitlines(), 1):
+        toks = [t for t in line.replace(";", ",").replace("\t", ",").replace(" ", ",")
+                .split(",") if t]
+        if not toks:
+            continue
+        try:
+            w, v = float(toks[0]), float(toks[1])
+        except (ValueError, IndexError):
+            if wl:
+                raise FileFormatError(f"{path}, line {n}: expected 'wavelength, factor'") \
+                    from None
+            continue  # header
+        wl.append(w)
+        f.append(v)
+    if len(wl) < 2:
+        raise FileFormatError(f"{path}: fewer than two numeric rows")
+    order = np.argsort(wl)
+    return np.asarray(wl)[order], np.asarray(f)[order]
+
+
+def apply_spectral_correction(
+    ds: xr.Dataset,
+    *,
+    ex_factors: str | Path | tuple[np.ndarray, np.ndarray],
+    em_factors: str | Path | tuple[np.ndarray, np.ndarray],
+    variables: tuple[str, ...] = ("intensity", "blank_intensity"),
+    convention: str = "multiply",
+) -> xr.Dataset:
+    """Multiply (or divide) EEMs by excitation and emission correction factors.
+
+    Factors are linearly interpolated onto the ``ex`` and ``em`` grids, which
+    they must cover (no extrapolation). ``convention`` says what the files
+    hold: ``"multiply"`` (correction factors) or ``"divide"`` (response
+    spectra). The stored ``spectral_correction_ex/em`` variables are always
+    the multipliers actually applied. Must precede every other correction.
+    """
+    step = "apply_spectral_correction"
+    if convention not in ("multiply", "divide"):
+        raise ValueError(f"{step}: convention must be 'multiply' or 'divide', not {convention!r}")
+    variables = tuple(v for v in variables if v in ds.data_vars)
+    require_vars(ds, "intensity", step=step)
+    require_not_done(ds, step)
+    if spectral_correction_status(ds) != NOT_CORRECTED:
+        raise CorrectionError(f"{step}: the data are already spectrally corrected "
+                              f"({spectral_correction_status(ds)})")
+    for later in ("correct_inner_filter", "subtract_blank", "normalize_raman", "remove_scatter"):
+        require_not_after(ds, step, later)
+
+    sources = {}
+    curves = {}
+    for dim, spec in (("ex", ex_factors), ("em", em_factors)):
+        if isinstance(spec, (str, Path)):
+            sources[dim] = str(spec)
+            spec = read_correction_file(spec)
+        else:
+            sources[dim] = "array"
+        wl, f = (np.asarray(a, dtype=float) for a in spec)
+        grid = ds[dim].values
+        if grid.min() < wl.min() - 1e-6 or grid.max() > wl.max() + 1e-6:
+            raise CorrectionError(f"{step}: {dim} factors cover {wl.min()}-{wl.max()} nm, "
+                                  f"grid needs {grid.min()}-{grid.max()} nm")
+        on_grid = np.interp(grid, wl, f)
+        if not np.all(np.isfinite(on_grid) & (on_grid > 0)):
+            raise CorrectionError(f"{step}: {dim} factors must be positive over "
+                                  f"{grid.min()}-{grid.max()} nm")
+        if convention == "divide":
+            on_grid = 1.0 / on_grid
+        curves[dim] = xr.DataArray(on_grid, dims=dim, coords={dim: grid})
+
+    out = ds.copy()
+    for name in variables:
+        out[name] = (ds[name] * curves["ex"] * curves["em"]).transpose(*ds[name].dims) \
+            .assign_attrs(ds[name].attrs)
+    out["spectral_correction_ex"] = curves["ex"]
+    out["spectral_correction_em"] = curves["em"]
+    out.attrs["spectral_correction"] = (f"applied (ex: {sources['ex']}; em: {sources['em']}; "
+                                        f"{convention})")
+    return with_history(out, step, ex_factors=sources["ex"], em_factors=sources["em"],
+                        convention=convention)
+
+
+def spectral_correction_status(ds: xr.Dataset) -> str:
+    """'none' or a description of the applied correction."""
+    return ds.attrs.get("spectral_correction", NOT_CORRECTED)

eemkit/errors.py

@@ -0,0 +1,37 @@
+"""Exceptions and warnings raised by eemkit."""
+
+
+class EEMKitError(Exception):
+    """Base class for eemkit errors."""
+
+
+class FileFormatError(EEMKitError, ValueError):
+    """An instrument file does not have the expected layout."""
+
+
+class PairingError(EEMKitError, ValueError):
+    """The pairing table is malformed or points to missing files."""
+
+
+class GridError(EEMKitError, ValueError):
+    """Spectra cannot be placed on, or combined into, a common wavelength grid."""
+
+
+class CorrectionError(EEMKitError, ValueError):
+    """A correction cannot be applied: missing input, wrong order or applied twice."""
+
+
+class IndexComputationError(EEMKitError, ValueError):
+    """A fluorescence index cannot be computed with the requested settings."""
+
+
+class SettingsError(EEMKitError, ValueError):
+    """A processing setting is missing or invalid (e.g. no cuvette path length)."""
+
+
+class Cancelled(EEMKitError):
+    """A long computation was cancelled by the caller."""
+
+
+class EEMKitWarning(UserWarning):
+    """Something unusual that does not prevent processing but should be reviewed."""

eemkit/gui/__init__.py

@@ -0,0 +1,30 @@
+"""Desktop application for eemkit (requires ``pip install eemkit[gui]``).
+
+Start it with ``eemkit-gui [project.toml]`` or ``python -m eemkit.gui``.
+The application is a front end to :mod:`eemkit.pipeline`: all processing
+is done by the library, and the project file it saves is the same settings
+TOML that scripts can run.
+"""
+
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    try:
+        from PySide6.QtWidgets import QApplication
+    except ImportError as exc:  # pragma: no cover
+        print(f"The eemkit desktop application needs PySide6 (pip install eemkit[gui]): {exc}",
+              file=sys.stderr)
+        return 1
+    from eemkit.gui import theme
+    from eemkit.gui.main_window import MainWindow
+
+    argv = sys.argv if argv is None else argv
+    app = QApplication.instance() or QApplication(argv)
+    app.setApplicationName("eemkit")
+    theme.apply_theme(app, theme.saved_theme())
+    window = MainWindow(argv[1] if len(argv) > 1 else None)
+    window.show()
+    return app.exec()

eemkit/gui/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from eemkit.gui import main
+
+sys.exit(main())

eemkit/gui/campaigns_tab.py

@@ -0,0 +1,275 @@
+"""Tab 5: differences between campaigns, along sites and with covariates."""
+
+from __future__ import annotations
+
+import pandas as pd
+from PySide6.QtCore import Qt
+from PySide6.QtWidgets import (
+    QComboBox,
+    QFileDialog,
+    QFormLayout,
+    QGroupBox,
+    QHBoxLayout,
+    QLabel,
+    QLineEdit,
+    QMessageBox,
+    QPushButton,
+    QSplitter,
+    QTableView,
+    QTabWidget,
+    QVBoxLayout,
+    QWidget,
+)
+
+from eemkit import pipeline, plot
+from eemkit.gui.common import DataFrameModel, PlotPanel, TaskBar, note, pair, primary
+from eemkit.gui.state import Project
+
+NONE = "(none)"
+
+
+def _table_view(model: DataFrameModel) -> QTableView:
+    v = QTableView()
+    v.setModel(model)
+    return v
+
+
+class CampaignsTab(QWidget):
+    def __init__(self, project: Project, tasks: TaskBar, parent=None):
+        super().__init__(parent)
+        self.project, self.tasks = project, tasks
+
+        self.value = QComboBox()
+        self.group = QComboBox()
+        self.time = QComboBox()
+        self.site = QComboBox()
+        self.position = QComboBox()
+        self.sites_file = QLineEdit()
+        self.cov_file = QLineEdit()
+        for e in (self.sites_file, self.cov_file):
+            e.setReadOnly(True)
+            e.setPlaceholderText("optional")
+        b_sites = QPushButton("Choose…")
+        b_sites.clicked.connect(lambda: self.choose_table("sites_table"))
+        b_cov = QPushButton("Choose…")
+        b_cov.clicked.connect(lambda: self.choose_table("covariates_table"))
+        b_clear = QPushButton("Clear tables")
+        b_clear.clicked.connect(self.clear_tables)
+
+        g_cols = QGroupBox("Sample columns")
+        f = QFormLayout(g_cols)
+        f.addRow("Variable", self.value)
+        f.addRow("Group (e.g. river)", self.group)
+        f.addRow("Time (e.g. campaign)", self.time)
+        f.addRow("Site", self.site)
+        f.addRow(note("Replicates are averaged per site and time before any test, so they "
+                      "are never counted as independent samples."))
+        g_opt = QGroupBox("Optional tables")
+        f = QFormLayout(g_opt)
+        f.addRow("Site table", pair(self.sites_file, b_sites))
+        f.addRow("Position along the river", self.position)
+        f.addRow("Covariate table", pair(self.cov_file, b_cov))
+        f.addRow("", b_clear)
+        f.addRow(note("Site table: CSV with the group and site columns plus e.g. latitude, "
+                      "longitude, distance_km. Covariate table: CSV with the group and time "
+                      "columns, written exactly as in the samples (e.g. 2024-05), plus e.g. "
+                      "discharge, rainfall. Rows are joined only on exact matches; missing "
+                      "rows are reported."))
+
+        self.b_run = primary(QPushButton("Analyse"))
+        self.b_run.clicked.connect(self.analyse)
+        self.b_save = QPushButton("Save to output folder")
+        self.b_save.clicked.connect(self.save)
+
+        self.warn = QLabel("")
+        self.warn.setWordWrap(True)
+        self.warn.setProperty("role", "warning")
+        self.warn.hide()
+        self.models = {k: DataFrameModel() for k in ("kruskal", "pairwise", "spatial",
+                                                     "covariates", "design", "units")}
+        self.plots = {k: PlotPanel() for k in ("time", "sites", "composition")}
+        views = QTabWidget()
+        views.addTab(self.plots["time"], "Over time")
+        views.addTab(self.plots["sites"], "Along sites")
+        views.addTab(self.plots["composition"], "PARAFAC composition")
+        tests = QWidget()
+        tl = QVBoxLayout(tests)
+        for title, key in (("Kruskal–Wallis between times, within each group", "kruskal"),
+                           ("Dunn's pairwise comparisons (Holm-adjusted p)", "pairwise")):
+            tl.addWidget(QLabel(f"<b>{title}</b>"))
+            tl.addWidget(_table_view(self.models[key]), 1)
+        views.addTab(tests, "Tests")
+        corr = QWidget()
+        cl = QVBoxLayout(corr)
+        for title, key in (("Spearman correlation with position", "spatial"),
+                           ("Spearman correlation with covariates", "covariates")):
+            cl.addWidget(QLabel(f"<b>{title}</b>"))
+            cl.addWidget(_table_view(self.models[key]), 1)
+        views.addTab(corr, "Correlations")
+        views.addTab(_table_view(self.models["design"]), "Design")
+        views.addTab(_table_view(self.models["units"]), "Site means")
+        self.views = views
+
+        left = QWidget()
+        ll = QVBoxLayout(left)
+        ll.addWidget(g_cols)
+        ll.addWidget(g_opt)
+        buttons = QHBoxLayout()
+        buttons.addWidget(self.b_run)
+        buttons.addWidget(self.b_save)
+        ll.addLayout(buttons)
+        ll.addStretch(1)
+        right = QWidget()
+        rl = QVBoxLayout(right)
+        rl.addWidget(self.warn)
+        rl.addWidget(views, 1)
+        split = QSplitter(Qt.Horizontal)
+        split.addWidget(left)
+        split.addWidget(right)
+        split.setStretchFactor(1, 1)
+        QVBoxLayout(self).addWidget(split)
+        project.changed.connect(self._on_changed)
+        tasks.busy_changed.connect(lambda b: self.b_run.setEnabled(not b))
+        self.refresh_columns()
+
+    # columns ------------------------------------------------------------- #
+
+    def table(self) -> pd.DataFrame | None:
+        p = self.project
+        if p.indices is None and p.model is None:
+            return None
+        return pipeline.sample_table(p.indices, p.model)
+
+    def _site_table_columns(self) -> list[str]:
+        path = self.project.resolve("sites_table", "campaigns")
+        if path is None or not path.is_file():
+            return []
+        try:
+            return list(pipeline.read_table(path).columns)
+        except Exception:  # noqa: BLE001 - an unreadable table offers no columns
+            return []
+
+    def refresh_columns(self) -> None:
+        df = self.table()
+        c = self.project.settings["campaigns"]
+        cols = [] if df is None else list(df.reset_index().columns)
+        numeric = [] if df is None else [k for k in df.columns
+                                         if pd.api.types.is_numeric_dtype(df[k])]
+        labels = [k for k in cols if k not in numeric and k not in ("sample", "cdom_notes")]
+        for box, items, want in ((self.value, numeric, self.value.currentText()),
+                                 (self.group, labels, c.get("group")),
+                                 (self.time, labels, c.get("time")),
+                                 (self.site, [NONE] + labels, c.get("site") or NONE),
+                                 (self.position, [NONE] + self._site_table_columns() + numeric,
+                                  c.get("position") or NONE)):
+            box.blockSignals(True)
+            box.clear()
+            box.addItems(list(dict.fromkeys(items)))
+            if want:
+                box.setCurrentText(want)
+            box.blockSignals(False)
+        self.sites_file.setText(c.get("sites_table", ""))
+        self.cov_file.setText(c.get("covariates_table", ""))
+
+    def _on_changed(self, what: str) -> None:
+        if what in ("settings", "indices", "final"):
+            self.refresh_columns()
+        if what in ("indices", "final", "campaigns") and self.project.campaign is None:
+            self._clear_results("Choose the columns and press Analyse.")
+
+    def choose_table(self, key: str) -> None:
+        path, _ = QFileDialog.getOpenFileName(self, "Choose table", str(self.project.base),
+                                              "Tables (*.csv *.txt)")
+        if path:
+            self.set_table(key, path)
+
+    def set_table(self, key: str, path: str) -> None:
+        self.project.set_path_setting(key, path, "campaigns")
+        self.project.invalidate("campaigns")
+        self.refresh_columns()
+
+    def clear_tables(self) -> None:
+        self.project.set_settings("campaigns", {"sites_table": "", "covariates_table": ""},
+                                  "campaigns")
+        self.refresh_columns()
+
+    # analysis ------------------------------------------------------------ #
+
+    def _store(self) -> None:
+        def val(box):
+            t = box.currentText()
+            return "" if t == NONE else t
+        self.project.set_settings("campaigns", {
+            "group": val(self.group), "time": val(self.time), "site": val(self.site),
+            "position": val(self.position)}, "campaigns")
+
+    def analyse(self) -> None:
+        df = self.table()
+        if df is None:
+            QMessageBox.information(self, "eemkit", "Compute the indices (or fit the final "
+                                    "PARAFAC model) first.")
+            return
+        self._store()
+        value, settings, base = self.value.currentText(), self.project.settings, self.project.base
+
+        def work(progress, cancelled):
+            return pipeline.campaign_analysis(df, value, settings, base)
+
+        def done(res):
+            self.project.campaign = res
+            self.project.changed.emit("campaigns")
+            self.show_results()
+
+        if not value:
+            QMessageBox.information(self, "eemkit", "Choose a variable.")
+            return
+        self.tasks.run(work, done, "Comparing campaigns…")
+
+    def _clear_results(self, message: str) -> None:
+        for m in self.models.values():
+            m.set_frame(pd.DataFrame())
+        for p in self.plots.values():
+            p.clear(message)
+        self.warn.hide()
+
+    def show_results(self) -> None:
+        res = self.project.campaign
+        if res is None:
+            return
+        c = self.project.settings["campaigns"]
+        self.warn.setText("⚠ " + "\n⚠ ".join(res.warnings) if res.warnings else "")
+        self.warn.setVisible(bool(res.warnings))
+        for key, df in (("kruskal", res.kruskal), ("pairwise", res.pairwise),
+                        ("spatial", res.spatial), ("covariates", res.covariates),
+                        ("design", res.design.reset_index() if res.design is not None else None),
+                        ("units", res.units)):
+            self.models[key].set_frame(df if df is not None else pd.DataFrame())
+        self.plots["time"].show_figure(plot.campaign_series(res.units, res.value,
+                                                            group=c["group"], time=c["time"]))
+        if res.spatial is not None:
+            self.plots["sites"].show_figure(plot.along_sites(res.units, res.value, c["position"],
+                                                             group=c["group"]))
+        else:
+            self.plots["sites"].clear("Choose a position column (e.g. distance_km from a site "
+                                      "table) to see the variable along the sites.")
+        pct = [k for k in res.units.columns if k.endswith("_pct") and not k.endswith("cv_pct")]
+        if pct:
+            self.plots["composition"].show_figure(plot.composition(
+                res.units, pct, group=c["group"], time=c["time"]))
+        else:
+            self.plots["composition"].clear("Fit the final PARAFAC model to see the share of "
+                                            "each component.")
+
+    def save(self) -> None:
+        res, out = self.project.campaign, self.project.resolve("output_dir")
+        if res is None:
+            QMessageBox.information(self, "eemkit", "Run the analysis first.")
+            return
+        if out is None or self.project.in_data_root(out):
+            QMessageBox.information(self, "eemkit", "Choose an output folder outside the data "
+                                    "folder (Project tab).")
+            return
+        written = pipeline.export_campaigns(out / "campaigns" / res.value, res,
+                                            self.project.settings)
+        QMessageBox.information(self, "eemkit", f"Wrote {len(written)} files to "
+                                f"{out / 'campaigns' / res.value}.")