spacr.host_pathogen¶

Workflow inputs and outputs¶

Host–Pathogen Analysis¶

Measure whole vacuoles and host reference compartments, keeping uninfected host cells for the infection denominator. Select marker channels and control-calibrated ratio thresholds. Optionally count individually segmented parasites from explicit vacuole links or a measured count column. Review vacuole, host and well tables, joint marker states, replication distributions and unmatched parasite links; unknown measurements remain unknown.

Open: Toxoplasma → Host–Pathogen Analysis.

Inputs and outputs below include conditional alternatives. The guidance and handoff notes say which route applies.

Inputs

Measured objects — measurements/measurements.db; object tables depend on the enabled cell, nucleus, pathogen and organelle masks. Relevant tables, depending on the route: cell, nucleus, pathogen, cytoplasm. Relevant columns, depending on the route: plateID, rowID, columnID, fieldID.

Outputs

Assay results — Assay-specific result tables and figures in the configured destination, preserving well and condition identities.

Before this module

Measure: Keep uninfected cells in Measure. Supply whole-vacuole masks, host reference intensities and optional explicit parasite-to-vacuole links; host identity alone does not define a vacuole.

API reference.

Module tutorial.

Vacuole recruitment and replication with explicit host-cell denominators.

Functions¶

`analyze_host_pathogen`([settings])	Analyze measured projects and save a unified, source-separated report.
`default_settings`([settings])	Apply Host–Pathogen defaults; replication requires explicit count inputs.
`summarize_tables`(cells, vacuoles, reference[, ...])	Join per-vacuole signals to host references and retain every host cell.
`vacuole_links`(child_mask, vacuole_mask)	Link each child label only when one vacuole covers most of its pixels.

Module Contents¶

spacr.host_pathogen.analyze_host_pathogen(settings=None)[source]¶

Analyze measured projects and save a unified, source-separated report.

Parameters:: settings – hp_* settings from default_settings(); src accepts a project, measurements.db, or a list of either. Each canonical DB path is a distinct source identity, even when plate/field IDs repeat.
Returns:: combined DataFrames from summarize_tables() and settings. CSV files and the exact settings JSON are written to the first project’s results/host_pathogen directory when save is true. Host infection fractions describe retained measured cells. Run Measure with uninfected=True to include uninfected hosts in that denominator; previously discarded hosts cannot be reconstructed from these tables.

spacr.host_pathogen.default_settings(settings=None)[source]¶

Apply Host–Pathogen defaults; replication requires explicit count inputs.

Parameters:: settings – optional overrides, copied without modifying the caller.
Returns:: settings with independent mutable defaults.

spacr.host_pathogen.summarize_tables(cells, vacuoles, reference, parasites=None, *, settings=None, source='experiment')[source]¶

Join per-vacuole signals to host references and retain every host cell.

Parameters:

cells – one row per host, including uninfected cells.
vacuoles – one row per segmented vacuole, with object_label/cell_id.
reference – one row per host reference compartment, object_label identifying its host, with channel mean-intensity columns.
parasites – optional independently segmented parasites with an explicit parent-vacuole column; never infer parentage from cell ID.
settings – hp_* options. Marker thresholds apply to vacuole/reference ratios. Threshold channel keys must be integer indices or their JSON string form; duplicate aliases are rejected. A count column or parasite table is required for replication; otherwise counts remain missing. These two inputs are mutually exclusive.
source – experiment/acquisition identity, preserved in every output.

Returns:

dict of vacuoles, cells, wells, marker_states and orphan_parasites DataFrames. Missing references and invalid denominators stay unknown; extracellular or unlinked vacuoles do not inflate host infection rates.

Raises:

ValueError – ambiguous identities, missing columns or invalid policy.

spacr.host_pathogen.vacuole_links(child_mask, vacuole_mask)[source]¶

Link each child label only when one vacuole covers most of its pixels.

Parameters:

child_mask – integer parasite/object mask, zero background.
vacuole_mask – co-registered integer whole-vacuole mask.

Returns:

label, pathogen_id and pathogen_overlap_fraction columns. A parent must cover strictly more than half the child; ties, outside objects and ambiguous overlaps retain missing parent identities. This geometric link does not assign biological meaning to an object.