spacr.import_plan

Preview filename parsing and destination paths before importing images.

plan() evaluates filenames, a regular expression, and group roles without opening, copying, or moving files. Its ImportPlan reports every matched rename, every unmatched filename, and any role problem. Output stems use spacr.io._escaped_field_stem(), so the preview matches the paths produced by the import pipeline.

Classes

ImportPlan	Describe matched renames, unmatched files, and role problems.
Renamed	One file, and what the import would call it.

Functions

for_get_regex(→ str)	Prepare a filename pattern for utils._get_regex.
group_names(→ Tuple[str, ...])	The named groups in regex, in the order they appear.
plan(→ ImportPlan)	What the import would do to filenames under regex.
role_trouble(→ Tuple[str, ...])	Return user-facing problems in a regex-group role assignment.

Module Contents

class spacr.import_plan.ImportPlan

Describe matched renames, unmatched files, and role problems.

Parameters:

• renamed – one entry per matched file, in input order.

• unmatched – filenames that did not match the pattern.

• trouble – explanations that make the plan incomplete or unusable. Valid partial results remain available when problems are present.

summary() → str

The one line the panel leads with.

tree() → OrderedDict[str, Any]

The spaCR structure this would produce, with counts at each level.

{plate: {well: {field: Counter(channel -> n)}}}, insertion ordered so the tree reads in the order the files arrived rather than alphabetically – which is what makes a missing well visible.

tree_lines() → Tuple[str, ...]

The tree as indented text, with the counts written in.

property n_files: int

Every file the plan covers, matched or not.

THE DENOMINATOR. A pattern matching 900 files means nothing until you know whether there were 900 or 9,000, and this is the number that makes the first one readable.

Returns:

the total count.

property n_matched: int

How many files the naming pattern resolved.

Returns:

the matched count.

class spacr.import_plan.Renamed

One file, and what the import would call it.

Variables:

• before – basename supplied to the import preview.

• after – TIFF filename that the import would write.

• plate – parsed or fallback plate identifier.

• well – captured well identifier.

• field – captured field-of-view identifier.

• channel – captured imaging-channel identifier.

• time – captured timepoint identifier, or an empty string for a non-timelapse filename.

spacr.import_plan.for_get_regex(pattern: str) → str

Prepare a filename pattern for utils._get_regex.

_get_regex appends its own image-extension pattern. This helper removes a trailing extension match and end anchor to prevent an inferred pattern such as \.(?:tif|tiff|png|jpg|jpeg)$ from receiving a second, unreachable suffix.

Parameters:

pattern (str) – Pattern stored by the import editor.

Returns:

str – The pattern without a trailing supported-image extension or end anchor. Patterns without either are returned unchanged.

spacr.import_plan.group_names(regex: str) → Tuple[str, ...]

The named groups in regex, in the order they appear.

Parameters:

regex – filename regular expression to inspect.

Returns an empty tuple while the pattern is incomplete or invalid.

spacr.import_plan.plan(filenames: Sequence[str], regex: str, roles: Mapping[str, str] | None = None, *, plate: str = '', timelapse: bool = False) → ImportPlan

What the import would do to filenames under regex.

Parameters:

• filenames – bare names, as dropped. Paths are reduced to their basename, because that is what the regex is matched against.

• regex – the pattern, with named groups.

• roles – {group name: role}, overriding the captured group name. A group whose name is already a role needs no entry.

• plate – the plate to use when no group supplies one – the import falls back to the source folder’s name, so the preview does too.

• timelapse – pass the timepoint through to the stem.

Returns:

an ImportPlan. Invalid patterns and missing roles are reported in ImportPlan.trouble rather than raised.

spacr.import_plan.role_trouble(roles: Mapping[str, str]) → Tuple[str, ...]

Return user-facing problems in a regex-group role assignment.

Parameters:

roles – named capture groups mapped to their selected import roles.

Duplicate roles and missing required roles are reported before import so no captured group is silently ignored.