itasc.contact_analysis.catalog

Catalog of contact-analysis positions for Contact Analysis.

Builds, loads, and saves a catalog of positions (each a contact-analysis .h5 plus optional cell/nucleus label images) discovered by file name / relative path via discover_catalog_entries().

Each row anchors on a position_path — the absolute path to the position folder — and stores every file (the contact-analysis .h5, cell labels, nucleus labels) as a path relative to that folder (e.g. contact_analysis.h5, beside the committed labels). Persisting the position folder lets downstream tools (notably the NLS classifier) resolve their own per-position relative paths against it. Older catalogs that lack position_path still load: their file paths are resolved relative to the CSV file’s directory.

Module attributes

CONTACT_ANALYSIS_RELPATH

The contacts .h5 is a derived Contact Analysis output, not a discovery input.

Functions

columns_from_levels(level_names, segments)	Zip level names to folder-name segments; blank/None names drop out.
discover_catalog_entries(root, *[, ...])	Find catalog entries under root by file name / relative path.
discovered_level_depth(root, position_paths)	The shared nesting depth of discovered positions, or None if it varies.
load_catalog(csv_path)	Load CSV catalog records and expose normalized compatibility keys.
merge_catalog_records(existing, incoming)	Append incoming records while skipping duplicate resolved H5 paths.
relative_levels(root, position_path)	The folder-name segments from root (exclusive) to position_path (inclusive).
save_catalog(csv_path, records)	Write catalog records to CSV.

itasc.contact_analysis.catalog.CONTACT_ANALYSIS_RELPATH = 'contact_analysis.h5'

The contacts .h5 is a derived Contact Analysis output, not a discovery input. It lives in the position base folder, beside the committed cell_labels.tif / nucleus_labels.tif — one homogeneous layout for every downstream-stable per-position artifact.

itasc.contact_analysis.catalog.relative_levels(root, position_path)

The folder-name segments from root (exclusive) to position_path (inclusive).

These are the nesting levels a discovered position sits under; the UI names each level once and every position inherits its column values from its own segments (see columns_from_levels()).

Return type:

tuple[str, ...]

Parameters:

• root (Path | str)

• position_path (Path | str)

itasc.contact_analysis.catalog.columns_from_levels(level_names, segments)

Zip level names to folder-name segments; blank/None names drop out.

Extra segments without a paired name (or extra names without a segment) are ignored — only the overlap with a non-blank name becomes a column.

Return type:

dict[str, str]

Parameters:

• level_names (Iterable[str | None])

• segments (Iterable[str])

itasc.contact_analysis.catalog.discovered_level_depth(root, position_paths)

The shared nesting depth of discovered positions, or None if it varies.

Folder-derived columns anchor at the root (level 1 = first folder under root), so the level names line up across positions only when every position sits at the same depth. A None return tells the caller to warn rather than mislabel.

Return type:

int | None

Parameters:

• root (Path | str)

• position_paths (Iterable[Path | str])

itasc.contact_analysis.catalog.load_catalog(csv_path)

Load CSV catalog records and expose normalized compatibility keys.

Only position_path is required. Uniqueness of the position identity (the combination of classification columns) is not checked here — a catalog may hold more positions than any one run aggregates; the aggregator validates uniqueness over the in-scope subset and refuses with an explanation there (see itasc.contact_analysis.shape_tables.aggregate()).

Return type:

list[dict]

Parameters:

csv_path (Path | str)

itasc.contact_analysis.catalog.save_catalog(csv_path, records)

Write catalog records to CSV.

Each row stores the absolute position_path and the position’s files as paths relative to that folder. Records without a known position folder (legacy / hand-made) fall back to paths relative to the CSV file.

Return type:

None

Parameters:

• csv_path (Path | str)

• records (Iterable[dict])

itasc.contact_analysis.catalog.merge_catalog_records(existing, incoming)

Append incoming records while skipping duplicate resolved H5 paths.

Return type:

list[dict]

Parameters:

• existing (Iterable[dict])

• incoming (Iterable[dict])

itasc.contact_analysis.catalog.discover_catalog_entries(root, *, cell_name=None, nucleus_name=None)

Find catalog entries under root by file name / relative path.

A position is any folder that contains at least one recognized input — cell labels and/or nucleus labels, each optional (cell_name / nucleus_name are a bare file name or a path relative to the position folder). A folder is registered once and carries whichever inputs it has; the others are None. The contact-analysis .h5 is a derived Contact Analysis output, not a discovery input: every position’s contact path is the fixed default location (CONTACT_ANALYSIS_RELPATH) and need not exist yet (it is built later by the contacts quantifier). The returned dicts carry the discovered paths but no metadata (date / condition / notes) — that is assigned before adding to the catalog.

Return type:

list[dict]

Parameters:

• root (Path | str)

• cell_name (str | None)

• nucleus_name (str | None)