Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.9/dist-packages/matplotlib/units.py: 39%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
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::
13 import matplotlib.units as units
14 import matplotlib.dates as dates
15 import matplotlib.ticker as ticker
16 import datetime
18 class DateConverter(units.ConversionInterface):
20 @staticmethod
21 def convert(value, unit, axis):
22 "Convert a datetime value to a scalar or array."
23 return dates.date2num(value)
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')
34 @staticmethod
35 def default_units(x, axis):
36 "Return the default unit for x or None."
37 return 'date'
39 # Finally we register our object type with the Matplotlib units registry.
40 units.registry[datetime.date] = DateConverter()
41"""
43from decimal import Decimal
44from numbers import Number
46import numpy as np
47from numpy import ma
49from matplotlib import cbook
52class ConversionError(TypeError):
53 pass
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)
72class AxisInfo:
73 """
74 Information to support default axis labeling, tick labeling, and limits.
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.
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
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 """
114 @staticmethod
115 def axisinfo(unit, axis):
116 """Return an `.AxisInfo` for the axis with the specified units."""
117 return None
119 @staticmethod
120 def default_units(x, axis):
121 """Return the default unit for *x* or ``None`` for the given axis."""
122 return None
124 @staticmethod
125 def convert(obj, unit, axis):
126 """
127 Convert *obj* using *unit* for the specified *axis*.
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
135class DecimalConverter(ConversionInterface):
136 """Converter for decimal.Decimal data to float."""
138 @staticmethod
139 def convert(value, unit, axis):
140 """
141 Convert Decimals to floats.
143 The *unit* and *axis* arguments are not used.
145 Parameters
146 ----------
147 value : decimal.Decimal or iterable
148 Decimal or list of Decimal need to be converted
149 """
150 if isinstance(value, Decimal):
151 return float(value)
152 # value is Iterable[Decimal]
153 elif isinstance(value, ma.MaskedArray):
154 return ma.asarray(value, dtype=float)
155 else:
156 return np.asarray(value, dtype=float)
158 # axisinfo and default_units can be inherited as Decimals are Numbers.
161class Registry(dict):
162 """Register types with conversion interface."""
164 def get_converter(self, x):
165 """Get the converter interface instance for *x*, or None."""
166 # Unpack in case of e.g. Pandas or xarray object
167 x = cbook._unpack_to_numpy(x)
169 if isinstance(x, np.ndarray):
170 # In case x in a masked array, access the underlying data (only its
171 # type matters). If x is a regular ndarray, getdata() just returns
172 # the array itself.
173 x = np.ma.getdata(x).ravel()
174 # If there are no elements in x, infer the units from its dtype
175 if not x.size:
176 return self.get_converter(np.array([0], dtype=x.dtype))
177 for cls in type(x).__mro__: # Look up in the cache.
178 try:
179 return self[cls]
180 except KeyError:
181 pass
182 try: # If cache lookup fails, look up based on first element...
183 first = cbook._safe_first_finite(x)
184 except (TypeError, StopIteration):
185 pass
186 else:
187 # ... and avoid infinite recursion for pathological iterables for
188 # which indexing returns instances of the same iterable class.
189 if type(first) is not type(x):
190 return self.get_converter(first)
191 return None
194registry = Registry()
195registry[Decimal] = DecimalConverter()