radiens_qc.cache

Reuse a saved report instead of running the pipeline again.

One coarse decision against a whole report directory: the key matches, the report is read from disk and the server is never touched; it does not, the pipeline runs and overwrites. force=True skips the comparison.

The key covers only what would require the server to redo work -- the dataset being measured and the detection settings measured through. Everything else a caller can vary is deliberately outside it:

window_sec, metrics and channels do change what the server produces, so varying one and taking a hit returns a report that does not answer what was asked. force is the way out.
:class:~radiens_qc.report.QualityThresholds never reaches the server at all -- five of its nine fields are colorbar bounds -- so keying on it would make nudging a color scale trigger a full recompute. Thresholds are instead re-applied when the report is read, by :func:~radiens_qc.persist.load_report.

Values are hashed as requested, never as resolved. Resolving them means asking the server, which is the call being avoided, and resolution is deterministic given the dataset -- so the requested form decides the same question while staying knowable up front.

Classes

Functions:

compute_or_load_report

compute_or_load_report(
    vc,
    data,
    out_dir,
    *,
    force=False,
    source=None,
    window_sec=None,
    channels=None,
    metrics=DEFAULT_METRICS,
    thresholds=None,
    detection=DEFAULT_DETECTION,
)

Load out_dir's report for this recording, or compute and save it.

A hit still applies thresholds to the loaded report, since thresholds are not part of the key -- so changing a grading bar regrades in-process instead of costing a recompute.

Parameters:

Name	Type	Description	Default
`vc`	`VidereClient`	Client connected to the server that would do the computation.	required
`data`	`DatasetMetadata \| Path`	An already-linked recording, or a path to link. Linking is idempotent and is the one server call a cache hit still makes; it is what yields the identity the key is built from.	required
`out_dir`	`Path`	Parent directory holding one subdirectory per recording, as :func:`~radiens_qc.persist.save_report` writes it.	required
`force`	`bool`	Recompute and overwrite even when the key matches.	`False`
`source`	`str \| None`	See :func:`~radiens_qc.compute.compute_report`. Outside the key: a provenance label this package never measures through.	`None`
`window_sec`	`float \| None`	See :func:`~radiens_qc.compute.compute_report`. Outside the key -- pass `force` when changing it.	`None`
`channels`	`Sequence[int] \| None`	See :func:`~radiens_qc.compute.compute_report`. Outside the key -- pass `force` when changing it.	`None`
`metrics`	`Sequence[FlexKpiMetricId]`	See :func:`~radiens_qc.compute.compute_report`. Outside the key -- pass `force` when changing it.	`DEFAULT_METRICS`
`thresholds`	`QualityThresholds \| None`	Channel-classification thresholds, applied on load as well as on compute.	`None`
`detection`	`DetectionSettings`	Stage-2 filters and detection threshold. Part of the key.	`DEFAULT_DETECTION`

Returns:

Type	Description
`QualityReport`	The loaded or freshly computed report.

report_cache_key

report_cache_key(*, dataset_path, base_name, detection)

Digest identifying the pipeline run a saved report came from.

Adding a field here invalidates every existing key, which is the correct behavior: a key that does not cover something the server acts on is a key that can hand back the wrong report.