itasc.contact_analysis.contacts.batch

Name-based batch discovery and headless contact-analysis builds.

The standalone contact piece is visualizer-first; the .h5 it shows is a pure derived artifact of the label inputs. This module lets users pre-compute that artifact for many positions at once: name the three files (cell labels, optional nucleus labels, output .h5), point at one top-level folder, and every folder that contains a cell-labels file becomes one job. A nucleus file is associated only when it sits in that same folder; otherwise the job runs cell-only. Outputs that already exist are skipped unless overwrite is set.

Position-agnostic and napari-free: shipped by the itasc-aggregate wheel.

Functions

discover_contact_batch_jobs(root, *, ...[, ...])

Find contact-analysis jobs under root by file name.

run_contact_batch(jobs, *[, overwrite, ...])

Build the contact-analysis HDF5 for each job, collecting per-job outcomes.

Classes

ContactBatchJob(group_dir, cell_labels, output)

One discovered contact-analysis build: a cell-labels file and where its output goes, with an optional co-located nucleus-labels file.

ContactBatchResult(job, status[, error])

Outcome of a single ContactBatchJob.
class itasc.contact_analysis.contacts.batch.ContactBatchJob(group_dir, cell_labels, output, nucleus_labels=None)[source]

Bases: object

One discovered contact-analysis build: a cell-labels file and where its output goes, with an optional co-located nucleus-labels file.

Parameters:

  • group_dir (Path)

  • cell_labels (Path)

  • output (Path)

  • nucleus_labels (Path | None)

group_dir: Path
cell_labels: Path
output: Path
nucleus_labels: Path | None = None
class itasc.contact_analysis.contacts.batch.ContactBatchResult(job, status, error=None)[source]

Bases: object

Outcome of a single ContactBatchJob.

status is "built" (computed), "skipped" (output already present), or "failed" (error holds the message).

Parameters:
job: ContactBatchJob
status: str
error: str | None = None
itasc.contact_analysis.contacts.batch.discover_contact_batch_jobs(root, *, cell_name, h5_name, nucleus_name=None)[source]

Find contact-analysis jobs under root by file name.

Files are discovered recursively, then grouped by position folder — the first directory under root on the path to each match (root itself for files lying directly in it). The named files of one position may live in different subfolders (e.g. pos01/3_cell/ and pos01/2_nucleus/); they are still grouped together.

For a position with exactly one cell-labels file, that file is one job whose output is <position>/<h5_name>; the nucleus is associated only when exactly one nucleus_name file exists anywhere in that position (zero or several → cell-only, “can’t associate → don’t assign”). A position holding several cell-labels files is ambiguous to group, so each falls back to a cell-only job written beside its own cell file. Jobs are sorted by cell path.

Return type:

list[ContactBatchJob]

Parameters:
itasc.contact_analysis.contacts.batch.run_contact_batch(jobs, *, overwrite=False, edge_extraction_params=None, progress_cb=None, cancel=None)[source]

Build the contact-analysis HDF5 for each job, collecting per-job outcomes.

A single job’s failure never aborts the run — it is recorded as a failed result and the batch continues. cancel is polled before each job; progress_cb(done, total, label) is reported after each.

Return type:

list[ContactBatchResult]

Parameters: