lsdviztools3 0.4.1__py3-none-any.whl

lsdviztools3/__init__.py

@@ -0,0 +1,12 @@
+"""lsdviztools3 — PyGMT-based visualisation tools for LSDTopoTools v3 output.
+
+Version 1 provides a backend-agnostic IO/data core (``lsdviztools3.io``) and a
+thin PyGMT render layer (``lsdviztools3.render``). Statistics (x-y) plotting is
+deferred (see ``lsdviztools3.charts``).
+"""
+
+__version__ = "0.4.1"
+
+# TODO: curate top-level re-exports once the render API stabilises, e.g.
+#   from .render.hillshade import render_hillshade
+#   from .render.style import MapStyle

lsdviztools3/_gmt.py

@@ -0,0 +1,48 @@
+"""Import PyGMT with a clear message when GMT itself is missing.
+
+PyGMT is a Python wrapper around the GMT C library. pip installs PyGMT (it is a
+dependency of lsdviztools3) but cannot install GMT, so a plain ``pip install``
+gives a PyGMT that fails on import with ``GMTCLibNotFoundError``. Every map
+renderer imports PyGMT through :func:`require_pygmt`, which turns that, and a
+missing PyGMT, into :class:`GMTNotAvailableError` saying how to install GMT.
+
+The import happens inside each renderer, not when lsdviztools3 is imported, so
+the matplotlib charts keep working without GMT.
+"""
+
+from __future__ import annotations
+
+INSTALL_HELP = (
+    "lsdviztools3 draws maps with PyGMT, which needs the GMT library. pip cannot "
+    "install GMT: install it from conda-forge (for example "
+    "`conda install -c conda-forge gmt pygmt`, or use the pixi environment in "
+    "the lsdviztools3 repository), Homebrew (`brew install gmt`) or your system "
+    "package manager (GMT 6.5 or later). The matplotlib charts work without it. "
+    "See https://lsdtopotools.github.io/lsdviztools3/ for installation."
+)
+
+
+class GMTNotAvailableError(ImportError):
+    """PyGMT, or the GMT library it wraps, cannot be loaded.
+
+    A subclass of ImportError, so ``pytest.importorskip`` and code that already
+    catches ImportError treat a missing GMT like a missing package.
+    """
+
+
+def require_pygmt():
+    """Return the ``pygmt`` module, or raise :class:`GMTNotAvailableError`."""
+    try:
+        import pygmt
+    except ImportError as err:  # PyGMT itself is not installed
+        raise GMTNotAvailableError(f"PyGMT is not installed. {INSTALL_HELP}") from err
+    except Exception as err:  # noqa: BLE001 - PyGMT raises its own types on load
+        # GMTCLibNotFoundError / GMTCLibError: PyGMT is there but cannot load
+        # libgmt (missing, or too old). Match on the name: pygmt.exceptions
+        # cannot be imported when importing pygmt itself has just failed.
+        if type(err).__name__.startswith("GMTCLib"):
+            raise GMTNotAvailableError(
+                f"PyGMT is installed but cannot load the GMT library ({err}). {INSTALL_HELP}"
+            ) from err
+        raise
+    return pygmt

lsdviztools3/charts/__init__.py

@@ -0,0 +1,214 @@
+"""Statistics (x-y) plotting.
+
+All x-y charts are implemented on a matplotlib engine (DESIGN decision #1),
+imported lazily so the core maps install stays lean. Only the channel
+longitudinal profile (:func:`plot_profile`) is still deferred and raises
+``NotImplementedError``.
+"""
+
+from __future__ import annotations
+
+from .chi import plot_chi_profile, plot_chi_stacked, plot_ksn_vs_erate
+from .circular import (
+    circular_wasserstein, kuiper_two_sample, plot_circular_comparison,
+)
+from .cross_sections import (
+    plot_valley_cross_section_map, plot_valley_cross_sections,
+    plot_valley_curved_cross_section_map,
+    plot_valley_cross_section_features,
+    plot_valley_cross_section_features_map,
+    plot_valley_cross_section_hydraulics,
+    cross_section_hydraulics, detect_hydraulic_flats,
+    combine_width_steps, compute_flat_surface_edges,
+)
+from .cosmo_comparison import (
+    load_cosmo_table, plot_cosmo_sweep_panels, plot_cosmo_sample_residuals,
+)
+from .cosmo_transient import (
+    cosmo_transient_title, load_cosmo_transient_table,
+    plot_cosmo_transient_concentration, plot_cosmo_transient_erate_ratio,
+    plot_nuclide_removal_response,
+)
+from .cosmo_transient_spatial import (
+    load_joined_samples, plot_ratio_overlay_1d, plot_ratio_vs_mean_erate,
+    plot_scenario_delta,
+    plot_ratio_vs_steptime,
+)
+from .distributions import plot_distributions
+from .lithology_ksn import (
+    plot_ksn_box_by_lithology, plot_ksn_by_lithology_and_basin,
+    plot_ksn_histogram_by_lithology, plot_reach_ksn_by_lithology,
+)
+from .channel_bearings import (
+    plot_binned_rose, plot_binned_rose_grid, plot_comparison_table,
+    plot_junction_angle_distributions, plot_junction_angle_summary,
+    plot_rose_comparison,
+)
+from .estar_rstar import plot_estar_rstar_model_scan
+from .divide_migration import (
+    aggressor_annotation, plot_head_metric_vs_distance, plot_pair_comparison,
+)
+from .hand import (
+    plot_hand_distance, plot_hand_window_populations, plot_valley_break_metric,
+    plot_valley_break_fraction, plot_valley_floor_map, plot_valley_reach_map,
+)
+from .hydraulic_breaks import (
+    plot_hydraulic_breaks_downstream, hydraulic_break_clusters,
+    plot_hydraulic_break_clusters, plot_cross_section_informed_valley_mask,
+)
+from .landslides import (
+    load_landslide_inventory,
+    plot_landslide_area_volume_larsen,
+    plot_sample_effect_apparent_vs_true,
+    plot_sample_effect_ratio,
+)
+from .network_geometry import (
+    plot_delta_L_cdf, plot_edge_basin_cdf, plot_junction_angle_cdf,
+    plot_metric_panels, plot_metric_vs_temperature,
+)
+from .rose import rose_diagram
+from .swath import plot_swath
+from .hillslope_profiles import (
+    load_profile_raster, profile_derivatives, profile_residuals,
+    plot_hillslope_profiles, plot_hillslope_profile, plot_profile_residual_panels,
+)
+from .hillslope_residuals import (
+    residual_statistics, summarise_residuals, plot_residual_density,
+    plot_hillslope_residual_density, plot_hillslope_residuals,
+    summarize_residuals, plot_residual_raster,
+)
+from .hillslope_transient_residuals import (
+    load_transient_residuals, plot_transient_residuals,
+    plot_hillslope_transient_residuals, plot_strip_transient_metrics,
+)
+
+__all__ = [
+    "plot_chi_profile", "plot_chi_stacked", "plot_ksn_vs_erate", "plot_swath",
+    "plot_hand_distance", "plot_hand_window_populations",
+    "plot_valley_break_metric", "plot_valley_break_fraction",
+    "plot_valley_cross_sections",
+    "plot_valley_cross_section_map",
+    "plot_valley_curved_cross_section_map",
+    "plot_valley_cross_section_features",
+    "plot_valley_cross_section_features_map",
+    "plot_valley_cross_section_hydraulics",
+    "cross_section_hydraulics", "detect_hydraulic_flats",
+    "combine_width_steps", "compute_flat_surface_edges",
+    "plot_valley_reach_map",
+    "plot_valley_floor_map",
+    "plot_hydraulic_breaks_downstream", "hydraulic_break_clusters",
+    "plot_hydraulic_break_clusters",
+    "plot_cross_section_informed_valley_mask",
+    "plot_distributions", "rose_diagram",
+    "plot_ksn_histogram_by_lithology", "plot_ksn_box_by_lithology",
+    "plot_reach_ksn_by_lithology", "plot_ksn_by_lithology_and_basin",
+    "plot_binned_rose", "plot_binned_rose_grid", "plot_junction_angle_summary",
+    "plot_junction_angle_distributions", "plot_rose_comparison", "plot_comparison_table",
+    "plot_estar_rstar_model_scan",
+    "load_landslide_inventory",
+    "plot_landslide_area_volume_larsen",
+    "plot_sample_effect_apparent_vs_true",
+    "plot_sample_effect_ratio",
+    "circular_wasserstein", "kuiper_two_sample", "plot_circular_comparison",
+    "load_cosmo_table", "plot_cosmo_sweep_panels", "plot_cosmo_sample_residuals",
+    "load_cosmo_transient_table", "cosmo_transient_title",
+    "plot_cosmo_transient_concentration", "plot_cosmo_transient_erate_ratio",
+    "plot_nuclide_removal_response",
+    "load_joined_samples", "plot_ratio_vs_steptime", "plot_ratio_vs_mean_erate",
+    "plot_ratio_overlay_1d", "plot_scenario_delta",
+    "plot_pair_comparison", "plot_head_metric_vs_distance",
+    "aggressor_annotation",
+    "plot_junction_angle_cdf", "plot_delta_L_cdf", "plot_edge_basin_cdf",
+    "plot_metric_panels", "plot_metric_vs_temperature",
+    "load_profile_raster", "profile_derivatives", "profile_residuals",
+    "plot_hillslope_profiles", "plot_hillslope_profile", "plot_profile_residual_panels",
+    "residual_statistics",
+    "summarise_residuals", "plot_residual_density", "plot_hillslope_residual_density",
+    "plot_hillslope_residuals", "summarize_residuals", "plot_residual_raster",
+    "load_transient_residuals", "plot_transient_residuals",
+    "plot_hillslope_transient_residuals", "plot_strip_transient_metrics",
+    "plot_profile", "plot_slope_area", "plot_gradient_curvature",
+    "plot_valley_spectrum", "plot_spacing_vs_ci", "plot_landscape_panel",
+    "plot_significant_frequencies_polar", "plot_spectral_tile_summary",
+    "plot_normalised_spectrum_2d", "plot_radial_spectrum",
+]
+
+_DEFERRED_MSG = (
+    "This lsdviztools3.charts x-y plot is deferred to a later release and is "
+    "not implemented yet."
+)
+
+
+def plot_profile(*args, **kwargs):
+    """Longitudinal channel profile. Deferred to a later release."""
+    raise NotImplementedError(_DEFERRED_MSG)
+
+
+def plot_slope_area(*args, **kwargs):
+    """Slope-area "boomerang" -- see :mod:`lsdviztools3.charts.slope_area`."""
+    from .slope_area import plot_slope_area as _impl
+    return _impl(*args, **kwargs)
+
+def plot_valley_spectrum(*args, **kwargs):
+    """One landscape's spectrum with both spacing measures marked.
+
+    See :mod:`lsdviztools3.charts.valley_spacing`.
+    """
+    from .valley_spacing import plot_valley_spectrum as _impl
+    return _impl(*args, **kwargs)
+
+def plot_spacing_vs_ci(*args, **kwargs):
+    """Valley spacing against the Bonetti channelization index, for a sweep.
+
+    See :mod:`lsdviztools3.charts.valley_spacing`.
+    """
+    from .valley_spacing import plot_spacing_vs_ci as _impl
+    return _impl(*args, **kwargs)
+
+def plot_landscape_panel(*args, **kwargs):
+    """Hillshade a set of landscapes side by side, for a visual sniff test.
+
+    See :mod:`lsdviztools3.charts.valley_spacing`.
+    """
+    from .valley_spacing import plot_landscape_panel as _impl
+    return _impl(*args, **kwargs)
+
+def plot_significant_frequencies_polar(*args, **kwargs):
+    """Significant 2D spectrum cells on a North-up polar axis (bearing x frequency).
+
+    See :mod:`lsdviztools3.charts.spectral`.
+    """
+    from .spectral import plot_significant_frequencies_polar as _impl
+    return _impl(*args, **kwargs)
+
+def plot_spectral_tile_summary(*args, **kwargs):
+    """One lsdtt-spectral-analysis run on a 2 x 2 figure (input, 2D, radial, polar).
+
+    See :mod:`lsdviztools3.charts.spectral`.
+    """
+    from .spectral import plot_spectral_tile_summary as _impl
+    return _impl(*args, **kwargs)
+
+def plot_normalised_spectrum_2d(*args, **kwargs):
+    """Normalised 2D spectrum, north up, significant cells outlined.
+
+    See :mod:`lsdviztools3.charts.spectral`.
+    """
+    from .spectral import plot_normalised_spectrum_2d as _impl
+    return _impl(*args, **kwargs)
+
+def plot_radial_spectrum(*args, **kwargs):
+    """Binned radial spectrum with background, normalised PSD and rollover.
+
+    See :mod:`lsdviztools3.charts.spectral`.
+    """
+    from .spectral import plot_radial_spectrum as _impl
+    return _impl(*args, **kwargs)
+
+def plot_gradient_curvature(*args, **kwargs):
+    """Gradient-curvature diagnostic after Roering (2008).
+
+    See :mod:`lsdviztools3.charts.gradient_curvature`.
+    """
+    from .gradient_curvature import plot_gradient_curvature as _impl
+    return _impl(*args, **kwargs)

lsdviztools3/charts/burned_profiles.py

@@ -0,0 +1,270 @@
+"""Long profiles of channels burned by lsdtt3 ``lsdtt-stream-burning``.
+
+Reads ``<write_fname>_burned_profiles.csv`` from a run with
+``stream_burn_mode: burn_to_corridor``: one row
+per channel cell, downstream order within each path (a chain of reaches from
+its head to where it joins another path or leaves the network), with
+
+  path_id, path_rank, reach_id, name, point_index, distance_m, flow_distance_m,
+  x, y, z_original, z_cleaned, z_profile, z_final, pit_filled, pit_id,
+  is_record_low, is_rejected_low, drainage_area_m2, chi, joins_path_id,
+  join_distance_m, starts_on_path_id
+
+Everything here is drawing: which cells form a course (a path and the paths it
+joins, down to the outlet) is read from ``joins_path_id`` / ``join_distance_m``;
+nothing is recomputed. The one derived quantity is the chi axis of a course,
+where each joined path's chi (counted from that path's head in the CSV) is
+shifted so the course's chi is continuous at the joins.
+
+``course_rows``       the rows of a course, ordered downstream, with
+                      ``course_distance_m`` and ``course_chi``
+``select_course``     a course by path id, path rank or river name
+``draw_burned_profile`` one course on one axis
+``plot_burned_profiles`` one panel per CSV (e.g. X = 0 / 60 / 150 m, or a
+                      linear against a chi fit), shared x axis
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+import matplotlib
+matplotlib.use("Agg")
+import matplotlib.pyplot as plt
+import numpy as np
+import pandas as pd
+
+# Fixed roles (validated together, light surface; green is below 3:1 contrast,
+# so every band carries a legend label).
+FINAL_COLOUR = "#2a78d6"       # the burned channel in the output DEM
+CUT_COLOUR = "#eb6834"         # cut below the cleaned DEM
+PIT_COLOUR = "#1baf7a"         # small pits filled before the profile was sampled
+RAISE_COLOUR = "#9a5bd6"       # raised above the cleaned DEM (junction pins, rejected minima)
+ORIGINAL_COLOUR = "#8a8a85"    # the input DEM under the channel
+INK = "#3d3d3a"
+
+REQUIRED = ["path_id", "path_rank", "name", "point_index", "distance_m", "flow_distance_m",
+            "x", "y", "z_original", "z_cleaned", "z_profile", "z_final", "pit_filled",
+            "pit_id", "is_record_low", "is_rejected_low", "chi", "joins_path_id",
+            "join_distance_m"]
+
+
+def read_burned_profiles(csv) -> pd.DataFrame:
+    """Read a ``_burned_profiles.csv`` written by burn_to_corridor."""
+    p = Path(csv)
+    if not p.exists():
+        raise FileNotFoundError(f"{p} (run lsdtt-stream-burning with stream_burn_mode: "
+                                "burn_to_corridor and write_burned_profiles_csv: true).")
+    df = pd.read_csv(p, keep_default_na=False, na_values={"chi": [""], "drainage_area_m2": [""],
+                                                         "join_distance_m": [""]})
+    missing = [c for c in REQUIRED if c not in df.columns]
+    if missing:
+        raise ValueError(f"{p}: not a burn_to_corridor profiles file (missing {missing}); "
+                         "older runs (z_filled / z_burned) are not supported.")
+    df["name"] = df["name"].astype(str)
+    return df
+
+
+def course_rows(df: pd.DataFrame, path_id: int, start_index: int = 0) -> pd.DataFrame:
+    """Rows of the course from ``path_id`` (from its cell ``start_index``) down
+    to the outlet, following ``joins_path_id``. Adds ``course_distance_m``
+    (downstream from the course's first cell) and ``course_chi`` (continuous
+    at the joins; NaN where the run has no chi)."""
+    parts = []
+    pid, lo = int(path_id), int(start_index)
+    offset = 0.0          # added to the chi of the current path
+    seen = set()
+    while pid >= 0 and pid not in seen:
+        seen.add(pid)
+        g = df[df.path_id == pid].sort_values("point_index")
+        if g.empty:
+            raise ValueError(f"no path {pid} in the profiles file")
+        g = g[g.point_index >= lo].copy()
+        g["course_chi"] = g.chi.astype(float) + offset
+        nxt = int(g.joins_path_id.iloc[0])
+        if nxt >= 0:
+            # the joined path continues from the join cell (this path's last
+            # cell); its chi is shifted to match this path's value there
+            h = df[df.path_id == nxt].sort_values("point_index")
+            jd = float(g.join_distance_m.iloc[0])
+            at = h[np.isclose(h.distance_m, jd, atol=1e-6)]
+            if at.empty:
+                raise ValueError(f"path {pid} joins path {nxt} at {jd} m, which has no such cell")
+            lo = int(at.point_index.min())
+            offset = float(g.course_chi.iloc[-1]) - float(at.chi.iloc[0])
+            g = g.iloc[:-1]
+        parts.append(g)
+        pid = nxt
+    c = pd.concat(parts, ignore_index=True)
+    c["course_distance_m"] = c.flow_distance_m.iloc[0] - c.flow_distance_m
+    return c
+
+
+def select_course(df: pd.DataFrame, path_id=None, path_rank=None, name=None):
+    """A course by path id, path rank (0 = the first, longest path) or river
+    name (from the most upstream cell with that name). Returns (rows, label)."""
+    given = [v is not None for v in (path_id, path_rank, name)]
+    if sum(given) > 1:
+        raise ValueError("give one of path_id, path_rank, name")
+    if name is not None:
+        hit = df[df.name == name]
+        if hit.empty:
+            raise ValueError(f"no cells named {name!r} (was vector_name_field set?)")
+        top = hit.loc[hit.flow_distance_m.idxmax()]
+        return course_rows(df, int(top.path_id), int(top.point_index)), name
+    if path_rank is None and path_id is None:
+        path_rank = 0
+    if path_rank is not None:
+        hit = df[df.path_rank == int(path_rank)]
+        if hit.empty:
+            raise ValueError(f"no path of rank {path_rank}")
+        path_id = int(hit.path_id.iloc[0])
+    rows = course_rows(df, int(path_id))
+    names = list(dict.fromkeys(n for n in rows.name if n))
+    label = (" / ".join(names[:3]) + (" ..." if len(names) > 3 else "")) if names else f"path {path_id}"
+    return rows, label
+
+
+def _joins_on_course(df, course, max_labels):
+    """(course x position, name, length) of paths joining the course."""
+    on = {(round(a, 3), round(b, 3)): i for i, (a, b) in enumerate(zip(course.x, course.y))}
+    course_paths = set(course.path_id)
+    out = []
+    for pid, g in df.groupby("path_id"):
+        if pid in course_paths:
+            continue
+        g = g.sort_values("point_index")
+        last = g.iloc[-1]
+        k = on.get((round(last.x, 3), round(last.y, 3)))
+        if k is None or int(last.joins_path_id) < 0:
+            continue
+        nm = next((n for n in g.name[::-1] if n), "")
+        out.append((k, nm, float(g.distance_m.max())))
+    out.sort(key=lambda t: -t[2])
+    return out, out[:max_labels]
+
+
+def draw_burned_profile(ax, df: pd.DataFrame, course: pd.DataFrame, x: str = "distance",
+                        mark=None, max_join_labels: int = 6, legend: bool = True):
+    """Draw one course on ``ax``. ``x``: "distance" (km downstream) or "chi"."""
+    if x == "chi":
+        if not np.isfinite(course.course_chi).all():
+            raise ValueError("this run has no chi (burn_profile_fit_algorithm_choice: chi)")
+        xs = course.course_chi.to_numpy()
+        ax.set_xlabel("chi (m)")
+    else:
+        xs = course.course_distance_m.to_numpy() / 1000.0
+        ax.set_xlabel("distance downstream (km)")
+    zo = course.z_original.to_numpy()
+    zc = course.z_cleaned.to_numpy()
+    zf = course.z_final.to_numpy()
+    zp = course.z_profile.to_numpy()
+
+    # Bands first, lines over them. Each cell's change against the input DEM is
+    # split without overlap: cut (final below the DEM); pit fill (from the DEM
+    # up to the lower of the cleaned and final values: the part of a small pit
+    # the channel still sits in); other raise (above both: junction pins,
+    # rejected minima).
+    pit = zc > zo
+    n_pits = int(course.loc[pit, "pit_id"].nunique())
+
+    def widen(m):
+        # each run widened by one cell either side (the band is zero there),
+        # so a one-cell run still draws
+        w = m.copy()
+        w[1:] |= m[:-1]
+        w[:-1] |= m[1:]
+        return w
+
+    cut = zf < zo
+    pit_top = np.minimum(zc, zf)
+    pit_band = pit & (zf > zo)
+    raise_lo = np.maximum(zo, zc)
+    raise_band = zf > raise_lo + 1e-6
+    ax.fill_between(xs, zf, zo, where=widen(cut), color=CUT_COLOUR, alpha=0.35, lw=0)
+    ax.fill_between(xs, zo, np.where(pit_band, pit_top, zo), where=widen(pit_band),
+                    color=PIT_COLOUR, alpha=0.6, lw=0)
+    ax.fill_between(xs, raise_lo, np.where(raise_band, zf, raise_lo), where=widen(raise_band),
+                    color=RAISE_COLOUR, alpha=0.5, lw=0)
+    ax.plot(xs, zo, color=ORIGINAL_COLOUR, lw=0.8, zorder=3)
+    if np.nanmax(np.abs(zp - zf)) > 0.01:
+        ax.plot(xs, zp, color=INK, lw=0.8, ls="--", zorder=4)
+    ax.plot(xs, zf, color=FINAL_COLOUR, lw=1.6, zorder=5)
+    lows = course.is_record_low.to_numpy() == 1
+    ax.plot(xs[lows], zf[lows], "o", ms=3.0, color=INK, mec="white", mew=0.5, zorder=6, ls="none")
+    rej = course.is_rejected_low.to_numpy() == 1
+    if rej.any():
+        ax.plot(xs[rej], zo[rej], "x", ms=4.5, color=INK, zorder=6, ls="none")
+
+    joins, labelled = _joins_on_course(df, course, max_join_labels)
+    for k, nm, _ in joins:
+        ax.axvline(xs[k], color=ORIGINAL_COLOUR, lw=0.5, alpha=0.6, zorder=1)
+    ytop = ax.get_ylim()[1]
+    span = float(np.nanmax(xs) - np.nanmin(xs)) or 1.0
+    placed = []
+    for k, nm, _ in labelled:
+        if nm and all(abs(xs[k] - q) > 0.03 * span for q in placed):
+            ax.text(xs[k], ytop, " " + nm, rotation=90, va="top", ha="right", fontsize=7, color=INK)
+            placed.append(xs[k])
+    if mark is not None:
+        mx, my, mlabel = mark
+        k = int(np.argmin(np.hypot(course.x - mx, course.y - my)))
+        ax.axvline(xs[k], color=INK, lw=0.8, ls=":", zorder=2)
+        ax.text(xs[k], ytop, " " + mlabel, va="top", ha="left", fontsize=8, color=INK)
+    ax.set_ylabel("elevation (m)")
+    ax.grid(alpha=0.25, lw=0.5)
+    for s in ("top", "right"):
+        ax.spines[s].set_visible(False)
+
+    rises = int((np.diff(zf) > 0).sum())
+    stats = (f"{n_pits} pits filled ({int(pit.sum())} cells), {int(lows.sum())} minima used, "
+             f"{int(rej.sum())} rejected; final rises at {rises} of {len(zf) - 1} steps")
+    from matplotlib.lines import Line2D
+    from matplotlib.patches import Patch
+    handles = [Line2D([], [], color=ORIGINAL_COLOUR, lw=0.8, label="input DEM under the channel"),
+               Line2D([], [], color=FINAL_COLOUR, lw=1.6, label="burned channel (output DEM)"),
+               Line2D([], [], color=INK, marker="o", ms=3, mec="white", ls="none",
+                      label="minima the profile joins"),
+               Patch(color=CUT_COLOUR, alpha=0.35, label="cut below the input DEM"),
+               Patch(color=PIT_COLOUR, alpha=0.6, label="small pit filled before sampling (channel in it)"),
+               Patch(color=RAISE_COLOUR, alpha=0.5, label="raised (junction, rejected minimum)")]
+    if rej.any():
+        handles.append(Line2D([], [], color=INK, marker="x", ls="none", label="minima rejected by the cut cap"))
+    if np.nanmax(np.abs(zp - zf)) > 0.01:
+        handles.append(Line2D([], [], color=INK, lw=0.8, ls="--", label="fitted profile"))
+    if legend:
+        ax.legend(handles=handles, fontsize=7, loc="upper right", frameon=False)
+    draw_burned_profile.last_handles = handles
+    return stats
+
+
+def plot_burned_profiles(csvs, out, labels=None, path_id=None, path_rank=None, name=None,
+                         x: str = "distance", mark=None, title=None, dpi: int = 200,
+                         panel_height: float = 3.4, max_join_labels: int = 6):
+    """One panel per CSV for the same course (chosen in the first CSV, by path
+    id, path rank or name; by name or rank in the others, whose path ids may
+    differ), shared x axis. Writes ``out`` (PNG)."""
+    csvs = [csvs] if isinstance(csvs, (str, Path)) else list(csvs)
+    labels = list(labels) if labels else [Path(c).name.replace("_burned_profiles.csv", "") for c in csvs]
+    if len(labels) != len(csvs):
+        raise ValueError("give one label per CSV")
+    fig, axes = plt.subplots(len(csvs), 1, figsize=(11, panel_height * len(csvs)), sharex=True, squeeze=False)
+    course_label = None
+    for i, (csv, lab) in enumerate(zip(csvs, labels)):
+        ax = axes[i, 0]
+        df = read_burned_profiles(csv)
+        if i > 0 and path_id is not None and name is None and path_rank is None:
+            raise ValueError("compare several runs by name or path rank, not path id")
+        course, course_label = select_course(df, path_id=path_id, path_rank=path_rank, name=name)
+        stats = draw_burned_profile(ax, df, course, x=x, mark=mark, max_join_labels=max_join_labels,
+                                    legend=False)
+        ax.set_title(f"{lab}: {stats}", fontsize=9, loc="left")
+        if i < len(csvs) - 1:
+            ax.set_xlabel("")
+    fig.suptitle(title or course_label, fontsize=11)
+    handles = draw_burned_profile.last_handles
+    fig.legend(handles=handles, loc="lower center", ncol=min(4, len(handles)), fontsize=8, frameon=False)
+    fig.tight_layout(rect=(0, 0.06 if len(csvs) > 1 else 0.14, 1, 1))
+    fig.savefig(out, dpi=dpi)
+    plt.close(fig)
+    return out