Configuration¶
omero_annotate_ai.core.annotation_config.load_config_from_yaml
¶
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 configuration from various sources.
omero_annotate_ai.core.annotation_config.create_default_config
¶
Create a default configuration.
omero_annotate_ai.core.annotation_config.get_config_template
¶
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:forbidvalidate_assignment:True
Fields:
-
schema_version(int) -
name(str) -
authors(list[AuthorInfo]) -
created(datetime) -
study(StudyContext) -
dataset(DatasetInfo) -
annotation_methodology(AnnotationMethodology) -
spatial_coverage(SpatialCoverage) -
training(TrainingConfig) -
normalization(NormalizationConfig) -
ai_model(AIModelConfig) -
workflow(WorkflowConfig) -
omero(OMEROConfig) -
source(Literal['omero', 'zarr']) -
zarr(ZarrConfig) -
storage(Literal['omero', 'local']) -
identity(Identity) -
sessions(list[SessionRecord]) -
documentation(HttpUrl | None) -
repository(HttpUrl | None) -
tags(list[str]) -
feature_types(list[FeatureType]) -
notes(str | None) -
custom_metadata(dict[str, Any])
Validators:
-
_reject_removed_keys -
_check_sources
storage
pydantic-field
¶
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.
feature_types
pydantic-field
¶
Annotation classes (e.g. cell, nucleus) with display colors
notes
pydantic-field
¶
Free-text notes about the annotation set (context, caveats, known issues)
custom_metadata
pydantic-field
¶
Additional key-value metadata not covered by the schema
to_yaml
¶
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 configuration to YAML file and remember the path.
from_dict
classmethod
¶
Create configuration from dictionary.
from_yaml
classmethod
¶
Create configuration from YAML string or file path.
to_json
¶
Serialize to JSON string.
Uses the same dict representation as to_dict(), ensuring consistency with YAML serialization.
from_json
classmethod
¶
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(str) -
container_id(int) -
container_ids(list[int] | None) -
source_desc(str) -
well_filters(dict[str, list[str]] | None) -
well_filter_mode(Literal['include', 'exclude'])
container_ids
pydantic-field
¶
List of OMERO container IDs of the same type. Takes precedence over container_id when set.
well_filters
pydantic-field
¶
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
¶
Whether to include or exclude wells matching the filters
get_all_container_ids
¶
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 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
¶
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:
-
channels(list[int]) -
timepoints(list[int]) -
n_timepoints(int | None) -
timepoint_mode(Literal['all', 'random', 'specific']) -
z_slices(list[int]) -
n_slices(int | None) -
z_slice_mode(Literal['all', 'random', 'specific']) -
three_d(bool) -
z_range_start(int | None) -
z_range_end(int | None) -
label_channel(int | None) -
training_channels(list[int] | None) -
context_channels(list[int]) -
context_channel_names(list[str] | None) -
context_channel_colormaps(list[str] | None) -
use_patches(bool) -
patch_size(list[int]) -
patches_per_image(int) -
random_patches(bool)
Validators:
n_timepoints
pydantic-field
¶
Number of timepoints to randomly select (used when timepoint_mode='random'). If not specified, uses the length of timepoints list for backward compatibility.
n_slices
pydantic-field
¶
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.
z_range_start
pydantic-field
¶
Starting z-slice for 3D volumes (when three_d=True)
z_range_end
pydantic-field
¶
Ending z-slice for 3D volumes (when three_d=True)
label_channel
pydantic-field
¶
Channel index used for segmentation/labeling (e.g., fluorescence nuclei). If not specified, defaults to channels[0] for backward compatibility.
training_channels
pydantic-field
¶
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
¶
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
¶
Display names for context_channels. Length must match context_channels when provided. Defaults to 'ch{idx}'.
context_channel_colormaps
pydantic-field
¶
Napari colormap names for context_channels. Length must match context_channels when provided. Defaults to cycle ['blue', 'magenta', 'green', 'yellow', 'cyan'].
get_label_channel
¶
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 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
¶
Check if separate channels are configured for labeling and training.
Returns True if label_channel differs from all training_channels.
uses_context_channels
¶
Return True if any context channels are configured.
get_context_channel_specs
¶
Return [(channel_index, display_name, colormap), ...] for each context channel.
model_dump
¶
Override model_dump to exclude patch fields when use_patches is False.
validate_3d_settings
pydantic-validator
¶
Validate 3D configuration consistency
validate_channel_settings
pydantic-validator
¶
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:
-
validation_strategy(Literal['random_split', 'expert_review', 'cross_validation']) -
split_unit(Literal['image', 'well']) -
split_rationale(str | None) -
stratify_by(list[str]) -
train_fraction(float) -
validation_fraction(float) -
test_fraction(float) -
train_n(int) -
validate_n(int) -
test_n(int) -
segment_all(bool) -
seed(int | None) -
quality_threshold(float | None)
Validators:
split_unit
pydantic-field
¶
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
¶
Why this split unit was chosen, e.g. 'fields within a well do not overlap'
stratify_by
pydantic-field
¶
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
¶
Fraction of data for training (used when segment_all=True)
validation_fraction
pydantic-field
¶
Fraction of data for validation (used when segment_all=True)
test_fraction
pydantic-field
¶
Fraction of data for testing (used when segment_all=True)
seed
pydantic-field
¶
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.
omero_annotate_ai.core.annotation_config.AIModelConfig
pydantic-model
¶
Bases: _Section
AI model configuration (bioimage.io compatible)
Config:
extra:forbidprotected_namespaces:()
Fields:
-
framework(Literal['micro_sam', 'cellpose', 'web_annotation']) -
framework_version(str | None) -
model_name(str) -
model_version(str) -
model_url(HttpUrl | None) -
model_doi(str | None) -
training_mode(Literal['inference', 'finetuning', 'from_scratch']) -
pretrained_from(str | None)
omero_annotate_ai.core.annotation_config.WorkflowConfig
pydantic-model
¶
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:
-
method(Literal['percentile', 'none']) -
percentile_low(float) -
percentile_high(float) -
clip(bool) -
apply_at_export(bool)
Validators:
-
validate_percentiles
omero_annotate_ai.core.annotation_config.ZarrConfig
pydantic-model
¶
Bases: _Section
OME-Zarr image selection (used when source == "zarr").
Fields:
-
uris(list[str]) -
level(int) -
fields(Literal['first', 'all']) -
wells(list[str] | None) -
well_metadata(str | None) -
well_filters(dict[str, list[str]] | None) -
well_filter_mode(Literal['include', 'exclude'])
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(str | None) -
table_id(int | None) -
local_uuid(str | None)
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)
Metadata sections¶
omero_annotate_ai.core.annotation_config.StudyContext
pydantic-model
¶
Bases: _Section
Biological and experimental context (MIFA emphasis)
Fields:
-
title(str) -
description(str) -
keywords(list[str]) -
organism(str | None) -
imaging_method(str | None) -
funding_statement(str | None)
funding_statement
pydantic-field
¶
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(str | None) -
source_dataset_url(HttpUrl | None) -
source_description(str) -
license(str)
source_dataset_id
pydantic-field
¶
BioImage Archive accession or DOI
omero_annotate_ai.core.annotation_config.AnnotationMethodology
pydantic-model
¶
Bases: _Section
MIFA-compatible annotation methodology
Fields:
-
annotation_type(Literal['segmentation_mask', 'bounding_box', 'point', 'classification', 'semantic_segmentation']) -
annotation_method(Literal['manual', 'semi_automatic', 'automatic'] | None) -
annotation_criteria(str) -
annotation_coverage(Literal['all', 'representative', 'partial']) -
annotation_tool(AnnotationTool | None)
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)
mode
pydantic-field
¶
Annotation mode
omero_annotate_ai.core.annotation_config.AuthorInfo
pydantic-model
¶
Bases: _Section
Author information compatible with bioimage.io
Fields:
-
name(str | None) -
affiliation(str | None) -
email(str | None) -
orcid(HttpUrl | None)