spacr.qc_quarantine

Reversible, auditable exclusion of merged fields from measurement.

Measurement discovers work by enumerating merged/*.npy. Quarantine therefore needs no exclusion database: moving one array to the sibling merged_quarantined/ folder removes it from the next run, while leaving every mask stack untouched. A JSON ledger beside the moved array records who made that decision, when, and which segmentation-QC flags prompted it.

The functions in this module deliberately have no Qt dependency. They are usable from the field browser, a notebook, or a headless audit script and can be tested without constructing an application.

Exceptions

QuarantineError

A field could not be quarantined or restored without losing data.

Functions

is_quarantined(→ bool)	Return whether the sibling quarantine currently holds field.
list_quarantined(→ List[str])	Return sorted field stems currently excluded from merged/*.npy.
quarantine_dir_for(→ pathlib.Path)	Return <plate>/merged_quarantined for <plate>/merged.
quarantine_field(, who)	Move one merged array out of measurement and write its audit record.
quarantine_record_path(→ pathlib.Path)	Return the audit sidecar path for one quarantined field.
resolve_field_path(→ Optional[pathlib.Path])	Locate a field in merged or its quarantine, active copy first.
restore_field(→ pathlib.Path)	Move one quarantined array back to its sibling merged folder.

Module Contents

exception spacr.qc_quarantine.QuarantineError

Bases: RuntimeError

A field could not be quarantined or restored without losing data.

Initialize self. See help(type(self)) for accurate signature.

spacr.qc_quarantine.is_quarantined(merged_dir: _PathValue, field: _PathValue) → bool

Return whether the sibling quarantine currently holds field.

Parameters:

• merged_dir – plate merged directory whose quarantine is checked.

• field – field stem, with an optional .npy suffix, to locate.

spacr.qc_quarantine.list_quarantined(merged_dir: _PathValue) → List[str]

Return sorted field stems currently excluded from merged/*.npy.

Parameters:

merged_dir – plate merged directory whose quarantine is listed.

spacr.qc_quarantine.quarantine_dir_for(merged_dir: _PathValue) → pathlib.Path

Return <plate>/merged_quarantined for <plate>/merged.

Parameters:

merged_dir – validated plate merged directory.

spacr.qc_quarantine.quarantine_field(merged_dir: _PathValue, field: _PathValue, *, flags: Iterable[str] = (), who: str | None = None) → pathlib.Path

Move one merged array out of measurement and write its audit record.

Parameters:

• merged_dir – the plate’s merged directory.

• field – a spacr.seg_qc.FieldQC field stem (.npy is accepted too).

• flags – the QC flags that motivated this decision.

• who – actor recorded in the ledger; defaults to the OS account.

Returns:

the new merged_quarantined/<field>.npy path.

Raises:

• FileNotFoundError – when the merged array is already gone.

• FileExistsError – rather than overwriting an existing quarantine.

If the sidecar cannot be written, the array is moved back before the exception is raised. An unaudited quarantine is never reported as a successful operation.

spacr.qc_quarantine.quarantine_record_path(quarantine_dir: _PathValue, field: _PathValue) → pathlib.Path

Return the audit sidecar path for one quarantined field.

Parameters:

• quarantine_dir – plate merged_quarantined directory.

• field – merged-field stem, with an optional .npy suffix.

spacr.qc_quarantine.resolve_field_path(merged_dir: _PathValue, field: _PathValue) → pathlib.Path | None

Locate a field in merged or its quarantine, active copy first.

Parameters:

• merged_dir – plate merged directory to search first.

• field – field stem, with an optional .npy suffix, to locate.

spacr.qc_quarantine.restore_field(quarantine_dir: _PathValue, field: _PathValue, *, who: str | None = None) → pathlib.Path

Move one quarantined array back to its sibling merged folder.

Parameters:

• quarantine_dir – plate merged_quarantined directory.

• field – field stem, with an optional .npy suffix, to restore.

The sidecar remains in merged_quarantined as the plate’s audit trail and gains a restoration event. As with quarantine, a ledger-write failure rolls the file move back.