Coverage for src/bioimageio/core/prediction.py: 89%
121 statements
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-20 09:46 +0000
« prev ^ index » next coverage.py v7.17.3, created at 2026-11-20 09:46 +0000
1from __future__ import annotations
3import atexit
4import itertools
5from collections.abc import Hashable, Iterable, Iterator, Mapping, Sequence, Sized
6from pathlib import Path
7from typing import overload
9import dask.array as da
10from loguru import logger
11from tqdm import tqdm
13from bioimageio.spec import load_description
14from bioimageio.spec.common import PermissiveFileSource
15from bioimageio.spec.model import v0_4, v0_5
17from ._prediction_pipeline import PredictionPipeline, create_prediction_pipeline
18from ._utils.type_hints import cast_and_assert
19from .axis import AxisId
20from .common import BlocksizeParameter, MemberId, PerMember
21from .digest_spec import TensorSource, create_sample_for_model, get_member_id
22from .io import save_sample
23from .sample import Sample
24from .tensor import Tensor
27@overload
28def predict(
29 *,
30 model: PermissiveFileSource
31 | v0_4.ModelDescr
32 | v0_5.ModelDescr
33 | PredictionPipeline,
34 inputs: Sample | PerMember[TensorSource] | TensorSource,
35 sample_id: Hashable = "sample",
36 blocksize_parameter: BlocksizeParameter | None = None,
37 input_block_shape: Mapping[MemberId, Mapping[AxisId, int]] | None = None,
38 output_path: None = None,
39 devices: Sequence[str] | None = None,
40 cache_path_after_preprocessing: Path | str | None = None,
41 cache_path_before_postprocessing: Path | str | None = None,
42) -> Sample: ...
45@overload
46def predict(
47 *,
48 model: PermissiveFileSource
49 | v0_4.ModelDescr
50 | v0_5.ModelDescr
51 | PredictionPipeline,
52 inputs: Sample | PerMember[TensorSource] | TensorSource,
53 sample_id: Hashable = "sample",
54 blocksize_parameter: BlocksizeParameter | None = None,
55 input_block_shape: Mapping[MemberId, Mapping[AxisId, int]] | None = None,
56 output_path: Path | str,
57 devices: Sequence[str] | None = None,
58 cache_path_after_preprocessing: Path | str | None = None,
59 cache_path_before_postprocessing: Path | str | None = None,
60) -> PerMember[Path]: ...
63@overload
64def predict(
65 *,
66 model: PermissiveFileSource
67 | v0_4.ModelDescr
68 | v0_5.ModelDescr
69 | PredictionPipeline,
70 inputs: Sample | PerMember[TensorSource] | TensorSource,
71 sample_id: Hashable = "sample",
72 blocksize_parameter: BlocksizeParameter | None = None,
73 input_block_shape: Mapping[MemberId, Mapping[AxisId, int]] | None = None,
74 output_path: Path | str | None = None,
75 devices: Sequence[str] | None = None,
76 cache_path_after_preprocessing: Path | str | None = None,
77 cache_path_before_postprocessing: Path | str | None = None,
78) -> Sample | PerMember[Path]: ...
81def predict(
82 *,
83 model: PermissiveFileSource
84 | v0_4.ModelDescr
85 | v0_5.ModelDescr
86 | PredictionPipeline,
87 inputs: Sample | PerMember[TensorSource] | TensorSource,
88 sample_id: Hashable = "sample",
89 blocksize_parameter: BlocksizeParameter | None = None,
90 input_block_shape: Mapping[MemberId, Mapping[AxisId, int]] | None = None,
91 output_path: Path | str | None = None,
92 devices: Sequence[str] | None = None,
93 cache_path_after_preprocessing: Path | str | None = None,
94 cache_path_before_postprocessing: Path | str | None = None,
95) -> Sample | PerMember[Path]:
96 """Run prediction for a single set of input(s) with a bioimage.io model
98 Args:
99 model: Model to predict with.
100 May be given as RDF source, model description or prediction pipeline.
101 inputs: the input sample or the named input(s) for this model as a dictionary
102 sample_id: the sample id.
103 The **sample_id** is used to format **output_path**
104 and to distinguish sample specific log messages.
105 blocksize_parameter: (optional) Tile the input into blocks parametrized by
106 **blocksize_parameter** according to any parametrized axis sizes defined
107 by the **model**.
108 See `bioimageio.spec.model.v0_5.ParameterizedSize` for details.
109 Note: For a predetermined, fixed block shape use **input_block_shape**.
110 input_block_shape: (optional) Tile the input sample tensors into blocks.
111 Note: Use **blocksize_parameter** for a parameterized block shape to
112 run prediction independent of the exact block shape.
113 output_path: A path (pattern) to save the output to.
114 Must contain:
115 - `{output_id}` (or `{member_id}`) if the model has multiple output tensors
116 May contain:
117 - `{sample_id}` to avoid overwriting recurrent calls with distinct **sample_id**.
118 cache_path_after_preprocessing: (experimental)
119 A path to cache the input after preprocessing.
120 Must have a '.zarr' suffix.
121 Must include `{member_id}`.
122 If the model has no preprocessing this will be ignored.
123 cache_path_before_postprocessing: (experimental)
124 A path to cache the output before postprocessing.
125 Must have a '.zarr' suffix.
126 Must include `{member_id}`.
127 If the model has no postprocessing this will be ignored.
129 Returns:
130 The eager (numpy-based) output sample if **model** was not given as a prediction pipeline and **output_path** was None.
131 The lazy (dask-based) output sample if **model** was given as a prediction pipeline and **output_path** was None.
132 The mapping of output tensor id to output file path if **output_path** was given.
133 """
134 if cache_path_after_preprocessing is not None:
135 if "{member_id}" not in str(cache_path_after_preprocessing):
136 raise ValueError(
137 f"Missing `{{member_id}}` in cache_path_after_preprocessing={cache_path_after_preprocessing}"
138 + " to differentiate cached sample members."
139 )
140 if Path(cache_path_after_preprocessing).suffix != ".zarr":
141 raise NotImplementedError(
142 f"cache_path_after_preprocessing={cache_path_after_preprocessing} must have a '.zarr' suffix"
143 )
144 if cache_path_before_postprocessing is not None:
145 if "{member_id}" not in str(cache_path_before_postprocessing):
146 raise ValueError(
147 f"Missing `{{member_id}}` in cache_path_before_postprocessing={cache_path_before_postprocessing}"
148 + " to differentiate cached sample members."
149 )
150 if Path(cache_path_before_postprocessing).suffix != ".zarr":
151 raise NotImplementedError(
152 f"cache_path_before_postprocessing={cache_path_before_postprocessing} must have a '.zarr' suffix"
153 )
154 if cache_path_before_postprocessing == cache_path_after_preprocessing:
155 raise ValueError(
156 f"cache_path_before_postprocessing={cache_path_before_postprocessing} must be different from "
157 + f"cache_path_after_preprocessing={cache_path_after_preprocessing}"
158 )
160 if isinstance(model, PredictionPipeline):
161 pp = model
162 model = pp.model_descr
163 unload_pp = False
164 if not pp.is_loaded: 164 ↛ 165line 164 didn't jump to line 165 because the condition on line 164 was never true
165 pp.load()
166 _ = atexit.register(pp.unload)
167 else:
168 if not isinstance(model, (v0_4.ModelDescr, v0_5.ModelDescr)):
169 loaded = load_description(model)
170 if not isinstance(loaded, (v0_4.ModelDescr, v0_5.ModelDescr)): 170 ↛ 171line 170 didn't jump to line 171 because the condition on line 170 was never true
171 raise TypeError(f"expected model description, but got {loaded}")
172 model = loaded
174 pp = create_prediction_pipeline(
175 model,
176 fixed_dataset_statistics=inputs.stat if isinstance(inputs, Sample) else {},
177 keep_updating_initial_dataset_statistics=False,
178 dataset_for_initial_statistics=[inputs],
179 devices=devices,
180 )
181 pp.load()
182 unload_pp = True
184 try:
185 model_descr = pp.model_descr
186 if output_path is not None and ( 186 ↛ 191line 186 didn't jump to line 191 because the condition on line 186 was never true
187 "{output_id}" not in str(output_path)
188 and "{member_id}" not in str(output_path)
189 and len(model_descr.outputs) > 1
190 ):
191 raise ValueError(
192 f"Missing `{{output_id}}` in output_path={output_path} to "
193 + "distinguish model outputs "
194 + str([get_member_id(d) for d in model_descr.outputs])
195 )
197 if isinstance(inputs, Sample):
198 sample = inputs.copy(deep=False)
199 else:
200 sample = create_sample_for_model(
201 pp.model_descr, inputs=inputs, sample_id=sample_id
202 )
203 sample.members = {
204 k: v.unstack_batch_multi_index()
205 if v.batch_multi_index is not None
206 else v
207 for k, v in sample.members.items()
208 }
210 pp.apply_input_padding(sample)
211 pp.apply_preprocessing(sample)
212 if cache_path_after_preprocessing is not None:
213 for m in list(sample.members):
214 cache_path = Path(
215 str(cache_path_after_preprocessing).format(member_id=m)
216 )
217 assert str(cache_path) != str(output_path)
218 assert str(cache_path) != str(cache_path_after_preprocessing)
219 assert str(cache_path) != str(cache_path_before_postprocessing)
221 data = cast_and_assert(da.Array, sample.members[m].as_dask().data.data)
222 logger.info(
223 "caching input sample member {} to {}",
224 m,
225 cache_path,
226 )
227 cached_data = da.to_zarr(
228 data,
229 cache_path,
230 compute=False,
231 return_stored=True,
232 overwrite=True,
233 mode="w",
234 )
235 cached_tensor = Tensor(cached_data, sample.members[m].dims)
236 cached_tensor.set_metadata(sample.members[m].get_metadata())
237 sample.members[m] = cached_tensor
239 if input_block_shape is not None:
240 if blocksize_parameter is not None: 240 ↛ 241line 240 didn't jump to line 241 because the condition on line 240 was never true
241 logger.warning(
242 "ignoring blocksize_parameter={} in favor of input_block_shape={}",
243 blocksize_parameter,
244 input_block_shape,
245 )
247 output = pp.predict_with_fixed_blocking(
248 sample,
249 input_block_shape=input_block_shape,
250 skip_input_padding=True,
251 skip_preprocessing=True,
252 skip_postprocessing=True,
253 skip_output_cropping=True,
254 )
255 elif blocksize_parameter is not None:
256 output = pp.predict_with_blocking(
257 sample,
258 ns=blocksize_parameter,
259 skip_input_padding=True,
260 skip_preprocessing=True,
261 skip_postprocessing=True,
262 skip_output_cropping=True,
263 )
264 else:
265 output = pp.predict_without_blocking(
266 sample,
267 skip_input_padding=True,
268 skip_preprocessing=True,
269 skip_postprocessing=True,
270 skip_output_cropping=True,
271 )
273 if cache_path_before_postprocessing is not None:
274 for m in list(output.members):
275 cache_path = Path(
276 str(cache_path_before_postprocessing).format(member_id=m)
277 )
278 assert str(cache_path) != str(output_path)
279 assert str(cache_path) != str(cache_path_before_postprocessing)
281 data = cast_and_assert(da.Array, output.members[m].as_dask().data.data)
282 logger.info(
283 "caching output sample member {} to {}",
284 m,
285 cache_path,
286 )
287 cached_data = da.to_zarr(
288 data,
289 cache_path,
290 compute=False,
291 return_stored=True,
292 overwrite=True,
293 mode="w",
294 )
295 cached_tensor = Tensor(cached_data, output.members[m].dims)
296 cached_tensor.set_metadata(output.members[m].get_metadata())
297 output.members[m] = cached_tensor
299 pp.apply_postprocessing(output)
300 pp.apply_output_cropping(output)
302 if output_path:
303 return save_sample(output_path, output)
304 elif unload_pp:
305 return output.as_numpy()
306 else:
307 return output
308 finally:
309 if unload_pp:
310 pp.unload()
313@overload
314def predict_many(
315 *,
316 model: PermissiveFileSource
317 | v0_4.ModelDescr
318 | v0_5.ModelDescr
319 | PredictionPipeline,
320 inputs: Iterable[PerMember[TensorSource]] | Iterable[TensorSource],
321 sample_id: str | Iterable[str] = "sample{i:03}",
322 blocksize_parameter: v0_5.ParameterizedSize_N
323 | Mapping[tuple[MemberId, AxisId], v0_5.ParameterizedSize_N]
324 | None = None,
325 output_path: Path | str,
326) -> Iterator[PerMember[Path]]: ...
329@overload
330def predict_many(
331 *,
332 model: PermissiveFileSource
333 | v0_4.ModelDescr
334 | v0_5.ModelDescr
335 | PredictionPipeline,
336 inputs: Iterable[PerMember[TensorSource]] | Iterable[TensorSource],
337 sample_id: str | Iterable[str] = "sample{i:03}",
338 blocksize_parameter: v0_5.ParameterizedSize_N
339 | Mapping[tuple[MemberId, AxisId], v0_5.ParameterizedSize_N]
340 | None = None,
341 output_path: None = None,
342) -> Iterator[Sample]: ...
345def predict_many(
346 *,
347 model: PermissiveFileSource
348 | v0_4.ModelDescr
349 | v0_5.ModelDescr
350 | PredictionPipeline,
351 inputs: Iterable[PerMember[TensorSource]] | Iterable[TensorSource],
352 sample_id: str | Iterable[str] = "sample{i:03}",
353 blocksize_parameter: v0_5.ParameterizedSize_N
354 | Mapping[tuple[MemberId, AxisId], v0_5.ParameterizedSize_N]
355 | None = None,
356 output_path: Path | str | None = None,
357) -> Iterator[Sample] | Iterator[PerMember[Path]]:
358 """Run prediction for a multiple sets of inputs with a bioimage.io model
360 Args:
361 model: Model to predict with.
362 May be given as RDF source, model description or prediction pipeline.
363 inputs: An iterable of the (named) input(s) for this model.
364 sample_id: The sample id pattern or iterable that is not a string (specify samples a,b,c as ['a', 'b', 'c'], not 'abc').
365 Note: If the `sample_id` (item) contains `{i}`, it will be formatted as the i-th sample starting with i=0.
366 If `{i}` (or `{i:`) is not present and `sample_id` is a single string, `{i:03}` is appended.
367 blocksize_parameter: (optional) Tile the input into blocks parametrized by
368 blocksize according to any parametrized axis sizes defined in the model RDF.
369 output_path: A path to save the output to.
370 Must contain:
371 - `{sample_id}` to differentiate predicted samples
372 - `{output_id}` (or `{member_id}`) if the model has multiple outputs
374 Returns:
375 An iterator of the mapping of output tensor id to output file path if **output_path** was given.
376 An iterator of the lazy output samples if **output_path** was None and **model** was given as a prediction pipeline
377 An iterator of the eager output samples if **output_path** was None and **model** was not given as a prediction pipeline
378 """
379 if output_path is not None and "{sample_id}" not in str(output_path):
380 raise ValueError(
381 f"Missing `{{sample_id}}` in output_path={output_path}"
382 + " to differentiate predicted samples."
383 )
385 if isinstance(model, PredictionPipeline): 385 ↛ 388line 385 didn't jump to line 388 because the condition on line 385 was always true
386 pp = model
387 else:
388 if not isinstance(model, (v0_4.ModelDescr, v0_5.ModelDescr)):
389 loaded = load_description(model)
390 if not isinstance(loaded, (v0_4.ModelDescr, v0_5.ModelDescr)):
391 raise TypeError(f"expected model description, but got {loaded}")
392 model = loaded
394 pp = create_prediction_pipeline(
395 model,
396 keep_updating_initial_dataset_statistics=False,
397 dataset_for_initial_statistics=inputs,
398 )
400 if isinstance(sample_id, str):
401 if "{i}" not in sample_id and "{i:" not in sample_id:
402 sample_id += "{i:03}"
404 sample_ids = itertools.repeat(sample_id)
405 else:
406 sample_ids = sample_id
408 total = (
409 len(inputs)
410 if isinstance(inputs, Sized)
411 else len(sample_ids)
412 if not isinstance(sample_ids, str) and isinstance(sample_ids, Sized)
413 else None
414 )
416 for i, (s_id, ipts) in tqdm(enumerate(zip(sample_ids, inputs)), total=total):
417 output = predict(
418 model=pp,
419 inputs=ipts,
420 sample_id=s_id.format(i=i),
421 blocksize_parameter=blocksize_parameter,
422 output_path=output_path,
423 )
424 if output_path is None:
425 assert isinstance(output, Sample)
426 yield output
427 else:
428 assert isinstance(output, Mapping)
429 yield output