bioio-imagexpress 0.2.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,18 @@
1
+ # -*- coding: utf-8 -*-
2
+
3
+ """Top-level package for bioio_imagexpress."""
4
+
5
+ from importlib.metadata import PackageNotFoundError, version
6
+
7
+ try:
8
+ __version__ = version("bioio-imagexpress")
9
+ except PackageNotFoundError:
10
+ __version__ = "uninstalled"
11
+
12
+ __author__ = "bioio-devs"
13
+ __email__ = "brian.whitney@alleninstitute.org"
14
+
15
+ from .reader import Reader
16
+ from .reader_metadata import ReaderMetadata
17
+
18
+ __all__ = ["Reader", "ReaderMetadata"]
@@ -0,0 +1,463 @@
1
+ import csv
2
+ import io
3
+ import json
4
+ import logging
5
+ import posixpath
6
+ import re
7
+ from dataclasses import dataclass, field
8
+ from datetime import datetime
9
+ from typing import Any, Dict, List, Optional, Sequence, Tuple
10
+
11
+ from fsspec.spec import AbstractFileSystem
12
+
13
+ ###############################################################################
14
+
15
+ log = logging.getLogger(__name__)
16
+
17
+ JDCE_EXTENSION = ".jdce"
18
+ TIMEPOINT_DIR_PREFIX = "timepoint"
19
+
20
+ # A normalized well label
21
+ WELL_RE = re.compile(r"^([A-Z]{1,2})(\d{1,2})$")
22
+
23
+ # (well, site) -- one acquisition position.
24
+ SceneKey = Tuple[str, int]
25
+ # (t, channel, z) -- one plane within an acquisition position.
26
+ PlaneKey = Tuple[int, int, int]
27
+
28
+ ###############################################################################
29
+
30
+
31
+ def normalize_well(value: str) -> Optional[str]:
32
+ """
33
+ Normalize a well label to the filenames' form, e.g. ``"B - 7"`` to ``"B07"``.
34
+
35
+ Parameters
36
+ ----------
37
+ value: str
38
+ A well label from either the manifest or a filename.
39
+
40
+ Returns
41
+ -------
42
+ well: Optional[str]
43
+ The normalized label, or None if the value is not a well.
44
+ """
45
+ match = re.match(
46
+ r"^([A-Za-z]{1,2})-?(\d{1,2})$", (value or "").strip().replace(" ", "")
47
+ )
48
+ if match is None:
49
+ return None
50
+
51
+ return f"{match.group(1).upper()}{int(match.group(2)):02d}"
52
+
53
+
54
+ def well_to_row_column(well: str) -> Tuple[str, int]:
55
+ """
56
+ Split a normalized well label into its plate coordinates.
57
+
58
+ Parameters
59
+ ----------
60
+ well: str
61
+ A label as ``normalize_well`` produces it.
62
+
63
+ Returns
64
+ -------
65
+ coordinates: Tuple[str, int]
66
+ The row letters and the column number, e.g. ``("AA", 1)`` for ``"AA01"``.
67
+ """
68
+ match = WELL_RE.match(well)
69
+ if match is None:
70
+ raise ValueError(f"Not a well label: {well!r}")
71
+
72
+ return match.group(1), int(match.group(2))
73
+
74
+
75
+ ###############################################################################
76
+
77
+
78
+ @dataclass
79
+ class JdceMetadata:
80
+ """The subset of the ``.jdce`` descriptor this reader consumes."""
81
+
82
+ raw: Dict[str, Any] = field(default_factory=dict)
83
+ channel_names: Dict[int, str] = field(default_factory=dict)
84
+ pixel_size_x: Optional[float] = None
85
+ pixel_size_y: Optional[float] = None
86
+ z_step: Optional[float] = None
87
+ objective: Optional[str] = None
88
+ binning: Optional[str] = None
89
+ operator: Optional[str] = None
90
+ acquired_at: Optional[datetime] = None
91
+ metadata_files: List[str] = field(default_factory=list)
92
+
93
+
94
+ def parse_jdce(contents: str) -> JdceMetadata:
95
+ """
96
+ Pull the acquisition parameters out of a ``.jdce`` descriptor.
97
+
98
+ Parameters
99
+ ----------
100
+ contents: str
101
+ The descriptor's text. It is JSON, despite the extension.
102
+
103
+ Returns
104
+ -------
105
+ metadata: JdceMetadata
106
+ acquisition parameters out of a ``.jdce`` descriptor. Every field is optional.
107
+ """
108
+ raw = json.loads(contents)
109
+ stack = raw.get("ImageStack", {})
110
+ protocol = stack.get("AutoLeadAcquisitionProtocol", {})
111
+ calibration = protocol.get("ObjectiveCalibration", {})
112
+ wavelengths = protocol.get("Wavelengths", []) or []
113
+ channel_names: Dict[int, str] = {}
114
+ for wavelength in wavelengths:
115
+ name = (wavelength.get("EmissionFilter") or {}).get("Name")
116
+ index = _as_int(wavelength.get("Index"))
117
+ if name and index is not None:
118
+ channel_names[index] = name
119
+
120
+ z_step = next(
121
+ (v for v in (_as_float(w.get("ZStep")) for w in wavelengths) if v), None
122
+ )
123
+
124
+ binning = protocol.get("Camera", {}).get("Binning")
125
+
126
+ return JdceMetadata(
127
+ raw=raw,
128
+ channel_names=channel_names,
129
+ pixel_size_x=_as_float(calibration.get("PixelWidth")),
130
+ pixel_size_y=_as_float(calibration.get("PixelHeight")),
131
+ z_step=z_step,
132
+ objective=calibration.get("ObjectiveName"),
133
+ binning=re.sub(r"\s*[xX]\s*", "x", str(binning).strip()) if binning else None,
134
+ operator=stack.get("Operator", {}).get("Login") or None,
135
+ acquired_at=_parse_creation(stack.get("Creation", {})),
136
+ metadata_files=[
137
+ _as_relpath(str(n)) for n in (stack.get("ImageMetadataFiles") or []) if n
138
+ ],
139
+ )
140
+
141
+
142
+ def _parse_creation(creation: Dict[str, Any]) -> Optional[datetime]:
143
+ date = (creation.get("Date") or "").strip()
144
+ time = (creation.get("Time") or "").strip()
145
+ if not date or not time:
146
+ return None
147
+
148
+ try:
149
+ return datetime.fromisoformat(f"{date}T{time}")
150
+ except ValueError:
151
+ return None
152
+
153
+
154
+ def _as_float(value: Any) -> Optional[float]:
155
+ try:
156
+ return float(value)
157
+ except (TypeError, ValueError):
158
+ return None
159
+
160
+
161
+ def _as_int(value: Any) -> Optional[int]:
162
+ try:
163
+ return int(value)
164
+ except (TypeError, ValueError):
165
+ return None
166
+
167
+
168
+ def _as_relpath(value: str) -> str:
169
+ # The instrument runs Windows, so its path fields may arrive backslashed.
170
+ return value.strip().replace("\\", "/").strip("/")
171
+
172
+
173
+ ###############################################################################
174
+
175
+
176
+ @dataclass(frozen=True)
177
+ class ManifestRow:
178
+ """One row of ``image_metadata_*.csv``, reduced to what the index needs."""
179
+
180
+ well: str
181
+ site: int
182
+ channel: int
183
+ t: int
184
+ z: int
185
+ subfolder: str
186
+ filename: str
187
+ timestamp_s: Optional[float]
188
+ position_x_um: Optional[float]
189
+ position_y_um: Optional[float]
190
+
191
+
192
+ def read_manifest(contents: str) -> List[ManifestRow]:
193
+ """
194
+ Parse an ``image_metadata_*.csv`` manifest.
195
+
196
+ Parameters
197
+ ----------
198
+ contents: str
199
+ The manifest's text.
200
+
201
+ Returns
202
+ -------
203
+ rows: List[ManifestRow]
204
+ One row per plane. Rows that do not resolve to a full (well, site,
205
+ channel, t, z) coordinate are dropped. A manifest that yields no rows at
206
+ all leaves the acquisition unreadable; the manifest is the one source
207
+ of truth for which planes exist.
208
+ """
209
+ rows = []
210
+
211
+ for record in csv.DictReader(io.StringIO(contents)):
212
+ well = normalize_well(record.get("Well") or "")
213
+ site = _as_int(record.get("Field"))
214
+ channel = _as_int(record.get("Wavelength"))
215
+ t = _as_int(record.get("Timepoint"))
216
+ z = _as_int(record.get("ZIndex"))
217
+ filename = (record.get("ImageFileName") or "").strip()
218
+
219
+ if not filename or None in (well, site, channel, t, z):
220
+ continue
221
+
222
+ rows.append(
223
+ ManifestRow(
224
+ well=well, # type: ignore[arg-type]
225
+ site=site, # type: ignore[arg-type]
226
+ channel=channel, # type: ignore[arg-type]
227
+ t=t, # type: ignore[arg-type]
228
+ z=z, # type: ignore[arg-type]
229
+ subfolder=_as_relpath(record.get("ImageSubFolderPath") or ""),
230
+ filename=_as_relpath(filename),
231
+ timestamp_s=_as_float(record.get("TimeStampSec")),
232
+ position_x_um=_as_float(record.get("PositionXUm")),
233
+ position_y_um=_as_float(record.get("PositionYUm")),
234
+ )
235
+ )
236
+
237
+ return rows
238
+
239
+
240
+ ###############################################################################
241
+
242
+
243
+ @dataclass
244
+ class Acquisition:
245
+ """One acquisition: its descriptor, its plane index, and its stage metadata."""
246
+
247
+ path: str
248
+ jdce: JdceMetadata
249
+ planes: Dict[SceneKey, Dict[PlaneKey, str]] = field(default_factory=dict)
250
+ timestamps: Dict[SceneKey, Dict[int, float]] = field(default_factory=dict)
251
+ positions: Dict[SceneKey, Tuple[Optional[float], Optional[float]]] = field(
252
+ default_factory=dict
253
+ )
254
+
255
+ @property
256
+ def scene_keys(self) -> List[SceneKey]:
257
+ """Every (well, site) present, ordered by plate row, column, then site."""
258
+
259
+ def order(key: SceneKey) -> Tuple[int, str, int, int]:
260
+ row, column = well_to_row_column(key[0])
261
+ return len(row), row, column, key[1]
262
+
263
+ return sorted(self.planes, key=order)
264
+
265
+ @property
266
+ def wells(self) -> List[str]:
267
+ """The wells imaged, in plate order."""
268
+ return list(dict.fromkeys(well for well, _ in self.scene_keys))
269
+
270
+ def sites(self, well: str) -> List[int]:
271
+ """The acquisition positions imaged in ``well``, in order."""
272
+ return sorted(site for name, site in self.planes if name == well)
273
+
274
+ def extents(
275
+ self, keys: Sequence[SceneKey]
276
+ ) -> Tuple[List[int], List[int], List[int]]:
277
+ """
278
+ The T, C and Z indices present across ``keys``.
279
+
280
+ Takes several keys because a mosaic scene spans every tile of a well, and
281
+ a tile that dropped a time point must not shrink the others. Read off the
282
+ index rather than the descriptor, which promises planes an aborted
283
+ acquisition never wrote.
284
+ """
285
+ all_plane_keys: List[PlaneKey] = []
286
+ for key in keys:
287
+ all_plane_keys.extend(self.planes[key])
288
+
289
+ return (
290
+ sorted({plane[0] for plane in all_plane_keys}),
291
+ sorted({plane[1] for plane in all_plane_keys}),
292
+ sorted({plane[2] for plane in all_plane_keys}),
293
+ )
294
+
295
+ def channel_names(self, keys: Sequence[SceneKey]) -> List[str]:
296
+ """The descriptor's emission filter names for the channels ``keys`` cover."""
297
+ _, channels, _ = self.extents(keys)
298
+ names = self.jdce.channel_names
299
+
300
+ return [names.get(channel, f"Channel:{channel}") for channel in channels]
301
+
302
+ def time_coords(self, keys: Sequence[SceneKey]) -> Optional[List[float]]:
303
+ """
304
+ Elapsed seconds from the first time point of the scene ``keys`` span.
305
+
306
+ Measured from the manifest's timestamps for these keys alone, because
307
+ wells are imaged in sequence and another well's clock says nothing about
308
+ this one. The descriptor's ``TimeSchedule.Times[].Ms`` values are time
309
+ point indices rather than milliseconds, so they are deliberately not used.
310
+ """
311
+ stamps: Dict[int, float] = {}
312
+ for key in keys:
313
+ for t, seconds in self.timestamps.get(key, {}).items():
314
+ if t not in stamps or seconds < stamps[t]:
315
+ stamps[t] = seconds
316
+
317
+ timepoints, _, _ = self.extents(keys)
318
+ if not all(t in stamps for t in timepoints):
319
+ return None
320
+
321
+ origin = min(stamps.values())
322
+
323
+ return [stamps[t] - origin for t in timepoints]
324
+
325
+ @property
326
+ def first_timestamp(self) -> Optional[float]:
327
+ """The acquisition's earliest manifest timestamp, or None without one."""
328
+ stamps = [
329
+ s for per_scene in self.timestamps.values() for s in per_scene.values()
330
+ ]
331
+
332
+ return min(stamps) if stamps else None
333
+
334
+
335
+ ###############################################################################
336
+
337
+
338
+ def discover_acquisition(
339
+ fs: AbstractFileSystem, path: str
340
+ ) -> Optional[Tuple[str, str]]:
341
+ """
342
+ Resolve a user-supplied path to a single acquisition.
343
+
344
+ Parameters
345
+ ----------
346
+ fs: AbstractFileSystem
347
+ The filesystem ``path`` lives on.
348
+ path: str
349
+ A ``.jdce`` descriptor or an acquisition directory.
350
+
351
+ Returns
352
+ -------
353
+ acquisition: Optional[Tuple[str, str]]
354
+ The acquisition's directory and its descriptor, or None if the path is not an
355
+ acquisition. Naming the descriptor is accepted on its existence alone,
356
+ without the ``timepoint<N>`` check the directory form makes, because that
357
+ check costs a directory listing.
358
+ """
359
+ path = path.rstrip("/")
360
+
361
+ if path.lower().endswith(JDCE_EXTENSION):
362
+ try:
363
+ found = bool(fs.exists(path))
364
+ except Exception:
365
+ found = False
366
+ return (posixpath.dirname(path), path) if found else None
367
+
368
+ names = _list_dir_names(fs, path)
369
+ descriptors = sorted(
370
+ posixpath.join(path, name)
371
+ for name in names
372
+ if name.lower().endswith(JDCE_EXTENSION)
373
+ )
374
+ timepoints = any(name.lower().startswith(TIMEPOINT_DIR_PREFIX) for name in names)
375
+ if descriptors and timepoints:
376
+ if len(descriptors) > 1:
377
+ log.warning(
378
+ "%s holds %d descriptors; reading %s. Name a descriptor directly "
379
+ "to read another.",
380
+ path,
381
+ len(descriptors),
382
+ descriptors[0],
383
+ )
384
+ return path, descriptors[0]
385
+
386
+ return None
387
+
388
+
389
+ def index_acquisition(
390
+ fs: AbstractFileSystem, path: str, descriptor: str
391
+ ) -> Acquisition:
392
+ """
393
+ Index one acquisition, opening no TIFF.
394
+
395
+ Parameters
396
+ ----------
397
+ fs: AbstractFileSystem
398
+ The filesystem the acquisition lives on.
399
+ path: str
400
+ The acquisition's directory.
401
+ descriptor: str
402
+ The acquisition's ``.jdce`` file.
403
+
404
+ Returns
405
+ -------
406
+ acquisition: Acquisition
407
+ The plane index, built from the ``image_metadata_*.csv`` manifests.
408
+ """
409
+ try:
410
+ with fs.open(descriptor, "r", encoding="utf-8-sig") as handle:
411
+ jdce = parse_jdce(handle.read())
412
+ except Exception as exc:
413
+ log.warning("Could not parse descriptor %s: %s", descriptor, exc)
414
+ jdce = JdceMetadata()
415
+
416
+ if jdce.metadata_files:
417
+ manifests = [posixpath.join(path, name) for name in jdce.metadata_files]
418
+ else:
419
+ manifests = sorted(
420
+ posixpath.join(path, name)
421
+ for name in _list_dir_names(fs, path)
422
+ if name.lower().startswith("image_metadata_")
423
+ and name.lower().endswith(".csv")
424
+ )
425
+
426
+ rows: List[ManifestRow] = []
427
+ for manifest in manifests:
428
+ try:
429
+ with fs.open(manifest, "r", encoding="utf-8-sig") as handle:
430
+ rows.extend(read_manifest(handle.read()))
431
+ except Exception as exc:
432
+ log.warning("Could not read manifest %s: %s", manifest, exc)
433
+
434
+ acq = Acquisition(path=path, jdce=jdce)
435
+
436
+ # Plane paths are composed, not confirmed; a missing file surfaces when
437
+ # the plane is read.
438
+ for row in rows:
439
+ scene: SceneKey = (row.well, row.site)
440
+ acq.planes.setdefault(scene, {}).setdefault(
441
+ (row.t, row.channel, row.z),
442
+ posixpath.join(path, row.subfolder, row.filename),
443
+ )
444
+
445
+ if row.timestamp_s is not None:
446
+ stamps = acq.timestamps.setdefault(scene, {})
447
+ recorded = stamps.get(row.t)
448
+ if recorded is None or row.timestamp_s < recorded:
449
+ stamps[row.t] = row.timestamp_s
450
+
451
+ if scene not in acq.positions and row.position_x_um is not None:
452
+ acq.positions[scene] = (row.position_x_um, row.position_y_um)
453
+
454
+ return acq
455
+
456
+
457
+ def _list_dir_names(fs: AbstractFileSystem, path: str) -> List[str]:
458
+ # A filesystem that cannot list is a supported state, not an error.
459
+ try:
460
+ return [posixpath.basename(p.rstrip("/")) for p in fs.ls(path, detail=False)]
461
+ except Exception as exc:
462
+ log.debug("Could not list %s: %s", path, exc)
463
+ return []
File without changes
@@ -0,0 +1,482 @@
1
+ import logging
2
+ from datetime import datetime, timedelta, timezone
3
+ from itertools import product
4
+ from typing import Any, Dict, List, Optional, Tuple
5
+
6
+ import dask.array as da
7
+ import numpy as np
8
+ import tifffile
9
+ import xarray as xr
10
+ from bioio_base import constants, exceptions, io
11
+ from bioio_base.dimensions import DEFAULT_DIMENSION_ORDER_LIST, DimensionNames
12
+ from bioio_base.reader import Reader as BaseReader
13
+ from bioio_base.standard_metadata import StandardMetadata
14
+ from bioio_base.types import DimSpec, PhysicalPixelSizes, TimeInterval
15
+ from dask import delayed
16
+ from fsspec.spec import AbstractFileSystem
17
+
18
+ from . import acquisition
19
+ from .acquisition import SceneKey
20
+
21
+ ###############################################################################
22
+
23
+ log = logging.getLogger(__name__)
24
+
25
+ ###############################################################################
26
+
27
+
28
+ class Reader(BaseReader):
29
+ """
30
+ Read Molecular Devices ImageXpress / MetaXpress acquisitions
31
+
32
+ An acquisition is a directory rather than a single file: every plane is its
33
+ own TIFF, and the structure tying them together lives in a ``.jdce``
34
+ descriptor, an ``image_metadata_*.csv`` manifest, and the plane filenames.
35
+
36
+ Parameters
37
+ ----------
38
+ image: Path or str
39
+ Path to a ``.jdce`` descriptor or to the acquisition directory holding it.
40
+ fs_kwargs: Dict[str, Any]
41
+ Any specific keyword arguments to pass down to the fsspec created filesystem.
42
+ Default: {}
43
+
44
+ Raises
45
+ ------
46
+ exceptions.UnsupportedFileFormatError
47
+ If the path is not an ImageXpress acquisition.
48
+ """
49
+
50
+ NAME = "bioio-imagexpress"
51
+
52
+ def __init__(
53
+ self,
54
+ image: Any,
55
+ fs_kwargs: Dict[str, Any] = {},
56
+ **kwargs: Any,
57
+ ):
58
+ self._fs, self._path = io.pathlike_to_fs(
59
+ image, enforce_exists=True, fs_kwargs=fs_kwargs
60
+ )
61
+
62
+ discovered = acquisition.discover_acquisition(self._fs, self._path)
63
+ if discovered is None:
64
+ raise exceptions.UnsupportedFileFormatError(
65
+ self.__class__.__name__,
66
+ self._path,
67
+ msg_extra=(
68
+ "Expected an ImageXpress acquisition directory (a '.jdce' "
69
+ "descriptor plus 'timepoint<N>' folders) or the '.jdce' "
70
+ "file itself."
71
+ ),
72
+ )
73
+
74
+ # Fetch Manifest
75
+ self._acquisition = acquisition.index_acquisition(self._fs, *discovered)
76
+ if not self._acquisition.planes:
77
+ raise exceptions.UnsupportedFileFormatError(
78
+ self.__class__.__name__,
79
+ self._path,
80
+ msg_extra=(
81
+ "No planes could be indexed from the acquisition's "
82
+ "'image_metadata_*.csv' manifest"
83
+ ),
84
+ )
85
+
86
+ self._scene_table = [
87
+ (well, (site,)) for well, site in self._acquisition.scene_keys
88
+ ]
89
+
90
+ # The current scene's (level_shapes, dtype, metaseries)
91
+ self._plane_metadata: Optional[
92
+ Tuple[List[Tuple[int, ...]], np.dtype, Optional[Dict[str, Any]]]
93
+ ] = None
94
+
95
+ self._scenes: Optional[Tuple[str, ...]] = None
96
+
97
+ @staticmethod
98
+ def _is_supported_image(fs: AbstractFileSystem, path: str, **kwargs: Any) -> bool:
99
+ return acquisition.discover_acquisition(fs, path) is not None
100
+
101
+ @property
102
+ def scenes(self) -> Tuple[str, ...]:
103
+ """
104
+ Returns
105
+ -------
106
+ scenes: Tuple[str, ...]
107
+ A tuple of valid scene ids in the file.
108
+ """
109
+ if self._scenes is None:
110
+ self._scenes = tuple(
111
+ f"{well}-s{sites[0]}" for well, sites in self._scene_table
112
+ )
113
+
114
+ return self._scenes
115
+
116
+ def _read_delayed(self) -> xr.DataArray:
117
+ return self._build_xarray(delayed_read=True)
118
+
119
+ def _read_immediate(self) -> xr.DataArray:
120
+ return self._build_xarray(delayed_read=False)
121
+
122
+ def _read_indexed(self, given_dims: str, dim_specs: List[DimSpec]) -> np.ndarray:
123
+ """
124
+ Slice the delayed graph so that only the planes asked for are opened.
125
+
126
+ Every plane is a separate file, so the base implementation -- materialize
127
+ the scene, then slice -- opens one file per TxCxZ even for a single plane.
128
+
129
+ Parameters
130
+ ----------
131
+ given_dims: str
132
+ The native dimension ordering of the image (``self.dims.order``).
133
+ dim_specs: List[DimSpec]
134
+ One getitem operation per dimension in ``given_dims``.
135
+
136
+ Returns
137
+ -------
138
+ data: np.ndarray
139
+ The indexed image data in native (reduced) dimension order.
140
+ """
141
+ if sum(isinstance(spec, (list, tuple)) for spec in dim_specs) > 1:
142
+ return super()._read_indexed(given_dims, dim_specs)
143
+
144
+ return self.dask_data[tuple(dim_specs)].compute()
145
+
146
+ def _build_xarray(self, delayed_read: bool) -> xr.DataArray:
147
+ well, sites = self._current()
148
+ timepoints, channels, zs = self._acquisition.extents(self._current_keys())
149
+ level = self._level()
150
+ shape = self._level_shapes[level]
151
+
152
+ planes = [
153
+ self._plane_array(
154
+ self._acquisition.planes[(well, site)].get((t, channel, z)),
155
+ shape,
156
+ self._plane_dtype,
157
+ level,
158
+ delayed_read,
159
+ )
160
+ for site, t, channel, z in product(sites, timepoints, channels, zs)
161
+ ]
162
+
163
+ stacked = da.stack(planes) if delayed_read else np.stack(planes)
164
+ data = stacked.reshape(
165
+ (len(sites), len(timepoints), len(channels), len(zs)) + tuple(shape)
166
+ )
167
+
168
+ return xr.DataArray(
169
+ data[0],
170
+ dims=DEFAULT_DIMENSION_ORDER_LIST,
171
+ coords=self._coords(zs),
172
+ attrs={constants.METADATA_UNPROCESSED: self._unprocessed_metadata()},
173
+ )
174
+
175
+ @property
176
+ def resolution_levels(self) -> Tuple[int, ...]:
177
+ """
178
+ Returns
179
+ -------
180
+ resolution_levels: Tuple[int, ...]
181
+ The levels of the pyramid MetaXpress writes into each plane.
182
+ """
183
+ return tuple(range(len(self._level_shapes)))
184
+
185
+ @property
186
+ def physical_pixel_sizes(self) -> PhysicalPixelSizes:
187
+ """
188
+ Returns
189
+ -------
190
+ sizes: PhysicalPixelSizes
191
+ Using available metadata, the floats representing physical pixel sizes for
192
+ dimensions Z, Y, and X.
193
+ """
194
+ scale = self._level_scale()
195
+ pixel_y = self._acquisition.jdce.pixel_size_y
196
+ pixel_x = self._acquisition.jdce.pixel_size_x
197
+
198
+ return PhysicalPixelSizes(
199
+ self._acquisition.jdce.z_step,
200
+ pixel_y * scale if pixel_y is not None else None,
201
+ pixel_x * scale if pixel_x is not None else None,
202
+ )
203
+
204
+ @property
205
+ def binning(self) -> Optional[str]:
206
+ """Camera binning as ``"<x>x<y>"``, e.g. ``"1x1"``."""
207
+ return self._acquisition.jdce.binning
208
+
209
+ @property
210
+ def objective(self) -> Optional[str]:
211
+ """The objective the acquisition was taken with."""
212
+ return self._acquisition.jdce.objective
213
+
214
+ @property
215
+ def row(self) -> Optional[str]:
216
+ """Plate row letters of the current scene, e.g. ``"B"``."""
217
+ return acquisition.well_to_row_column(self._current()[0])[0]
218
+
219
+ @property
220
+ def column(self) -> Optional[str]:
221
+ """Plate column of the current scene, unpadded, e.g. ``"7"``."""
222
+ return str(acquisition.well_to_row_column(self._current()[0])[1])
223
+
224
+ @property
225
+ def position_index(self) -> Optional[int]:
226
+ """
227
+ The current scene's acquisition position within its well.
228
+ """
229
+ return self._current()[1][0]
230
+
231
+ @property
232
+ def imaged_by(self) -> Optional[str]:
233
+ """The acquisition protocol's user, falling back to the station login."""
234
+ return self._acquisition.jdce.operator
235
+
236
+ @property
237
+ def imaging_datetime(self) -> Optional[datetime]:
238
+ """
239
+ When the acquisition began.
240
+ """
241
+ if self._acquisition.jdce.acquired_at is not None:
242
+ return self._acquisition.jdce.acquired_at
243
+
244
+ first = self._acquisition.first_timestamp
245
+ if first is None:
246
+ return None
247
+
248
+ return datetime.fromtimestamp(first, tz=timezone.utc)
249
+
250
+ @property
251
+ def stage_position(self) -> Tuple[Optional[float], Optional[float]]:
252
+ """
253
+ Stage X and Y of the current scene in microns, from the manifest.
254
+ """
255
+ well, sites = self._current()
256
+ stage = [
257
+ self._acquisition.positions.get((well, site), (None, None))
258
+ for site in sites
259
+ ]
260
+ if any(x is None or y is None for x, y in stage):
261
+ return (None, None)
262
+
263
+ positions = [(float(x), float(y)) for x, y in stage] # type: ignore[arg-type]
264
+
265
+ return (
266
+ sum(x for x, _ in positions) / len(positions),
267
+ sum(y for _, y in positions) / len(positions),
268
+ )
269
+
270
+ @property
271
+ def time_interval(self) -> TimeInterval:
272
+ """
273
+ Average interval between the current scene's time points.
274
+ """
275
+ duration = self.total_time_duration
276
+ if duration is None:
277
+ return None
278
+
279
+ timepoints, _, _ = self._acquisition.extents(self._current_keys())
280
+
281
+ return duration / (len(timepoints) - 1)
282
+
283
+ @property
284
+ def total_time_duration(self) -> Optional[timedelta]:
285
+ """
286
+ Elapsed time from the first to the last time point of the current scene.
287
+ """
288
+ elapsed = self._acquisition.time_coords(self._current_keys())
289
+ if elapsed is None or len(elapsed) < 2:
290
+ return None
291
+
292
+ return timedelta(seconds=elapsed[-1] - elapsed[0])
293
+
294
+ @property
295
+ def standard_metadata(self) -> StandardMetadata:
296
+ """
297
+ Return the embedded metadata for this reader.
298
+ """
299
+ metadata = super().standard_metadata
300
+
301
+ metadata.binning = self.binning
302
+ metadata.column = self.column
303
+ metadata.imaged_by = self.imaged_by
304
+ metadata.imaging_datetime = self.imaging_datetime
305
+ metadata.objective = self.objective
306
+ metadata.position_index = self.position_index
307
+ metadata.row = self.row
308
+ metadata.stage_position_x, metadata.stage_position_y = self.stage_position
309
+ metadata.total_time_duration = self.total_time_duration
310
+
311
+ return metadata
312
+
313
+ def _current(self) -> Tuple[str, Tuple[int, ...]]:
314
+ return self._scene_table[self._current_scene_index]
315
+
316
+ def _current_keys(self) -> List[SceneKey]:
317
+ well, sites = self._current()
318
+
319
+ return [(well, site) for site in sites]
320
+
321
+ def _reset_self(self) -> None:
322
+ self._plane_metadata = None
323
+ super()._reset_self()
324
+
325
+ @property
326
+ def _level_shapes(self) -> List[Tuple[int, ...]]:
327
+ """Pyramid shapes of the current scene's planes."""
328
+ if self._plane_metadata is None:
329
+ self._plane_metadata = self._read_plane_metadata()
330
+
331
+ shapes, _, _ = self._plane_metadata
332
+ return shapes
333
+
334
+ @property
335
+ def _plane_dtype(self) -> np.dtype:
336
+ """Pixel dtype of the current scene's planes."""
337
+ if self._plane_metadata is None:
338
+ self._plane_metadata = self._read_plane_metadata()
339
+
340
+ _, dtype, _ = self._plane_metadata
341
+ return dtype
342
+
343
+ @property
344
+ def _metaseries(self) -> Optional[Dict[str, Any]]:
345
+ """MetaSeries tags of the current scene's planes."""
346
+ if self._plane_metadata is None:
347
+ self._plane_metadata = self._read_plane_metadata()
348
+
349
+ _, _, metaseries = self._plane_metadata
350
+ return metaseries
351
+
352
+ def _read_plane_metadata(
353
+ self,
354
+ ) -> Tuple[List[Tuple[int, ...]], np.dtype, Optional[Dict[str, Any]]]:
355
+ """
356
+ Read the current scene's pyramid shapes, dtype and MetaSeries tags off
357
+ one plane.
358
+ """
359
+ paths = [
360
+ self._acquisition.planes[key][plane]
361
+ for key in self._current_keys()
362
+ for plane in sorted(self._acquisition.planes[key])
363
+ ]
364
+ error: Optional[Exception] = None
365
+ for path in paths:
366
+ try:
367
+ with self._fs.open(path, "rb") as handle:
368
+ with tifffile.TiffFile(handle) as tiff:
369
+ series = tiff.series[0]
370
+ try:
371
+ metaseries = tiff.metaseries_metadata
372
+ except Exception as exc:
373
+ log.debug("Could not read MetaSeries tags: %s", exc)
374
+ metaseries = None
375
+
376
+ return (
377
+ [tuple(level.shape) for level in series.levels],
378
+ np.dtype(series.dtype),
379
+ metaseries,
380
+ )
381
+ except Exception as exc:
382
+ error = exc
383
+ log.warning("Could not probe %s: %s", path, exc)
384
+
385
+ raise IOError(
386
+ f"No plane of scene '{self.current_scene}' could be opened."
387
+ ) from error
388
+
389
+ def _level(self) -> int:
390
+ level = self._current_resolution_level
391
+ available = len(self._level_shapes)
392
+ if level >= available:
393
+ raise IndexError(
394
+ f"Scene '{self.current_scene}' has {available} resolution levels; "
395
+ f"level {level} was set. Call set_resolution_level to pick one of "
396
+ "this scene's levels."
397
+ )
398
+
399
+ return level
400
+
401
+ def _level_scale(self) -> float:
402
+ """Linear downsample factor of the current level relative to level 0."""
403
+ shapes = self._level_shapes
404
+
405
+ return shapes[0][-1] / shapes[self._level()][-1]
406
+
407
+ def _plane_array(
408
+ self,
409
+ path: Optional[str],
410
+ shape: Tuple[int, ...],
411
+ dtype: np.dtype,
412
+ level: int,
413
+ delayed_read: bool,
414
+ ) -> Any:
415
+ if not delayed_read:
416
+ return _read_plane(self._fs, path, level)
417
+
418
+ return da.from_delayed(
419
+ delayed(_read_plane)(self._fs, path, level), shape=shape, dtype=dtype
420
+ )
421
+
422
+ def _coords(self, zs: List[int]) -> Dict[str, Any]:
423
+ keys = self._current_keys()
424
+ coords: Dict[str, Any] = {
425
+ DimensionNames.Channel: self._acquisition.channel_names(keys)
426
+ }
427
+
428
+ times = self._acquisition.time_coords(keys)
429
+ if times is not None:
430
+ coords[DimensionNames.Time] = times
431
+
432
+ if self._acquisition.jdce.z_step:
433
+ coords[DimensionNames.SpatialZ] = [
434
+ z * self._acquisition.jdce.z_step for z in zs
435
+ ]
436
+
437
+ return coords
438
+
439
+ def _unprocessed_metadata(self) -> Dict[str, Any]:
440
+ """The descriptor plus the plate position a writer needs to place a scene."""
441
+ well, sites = self._current()
442
+ positions = [
443
+ self._acquisition.positions.get((well, s), (None, None)) for s in sites
444
+ ]
445
+ origin_x, origin_y = positions[0]
446
+
447
+ row, column = acquisition.well_to_row_column(well)
448
+ metadata: Dict[str, Any] = {
449
+ "jdce": self._acquisition.jdce.raw,
450
+ "well": well,
451
+ "row": row,
452
+ "column": column,
453
+ "sites": list(sites),
454
+ "stage_position_um": {"x": origin_x, "y": origin_y},
455
+ "tile_stage_positions_um": [
456
+ {"site": site, "x": x, "y": y} for site, (x, y) in zip(sites, positions)
457
+ ],
458
+ }
459
+
460
+ if self._metaseries is not None:
461
+ metadata["metaseries"] = self._metaseries
462
+
463
+ return metadata
464
+
465
+
466
+ ###############################################################################
467
+
468
+
469
+ def _read_plane(fs: AbstractFileSystem, path: Optional[str], level: int) -> np.ndarray:
470
+ if path is None:
471
+ raise FileNotFoundError("The acquisition indexes no plane at this coordinate.")
472
+
473
+ with fs.open(path, "rb") as handle:
474
+ with tifffile.TiffFile(handle) as tiff:
475
+ series = tiff.series[0]
476
+ if level >= len(series.levels):
477
+ raise IndexError(
478
+ f"{path} has {len(series.levels)} resolution levels; "
479
+ f"level {level} was requested."
480
+ )
481
+
482
+ return series.levels[level].asarray()
@@ -0,0 +1,37 @@
1
+ #!/usr/bin/env python
2
+ # -*- coding: utf-8 -*-
3
+
4
+ from typing import List
5
+
6
+ import bioio_base.reader_metadata
7
+
8
+ ###############################################################################
9
+
10
+
11
+ class ReaderMetadata(bioio_base.reader_metadata.ReaderMetadata):
12
+ """
13
+ Notes
14
+ -----
15
+ Defines metadata for the reader itself (not the image read),
16
+ such as supported file extensions.
17
+ """
18
+
19
+ @staticmethod
20
+ def get_supported_extensions() -> List[str]:
21
+ """
22
+ Return a list of file extensions this plugin supports reading.
23
+
24
+ An ImageXpress acquisition is a directory of per-plane TIFFs; the
25
+ ``.jdce`` descriptor is the one file that identifies it, and naming it is
26
+ what lets ``bioio`` route to this reader on its own.
27
+ """
28
+ return [".jdce"]
29
+
30
+ @staticmethod
31
+ def get_reader() -> bioio_base.reader.Reader:
32
+ """
33
+ Return the reader this plugin represents
34
+ """
35
+ from .reader import Reader
36
+
37
+ return Reader
@@ -0,0 +1,69 @@
1
+ Metadata-Version: 2.4
2
+ Name: bioio-imagexpress
3
+ Version: 0.2.0
4
+ Summary: A BioIO reader plugin for reading Molecular Devices ImageXpress (multifile) images.
5
+ Author-email: bioio-devs <brian.whitney@alleninstitute.org>
6
+ License: MIT License
7
+ Project-URL: Homepage, https://github.com/bioio-devs/bioio-imagexpress
8
+ Project-URL: Bug Tracker, https://github.com/bioio-devs/bioio-imagexpress/issues
9
+ Project-URL: Documentation, https://bioio-devs.github.io/bioio-imagexpress
10
+ Project-URL: User Support, https://github.com/bioio-devs/bioio-imagexpress/issues
11
+ Classifier: Development Status :: 4 - Beta
12
+ Classifier: Natural Language :: English
13
+ Classifier: Programming Language :: Python :: 3.10
14
+ Classifier: Programming Language :: Python :: 3.11
15
+ Classifier: Programming Language :: Python :: 3.12
16
+ Classifier: Programming Language :: Python :: 3.13
17
+ Requires-Python: >=3.10
18
+ Description-Content-Type: text/markdown
19
+ License-File: LICENSE
20
+ Requires-Dist: bioio-base>=3.4.0
21
+ Requires-Dist: dask[array]>=2021.4.1
22
+ Requires-Dist: fsspec>=2022.8.0
23
+ Requires-Dist: imagecodecs>=2020.5.30
24
+ Requires-Dist: numpy>=1.21
25
+ Requires-Dist: tifffile>=2021.8.30
26
+ Requires-Dist: xarray>=0.16.1
27
+ Provides-Extra: lint
28
+ Requires-Dist: pre-commit>=2.20.0; extra == "lint"
29
+ Provides-Extra: test
30
+ Requires-Dist: bioio>=3.0.0; extra == "test"
31
+ Requires-Dist: coverage>=5.1; extra == "test"
32
+ Requires-Dist: pytest>=5.4.3; extra == "test"
33
+ Requires-Dist: pytest-cov>=2.9.0; extra == "test"
34
+ Requires-Dist: pytest-raises>=0.11; extra == "test"
35
+ Dynamic: license-file
36
+
37
+ # bioio-imagexpress
38
+
39
+ [![Build Status](https://github.com/bioio-devs/bioio-imagexpress/actions/workflows/ci.yml/badge.svg)](https://github.com/bioio-devs/bioio-imagexpress/actions)
40
+ [![Documentation](https://github.com/bioio-devs/bioio-imagexpress/actions/workflows/docs.yml/badge.svg)](https://bioio-devs.github.io/bioio-imagexpress)
41
+
42
+ A BioIO reader plugin for reading Molecular Devices ImageXpress (multifile) images.
43
+
44
+ This plugin is intended to be used in conjunction with [bioio](https://github.com/bioio-devs/bioio)
45
+ ---
46
+
47
+ ## Installation
48
+
49
+ **Stable Release:** `pip install bioio-imagexpress`<br>
50
+ **Development Head:** `pip install git+https://github.com/bioio-devs/bioio-imagexpress.git`
51
+
52
+ ## Quickstart
53
+
54
+ ```python
55
+ from bioio_imagexpress import Reader
56
+
57
+ r = Reader("my-image.ext")
58
+ r.dims
59
+ ```
60
+
61
+ ## Documentation
62
+
63
+ For full package documentation please visit [bioio-devs.github.io/bioio-imagexpress](https://bioio-devs.github.io/bioio-imagexpress).
64
+
65
+ ## Development
66
+
67
+ See [CONTRIBUTING.md](CONTRIBUTING.md) for information related to developing the code.
68
+
69
+ **MIT License**
@@ -0,0 +1,11 @@
1
+ bioio_imagexpress/__init__.py,sha256=bgS_-9IpYu1pYUlxEclcXNKxhyxiQqWvnA7IXOz7-FI,434
2
+ bioio_imagexpress/acquisition.py,sha256=LP0FuT7LE0MUiJNUemSrGgMGco8X2fBg_Gm2QbZHNO4,14865
3
+ bioio_imagexpress/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
4
+ bioio_imagexpress/reader.py,sha256=4Sh-JUKPa06nDxbxf-_7QrLpAxlatRMCZDo-zwBwoEs,16291
5
+ bioio_imagexpress/reader_metadata.py,sha256=AA2PLcDNp91oOPCr1V5bFt1v5DCYPcnTsGrf-hZRRk8,1000
6
+ bioio_imagexpress-0.2.0.dist-info/licenses/LICENSE,sha256=yx0BuV5IDZnE-n4kZzpQaCQzimc2IQqZIVhxhJo8MoU,1068
7
+ bioio_imagexpress-0.2.0.dist-info/METADATA,sha256=2iwomgFZrAf2k5_Osz6sOZGA-cWm174ijMYqkClaQpw,2570
8
+ bioio_imagexpress-0.2.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
9
+ bioio_imagexpress-0.2.0.dist-info/entry_points.txt,sha256=bAo6VFQUJjV1fqx_cs2aAeimOaaIsWYcHIkCEjUziLA,54
10
+ bioio_imagexpress-0.2.0.dist-info/top_level.txt,sha256=PNwZ6YdrllGIIqhFCz8V5zpnL6xH2mxk-3tcxSxCdhs,18
11
+ bioio_imagexpress-0.2.0.dist-info/RECORD,,
@@ -0,0 +1,5 @@
1
+ Wheel-Version: 1.0
2
+ Generator: setuptools (84.0.0)
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
5
+
@@ -0,0 +1,2 @@
1
+ [bioio.readers]
2
+ bioio-imagexpress = bioio_imagexpress
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026, bioio-devs
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1 @@
1
+ bioio_imagexpress