API Reference

This section contains the reference documentation for the public functions and the controllers of the pipeline steps.

Configuration

`plex_pipe.config.config_loaders.load_config(settings_path)`

Loads analysis settings from a YAML file.

Parameters:

Name	Type	Description	Default
`settings_path`	`str \| Path`	Path to the YAML settings file.	required

Returns:

Type	Description
`AnalysisConfig`	The validated AnalysisConfig object.

Raises:

Type	Description
`ValueError`	If the config is a newer schema than this build understands, or if it fails validation (raised with a human-readable message).

`plex_pipe.config.config_loaders.migrate_config(in_path, out_path=None)`

Read an old config, migrate it to the current schema, and write it out.

Writes the upgraded config to a new file by default (never overwrites the original unless out_path is explicitly set to the same path).

Parameters:

Name	Type	Description	Default
`in_path`	`str \| Path`	Path to the config file to migrate.	required
`out_path`	`str \| Path \| None`	Where to write the migrated config. Defaults to `<stem>_v<MAJOR>.<suffix>` next to the input (e.g. `analysis_v2.yaml`).	`None`

Returns:

Type	Description
`Path \| None`	The path written, or `None` if the config was already current.

`plex_pipe.config.config_loaders.save_config_snapshot(config)`

Save the config used for a run into the analysis directory.

Each distinct config is saved once, as <analysis_dir>/configs/config_<hash>.yaml, where <hash> is a short fingerprint of its content. Runs with the same config reuse the same file; a changed config gives a new file. The file holds the config as loaded (already upgraded to the current schema, ${input} steps unexpanded) and can be loaded again with :func:load_config. Its header records when and from which source file it was first written.

Every call logs which snapshot the run used, with the details of this run: source file, the folder the run started from (relative paths are resolved against it), PlexPipe version and schema versions. Nothing is written next to the source file.

Parameters:

Name	Type	Description	Default
`config`	`AnalysisConfig`	A config returned by :func:`load_config`.	required

Returns:

Type	Description
`Path \| None`	The path of the snapshot, or `None` if `config` was not loaded
`Path \| None`	from a file (nothing to save).

Example data

`plex_pipe.datasets.setup_example(dest)`

Sets up a ready-to-run example analysis and returns its config path.

Creates, in dest:

input/: the example images (see :func:fetch_example),
config.yaml: the example config, with absolute paths to input/ and output/,
output/example/rois.pkl (and rois.csv): two small ROIs (:data:EXAMPLE_ROI_CORNERS), so the ROI definition step can be skipped.

Files that already exist are left unchanged, so your edits to the config survive a second call.

Parameters:

Name	Type	Description	Default
`dest`	`str \| Path`	Folder for the example (created if needed).	required

Returns:

Type	Description
`Path`	Path to `config.yaml`, ready for :func:`plex_pipe.load_config`.

`plex_pipe.datasets.fetch_example(dest=None)`

Download and unpack the example dataset, returning its image directory.

The dataset contains DAPI plus three markers (bCat, CD45, NaKATPase) across two TMA cores at full resolution: raw intensities, without annotations.

On the first call the archive is downloaded from the data release and validated against :data:EXAMPLE_DATA_SHA256. Subsequent calls reuse the cached archive and require no network access. The cache is disposable: if it is deleted, the next call downloads the archive again.

Parameters:

Name	Type	Description	Default
`dest`	`str \| Path \| None`	Directory to unpack the images into. Supplying a path means a config whose `general.image_dir` already points at that directory works unchanged, which keeps the config file the single source of truth for where the data lives. When omitted, the images are unpacked into the local cache and that location is returned instead.	`None`

Returns:

Type	Description
`Path`	Path to the directory holding the example `.tiff` images, suitable for
`Path`	use as the config's `general.image_dir`.

Raises:

Type	Description
`RuntimeError`	If the archive contains no images, indicating a corrupt archive or a change to its internal layout.

Channels

`plex_pipe.stages.roi_preparation.channel_scanner.preview_channels(config, gc=None, preset=None)`

Dry run of channel discovery: what will be cut, and why.

Lists image_dir (locally, or over Globus when gc is given), builds the manifest exactly as a run would (from channels.manifest in the config if set, otherwise with the naming preset), applies the selection rules from the channels section, and returns one row per file. Unlike a run it never stops at the first problem: unrecognised files, duplicate channels, files missing from image_dir and files not in the manifest are reported as rows.

To get an editable manifest CSV, call :func:save_manifest with the same config (it does not need this table).

Parameters:

Name	Type	Description	Default
`config`	`AnalysisConfig`	The analysis configuration.	required
`gc`	`GlobusConfig \| None`	Globus configuration, if `image_dir` is on a Globus endpoint.	`None`
`preset`	`str \| None`	Force this naming preset, ignoring the `manifest` in the config (e.g. to start a fresh manifest).	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with columns ``file, marker, round, use, channel, selected,
`DataFrame`	reason``. Selected and candidate rows come first (by channel), then
`DataFrame`	rows needing attention. If later pipeline steps need markers that are
`DataFrame`	not selected, a warning is logged (see
`DataFrame`	func:`check_downstream_markers`).

Raises:

Type	Description
`ValueError`	If `image_dir` contains no TIFF files.
`ManifestError`	If the `manifest` CSV cannot be parsed.

`plex_pipe.stages.roi_preparation.channel_scanner.save_manifest(config, out_path=None, gc=None, preset=None, overwrite=False)`

Write an editable manifest CSV for image_dir.

Builds the manifest the same way :func:preview_channels does (from the manifest CSV if it exists, otherwise with the naming preset) and writes only file, marker, round, use. The selection rules are not saved: they are re-applied on every run. use is written as no only for files already excluded in the manifest and left blank otherwise. Rows needing attention are kept (blank marker, or duplicate channels) so the user can fix them; files missing from image_dir are dropped with a warning.

Workflow: set manifest (under channels:) in the config YAML file to where the CSV should be, reload the config, call this function, then fill in the CSV in any program that opens CSV files.

Parameters:

Name	Type	Description	Default
`config`	`AnalysisConfig`	The analysis configuration.	required
`out_path`	`str \| Path \| None`	Where to write the CSV. Defaults to the `manifest` path from the config if it is set (typically a CSV not created yet), otherwise `channels.csv` in the analysis directory.	`None`
`gc`	`GlobusConfig \| None`	Globus configuration, if `image_dir` is on a Globus endpoint.	`None`
`preset`	`str \| None`	Force this naming preset, ignoring an existing `manifest` CSV (e.g. to start a fresh manifest).	`None`
`overwrite`	`bool`	Replace `out_path` if it exists. Off by default so a hand-edited manifest is never lost by accident.	`False`

Returns:

Type	Description
`Path`	The path written.

Raises:

Type	Description
`FileExistsError`	If `out_path` exists and `overwrite` is False.
`ValueError`	If `image_dir` contains no TIFF files.

Controllers

`RoiPreparationController(metadata_df, file_strategy, temp_dir, output_dir, margin=0, mask_value=0, max_pyramid_levels=3, chunk_size=(1, 256, 256), downscale=2, temp_roi_delete=True)`

Coordinate cutting and assembly of cores from multiplex images.

Initialize the RoiPreparationController.

Parameters:

Name	Type	Description	Default
`metadata_df`	`DataFrame`	DataFrame containing ROI metadata.	required
`file_strategy`	`FileAvailabilityStrategy`	Strategy for retrieving image files.	required
`temp_dir`	`str`	Directory for temporary core files.	required
`output_dir`	`str`	Destination for assembled Zarr outputs.	required
`margin`	`int`	Padding pixels around each core.	`0`
`mask_value`	`int`	Fill value for masked regions.	`0`
`max_pyramid_levels`	`int`	Number of pyramid levels for the output.	`3`
`chunk_size`	`tuple[int, int, int]`	Chunk dimensions (C, Y, X) for the Zarr array.	`(1, 256, 256)`
`downscale`	`int`	Downsampling factor between pyramid levels.	`2`
`temp_roi_delete`	`bool`	Whether to delete intermediate TIFFs after assembly.	`True`

`run()`

Execute the ROI preparation pipeline.

Iterates through available channels, cuts ROIs, and assembles them into SpatialData Zarr stores.

`ResourceBuildingController(builder, input_names, output_names, resolution_level=0, keep=False, overwrite=False, pyramid_levels=1, downscale=2, chunk_size=None)`

Controls the execution of a builder op on a SpatialData object.

This class orchestrates the process of running a BaseOp subclass. It manages input validation, fetching data from the correct resolution, handling overwrites, executing the operation, and saving the results back into the SpatialData object.

Initializes the ResourceBuildingController.

Parameters:

Name	Type	Description	Default
`builder`	`BaseOp`	The processing operation instance (e.g., a filter).	required
`input_names`	`str \| Sequence[str]`	Name or sequence of names of input elements.	required
`output_names`	`str \| Sequence[str]`	Name or sequence of names for output elements.	required
`resolution_level`	`int`	The resolution level to fetch input data from.	`0`
`keep`	`bool`	Whether to save the generated element to disk.	`False`
`overwrite`	`bool`	Whether to overwrite existing elements with the same name.	`False`
`pyramid_levels`	`int`	The number of pyramid levels for the output.	`1`
`downscale`	`int`	The downscaling factor between pyramid levels.	`2`
`chunk_size`	`Sequence[int] \| None`	The chunk size for the output Dask array.	`None`

`validate_sdata_as_input(sdata)`

Runs all input validation checks.

Parameters:

Name	Type	Description	Default
`sdata`	`SpatialData`	The SpatialData object to validate.	required

`run(sdata)`

Executes the full pipeline for the processor.

Starts with running validation of a compatibility of a processor with the sdata object to process.

Parameters:

Name	Type	Description	Default
`sdata`	`SpatialData`	The SpatialData object to process.	required

Returns:

Type	Description
`SpatialData`	The processed SpatialData object.

`QuantificationController(mask_keys, table_name='quantification', mask_to_annotate=None, markers_to_quantify=None, add_qc_masks=False, qc_prefix='qc_exclude', overwrite=False, morphological_properties=None, intensity_properties=None)`

Orchestrates quantification of data within a SpatialData object.

Designed as a stateless service, this class configures and executes a quantification task, processing channels and masks from a SpatialData object.

Initializes the QuantificationController.

Parameters:

Name	Type	Description	Default
`mask_keys`	`dict[str, str]`	Maps a mask suffix to its `sdata.labels` key (e.g., {'cell': 'cell_mask'}). Assumes object labels correspond across masks.	required
`table_name`	`str`	Name for the output AnnData table.	`'quantification'`
`mask_to_annotate`	`str \| None`	Label key to connect the resulting table to.	`None`
`markers_to_quantify`	`list[str] \| None`	List of markers/channels to quantify. If None, all images of the first ROI are quantified, and every later ROI run with this controller must have the same images (so all tables have the same columns).	`None`
`add_qc_masks`	`bool`	If True, runs QC masking after quantification.	`False`
`qc_prefix`	`str`	Prefix for QC exclusion columns.	`'qc_exclude'`
`overwrite`	`bool`	If True, allows overwriting an existing table.	`False`
`morphological_properties`	`list[str] \| None`	List of morphological properties to compute.	`None`
`intensity_properties`	`list[str] \| None`	List of intensity properties to compute.	`None`

`validate_sdata_as_input(sdata)`

Validates that required masks and channels exist in the SpatialData object.

Parameters:

Name	Type	Description	Default
`sdata`	`SpatialData`	The SpatialData object to validate.	required

Raises:

Type	Description
`ValueError`	If a specified mask or channel key is missing, or (with `markers_to_quantify` unset) if this ROI's channels differ from those of the first ROI run with this controller.

`run(sdata)`

Executes the quantification pipeline.

Parameters:

Name	Type	Description	Default
`sdata`	`SpatialData`	The SpatialData object to process.	required