clearex.workflow

Functions

analysis_chainable_output_component(...)

Return the reusable latest-output component for one operation.

analysis_operation_for_output_component(...)

Return the producing operation for one known output component.

collect_analysis_input_references(*, ...)

Collect input references from the selected analysis sequence.

dask_backend_from_dict(payload)

Deserialize a backend mapping into DaskBackendConfig.

dask_backend_to_dict(config)

Serialize Dask backend config into JSON-friendly mappings.

default_analysis_operation_parameters()

Return independent default analysis operation parameters.

format_chunks(chunks)

Format a chunk specification for display.

format_dask_backend_summary(config)

Format a compact summary of the selected Dask backend.

format_local_cluster_recommendation_summary(...)

Format a human-readable summary of local-cluster recommendations.

format_pyramid_levels(levels)

Format pyramid factors for one axis.

format_spatial_calibration(config)

Format a spatial calibration in canonical text form.

format_zarr_chunks_ptczyx(chunks_ptczyx)

Format chunk sizes for display in (p, t, c, z, y, x) order.

format_zarr_pyramid_ptczyx(pyramid_ptczyx)

Format pyramid factors for display in (p, t, c, z, y, x) order.

normalize_analysis_operation_parameters(...)

Normalize analysis operation parameter mappings.

normalize_analysis_targets(targets)

Normalize workflow analysis targets.

normalize_spatial_calibration(value)

Normalize flexible spatial-calibration payloads.

parse_chunks(chunks)

Parse chunk spec from CLI/GUI text.

parse_pyramid_levels(levels, *, axis_name)

Parse comma-separated pyramid factors for a single axis.

parse_spatial_calibration(mapping)

Parse CLI/GUI text into a spatial calibration configuration.

recommend_local_cluster_config(*[, ...])

Recommend aggressive LocalCluster settings from host/data characteristics.

resolve_analysis_execution_sequence(*, ...)

Resolve selected analyses into execution order.

resolve_analysis_input_component(...[, ...])

Resolve an analysis input alias to a component path.

selected_analysis_operations(*, flatfield, ...)

Collect enabled analysis operation names.

spatial_calibration_from_dict(payload)

Deserialize spatial calibration from metadata payloads.

spatial_calibration_to_dict(config)

Serialize spatial calibration for Zarr attrs and provenance.

to_tpczyx_chunks(chunks_ptczyx)

Convert chunk sizes from (p, t, c, z, y, x) to (t, p, c, z, y, x).

to_tpczyx_pyramid(pyramid_ptczyx)

Convert pyramid factors from (p, t, c, z, y, x) to (t, p, c, z, y, x).

validate_analysis_input_references(*, ...[, ...])

Validate selected analysis input references.

zarr_save_from_dict(payload)

Deserialize a Zarr save configuration from a mapping payload.

zarr_save_to_dict(config)

Serialize a Zarr save configuration to a JSON-safe mapping.

Classes

AnalysisInputDependencyIssue(...[, ...])

Description of one invalid analysis input dependency.

AnalysisInputReference(consumer_operation, ...)

One analysis input reference used for dependency validation.

AnalysisTarget(experiment_path, store_path)

Resolved experiment/store pair available to the analysis dialog.

DaskBackendConfig([mode, local_cluster, ...])

Shared Dask backend configuration for GUI and headless execution.

LocalClusterConfig([n_workers, ...])

Runtime options for local Dask distributed execution.

LocalClusterRecommendation(config, ...)

Recommended LocalCluster settings derived from host and data context.

SlurmClusterConfig([workers, cores, ...])

Runtime options for launching a Dask SLURMCluster.

SlurmRunnerConfig([scheduler_file, ...])

Runtime options for connecting through dask_jobqueue.SLURMRunner.

SpatialCalibrationConfig([...])

Store-level stage-to-world axis mapping for multiposition placement.

WorkflowConfig([file, analysis_targets, ...])

Runtime workflow options shared by GUI and headless entrypoints.

ZarrSaveConfig([chunks_ptczyx, pyramid_ptczyx])

Configuration for analysis-store chunking and pyramid downsampling.

Exceptions

WorkflowExecutionCancelled

Raised when a running workflow is cancelled by the operator.
class clearex.workflow.AnalysisInputReference(consumer_operation, field_name, requested_source)

Bases: object

One analysis input reference used for dependency validation.

Parameters:

  • consumer_operation (str) – Analysis operation consuming the reference.

  • field_name (str) – Parameter field name carrying the reference.

  • requested_source (str) – Requested alias or component path.

consumer_operation: str
field_name: str
requested_source: str
class clearex.workflow.AnalysisInputDependencyIssue(consumer_operation, field_name, requested_source, reason, message, producer_operation=None, resolved_component=None)

Bases: object

Description of one invalid analysis input dependency.

Parameters:

  • consumer_operation (str) – Analysis operation consuming the reference.

  • field_name (str) – Parameter field name carrying the reference.

  • requested_source (str) – Requested alias or component path.

  • reason (str) – Machine-readable reason key.

  • message (str) – Human-readable validation message.

  • producer_operation (str, optional) – Upstream producer operation when the reference maps to one.

  • resolved_component (str, optional) – Expected component path for the requested source when known.

consumer_operation: str
field_name: str
requested_source: str
reason: str
message: str
producer_operation: Optional[str] = None
resolved_component: Optional[str] = None
clearex.workflow.analysis_chainable_output_component(operation_name)

Return the reusable latest-output component for one operation.

Parameters:

operation_name (str) – Candidate operation key.

Returns:

Reusable component path when the operation exposes one, otherwise None.

Return type:

str, optional

clearex.workflow.analysis_operation_for_output_component(component)

Return the producing operation for one known output component.

Parameters:

component (str) – Output component path.

Returns:

Operation key when the component is a known latest-output location, otherwise None.

Return type:

str, optional

clearex.workflow.resolve_analysis_input_component(requested_source, produced_components=None)

Resolve an analysis input alias to a component path.

Parameters:

  • requested_source (str) – Requested alias or explicit component path.

  • produced_components (mapping[str, str], optional) – Components produced earlier in the current workflow run.

Returns:

Resolved component path suitable for store lookup.

Return type:

str

clearex.workflow.collect_analysis_input_references(*, execution_sequence, analysis_parameters)

Collect input references from the selected analysis sequence.

Parameters:

  • execution_sequence (sequence[str]) – Selected operations in execution order.

  • analysis_parameters (mapping[str, mapping[str, Any]]) – Candidate normalized or denormalized per-operation parameters.

Returns:

Collected references, including visualization volume-layer components.

Return type:

tuple[AnalysisInputReference, …]

clearex.workflow.validate_analysis_input_references(*, execution_sequence, analysis_parameters, available_components=None)

Validate selected analysis input references.

Parameters:

  • execution_sequence (sequence[str]) – Selected operations in execution order.

  • analysis_parameters (mapping[str, mapping[str, Any]]) – Candidate normalized or denormalized per-operation parameters.

  • available_components (collection[str], optional) – Components currently available in the active analysis store.

Returns:

Validation issues for invalid references. Empty when configuration is dependency-safe under the current sequence and available components.

Return type:

tuple[AnalysisInputDependencyIssue, …]

exception clearex.workflow.WorkflowExecutionCancelled

Bases: RuntimeError

Raised when a running workflow is cancelled by the operator.

clearex.workflow.default_analysis_operation_parameters()

Return independent default analysis operation parameters.

Parameters:

None –

Returns:

Deep-copied default analysis parameter mapping keyed by analysis name.

Return type:

dict[str, dict[str, Any]]

clearex.workflow.normalize_analysis_operation_parameters(parameters)

Normalize analysis operation parameter mappings.

Parameters:

parameters (dict[str, dict[str, Any]], optional) – Candidate parameter mapping keyed by analysis operation name.

Returns:

Normalized mapping merged with defaults.

Return type:

dict[str, dict[str, Any]]

Raises:

ValueError – If known operation parameters are malformed.

clearex.workflow.selected_analysis_operations(*, flatfield, deconvolution, shear_transform, fusion, particle_detection, usegment3d, registration, display_pyramid, visualization, render_movie, compile_movie, volume_export, mip_export)

Collect enabled analysis operation names.

Parameters:

  • flatfield (bool) – Whether flatfield correction is enabled.

  • deconvolution (bool) – Whether deconvolution is enabled.

  • shear_transform (bool) – Whether shear transform is enabled.

  • fusion (bool) – Whether fusion is enabled.

  • particle_detection (bool) – Whether particle detection is enabled.

  • usegment3d (bool) – Whether usegment3d segmentation is enabled.

  • registration (bool) – Whether registration is enabled.

  • display_pyramid (bool) – Whether display-pyramid preparation is enabled.

  • visualization (bool) – Whether visualization is enabled.

  • render_movie (bool) – Whether movie rendering is enabled.

  • compile_movie (bool) – Whether movie compilation is enabled.

  • volume_export (bool) – Whether volume export is enabled.

  • mip_export (bool) – Whether MIP export is enabled.

Returns:

Selected operations in canonical declaration order.

Return type:

tuple[str, …]

clearex.workflow.resolve_analysis_execution_sequence(*, flatfield, deconvolution, shear_transform, fusion, particle_detection, usegment3d, registration, display_pyramid, visualization, render_movie, compile_movie, volume_export, mip_export, analysis_parameters=None)

Resolve selected analyses into execution order.

Parameters:

  • flatfield (bool) – Whether flatfield correction is enabled.

  • deconvolution (bool) – Whether deconvolution is enabled.

  • shear_transform (bool) – Whether shear transform is enabled.

  • fusion (bool) – Whether fusion is enabled.

  • particle_detection (bool) – Whether particle detection is enabled.

  • usegment3d (bool) – Whether usegment3d segmentation is enabled.

  • registration (bool) – Whether registration is enabled.

  • display_pyramid (bool) – Whether display-pyramid preparation is enabled.

  • visualization (bool) – Whether visualization is enabled.

  • render_movie (bool) – Whether movie rendering is enabled.

  • compile_movie (bool) – Whether movie compilation is enabled.

  • volume_export (bool) – Whether volume export is enabled.

  • mip_export (bool) – Whether MIP export is enabled.

  • analysis_parameters (dict[str, dict[str, Any]], optional) – Candidate per-operation parameter mapping. The execution_order field in each selected operation controls ordering.

Returns:

Selected operation names sorted by execution_order and then by canonical declaration order as a stable tie-breaker.

Return type:

tuple[str, …]

clearex.workflow.parse_pyramid_levels(levels, *, axis_name)

Parse comma-separated pyramid factors for a single axis.

Parameters:

  • levels (str, optional) – Comma-separated factors such as "1,2,4,8".

  • axis_name (str) – Axis label used in validation messages.

Returns:

Parsed positive integer factors.

Return type:

tuple[int, …]

Raises:

ValueError – If input is missing, contains invalid integers, includes non-positive values, or does not start with 1.

clearex.workflow.format_pyramid_levels(levels)

Format pyramid factors for one axis.

Parameters:

levels (sequence of int) – Pyramid factors.

Returns:

Comma-separated factors.

Return type:

str

Raises:

ValueError – If factors are empty or invalid.

clearex.workflow.to_tpczyx_chunks(chunks_ptczyx)

Convert chunk sizes from (p, t, c, z, y, x) to (t, p, c, z, y, x).

Parameters:

chunks_ptczyx (sequence of int) – Chunk sizes in (p, t, c, z, y, x) order.

Returns:

Chunk sizes in (t, p, c, z, y, x) order.

Return type:

tuple[int, int, int, int, int, int]

Raises:

ValueError – If chunk values are invalid.

clearex.workflow.to_tpczyx_pyramid(pyramid_ptczyx)

Convert pyramid factors from (p, t, c, z, y, x) to (t, p, c, z, y, x).

Parameters:

pyramid_ptczyx (sequence of sequence of int) – Pyramid factors per axis in (p, t, c, z, y, x) order.

Returns:

Pyramid factors in (t, p, c, z, y, x) order.

Return type:

tuple[tuple[int, …], …]

Raises:

ValueError – If factors are invalid.

clearex.workflow.format_zarr_chunks_ptczyx(chunks_ptczyx)

Format chunk sizes for display in (p, t, c, z, y, x) order.

Parameters:

chunks_ptczyx (sequence of int) – Chunk sizes in (p, t, c, z, y, x) order.

Returns:

Formatted axis/value pairs such as "p=1, t=1, c=1, z=256, y=256, x=256".

Return type:

str

Raises:

ValueError – If chunk values are invalid.

clearex.workflow.format_zarr_pyramid_ptczyx(pyramid_ptczyx)

Format pyramid factors for display in (p, t, c, z, y, x) order.

Parameters:

pyramid_ptczyx (sequence of sequence of int) – Pyramid factors per axis in (p, t, c, z, y, x) order.

Returns:

Formatted axis/value list such as "p=1; t=1; c=1; z=1,2,4,8; y=1,2,4,8; x=1,2,4,8".

Return type:

str

Raises:

ValueError – If pyramid values are invalid.

class clearex.workflow.ZarrSaveConfig(chunks_ptczyx=(1, 1, 1, 256, 256, 256), pyramid_ptczyx=((1,), (1,), (1,), (1, 2, 4, 8), (1, 2, 4, 8), (1, 2, 4, 8)))

Bases: object

Configuration for analysis-store chunking and pyramid downsampling.

Variables:

  • chunks_ptczyx (tuple[int, int, int, int, int, int]) – Chunk sizes in (p, t, c, z, y, x) order.

  • pyramid_ptczyx (tuple[tuple[int, ...], ...]) – Per-axis pyramid factors in (p, t, c, z, y, x) order.

Parameters:

  • chunks_ptczyx (Tuple[int, int, int, int, int, int]) –

  • pyramid_ptczyx (Tuple[Tuple[int, ...], Tuple[int, ...], Tuple[int, ...], Tuple[int, ...], Tuple[int, ...], Tuple[int, ...]]) –

chunks_ptczyx: Tuple[int, int, int, int, int, int] = (1, 1, 1, 256, 256, 256)
pyramid_ptczyx: Tuple[Tuple[int, ...], Tuple[int, ...], Tuple[int, ...], Tuple[int, ...], Tuple[int, ...], Tuple[int, ...]] = ((1,), (1,), (1,), (1, 2, 4, 8), (1, 2, 4, 8), (1, 2, 4, 8))
chunks_tpczyx()

Return chunk sizes in canonical (t, p, c, z, y, x) order.

Parameters:

None –

Returns:

Chunk sizes in canonical axis order.

Return type:

tuple[int, int, int, int, int, int]

pyramid_tpczyx()

Return pyramid factors in canonical (t, p, c, z, y, x) order.

Parameters:

None –

Returns:

Pyramid factors in canonical axis order.

Return type:

tuple[tuple[int, …], …]

clearex.workflow.zarr_save_to_dict(config)

Serialize a Zarr save configuration to a JSON-safe mapping.

Parameters:

config (ZarrSaveConfig) – Zarr save configuration to serialize.

Returns:

JSON-safe mapping containing chunk and pyramid settings in (p, t, c, z, y, x) order.

Return type:

dict[str, Any]

clearex.workflow.zarr_save_from_dict(payload)

Deserialize a Zarr save configuration from a mapping payload.

Parameters:

payload (Any) – Mapping payload produced by zarr_save_to_dict().

Returns:

Parsed Zarr save configuration.

Return type:

ZarrSaveConfig

Raises:

ValueError – If the payload is not a mapping containing valid Zarr save settings.

class clearex.workflow.LocalClusterConfig(n_workers=None, threads_per_worker=1, memory_limit='auto', local_directory=None)

Bases: object

Runtime options for local Dask distributed execution.

Variables:

  • n_workers (int, optional) – Number of local workers. None defers to Dask defaults.

  • threads_per_worker (int) – Number of threads per worker process.

  • memory_limit (str) – Per-worker memory limit.

  • local_directory (str, optional) – Optional local spill/scratch directory.

Parameters:

  • n_workers (Optional[int]) –

  • threads_per_worker (int) –

  • memory_limit (str) –

  • local_directory (Optional[str]) –

n_workers: Optional[int] = None
threads_per_worker: int = 1
memory_limit: str = 'auto'
local_directory: Optional[str] = None
class clearex.workflow.SlurmRunnerConfig(scheduler_file=None, wait_for_workers=None)

Bases: object

Runtime options for connecting through dask_jobqueue.SLURMRunner.

Variables:

  • scheduler_file (str, optional) – Scheduler file path used by SLURMRunner.

  • wait_for_workers (int, optional) – Explicit worker count to await after client connection. None uses runner defaults.

Parameters:

  • scheduler_file (Optional[str]) –

  • wait_for_workers (Optional[int]) –

scheduler_file: Optional[str] = None
wait_for_workers: Optional[int] = None
class clearex.workflow.SlurmClusterConfig(workers=1, cores=28, processes=1, memory='220GB', local_directory=None, interface='ib0', walltime='01:00:00', job_name='clearex', queue='256GB', death_timeout='600s', mail_user=None, job_extra_directives=('--nodes=1', '--ntasks=1', '--mail-type=FAIL', '-o job_%j.out', '-e job_%j.err'), dashboard_address=':9000', scheduler_interface='ib0', idle_timeout='3600s', allowed_failures=10)

Bases: object

Runtime options for launching a Dask SLURMCluster.

Variables:

  • workers (int) – Number of worker jobs to request.

  • cores (int) – Worker cores/threads setting.

  • processes (int) – Number of Python processes per job.

  • memory (str) – Worker memory request (for example "220GB").

  • local_directory (str, optional) – Worker local spill/scratch directory.

  • interface (str) – Network interface for worker communications.

  • walltime (str) – Walltime in Slurm format (for example "01:00:00").

  • job_name (str) – Slurm job name.

  • queue (str) – Slurm partition/queue.

  • death_timeout (str) – Worker death timeout text (for example "600s").

  • mail_user (str, optional) – Email recipient for Slurm notifications.

  • job_extra_directives (tuple[str, ...]) – Additional Slurm directives passed through job_extra_directives.

  • dashboard_address (str) – Dashboard bind address for scheduler options.

  • scheduler_interface (str) – Network interface for scheduler options.

  • idle_timeout (str) – Scheduler idle timeout (for example "3600s").

  • allowed_failures (int) – Scheduler allowed worker failures before shutdown.

Parameters:

  • workers (int) –

  • cores (int) –

  • processes (int) –

  • memory (str) –

  • local_directory (Optional[str]) –

  • interface (str) –

  • walltime (str) –

  • job_name (str) –

  • queue (str) –

  • death_timeout (str) –

  • mail_user (Optional[str]) –

  • job_extra_directives (Tuple[str, ...]) –

  • dashboard_address (str) –

  • scheduler_interface (str) –

  • idle_timeout (str) –

  • allowed_failures (int) –

workers: int = 1
cores: int = 28
processes: int = 1
memory: str = '220GB'
local_directory: Optional[str] = None
interface: str = 'ib0'
walltime: str = '01:00:00'
job_name: str = 'clearex'
queue: str = '256GB'
death_timeout: str = '600s'
mail_user: Optional[str] = None
job_extra_directives: Tuple[str, ...] = ('--nodes=1', '--ntasks=1', '--mail-type=FAIL', '-o job_%j.out', '-e job_%j.err')
dashboard_address: str = ':9000'
scheduler_interface: str = 'ib0'
idle_timeout: str = '3600s'
allowed_failures: int = 10
class clearex.workflow.DaskBackendConfig(mode='local_cluster', local_cluster=<factory>, slurm_runner=<factory>, slurm_cluster=<factory>)

Bases: object

Shared Dask backend configuration for GUI and headless execution.

Variables:

  • mode ({"local_cluster", "slurm_runner", "slurm_cluster"}) – Selected Dask backend mode.

  • local_cluster (LocalClusterConfig) – Settings for local distributed execution.

  • slurm_runner (SlurmRunnerConfig) – Settings for scheduler-file-based SLURM runner execution.

  • slurm_cluster (SlurmClusterConfig) – Settings for launching worker jobs with SLURMCluster.

Parameters:
mode: Literal['local_cluster', 'slurm_runner', 'slurm_cluster'] = 'local_cluster'
local_cluster: LocalClusterConfig
slurm_runner: SlurmRunnerConfig
slurm_cluster: SlurmClusterConfig
class clearex.workflow.LocalClusterRecommendation(config, detected_cpu_count, detected_memory_bytes, detected_gpu_count, detected_gpu_memory_bytes, estimated_chunk_bytes, estimated_dataset_bytes, estimated_chunk_count)

Bases: object

Recommended LocalCluster settings derived from host and data context.

Variables:

  • config (LocalClusterConfig) – Recommended LocalCluster configuration.

  • detected_cpu_count (int) – Effective CPU count detected for the current process.

  • detected_memory_bytes (int) – Effective memory budget detected for the current process.

  • detected_gpu_count (int) – Number of locally visible GPUs.

  • detected_gpu_memory_bytes (int, optional) – Aggregate GPU memory in bytes when detectable.

  • estimated_chunk_bytes (int) – Estimated bytes per canonical chunk using the configured save chunks.

  • estimated_dataset_bytes (int, optional) – Estimated canonical dataset size in bytes when shape metadata is known.

  • estimated_chunk_count (int, optional) – Estimated number of canonical chunks when shape metadata is known.

Parameters:

  • config (LocalClusterConfig) –

  • detected_cpu_count (int) –

  • detected_memory_bytes (int) –

  • detected_gpu_count (int) –

  • detected_gpu_memory_bytes (Optional[int]) –

  • estimated_chunk_bytes (int) –

  • estimated_dataset_bytes (Optional[int]) –

  • estimated_chunk_count (Optional[int]) –

config: LocalClusterConfig
detected_cpu_count: int
detected_memory_bytes: int
detected_gpu_count: int
detected_gpu_memory_bytes: Optional[int]
estimated_chunk_bytes: int
estimated_dataset_bytes: Optional[int]
estimated_chunk_count: Optional[int]
clearex.workflow.recommend_local_cluster_config(*, shape_tpczyx=None, chunks_tpczyx=None, dtype_itemsize=None, cpu_count=None, memory_bytes=None, gpu_count=None, gpu_memory_bytes=None)

Recommend aggressive LocalCluster settings from host/data characteristics.

Parameters:

  • shape_tpczyx (tuple[int, int, int, int, int, int], optional) – Canonical dataset shape in (t, p, c, z, y, x) order.

  • chunks_tpczyx (tuple[int, int, int, int, int, int], optional) – Canonical chunk shape in (t, p, c, z, y, x) order.

  • dtype_itemsize (int, optional) – Bytes per voxel. Defaults to 2 when unknown.

  • cpu_count (int, optional) – Explicit effective CPU count for deterministic testing.

  • memory_bytes (int, optional) – Explicit effective memory budget in bytes for deterministic testing.

  • gpu_count (int, optional) – Explicit GPU count for deterministic testing.

  • gpu_memory_bytes (int, optional) – Explicit aggregate GPU memory in bytes for deterministic testing.

Returns:

Recommended LocalCluster configuration plus sizing diagnostics.

Return type:

LocalClusterRecommendation

Notes

Recommendations are intentionally aggressive by default: they target high CPU utilization while respecting chunk-memory pressure and available RAM. GPU presence is incorporated as additional diagnostic context and can raise target worker counts when resources permit.

clearex.workflow.format_local_cluster_recommendation_summary(recommendation)

Format a human-readable summary of local-cluster recommendations.

Parameters:

recommendation (LocalClusterRecommendation) – Recommendation payload to summarize.

Returns:

Concise operator-facing summary string.

Return type:

str

clearex.workflow.dask_backend_to_dict(config)

Serialize Dask backend config into JSON-friendly mappings.

Parameters:

config (DaskBackendConfig) – Backend configuration to serialize.

Returns:

JSON-serializable backend mapping.

Return type:

dict[str, Any]

clearex.workflow.dask_backend_from_dict(payload)

Deserialize a backend mapping into DaskBackendConfig.

Parameters:

payload (Any) – JSON-like mapping, typically produced by dask_backend_to_dict().

Returns:

Parsed backend configuration. Invalid or partial payloads fall back to default values for affected sections.

Return type:

DaskBackendConfig

Notes

This parser is intentionally tolerant for user-level persisted settings. Unknown keys are ignored and malformed subsections are replaced with defaults so GUI startup can always proceed.

clearex.workflow.format_dask_backend_summary(config)

Format a compact summary of the selected Dask backend.

Parameters:

config (DaskBackendConfig) – Backend configuration.

Returns:

Human-readable one-line summary.

Return type:

str

class clearex.workflow.SpatialCalibrationConfig(stage_axis_map_zyx=('+z', '+y', '+x'), theta_mode='rotate_zy_about_x')

Bases: object

Store-level stage-to-world axis mapping for multiposition placement.

Variables:

  • stage_axis_map_zyx (tuple[str, str, str]) – World-axis bindings in (z, y, x) order. Allowed values are +x, -x, +y, -y, +z, -z, +f, -f, and none.

  • theta_mode (str) – Rotation interpretation for Navigate THETA values.

Parameters:

  • stage_axis_map_zyx (tuple[str, str, str]) –

  • theta_mode (str) –

stage_axis_map_zyx: tuple[str, str, str] = ('+z', '+y', '+x')
theta_mode: str = 'rotate_zy_about_x'
stage_axis_map_by_world_axis()

Return the world-axis binding mapping.

Parameters:

None –

Returns:

Mapping of world z/y/x axes to canonical binding strings.

Return type:

dict[str, str]

clearex.workflow.parse_spatial_calibration(mapping)

Parse CLI/GUI text into a spatial calibration configuration.

Parameters:

mapping (str, optional) – Canonical text form such as "z=+x,y=none,x=+y".

Returns:

Parsed and validated calibration. Empty input resolves to identity.

Return type:

SpatialCalibrationConfig

Raises:

ValueError – If the text is malformed or reuses a non-none stage axis.

clearex.workflow.normalize_spatial_calibration(value)

Normalize flexible spatial-calibration payloads.

Parameters:

value (Any) – Candidate calibration payload. Accepts SpatialCalibrationConfig, canonical text, or metadata mappings.

Returns:

Normalized calibration configuration.

Return type:

SpatialCalibrationConfig

Raises:

ValueError – If the payload cannot be interpreted as a valid calibration.

clearex.workflow.spatial_calibration_to_dict(config)

Serialize spatial calibration for Zarr attrs and provenance.

Parameters:

config (SpatialCalibrationConfig) – Calibration to serialize.

Returns:

JSON-compatible payload with schema, bindings, and theta mode.

Return type:

dict[str, Any]

clearex.workflow.spatial_calibration_from_dict(payload)

Deserialize spatial calibration from metadata payloads.

Parameters:

payload (Any) – Stored calibration payload. Missing values resolve to identity.

Returns:

Parsed calibration configuration.

Return type:

SpatialCalibrationConfig

clearex.workflow.format_spatial_calibration(config)

Format a spatial calibration in canonical text form.

Parameters:

config (Any) – Calibration payload accepted by normalize_spatial_calibration().

Returns:

Canonical text form z=...,y=...,x=....

Return type:

str

class clearex.workflow.AnalysisTarget(experiment_path, store_path)

Bases: object

Resolved experiment/store pair available to the analysis dialog.

Variables:

  • experiment_path (str) – Navigate experiment.yml path shown to operators in batch/single analysis scope controls.

  • store_path (str) – Canonical analysis-store path used when executing this target.

Parameters:

  • experiment_path (str) –

  • store_path (str) –

experiment_path: str
store_path: str
clearex.workflow.normalize_analysis_targets(targets)

Normalize workflow analysis targets.

Parameters:

targets (sequence[AnalysisTarget or mapping], optional) – Candidate analysis targets. Mapping entries must provide experiment_path and store_path keys.

Returns:

Normalized targets in first-seen order. Duplicate experiment paths are collapsed to one entry.

Return type:

tuple[AnalysisTarget, …]

Raises:

ValueError – If a target is malformed or missing required paths.

class clearex.workflow.WorkflowConfig(file=None, analysis_targets=<factory>, analysis_selected_experiment_path=None, analysis_apply_to_all=False, prefer_dask=True, dask_backend=<factory>, chunks=None, flatfield=False, deconvolution=False, shear_transform=False, particle_detection=False, usegment3d=False, registration=False, fusion=False, display_pyramid=False, visualization=False, render_movie=False, compile_movie=False, volume_export=False, mip_export=False, zarr_save=<factory>, spatial_calibration=<factory>, spatial_calibration_explicit=False, analysis_parameters=<factory>)

Bases: object

Runtime workflow options shared by GUI and headless entrypoints.

Variables:

  • file (str, optional) – Input image path for processing.

  • analysis_targets (tuple[AnalysisTarget, ...]) – Ordered experiment/store pairs available for single-experiment or batch analysis selection in the GUI.

  • analysis_selected_experiment_path (str, optional) – Currently selected Navigate experiment.yml path within analysis_targets.

  • analysis_apply_to_all (bool) – Whether analysis should run across every entry in analysis_targets instead of only the selected one.

  • prefer_dask (bool) – Whether to open data using lazy Dask-backed arrays when supported.

  • dask_backend (DaskBackendConfig) – Backend orchestration mode and runtime settings for Dask execution.

  • chunks (int or tuple of int, optional) – Chunking configuration used for Dask reads.

  • flatfield (bool) – Flag indicating whether flatfield-correction workflow should run.

  • deconvolution (bool) – Flag indicating whether deconvolution workflow should run.

  • shear_transform (bool) – Flag indicating whether shear-transform workflow should run.

  • particle_detection (bool) – Flag indicating whether particle detection workflow should run.

  • usegment3d (bool) – Flag indicating whether usegment3d workflow should run.

  • registration (bool) – Flag indicating whether registration workflow should run.

  • fusion (bool) – Flag indicating whether fusion workflow should run.

  • display_pyramid (bool) – Flag indicating whether display-pyramid preparation should run.

  • visualization (bool) – Flag indicating whether visualization workflow should run.

  • render_movie (bool) – Flag indicating whether movie-render workflow should run.

  • compile_movie (bool) – Flag indicating whether movie-compile workflow should run.

  • volume_export (bool) – Flag indicating whether volume-export workflow should run.

  • mip_export (bool) – Flag indicating whether MIP-export workflow should run.

  • zarr_save (ZarrSaveConfig) – Analysis-store chunking and pyramid configuration for saved Zarr data.

  • spatial_calibration (SpatialCalibrationConfig) – Store-level Navigate stage-to-world axis mapping used for multiposition placement metadata.

  • spatial_calibration_explicit (bool) – Whether the current spatial calibration was explicitly supplied by the operator rather than inherited as the identity default.

  • analysis_parameters (dict[str, dict[str, Any]]) – Per-analysis runtime parameters keyed by analysis name.

Parameters:

  • file (Optional[str]) –

  • analysis_targets (tuple[clearex.workflow.AnalysisTarget, ...]) –

  • analysis_selected_experiment_path (Optional[str]) –

  • analysis_apply_to_all (bool) –

  • prefer_dask (bool) –

  • dask_backend (DaskBackendConfig) –

  • chunks (Optional[Union[int, Tuple[int, ...]]]) –

  • flatfield (bool) –

  • deconvolution (bool) –

  • shear_transform (bool) –

  • particle_detection (bool) –

  • usegment3d (bool) –

  • registration (bool) –

  • fusion (bool) –

  • display_pyramid (bool) –

  • visualization (bool) –

  • render_movie (bool) –

  • compile_movie (bool) –

  • volume_export (bool) –

  • mip_export (bool) –

  • zarr_save (ZarrSaveConfig) –

  • spatial_calibration (SpatialCalibrationConfig) –

  • spatial_calibration_explicit (bool) –

  • analysis_parameters (Dict[str, Dict[str, Any]]) –

file: Optional[str] = None
analysis_targets: tuple[clearex.workflow.AnalysisTarget, ...]
analysis_selected_experiment_path: Optional[str] = None
analysis_apply_to_all: bool = False
prefer_dask: bool = True
dask_backend: DaskBackendConfig
chunks: Optional[Union[int, Tuple[int, ...]]] = None
flatfield: bool = False
deconvolution: bool = False
shear_transform: bool = False
particle_detection: bool = False
usegment3d: bool = False
registration: bool = False
fusion: bool = False
display_pyramid: bool = False
visualization: bool = False
render_movie: bool = False
compile_movie: bool = False
volume_export: bool = False
mip_export: bool = False
zarr_save: ZarrSaveConfig
spatial_calibration: SpatialCalibrationConfig
spatial_calibration_explicit: bool = False
analysis_parameters: Dict[str, Dict[str, Any]]
has_analysis_selection()

Return whether at least one analysis operation is selected.

Returns:

True if any analysis flag is enabled, otherwise False.

Return type:

bool

selected_analysis_target()

Return the currently selected analysis target, when configured.

Returns:

Selected target resolved from analysis_targets and analysis_selected_experiment_path.

Return type:

AnalysisTarget, optional

clearex.workflow.parse_chunks(chunks)

Parse chunk spec from CLI/GUI text.

Parameters:

chunks (str, optional) – A single integer (e.g., "256") or comma-separated tuple (e.g., "1,256,256"). Empty strings are treated as None.

Returns:

Parsed chunk specification or None.

Return type:

Optional[int | Tuple[int, …]]

Raises:

ValueError – If chunks cannot be parsed as integers or contains non-positive values.

clearex.workflow.format_chunks(chunks)

Format a chunk specification for display.

Parameters:

chunks (int or tuple of int, optional) – Chunk specification to serialize.

Returns:

Empty string when chunks is None. Otherwise returns a single integer or comma-separated integer list.

Return type:

str