Skip to content

specs

Pydantic models related to OME-NGFF 0.4 specs, as implemented in fractal-tasks-core.

AcquisitionInPlate

Bases: BaseModel

Model for an element of Plate.acquisitions.

See https://ngff.openmicroscopy.org/0.4/#plate-md.

Source code in fractal_tasks_core/ngff/specs.py 
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
class AcquisitionInPlate(BaseModel):
    """
    Model for an element of `Plate.acquisitions`.

    See https://ngff.openmicroscopy.org/0.4/#plate-md.
    """

    id: int = Field(
        description="A unique identifier within the context of the plate"
    )
    maximumfieldcount: Optional[int] = Field(
        None,
        description=(
            "Int indicating the maximum number of fields of view for the "
            "acquisition"
        ),
    )
    name: Optional[str] = Field(
        None, description="a string identifying the name of the acquisition"
    )
    description: Optional[str] = Field(
        None,
        description="The description of the acquisition",
    )

Axis

Bases: BaseModel

Model for an element of Multiscale.axes.

See https://ngff.openmicroscopy.org/0.4/#axes-md.

Source code in fractal_tasks_core/ngff/specs.py 
67
68
69
70
71
72
73
74
75
76
class Axis(BaseModel):
    """
    Model for an element of `Multiscale.axes`.

    See https://ngff.openmicroscopy.org/0.4/#axes-md.
    """

    name: str
    type: Optional[str] = None
    unit: Optional[str] = None

Channel

Bases: BaseModel

Model for an element of Omero.channels.

See https://ngff.openmicroscopy.org/0.4/#omero-md.

Source code in fractal_tasks_core/ngff/specs.py 
43
44
45
46
47
48
49
50
51
52
53
54
class Channel(BaseModel):
    """
    Model for an element of `Omero.channels`.

    See https://ngff.openmicroscopy.org/0.4/#omero-md.
    """

    window: Optional[Window] = None
    label: Optional[str] = None
    family: Optional[str] = None
    color: str
    active: Optional[bool] = None

ColumnInPlate

Bases: BaseModel

Model for an element of Plate.columns.

See https://ngff.openmicroscopy.org/0.4/#plate-md.

Source code in fractal_tasks_core/ngff/specs.py 
437
438
439
440
441
442
443
444
class ColumnInPlate(BaseModel):
    """
    Model for an element of `Plate.columns`.

    See https://ngff.openmicroscopy.org/0.4/#plate-md.
    """

    name: str

Dataset

Bases: BaseModel

Model for an element of Multiscale.datasets.

See https://ngff.openmicroscopy.org/0.4/#multiscale-md

Source code in fractal_tasks_core/ngff/specs.py 
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
class Dataset(BaseModel):
    """
    Model for an element of `Multiscale.datasets`.

    See https://ngff.openmicroscopy.org/0.4/#multiscale-md
    """

    path: str
    coordinateTransformations: list[
        Union[
            ScaleCoordinateTransformation, TranslationCoordinateTransformation
        ]
    ] = Field(..., min_length=1)

    @property
    def scale_transformation(self) -> ScaleCoordinateTransformation:
        """
        Extract the unique scale transformation, or fail otherwise.
        """
        _transformations = [
            t for t in self.coordinateTransformations if t.type == "scale"
        ]
        if len(_transformations) == 0:
            raise ValueError(
                "Missing scale transformation in dataset.\n"
                "Current coordinateTransformations:\n"
                f"{self.coordinateTransformations}"
            )
        elif len(_transformations) > 1:
            raise ValueError(
                "More than one scale transformation in dataset.\n"
                "Current coordinateTransformations:\n"
                f"{self.coordinateTransformations}"
            )
        else:
            return _transformations[0]

scale_transformation: ScaleCoordinateTransformation property

Extract the unique scale transformation, or fail otherwise.

ImageInWell

Bases: BaseModel

Model for an element of Well.images.

Note 1: The NGFF image is defined in a different model (NgffImageMeta), while the Image model only refere to an item of Well.images.

Note 2: We deviate from NGFF specs, since we allow path to be an arbitrary string. TODO: include a check like constr(regex=r'^[A-Za-z0-9]+$'), through a Pydantic validator.

See https://ngff.openmicroscopy.org/0.4/#well-md.

Source code in fractal_tasks_core/ngff/specs.py 
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
class ImageInWell(BaseModel):
    """
    Model for an element of `Well.images`.

    **Note 1:** The NGFF image is defined in a different model
    (`NgffImageMeta`), while the `Image` model only refere to an item of
    `Well.images`.

    **Note 2:** We deviate from NGFF specs, since we allow `path` to be an
    arbitrary string.
    TODO: include a check like `constr(regex=r'^[A-Za-z0-9]+$')`, through a
    Pydantic validator.

    See https://ngff.openmicroscopy.org/0.4/#well-md.
    """

    acquisition: Optional[int] = Field(
        None, description="A unique identifier within the context of the plate"
    )
    path: str = Field(
        ..., description="The path for this field of view subgroup"
    )

Multiscale

Bases: BaseModel

Model for an element of NgffImageMeta.multiscales.

See https://ngff.openmicroscopy.org/0.4/#multiscale-md.

Source code in fractal_tasks_core/ngff/specs.py 
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
class Multiscale(BaseModel):
    """
    Model for an element of `NgffImageMeta.multiscales`.

    See https://ngff.openmicroscopy.org/0.4/#multiscale-md.
    """

    name: Optional[str] = None
    datasets: list[Dataset] = Field(..., min_length=1)
    version: Optional[str] = None
    axes: list[Axis] = Field(..., max_length=5, min_length=2)
    coordinateTransformations: Optional[
        list[
            Union[
                ScaleCoordinateTransformation,
                TranslationCoordinateTransformation,
            ]
        ]
    ] = None
    _check_unique = field_validator("axes")(unique_items_validator)

    @field_validator("coordinateTransformations", mode="after")
    @classmethod
    def _no_global_coordinateTransformations(
        cls, v: Optional[list]
    ) -> Optional[list]:
        """
        Fail if Multiscale has a (global) coordinateTransformations attribute.
        """
        if v is None:
            return v
        else:
            raise NotImplementedError(
                "Global coordinateTransformations at the multiscales "
                "level are not currently supported in the fractal-tasks-core "
                "model for the NGFF multiscale."
            )

_no_global_coordinateTransformations(v) classmethod

Fail if Multiscale has a (global) coordinateTransformations attribute.

Source code in fractal_tasks_core/ngff/specs.py 
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
@field_validator("coordinateTransformations", mode="after")
@classmethod
def _no_global_coordinateTransformations(
    cls, v: Optional[list]
) -> Optional[list]:
    """
    Fail if Multiscale has a (global) coordinateTransformations attribute.
    """
    if v is None:
        return v
    else:
        raise NotImplementedError(
            "Global coordinateTransformations at the multiscales "
            "level are not currently supported in the fractal-tasks-core "
            "model for the NGFF multiscale."
        )

NgffImageMeta

Bases: BaseModel

Model for the metadata of a NGFF image.

See https://ngff.openmicroscopy.org/0.4/#image-layout.

Source code in fractal_tasks_core/ngff/specs.py 
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
class NgffImageMeta(BaseModel):
    """
    Model for the metadata of a NGFF image.

    See https://ngff.openmicroscopy.org/0.4/#image-layout.
    """

    multiscales: list[Multiscale] = Field(
        ...,
        description="The multiscale datasets for this image",
        min_length=1,
    )
    omero: Optional[Omero] = None
    _check_unique = field_validator("multiscales")(unique_items_validator)

    @property
    def multiscale(self) -> Multiscale:
        """
        The single element of `self.multiscales`.

        Raises:
            NotImplementedError:
                If there are no multiscales or more than one.
        """
        if len(self.multiscales) > 1:
            raise NotImplementedError(
                "Only images with one multiscale are supported "
                f"(given: {len(self.multiscales)}"
            )
        return self.multiscales[0]

    @property
    def datasets(self) -> list[Dataset]:
        """
        The `datasets` attribute of `self.multiscale`.
        """
        return self.multiscale.datasets

    @property
    def num_levels(self) -> int:
        return len(self.datasets)

    @property
    def axes_names(self) -> list[str]:
        """
        List of axes names.
        """
        return [ax.name for ax in self.multiscale.axes]

    @property
    def pixel_sizes_zyx(self) -> list[list[float]]:
        """
        Pixel sizes extracted from scale transformations of datasets.

        Raises:
            ValueError:
                If pixel sizes are below a given threshold (1e-9).
        """
        x_index = self.axes_names.index("x")
        y_index = self.axes_names.index("y")
        try:
            z_index = self.axes_names.index("z")
        except ValueError:
            z_index = None
            logging.warning(
                f"Z axis is not present (axes: {self.axes_names}), and Z pixel"
                " size is set to 1. This may work, by accident, but it is "
                "not fully supported."
            )
        _pixel_sizes_zyx = []
        for level in range(self.num_levels):
            scale = self.datasets[level].scale_transformation.scale
            pixel_size_x = scale[x_index]
            pixel_size_y = scale[y_index]
            if z_index is not None:
                pixel_size_z = scale[z_index]
            else:
                pixel_size_z = 1.0
            _pixel_sizes_zyx.append([pixel_size_z, pixel_size_y, pixel_size_x])
            if min(_pixel_sizes_zyx[-1]) < 1e-9:
                raise ValueError(
                    f"Pixel sizes at level {level} are too small: "
                    f"{_pixel_sizes_zyx[-1]}"
                )

        return _pixel_sizes_zyx

    def get_pixel_sizes_zyx(self, *, level: int = 0) -> list[float]:
        return self.pixel_sizes_zyx[level]

    @property
    def coarsening_xy(self) -> int:
        """
        Linear coarsening factor in the YX plane.

        We only support coarsening factors that are homogeneous (both in the
        X/Y directions and across pyramid levels).

        Raises:
            NotImplementedError:
                If coarsening ratios are not homogeneous.
        """
        current_ratio = None
        for ind in range(1, self.num_levels):
            ratio_x = round(
                self.pixel_sizes_zyx[ind][2] / self.pixel_sizes_zyx[ind - 1][2]
            )
            ratio_y = round(
                self.pixel_sizes_zyx[ind][1] / self.pixel_sizes_zyx[ind - 1][1]
            )
            if ratio_x != ratio_y:
                raise NotImplementedError(
                    "Inhomogeneous coarsening in X/Y directions "
                    "is not supported.\n"
                    f"ZYX pixel sizes:\n {self.pixel_sizes_zyx}"
                )
            if current_ratio is None:
                current_ratio = ratio_x
            else:
                if current_ratio != ratio_x:
                    raise NotImplementedError(
                        "Inhomogeneous coarsening across levels "
                        "is not supported.\n"
                        f"ZYX pixel sizes:\n {self.pixel_sizes_zyx}"
                    )

        return current_ratio

axes_names: list[str] property

List of axes names.

coarsening_xy: int property

Linear coarsening factor in the YX plane.

We only support coarsening factors that are homogeneous (both in the X/Y directions and across pyramid levels).

RAISES DESCRIPTION
NotImplementedError

If coarsening ratios are not homogeneous.

datasets: list[Dataset] property

The datasets attribute of self.multiscale.

multiscale: Multiscale property

The single element of self.multiscales.

RAISES DESCRIPTION
NotImplementedError

If there are no multiscales or more than one.

pixel_sizes_zyx: list[list[float]] property

Pixel sizes extracted from scale transformations of datasets.

RAISES DESCRIPTION
ValueError

If pixel sizes are below a given threshold (1e-9).

NgffPlateMeta

Bases: BaseModel

Model for the metadata of a NGFF plate.

See https://ngff.openmicroscopy.org/0.4/#plate-md.

Source code in fractal_tasks_core/ngff/specs.py 
476
477
478
479
480
481
482
483
class NgffPlateMeta(BaseModel):
    """
    Model for the metadata of a NGFF plate.

    See https://ngff.openmicroscopy.org/0.4/#plate-md.
    """

    plate: Plate

NgffWellMeta

Bases: BaseModel

Model for the metadata of a NGFF well.

See https://ngff.openmicroscopy.org/0.4/#well-md.

Source code in fractal_tasks_core/ngff/specs.py 
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
class NgffWellMeta(BaseModel):
    """
    Model for the metadata of a NGFF well.

    See https://ngff.openmicroscopy.org/0.4/#well-md.
    """

    well: Optional[Well] = None

    def get_acquisition_paths(self) -> dict[int, list[str]]:
        """
        Create mapping from acquisition indices to corresponding paths.

        Runs on the well zarr attributes and loads the relative paths in the
        well.

        Returns:
            Dictionary with `(acquisition index: [image_path])` key/value
            pairs.

        Raises:
            ValueError:
                If an element of `self.well.images` has no `acquisition`
                    attribute.
        """
        acquisition_dict = {}
        for image in self.well.images:
            if image.acquisition is None:
                raise ValueError(
                    "Cannot get acquisition paths for Zarr files without "
                    "'acquisition' metadata at the well level"
                )
            if image.acquisition not in acquisition_dict:
                acquisition_dict[image.acquisition] = []
            acquisition_dict[image.acquisition].append(image.path)
        return acquisition_dict

get_acquisition_paths()

Create mapping from acquisition indices to corresponding paths.

Runs on the well zarr attributes and loads the relative paths in the well.

RETURNS DESCRIPTION
dict[int, list[str]]

Dictionary with (acquisition index: [image_path]) key/value
dict[int, list[str]]

pairs.
RAISES DESCRIPTION
ValueError

If an element of self.well.images has no acquisition attribute.
Source code in fractal_tasks_core/ngff/specs.py 
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
def get_acquisition_paths(self) -> dict[int, list[str]]:
    """
    Create mapping from acquisition indices to corresponding paths.

    Runs on the well zarr attributes and loads the relative paths in the
    well.

    Returns:
        Dictionary with `(acquisition index: [image_path])` key/value
        pairs.

    Raises:
        ValueError:
            If an element of `self.well.images` has no `acquisition`
                attribute.
    """
    acquisition_dict = {}
    for image in self.well.images:
        if image.acquisition is None:
            raise ValueError(
                "Cannot get acquisition paths for Zarr files without "
                "'acquisition' metadata at the well level"
            )
        if image.acquisition not in acquisition_dict:
            acquisition_dict[image.acquisition] = []
        acquisition_dict[image.acquisition].append(image.path)
    return acquisition_dict

Omero

Bases: BaseModel

Model for NgffImageMeta.omero.

See https://ngff.openmicroscopy.org/0.4/#omero-md.

Source code in fractal_tasks_core/ngff/specs.py 
57
58
59
60
61
62
63
64
class Omero(BaseModel):
    """
    Model for `NgffImageMeta.omero`.

    See https://ngff.openmicroscopy.org/0.4/#omero-md.
    """

    channels: list[Channel]

Plate

Bases: BaseModel

Model for NgffPlateMeta.plate.

See https://ngff.openmicroscopy.org/0.4/#plate-md.

Source code in fractal_tasks_core/ngff/specs.py 
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
class Plate(BaseModel):
    """
    Model for `NgffPlateMeta.plate`.

    See https://ngff.openmicroscopy.org/0.4/#plate-md.
    """

    acquisitions: Optional[list[AcquisitionInPlate]] = None
    columns: list[ColumnInPlate]
    field_count: Optional[int] = None
    name: Optional[str] = None
    rows: list[RowInPlate]
    # version will become required in 0.5
    version: Optional[str] = Field(
        None, description="The version of the specification"
    )
    wells: list[WellInPlate]

RowInPlate

Bases: BaseModel

Model for an element of Plate.rows.

See https://ngff.openmicroscopy.org/0.4/#plate-md.

Source code in fractal_tasks_core/ngff/specs.py 
447
448
449
450
451
452
453
454
class RowInPlate(BaseModel):
    """
    Model for an element of `Plate.rows`.

    See https://ngff.openmicroscopy.org/0.4/#plate-md.
    """

    name: str

ScaleCoordinateTransformation

Bases: BaseModel

Model for a scale transformation.

This corresponds to scale-type elements of Dataset.coordinateTransformations or Multiscale.coordinateTransformations. See https://ngff.openmicroscopy.org/0.4/#trafo-md

Source code in fractal_tasks_core/ngff/specs.py 
79
80
81
82
83
84
85
86
87
88
89
90
class ScaleCoordinateTransformation(BaseModel):
    """
    Model for a scale transformation.

    This corresponds to scale-type elements of
    `Dataset.coordinateTransformations` or
    `Multiscale.coordinateTransformations`.
    See https://ngff.openmicroscopy.org/0.4/#trafo-md
    """

    type: Literal["scale"]
    scale: list[float] = Field(..., min_length=2)

TranslationCoordinateTransformation

Bases: BaseModel

Model for a translation transformation.

This corresponds to translation-type elements of Dataset.coordinateTransformations or Multiscale.coordinateTransformations. See https://ngff.openmicroscopy.org/0.4/#trafo-md

Source code in fractal_tasks_core/ngff/specs.py 
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
class TranslationCoordinateTransformation(BaseModel):
    """
    Model for a translation transformation.

    This corresponds to translation-type elements of
    `Dataset.coordinateTransformations` or
    `Multiscale.coordinateTransformations`.
    See https://ngff.openmicroscopy.org/0.4/#trafo-md
    """

    type: Literal["translation"]
    translation: list[float] = Field(..., min_length=2)

Well

Bases: BaseModel

Model for NgffWellMeta.well.

See https://ngff.openmicroscopy.org/0.4/#well-md.

Source code in fractal_tasks_core/ngff/specs.py 
337
338
339
340
341
342
343
344
345
346
347
348
349
350
class Well(BaseModel):
    """
    Model for `NgffWellMeta.well`.

    See https://ngff.openmicroscopy.org/0.4/#well-md.
    """

    images: list[ImageInWell] = Field(
        ..., description="The images included in this well", min_length=1
    )
    version: Optional[str] = Field(
        None, description="The version of the specification"
    )
    _check_unique = field_validator("images")(unique_items_validator)

WellInPlate

Bases: BaseModel

Model for an element of Plate.wells.

See https://ngff.openmicroscopy.org/0.4/#plate-md.

Source code in fractal_tasks_core/ngff/specs.py 
425
426
427
428
429
430
431
432
433
434
class WellInPlate(BaseModel):
    """
    Model for an element of `Plate.wells`.

    See https://ngff.openmicroscopy.org/0.4/#plate-md.
    """

    path: str
    rowIndex: int
    columnIndex: int

Window

Bases: BaseModel

Model for Channel.window.

Note that we deviate by NGFF specs by making start and end optional. See https://ngff.openmicroscopy.org/0.4/#omero-md.

Source code in fractal_tasks_core/ngff/specs.py 
29
30
31
32
33
34
35
36
37
38
39
40
class Window(BaseModel):
    """
    Model for `Channel.window`.

    Note that we deviate by NGFF specs by making `start` and `end` optional.
    See https://ngff.openmicroscopy.org/0.4/#omero-md.
    """

    max: float
    min: float
    start: Optional[float] = None
    end: Optional[float] = None