Coverage for src/bioimageio/core/sample.py: 78%
62 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 collections.abc
4import copy
5from collections.abc import Mapping, Sequence
6from dataclasses import dataclass
7from typing import (
8 TYPE_CHECKING,
9 Literal,
10)
12import xarray as xr
13from loguru import logger
14from typing_extensions import Self, assert_never
16from ._utils.resolve_per_member_key import resolve_per_member_var
17from .axis import AxisId, PerAxis
18from .common import (
19 MemberId,
20 PadMode,
21 PadWidthLike,
22 PerMember,
23 SampleId,
24 SliceInfo,
25)
26from .stat_measures import Stat
27from .tensor import Tensor
29if TYPE_CHECKING:
30 from ._op_base import Operator
33@dataclass
34class Sample:
35 """A dataset sample.
37 A `Sample` has `members`, which allows to combine multiple tensors into a single
38 sample.
39 For example a `Sample` from a dataset with masked images may contain a
40 `MemberId("raw")` and `MemberId("mask")` image.
41 """
43 id: SampleId
44 """Identifies the `Sample` within the dataset -- typically a number or a string."""
46 members: dict[MemberId, Tensor]
47 """The sample's tensors"""
49 stat: Stat
50 """Sample and dataset statistics"""
52 applied_ops: tuple[Operator, ...] = ()
53 """Operators applied to this sample, in order.
55 Notes:
56 - Any direct modifications of member tensors or the sample's stats are not recorded here.
57 - Serialized statistics updaters retain their configuration but not calculator state;
58 restored updaters are references and cannot be called.
59 """
61 def __getitem__(
62 self,
63 key: PerMember[PerAxis[SliceInfo | slice | int] | Tensor | xr.DataArray]
64 | PerAxis[SliceInfo | slice | int]
65 | Tensor
66 | xr.DataArray,
67 ) -> Self:
68 per_member_key = resolve_per_member_var(
69 key,
70 valid_per_member_types=(
71 SliceInfo,
72 slice,
73 int,
74 Tensor,
75 xr.DataArray,
76 ),
77 valid_per_axis_types=(SliceInfo, slice, int),
78 members=self.members,
79 )
81 return self.__class__(
82 members={
83 m: t[per_member_key[m]]
84 for m, t in self.members.items()
85 if m in per_member_key
86 },
87 stat=self.stat,
88 id=self.id,
89 applied_ops=self.applied_ops,
90 )
92 def __postinit__(self):
93 # default tensor names to member ids
94 for m, t in self.members.items():
95 if t.name is None:
96 t.name = str(m)
98 @property
99 def shape(self) -> PerMember[PerAxis[int]]:
100 return {tid: t.sizes for tid, t in self.members.items()}
102 def as_numpy(self) -> Self:
103 """Return sample as a new sample with all members converted to numpy arrays."""
104 return self.__class__(
105 members={m: t.as_numpy() for m, t in self.members.items()},
106 stat={
107 k: v.as_numpy() if isinstance(v, Tensor) else v
108 for k, v in self.stat.items()
109 },
110 id=self.id,
111 applied_ops=self.applied_ops,
112 )
114 def as_dask(self) -> Self:
115 """Return sample as a new sample with all members converted to dask arrays."""
116 return self.__class__(
117 members={m: t.as_dask() for m, t in self.members.items()},
118 stat={
119 k: v.as_dask() if isinstance(v, Tensor) else v
120 for k, v in self.stat.items()
121 },
122 id=self.id,
123 applied_ops=self.applied_ops,
124 )
126 def pad(
127 self,
128 pad_width: PerMember[PerAxis[int | PadWidthLike]],
129 mode: PerMember[PadMode] | PadMode,
130 ) -> Self:
131 """Convenience method to pad sample members."""
132 default_mode = "symmetric"
133 if isinstance(mode, collections.abc.Mapping):
134 mode_per_member = mode
135 else:
136 mode_per_member: Mapping[MemberId, PadMode] = {}
137 default_mode = mode
139 return self.__class__(
140 members={
141 m: t.pad(
142 pad_width=pad_width.get(m, {}),
143 mode=mode_per_member.get(m, default_mode),
144 )
145 for m, t in self.members.items()
146 },
147 stat=self.stat,
148 id=self.id,
149 applied_ops=self.applied_ops,
150 )
152 def unstack_batch_multi_index(
153 self,
154 *,
155 errors: Literal["raise", "warn", "ignore"] = "raise",
156 unstacked_dim_order: PerMember[Sequence[AxisId]] | None = None,
157 ) -> Self:
158 """Unstack the batch multi-index of all sample members.
160 Args:
161 errors: Whether to raise an error if a member does not have a batch multi-index. Default is "raise".
163 Returns:
164 A new `Sample` with unstacked batch multi-index for all members.
165 """
166 if ( 166 ↛ 175line 166 didn't jump to line 175 because the condition on line 166 was never true
167 len(
168 no_batch := [
169 m for m, t in self.members.items() if AxisId("batch") not in t.dims
170 ]
171 )
172 == len(self.members)
173 and errors != "ignore"
174 ):
175 error_msg = f"No member has a batch dimension: {no_batch}"
176 if errors == "raise":
177 raise ValueError(error_msg)
178 elif errors == "warn":
179 logger.warning(error_msg)
180 else:
181 assert_never(errors)
183 members = {
184 m: t
185 if AxisId("batch") not in t.dims
186 else t.unstack_batch_multi_index(
187 errors=errors,
188 unstacked_dim_order=unstacked_dim_order[m]
189 if unstacked_dim_order is not None
190 else None,
191 )
192 for m, t in self.members.items()
193 }
194 if ( 194 ↛ 204line 194 didn't jump to line 204 because the condition on line 194 was never true
195 len(
196 batch_lengths := {
197 t.sizes.get(AxisId("batch"))
198 for t in members.values()
199 if AxisId("batch") in t.dims
200 }
201 )
202 > 1
203 ):
204 raise ValueError(
205 f"Different batch lengths after unstacking: {batch_lengths}"
206 )
208 stat: Stat = { # TODO: update stat calculations to maintain any multi-index batch index.
209 k: v.unstack_batch_multi_index(errors="ignore", unstacked_dim_order=None)
210 if isinstance(v, Tensor)
211 else float(v)
212 for k, v in self.stat.items()
213 }
214 return self.__class__(
215 members=members,
216 stat=stat,
217 id=self.id,
218 applied_ops=self.applied_ops,
219 )
221 def copy(self, deep: bool = False) -> Self:
222 """Return a copy of the sample.
224 Args:
225 deep: Whether to perform a deep copy of the members and stat.
226 """
227 if deep:
228 cp = copy.deepcopy
229 else:
230 cp = copy.copy
232 return self.__class__(
233 members=cp(self.members),
234 stat=cp(self.stat),
235 id=self.id,
236 applied_ops=self.applied_ops,
237 )