Development and exploration

CryoSwath production functions sometimes expose opt-in diagnostic hooks. These hooks are meant for development, improvement, exploration, introspection, validation, and, when something behaves unexpectedly, debugging.

The hook pattern keeps the numerical code quiet by default. Core routines do not import plotting libraries or external workflow helpers. Instead, callers can pass a small callback when they want to inspect intermediate state:

events = []

def capture_event(name, payload):
    events.append((name, payload))

filled = cryoswath.misc.interpolate_hypsometrically(
    ds,
    "_median",
    "_iqr",
    diagnostic_hook=capture_event,
)

The callback receives a stable event name and a payload with the objects that were already computed at that stage. For example, hypsometric interpolation can emit events such as hypsometry.model_preview and hypsometry.fit_fill_mask. Plotting helpers in cryoswath.test_plots.hypsometry can turn those payloads into quick-look figures.

Lab environment

For interactive exploration with the optional snippets helpers, use the Pixi lab environment:

pixi install -e lab
pixi shell -e lab

The environment adds an IPython kernel and the snippets package. It does not install a notebook server; open notebooks from your editor or a Jupyter frontend of your choice.

If you manage environments with conda or mamba, create the environment there and install the lab extra with pip:

mamba create -n cryoswath-lab python=3.12
mamba activate cryoswath-lab
pip install "cryoswath[lab]"

Writing artifacts

The optional snippets.debugging.Diagnostics helper is useful in external scripts and exploratory notebooks when you want selected plots or reports written to disk:

from snippets.debugging import Diagnostics
from cryoswath.test_plots import hypsometry

diagnostics = Diagnostics(
    enabled=True,
    outdir="debug/hypsometry",
    only={"hypsometry.fit_fill_mask"},
)

def write_diagnostic(name, payload):
    def write(path):
        result = hypsometry.plot_event(name, payload)
        fig = result if hasattr(result, "savefig") else result.figure
        fig.savefig(path / "plot.png", dpi=150, bbox_inches="tight")

    diagnostics.emit(name, write)

CryoSwath itself does not depend on snippets. This keeps production workflows dependency-light while still making rich introspection available to home-grown workflows.

Tutorial

The packaged notebook tutorial__diagnostic_hooks.ipynb walks through the same workflow with synthetic data. Copy it into a project with:

cryoswath get-tutorials

Then open tutorials/tutorial__diagnostic_hooks.ipynb with the lab kernel or with any environment that has CryoSwath installed.