Coverage for src/bioimageio/core/stat_calculators.py: 93%
488 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 warnings
4from collections.abc import Callable, Collection, Iterable, Mapping, Sequence
5from copy import copy
6from functools import partial
7from itertools import product
8from typing import (
9 Any,
10 cast,
11)
13import dask.array as da
14import numpy as np
15import xarray as xr
16from dask.delayed import Delayed, delayed # pyright: ignore[reportUnknownVariableType]
17from numpy.typing import NDArray
18from typing_extensions import assert_never
20from bioimageio.spec.model.v0_5 import BATCH_AXIS_ID
22from ._op_base import Operator, get_relevant_preceding_ops
23from ._utils.statistics import compute_quantiles
24from .axis import AxisId
25from .common import MemberId, QuantileMethod
26from .sample import Sample
27from .stat_measures import (
28 AppliedOps,
29 DatasetMean,
30 DatasetMeasure,
31 DatasetMeasureBase,
32 DatasetQuantile,
33 DatasetStd,
34 DatasetVar,
35 Measure,
36 MeasureValue,
37 SampleMean,
38 SampleMeasure,
39 SampleMeasureBase,
40 SampleQuantile,
41 SampleStd,
42 SampleVar,
43)
44from .tensor import Tensor
46try:
47 import crick # pyright: ignore[reportMissingTypeStubs]
49except Exception:
50 crick = None
52 class TDigest:
53 def update(self, obj: Any):
54 pass
56 def quantile(self, q: Any) -> Any:
57 pass
59else:
60 TDigest = crick.TDigest # type: ignore
63def _dataset_preceding_ops(
64 member_id: MemberId,
65 sample: Sample,
66 previous: tuple[Operator, ...] | None,
67) -> tuple[Operator, ...]:
68 _ = sample.members[member_id]
69 preceding_ops = get_relevant_preceding_ops(member_id, sample.applied_ops)
70 if previous is not None and preceding_ops != previous:
71 raise ValueError(
72 f"Dataset samples have different applied_ops for member {member_id}"
73 )
74 return preceding_ops
77class MeanCalculator:
78 """Build lazy sample and dataset means."""
80 def __init__(self, member_id: MemberId, axes: Sequence[AxisId] | None):
81 super().__init__()
82 self._n: int = 0
83 self._mean: Tensor | None = None
84 self._axes = None if axes is None else tuple(axes)
85 self._member_id = member_id
86 self._preceding_ops: tuple[Operator, ...] | None = None
88 def compute(self, sample: Sample) -> dict[SampleMean, MeasureValue]:
89 return {
90 SampleMean(
91 member_id=self._member_id,
92 axes=self._axes,
93 preceding_ops=get_relevant_preceding_ops(
94 self._member_id, sample.applied_ops
95 ),
96 ): self._compute_impl(sample)
97 }
99 def _compute_impl(self, sample: Sample) -> Tensor:
100 tensor = sample.members[self._member_id].as_dask().astype("float64", copy=False)
101 return tensor.mean(dim=self._axes)
103 def update(self, sample: Sample) -> None:
104 _ = self._update(sample)
106 def compute_and_update(self, sample: Sample) -> dict[SampleMean, MeasureValue]:
107 mean = self._update(sample)
108 assert self._preceding_ops is not None
109 return {
110 SampleMean(
111 member_id=self._member_id,
112 axes=self._axes,
113 preceding_ops=self._preceding_ops,
114 ): mean
115 }
117 def _update(self, sample: Sample) -> Tensor:
118 preceding_ops = _dataset_preceding_ops(
119 self._member_id, sample, self._preceding_ops
120 )
121 mean = self._compute_impl(sample)
122 self._update_impl(sample.members[self._member_id], mean)
123 self._preceding_ops = preceding_ops
124 return mean
126 def _update_impl(self, tensor: Tensor, tensor_mean: Tensor):
127 assert tensor_mean.dtype == "float64"
128 # reduced voxel count
129 n_b = int(tensor.size / tensor_mean.size)
131 if self._mean is None:
132 assert self._n == 0
133 self._n = n_b
134 self._mean = tensor_mean
135 else:
136 assert self._n != 0
137 n_a = self._n
138 mean_old = self._mean
139 self._n = n_a + n_b
140 self._mean = (n_a * mean_old + n_b * tensor_mean) / self._n
141 assert self._mean.dtype == "float64"
143 def finalize(self) -> dict[DatasetMean, MeasureValue]:
144 if self._mean is None:
145 return {}
146 else:
147 assert self._preceding_ops is not None
148 return {
149 DatasetMean(
150 member_id=self._member_id,
151 axes=self._axes,
152 preceding_ops=self._preceding_ops,
153 ): self._mean
154 }
157class MeanVarStdCalculator:
158 """to calculate sample and dataset mean, variance or standard deviation"""
160 def __init__(self, member_id: MemberId, axes: Sequence[AxisId] | None):
161 super().__init__()
162 self._axes = None if axes is None else tuple(map(AxisId, axes))
163 self._member_id = member_id
164 self._preceding_ops: tuple[Operator, ...] | None = None
165 self._n: int = 0
166 self._mean: Tensor | None = None
167 self._m2: Tensor | None = None
169 def compute(
170 self, sample: Sample
171 ) -> dict[SampleMean | SampleVar | SampleStd, MeasureValue]:
172 tensor = sample.members[self._member_id].as_dask()
173 mean = tensor.mean(dim=self._axes)
174 c = (tensor - mean).data
175 if self._axes is None:
176 n = tensor.size
177 else:
178 n = int(np.prod([tensor.sizes[d] for d in self._axes]))
180 if xr.__version__.startswith("2023"): 180 ↛ 181line 180 didn't jump to line 181 because the condition on line 180 was never true
181 var = xr.dot(c, c, dims=self._axes) / n
182 else:
183 var = xr.dot(c, c, dim=self._axes) / n
185 assert isinstance(var, xr.DataArray)
186 std = np.sqrt(var)
187 assert isinstance(std, xr.DataArray)
188 preceding_ops = get_relevant_preceding_ops(self._member_id, sample.applied_ops)
189 return {
190 SampleMean(
191 axes=self._axes,
192 member_id=self._member_id,
193 preceding_ops=preceding_ops,
194 ): mean,
195 SampleVar(
196 axes=self._axes,
197 member_id=self._member_id,
198 preceding_ops=preceding_ops,
199 ): Tensor.from_xarray(var),
200 SampleStd(
201 axes=self._axes,
202 member_id=self._member_id,
203 preceding_ops=preceding_ops,
204 ): Tensor.from_xarray(std),
205 }
207 def update(self, sample: Sample):
208 if self._axes is not None and BATCH_AXIS_ID not in self._axes: 208 ↛ 209line 208 didn't jump to line 209 because the condition on line 208 was never true
209 return
211 preceding_ops = _dataset_preceding_ops(
212 self._member_id, sample, self._preceding_ops
213 )
214 tensor = sample.members[self._member_id].as_dask().astype("float64", copy=False)
215 mean_b = tensor.mean(dim=self._axes)
216 assert mean_b.dtype == "float64"
217 # reduced voxel count
218 n_b = int(tensor.size / mean_b.size)
219 m2_b = ((tensor - mean_b) ** 2).sum(dim=self._axes)
220 assert m2_b.dtype == "float64"
221 if self._mean is None:
222 assert self._m2 is None
223 self._n = n_b
224 self._mean = mean_b
225 self._m2 = m2_b
226 else:
227 n_a = self._n
228 mean_a = self._mean
229 m2_a = self._m2
230 self._n = n = n_a + n_b
231 self._mean = (n_a * mean_a + n_b * mean_b) / n
232 assert self._mean.dtype == "float64"
233 d = mean_b - mean_a
234 self._m2 = m2_a + m2_b + d**2 * n_a * n_b / n
235 assert self._m2.dtype == "float64"
237 self._preceding_ops = preceding_ops
239 def finalize(
240 self,
241 ) -> dict[DatasetMean | DatasetVar | DatasetStd, MeasureValue]:
242 if (
243 self._axes is not None
244 and BATCH_AXIS_ID not in self._axes
245 or self._mean is None
246 ):
247 return {}
248 else:
249 assert self._m2 is not None
250 assert self._preceding_ops is not None
251 var = self._m2 / self._n
252 sqrt = var**0.5
253 if isinstance(sqrt, (int, float)): 253 ↛ 255line 253 didn't jump to line 255 because the condition on line 253 was never true
254 # var and mean are scalar tensors, let's keep it consistent
255 sqrt = Tensor.from_xarray(xr.DataArray(sqrt))
257 assert isinstance(sqrt, Tensor), type(sqrt)
258 return {
259 DatasetMean(
260 member_id=self._member_id,
261 axes=self._axes,
262 preceding_ops=self._preceding_ops,
263 ): self._mean,
264 DatasetVar(
265 member_id=self._member_id,
266 axes=self._axes,
267 preceding_ops=self._preceding_ops,
268 ): var,
269 DatasetStd(
270 member_id=self._member_id,
271 axes=self._axes,
272 preceding_ops=self._preceding_ops,
273 ): sqrt,
274 }
277class SampleQuantilesCalculator:
278 """to calculate sample quantiles"""
280 def __init__(
281 self,
282 member_id: MemberId,
283 axes: Sequence[AxisId] | None,
284 qs: Collection[float],
285 method: QuantileMethod = "linear",
286 ):
287 super().__init__()
288 assert all(0.0 <= q <= 1.0 for q in qs)
289 self._qs = sorted(set(qs))
290 self._axes = None if axes is None else tuple(axes)
291 self._member_id = member_id
292 self._method: QuantileMethod = method
294 def compute(self, sample: Sample) -> dict[SampleQuantile, MeasureValue]:
295 ps = compute_quantiles(
296 sample.members[self._member_id], self._qs, self._axes, self._method
297 )
298 return {
299 SampleQuantile(
300 q=q,
301 axes=self._axes,
302 member_id=self._member_id,
303 method=self._method,
304 preceding_ops=get_relevant_preceding_ops(
305 self._member_id, sample.applied_ops
306 ),
307 ): p
308 for q, p in zip(self._qs, ps)
309 }
312class InMemoryDatasetQuantilesCalculator:
313 """to calculate dataset quantiles in memory for datasets that fit in memory."""
315 def __init__(
316 self,
317 member_id: MemberId,
318 axes: Sequence[AxisId] | None,
319 qs: Collection[float],
320 ):
321 super().__init__()
322 assert all(0.0 <= q <= 1.0 for q in qs)
323 self._qs = sorted(set(qs))
324 self._axes = None if axes is None else tuple(axes)
325 self._member_id = member_id
326 self._preceding_ops: tuple[Operator, ...] | None = None
327 self._samples: list[Tensor] = []
329 def update(self, sample: Sample):
330 preceding_ops = _dataset_preceding_ops(
331 self._member_id, sample, self._preceding_ops
332 )
333 self._samples.append(sample.members[self._member_id].as_dask())
334 self._preceding_ops = preceding_ops
336 def finalize(self) -> dict[DatasetQuantile, MeasureValue]:
337 if not self._samples:
338 return {}
340 assert self._preceding_ops is not None
341 dims = self._samples[0].dims
342 if BATCH_AXIS_ID in dims: 342 ↛ 348line 342 didn't jump to line 348 because the condition on line 342 was always true
343 combine = cast(
344 Callable[[Any], da.Array],
345 partial(da.concatenate, axis=dims.index(BATCH_AXIS_ID)),
346 )
347 else:
348 dims = (BATCH_AXIS_ID, *dims)
349 combine = cast(Callable[[Any], da.Array], da.stack)
351 dataset = Tensor(combine(s.data.data for s in self._samples), dims=dims)
353 if self._axes is not None and BATCH_AXIS_ID not in self._axes: 353 ↛ 354line 353 didn't jump to line 354 because the condition on line 353 was never true
354 axes = (BATCH_AXIS_ID, *self._axes)
355 else:
356 axes = self._axes
358 ps = compute_quantiles(dataset, self._qs, axes, "linear")
359 return {
360 DatasetQuantile(
361 q=q,
362 axes=self._axes,
363 member_id=self._member_id,
364 preceding_ops=self._preceding_ops,
365 ): p
366 for q, p in zip(self._qs, ps)
367 }
370class MeanQuantilesCalculator:
371 """to calculate dataset quantiles heuristically by averaging across samples
373 Note:
374 The returned dataset quantiles are an estiamte and **not mathematically correct**
375 """
377 def __init__(
378 self,
379 member_id: MemberId,
380 axes: Sequence[AxisId] | None,
381 qs: Collection[float],
382 ):
383 super().__init__()
384 assert all(0.0 <= q <= 1.0 for q in qs)
385 self._qs = sorted(set(qs))
386 self._axes = None if axes is None else tuple(axes)
387 self._member_id = member_id
388 self._preceding_ops: tuple[Operator, ...] | None = None
389 self._n: int = 0
390 self._estimates: Tensor | None = None
392 def update(self, sample: Sample):
393 preceding_ops = _dataset_preceding_ops(
394 self._member_id, sample, self._preceding_ops
395 )
396 tensor = sample.members[self._member_id]
397 sample_estimates = compute_quantiles(
398 tensor, self._qs, self._axes, "linear"
399 ).astype("float64", copy=False)
401 # reduced voxel count
402 n = int(tensor.size / np.prod(sample_estimates.shape_tuple[1:]))
404 if self._estimates is None:
405 assert self._n == 0
406 self._estimates = sample_estimates
407 else:
408 self._estimates = (self._n * self._estimates + n * sample_estimates) / (
409 self._n + n
410 )
411 assert self._estimates.dtype == "float64"
413 self._n += n
414 self._preceding_ops = preceding_ops
416 def finalize(self) -> dict[DatasetQuantile, MeasureValue]:
417 if self._estimates is None:
418 return {}
419 else:
420 assert self._preceding_ops is not None
421 warnings.warn(
422 "Computed dataset percentiles naively by averaging percentiles of samples."
423 )
424 return {
425 DatasetQuantile(
426 q=q,
427 axes=self._axes,
428 member_id=self._member_id,
429 preceding_ops=self._preceding_ops,
430 ): e
431 for q, e in zip(self._qs, self._estimates)
432 }
435def _update_crick_digests(
436 previous: list[TDigest] | None,
437 data: NDArray[Any],
438 remaining_shape: tuple[int, ...],
439) -> list[TDigest]:
440 assert crick is not None
441 # A new state keeps earlier results stable across updates and repeated computes.
442 digests = (
443 [copy(d) for d in previous]
444 if previous is not None
445 else [TDigest() for _ in range(int(np.prod(remaining_shape)))]
446 )
447 for digest, idx in zip(digests, product(*map(range, remaining_shape))):
448 digest.update(data[idx])
449 return digests
452def _get_crick_quantiles(
453 digests: list[TDigest], qs: tuple[float, ...], remaining_shape: tuple[int, ...]
454) -> NDArray[Any]:
455 return np.asarray([[d.quantile(q) for d in digests] for q in qs]).reshape(
456 (len(qs), *remaining_shape)
457 )
460class CrickQuantilesCalculator:
461 """to calculate dataset quantiles with the experimental [crick libray](https://github.com/dask/crick)"""
463 def __init__(
464 self,
465 member_id: MemberId,
466 axes: Sequence[AxisId] | None,
467 qs: Collection[float],
468 ):
469 warnings.warn("Computing dataset quantiles with experimental 'crick' library.")
470 super().__init__()
471 assert all(0.0 <= q <= 1.0 for q in qs)
472 assert axes is None or "_quantiles" not in axes
473 self._qs = sorted(set(qs))
474 self._axes = None if axes is None else tuple(axes)
475 self._member_id = member_id
476 self._preceding_ops: tuple[Operator, ...] | None = None
477 self._digest: Delayed | None = None
478 self._dims: tuple[AxisId, ...] | None = None
479 self._shape: tuple[int, ...] | None = None
481 def update(self, part: Sample):
482 preceding_ops = _dataset_preceding_ops(
483 self._member_id, part, self._preceding_ops
484 )
485 tensor = part.members[self._member_id].as_dask()
486 assert "_quantiles" not in tensor.dims
487 dims = tuple(
488 d for d in tensor.dims if self._axes is not None and d not in self._axes
489 )
490 if self._dims is not None and set(dims) == set(self._dims):
491 dims = self._dims
492 shape = tuple(tensor.sizes[d] for d in dims)
493 if self._dims is not None and (dims != self._dims or shape != self._shape):
494 raise ValueError("Dataset quantiles require matching unreduced dimensions.")
496 self._dims = dims
497 self._shape = shape
498 array = tensor.transpose((*dims, *(d for d in tensor.dims if d not in dims)))
499 data = array.data.data
500 assert isinstance(data, da.Array)
501 # Preserve upstream keys so statistics and preprocessing share input reads.
502 rechunked = cast(da.Array, data.rechunk(data.shape)) # pyright: ignore[reportArgumentType]
503 deferred_data = cast(
504 Delayed,
505 rechunked.to_delayed(optimize_graph=False).item(), # pyright: ignore[reportAttributeAccessIssue]
506 )
507 # shortcut: materializes one sample per task; use chunked digests for larger inputs.
508 self._digest = delayed(_update_crick_digests, pure=True)(
509 self._digest, deferred_data, shape
510 )
511 self._preceding_ops = preceding_ops
513 def finalize(self) -> dict[DatasetQuantile, MeasureValue]:
514 if self._digest is None:
515 return {}
516 else:
517 assert self._dims is not None
518 assert self._shape is not None
519 assert self._preceding_ops is not None
521 vs = cast(
522 da.Array,
523 da.from_delayed(
524 delayed(_get_crick_quantiles, pure=True)(
525 self._digest, tuple(self._qs), self._shape
526 ),
527 shape=(len(self._qs), *self._shape),
528 dtype="float64",
529 ),
530 )
531 return {
532 DatasetQuantile(
533 q=q,
534 axes=self._axes,
535 member_id=self._member_id,
536 preceding_ops=self._preceding_ops,
537 ): Tensor(cast(da.Array, vs[i]), dims=self._dims)
538 for i, q in enumerate(self._qs)
539 }
542if crick is None: 542 ↛ 543line 542 didn't jump to line 543 because the condition on line 542 was never true
543 DatasetQuantilesCalculator: type[
544 MeanQuantilesCalculator | CrickQuantilesCalculator
545 ] = MeanQuantilesCalculator
546else:
547 DatasetQuantilesCalculator = CrickQuantilesCalculator
550class NaiveSampleMeasureCalculator:
551 """wrapper for measures to match interface of other sample measure calculators"""
553 def __init__(self, member_id: MemberId, measure: SampleMeasure):
554 super().__init__()
555 self.tensor_name = member_id
556 self.measure = measure
558 def compute(self, sample: Sample) -> dict[SampleMeasure, MeasureValue]:
559 measure = self.measure.model_copy(
560 update={
561 "preceding_ops": get_relevant_preceding_ops(
562 self.measure.member_id, sample.applied_ops
563 )
564 }
565 )
566 return {measure: measure.compute(sample.as_dask())}
569SampleMeasureCalculator = (
570 MeanCalculator
571 | MeanVarStdCalculator
572 | SampleQuantilesCalculator
573 | NaiveSampleMeasureCalculator
574)
575DatasetMeasureCalculator = (
576 MeanCalculator
577 | MeanVarStdCalculator
578 | DatasetQuantilesCalculator
579 | InMemoryDatasetQuantilesCalculator
580)
583def _compute_measures_with_preprocessing(
584 measures: Iterable[Measure],
585 dataset: Sequence[Sample],
586 initial_dataset_measures: Mapping[DatasetMeasure, MeasureValue] | None = None,
587 *,
588 dataset_fits_in_memory: bool = False,
589) -> dict[Measure, MeasureValue]:
590 """Compute measures on the outputs of their preceding processing steps."""
591 requested = tuple(measures)
592 if not requested: 592 ↛ 593line 592 didn't jump to line 593 because the condition on line 592 was never true
593 return {}
594 elif not dataset: 594 ↛ 595line 594 didn't jump to line 595 because the condition on line 594 was never true
595 raise ValueError("empty dataset")
597 dataset_measures = dict(initial_dataset_measures or {})
598 sample_measures: list[dict[SampleMeasure, MeasureValue]] = [{} for _ in dataset]
599 processed_samples: dict[tuple[int, AppliedOps], Sample] = {}
600 active: set[tuple[int | None, Measure]] = set()
602 def apply_preceding_ops(measure: Measure, sample_index: int) -> Sample:
603 cache_key = (sample_index, measure.preceding_ops)
604 cached = processed_samples.get(cache_key)
605 if cached is not None:
606 return cached
608 sample = dataset[sample_index].copy(deep=False)
609 sample.stat = dict(sample.stat)
610 already_applied = get_relevant_preceding_ops(
611 measure.member_id, sample.applied_ops
612 )
613 if measure.preceding_ops[: len(already_applied)] != already_applied:
614 raise ValueError(
615 f"Sample applied_ops do not match the requested measure: {measure}"
616 )
617 for proc in measure.preceding_ops[len(already_applied) :]:
618 for required in proc.get_required_measures():
619 if required in sample.stat: 619 ↛ 620line 619 didn't jump to line 620 because the condition on line 619 was never true
620 continue
621 if isinstance(required, DatasetMeasureBase):
622 sample.stat[required] = get_dataset_value(required)
623 else:
624 sample.stat[required] = get_sample_value(required, sample_index)
626 proc(sample)
628 processed_samples[cache_key] = sample
629 return sample
631 def get_dataset_value(measure: DatasetMeasure) -> MeasureValue:
632 cached = dataset_measures.get(measure)
633 if cached is not None:
634 return cached
636 active_key = (None, measure)
637 if active_key in active: 637 ↛ 638line 637 didn't jump to line 638 because the condition on line 637 was never true
638 raise ValueError(f"Cyclic processing dependency for {measure}")
640 active.add(active_key)
641 try:
642 transformed = [apply_preceding_ops(measure, i) for i in range(len(dataset))]
643 sample_calculators, dataset_calculators = get_measure_calculators(
644 [measure], datast_fits_in_memory=dataset_fits_in_memory
645 )
646 assert not sample_calculators
647 for sample in transformed:
648 for calculator in dataset_calculators:
649 calculator.update(sample)
651 values: dict[DatasetMeasure, MeasureValue] = {}
652 for calculator in dataset_calculators:
653 values.update(calculator.finalize().items())
655 value = values[measure]
656 dataset_measures[measure] = value
657 return value
658 finally:
659 active.remove(active_key)
661 def get_sample_value(measure: SampleMeasure, sample_index: int) -> MeasureValue:
662 cached = sample_measures[sample_index].get(measure)
663 if cached is not None: 663 ↛ 664line 663 didn't jump to line 664 because the condition on line 663 was never true
664 return cached
666 active_key = (sample_index, measure)
667 if active_key in active: 667 ↛ 668line 667 didn't jump to line 668 because the condition on line 667 was never true
668 raise ValueError(f"Cyclic processing dependency for {measure}")
670 active.add(active_key)
671 try:
672 transformed = apply_preceding_ops(measure, sample_index)
673 sample_calculators, dataset_calculators = get_measure_calculators([measure])
674 assert not dataset_calculators
675 values: dict[SampleMeasure, MeasureValue] = {}
676 for calculator in sample_calculators:
677 values.update(calculator.compute(transformed).items())
678 value = values[measure]
679 sample_measures[sample_index][measure] = value
680 return value
681 finally:
682 active.remove(active_key)
684 ret: dict[Measure, MeasureValue] = {}
685 for measure in requested:
686 if isinstance(measure, DatasetMeasureBase): 686 ↛ 689line 686 didn't jump to line 689 because the condition on line 686 was always true
687 ret[measure] = get_dataset_value(measure)
688 else:
689 ret[measure] = get_sample_value(measure, len(dataset) - 1)
691 return ret
694def _check_sample_applied_ops(measures: Iterable[Measure], sample: Sample) -> None:
695 mismatched = [
696 measure
697 for measure in measures
698 if measure.preceding_ops
699 != get_relevant_preceding_ops(measure.member_id, sample.applied_ops)
700 ]
701 if mismatched:
702 raise ValueError(
703 "Requested measures do not match the sample's applied_ops: "
704 + f"{mismatched}"
705 )
708class StatsCalculator:
709 """Build lazy statistics from samples that have already been processed.
711 Measures retain their full preprocessing provenance.
712 The calculator does not execute preprocessing. Each measure's operations must
713 match the relevant operations recorded on each sample.
714 """
716 def __init__(
717 self,
718 measures: Collection[Measure],
719 initial_dataset_measures: Mapping[DatasetMeasure, MeasureValue] | None = None,
720 *,
721 dataset_fits_in_memory: bool = False,
722 ):
723 """Create a calculator for measures on already-processed samples."""
724 super().__init__()
725 self._measures = tuple(measures)
726 self._dataset_fits_in_memory = dataset_fits_in_memory
727 self._sample_measures = {
728 measure
729 for measure in self._measures
730 if isinstance(measure, SampleMeasureBase)
731 }
732 self._dataset_measures = {
733 measure
734 for measure in self._measures
735 if isinstance(measure, DatasetMeasureBase)
736 }
737 self._sample_calculators, self._dataset_calculators = get_measure_calculators(
738 self._measures, datast_fits_in_memory=dataset_fits_in_memory
739 )
740 self.sample_count = 0
741 self._current_dataset_measures = dict(initial_dataset_measures or {})
743 @property
744 def measures(self) -> tuple[Measure, ...]:
745 """Measures configured for this calculator."""
746 return self._measures
748 @property
749 def dataset_fits_in_memory(self) -> bool:
750 """Whether dataset quantiles use the in-memory algorithm."""
751 return self._dataset_fits_in_memory
753 @property
754 def has_dataset_measures(self):
755 return bool(self._current_dataset_measures) and all(
756 measure in self._current_dataset_measures
757 for measure in self._dataset_measures
758 )
760 def update(
761 self,
762 sample: Sample | Iterable[Sample],
763 ) -> None:
764 """Update with samples that have already been processed."""
765 _ = self._update(sample)
767 def finalize(self) -> dict[DatasetMeasure, MeasureValue]:
768 """Return lazy aggregated statistics for the samples registered so far."""
769 if not self._dataset_measures.issubset(self._current_dataset_measures):
770 for calc in self._dataset_calculators:
771 for computed_measure, value in calc.finalize().items():
772 if computed_measure in self._dataset_measures:
773 _ = self._current_dataset_measures.setdefault(
774 computed_measure, value
775 )
777 return dict(self._current_dataset_measures)
779 def update_and_get_all(
780 self,
781 sample: Sample | Iterable[Sample],
782 ) -> dict[Measure, MeasureValue]:
783 """Returns sample as well as updated dataset statistics"""
784 last_sample = self._update(sample)
785 if last_sample is None: 785 ↛ 786line 785 didn't jump to line 786 because the condition on line 785 was never true
786 raise ValueError("`sample` was not a `Sample`, nor did it yield any.")
788 return {**self._compute(last_sample), **self.finalize()}
790 def skip_update_and_get_all(self, sample: Sample) -> dict[Measure, MeasureValue]:
791 """Returns sample as well as previously computed dataset statistics"""
792 _check_sample_applied_ops(self._measures, sample)
793 return {**self._compute(sample), **self.finalize()}
795 def _compute(self, sample: Sample) -> dict[SampleMeasure, MeasureValue]:
796 ret: dict[SampleMeasure, MeasureValue] = {}
797 for calc in self._sample_calculators:
798 for measure, value in calc.compute(sample).items():
799 if measure in self._sample_measures:
800 ret[measure] = value
801 return ret
803 def _update(self, sample: Sample | Iterable[Sample]) -> Sample | None:
804 samples = [sample] if isinstance(sample, Sample) else sample
805 last_sample = None
806 for el in samples:
807 _check_sample_applied_ops(self._measures, el)
808 if last_sample is None: 808 ↛ 810line 808 didn't jump to line 810 because the condition on line 808 was always true
809 self.sample_count += 1
810 last_sample = el
811 for measure in self._dataset_measures:
812 _ = self._current_dataset_measures.pop(measure, None)
813 for calc in self._dataset_calculators:
814 calc.update(el)
815 return last_sample
818def get_measure_calculators(
819 required_measures: Iterable[Measure], *, datast_fits_in_memory: bool = False
820) -> tuple[list[SampleMeasureCalculator], list[DatasetMeasureCalculator]]:
821 """Create calculators that derive provenance from their input samples."""
823 sample_calculators: list[SampleMeasureCalculator] = []
824 dataset_calculators: list[DatasetMeasureCalculator] = []
826 # split required measures into groups
827 required_sample_means: set[tuple[MemberId, tuple[AxisId, ...] | None]] = set()
828 required_dataset_means: set[tuple[MemberId, tuple[AxisId, ...] | None]] = set()
829 required_sample_mean_var_std: set[tuple[MemberId, tuple[AxisId, ...] | None]] = (
830 set()
831 )
832 required_dataset_mean_var_std: set[tuple[MemberId, tuple[AxisId, ...] | None]] = (
833 set()
834 )
835 required_sample_quantiles: dict[
836 tuple[MemberId, tuple[AxisId, ...] | None, QuantileMethod],
837 set[float],
838 ] = {}
839 required_dataset_quantiles: dict[
840 tuple[MemberId, tuple[AxisId, ...] | None], set[float]
841 ] = {}
843 for rm in required_measures:
844 if isinstance(rm, SampleMean):
845 required_sample_means.add((rm.member_id, rm.axes))
846 elif isinstance(rm, DatasetMean):
847 required_dataset_means.add((rm.member_id, rm.axes))
848 elif isinstance(rm, (SampleVar, SampleStd)):
849 required_sample_mean_var_std.add((rm.member_id, rm.axes))
850 elif isinstance(rm, (DatasetVar, DatasetStd)):
851 required_dataset_mean_var_std.add((rm.member_id, rm.axes))
852 elif isinstance(rm, SampleQuantile):
853 required_sample_quantiles.setdefault(
854 (rm.member_id, rm.axes, rm.method), set()
855 ).add(rm.q)
856 elif isinstance(rm, DatasetQuantile):
857 required_dataset_quantiles.setdefault((rm.member_id, rm.axes), set()).add(
858 rm.q
859 )
860 else:
861 assert_never(rm)
863 for tid, axes in required_sample_means:
864 if (tid, axes) in required_sample_mean_var_std:
865 # computed togehter with var and std
866 continue
868 sample_calculators.append(MeanCalculator(member_id=tid, axes=axes))
870 for tid, axes in required_sample_mean_var_std:
871 sample_calculators.append(MeanVarStdCalculator(member_id=tid, axes=axes))
873 for tid, axes in required_dataset_means:
874 if (tid, axes) in required_dataset_mean_var_std:
875 # computed togehter with var and std
876 continue
878 dataset_calculators.append(MeanCalculator(member_id=tid, axes=axes))
880 for tid, axes in required_dataset_mean_var_std:
881 dataset_calculators.append(MeanVarStdCalculator(member_id=tid, axes=axes))
883 for (tid, axes, m), qs in required_sample_quantiles.items():
884 sample_calculators.append(
885 SampleQuantilesCalculator(member_id=tid, axes=axes, qs=qs, method=m)
886 )
888 DQCalc = (
889 InMemoryDatasetQuantilesCalculator
890 if datast_fits_in_memory
891 else DatasetQuantilesCalculator
892 )
893 for (tid, axes), qs in required_dataset_quantiles.items():
894 dataset_calculators.append(DQCalc(member_id=tid, axes=axes, qs=qs))
896 return sample_calculators, dataset_calculators
899def compute_dataset_measures(
900 measures: Iterable[DatasetMeasure],
901 dataset: Iterable[Sample],
902 *,
903 dataset_fits_in_memory: bool = False,
904 initial_dataset_measures: Mapping[DatasetMeasure, MeasureValue] | None = None,
905) -> dict[DatasetMeasure, MeasureValue]:
906 """Build lazy dataset measures, including any preprocessing dependencies.
908 ``initial_dataset_measures`` supplies known statistics used by preprocessing.
909 """
910 measures = tuple(measures)
911 if any(m.preceding_ops for m in measures):
912 return cast(
913 dict[DatasetMeasure, MeasureValue],
914 _compute_measures_with_preprocessing(
915 measures,
916 list(dataset),
917 initial_dataset_measures,
918 dataset_fits_in_memory=dataset_fits_in_memory,
919 ),
920 )
922 sample_calculators, calculators = get_measure_calculators(
923 measures, datast_fits_in_memory=dataset_fits_in_memory
924 )
925 assert not sample_calculators
927 ret: dict[DatasetMeasure, MeasureValue] = {}
929 for sample in dataset:
930 _check_sample_applied_ops(measures, sample)
931 for calc in calculators:
932 calc.update(sample)
934 for calc in calculators:
935 ret.update(calc.finalize().items())
937 return ret
940def compute_sample_measures(
941 measures: Iterable[SampleMeasure], sample: Sample
942) -> dict[SampleMeasure, MeasureValue]:
943 """Build lazy sample measures; convert the returned tensors to NumPy to evaluate."""
944 measures = tuple(measures)
945 if any(m.preceding_ops for m in measures): 945 ↛ 946line 945 didn't jump to line 946 because the condition on line 945 was never true
946 return cast(
947 dict[SampleMeasure, MeasureValue],
948 _compute_measures_with_preprocessing(measures, [sample]),
949 )
951 _check_sample_applied_ops(measures, sample)
952 calculators, dataset_calculators = get_measure_calculators(measures)
953 assert not dataset_calculators
954 ret: dict[SampleMeasure, MeasureValue] = {}
956 for calc in calculators:
957 ret.update(calc.compute(sample).items())
959 return ret
962def compute_measures(
963 measures: Iterable[Measure], dataset: Iterable[Sample]
964) -> dict[Measure, MeasureValue]:
965 """Build lazy measures for the dataset and its last sample.
967 The dataset iterable is consumed without evaluating tensor data.
968 """
969 measures = tuple(measures)
970 if any(m.preceding_ops for m in measures): 970 ↛ 971line 970 didn't jump to line 971 because the condition on line 970 was never true
971 return _compute_measures_with_preprocessing(measures, list(dataset))
973 sample_calculators, dataset_calculators = get_measure_calculators(measures)
974 ret: dict[Measure, MeasureValue] = {}
975 sample = None
976 for sample in dataset:
977 _check_sample_applied_ops(measures, sample)
978 for calc in dataset_calculators:
979 calc.update(sample)
980 if sample is None: 980 ↛ 981line 980 didn't jump to line 981 because the condition on line 980 was never true
981 raise ValueError("empty dataset")
983 for calc in dataset_calculators:
984 ret.update(calc.finalize().items())
986 for calc in sample_calculators:
987 ret.update(calc.compute(sample).items())
989 return ret