spacr.errors¶

Fail-loud error accounting for spaCR pipelines.

spaCR processes batches — 384 wells, thousands of fields, dozens of image files. A single unreadable image must not abort the plate, so almost every batch loop in the codebase wraps its body in try/except Exception and carries on. The historical problem was not the surviving; it was that the survival left no trace: forty wells would fail to segment, forty lines would scroll past in a log nobody was watching, measurements.db would be written anyway, and every downstream regression would silently run on 344 wells while reporting as if it had 384.

This module supplies the missing half — survive, but account for it, and make the accounting impossible to miss:

RunLedger records every per-item success and failure, logs each failure at ERROR with the item id and traceback, and prints one loud, grouped block at the end of the run.
RunLedger.stamp() writes that verdict into the artifact — a run_status table inside a SQLite database, or a sibling <name>.run_status.json next to any other output — so a later reader can tell that the result is partial.
read_run_status() / run_is_complete() / assert_run_complete() let downstream code check before it trusts a file.
ConfigurationError marks the failures that must not be survived. A wrong src path or a missing metadata column is not a per-item problem — continuing past it only produces garbage. RunLedger.item() deliberately re-raises it.

Typical adoption inside a batch loop:

from .errors import RunLedger

ledger = RunLedger('convert_to_yokogawa')
for file in files:
    with ledger.item(file, stage='convert'):
        convert(file)
ledger.finalize(artifact=csv_path)

and downstream, before trusting the output:

from spacr.errors import run_is_complete
if not run_is_complete(db_path):
    ...            # the numbers in here are computed on a subset

The module is deliberately stdlib-only. It is imported by io/core/measure/deep_spacr/plot at module scope, so it must never drag in torch, cellpose, pandas or numpy.

Exceptions¶

`ConfigurationError`	The run was set up wrongly and cannot produce a valid result.
`DataIntegrityError`	The data produced cannot be trusted.
`PartialRunError`	Raised by `RunLedger.raise_if_worse_than()` past the threshold.
`RunStatusUnreadable`	The stamp could not be read, so the run's verdict is unknown.
`SpacrError`	Base class for every spaCR-raised error.

Classes¶

`Failure`	One recorded per-item failure.
`RunLedger`	Accounting for one batch run: what was attempted, what failed, and why.

Functions¶

`assert_run_complete`(→ None)	Raise `DataIntegrityError` if `artifact` is stamped partial.
`raise_if_strict`(→ bool)	Raise `error_type(message)` in strict mode; otherwise log it at `ERROR`.
`read_run_status`(→ List[Dict[str, Any]])	Read back every `RunLedger.stamp()` recorded for `artifact`.
`run_is_complete`(→ bool)	True when no stamp on `artifact` recorded a failure.
`strict_errors`(→ bool)	True when recoverable setup errors should be raised instead of printed.

Module Contents¶

exception spacr.errors.ConfigurationError[source]¶

Bases: SpacrError

The run was set up wrongly and cannot produce a valid result.

A missing src folder, an unparseable regex, a metadata column that does not exist. These are not per-item failures: continuing past one produces garbage for every item, so RunLedger.item() re-raises this instead of recording it.