spacr.original_filenames

Recover original image names on measurement rows without changing sources.

Accept spaCR conversion records, older Yokogawa rename logs, and records produced by sorting image channels. Group records from image channels and z slices by microscope field. Keep timepoints and plates separate.

Do not read image data. Read an embedded conversion_map table without modifying it.

Functions

discover_maps(→ list[pathlib.Path])

Find known map names beside a database and up to three parent folders.

enrich(frame, map_path, *[, expected_sha256, ...])

Return an enriched copy and JSON-safe matching/provenance report.

Module Contents

spacr.original_filenames.discover_maps(db_path) → list[pathlib.Path][source]

Find known map names beside a database and up to three parent folders.

Discovery is bounded and nonrecursive, including the usual plate/measurements/measurements.db layout. It never scans image trees. A SQLite database containing a conversion_map table is also offered.

Parameters:

db_path – measurement database path or dataset directory.

Returns:

existing CSV paths, nearest folder first, followed by the database itself when it contains a conversion_map table.

spacr.original_filenames.enrich(frame, map_path, *, expected_sha256=None, output_column='original_filename')[source]

Return an enriched copy and JSON-safe matching/provenance report.

Rows, index, order and existing columns are preserved. Multiple original images for one field are deduplicated and sorted, joined with '; '. Unmatched values are missing. Existing output columns are never replaced. Ambiguous plate or timepoint matches raise ValueError, as do changed maps when expected_sha256 binds a saved workflow to its reviewed mapping bytes. original_path preserves recorded paths, not a promise they still exist.

Parameters:

  • frame – current measurement DataFrame; never modified.

  • map_path – supported CSV or SQLite database with conversion_map.

  • expected_sha256 – optional digest from an earlier preview. CSV digests bind the exact parsed bytes; SQLite digests bind sorted mapping contents independently of unrelated database writes.

  • output_column – new filename column name; original_path is also added.

Returns:

(enriched DataFrame, JSON-safe report) with mapping provenance, matched/unmatched row counts and up to ten unmatched identity examples.

Raises:

ValueError – for an unsupported or changed map, output collisions, conflicting/ambiguous identities, or zero matches on nonempty data.

Unparseable legacy names can still be restored by their exact target, and a timed filename refines an untimed prcf without merging timepoints.