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

1from __future__ import annotations 

2 

3import collections.abc 

4import copy 

5from collections.abc import Mapping, Sequence 

6from dataclasses import dataclass 

7from typing import ( 

8 TYPE_CHECKING, 

9 Literal, 

10) 

11 

12import xarray as xr 

13from loguru import logger 

14from typing_extensions import Self, assert_never 

15 

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 

28 

29if TYPE_CHECKING: 

30 from ._op_base import Operator 

31 

32 

33@dataclass 

34class Sample: 

35 """A dataset sample. 

36 

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 """ 

42 

43 id: SampleId 

44 """Identifies the `Sample` within the dataset -- typically a number or a string.""" 

45 

46 members: dict[MemberId, Tensor] 

47 """The sample's tensors""" 

48 

49 stat: Stat 

50 """Sample and dataset statistics""" 

51 

52 applied_ops: tuple[Operator, ...] = () 

53 """Operators applied to this sample, in order. 

54 

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 """ 

60 

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 ) 

80 

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 ) 

91 

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) 

97 

98 @property 

99 def shape(self) -> PerMember[PerAxis[int]]: 

100 return {tid: t.sizes for tid, t in self.members.items()} 

101 

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 ) 

113 

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 ) 

125 

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 

138 

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 ) 

151 

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. 

159 

160 Args: 

161 errors: Whether to raise an error if a member does not have a batch multi-index. Default is "raise". 

162 

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) 

182 

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 ) 

207 

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 ) 

220 

221 def copy(self, deep: bool = False) -> Self: 

222 """Return a copy of the sample. 

223 

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 

231 

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 )