Provenance

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 Provenance(produced_by: str, spec_fingerprint: str, inputs: ~typing.Tuple[~habit.contracts.provenance.Provenance, ...] = (), software: ~typing.Mapping[str, str] = <factory>, random_seed: int | None = None, created_at: str | None = None, notes: ~typing.Mapping[str, ~typing.Any] = <factory>)[source]

Bases: object

Immutable record answering “how was this object produced?”.

produced_by

Registered component name that created this object, e.g. "supervoxelizer.slic".

Type:

str

spec_fingerprint

Stable hash of the algorithm specification used, so two runs can be compared for scientific equivalence.

Type:

str

inputs

Provenance of every object consumed to produce this one. This forms a directed acyclic graph back to the raw images.

Type:

Tuple[habit.contracts.provenance.Provenance, …]

software

Version fingerprint of HABIT and the scientifically relevant dependencies (e.g. PyRadiomics, SimpleITK, scikit-learn).

Type:

Mapping[str, str]

random_seed

Seed in effect for this scientific result, or None when no seeded step contributed. Deterministic derivations inherit the parent’s seed via derive() unless cleared explicitly.

Type:

int | None

created_at

ISO-8601 UTC timestamp.

Type:

str | None

notes

Free-form annotations that must never be required for reproduction; they exist for human readers only.

Type:

Mapping[str, Any]

derive(*, produced_by: str, spec_fingerprint: str, random_seed: int | None | object = <object object>) → Provenance[source]

Create the provenance of an object derived from this one.

Operator authors never write provenance by hand; base classes call this so that the propagation rule stays uniform across the codebase. The software fingerprint is inherited from self (the environment does not change mid-pipeline) and the timestamp is stamped here.

The random seed follows the same inheritance rule unless overridden: a deterministic step that does not mention seeding must not erase the seed that defined the scientific result upstream (for example, attaching cohort-level feature preprocessing to a fitted HabitatModel). Pass random_seed= explicitly to record a new seed, or random_seed=None to clear it.

Parameters:

  • produced_by – Registered name of the component doing the derivation.

  • spec_fingerprint – Fingerprint of that component’s specification.

  • random_seed – Seed used by the derivation. Omitted (default) keeps self.random_seed; None clears; an int replaces.

Returns:

A new Provenance whose inputs contains self.

classmethod source(produced_by: str) → Provenance[source]

Create the root provenance of an object that has no HABIT inputs.

Used for objects entering the pipeline from the outside world (raw images, user-constructed arrays) so that every derived record still terminates at a well-defined root.

Parameters:

produced_by – Description of the external origin, e.g. "directory_source" or "user_array".

Returns:

A provenance record with no inputs and the current software fingerprint.

__init__(produced_by: str, spec_fingerprint: str, inputs: ~typing.Tuple[~habit.contracts.provenance.Provenance, ...] = (), software: ~typing.Mapping[str, str] = <factory>, random_seed: int | None = None, created_at: str | None = None, notes: ~typing.Mapping[str, ~typing.Any] = <factory>) → None