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

1from __future__ import annotations 

2 

3import atexit 

4import itertools 

5from collections.abc import Hashable, Iterable, Iterator, Mapping, Sequence, Sized 

6from pathlib import Path 

7from typing import overload 

8 

9import dask.array as da 

10from loguru import logger 

11from tqdm import tqdm 

12 

13from bioimageio.spec import load_description 

14from bioimageio.spec.common import PermissiveFileSource 

15from bioimageio.spec.model import v0_4, v0_5 

16 

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 

25 

26 

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: ... 

43 

44 

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]: ... 

61 

62 

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]: ... 

79 

80 

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 

97 

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. 

128 

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 ) 

159 

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 

173 

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 

183 

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 ) 

196 

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 } 

209 

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) 

220 

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 

238 

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 ) 

246 

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 ) 

272 

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) 

280 

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 

298 

299 pp.apply_postprocessing(output) 

300 pp.apply_output_cropping(output) 

301 

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() 

311 

312 

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]]: ... 

327 

328 

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]: ... 

343 

344 

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 

359 

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 

373 

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 ) 

384 

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 

393 

394 pp = create_prediction_pipeline( 

395 model, 

396 keep_updating_initial_dataset_statistics=False, 

397 dataset_for_initial_statistics=inputs, 

398 ) 

399 

400 if isinstance(sample_id, str): 

401 if "{i}" not in sample_id and "{i:" not in sample_id: 

402 sample_id += "{i:03}" 

403 

404 sample_ids = itertools.repeat(sample_id) 

405 else: 

406 sample_ids = sample_id 

407 

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 ) 

415 

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