Coverage for src/bioimageio/core/stat_measures.py: 98%

108 statements  

« prev     ^ index     » next       coverage.py v7.17.3, created at 2026-11-20 09:46 +0000

1from __future__ import annotations 

2 

3from abc import ABC, abstractmethod 

4from collections.abc import Mapping 

5from typing import ( 

6 Annotated, 

7 Any, 

8 Literal, 

9 Protocol, 

10 TypeAlias, 

11 cast, 

12) 

13 

14import numpy as np 

15from pydantic import ( 

16 BaseModel, 

17 BeforeValidator, 

18 ConfigDict, 

19 Discriminator, 

20 PlainSerializer, 

21) 

22 

23from ._op_base import Operator 

24from .axis import AxisId 

25from .common import MemberId, PerMember, QuantileMethod 

26from .tensor import Tensor 

27 

28 

29def tensor_custom_before_validator(data: Tensor | Mapping[str, Any]): 

30 if isinstance(data, Tensor): 

31 return data 

32 

33 # custom before validation logic 

34 return Tensor(np.asarray(data["data"]), dims=data["dims"]) 

35 

36 

37def tensor_custom_serializer(t: Tensor) -> dict[str, Any]: 

38 # Serialization explicitly evaluates lazy statistics. 

39 return {"data": t.data.to_numpy().tolist(), "dims": list(map(str, t.dims))} 

40 

41 

42MeasureValue: TypeAlias = ( 

43 float 

44 | Annotated[ 

45 Tensor, 

46 BeforeValidator(tensor_custom_before_validator), 

47 PlainSerializer(tensor_custom_serializer), 

48 ] 

49) 

50 

51 

52def _validate_applied_ops(value: Any) -> tuple[Operator, ...]: 

53 if not isinstance(value, (list, tuple)): 53 ↛ 54line 53 didn't jump to line 54 because the condition on line 53 was never true

54 raise TypeError("applied_ops must be a sequence") 

55 

56 values = cast(list[Any] | tuple[Any, ...], value) 

57 if all(isinstance(op, Operator) for op in values): 

58 return cast(tuple[Operator, ...], tuple(values)) 

59 

60 from .proc_ops import deserialize_processing 

61 

62 return tuple(deserialize_processing(cast(Mapping[str, Any], op)) for op in values) 

63 

64 

65def _serialize_applied_ops(ops: tuple[Operator, ...]) -> list[dict[str, Any]]: 

66 from .proc_ops import serialize_processing 

67 

68 return [serialize_processing(op) for op in ops] 

69 

70 

71AppliedOps: TypeAlias = Annotated[ 

72 tuple[Operator, ...], 

73 BeforeValidator(_validate_applied_ops), 

74 PlainSerializer(_serialize_applied_ops), 

75] 

76 

77 

78# using Sample Protocol really only to avoid circular imports 

79class SampleLike(Protocol): 

80 @property 

81 def members(self) -> PerMember[Tensor]: ... 

82 

83 

84class MeasureBase(BaseModel, frozen=True): 

85 model_config = ConfigDict(extra="forbid") 

86 

87 member_id: MemberId 

88 preceding_ops: AppliedOps = () 

89 

90 

91class SampleMeasureBase(MeasureBase, ABC, frozen=True): 

92 scope: Literal["sample"] = "sample" 

93 

94 @abstractmethod 

95 def compute(self, sample: SampleLike) -> MeasureValue: 

96 """Compute eagerly for NumPy inputs and lazily for Dask inputs.""" 

97 ... 

98 

99 

100class DatasetMeasureBase(MeasureBase, ABC, frozen=True): 

101 scope: Literal["dataset"] = "dataset" 

102 

103 

104class _Mean(BaseModel, frozen=True): 

105 name: Literal["mean"] = "mean" 

106 axes: tuple[AxisId, ...] | None = None 

107 """`axes` to reduce""" 

108 

109 

110class SampleMean(_Mean, SampleMeasureBase, frozen=True): 

111 """The mean value of a single tensor""" 

112 

113 def compute(self, sample: SampleLike) -> MeasureValue: 

114 tensor = sample.members[self.member_id] 

115 return tensor.mean(dim=self.axes) 

116 

117 def model_post_init(self, __context: Any, /): 

118 assert self.axes is None or AxisId("batch") not in self.axes 

119 

120 

121class DatasetMean(_Mean, DatasetMeasureBase, frozen=True): 

122 """The mean value across multiple samples""" 

123 

124 def model_post_init(self, __context: Any, /): 

125 assert self.axes is None or AxisId("batch") in self.axes 

126 

127 

128class _Std(BaseModel, frozen=True): 

129 name: Literal["std"] = "std" 

130 axes: tuple[AxisId, ...] | None = None 

131 """`axes` to reduce""" 

132 

133 

134class SampleStd(_Std, SampleMeasureBase, frozen=True): 

135 """The standard deviation of a single tensor""" 

136 

137 def compute(self, sample: SampleLike) -> MeasureValue: 

138 tensor = sample.members[self.member_id] 

139 return tensor.std(dim=self.axes) 

140 

141 def model_post_init(self, __context: Any, /): 

142 assert self.axes is None or AxisId("batch") not in self.axes 

143 

144 

145class DatasetStd(_Std, DatasetMeasureBase, frozen=True): 

146 """The standard deviation across multiple samples""" 

147 

148 def model_post_init(self, __context: Any, /): 

149 assert self.axes is None or AxisId("batch") in self.axes 

150 

151 

152class _Var(BaseModel, frozen=True): 

153 name: Literal["var"] = "var" 

154 axes: tuple[AxisId, ...] | None = None 

155 """`axes` to reduce""" 

156 

157 

158class SampleVar(_Var, SampleMeasureBase, frozen=True): 

159 """The variance of a single tensor""" 

160 

161 def compute(self, sample: SampleLike) -> MeasureValue: 

162 tensor = sample.members[self.member_id] 

163 return tensor.var(dim=self.axes) 

164 

165 def model_post_init(self, __context: Any, /): 

166 assert self.axes is None or AxisId("batch") not in self.axes 

167 

168 

169class DatasetVar(_Var, DatasetMeasureBase, frozen=True): 

170 """The variance across multiple samples""" 

171 

172 def model_post_init(self, __context: Any, /): # TODO: turn into @model_validator 

173 assert self.axes is None or AxisId("batch") in self.axes 

174 

175 

176class _Quantile(BaseModel, frozen=True): 

177 name: Literal["quantile"] = "quantile" 

178 q: float 

179 axes: tuple[AxisId, ...] | None = None 

180 """`axes` to reduce""" 

181 

182 def model_post_init(self, __context: Any, /): 

183 assert self.q >= 0.0 

184 assert self.q <= 1.0 

185 

186 

187class SampleQuantile(_Quantile, SampleMeasureBase, frozen=True): 

188 """The `q`th quantile of a single tensor""" 

189 

190 method: QuantileMethod = "linear" 

191 """Method to use when the desired quantile lies between two data points. 

192 See https://numpy.org/devdocs/reference/generated/numpy.quantile.html#numpy-quantile for details.""" 

193 

194 def compute(self, sample: SampleLike) -> MeasureValue: 

195 tensor = sample.members[self.member_id] 

196 return tensor.quantile(self.q, dim=self.axes, method=self.method) 

197 

198 def model_post_init(self, __context: Any, /): 

199 super().model_post_init(__context) 

200 assert self.axes is None or AxisId("batch") not in self.axes 

201 

202 

203class DatasetQuantile(_Quantile, DatasetMeasureBase, frozen=True): 

204 """The `q`th quantile across multiple samples""" 

205 

206 def model_post_init(self, __context: Any, /): 

207 super().model_post_init(__context) 

208 assert self.axes is None or AxisId("batch") in self.axes 

209 

210 

211SampleMeasure: TypeAlias = Annotated[ 

212 SampleMean | SampleStd | SampleVar | SampleQuantile, Discriminator("name") 

213] 

214DatasetMeasure: TypeAlias = Annotated[ 

215 DatasetMean | DatasetStd | DatasetVar | DatasetQuantile, Discriminator("name") 

216] 

217Measure: TypeAlias = Annotated[SampleMeasure | DatasetMeasure, Discriminator("scope")] 

218Stat: TypeAlias = dict[Measure, MeasureValue] 

219 

220MeanMeasure: TypeAlias = SampleMean | DatasetMean 

221StdMeasure: TypeAlias = SampleStd | DatasetStd 

222VarMeasure: TypeAlias = SampleVar | DatasetVar 

223PercentileMeasure: TypeAlias = SampleQuantile | DatasetQuantile