Skip to content

Configuration

omero_annotate_ai.core.annotation_config.load_config_from_yaml

load_config_from_yaml(yaml_path: str) -> AnnotationConfig

Load AnnotationConfig from a YAML file.

Convenience function for loading configuration from YAML files.

Parameters:

Name Type Description Default
yaml_path str

Path to YAML configuration file

required

Returns:

Type Description
AnnotationConfig

AnnotationConfig object

omero_annotate_ai.core.annotation_config.load_config

load_config(config_source: str | Path | dict[str, Any]) -> AnnotationConfig

Load configuration from various sources.

omero_annotate_ai.core.annotation_config.create_default_config

create_default_config() -> AnnotationConfig

Create a default configuration.

omero_annotate_ai.core.annotation_config.get_config_template

get_config_template() -> str

Get a YAML template with comments for all configuration options.

omero_annotate_ai.core.annotation_config.AnnotationConfig pydantic-model

Bases: BaseModel

A training set's definition: what to annotate, how, and its history.

The rows (one per annotation unit) are not part of the config; they live in the set's tracking_table.csv and OMERO tracking table.

Config:

  • extra: forbid
  • validate_assignment: True

Fields:

Validators:

  • _reject_removed_keys
  • _check_sources

schema_version pydantic-field

schema_version: int = SCHEMA_VERSION

Configuration schema version

name pydantic-field

name: str

Annotation workflow name

authors pydantic-field

authors: list[AuthorInfo]

Workflow authors

created pydantic-field

created: datetime

Creation timestamp

source pydantic-field

source: Literal['omero', 'zarr'] = 'omero'

Where images come from

storage pydantic-field

storage: Literal['omero', 'local'] = 'omero'

Where rows and masks are kept: an OMERO tracking table with uploads ('omero'), or only the set's local folder ('local'). Fixed when the set is created; OME-Zarr sets are always local.

sessions pydantic-field

sessions: list[SessionRecord]

Annotation sessions, oldest first

documentation pydantic-field

documentation: HttpUrl | None = None

Documentation URL

repository pydantic-field

repository: HttpUrl | None = None

Code repository URL

tags pydantic-field

tags: list[str]

Classification tags

feature_types pydantic-field

feature_types: list[FeatureType]

Annotation classes (e.g. cell, nucleus) with display colors

notes pydantic-field

notes: str | None = None

Free-text notes about the annotation set (context, caveats, known issues)

custom_metadata pydantic-field

custom_metadata: dict[str, Any]

Additional key-value metadata not covered by the schema

to_dict

to_dict() -> dict[str, Any]

Convert configuration to dictionary.

to_yaml

to_yaml(sort_keys: bool = False) -> str

Convert configuration to a YAML string.

Parameters:

Name Type Description Default
sort_keys bool

When True, keys are sorted alphabetically. When False (default), keys are emitted in the schema-defined order from the Pydantic model.

False

Returns:

Type Description
str

YAML string representation of the configuration.

save_yaml

save_yaml(file_path: str | Path, *, sort_keys: bool = False) -> None

Save configuration to YAML file and remember the path.

from_dict classmethod

from_dict(config_dict: dict[str, Any]) -> AnnotationConfig

Create configuration from dictionary.

from_yaml classmethod

from_yaml(yaml_source: str | Path) -> AnnotationConfig

Create configuration from YAML string or file path.

to_json

to_json(**kwargs) -> str

Serialize to JSON string.

Uses the same dict representation as to_dict(), ensuring consistency with YAML serialization.

from_json classmethod

from_json(json_source: str | Path | dict) -> AnnotationConfig

Load from JSON string, file path, or dict.

Parameters:

Name Type Description Default
json_source str | Path | dict

JSON string, Path to .json file, or dict.

required

Returns:

Type Description
AnnotationConfig

Hydrated AnnotationConfig instance.

Sections

omero_annotate_ai.core.annotation_config.OMEROConfig pydantic-model

Bases: _Section

OMERO connection and data selection configuration

Fields:

container_type pydantic-field

container_type: str = 'dataset'

OMERO container type

container_id pydantic-field

container_id: int = 0

OMERO container ID (single container)

container_ids pydantic-field

container_ids: list[int] | None = None

List of OMERO container IDs of the same type. Takes precedence over container_id when set.

source_desc pydantic-field

source_desc: str = ''

Source description for tracking

well_filters pydantic-field

well_filters: dict[str, list[str]] | None = None

Filter wells by map annotation key-value pairs. Example: {'cellline': ['U2OS', 'HeLa'], 'treatment': ['Control']}. All conditions must be met (AND logic). Only applies when container_type='plate'.

well_filter_mode pydantic-field

well_filter_mode: Literal['include', 'exclude'] = 'include'

Whether to include or exclude wells matching the filters

get_all_container_ids

get_all_container_ids() -> list[int]

Get all container IDs, with container_ids taking precedence over container_id.

Returns:

Type Description
list[int]

List of container IDs. Returns container_ids if set and non-empty,

list[int]

otherwise returns [container_id] if container_id is non-zero,

list[int]

otherwise returns empty list.

get_primary_container_id

get_primary_container_id() -> int

Get the primary (first) container ID.

Returns:

Type Description
int

The first container ID from the list, or 0 if no containers configured.

is_multi_container

is_multi_container() -> bool

Check if multiple containers are configured.

Returns:

Type Description
bool

True if more than one container ID is configured.

omero_annotate_ai.core.annotation_config.SpatialCoverage pydantic-model

Bases: _Section

Spatial scope of annotations (MIFA requirement)

Fields:

Validators:

channels pydantic-field

channels: list[int]

Channel indices processed

timepoints pydantic-field

timepoints: list[int]

Timepoints as list

n_timepoints pydantic-field

n_timepoints: int | None = None

Number of timepoints to randomly select (used when timepoint_mode='random'). If not specified, uses the length of timepoints list for backward compatibility.

z_slices pydantic-field

z_slices: list[int]

Z-slices as list

n_slices pydantic-field

n_slices: int | None = None

Number of z-slices to randomly select (used when z_slice_mode='random'). If not specified, uses the length of z_slices list for backward compatibility.

three_d pydantic-field

three_d: bool = False

3D volumetric processing mode

z_range_start pydantic-field

z_range_start: int | None = None

Starting z-slice for 3D volumes (when three_d=True)

z_range_end pydantic-field

z_range_end: int | None = None

Ending z-slice for 3D volumes (when three_d=True)

label_channel pydantic-field

label_channel: int | None = None

Channel index used for segmentation/labeling (e.g., fluorescence nuclei). If not specified, defaults to channels[0] for backward compatibility.

training_channels pydantic-field

training_channels: list[int] | None = None

Channel index(es) used for model training input (e.g., brightfield). If not specified, defaults to [label_channel] for backward compatibility. Multiple channels supported if the training model permits.

context_channels pydantic-field

context_channels: list[int]

Display-only channel indices shown alongside the annotation channel in napari. Never enter SAM embeddings or training data. OMERO channel index space.

context_channel_names pydantic-field

context_channel_names: list[str] | None = None

Display names for context_channels. Length must match context_channels when provided. Defaults to 'ch{idx}'.

context_channel_colormaps pydantic-field

context_channel_colormaps: list[str] | None = None

Napari colormap names for context_channels. Length must match context_channels when provided. Defaults to cycle ['blue', 'magenta', 'green', 'yellow', 'cyan'].

use_patches pydantic-field

use_patches: bool = False

Extract patches vs full images

patch_size pydantic-field

patch_size: list[int] = [512, 512]

Patch dimensions [width, height]

patches_per_image pydantic-field

patches_per_image: int = 1

Patches per image

random_patches pydantic-field

random_patches: bool = True

Use random patch extraction

primary_channel property

primary_channel: int

Get the primary/first channel

is_single_channel property

is_single_channel: bool

Check if only one channel is configured

get_label_channel

get_label_channel() -> int

Get the channel to use for labeling/segmentation.

Returns label_channel if explicitly set, otherwise falls back to primary_channel (channels[0]).

get_training_channels

get_training_channels() -> list[int]

Get the channel(s) to use for training input.

Returns training_channels if explicitly set, otherwise falls back to [get_label_channel()] for backward compatibility (same channel for both labeling and training).

uses_separate_channels

uses_separate_channels() -> bool

Check if separate channels are configured for labeling and training.

Returns True if label_channel differs from all training_channels.

uses_context_channels

uses_context_channels() -> bool

Return True if any context channels are configured.

get_context_channel_specs

get_context_channel_specs() -> list[tuple[int, str, str]]

Return [(channel_index, display_name, colormap), ...] for each context channel.

get_z_range

get_z_range() -> tuple[int, int]

Get the z-range for volumetric processing

get_z_length

get_z_length() -> int

Get the number of z-slices for volumetric processing

model_dump

model_dump(**kwargs)

Override model_dump to exclude patch fields when use_patches is False.

validate_3d_settings pydantic-validator

validate_3d_settings()

Validate 3D configuration consistency

validate_channel_settings pydantic-validator

validate_channel_settings()

Validate channel configuration consistency.

Ensures that label_channel and training_channels are valid indices that exist in the channels list.

omero_annotate_ai.core.annotation_config.TrainingConfig pydantic-model

Bases: _Section

Quality metrics and validation (MIFA requirement)

Fields:

Validators:

split_unit pydantic-field

split_unit: Literal['image', 'well'] = 'image'

Unit of the train/validation/test split: 'image' (a field with all its timepoints/z-slices) or 'well' (all fields of a plate well)

split_rationale pydantic-field

split_rationale: str | None = None

Why this split unit was chosen, e.g. 'fields within a well do not overlap'

stratify_by pydantic-field

stratify_by: list[str]

Well key-value pairs (e.g. ['cell_line', 'treatment']) or 'well' to split within: each combination is divided over the splits separately

train_fraction pydantic-field

train_fraction: float = 0.7

Fraction of data for training (used when segment_all=True)

validation_fraction pydantic-field

validation_fraction: float = 0.3

Fraction of data for validation (used when segment_all=True)

test_fraction pydantic-field

test_fraction: float = 0.0

Fraction of data for testing (used when segment_all=True)

train_n pydantic-field

train_n: int = 3

Number of training images (used when segment_all=False)

validate_n pydantic-field

validate_n: int = 2

Number of validation images (0=no validation)

test_n pydantic-field

test_n: int = 0

Number of test images (0=no test)

segment_all pydantic-field

segment_all: bool = False

Process all images vs subset

seed pydantic-field

seed: int | None = None

Seed for every random choice (split, timepoints, z-slices, patches, extension), so the selection can be reproduced. Generated and stored when the pipeline starts if left empty.

quality_threshold pydantic-field

quality_threshold: float | None = None

Minimum quality score

validate_splits pydantic-validator

validate_splits()

Validate splits based on segment_all mode.

omero_annotate_ai.core.annotation_config.AIModelConfig pydantic-model

Bases: _Section

AI model configuration (bioimage.io compatible)

Config:

  • extra: forbid
  • protected_namespaces: ()

Fields:

framework pydantic-field

framework: Literal['micro_sam', 'cellpose', 'web_annotation'] = 'micro_sam'

AI framework

framework_version pydantic-field

framework_version: str | None = None

Framework version

model_name pydantic-field

model_name: str = ''

Model name/identifier

model_version pydantic-field

model_version: str = 'latest'

Model version

model_url pydantic-field

model_url: HttpUrl | None = None

URL to model weights/repository

model_doi pydantic-field

model_doi: str | None = None

DOI for model citation

training_mode pydantic-field

training_mode: Literal['inference', 'finetuning', 'from_scratch'] = 'inference'

Training mode

pretrained_from pydantic-field

pretrained_from: str | None = 'vit_b_lm'

Base model for finetuning (e.g., 'vit_b_lm')

omero_annotate_ai.core.annotation_config.WorkflowConfig pydantic-model

Bases: _Section

How annotation sessions run.

Fields:

batch_size pydantic-field

batch_size: int = 0

Images per napari session (0 = all)

claim_hours pydantic-field

claim_hours: float = 6.0

OMERO sets: hours a session's claim on a unit lasts before another computer may take the unit over (see omero_annotate_ai.claims)

omero_annotate_ai.core.annotation_config.NormalizationConfig pydantic-model

Bases: _Section

Intensity normalisation of model input images.

Defined once and applied either when exporting training data (apply_at_export) or by the trainer, which is configured from the same values (see :mod:omero_annotate_ai.processing.normalization).

Fields:

Validators:

  • validate_percentiles

method pydantic-field

method: Literal['percentile', 'none'] = 'percentile'

'percentile': per-image percentile bounds mapped to [0, 1]. 'none': raw intensities.

percentile_low pydantic-field

percentile_low: float = 1.0

Lower percentile, mapped to 0

percentile_high pydantic-field

percentile_high: float = 99.8

Upper percentile, mapped to 1

clip pydantic-field

clip: bool = True

Clip normalised values to [0, 1]

apply_at_export pydantic-field

apply_at_export: bool = False

Write float32 normalised images (bounds recorded in normalization.json) instead of native bit depth

omero_annotate_ai.core.annotation_config.ZarrConfig pydantic-model

Bases: _Section

OME-Zarr image selection (used when source == "zarr").

Fields:

uris pydantic-field

uris: list[str]

OME-Zarr plates, wells or images (http(s) URL or local path)

level pydantic-field

level: int = 0

Multiscale level to read

fields pydantic-field

fields: Literal['first', 'all'] = 'first'

Fields per well: the first one, or all

wells pydantic-field

wells: list[str] | None = None

Only these wells, e.g. ['B2']

well_metadata pydantic-field

well_metadata: str | None = None

CSV with a 'well' column (optional 'plate') and metadata columns

well_filters pydantic-field

well_filters: dict[str, list[str]] | None = None

Filter wells on well_metadata values (AND logic)

omero_annotate_ai.core.annotation_config.Identity pydantic-model

Bases: _Section

Which training set this config belongs to. Written by omero-annotate-ai.

table_id is set for sets tracked in an OMERO table (storage: omero), local_uuid for sets kept only on disk (storage: local). Setting table_id before opening a set selects that existing set.

Fields:

server pydantic-field

server: str | None = None

OMERO server slug

table_id pydantic-field

table_id: int | None = None

OMERO tracking table ID

local_uuid pydantic-field

local_uuid: str | None = None

ID of a local-only set

omero_annotate_ai.core.annotation_config.SessionRecord pydantic-model

Bases: _Section

One annotation session: who, when, how many units, and the user's note.

Fields:

  • id (int)
  • kind (Literal['annotate', 'review'])
  • started (datetime)
  • ended (datetime | None)
  • status (Literal['open', 'finished', 'interrupted'])
  • user (str | None)
  • host (str | None)
  • software_version (str | None)
  • model (str | None)
  • batch_size (int | None)
  • n_annotated (int)
  • note (str | None)

host pydantic-field

host: str | None = None

Hashed ID of the computer

n_annotated pydantic-field

n_annotated: int = 0

Units saved (annotated, or changed in a review)

Metadata sections

omero_annotate_ai.core.annotation_config.StudyContext pydantic-model

Bases: _Section

Biological and experimental context (MIFA emphasis)

Fields:

title pydantic-field

title: str

Study/experiment title

description pydantic-field

description: str

Detailed study description

keywords pydantic-field

keywords: list[str]

Study keywords/tags

organism pydantic-field

organism: str | None = None

Organism studied

imaging_method pydantic-field

imaging_method: str | None = None

Microscopy technique used

funding_statement pydantic-field

funding_statement: str | None = None

How the study was funded (required by MIFA Study metadata)

omero_annotate_ai.core.annotation_config.DatasetInfo pydantic-model

Bases: _Section

Dataset identification and linking (both schemas)

Fields:

source_dataset_id pydantic-field

source_dataset_id: str | None = None

BioImage Archive accession or DOI

source_dataset_url pydantic-field

source_dataset_url: HttpUrl | None = None

URL to source dataset

source_description pydantic-field

source_description: str

Human-readable source description

license pydantic-field

license: str = 'CC-BY-4.0'

Data license

omero_annotate_ai.core.annotation_config.AnnotationMethodology pydantic-model

Bases: _Section

MIFA-compatible annotation methodology

Fields:

annotation_method pydantic-field

annotation_method: Literal['manual', 'semi_automatic', 'automatic'] | None = None

How annotations were produced

annotation_criteria pydantic-field

annotation_criteria: str

Criteria used for annotation

annotation_tool pydantic-field

annotation_tool: AnnotationTool | None = None

Tool used for annotation

omero_annotate_ai.core.annotation_config.AnnotationTool pydantic-model

Bases: _Section

Tool configuration for annotation workflows

Fields:

  • name (str)
  • version (str | None)
  • mode (Literal['automatic', 'interactive', 'human_in_the_loop'])
  • parameters (dict[str, Any] | None)

name pydantic-field

name: str

Tool name (e.g., 'micro-sam', 'cellpose')

version pydantic-field

version: str | None = None

Tool version

mode pydantic-field

mode: Literal['automatic', 'interactive', 'human_in_the_loop'] = 'interactive'

Annotation mode

parameters pydantic-field

parameters: dict[str, Any] | None = None

Tool-specific parameters

omero_annotate_ai.core.annotation_config.AuthorInfo pydantic-model

Bases: _Section

Author information compatible with bioimage.io

Fields:

name pydantic-field

name: str | None = None

Full name of the author

affiliation pydantic-field

affiliation: str | None = None

Institution affiliation

email pydantic-field

email: str | None = None

Contact email

orcid pydantic-field

orcid: HttpUrl | None = None

ORCID identifier