eemkit 0.1.0__py3-none-any.whl

eemkit/core/grid.py

@@ -0,0 +1,100 @@
+"""Wavelength grids and resampling of spectra onto them."""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+import xarray as xr
+
+from eemkit.core.history import with_history
+from eemkit.errors import GridError
+
+#: Grid points this far (nm) outside the measured range take the edge value
+#: instead of NaN. Absorbs the ~0.02 nm jitter of instrument wavelength axes.
+DEFAULT_TOLERANCE = 0.1
+
+
+def regular_grid(start: float, stop: float, step: float) -> np.ndarray:
+    """Evenly spaced grid from ``start`` to ``stop`` inclusive.
+
+    ``stop - start`` must be a whole number of steps.
+    """
+    if step <= 0 or stop <= start:
+        raise GridError(f"invalid grid {start}..{stop} step {step}")
+    n = (stop - start) / step
+    if not np.isclose(n, round(n), atol=1e-6):
+        raise GridError(f"{start}..{stop} is not a whole number of {step} nm steps")
+    return np.round(start + step * np.arange(round(n) + 1), 10)
+
+
+def interp_on_grid(
+    x: np.ndarray, y: np.ndarray, grid: np.ndarray, tolerance: float = DEFAULT_TOLERANCE
+) -> np.ndarray:
+    """Linearly interpolate the spectrum ``y(x)`` onto ``grid``.
+
+    NaN pairs are dropped and ``x`` may be in any order. Grid points farther
+    than ``tolerance`` outside the measured range are NaN (no extrapolation).
+    """
+    x = np.asarray(x, dtype=float)
+    y = np.asarray(y, dtype=float)
+    grid = np.asarray(grid, dtype=float)
+    ok = np.isfinite(x) & np.isfinite(y)
+    if ok.sum() < 2:
+        return np.full(grid.shape, np.nan)
+    xs, ys = x[ok], y[ok]
+    order = np.argsort(xs)
+    xs, ys = xs[order], ys[order]
+    if np.any(np.diff(xs) == 0):
+        raise GridError("duplicate wavelengths in spectrum")
+    out = np.interp(grid, xs, ys)
+    out[(grid < xs[0] - tolerance) | (grid > xs[-1] + tolerance)] = np.nan
+    return out
+
+
+def resample(
+    ds: xr.Dataset, dim: str, grid: np.ndarray, tolerance: float = DEFAULT_TOLERANCE
+) -> xr.Dataset:
+    """Resample every data variable of ``ds`` along ``dim`` onto ``grid``.
+
+    Linear interpolation; recorded in the processing history.
+    """
+    grid = np.asarray(grid, dtype=float)
+    old = ds[dim].values
+    out = ds.drop_dims(dim)
+    for name, var in ds.data_vars.items():
+        if dim not in var.dims:
+            out[name] = var
+            continue
+        moved = np.moveaxis(var.values, var.dims.index(dim), -1)
+        flat = moved.reshape(-1, moved.shape[-1])
+        res = np.stack([interp_on_grid(old, row, grid, tolerance) for row in flat])
+        res = np.moveaxis(res.reshape(moved.shape[:-1] + (grid.size,)), -1, var.dims.index(dim))
+        out[name] = (var.dims, res, var.attrs)
+    out = out.assign_coords({dim: (dim, grid, ds[dim].attrs)})
+    out.attrs = dict(ds.attrs)
+    # the native axis is left out on purpose: it is in the source file, and keeping
+    # the entry identical across samples lets a stacked dataset hold one history
+    return with_history(out, "resample", dim=dim, grid=grid, method="linear",
+                        tolerance_nm=tolerance)
+
+
+def infer_common_grid(axes: Iterable[np.ndarray], decimals: int = 0) -> np.ndarray:
+    """Propose a regular grid covered by every axis in ``axes``.
+
+    The step is the coarsest of the median native steps (rounded to
+    ``decimals``), so no axis is resampled to a finer resolution than it was
+    measured at. Start and stop are the overlap of all axes, snapped inward
+    onto multiples of the step.
+    """
+    axes = [np.asarray(a, dtype=float) for a in axes]
+    if not axes:
+        raise GridError("no axes given")
+    step = max(round(float(np.median(np.abs(np.diff(a)))), decimals) for a in axes)
+    if step <= 0:
+        raise GridError("cannot infer a positive step")
+    lo = max(np.nanmin(a) for a in axes)
+    hi = min(np.nanmax(a) for a in axes)
+    start = np.ceil(round(lo / step - DEFAULT_TOLERANCE / step, 6)) * step
+    stop = np.floor(round(hi / step + DEFAULT_TOLERANCE / step, 6)) * step
+    return regular_grid(start, stop, step)

eemkit/core/history.py

@@ -0,0 +1,78 @@
+"""Processing history (provenance) stored in dataset attributes.
+
+Every function that changes data appends one entry to ``ds.attrs["eemkit_history"]``,
+a JSON-encoded list, so the record survives a round trip through netCDF.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+import numpy as np
+import xarray as xr
+
+HISTORY_ATTR = "eemkit_history"
+
+
+def get_history(ds: xr.Dataset | xr.DataArray) -> list[dict[str, Any]]:
+    """Return the list of processing steps applied to ``ds``, oldest first."""
+    return json.loads(ds.attrs.get(HISTORY_ATTR, "[]"))
+
+
+def make_entry(step: str, **params: Any) -> dict[str, Any]:
+    """One history record: step name, parameters, eemkit version, UTC time."""
+    from eemkit import __version__
+
+    return {
+        "step": step,
+        "params": _jsonable(params),
+        "eemkit_version": __version__,
+        "time": datetime.now(UTC).isoformat(timespec="seconds"),
+    }
+
+
+def with_history(ds: xr.Dataset, step: str, **params: Any) -> xr.Dataset:
+    """Return a shallow copy of ``ds`` with one history entry appended."""
+    out = ds.copy()
+    out.attrs[HISTORY_ATTR] = json.dumps(get_history(ds) + [make_entry(step, **params)])
+    return out
+
+
+def has_step(ds: xr.Dataset | xr.DataArray, step: str) -> bool:
+    """True if ``step`` appears in the processing history of ``ds``."""
+    return any(e["step"] == step for e in get_history(ds))
+
+
+def same_history(a: list[dict], b: list[dict]) -> bool:
+    """Compare two histories ignoring timestamps."""
+    strip = [{k: v for k, v in e.items() if k != "time"} for e in a]
+    return strip == [{k: v for k, v in e.items() if k != "time"} for e in b]
+
+
+def describe_grid(grid: np.ndarray) -> dict[str, Any]:
+    """Compact, JSON-friendly description of a wavelength grid."""
+    g = np.asarray(grid, dtype=float)
+    steps = np.diff(g)
+    regular = steps.size > 0 and np.allclose(steps, steps[0])
+    return {
+        "start": float(g[0]),
+        "stop": float(g[-1]),
+        "n": int(g.size),
+        "step": float(steps[0]) if regular else None,
+    }
+
+
+def _jsonable(obj: Any) -> Any:
+    if isinstance(obj, dict):
+        return {str(k): _jsonable(v) for k, v in obj.items()}
+    if isinstance(obj, (list, tuple)):
+        return [_jsonable(v) for v in obj]
+    if isinstance(obj, np.ndarray):
+        return describe_grid(obj) if obj.ndim == 1 and obj.size > 1 else obj.tolist()
+    if isinstance(obj, np.generic):
+        return obj.item()
+    if obj is None or isinstance(obj, (str, int, float, bool)):
+        return obj
+    return str(obj)

eemkit/corrections/__init__.py

@@ -0,0 +1,44 @@
+"""EEM corrections. Each is a separate, optional function recorded in the history.
+
+Recommended order (each function refuses to run after a step that must follow it):
+
+1. :func:`apply_spectral_correction` (instrument response; optional)
+2. :func:`subtract_absorbance_blank`
+3. :func:`correct_inner_filter`
+4. :func:`subtract_blank`
+5. :func:`normalize_raman`
+6. :func:`remove_scatter`, then optionally :func:`interpolate_missing`
+7. :func:`crop`
+"""
+
+from eemkit.corrections.blank import subtract_absorbance_blank, subtract_blank
+from eemkit.corrections.crop import crop
+from eemkit.corrections.inner_filter import correct_inner_filter
+from eemkit.corrections.raman import normalize_raman, raman_area
+from eemkit.corrections.scatter import (
+    interpolate_missing,
+    raman_emission,
+    remove_scatter,
+    scatter_mask,
+)
+from eemkit.corrections.spectral import (
+    apply_spectral_correction,
+    read_correction_file,
+    spectral_correction_status,
+)
+
+__all__ = [
+    "apply_spectral_correction",
+    "correct_inner_filter",
+    "crop",
+    "interpolate_missing",
+    "normalize_raman",
+    "raman_area",
+    "raman_emission",
+    "read_correction_file",
+    "remove_scatter",
+    "scatter_mask",
+    "spectral_correction_status",
+    "subtract_absorbance_blank",
+    "subtract_blank",
+]

eemkit/corrections/_common.py

@@ -0,0 +1,58 @@
+"""Helpers shared by the correction functions."""
+
+from __future__ import annotations
+
+import numpy as np
+import xarray as xr
+
+from eemkit.core.dataset import SAMPLE_DIM
+from eemkit.core.history import has_step
+from eemkit.errors import CorrectionError
+
+MISSING_POLICIES = ("error", "keep", "drop")
+
+
+def require_vars(ds: xr.Dataset, *names: str, step: str) -> None:
+    missing = [n for n in names if n not in ds.data_vars]
+    if missing:
+        raise CorrectionError(f"{step}: dataset has no {missing}")
+
+
+def require_not_done(ds: xr.Dataset, step: str) -> None:
+    if has_step(ds, step):
+        raise CorrectionError(f"{step} has already been applied to this dataset")
+
+
+def require_not_after(ds: xr.Dataset, step: str, later: str) -> None:
+    if has_step(ds, later):
+        raise CorrectionError(f"{step} must be applied before {later}")
+
+
+def resolve_missing(
+    ds: xr.Dataset, available: xr.DataArray, policy: str, step: str, what: str
+) -> tuple[xr.Dataset, xr.DataArray]:
+    """Apply the policy for samples that lack an input (``available`` is False).
+
+    'error' raises listing the samples, 'drop' removes them, 'keep' leaves
+    them uncorrected. Returns the (possibly reduced) dataset and the mask of
+    samples that will be corrected.
+    """
+    if policy not in MISSING_POLICIES:
+        raise ValueError(f"missing must be one of {MISSING_POLICIES}")
+    lacking = list(ds[SAMPLE_DIM].values[~available.values])
+    if lacking and policy == "error":
+        raise CorrectionError(
+            f"{step}: {len(lacking)} sample(s) have no {what}: {lacking[:10]}"
+            + (" ..." if len(lacking) > 10 else "")
+            + "; fix the pairing table or pass missing='keep' or 'drop'"
+        )
+    if lacking and policy == "drop":
+        ds = ds.sel({SAMPLE_DIM: available.values})
+        available = available.sel({SAMPLE_DIM: available.values})
+    return ds, available
+
+
+def has_data(da: xr.DataArray) -> xr.DataArray:
+    """Per-sample flag: True where the array is not entirely NaN."""
+    dims = [d for d in da.dims if d != SAMPLE_DIM]
+    return np.isfinite(da).any(dims)

eemkit/corrections/blank.py

@@ -0,0 +1,66 @@
+"""Blank subtraction for EEMs and absorbance spectra."""
+
+from __future__ import annotations
+
+import xarray as xr
+
+from eemkit.core.history import with_history
+from eemkit.corrections._common import (
+    has_data,
+    require_not_after,
+    require_not_done,
+    require_vars,
+    resolve_missing,
+)
+
+
+def subtract_blank(ds: xr.Dataset, missing: str = "error") -> xr.Dataset:
+    """Subtract the paired blank EEM from each sample EEM.
+
+    ``intensity`` becomes ``intensity - blank_intensity``; ``blank_intensity``
+    is kept unchanged (it is still needed for Raman normalisation). The
+    coordinate ``blank_subtracted(sample)`` records which samples were
+    corrected.
+
+    Parameters
+    ----------
+    missing
+        What to do with samples that have no blank: ``"error"`` (default),
+        ``"drop"`` them, or ``"keep"`` them uncorrected.
+    """
+    step = "subtract_blank"
+    require_vars(ds, "intensity", "blank_intensity", step=step)
+    require_not_done(ds, step)
+    require_not_after(ds, step, "normalize_raman")
+    require_not_after(ds, step, "remove_scatter")
+    ds, ok = resolve_missing(ds, has_data(ds["blank_intensity"]), missing, step, "blank EEM")
+
+    out = ds.copy()
+    out["intensity"] = xr.where(ok, ds["intensity"] - ds["blank_intensity"], ds["intensity"],
+                                keep_attrs=True)
+    out = out.assign_coords(blank_subtracted=ok)
+    return with_history(out, step, missing=missing, n_corrected=int(ok.sum()),
+                        n_uncorrected=int((~ok).sum()))
+
+
+def subtract_absorbance_blank(ds: xr.Dataset, missing: str = "error") -> xr.Dataset:
+    """Subtract the paired absorbance blank: ``absorbance - blank_absorbance``.
+
+    Coordinate ``absorbance_blank_subtracted(sample)`` records which samples
+    were corrected. ``missing`` as in :func:`subtract_blank`; samples without
+    any absorbance are left alone.
+    """
+    step = "subtract_absorbance_blank"
+    require_vars(ds, "absorbance", "blank_absorbance", step=step)
+    require_not_done(ds, step)
+    require_not_after(ds, step, "correct_inner_filter")
+    has_abs = has_data(ds["absorbance"])
+    ds, ok = resolve_missing(ds, has_data(ds["blank_absorbance"]) | ~has_abs, missing, step,
+                             "absorbance blank")
+    ok = ok & has_data(ds["absorbance"])
+
+    out = ds.copy()
+    out["absorbance"] = xr.where(ok, ds["absorbance"] - ds["blank_absorbance"],
+                                 ds["absorbance"], keep_attrs=True)
+    out = out.assign_coords(absorbance_blank_subtracted=ok)
+    return with_history(out, step, missing=missing, n_corrected=int(ok.sum()))

eemkit/corrections/crop.py

@@ -0,0 +1,33 @@
+"""Restricting EEMs to a wavelength window."""
+
+from __future__ import annotations
+
+import xarray as xr
+
+from eemkit.core.history import with_history
+from eemkit.errors import CorrectionError
+
+
+def crop(
+    ds: xr.Dataset,
+    *,
+    ex: tuple[float | None, float | None] | None = None,
+    em: tuple[float | None, float | None] | None = None,
+) -> xr.Dataset:
+    """Keep ``ex`` and ``em`` within the given inclusive ``(min, max)`` limits.
+
+    ``None`` leaves a limit (or a whole axis) unchanged. Absorbance, which
+    lives on its own ``wavelength`` axis, is not affected.
+    """
+    sel = {}
+    for dim, lim in (("ex", ex), ("em", em)):
+        if lim is None:
+            continue
+        lo, hi = lim
+        sel[dim] = slice(lo, hi)
+    out = ds.sel(sel)
+    for dim in sel:
+        if out.sizes[dim] == 0:
+            raise CorrectionError(f"crop: no {dim} wavelength within {sel[dim]}")
+    return with_history(out, "crop", ex=list(ex) if ex else None, em=list(em) if em else None,
+                        n_ex=out.sizes["ex"], n_em=out.sizes["em"])

eemkit/corrections/inner_filter.py

@@ -0,0 +1,123 @@
+"""Absorbance-based inner-filter-effect (IFE) correction.
+
+For a right-angle geometry with central illumination of a square cuvette,
+
+    F_corr(ex, em) = F_obs(ex, em) * 10 ** ((A_ex + A_em) / 2)
+
+where A_ex and A_em are the sample absorbances at the excitation and
+emission wavelengths over the fluorescence cuvette path length (Lakowicz,
+*Principles of Fluorescence Spectroscopy*, 3rd ed., 2006). Kothawala et al.
+(2013, Limnol. Oceanogr. Methods 11:616-630) showed that this
+absorbance-based approach is reliable for samples with A254 up to about 1.5
+(1 cm path) and recommended dilution above that.
+"""
+
+from __future__ import annotations
+
+import warnings
+
+import numpy as np
+import xarray as xr
+
+from eemkit.core.dataset import SAMPLE_DIM
+from eemkit.core.history import has_step, with_history
+from eemkit.corrections._common import (
+    has_data,
+    require_not_after,
+    require_not_done,
+    require_vars,
+    resolve_missing,
+)
+from eemkit.errors import CorrectionError, EEMKitWarning
+
+KOTHAWALA_MAX_A254 = 1.5
+
+
+def correct_inner_filter(
+    ds: xr.Dataset,
+    *,
+    absorbance_path_length_cm: float,
+    fluorescence_path_length_cm: float,
+    missing: str = "error",
+    max_a254: float = KOTHAWALA_MAX_A254,
+) -> xr.Dataset:
+    """Correct ``intensity`` for inner-filter effects using the sample absorbance.
+
+    Parameters
+    ----------
+    absorbance_path_length_cm
+        Path length of the cuvette the absorbance was measured in.
+    fluorescence_path_length_cm
+        Path length of the fluorescence cuvette. Both are required: eemkit
+        never assumes a cuvette.
+    missing
+        Samples without absorbance: ``"error"``, ``"drop"`` or ``"keep"``.
+    max_a254
+        Samples whose A254 over the fluorescence path exceeds this value get a
+        warning (Kothawala et al. 2013 recommend dilution above 1.5).
+
+    Notes
+    -----
+    The absorbance must already be blank-corrected
+    (:func:`~eemkit.corrections.subtract_absorbance_blank`). The applied
+    factor is kept as the variable ``ife_factor(sample, ex, em)``.
+    """
+    step = "correct_inner_filter"
+    require_vars(ds, "intensity", "absorbance", step=step)
+    require_not_done(ds, step)
+    # The water Raman signal inside the sample is attenuated like the DOM
+    # fluorescence, so IFE must be corrected before the blank is subtracted.
+    for later in ("subtract_blank", "normalize_raman", "remove_scatter"):
+        require_not_after(ds, step, later)
+    if not has_step(ds, "subtract_absorbance_blank"):
+        raise CorrectionError(f"{step}: subtract the absorbance blank first")
+    for name, val in (("absorbance_path_length_cm", absorbance_path_length_cm),
+                      ("fluorescence_path_length_cm", fluorescence_path_length_cm)):
+        if not np.isfinite(val) or val <= 0:
+            raise CorrectionError(f"{step}: {name} must be a positive number, got {val}")
+
+    wl = ds["wavelength"].values
+    for dim in ("ex", "em"):
+        lo, hi = ds[dim].values.min(), ds[dim].values.max()
+        if lo < wl.min() or hi > wl.max():
+            raise CorrectionError(f"{step}: absorbance ({wl.min()}-{wl.max()} nm) does not "
+                                  f"cover {dim} {lo}-{hi} nm")
+
+    ds, ok = resolve_missing(ds, has_data(ds["absorbance"]), missing, step, "absorbance")
+    a_fl = ds["absorbance"] / absorbance_path_length_cm * fluorescence_path_length_cm
+    a_ex = _at(a_fl, ds["ex"])
+    a_em = _at(a_fl, ds["em"])
+    factor = 10.0 ** ((a_ex + a_em) / 2.0)
+    factor = xr.where(ok, factor, 1.0).transpose(SAMPLE_DIM, "ex", "em")
+
+    if 254 >= wl.min() and 254 <= wl.max():
+        a254 = _at(a_fl, xr.DataArray([254.0], dims="wavelength")).squeeze(drop=True)
+        high = list(ds[SAMPLE_DIM].values[(a254 > max_a254).values & ok.values])
+        if high:
+            warnings.warn(f"{step}: A254 > {max_a254} for {high}; Kothawala et al. (2013) "
+                          "recommend diluting such samples", EEMKitWarning, stacklevel=2)
+
+    out = ds.copy()
+    out["intensity"] = (ds["intensity"] * factor).assign_attrs(ds["intensity"].attrs)
+    out["ife_factor"] = factor.assign_attrs(
+        long_name="inner-filter correction factor 10**((A_ex+A_em)/2)", units="1")
+    out = out.assign_coords(ife_corrected=ok)
+    return with_history(
+        out, step, method="absorbance-based (Kothawala et al. 2013)",
+        absorbance_path_length_cm=absorbance_path_length_cm,
+        fluorescence_path_length_cm=fluorescence_path_length_cm, missing=missing,
+        n_corrected=int(ok.sum()), max_factor=float(factor.max()),
+    )
+
+
+def _at(a: xr.DataArray, wavelengths: xr.DataArray) -> xr.DataArray:
+    """Absorbance at the given wavelengths, linear interpolation, renamed to their dim."""
+    dim = wavelengths.dims[0]
+    vals = np.apply_along_axis(
+        lambda row: np.interp(wavelengths.values, a["wavelength"].values, row),
+        a.get_axis_num("wavelength"), a.values,
+    )
+    dims = tuple(dim if d == "wavelength" else d for d in a.dims)
+    coords = {d: a[d].values for d in a.dims if d != "wavelength" and d in a.coords}
+    coords[dim] = wavelengths.values
+    return xr.DataArray(vals, dims=dims, coords=coords)

eemkit/corrections/raman.py

@@ -0,0 +1,107 @@
+"""Normalisation to Raman units (Lawaetz & Stedmon 2009, Appl. Spectrosc. 63:936-940).
+
+Intensities are divided by the area of the water Raman peak of a pure-water
+blank measured in the same session, integrated over emission at a fixed
+excitation. Lawaetz & Stedmon used excitation 350 nm and emission 381-426 nm.
+Without instrument spectral correction the result is internally consistent
+but not comparable with Raman units from other instruments.
+"""
+
+from __future__ import annotations
+
+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,
+    resolve_missing,
+)
+from eemkit.errors import CorrectionError
+
+
+def raman_area(
+    blank: xr.DataArray,
+    *,
+    ex: float,
+    em_range: tuple[float, float],
+    baseline: bool = False,
+) -> xr.DataArray:
+    """Integrated water Raman peak of ``blank`` (dims ``..., ex, em``).
+
+    The spectrum at excitation ``ex`` (which must be measured) is treated as
+    piecewise linear and integrated exactly from ``em_range[0]`` to
+    ``em_range[1]``, so the limits need not be grid points. With
+    ``baseline=True`` the straight line joining the spectrum at the two limits
+    is subtracted first. Result in intensity units x nm; NaN for an all-NaN
+    spectrum (no blank).
+    """
+    exs = blank["ex"].values
+    if not np.any(np.isclose(exs, ex)):
+        raise CorrectionError(f"raman_area: excitation {ex} nm is not measured "
+                              f"({exs.min()}-{exs.max()} nm)")
+    lo, hi = em_range
+    em = blank["em"].values
+    if not (em.min() <= lo < hi <= em.max()):
+        raise CorrectionError(f"raman_area: {lo}-{hi} nm is outside the emission range "
+                              f"{em.min()}-{em.max()} nm")
+    spec = blank.sel(ex=exs[np.isclose(exs, ex)][0])
+    inside = (em > lo) & (em < hi)
+    x = np.concatenate([[lo], em[inside], [hi]])
+    # grid points that enter the integral, including the neighbours of each limit
+    used = slice(np.searchsorted(em, lo, side="right") - 1, np.searchsorted(em, hi) + 1)
+
+    def area_of(row: np.ndarray) -> float:
+        if np.isnan(row).all():
+            return np.nan
+        if np.isnan(row[used]).any():
+            raise CorrectionError("raman_area: NaN inside the integration range "
+                                  "(was scatter removed before normalising?)")
+        y = np.concatenate([[np.interp(lo, em, row)], row[inside], [np.interp(hi, em, row)]])
+        if baseline:
+            y = y - (y[0] + (y[-1] - y[0]) * (x - x[0]) / (x[-1] - x[0]))
+        return float(np.trapezoid(y, x))
+
+    axis = spec.get_axis_num("em")
+    area = np.apply_along_axis(area_of, axis, spec.values)
+    dims = tuple(d for d in spec.dims if d != "em")
+    return xr.DataArray(area, dims=dims, coords={d: spec[d].values for d in dims})
+
+
+def normalize_raman(
+    ds: xr.Dataset,
+    *,
+    ex: float,
+    em_range: tuple[float, float],
+    baseline: bool = False,
+    missing: str = "error",
+) -> xr.Dataset:
+    """Divide ``intensity`` and ``blank_intensity`` by the blank's Raman area.
+
+    Each sample is normalised with its own paired blank. The area (a.u. nm)
+    is stored as the coordinate ``raman_area(sample)`` and the intensity
+    units become ``R.U.``. ``missing`` controls samples without a blank.
+    """
+    step = "normalize_raman"
+    require_vars(ds, "intensity", "blank_intensity", step=step)
+    require_not_done(ds, step)
+    require_not_after(ds, step, "remove_scatter")
+    area = raman_area(ds["blank_intensity"], ex=ex, em_range=em_range, baseline=baseline)
+    ds, ok = resolve_missing(ds, np.isfinite(area), missing, step, "blank for the Raman area")
+    area = area.sel(sample=ds["sample"].values)
+    if ((area <= 0) & ok).any():
+        bad = list(ds["sample"].values[((area <= 0) & ok).values])
+        raise CorrectionError(f"{step}: non-positive Raman area for {bad}")
+
+    scale = xr.where(ok, area, 1.0)
+    units = "R.U." if bool(ok.all()) else "R.U. (a.u. where raman_normalized is False)"
+    out = ds.copy()
+    for name in ("intensity", "blank_intensity"):
+        out[name] = (ds[name] / scale).assign_attrs(ds[name].attrs, units=units)
+    out = out.assign_coords(raman_area=area.where(ok).assign_attrs(units="a.u. nm"),
+                            raman_normalized=ok)
+    return with_history(out, step, method="Lawaetz & Stedmon (2009)", ex=ex,
+                        em_range=list(em_range), baseline=baseline, missing=missing,
+                        n_normalized=int(ok.sum()))