Coverage for src/CSET/operators/misc.py: 100%

1# Copyright 2022 Met Office and contributors. 

2# 

3# Licensed under the Apache License, Version 2.0 (the "License"); 

4# you may not use this file except in compliance with the License. 

5# You may obtain a copy of the License at 

6# 

7# http://www.apache.org/licenses/LICENSE-2.0 

8# 

9# Unless required by applicable law or agreed to in writing, software 

10# distributed under the License is distributed on an "AS IS" BASIS, 

11# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 

12# See the License for the specific language governing permissions and 

13# limitations under the License. 

14 

15"""Miscellaneous operators.""" 

16 

17from collections.abc import Iterable 

18from typing import Union 

19 

20from iris.cube import Cube, CubeList 

21 

22from CSET._common import iter_maybe 

23 

24 

25def noop(x, **kwargs): 

26 """Return its input without doing anything to it. 

27 

28 Useful for constructing diagnostic chains. 

29 

30 Arguments 

31 --------- 

32 x: Any 

33 Input to return. 

34 

35 Returns 

36 ------- 

37 x: Any 

38 The input that was given. 

39 """ 

40 return x 

41 

42 

43def remove_attribute( 

44 cubes: Union[Cube, CubeList], attribute: Union[str, Iterable], **kwargs 

45) -> CubeList: 

46 """Remove a cube attribute. 

47 

48 If the attribute is not on the cube, the cube is passed through unchanged. 

49 

50 Arguments 

51 --------- 

52 cubes: Cube | CubeList 

53 One or more cubes to remove the attribute from. 

54 attribute: str | Iterable 

55 Name of attribute (or Iterable of names) to remove. 

56 

57 Returns 

58 ------- 

59 cubes: CubeList 

60 CubeList of cube(s) with the attribute removed. 

61 """ 

62 # Ensure cubes is a CubeList. 

63 if not isinstance(cubes, CubeList): 

64 cubes = CubeList(iter_maybe(cubes)) 

65 

66 for cube in cubes: 

67 for attr in iter_maybe(attribute): 

68 cube.attributes.pop(attr, None) 

69 return cubes 

70 

71 

72def addition(addend_1, addend_2): 

73 """Addition of two fields. 

74 

75 Parameters 

76 ---------- 

77 addend_1: Cube 

78 Any field to have another field added to it. 

79 addend_2: Cube 

80 Any field to be added to another field. 

81 

82 Returns 

83 ------- 

84 Cube 

85 

86 Raises 

87 ------ 

88 ValueError, iris.exceptions.NotYetImplementedError 

89 When the cubes are not compatible. 

90 

91 Notes 

92 ----- 

93 This is a simple operator designed for combination of diagnostics or 

94 creating new diagnostics by using recipes. 

95 

96 Examples 

97 -------- 

98 >>> field_addition = misc.addition(kinetic_energy_u, kinetic_energy_v) 

99 

100 """ 

101 return addend_1 + addend_2 

102 

103 

104def subtraction(minuend, subtrahend): 

105 """Subtraction of two fields. 

106 

107 Parameters 

108 ---------- 

109 minuend: Cube 

110 Any field to have another field subtracted from it. 

111 subtrahend: Cube 

112 Any field to be subtracted from to another field. 

113 

114 Returns 

115 ------- 

116 Cube 

117 

118 Raises 

119 ------ 

120 ValueError, iris.exceptions.NotYetImplementedError 

121 When the cubes are not compatible. 

122 

123 Notes 

124 ----- 

125 This is a simple operator designed for combination of diagnostics or 

126 creating new diagnostics by using recipes. It can be used for model 

127 differences to allow for comparisons between the same field in different 

128 models or model configurations. 

129 

130 Examples 

131 -------- 

132 >>> model_diff = misc.subtraction(temperature_model_A, temperature_model_B) 

133 

134 """ 

135 return minuend - subtrahend 

136 

137 

138def division(numerator, denominator): 

139 """Division of two fields. 

140 

141 Parameters 

142 ---------- 

143 numerator: Cube 

144 Any field to have the ratio taken with respect to another field. 

145 denominator: Cube 

146 Any field used to divide another field or provide the reference 

147 value in a ratio. 

148 

149 Returns 

150 ------- 

151 Cube 

152 

153 Raises 

154 ------ 

155 ValueError 

156 When the cubes are not compatible. 

157 

158 Notes 

159 ----- 

160 This is a simple operator designed for combination of diagnostics or 

161 creating new diagnostics by using recipes. 

162 

163 Examples 

164 -------- 

165 >>> bowen_ratio = misc.division(sensible_heat_flux, latent_heat_flux) 

166 

167 """ 

168 return numerator / denominator 

169 

170 

171def multiplication(multiplicand, multiplier): 

172 """Multiplication of two fields. 

173 

174 Parameters 

175 ---------- 

176 multiplicand: Cube 

177 Any field to be multiplied by another field. 

178 multiplier: Cube 

179 Any field to be multiplied to another field. 

180 

181 Returns 

182 ------- 

183 Cube 

184 

185 Raises 

186 ------ 

187 ValueError 

188 When the cubes are not compatible. 

189 

190 Notes 

191 ----- 

192 This is a simple operator designed for combination of diagnostics or 

193 creating new diagnostics by using recipes. 

194 

195 Examples 

196 -------- 

197 >>> filtered_CAPE_ratio = misc.multiplication(CAPE_ratio, inflow_layer_properties) 

198 

199 """ 

200 return multiplicand * multiplier