spacr.qt.regex_detect

Filename-metadata regex helpers for drag-and-drop and manual configuration.

Central place for four related concerns:

  • apply_regex() — run a compiled regex over a list of filenames, return a list of MetadataRecord dicts (one per file that matched).

  • validate_records() — check whether the parsed records supply the fields the rest of spaCR needs (wellID/fieldID + chanID for multi-channel; fieldID for single-channel). Returns human-friendly warning strings for anything missing.

  • auto_detect_regex() — heuristic detector that tries each built-in regex, and if none fit, synthesises a fresh one from the common shape of the sampled filenames.

  • tabulate_records() — render a small aligned text table of records for the Console.

Public constants:

  • BUILTIN_REGEXES — ordered {label: pattern} map tried by auto_detect_regex() before falling back to synthesis.

  • REQUIRED_MULTICHANNEL / REQUIRED_SINGLECHANNEL — which group names must be present for spaCR to be happy.

Classes

MetadataRecord

One parsed filename.

Functions

apply_regex(→ Tuple[List[MetadataRecord], List[str]])

Run pattern over each filename and return matched records.

auto_detect_regex(→ Tuple[Optional[str], str, int])

Return the best-fitting regex for a set of filenames.

tabulate_records(→ str)

Render a small aligned-column table of records for the Console.

validate_records(→ List[str])

Check parsed records against spaCR's downstream requirements.

Module Contents

class spacr.qt.regex_detect.MetadataRecord[source]

One parsed filename.

Variables:

  • filename – bare filename (no path).

  • groups – mapping of regex group name → matched text.

get(name: str, default: str = '') → str[source]

One captured group, or default when the pattern did not capture it.

Parameters:

  • name – the group’s name.

  • default – what to return when it is absent.

Returns:

the captured text.

spacr.qt.regex_detect.apply_regex(filenames: Sequence[str], pattern: str) → Tuple[List[MetadataRecord], List[str]][source]

Run pattern over each filename and return matched records.

Parameters:

  • filenames – bare filenames (no directory).

  • pattern – regex string; anchored with re.match semantics.

Returns:

(records, non_matching_filenames).

spacr.qt.regex_detect.auto_detect_regex(filenames: Sequence[str]) → Tuple[str | None, str, int][source]

Return the best-fitting regex for a set of filenames.

Strategy:

  1. Try every BUILTIN_REGEXES pattern; if one matches every file it wins immediately.

  2. Otherwise pick the built-in that matches the MOST files (>=50 %).

  3. If nothing crosses the 50 % bar, synthesise a fresh regex from the common shape of the sample (see _synthesise_regex()).

Parameters:

filenames – sample filenames to fit against.

Returns:

(pattern_or_None, label, n_matches). pattern_or_None is None only when synthesis also fails.

spacr.qt.regex_detect.tabulate_records(records: Sequence[MetadataRecord], columns: Sequence[str] | None = None, max_rows: int = 10, random_sample: bool = True, seed: int = 42) → str[source]

Render a small aligned-column table of records for the Console.

Parameters:

  • records – list of parsed records.

  • columns – which group names to include; auto-inferred from the first record when None.

  • max_rows – cap on rows; sampled at random if exceeded.

  • random_sample – True → pick max_rows at random when the list is longer; False → take the first max_rows.

  • seed – RNG seed so the sample is reproducible between runs.

Returns:

multi-line string ready to feed to ConsolePanel.append_stdout().

spacr.qt.regex_detect.validate_records(records: Sequence[MetadataRecord], multichannel: bool = True) → List[str][source]

Check parsed records against spaCR’s downstream requirements.

Parameters:

  • records – output of apply_regex().

  • multichannel – True if the dataset has more than one channel; False for single-channel data (relaxes the requirement set).

Returns:

list of warning strings — empty when everything is fine.