Coverage for /usr/lib/python3/dist-packages/matplotlib/units.py: 69%

1""" 

2The classes here provide support for using custom classes with 

3Matplotlib, e.g., those that do not expose the array interface but know 

4how to convert themselves to arrays. It also supports classes with 

5units and units conversion. Use cases include converters for custom 

6objects, e.g., a list of datetime objects, as well as for objects that 

7are unit aware. We don't assume any particular units implementation; 

8rather a units implementation must register with the Registry converter 

9dictionary and provide a `ConversionInterface`. For example, 

10here is a complete implementation which supports plotting with native 

11datetime objects:: 

12 

13 import matplotlib.units as units 

14 import matplotlib.dates as dates 

15 import matplotlib.ticker as ticker 

16 import datetime 

17 

18 class DateConverter(units.ConversionInterface): 

19 

20 @staticmethod 

21 def convert(value, unit, axis): 

22 "Convert a datetime value to a scalar or array." 

23 return dates.date2num(value) 

24 

25 @staticmethod 

26 def axisinfo(unit, axis): 

27 "Return major and minor tick locators and formatters." 

28 if unit != 'date': 

29 return None 

30 majloc = dates.AutoDateLocator() 

31 majfmt = dates.AutoDateFormatter(majloc) 

32 return units.AxisInfo(majloc=majloc, majfmt=majfmt, label='date') 

33 

34 @staticmethod 

35 def default_units(x, axis): 

36 "Return the default unit for x or None." 

37 return 'date' 

38 

39 # Finally we register our object type with the Matplotlib units registry. 

40 units.registry[datetime.date] = DateConverter() 

41""" 

42 

43from decimal import Decimal 

44from numbers import Number 

45 

46import numpy as np 

47from numpy import ma 

48 

49from matplotlib import _api, cbook 

50 

51 

52class ConversionError(TypeError): 

53 pass 

54 

55 

56def _is_natively_supported(x): 

57 """ 

58 Return whether *x* is of a type that Matplotlib natively supports or an 

59 array of objects of such types. 

60 """ 

61 # Matplotlib natively supports all number types except Decimal. 

62 if np.iterable(x): 

63 # Assume lists are homogeneous as other functions in unit system. 

64 for thisx in x: 

65 if thisx is ma.masked: 

66 continue 

67 return isinstance(thisx, Number) and not isinstance(thisx, Decimal) 

68 else: 

69 return isinstance(x, Number) and not isinstance(x, Decimal) 

70 

71 

72class AxisInfo: 

73 """ 

74 Information to support default axis labeling, tick labeling, and limits. 

75 

76 An instance of this class must be returned by 

77 `ConversionInterface.axisinfo`. 

78 """ 

79 def __init__(self, majloc=None, minloc=None, 

80 majfmt=None, minfmt=None, label=None, 

81 default_limits=None): 

82 """ 

83 Parameters 

84 ---------- 

85 majloc, minloc : Locator, optional 

86 Tick locators for the major and minor ticks. 

87 majfmt, minfmt : Formatter, optional 

88 Tick formatters for the major and minor ticks. 

89 label : str, optional 

90 The default axis label. 

91 default_limits : optional 

92 The default min and max limits of the axis if no data has 

93 been plotted. 

94 

95 Notes 

96 ----- 

97 If any of the above are ``None``, the axis will simply use the 

98 default value. 

99 """ 

100 self.majloc = majloc 

101 self.minloc = minloc 

102 self.majfmt = majfmt 

103 self.minfmt = minfmt 

104 self.label = label 

105 self.default_limits = default_limits 

106 

107 

108class ConversionInterface: 

109 """ 

110 The minimal interface for a converter to take custom data types (or 

111 sequences) and convert them to values Matplotlib can use. 

112 """ 

113 

114 @staticmethod 

115 def axisinfo(unit, axis): 

116 """Return an `.AxisInfo` for the axis with the specified units.""" 

117 return None 

118 

119 @staticmethod 

120 def default_units(x, axis): 

121 """Return the default unit for *x* or ``None`` for the given axis.""" 

122 return None 

123 

124 @staticmethod 

125 def convert(obj, unit, axis): 

126 """ 

127 Convert *obj* using *unit* for the specified *axis*. 

128 

129 If *obj* is a sequence, return the converted sequence. The output must 

130 be a sequence of scalars that can be used by the numpy array layer. 

131 """ 

132 return obj 

133 

134 @staticmethod 

135 @_api.deprecated("3.5") 

136 def is_numlike(x): 

137 """ 

138 The Matplotlib datalim, autoscaling, locators etc work with scalars 

139 which are the units converted to floats given the current unit. The 

140 converter may be passed these floats, or arrays of them, even when 

141 units are set. 

142 """ 

143 if np.iterable(x): 

144 for thisx in x: 

145 if thisx is ma.masked: 

146 continue 

147 return isinstance(thisx, Number) 

148 else: 

149 return isinstance(x, Number) 

150 

151 

152class DecimalConverter(ConversionInterface): 

153 """Converter for decimal.Decimal data to float.""" 

154 

155 @staticmethod 

156 def convert(value, unit, axis): 

157 """ 

158 Convert Decimals to floats. 

159 

160 The *unit* and *axis* arguments are not used. 

161 

162 Parameters 

163 ---------- 

164 value : decimal.Decimal or iterable 

165 Decimal or list of Decimal need to be converted 

166 """ 

167 if isinstance(value, Decimal): 

168 return float(value) 

169 # value is Iterable[Decimal] 

170 elif isinstance(value, ma.MaskedArray): 

171 return ma.asarray(value, dtype=float) 

172 else: 

173 return np.asarray(value, dtype=float) 

174 

175 # axisinfo and default_units can be inherited as Decimals are Numbers. 

176 

177 

178class Registry(dict): 

179 """Register types with conversion interface.""" 

180 

181 def get_converter(self, x): 

182 """Get the converter interface instance for *x*, or None.""" 

183 # Unpack in case of e.g. Pandas or xarray object 

184 x = cbook._unpack_to_numpy(x) 

185 

186 if isinstance(x, np.ndarray): 

187 # In case x in a masked array, access the underlying data (only its 

188 # type matters). If x is a regular ndarray, getdata() just returns 

189 # the array itself. 

190 x = np.ma.getdata(x).ravel() 

191 # If there are no elements in x, infer the units from its dtype 

192 if not x.size: 

193 return self.get_converter(np.array([0], dtype=x.dtype)) 

194 for cls in type(x).__mro__: # Look up in the cache. 

195 try: 

196 return self[cls] 

197 except KeyError: 

198 pass 

199 try: # If cache lookup fails, look up based on first element... 

200 first = cbook._safe_first_finite(x) 

201 except (TypeError, StopIteration): 

202 pass 

203 else: 

204 # ... and avoid infinite recursion for pathological iterables for 

205 # which indexing returns instances of the same iterable class. 

206 if type(first) is not type(x): 

207 return self.get_converter(first) 

208 return None 

209 

210 

211registry = Registry() 

212registry[Decimal] = DecimalConverter()