exceptions

Custom exceptions for ClearMap.

Every exception carries presentation metadata so the GUI can display user-friendly dialogs with actionable recovery options.

Hierarchy (indentation = inheritance)

ClearMapException ├── ClearMapValueError (also ValueError) │ └── ParamsOrientationError ├── ClearMapRuntimeError (also RuntimeError) ├── ClearMapIoException (also IOError) │ ├── SourceModuleNotFoundError │ ├── IncompatibleSource │ ├── MetadataError │ │ └── NotAnOmeFile │ └── NrrdError ├── ClearMapWorkspaceError │ ├── ClearMapAssetError │ │ └── AssetNotFoundError (also FileNotFoundError, via MissingRequirementException) │ ├── MissingChannelError │ └── MissingAssetError (also KeyError, via MissingRequirementException) ├── MissingRequirementException ├── ClearMapConfigError │ ├── ConfigNotFoundError │ ├── ConfigParsingError │ ├── AggregatedValidationError │ └── PatchConflictError ├── PlotGraphError ├── ClearMapVRamException ├── SmiError └── GroupStatsError

exception AggregatedValidationError(messages: Iterable[str])

Bases: ClearMapConfigError

Multiple validation errors collected during a single schema or semantic check pass. messages holds one human-readable string per individual violation.

severity: Severity = 'fatal'

user_hint: str = 'Fix the errors listed below, then save again.'

property user_message: str

What goes into the dialog body. Override for richer messages.

user_title: str = 'Validation Errors'

exception AssetNotFoundError(message: str, asset_path: str = '', asset_type: str = '', asset_sub_type: str = '', missing_step_name: str = '', required_by: str = '', workspace_path: str = '')

Bases: MissingRequirementException, ClearMapAssetError, FileNotFoundError

The file backing a declared workspace asset (or its compressed variant) does not exist on disk.

Unlike MissingAssetError (lookup failure), this means the workspace does reference the asset but the expected path is absent — typically because results were moved, deleted or never written.

severity: Severity = 'recoverable'

property user_message: str

What goes into the dialog body. Override for richer messages.

user_title: str = 'Asset File Not Found'

exception ClearMapAssetError

Bases: ClearMapWorkspaceError

Raised when an Asset object is internally inconsistent. Typically caused by invalid TypeSpec or ChannelSpec definitions, or unresolved tags in a tiled file Expression (e.g., forbidden <S> tags before parametrization).

user_title: str = 'Asset Error'

exception ClearMapConfigError

Bases: ClearMapException

A configuration file is invalid, missing, or internally inconsistent.

user_hint: str = 'Check the configuration files for errors.'

user_title: str = 'Configuration Error'

exception ClearMapException

Bases: Exception

Base for every ClearMap-specific exception.

Class attributes

severitySeverity

How the GUI should present this error.

user_titlestr

Short, user-facing heading shown in the dialog title bar.

user_hintstr

Actionable advice shown below the error message.

Properties

user_messagestr

Derived from str(self); subclasses may enrich it with structured fields (asset name, channel, etc.).

recovery_optionstuple[RecoveryOption, …]

Buttons offered to the user. Defaults come from DEFAULT_RECOVERY_OPTIONS[self.severity] but can be overridden per-class or per-instance.

property recovery_options: tuple[RecoveryOption, ...]

severity: Severity = 'fatal'

user_hint: str = ''

property user_message: str

What goes into the dialog body. Override for richer messages.

user_title: str = 'ClearMap Error'

exception ClearMapFileNotFoundError

Bases: ClearMapIoException, FileNotFoundError

Raised when a required file is not found on disk.

severity: Severity = 'fatal'

user_title: str = 'File Not Found'

exception ClearMapIoException

Bases: ClearMapException, OSError

Base exception for failures within the ClearMap.IO dispatcher when reading, writing, or initializing Source objects.

user_title: str = 'I/O Error'

exception ClearMapPermissionError

Bases: ClearMapIoException, PermissionError

Raised when there are insufficient permissions to read/write a file.

severity: Severity = 'fatal'

user_hint: str = 'Check file permissions or ensure the file is not opened in another program.'

user_title: str = 'Permission Denied'

exception ClearMapRuntimeError(message: str, command: str = '')

Bases: ClearMapException, RuntimeError

An operation failed at runtime (external tool crashed, unexpected state, etc.).

If triggered by a shell command, command holds the command line for diagnostics.

severity: Severity = 'fatal'

user_hint: str = 'Check the log files for more details.'

property user_message: str

What goes into the dialog body. Override for richer messages.

user_title: str = 'Runtime Error'

exception ClearMapVRamException

Bases: ClearMapException

Not enough free GPU memory to launch a CUDA/OpenCL kernel.

The user can free VRAM by closing other applications or reducing block sizes, then retry.

property recovery_options: tuple[RecoveryOption, ...]

severity: Severity = 'recoverable'

user_hint: str = 'Close other GPU applications, reduce the batch/block size, or switch to CPU processing if available.'

user_title: str = 'Insufficient GPU Memory'

exception ClearMapValueError(message: str, value=None, expected=None)

Bases: ClearMapException, ValueError

A parameter, argument or computed quantity is outside its valid domain.

Carries the offending value and optionally what was expected so the dialog can show both to the user.

severity: Severity = 'fatal'

user_hint: str = 'Check your parameters and try again.'

property user_message: str

What goes into the dialog body. Override for richer messages.

user_title: str = 'Invalid Value'

exception ClearMapWorkspaceError

Bases: ClearMapException

Raised when the Workspace2 instance detects an invalid state, such as a malformed folder layout (resource_type_to_folder), unregistered pipelines, or failed directory migrations.

property recovery_options: tuple[RecoveryOption, ...]

user_hint: str = 'If this persists, try "Reset Workspace" from the Workspace menu to rebuild from configuration files.'

user_title: str = 'Workspace Error'

exception ConfigNotFoundError

Bases: ClearMapConfigError

The expected .cfg / .yml file does not exist at the resolved path.

This usually means the experiment folder was never initialised or the file was manually deleted.

user_title: str = 'Configuration File Not Found'

exception ConfigParsingError

Bases: ClearMapConfigError

A configuration file exists but cannot be deserialised (malformed YAML, unknown anchors, encoding issues, etc.).

user_hint: str = 'The configuration file contains invalid syntax or values.'

user_title: str = 'Configuration Parsing Error'

exception GroupStatsError

Bases: ClearMapException

Group-level statistical analysis failed — typically because density maps across samples have mismatched shapes, duplicate sample IDs, or empty groups.

user_hint: str = 'Ensure all samples in each group have matching density maps with identical dimensions.'

user_title: str = 'Group Statistics Error'

exception IncompatibleSource(source, variable_name, current_vars)

Bases: ClearMapIoException

Two data sources that should be combinable differ in a critical property.

Typically raised when trying to stack or overlay images whose shapes, dtypes or coordinate systems do not match.

severity: Severity = 'fatal'

user_title: str = 'Incompatible Data Source'

exception MetadataError(message: str, img_path: str = '')

Bases: ClearMapIoException

Image metadata (resolution, channel count, etc.) could not be extracted.

Usually means the file header is truncated, the format is unsupported, or the file is simply not an image.

severity: Severity = 'fatal'

user_hint: str = 'The image metadata could not be read. Is the file valid?'

property user_message: str

What goes into the dialog body. Override for richer messages.

user_title: str = 'Metadata Error'

exception MissingAssetError(message: str, asset_type: str = '', channel: str = '', asset_sub_type: str = '', missing_step_name: str = '', required_by: str = '', workspace_path: str = '')

Bases: MissingRequirementException, ClearMapWorkspaceError, KeyError

Raised during workspace lookups when the requested asset type (e.g. ‘stitched’, ‘cells’) is not configured in the AssetCollection for the specified channel.

This represents a logical missing definition in the workspace layout, not a missing physical file.

severity: Severity = 'recoverable'

property user_hint: str

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

property user_message: str

What goes into the dialog body. Override for richer messages.

user_title: str = 'Missing Asset Definition'

exception MissingChannelError

Bases: ClearMapWorkspaceError

Raised when a pipeline or workspace query targets a channel ID that has not been added to the workspace’s AssetCollection.

severity: Severity = 'recoverable'

user_hint: str = 'Add the channel in the Sample Info tab, then retry.'

user_title: str = 'Missing Channel'

exception MissingRequirementException(message: str = '', missing_step_name: str = '', required_by: str = '', context_message: str = '', missing_items: Iterable[str] = (), found_items: Iterable[str] = ())

Bases: ClearMapException

Exception raised when a processing step is missing a required condition (i.e. another step has not been run yet)

severity: Severity = 'recoverable'

property user_hint: str

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

property user_message: str

What goes into the dialog body. Override for richer messages.

user_title: str = 'Missing Prerequisite'

exception NotAnOmeFile(message: str, img_path: str = '')

Bases: MetadataError

A file expected to be OME-TIFF lacks the required OME-XML header.

The file may be a plain TIFF, a BigTIFF or a completely different format. Recoverable because the caller can often fall back to non-OME parsing.

severity: Severity = 'recoverable'

user_hint: str = 'Use a valid OME-TIFF file, or select a different format.'

user_title: str = 'Not an OME-TIFF File'

exception NrrdError(message: str, field: str = '', encoding: str = '')

Bases: ClearMapIoException

An NRRD file could not be parsed — missing header fields, unknown encoding, version mismatch or truncated data.

severity: Severity = 'fatal'

user_hint: str = 'The NRRD file appears to be corrupted or unsupported.'

user_title: str = 'NRRD File Error'

exception ParamsOrientationError(message: str, channel: str = '')

Bases: ClearMapValueError

The user-supplied sample orientation axes are invalid.

A valid orientation is a permutation of (±1, ±2, ±3) with no repeated absolute values. This error is recoverable because the user simply needs to correct the spinboxes.

severity: Severity = 'recoverable'

user_hint: str = 'Each axis must be one of ±1, ±2, ±3 with no duplicates.'

property user_message: str

What goes into the dialog body. Override for richer messages.

user_title: str = 'Invalid Orientation'

exception PatchConflictError(path: Tuple[str, ...], src_value: object, dst_value: object, reason: str)

Bases: ClearMapConfigError

Two concurrent or sequential config patches target the same key with incompatible intentions (e.g. one deletes a subtree while another updates a value inside it).

Marked CRITICAL because the in-memory config may already be partially applied and the on-disk state could be out of sync.

severity: Severity = 'critical'

user_hint: str = 'The workspace may be in an inconsistent state.\nIt is recommended to reset the workspace and reload.'

user_title: str = 'Configuration Conflict'

exception PlotGraphError

Bases: ClearMapException

The requested graph visualisation cannot be rendered, usually because the vertex/edge count exceeds safe memory limits for the 3-D viewer.

severity: Severity = 'recoverable'

user_hint: str = 'Reduce the data subset or apply stricter filters.'

user_title: str = 'Cannot Display Graph'

exception SmiError

Bases: ClearMapException

nvidia-smi returned an error or could not be executed.

GPU monitoring is non-essential, so the session can continue in degraded mode without hardware stats.

severity: Severity = 'degraded'

user_hint: str = 'nvidia-smi could not be reached. GPU monitoring will be disabled for this session.'

user_title: str = 'GPU Query Failed'

exception SourceModuleNotFoundError(filename: str = '', ext: str = '')

Bases: ClearMapIoException

No reader module is registered for the given file extension.

Raised by the I/O dispatcher when a file’s extension (e.g. .xyz) does not map to any registered backend module (like TIF, NRRD, NPY, etc.).

severity: Severity = 'fatal'

user_hint: str = 'The file extension is not recognised. Check the file path.'

user_title: str = 'Unsupported File Format'

class RecoveryOption(label: str, action: str, tooltip: str = '', is_default: bool = False, is_destructive: bool = False)

Bases: object

One button the user can click in the exception dialog.

action: str

is_default: bool = False

is_destructive: bool = False

label: str

tooltip: str = ''

class Severity(value)

Bases: Enum

How badly the error affects the current session.

The GUI dialog adapts its appearance and available actions accordingly:

RECOVERABLE

Retry or skip possible; no data is at risk.

DEGRADED

Processing can continue with reduced functionality.

FATAL

The current operation must stop, but the workspace is intact.

CRITICAL

The workspace / experiment may be corrupt; suggest reset.

CRITICAL = 'critical'

DEGRADED = 'degraded'

FATAL = 'fatal'

RECOVERABLE = 'recoverable'

get_caller_name(skip_patterns: tuple[str, ...] = ('wrapper', '_decorator', 'decorator', '__')) → str

Walk up the call stack and return the first meaningful caller name. Skips frames whose co_name contains any of skip_patterns (typically wrappers, decorators and dunder methods). Returns '<unknown>' when no suitable frame is found.