Report

Note

This page is a reference documentation. It only explains the class signature, and not how to use it. Please refer to the Habitat Guide and Python API guide (v2.0) for usage.

class Report(persist: Tuple[str, ...] = (), retain: str = 'all', figures: Tuple[FigureAtom, ...] = (), writer: ResultWriter | None = None, figure_dir: Path | None = None, figure_layout: str = 'flat', style: str = 'radiology', on_subject_complete: Callable[[Subject, HabitatMap, HabitatModel], None] | None = None)

Bases: object

What to leave on disk and what to keep in memory for one study run.

Construct this in Python (notebook, script, service) and pass it as report= to fit_predict(). YAML / CLI may serialise a subset later; they are not the authoring surface.

persist

Artefacts written per completed subject. First-phase kinds: "habitat_map", "subject_model". Empty by default – passing a writer without persist writes nothing.

Type:

Tuple[str, …]

retain

"all" keeps every artefact in memory (historical default); "maps" drops voxel-level clustering units; "tables" additionally drops habitat maps and therefore requires writer plus "habitat_map" in persist.

Type:

str

figures

Figure atoms drawn after persist, before retention stripping. Empty by default.

Type:

Tuple[habit.report.api.FigureAtom, …]

writer

Streaming destination. Required when retain="tables" or when persist is non-empty.

Type:

habit.contracts.ops.ResultWriter | None

figure_dir

Directory for PNGs. Defaults to <writer.root>/figures when the writer exposes a root.

Type:

pathlib.Path | None

figure_layout

How those PNGs are arranged. "flat" (default) writes <figure_dir>/<stem>.png; "by_subject" writes <figure_dir>/<subject_id>/<kind>.png, stripping a leading <subject_id>_ from the atom stem so the filename is just the figure kind.

Type:

str

style

use_style() preset used when saving figures.

Type:

str

on_subject_complete

Optional escape-hatch callback (subject, habitat_map, model) fired after persist and figures. Prefer a custom FigureAtom when the work is a figure.

Type:

Callable[[habit.contracts.subject.Subject, habit.contracts.habitat.HabitatMap, habit.contracts.habitat.HabitatModel], None] | None

__post_init__() → None

Canonicalise sequences and reject unknown persist / retain / layout values.

property streams: bool

Return whether this report does any per-subject work.

resolve_figure_dir() → Path | None

Return the PNG directory, or None when figures cannot be written.

Returns:

figure_dir when set; otherwise <writer.root>/figures when the writer exposes a filesystem root.

resolve_figure_path(subject_id: str, stem: str) → Path

Return the PNG path for one atom under the current figure_layout.

flat writes <figure_dir>/<stem>.png. by_subject writes <figure_dir>/<subject_id>/<kind>.png, where kind is stem with a leading <subject_id>_ stripped so built-in atoms do not repeat the subject id in the filename.

Parameters:

• subject_id – Subject identifier; used as the subdirectory name when figure_layout="by_subject".

• stem – Filename stem from FigureAtom.stem(subject_id) (no suffix). Built-in atoms return <subject_id>_<kind>.

Returns:

Destination path including the .png suffix.

Raises:

HABITAPIError – If no figure directory can be resolved.

consume_subject(ctx: SubjectContext) → None

Persist, draw, and notify for one completed subject.

Runs in the parent process, including for checkpoint-resumed subjects, so a crash between the backend’s checkpoint write and this call is repaired on resume.

Parameters:

ctx – The completed subject’s map, model, and images.

Raises:

HABITAPIError – If figures are declared but no figure directory can be resolved.

__init__(persist: Tuple[str, ...] = (), retain: str = 'all', figures: Tuple[FigureAtom, ...] = (), writer: ResultWriter | None = None, figure_dir: Path | None = None, figure_layout: str = 'flat', style: str = 'radiology', on_subject_complete: Callable[[Subject, HabitatMap, HabitatModel], None] | None = None) → None