1MIZANI(1) Mizani MIZANI(1)
2
6 mizani - Mizani Documentation
7 Mizani is python library that provides the pieces necessary to create
9 scales for a graphics system. It is based on the R Scales package.
10
12 bounds - Limiting data values for a palette
13 Continuous variables have values anywhere in the range minus infinite
14 to plus infinite. However, when creating a visual representation of
15 these values what usually matters is the relative difference between
16 the values. This is where rescaling comes into play.
17 The values are mapped onto a range that a scale can deal with. For
19 graphical representation that range tends to be [0, 1] or [0, n], where
20 n is some number that makes the plotted object overflow the plotting
21 area.
22 Although a scale may be able handle the [0, n] range, it may be desir‐
24 able to have a lower bound greater than zero. For example, if data val‐
25 ues get mapped to zero on a scale whose graphical representation is the
26 size/area/radius/length some data will be invisible. The solution is to
27 restrict the lower bound e.g. [0.1, 1]. Similarly you can restrict the
28 upper bound -- using these functions.
29 mizani.bounds.censor(x, range=(0, 1), only_finite=True)
31 Convert any values outside of range to a NULL type object.
32 Parameters
34 x numpy:array_like Values to manipulate
36 range python:tuple (min, max) giving desired output
38 range
39 only_finite
41 bool If True (the default), will only modify fi‐
42 nite values.
43 Returns
45 x numpy:array_like Censored array
47 Notes
49 All values in x should be of the same type. only_finite parame‐
51 ter is not considered for Datetime and Timedelta types.
52 The NULL type object depends on the type of values in x.
54 • float - float('nan')
56 • int - float('nan')
58 • datetime.datetime : np.datetime64(NaT)
60 • datetime.timedelta : np.timedelta64(NaT)
62 Examples
64 >>> a = [1, 2, np.inf, 3, 4, -np.inf, 5]
66 >>> censor(a, (0, 10))
67 [1, 2, inf, 3, 4, -inf, 5]
68 >>> censor(a, (0, 10), False)
69 [1, 2, nan, 3, 4, nan, 5]
70 >>> censor(a, (2, 4))
71 [nan, 2, inf, 3, 4, -inf, nan]
72 mizani.bounds.expand_range(range, mul=0, add=0, zero_width=1)
74 Expand a range with a multiplicative or additive constant
75 Parameters
77 range python:tuple Range of data. Size 2.
79 mul python:int | python:float Multiplicative constant
81 add python:int | python:float | timedelta Additive
83 constant
84 zero_width
86 python:int | python:float | timedelta Distance to
87 use if range has zero width
88 Returns
90 out python:tuple Expanded range
92 Notes
94 If expanding datetime or timedelta types, add and zero_width
96 must be suitable timedeltas i.e. You should not mix types be‐
97 tween Numpy, Pandas and the datetime module.
98 Examples
100 >>> expand_range((3, 8))
102 (3, 8)
103 >>> expand_range((0, 10), mul=0.1)
104 (-1.0, 11.0)
105 >>> expand_range((0, 10), add=2)
106 (-2, 12)
107 >>> expand_range((0, 10), mul=.1, add=2)
108 (-3.0, 13.0)
109 >>> expand_range((0, 1))
110 (0, 1)
111 When the range has zero width
113 >>> expand_range((5, 5))
115 (4.5, 5.5)
116 mizani.bounds.rescale(x, to=(0, 1), _from=None)
118 Rescale numeric vector to have specified minimum and maximum.
119 Parameters
121 x numpy:array_like | numeric 1D vector of values to
123 manipulate.
124 to python:tuple output range (numeric vector of
126 length two)
127 _from python:tuple input range (numeric vector of length
129 two). If not given, is calculated from the range
130 of x
131 Returns
133 out numpy:array_like Rescaled values
135 Examples
137 >>> x = [0, 2, 4, 6, 8, 10]
139 >>> rescale(x)
140 array([0. , 0.2, 0.4, 0.6, 0.8, 1. ])
141 >>> rescale(x, to=(0, 2))
142 array([0. , 0.4, 0.8, 1.2, 1.6, 2. ])
143 >>> rescale(x, to=(0, 2), _from=(0, 20))
144 array([0. , 0.2, 0.4, 0.6, 0.8, 1. ])
145 mizani.bounds.rescale_max(x, to=(0, 1), _from=None)
147 Rescale numeric vector to have specified maximum.
148 Parameters
150 x numpy:array_like | numeric 1D vector of values to
152 manipulate.
153 to python:tuple output range (numeric vector of
155 length two)
156 _from python:tuple input range (numeric vector of length
158 two). If not given, is calculated from the range
159 of x. Only the 2nd (max) element is essential to
160 the output.
161 Returns
163 out numpy:array_like Rescaled values
165 Examples
167 >>> x = [0, 2, 4, 6, 8, 10]
169 >>> rescale_max(x, (0, 3))
170 array([0. , 0.6, 1.2, 1.8, 2.4, 3. ])
171 Only the 2nd (max) element of the parameters to and _from are
173 essential to the output.
174 >>> rescale_max(x, (1, 3))
176 array([0. , 0.6, 1.2, 1.8, 2.4, 3. ])
177 >>> rescale_max(x, (0, 20))
178 array([ 0., 4., 8., 12., 16., 20.])
179 If max(x) < _from[1] then values will be scaled beyond the re‐
181 quested maximum (to[1]).
182 >>> rescale_max(x, to=(1, 3), _from=(-1, 6))
184 array([0., 1., 2., 3., 4., 5.])
185 If the values are the same, they taken on the requested maximum.
187 This includes an array of all zeros.
188 >>> rescale_max([5, 5, 5])
190 array([1., 1., 1.])
191 >>> rescale_max([0, 0, 0])
192 array([1, 1, 1])
193 mizani.bounds.rescale_mid(x, to=(0, 1), _from=None, mid=0)
195 Rescale numeric vector to have specified minimum, midpoint, and
196 maximum.
197 Parameters
199 x numpy:array_like | numeric 1D vector of values to
201 manipulate.
202 to python:tuple output range (numeric vector of
204 length two)
205 _from python:tuple input range (numeric vector of length
207 two). If not given, is calculated from the range
208 of x
209 mid numeric mid-point of input range
211 Returns
213 out numpy:array_like Rescaled values
215 Examples
217 >>> rescale_mid([1, 2, 3], mid=1)
219 array([0.5 , 0.75, 1. ])
220 >>> rescale_mid([1, 2, 3], mid=2)
221 array([0. , 0.5, 1. ])
222 mizani.bounds.squish_infinite(x, range=(0, 1))
224 Truncate infinite values to a range.
225 Parameters
227 x numpy:array_like Values that should have infini‐
229 ties squished.
230 range python:tuple The range onto which to squish the
232 infinites. Must be of size 2.
233 Returns
235 out numpy:array_like Values with infinites squished.
237 Examples
239 >>> squish_infinite([0, .5, .25, np.inf, .44])
241 [0.0, 0.5, 0.25, 1.0, 0.44]
242 >>> squish_infinite([0, -np.inf, .5, .25, np.inf], (-10, 9))
243 [0.0, -10.0, 0.5, 0.25, 9.0]
244 mizani.bounds.zero_range(x, tol=2.220446049250313e-14)
246 Determine if range of vector is close to zero.
247 Parameters
249 x numpy:array_like | numeric Value(s) to check. If
251 it is an array_like, it should be of length 2.
252 tol python:float Tolerance. Default tolerance is the
254 machine epsilon times 10^2.
255 Returns
257 out bool Whether x has zero range.
259 Examples
261 >>> zero_range([1, 1])
263 True
264 >>> zero_range([1, 2])
265 False
266 >>> zero_range([1, 2], tol=2)
267 True
268 mizani.bounds.expand_range_distinct(range, expand=(0, 0, 0, 0),
270 zero_width=1)
271 Expand a range with a multiplicative or additive constants
272 Similar to expand_range() but both sides of the range expanded
274 using different constants
275 Parameters
277 range python:tuple Range of data. Size 2
279 expand python:tuple Length 2 or 4. If length is 2, then
281 the same constants are used for both sides. If
282 length is 4 then the first two are are the Multi‐
283 plicative (mul) and Additive (add) constants for
284 the lower limit, and the second two are the con‐
285 stants for the upper limit.
286 zero_width
288 python:int | python:float | timedelta Distance to
289 use if range has zero width
290 Returns
292 out python:tuple Expanded range
294 Examples
296 >>> expand_range_distinct((3, 8))
298 (3, 8)
299 >>> expand_range_distinct((0, 10), (0.1, 0))
300 (-1.0, 11.0)
301 >>> expand_range_distinct((0, 10), (0.1, 0, 0.1, 0))
302 (-1.0, 11.0)
303 >>> expand_range_distinct((0, 10), (0.1, 0, 0, 0))
304 (-1.0, 10)
305 >>> expand_range_distinct((0, 10), (0, 2))
306 (-2, 12)
307 >>> expand_range_distinct((0, 10), (0, 2, 0, 2))
308 (-2, 12)
309 >>> expand_range_distinct((0, 10), (0, 0, 0, 2))
310 (0, 12)
311 >>> expand_range_distinct((0, 10), (.1, 2))
312 (-3.0, 13.0)
313 >>> expand_range_distinct((0, 10), (.1, 2, .1, 2))
314 (-3.0, 13.0)
315 >>> expand_range_distinct((0, 10), (0, 0, .1, 2))
316 (0, 13.0)
317 mizani.bounds.squish(x, range=(0, 1), only_finite=True)
319 Squish values into range.
320 Parameters
322 x numpy:array_like Values that should have out of
324 range values squished.
325 range python:tuple The range onto which to squish the
327 values.
328 only_finite: boolean
330 When true, only squishes finite values.
331 Returns
333 out numpy:array_like Values with out of range values
335 squished.
336 Examples
338 >>> squish([-1.5, 0.2, 0.5, 0.8, 1.0, 1.2])
340 [0.0, 0.2, 0.5, 0.8, 1.0, 1.0]
341 >>> squish([-np.inf, -1.5, 0.2, 0.5, 0.8, 1.0, np.inf], only_finite=False)
343 [0.0, 0.0, 0.2, 0.5, 0.8, 1.0, 1.0]
344 breaks - Partitioning a scale for readability
346 All scales have a means by which the values that are mapped onto the
347 scale are interpreted. Numeric digital scales put out numbers for di‐
348 rect interpretation, but most scales cannot do this. What they offer is
349 named markers/ticks that aid in assessing the values e.g. the common
350 odometer will have ticks and values to help gauge the speed of the ve‐
351 hicle.
352 The named markers are what we call breaks. Properly calculated breaks
354 make interpretation straight forward. These functions provide ways to
355 calculate good(hopefully) breaks.
356 class mizani.breaks.mpl_breaks(*args, **kwargs)
358 Compute breaks using MPL's default locator
359 See MaxNLocator for the parameter descriptions
361 Examples
363 >>> x = range(10)
365 >>> limits = (0, 9)
366 >>> mpl_breaks()(limits)
367 array([0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])
368 >>> mpl_breaks(nbins=2)(limits)
369 array([ 0., 5., 10.])
370 __call__(limits)
372 Compute breaks
373 Parameters
375 limits python:tuple Minimum and maximum values
377 Returns
379 out numpy:array_like Sequence of breaks points
381 class mizani.breaks.log_breaks(n=5, base=10)
383 Integer breaks on log transformed scales
384 Parameters
386 n python:int Desired number of breaks
388 base python:int Base of logarithm
390 Examples
392 >>> x = np.logspace(3, 6)
394 >>> limits = min(x), max(x)
395 >>> log_breaks()(limits)
396 array([ 1000, 10000, 100000, 1000000])
397 >>> log_breaks(2)(limits)
398 array([ 1000, 100000])
399 >>> log_breaks()([0.1, 1])
400 array([0.1, 0.3, 1. , 3. ])
401 __call__(limits)
403 Compute breaks
404 Parameters
406 limits python:tuple Minimum and maximum values
408 Returns
410 out numpy:array_like Sequence of breaks points
412 class mizani.breaks.minor_breaks(n=1)
414 Compute minor breaks
415 Parameters
417 n python:int Number of minor breaks between the ma‐
419 jor breaks.
420 Examples
422 >>> major = [1, 2, 3, 4]
424 >>> limits = [0, 5]
425 >>> minor_breaks()(major, limits)
426 array([0.5, 1.5, 2.5, 3.5, 4.5])
427 >>> minor_breaks()([1, 2], (1, 2))
428 array([1.5])
429 More than 1 minor break.
431 >>> minor_breaks(3)([1, 2], (1, 2))
433 array([1.25, 1.5 , 1.75])
434 >>> minor_breaks()([1, 2], (1, 2), 3)
435 array([1.25, 1.5 , 1.75])
436 __call__(major, limits=None, n=None)
438 Minor breaks
439 Parameters
441 major numpy:array_like Major breaks
443 limits numpy:array_like | python:None Limits of
445 the scale. If array_like, must be of size
446 2. If None, then the minimum and maximum of
447 the major breaks are used.
448 n python:int Number of minor breaks between
450 the major breaks. If None, then self.n is
451 used.
452 Returns
454 out numpy:array_like Minor beraks
456 class mizani.breaks.trans_minor_breaks(trans, n=1)
458 Compute minor breaks for transformed scales
459 The minor breaks are computed in data space. This together with
461 major breaks computed in transform space reveals the non linear‐
462 ity of of a scale. See the log transforms created with
463 log_trans() like log10_trans.
464 Parameters
466 trans trans or type Trans object or trans class.
468 n python:int Number of minor breaks between the ma‐
470 jor breaks.
471 Examples
473 >>> from mizani.transforms import sqrt_trans
475 >>> major = [1, 2, 3, 4]
476 >>> limits = [0, 5]
477 >>> sqrt_trans().minor_breaks(major, limits)
478 array([0.5, 1.5, 2.5, 3.5, 4.5])
479 >>> class sqrt_trans2(sqrt_trans):
480 ... def __init__(self):
481 ... self.minor_breaks = trans_minor_breaks(sqrt_trans2)
482 >>> sqrt_trans2().minor_breaks(major, limits)
483 array([1.58113883, 2.54950976, 3.53553391])
484 More than 1 minor break
486 >>> major = [1, 10]
488 >>> limits = [1, 10]
489 >>> sqrt_trans().minor_breaks(major, limits, 4)
490 array([2.8, 4.6, 6.4, 8.2])
491 __call__(major, limits=None, n=None)
493 Minor breaks for transformed scales
494 Parameters
496 major numpy:array_like Major breaks
498 limits numpy:array_like | python:None Limits of
500 the scale. If array_like, must be of size
501 2. If None, then the minimum and maximum of
502 the major breaks are used.
503 n python:int Number of minor breaks between
505 the major breaks. If None, then self.n is
506 used.
507 Returns
509 out numpy:array_like Minor breaks
511 class mizani.breaks.date_breaks(width=None)
513 Regularly spaced dates
514 Parameters
516 width python:str | python:None An interval specifica‐
518 tion. Must be one of [second, minute, hour, day,
519 week, month, year] If None, the interval auto‐
520 matic.
521 Examples
523 >>> from datetime import datetime
525 >>> x = [datetime(year, 1, 1) for year in [2010, 2026, 2015]]
526 Default breaks will be regularly spaced but the spacing is auto‐
528 matically determined
529 >>> limits = min(x), max(x)
531 >>> breaks = date_breaks()
532 >>> [d.year for d in breaks(limits)]
533 [2010, 2012, 2014, 2016, 2018, 2020, 2022, 2024, 2026]
534 Breaks at 4 year intervals
536 >>> breaks = date_breaks('4 year')
538 >>> [d.year for d in breaks(limits)]
539 [2008, 2012, 2016, 2020, 2024, 2028]
540 __call__(limits)
542 Compute breaks
543 Parameters
545 limits python:tuple Minimum and maximum date‐
547 time.datetime values.
548 Returns
550 out numpy:array_like Sequence of break points.
552 class mizani.breaks.timedelta_breaks(n=5, Q=(1, 2, 5, 10))
554 Timedelta breaks
555 Returns
557 out python:callable() f(limits) A function that takes
559 a sequence of two datetime.timedelta values and
560 returns a sequence of break points.
561 Examples
563 >>> from datetime import timedelta
565 >>> breaks = timedelta_breaks()
566 >>> x = [timedelta(days=i*365) for i in range(25)]
567 >>> limits = min(x), max(x)
568 >>> major = breaks(limits)
569 >>> [val.total_seconds()/(365*24*60*60)for val in major]
570 [0.0, 5.0, 10.0, 15.0, 20.0, 25.0]
571 __call__(limits)
573 Compute breaks
574 Parameters
576 limits python:tuple Minimum and maximum date‐
578 time.timedelta values.
579 Returns
581 out numpy:array_like Sequence of break points.
583 class mizani.breaks.extended_breaks(n=5, Q=[1, 5, 2, 2.5, 4, 3],
585 only_inside=False, w=[0.25, 0.2, 0.5, 0.05])
586 An extension of Wilkinson's tick position algorithm
587 Parameters
589 n python:int Desired number of ticks
591 Q python:list List of nice numbers
593 only_inside
595 bool If True, then all the ticks will be within
596 the given range.
597 w python:list Weights applied to the four optimiza‐
599 tion components (simplicity, coverage, density,
600 and legibility). They should add up to 1.
601 References
603 • Talbot, J., Lin, S., Hanrahan, P. (2010) An Extension of
605 Wilkinson's Algorithm for Positioning Tick Labels on Axes, In‐
606 foVis 2010.
607 Additional Credit to Justin Talbot on whose code this implemen‐
609 tation is almost entirely based.
610 Examples
612 >>> limits = (0, 9)
614 >>> extended_breaks()(limits)
615 array([ 0. , 2.5, 5. , 7.5, 10. ])
616 >>> extended_breaks(n=6)(limits)
617 array([ 0., 2., 4., 6., 8., 10.])
618 __call__(limits)
620 Calculate the breaks
621 Parameters
623 limits array Minimum and maximum values.
625 Returns
627 out numpy:array_like Sequence of break points.
629 formatters - Labelling breaks
631 Scales have guides and these are what help users make sense of the data
632 mapped onto the scale. Common examples of guides include the x-axis,
633 the y-axis, the keyed legend and a colorbar legend. The guides have
634 demarcations(breaks), some of which must be labelled.
635 The *_format functions below create functions that convert data values
637 as understood by a specific scale and return string representations of
638 those values. Manipulating the string representation of a value helps
639 improve readability of the guide.
640 class mizani.formatters.comma_format(digits=0)
642 Format number with commas separating thousands
643 Parameters
645 digits python:int Number of digits after the decimal
647 point.
648 Examples
650 >>> comma_format()([1000, 2, 33000, 400])
652 ['1,000', '2', '33,000', '400']
653 __call__(x)
655 Format a sequence of inputs
656 Parameters
658 x array Input
660 Returns
662 out python:list List of strings.
664 class mizani.formatters.custom_format(fmt='{}', style='new')
666 Custom format
667 Parameters
669 fmt python:str, optional Format string. Default is the
671 generic new style format braces, {}.
672 style 'new' | 'old' Whether to use new style or old
674 style formatting. New style uses the str.format()
675 while old style uses %. The format string must be
676 written accordingly.
677 Examples
679 >>> formatter = custom_format('{:.2f} USD')
681 >>> formatter([3.987, 2, 42.42])
682 ['3.99 USD', '2.00 USD', '42.42 USD']
683 __call__(x)
685 Format a sequence of inputs
686 Parameters
688 x array Input
690 Returns
692 out python:list List of strings.
694 class mizani.formatters.currency_format(prefix='$', suffix='', dig‐
696 its=2, big_mark='')
697 Currency formatter
698 Parameters
700 prefix python:str What to put before the value.
702 suffix python:str What to put after the value.
704 digits python:int Number of significant digits
706 big_mark
708 python:str The thousands separator. This is usu‐
709 ally a comma or a dot.
710 Examples
712 >>> x = [1.232, 99.2334, 4.6, 9, 4500]
714 >>> currency_format()(x)
715 ['$1.23', '$99.23', '$4.60', '$9.00', '$4500.00']
716 >>> currency_format('C$', digits=0, big_mark=',')(x)
717 ['C$1', 'C$99', 'C$5', 'C$9', 'C$4,500']
718 __call__(x)
720 Format a sequence of inputs
721 Parameters
723 x array Input
725 Returns
727 out python:list List of strings.
729 mizani.formatters.dollar_format
731 alias of currency_format
732 class mizani.formatters.percent_format(use_comma=False)
734 Percent formatter
735 Multiply by one hundred and display percent sign
737 Parameters
739 use_comma
741 bool If True, use a comma to separate the thou‐
742 sands. Default is False.
743 Examples
745 >>> formatter = percent_format()
747 >>> formatter([.45, 9.515, .01])
748 ['45%', '952%', '1%']
749 >>> formatter([.654, .8963, .1])
750 ['65.4%', '89.6%', '10.0%']
751 __call__(x)
753 Format a sequence of inputs
754 Parameters
756 x array Input
758 Returns
760 out python:list List of strings.
762 class mizani.formatters.scientific_format(digits=3)
764 Scientific formatter
765 Parameters
767 digits python:int Significant digits.
769 Notes
771 Be careful when using many digits (15+ on a 64 bit computer).
773 Consider of the machine epsilon.
774 Examples
776 >>> x = [.12, .23, .34, 45]
778 >>> scientific_format()(x)
779 ['1.2e-01', '2.3e-01', '3.4e-01', '4.5e+01']
780 __call__(x)
782 Call self as a function.
783 class mizani.formatters.date_format(fmt='%Y-%m-%d', tz=None)
785 Datetime formatter
786 Parameters
788 fmt python:str Format string. See strftime.
790 tz datetime.tzinfo, optional Time zone information.
792 If none is specified, the time zone will be that
793 of the first date. If the first date has no time
794 information then a time zone is chosen by other
795 means.
796 Examples
798 >>> from datetime import datetime
800 >>> x = [datetime(x, 1, 1) for x in [2010, 2014, 2018, 2022]]
801 >>> date_format()(x)
802 ['2010-01-01', '2014-01-01', '2018-01-01', '2022-01-01']
803 >>> date_format('%Y')(x)
804 ['2010', '2014', '2018', '2022']
805 Can format time
807 >>> x = [datetime(2017, 12, 1, 16, 5, 7)]
809 >>> date_format("%Y-%m-%d %H:%M:%S")(x)
810 ['2017-12-01 16:05:07']
811 Time zones are respected
813 >>> UTC = ZoneInfo('UTC')
815 >>> UG = ZoneInfo('Africa/Kampala')
816 >>> x = [datetime(2010, 1, 1, i) for i in [8, 15]]
817 >>> x_tz = [datetime(2010, 1, 1, i, tzinfo=UG) for i in [8, 15]]
818 >>> date_format('%Y-%m-%d %H:%M')(x)
819 ['2010-01-01 08:00', '2010-01-01 15:00']
820 >>> date_format('%Y-%m-%d %H:%M')(x_tz)
821 ['2010-01-01 08:00', '2010-01-01 15:00']
822 Format with a specific time zone
824 >>> date_format('%Y-%m-%d %H:%M', tz=UTC)(x_tz)
826 ['2010-01-01 05:00', '2010-01-01 12:00']
827 >>> date_format('%Y-%m-%d %H:%M', tz='EST')(x_tz)
828 ['2010-01-01 00:00', '2010-01-01 07:00']
829 __call__(x)
831 Format a sequence of inputs
832 Parameters
834 x array Input
836 Returns
838 out python:list List of strings.
840 class mizani.formatters.mpl_format
842 Format using MPL formatter for scalars
843 Examples
845 >>> mpl_format()([.654, .8963, .1])
847 ['0.6540', '0.8963', '0.1000']
848 __call__(x)
850 Format a sequence of inputs
851 Parameters
853 x array Input
855 Returns
857 out python:list List of strings.
859 class mizani.formatters.log_format(base=10, exponent_limits=(- 4, 4),
861 mathtex=False)
862 Log Formatter
863 Parameters
865 base python:int Base of the logarithm. Default is 10.
867 exponent_limits
869 python:tuple limits (int, int) where if the any of
870 the powers of the numbers falls outside, then the
871 labels will be in exponent form. This only applies
872 for base 10.
873 mathtex
875 bool If True, return the labels in mathtex format
876 as understood by Matplotlib.
877 Examples
879 >>> log_format()([0.001, 0.1, 100])
881 ['0.001', '0.1', '100']
882 >>> log_format()([0.0001, 0.1, 10000])
884 ['1e-4', '1e-1', '1e4']
885 >>> log_format(mathtex=True)([0.0001, 0.1, 10000])
887 ['$10^{-4}$', '$10^{-1}$', '$10^{4}$']
888 __call__(x)
890 Format a sequence of inputs
891 Parameters
893 x array Input
895 Returns
897 out python:list List of strings.
899 class mizani.formatters.timedelta_format(units=None, add_units=True,
901 usetex=False)
902 Timedelta formatter
903 Parameters
905 units python:str, optional The units in which the breaks
907 will be computed. If None, they are decided auto‐
908 matically. Otherwise, the value should be one of:
909 'ns' # nanoseconds
911 'us' # microseconds
912 'ms' # milliseconds
913 's' # secondss
914 'm' # minute
915 'h' # hour
916 'd' # day
917 'w' # week
918 'M' # month
919 'y' # year
920 add_units
922 bool Whether to append the units identifier string
923 to the values.
924 usetext
926 bool If True, they microseconds identifier string
927 is rendered with greek letter mu. Default is
928 False.
929 Examples
931 >>> from datetime import timedelta
933 >>> x = [timedelta(days=31*i) for i in range(5)]
934 >>> timedelta_format()(x)
935 ['0', '1 month', '2 months', '3 months', '4 months']
936 >>> timedelta_format(units='d')(x)
937 ['0', '31 days', '62 days', '93 days', '124 days']
938 >>> timedelta_format(units='d', add_units=False)(x)
939 ['0', '31', '62', '93', '124']
940 __call__(x)
942 Call self as a function.
943 class mizani.formatters.pvalue_format(accuracy=0.001, add_p=False)
945 p-values Formatter
946 Parameters
948 accuracy
950 python:float Number to round to
951 add_p bool Whether to prepend "p=" or "p<" to the output
953 Examples
955 >>> x = [.90, .15, .015, .009, 0.0005]
957 >>> pvalue_format()(x)
958 ['0.9', '0.15', '0.015', '0.009', '<0.001']
959 >>> pvalue_format(0.1)(x)
960 ['0.9', '0.1', '<0.1', '<0.1', '<0.1']
961 >>> pvalue_format(0.1, True)(x)
962 ['p=0.9', 'p=0.1', 'p<0.1', 'p<0.1', 'p<0.1']
963 __call__(x)
965 Format a sequence of inputs
966 Parameters
968 x array Input
970 Returns
972 out python:list List of strings.
974 class mizani.formatters.ordinal_format(prefix='', suffix='',
976 big_mark='')
977 Ordinal Formatter
978 Parameters
980 prefix python:str What to put before the value.
982 suffix python:str What to put after the value.
984 big_mark
986 python:str The thousands separator. This is usu‐
987 ally a comma or a dot.
988 Examples
990 >>> ordinal_format()(range(8))
992 ['0th', '1st', '2nd', '3rd', '4th', '5th', '6th', '7th']
993 >>> ordinal_format(suffix=' Number')(range(11, 15))
994 ['11th Number', '12th Number', '13th Number', '14th Number']
995 __call__(x)
997 Call self as a function.
998 class mizani.formatters.number_bytes_format(symbol='auto', units='bi‐
1000 nary', fmt='{:.0f} ')
1001 Bytes Formatter
1002 Parameters
1004 symbol python:str Valid symbols are "B", "kB", "MB",
1006 "GB", "TB", "PB", "EB", "ZB", and "YB" for SI
1007 units, and the "iB" variants for binary units. De‐
1008 fault is "auto" where the symbol to be used is de‐
1009 termined separately for each value of 1x.
1010 units "binary" | "si" Which unit base to use, 1024 for
1012 "binary" or 1000 for "si".
1013 fmt python:str, optional Format sting. Default is
1015 {:.0f}.
1016 Examples
1018 >>> x = [1000, 1000000, 4e5]
1020 >>> number_bytes_format()(x)
1021 ['1000 B', '977 KiB', '391 KiB']
1022 >>> number_bytes_format(units='si')(x)
1023 ['1 kB', '1 MB', '400 kB']
1024 __call__(x)
1026 Call self as a function.
1027 palettes - Mapping values onto the domain of a scale
1029 Palettes are the link between data values and the values along the di‐
1030 mension of a scale. Before a collection of values can be represented on
1031 a scale, they are transformed by a palette. This transformation is
1032 knowing as mapping. Values are mapped onto a scale by a palette.
1033 Scales tend to have restrictions on the magnitude of quantities that
1035 they can intelligibly represent. For example, the size of a point
1036 should be significantly smaller than the plot panel onto which it is
1037 plotted or else it would be hard to compare two or more points. There‐
1038 fore palettes must be created that enforce such restrictions. This is
1039 the reason for the *_pal functions that create and return the actual
1040 palette functions.
1041 mizani.palettes.hls_palette(n_colors=6, h=0.01, l=0.6, s=0.65)
1043 Get a set of evenly spaced colors in HLS hue space.
1044 h, l, and s should be between 0 and 1
1046 Parameters
1048 n_colors
1050 python:int number of colors in the palette
1051 h python:float first hue
1053 l python:float lightness
1055 s python:float saturation
1057 Returns
1059 palette
1061 python:list List of colors as RGB hex strings.
1062 SEE ALSO:
1064 husl_palette
1066 Make a palette using evenly spaced circular hues in
1067 the HUSL system.
1068 Examples
1070 >>> len(hls_palette(2))
1072 2
1073 >>> len(hls_palette(9))
1074 9
1075 mizani.palettes.husl_palette(n_colors=6, h=0.01, s=0.9, l=0.65)
1077 Get a set of evenly spaced colors in HUSL hue space.
1078 h, s, and l should be between 0 and 1
1080 Parameters
1082 n_colors
1084 python:int number of colors in the palette
1085 h python:float first hue
1087 s python:float saturation
1089 l python:float lightness
1091 Returns
1093 palette
1095 python:list List of colors as RGB hex strings.
1096 SEE ALSO:
1098 hls_palette
1100 Make a palette using evenly spaced circular hues in
1101 the HSL system.
1102 Examples
1104 >>> len(husl_palette(3))
1106 3
1107 >>> len(husl_palette(11))
1108 11
1109 mizani.palettes.rescale_pal(range=(0.1, 1))
1111 Rescale the input to the specific output range.
1112 Useful for alpha, size, and continuous position.
1114 Parameters
1116 range python:tuple Range of the scale
1118 Returns
1120 out function Palette function that takes a sequence of
1122 values in the range [0, 1] and returns values in
1123 the specified range.
1124 Examples
1126 >>> palette = rescale_pal()
1128 >>> palette([0, .2, .4, .6, .8, 1])
1129 array([0.1 , 0.28, 0.46, 0.64, 0.82, 1. ])
1130 The returned palette expects inputs in the [0, 1] range. Any
1132 value outside those limits is clipped to range[0] or range[1].
1133 >>> palette([-2, -1, 0.2, .4, .8, 2, 3])
1135 array([0.1 , 0.1 , 0.28, 0.46, 0.82, 1. , 1. ])
1136 mizani.palettes.area_pal(range=(1, 6))
1138 Point area palette (continuous).
1139 Parameters
1141 range python:tuple Numeric vector of length two, giving
1143 range of possible sizes. Should be greater than
1144 0.
1145 Returns
1147 out function Palette function that takes a sequence of
1149 values in the range [0, 1] and returns values in
1150 the specified range.
1151 Examples
1153 >>> x = np.arange(0, .6, .1)**2
1155 >>> palette = area_pal()
1156 >>> palette(x)
1157 array([1. , 1.5, 2. , 2.5, 3. , 3.5])
1158 The results are equidistant because the input x is in area
1160 space, i.e it is squared.
1161 mizani.palettes.abs_area(max)
1163 Point area palette (continuous), with area proportional to
1164 value.
1165 Parameters
1167 max python:float A number representing the maximum
1169 size
1170 Returns
1172 out function Palette function that takes a sequence of
1174 values in the range [0, 1] and returns values in
1175 the range [0, max].
1176 Examples
1178 >>> x = np.arange(0, .8, .1)**2
1180 >>> palette = abs_area(5)
1181 >>> palette(x)
1182 array([0. , 0.5, 1. , 1.5, 2. , 2.5, 3. , 3.5])
1183 Compared to area_pal(), abs_area() will handle values in the
1185 range [-1, 0] without returning np.nan. And values whose abso‐
1186 lute value is greater than 1 will be clipped to the maximum.
1187 mizani.palettes.grey_pal(start=0.2, end=0.8)
1189 Utility for creating continuous grey scale palette
1190 Parameters
1192 start python:float grey value at low end of palette
1194 end python:float grey value at high end of palette
1196 Returns
1198 out function Continuous color palette that takes a
1200 single int parameter n and returns n equally
1201 spaced colors.
1202 Examples
1204 >>> palette = grey_pal()
1206 >>> palette(5)
1207 ['#333333', '#737373', '#989898', '#b5b5b5', '#cccccc']
1208 mizani.palettes.hue_pal(h=0.01, l=0.6, s=0.65, color_space='hls')
1210 Utility for making hue palettes for color schemes.
1211 Parameters
1213 h python:float first hue. In the [0, 1] range
1215 l python:float lightness. In the [0, 1] range
1217 s python:float saturation. In the [0, 1] range
1219 color_space
1221 'hls' | 'husl' Color space to use for the palette
1222 Returns
1224 out function A discrete color palette that takes a
1226 single int parameter n and returns n equally
1227 spaced colors. Though the palette is continuous,
1228 since it is varies the hue it is good for categor‐
1229 ical data. However if n is large enough the colors
1230 show continuity.
1231 Examples
1233 >>> hue_pal()(5)
1235 ['#db5f57', '#b9db57', '#57db94', '#5784db', '#c957db']
1236 >>> hue_pal(color_space='husl')(5)
1237 ['#e0697e', '#9b9054', '#569d79', '#5b98ab', '#b675d7']
1238 mizani.palettes.brewer_pal(type='seq', palette=1, direction=1)
1240 Utility for making a brewer palette
1241 Parameters
1243 type 'sequential' | 'qualitative' | 'diverging' Type of
1245 palette. Sequential, Qualitative or Diverging. The
1246 following abbreviations may be used, seq, qual or
1247 div.
1248 palette
1250 python:int | python:str Which palette to choose
1251 from. If is an integer, it must be in the range
1252 [0, m], where m depends on the number sequential,
1253 qualitative or diverging palettes. If it is a
1254 string, then it is the name of the palette.
1255 direction
1257 python:int The order of colours in the scale. If
1258 -1 the order of colors is reversed. The default is
1259 1.
1260 Returns
1262 out function A color palette that takes a single int
1264 parameter n and returns n colors. The maximum
1265 value of n varies depending on the parameters.
1266 Examples
1268 >>> brewer_pal()(5)
1270 ['#EFF3FF', '#BDD7E7', '#6BAED6', '#3182BD', '#08519C']
1271 >>> brewer_pal('qual')(5)
1272 ['#7FC97F', '#BEAED4', '#FDC086', '#FFFF99', '#386CB0']
1273 >>> brewer_pal('qual', 2)(5)
1274 ['#1B9E77', '#D95F02', '#7570B3', '#E7298A', '#66A61E']
1275 >>> brewer_pal('seq', 'PuBuGn')(5)
1276 ['#F6EFF7', '#BDC9E1', '#67A9CF', '#1C9099', '#016C59']
1277 The available color names for each palette type can be obtained
1279 using the following code:
1280 import palettable.colorbrewer as brewer
1282 print([k for k in brewer.COLOR_MAPS['Sequential'].keys()])
1284 print([k for k in brewer.COLOR_MAPS['Qualitative'].keys()])
1285 print([k for k in brewer.COLOR_MAPS['Diverging'].keys()])
1286 mizani.palettes.gradient_n_pal(colors, values=None, name='gradientn')
1288 Create a n color gradient palette
1289 Parameters
1291 colors python:list list of colors
1293 values python:list, optional list of points in the range
1295 [0, 1] at which to place each color. Must be the
1296 same size as colors. Default to evenly space the
1297 colors
1298 name python:str Name to call the resultant MPL colormap
1300 Returns
1302 out function Continuous color palette that takes a
1304 single parameter either a float or a sequence of
1305 floats maps those value(s) onto the palette and
1306 returns color(s). The float(s) must be in the
1307 range [0, 1].
1308 Examples
1310 >>> palette = gradient_n_pal(['red', 'blue'])
1312 >>> palette([0, .25, .5, .75, 1])
1313 ['#ff0000', '#bf0040', '#7f0080', '#3f00c0', '#0000ff']
1314 >>> palette([-np.inf, 0, np.nan, 1, np.inf])
1315 [nan, '#ff0000', nan, '#0000ff', nan]
1316 mizani.palettes.cmap_pal(name, lut=None)
1318 Create a continuous palette using an MPL colormap
1319 Parameters
1321 name python:str Name of colormap
1323 lut python:None | python:int This is the number of en‐
1325 tries desired in the lookup table. Default is
1326 None, leave it up Matplotlib.
1327 Returns
1329 out function Continuous color palette that takes a
1331 single parameter either a float or a sequence of
1332 floats maps those value(s) onto the palette and
1333 returns color(s). The float(s) must be in the
1334 range [0, 1].
1335 Examples
1337 >>> palette = cmap_pal('viridis')
1339 >>> palette([.1, .2, .3, .4, .5])
1340 ['#482475', '#414487', '#355f8d', '#2a788e', '#21918c']
1341 mizani.palettes.cmap_d_pal(name, lut=None)
1343 Create a discrete palette using an MPL Listed colormap
1344 Parameters
1346 name python:str Name of colormap
1348 lut python:None | python:int This is the number of en‐
1350 tries desired in the lookup table. Default is
1351 None, leave it up Matplotlib.
1352 Returns
1354 out function A discrete color palette that takes a
1356 single int parameter n and returns n colors. The
1357 maximum value of n varies depending on the parame‐
1358 ters.
1359 Examples
1361 >>> palette = cmap_d_pal('viridis')
1363 >>> palette(5)
1364 ['#440154', '#3b528b', '#21918c', '#5cc863', '#fde725']
1365 mizani.palettes.desaturate_pal(color, prop, reverse=False)
1367 Create a palette that desaturate a color by some proportion
1368 Parameters
1370 color matplotlib color hex, rgb-tuple, or html color
1372 name
1373 prop python:float saturation channel of color will be
1375 multiplied by this value
1376 reverse
1378 bool Whether to reverse the palette.
1379 Returns
1381 out function Continuous color palette that takes a
1383 single parameter either a float or a sequence of
1384 floats maps those value(s) onto the palette and
1385 returns color(s). The float(s) must be in the
1386 range [0, 1].
1387 Examples
1389 >>> palette = desaturate_pal('red', .1)
1391 >>> palette([0, .25, .5, .75, 1])
1392 ['#ff0000', '#e21d1d', '#c53a3a', '#a95656', '#8c7373']
1393 mizani.palettes.manual_pal(values)
1395 Create a palette from a list of values
1396 Parameters
1398 values python:sequence Values that will be returned by
1400 the palette function.
1401 Returns
1403 out function A function palette that takes a single
1405 int parameter n and returns n values.
1406 Examples
1408 >>> palette = manual_pal(['a', 'b', 'c', 'd', 'e'])
1410 >>> palette(3)
1411 ['a', 'b', 'c']
1412 mizani.palettes.xkcd_palette(colors)
1414 Make a palette with color names from the xkcd color survey.
1415 See xkcd for the full list of colors: http://xkcd.com/color/rgb/
1417 Parameters
1419 colors python:list of strings List of keys in the
1421 mizani.external.xkcd_rgb dictionary.
1422 Returns
1424 palette
1426 python:list List of colors as RGB hex strings.
1427 Examples
1429 >>> palette = xkcd_palette(['red', 'green', 'blue'])
1431 >>> palette
1432 ['#e50000', '#15b01a', '#0343df']
1433 >>> from mizani.external import xkcd_rgb
1435 >>> list(sorted(xkcd_rgb.keys()))[:5]
1436 ['acid green', 'adobe', 'algae', 'algae green', 'almost black']
1437 mizani.palettes.crayon_palette(colors)
1439 Make a palette with color names from Crayola crayons.
1440 The colors come from
1442 http://en.wikipedia.org/wiki/List_of_Crayola_crayon_colors
1443 Parameters
1445 colors python:list of strings List of keys in the
1447 mizani.external.crayloax_rgb dictionary.
1448 Returns
1450 palette
1452 python:list List of colors as RGB hex strings.
1453 Examples
1455 >>> palette = crayon_palette(['almond', 'silver', 'yellow'])
1457 >>> palette
1458 ['#eed9c4', '#c9c0bb', '#fbe870']
1459 >>> from mizani.external import crayon_rgb
1461 >>> list(sorted(crayon_rgb.keys()))[:5]
1462 ['almond', 'antique brass', 'apricot', 'aquamarine', 'asparagus']
1463 mizani.palettes.cubehelix_pal(start=0, rot=0.4, gamma=1.0, hue=0.8,
1465 light=0.85, dark=0.15, reverse=False)
1466 Utility for creating continuous palette from the cubehelix sys‐
1467 tem.
1468 This produces a colormap with linearly-decreasing (or increas‐
1470 ing) brightness. That means that information will be preserved
1471 if printed to black and white or viewed by someone who is color‐
1472 blind.
1473 Parameters
1475 start python:float (0 <= start <= 3) The hue at the
1477 start of the helix.
1478 rot python:float Rotations around the hue wheel over
1480 the range of the palette.
1481 gamma python:float (0 <= gamma) Gamma factor to empha‐
1483 size darker (gamma < 1) or lighter (gamma > 1)
1484 colors.
1485 hue python:float (0 <= hue <= 1) Saturation of the
1487 colors.
1488 dark python:float (0 <= dark <= 1) Intensity of the
1490 darkest color in the palette.
1491 light python:float (0 <= light <= 1) Intensity of the
1493 lightest color in the palette.
1494 reverse
1496 bool If True, the palette will go from dark to
1497 light.
1498 Returns
1500 out function Continuous color palette that takes a
1502 single int parameter n and returns n equally
1503 spaced colors.
1504 References
1506 Green, D. A. (2011). "A colour scheme for the display of astro‐
1508 nomical intensity images". Bulletin of the Astromical Society of
1509 India, Vol. 39, p. 289-295.
1510 Examples
1512 >>> palette = cubehelix_pal()
1514 >>> palette(5)
1515 ['#edd1cb', '#d499a7', '#aa688f', '#6e4071', '#2d1e3e']
1516 transforms - Transforming variables, scales and coordinates
1518 "The Grammar of Graphics [4m(2005)" by Wilkinson, Anand and Grossman de‐
1519 scribes three types of transformations.
1520 • Variable transformations - Used to make statistical operations on
1522 variables appropriate and meaningful. They are also used to new vari‐
1523 ables.
1524 • Scale transformations - Used to make statistical objects displayed on
1526 dimensions appropriate and meaningful.
1527 • Coordinate transformations - Used to manipulate the geometry of
1529 graphics to help perceive relationships and find meaningful struc‐
1530 tures for representing variations.
1531 Variable and scale transformations are similar in-that they lead to
1533 plotted objects that are indistinguishable. Typically, variable trans‐
1534 formation is done outside the graphics system and so the system cannot
1535 provide transformation specific guides & decorations for the plot. The
1536 trans is aimed at being useful for scale and coordinate transforma‐
1537 tions.
1538 class mizani.transforms.asn_trans(**kwargs)
1540 Arc-sin square-root Transformation
1541 static transform(x)
1543 Transform of x
1544 static inverse(x)
1546 Inverse of x
1547 class mizani.transforms.atanh_trans(**kwargs)
1549 Arc-tangent Transformation
1550 transform(x, /, out=None, *, where=True, casting='same_kind',
1552 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1553 'arctanh'>
1554 inverse(x, /, out=None, *, where=True, casting='same_kind', or‐
1556 der='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1557 'tanh'>
1558 mizani.transforms.boxcox_trans(p, offset=0, **kwargs)
1560 Boxcox Transformation
1561 The Box-Cox transformation is a flexible transformation, often
1563 used to transform data towards normality.
1564 The Box-Cox power transformation (type 1) requires strictly pos‐
1566 itive values and takes the following form for y \gt 0:
1567 y^{(\lambda)} = \frac{y^\lambda - 1}{\lambda}
1569 When y = 0, the natural log transform is used.
1571 Parameters
1573 p python:float Transformation exponent \lambda.
1575 offset python:int Constant offset. 0 for Box-Cox type 1,
1577 otherwise any non-negative constant (Box-Cox type
1578 2). The default is 0. modulus_trans() sets the
1579 default to 1.
1580 kwargs python:dict Keyword arguments passed onto
1582 trans_new(). Should not include the transform or
1583 inverse.
1584 SEE ALSO:
1586 modulus_trans()
1588 References
1590 • Box, G. E., & Cox, D. R. (1964). An analysis of transforma‐
1592 tions. Journal of the Royal Statistical Society. Series B
1593 (Methodological), 211-252.
1594 https://www.jstor.org/stable/2984418
1595 • John, J. A., & Draper, N. R. (1980). An alternative family of
1597 transformations. Applied Statistics, 190-197.
1598 http://www.jstor.org/stable/2986305
1599 mizani.transforms.modulus_trans(p, offset=1, **kwargs)
1601 Modulus Transformation
1602 The modulus transformation generalises Box-Cox to work with both
1604 positive and negative values.
1605 When y \neq 0
1607 y^{(\lambda)} = sign(y) * \frac{(|y| + 1)^\lambda - 1}{\lambda}
1609 and when y = 0
1611 y^{(\lambda)} = sign(y) * \ln{(|y| + 1)}
1613 Parameters
1615 p python:float Transformation exponent \lambda.
1617 offset python:int Constant offset. 0 for Box-Cox type 1,
1619 otherwise any non-negative constant (Box-Cox type
1620 2). The default is 1. boxcox_trans() sets the de‐
1621 fault to 0.
1622 kwargs python:dict Keyword arguments passed onto
1624 trans_new(). Should not include the transform or
1625 inverse.
1626 SEE ALSO:
1628 boxcox_trans()
1630 References
1632 • Box, G. E., & Cox, D. R. (1964). An analysis of transforma‐
1634 tions. Journal of the Royal Statistical Society. Series B
1635 (Methodological), 211-252.
1636 https://www.jstor.org/stable/2984418
1637 • John, J. A., & Draper, N. R. (1980). An alternative family of
1639 transformations. Applied Statistics, 190-197.
1640 http://www.jstor.org/stable/2986305
1641 class mizani.transforms.datetime_trans(tz=None, **kwargs)
1643 Datetime Transformation
1644 Parameters
1646 tz python:str | ZoneInfo Timezone information
1648 Examples
1650 >>> # from zoneinfo import ZoneInfo
1652 >>> # from backports.zoneinfo import ZoneInfo # for python < 3.9
1653 >>> UTC = ZoneInfo("UTC")
1654 >>> EST = ZoneInfo("EST")
1655 >>> t = datetime_trans(EST)
1656 >>> x = datetime.datetime(2022, 1, 20, tzinfo=UTC)
1657 >>> x2 = t.inverse(t.transform(x))
1658 >>> x == x2
1659 True
1660 >>> x.tzinfo == x2.tzinfo
1661 False
1662 >>> x.tzinfo.key
1663 'UTC'
1664 >>> x2.tzinfo.key
1665 'EST'
1666 dataspace_is_numerical = False
1668 Whether the untransformed data is numerical
1669 domain = (datetime.datetime(1, 1, 1, 0, 0, tzinfo=zoneinfo.Zone‐
1671 Info(key='UTC')), datetime.datetime(9999, 12, 31, 0, 0, tz‐
1672 info=zoneinfo.ZoneInfo(key='UTC')))
1673 Limits of the transformed data
1674 breaks_ = <mizani.breaks.date_breaks object>
1676 Callable to calculate breaks
1677 format = <mizani.formatters.date_format object>
1679 Function to format breaks
1680 transform(x)
1682 Transform from date to a numerical format
1683 inverse(x)
1685 Transform to date from numerical format
1686 property tzinfo
1688 Alias of tz
1689 mizani.transforms.exp_trans(base=None, **kwargs)
1691 Create a exponential transform class for base
1692 This is inverse of the log transform.
1694 Parameters
1696 base python:float Base of the logarithm
1698 kwargs python:dict Keyword arguments passed onto
1700 trans_new(). Should not include the transform or
1701 inverse.
1702 Returns
1704 out type Exponential transform class
1706 class mizani.transforms.identity_trans(**kwargs)
1708 Identity Transformation
1709 class mizani.transforms.log10_trans(**kwargs)
1711 Log 10 Transformation
1712 breaks_ = <mizani.breaks.log_breaks object>
1714 Callable to calculate breaks
1715 domain = (2.2250738585072014e-308, inf)
1717 Limits of the transformed data
1718 format = <mizani.formatters.log_format object>
1720 Function to format breaks
1721 static inverse(x)
1723 Inverse of x
1724 minor_breaks = <mizani.breaks.trans_minor_breaks object>
1726 Callable to calculate minor_breaks
1727 transform(x, /, out=None, *, where=True, casting='same_kind',
1729 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1730 'log10'>
1731 class mizani.transforms.log1p_trans(**kwargs)
1733 Log plus one Transformation
1734 transform(x, /, out=None, *, where=True, casting='same_kind',
1736 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1737 'log1p'>
1738 inverse(x, /, out=None, *, where=True, casting='same_kind', or‐
1740 der='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1741 'expm1'>
1742 class mizani.transforms.log2_trans(**kwargs)
1744 Log 2 Transformation
1745 breaks_ = <mizani.breaks.log_breaks object>
1747 Callable to calculate breaks
1748 domain = (2.2250738585072014e-308, inf)
1750 Limits of the transformed data
1751 format = <mizani.formatters.log_format object>
1753 Function to format breaks
1754 static inverse(x)
1756 Inverse of x
1757 minor_breaks = <mizani.breaks.trans_minor_breaks object>
1759 Callable to calculate minor_breaks
1760 transform(x, /, out=None, *, where=True, casting='same_kind',
1762 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1763 'log2'>
1764 mizani.transforms.log_trans(base=None, **kwargs)
1766 Create a log transform class for base
1767 Parameters
1769 base python:float Base for the logarithm. If None, then
1771 the natural log is used.
1772 kwargs python:dict Keyword arguments passed onto
1774 trans_new(). Should not include the transform or
1775 inverse.
1776 Returns
1778 out type Log transform class
1780 class mizani.transforms.logit_trans(**kwargs)
1782 Logit Transformation
1783 domain = (0, 1)
1785 Limits of the transformed data
1786 static inverse(x)
1788 Inverse of x
1789 static transform(x)
1791 Transform of x
1792 mizani.transforms.probability_trans(distribution, *args, **kwargs)
1794 Probability Transformation
1795 Parameters
1797 distribution
1799 python:str Name of the distribution. Valid distri‐
1800 butions are listed at scipy.stats. Any of the con‐
1801 tinuous or discrete distributions.
1802 args python:tuple Arguments passed to the distribution
1804 functions.
1805 kwargs python:dict Keyword arguments passed to the dis‐
1807 tribution functions.
1808 Notes
1810 Make sure that the distribution is a good enough approximation
1812 for the data. When this is not the case, computations may run
1813 into errors. Absence of any errors does not imply that the dis‐
1814 tribution fits the data.
1815 mizani.transforms.probit_trans
1817 alias of norm_trans
1818 class mizani.transforms.reverse_trans(**kwargs)
1820 Reverse Transformation
1821 transform(x, /, out=None, *, where=True, casting='same_kind',
1823 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1824 'negative'>
1825 inverse(x, /, out=None, *, where=True, casting='same_kind', or‐
1827 der='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1828 'negative'>
1829 class mizani.transforms.sqrt_trans(**kwargs)
1831 Square-root Transformation
1832 transform(x, /, out=None, *, where=True, casting='same_kind',
1834 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1835 'sqrt'>
1836 inverse(x, /, out=None, *, where=True, casting='same_kind', or‐
1838 der='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1839 'square'>
1840 domain = (0, inf)
1842 Limits of the transformed data
1843 class mizani.transforms.timedelta_trans(**kwargs)
1845 Timedelta Transformation
1846 dataspace_is_numerical = False
1848 Whether the untransformed data is numerical
1849 domain = (datetime.timedelta(days=-999999999), date‐
1851 time.timedelta(days=999999999, seconds=86399, microsec‐
1852 onds=999999))
1853 Limits of the transformed data
1854 breaks_ = <mizani.breaks.timedelta_breaks object>
1856 Callable to calculate breaks
1857 format = <mizani.formatters.timedelta_format object>
1859 Function to format breaks
1860 static transform(x)
1862 Transform from Timeddelta to numerical format
1863 static inverse(x)
1865 Transform to Timedelta from numerical format
1866 class mizani.transforms.pd_timedelta_trans(**kwargs)
1868 Pandas timedelta Transformation
1869 dataspace_is_numerical = False
1871 Whether the untransformed data is numerical
1872 domain = (Timedelta('-106752 days +00:12:43.145224193'),
1874 Timedelta('106751 days 23:47:16.854775807'))
1875 Limits of the transformed data
1876 breaks_ = <mizani.breaks.timedelta_breaks object>
1878 Callable to calculate breaks
1879 format = <mizani.formatters.timedelta_format object>
1881 Function to format breaks
1882 static transform(x)
1884 Transform from Timeddelta to numerical format
1885 static inverse(x)
1887 Transform to Timedelta from numerical format
1888 mizani.transforms.pseudo_log_trans(sigma=1, base=None, **kwargs)
1890 Pseudo-log transformation
1891 A transformation mapping numbers to a signed logarithmic scale
1893 with a smooth transition to linear scale around 0.
1894 Parameters
1896 sigma python:float Scaling factor for the linear part.
1898 base python:int Approximate logarithm used. If None,
1900 then the natural log is used.
1901 kwargs python:dict Keyword arguments passed onto
1903 trans_new(). Should not include the transform or
1904 inverse.
1905 class mizani.transforms.reciprocal_trans(**kwargs)
1907 Reciprocal Transformation
1908 static transform(x)
1910 Transform of x
1911 static inverse(x)
1913 Inverse of x
1914 class mizani.transforms.trans(**kwargs)
1916 Base class for all transforms
1917 This class is used to transform data and also tell the x and y
1919 axes how to create and label the tick locations.
1920 The key methods to override are trans.transform() and
1922 trans.inverse(). Alternately, you can quickly create a transform
1923 class using the trans_new() function.
1924 Parameters
1926 kwargs python:dict Attributes of the class to set/over‐
1928 ride
1929 Examples
1931 By default trans returns one minor break between every pair of
1933 major break
1934 >>> major = [0, 1, 2]
1936 >>> t = trans()
1937 >>> t.minor_breaks(major)
1938 array([0.5, 1.5])
1939 Create a trans that returns 4 minor breaks
1941 >>> t = trans(minor_breaks=minor_breaks(4))
1943 >>> t.minor_breaks(major)
1944 array([0.2, 0.4, 0.6, 0.8, 1.2, 1.4, 1.6, 1.8])
1945 aesthetic = None
1947 Aesthetic that the transform works on
1948 dataspace_is_numerical = True
1950 Whether the untransformed data is numerical
1951 domain = (-inf, inf)
1953 Limits of the transformed data
1954 format = <mizani.formatters.mpl_format object>
1956 Function to format breaks
1957 breaks_ = None
1959 Callable to calculate breaks
1960 minor_breaks = None
1962 Callable to calculate minor_breaks
1963 static transform(x)
1965 Transform of x
1966 static inverse(x)
1968 Inverse of x
1969 breaks(limits)
1971 Calculate breaks in data space and return them in trans‐
1972 formed space.
1973 Expects limits to be in transform space, this is the same
1975 space as that where the domain is specified.
1976 This method wraps around breaks_() to ensure that the
1978 calculated breaks are within the domain the transform.
1979 This is helpful in cases where an aesthetic requests
1980 breaks with limits expanded for some padding, yet the ex‐
1981 pansion goes beyond the domain of the transform. e.g for
1982 a probability transform the breaks will be in the domain
1983 [0, 1] despite any outward limits.
1984 Parameters
1986 limits python:tuple The scale limits. Size 2.
1988 Returns
1990 out numpy:array_like Major breaks
1992 mizani.transforms.trans_new(name, transform, inverse, breaks=None, mi‐
1994 nor_breaks=None, _format=None, domain=(- inf, inf), doc='', **kwargs)
1995 Create a transformation class object
1996 Parameters
1998 name python:str Name of the transformation
2000 transform
2002 python:callable() f(x) A function (preferably a
2003 ufunc) that computes the transformation.
2004 inverse
2006 python:callable() f(x) A function (preferably a
2007 ufunc) that computes the inverse of the transfor‐
2008 mation.
2009 breaks python:callable() f(limits) Function to compute
2011 the breaks for this transform. If None, then a
2012 default good enough for a linear domain is used.
2013 minor_breaks
2015 python:callable() f(major, limits) Function to
2016 compute the minor breaks for this transform. If
2017 None, then a default good enough for a linear do‐
2018 main is used.
2019 _format
2021 python:callable() f(breaks) Function to format the
2022 generated breaks.
2023 domain numpy:array_like Domain over which the transforma‐
2025 tion is valid. It should be of length 2.
2026 doc python:str Docstring for the class.
2028 **kwargs
2030 python:dict Attributes of the transform, e.g if
2031 base is passed in kwargs, then t.base would be a
2032 valied attribute.
2033 Returns
2035 out trans Transform class
2037 mizani.transforms.gettrans(t)
2039 Return a trans object
2040 Parameters
2042 t python:str | python:callable() | type | trans name
2044 of transformation function
2045 Returns
2047 out trans.UNINDENT
2049 scale - Implementing a scale
2051 According to On the theory of scales of measurement by S.S. Stevens,
2052 scales can be classified in four ways -- nominal, ordinal, interval and
2053 ratio. Using current(2016) terminology, nominal data is made up of un‐
2054 ordered categories, ordinal data is made up of ordered categories and
2055 the two can be classified as discrete. On the other hand both interval
2056 and ratio data are continuous.
2057 The scale classes below show how the rest of the Mizani package can be
2059 used to implement the two categories of scales. The key tasks are
2060 training and mapping and these correspond to the train and map methods.
2061 To train a scale on data means, to make the scale learn the limits of
2063 the data. This is elaborate (or worthy of a dedicated method) for two
2064 reasons:
2065 • Practical -- data may be split up across more than one object, yet
2067 all will be represented by a single scale.
2068 • Conceptual -- training is a key action that may need to be in‐
2070 serted into multiple locations of the data processing pipeline be‐
2071 fore a graphic can be created.
2072 To map data onto a scale means, to associate data values with val‐
2074 ues(potential readings) on a scale. This is perhaps the most important
2075 concept unpinning a scale.
2076 The apply methods are simple examples of how to put it all together.
2078 class mizani.scale.scale_continuous
2080 Continuous scale
2081 classmethod apply(x, palette, na_value=None, trans=None)
2083 Scale data continuously
2084 Parameters
2086 x numpy:array_like Continuous values to scale
2088 palette
2090 python:callable() f(x) Palette to use
2091 na_value
2093 object Value to use for missing values.
2094 trans trans How to transform the data before
2096 scaling. If None, no transformation is
2097 done.
2098 Returns
2100 out numpy:array_like Scaled values
2102 classmethod train(new_data, old=None)
2104 Train a continuous scale
2105 Parameters
2107 new_data
2109 numpy:array_like New values
2110 old numpy:array_like Old range. Most likely a
2112 tuple of length 2.
2113 Returns
2115 out python:tuple Limits(range) of the scale
2117 classmethod map(x, palette, limits, na_value=None, oob=<function
2119 censor>)
2120 Map values to a continuous palette
2121 Parameters
2123 x numpy:array_like Continuous values to scale
2125 palette
2127 python:callable() f(x) palette to use
2128 na_value
2130 object Value to use for missing values.
2131 oob python:callable() f(x) Function to deal
2133 with values that are beyond the limits
2134 Returns
2136 out numpy:array_like Values mapped onto a pal‐
2138 ette
2139 class mizani.scale.scale_discrete
2141 Discrete scale
2142 classmethod apply(x, palette, na_value=None)
2144 Scale data discretely
2145 Parameters
2147 x numpy:array_like Discrete values to scale
2149 palette
2151 python:callable() f(x) Palette to use
2152 na_value
2154 object Value to use for missing values.
2155 Returns
2157 out numpy:array_like Scaled values
2159 classmethod train(new_data, old=None, drop=False, na_rm=False)
2161 Train a continuous scale
2162 Parameters
2164 new_data
2166 numpy:array_like New values
2167 old numpy:array_like Old range. List of values
2169 known to the scale.
2170 drop bool Whether to drop(not include) unused
2172 categories
2173 na_rm bool If True, remove missing values. Miss‐
2175 ing values are either NaN or None.
2176 Returns
2178 out python:list Values covered by the scale
2180 classmethod map(x, palette, limits, na_value=None)
2182 Map values to a discrete palette
2183 Parameters
2185 palette
2187 python:callable() f(x) palette to use
2188 x numpy:array_like Continuous values to scale
2190 na_value
2192 object Value to use for missing values.
2193 Returns
2195 out numpy:array_like Values mapped onto a pal‐
2197 ette
2198 Installation
2200 mizani can be can be installed in a couple of ways depending on pur‐
2201 pose.
2202 Official release installation
2204 For a normal user, it is recommended to install the official release.
2205 $ pip install mizani
2207 Development installation
2209 To do any development you have to clone the mizani source repository
2210 and install the package in development mode. These commands do all of
2211 that:
2212 $ git clone https://github.com/has2k1/mizani.git
2214 $ cd mizani
2215 $ pip install -e .
2216 If you only want to use the latest development sources and do not care
2218 about having a cloned repository, e.g. if a bug you care about has been
2219 fixed but an official release has not come out yet, then use this com‐
2220 mand:
2221 $ pip install git+https://github.com/has2k1/mizani.git
2223 Changelog
2225 v0.8.1
2226 2022-09-28
2227 Bug Fixes
2229 • Fixed regression bug in log_format for where formatting for bases 2,
2230 8 and 16 would fail if the values were float-integers.
2231 Enhancements
2233 • log_format now uses exponent notation for bases other than base 10.
2234 v0.8.0
2236 2022-09-26
2237 API Changes
2239 • The lut parameter of cmap_pal and cmap_d_pal has been deprecated and
2240 will removed in a future version.
2241 • datetime_trans gained parameter tz that controls the timezone of the
2243 transformation.
2244 • log_format gained boolean parameter mathtex for TeX values as under‐
2246 stood matplotlib instead of values in scientific notation.
2247 Bug Fixes
2249 • Fixed bug in zero_range where uint64 values would cause a RuntimeEr‐
2250 ror.
2251 v0.7.4
2253 2022-04-02 .SS API Changes
2254 • comma_format is now imported automatically when using *.
2256 • Fixed issue with scale_discrete so that if you train on data with Nan
2258 and specify and old range that also has NaN, the result range does
2259 not include two NaN values.
2260 v0.7.3
2262 (2020-10-29) .SS Bug Fixes
2263 • Fixed log_breaks for narrow range if base=2 (GH76).
2265 v0.7.2
2267 (2020-10-29) .SS Bug Fixes
2268 • Fixed bug in rescale_max() to properly handle values whose maximum is
2270 zero (GH16).
2271 v0.7.1
2273 (2020-06-05) .SS Bug Fixes
2274 • Fixed regression in mizani.scales.scale_discrete.train() when train‐
2276 ning on values with some categoricals that have common elements.
2277 v0.7.0
2279 (2020-06-04) .SS Bug Fixes
2280 • Fixed issue with mizani.formatters.log_breaks where non-linear breaks
2282 could not be generated if the limits where greater than the largest
2283 integer sys.maxsize.
2284 • Fixed mizani.palettes.gradient_n_pal() to return nan for nan values.
2286 • Fixed mizani.scales.scale_discrete.train() when training categoricals
2288 to maintain the order. (plotnine #381)
2289 v0.6.0
2291 (2019-08-15) .SS New
2292 • Added pvalue_format
2294 • Added ordinal_format
2296 • Added number_bytes_format
2298 • Added pseudo_log_trans()
2300 • Added reciprocal_trans
2302 • Added modulus_trans()
2304 Enhancements
2306 •
2307 mizani.breaks.date_breaks now supports intervals in the
2309 order of seconds.
2310 • mizani.palettes.brewer_pal now supports a direction argument to con‐
2312 trol the order of the returned colors.
2313 API Changes
2315 • boxcox_trans() now only accepts positive values. For both positive
2316 and negative values, modulus_trans() has been added.
2317 v0.5.4
2319 (2019-03-26) .SS Enhancements
2320 • mizani.formatters.log_format now does a better job of approximating
2322 labels for numbers like 3.000000000000001e-05.
2323 API Changes
2325 • exponent_threshold parameter of mizani.formatters.log_format has been
2326 deprecated.
2327 v0.5.3
2329 (2018-12-24) .SS API Changes
2330 • Log transforms now default to base - 2 minor breaks. So base 10 has
2332 8 minor breaks and 9 partitions, base 8 has 6 minor breaks and 7 par‐
2333 titions, ..., base 2 has 0 minor breaks and a single partition.
2334 v0.5.2
2336 (2018-10-17) .SS Bug Fixes
2337 • Fixed issue where some functions that took pandas series would return
2339 output where the index did not match that of the input.
2340 v0.5.1
2342 (2018-10-15) .SS Bug Fixes
2343 • Fixed issue with log_breaks, so that it does not fail needlessly when
2345 the limits in the (0, 1) range.
2346 Enhancements
2348 • Changed log_format to return better formatted breaks.
2349 v0.5.0
2351 (2018-11-10) .SS API Changes
2352 • Support for python 2 has been removed.
2354 •
2356 call() and
2358 meth:~mizani.breaks.trans_minor_breaks.call now accept op‐
2359 tional parameter n which is the number of minor breaks between
2360 any two major breaks.
2361 • The parameter nan_value has be renamed to na_value.
2363 • The parameter nan_rm has be renamed to na_rm.
2365 Enhancements
2367 • Better support for handling missing values when training discrete
2368 scales.
2369 • Changed the algorithm for log_breaks, it can now return breaks that
2371 do not fall on the integer powers of the base.
2372 v0.4.6
2374 (2018-03-20) .INDENT 0.0
2375 • Added squish
2377 v0.4.5
2379 (2018-03-09) .INDENT 0.0
2380 • Added identity_pal
2382 • Added cmap_d_pal
2384 v0.4.4
2386 (2017-12-13) .INDENT 0.0
2387 • Fixed date_format to respect the timezones of the dates (GH8).
2389 v0.4.3
2391 (2017-12-01) .INDENT 0.0
2392 • Changed date_breaks to have more variety in the spacing between the
2394 breaks.
2395 • Fixed date_format to respect time part of the date (GH7).
2397 v0.4.2
2399 (2017-11-06) .INDENT 0.0
2400 • Fixed (regression) break calculation for the non ordinal transforms.
2402 v0.4.1
2404 (2017-11-04) .INDENT 0.0
2405 • trans objects can now be instantiated with parameter to override at‐
2407 tributes of the instance. And the default methods for computing
2408 breaks and minor breaks on the transform instance are not class at‐
2409 tributes, so they can be modified without global repercussions.
2410 v0.4.0
2412 (2017-10-24) .SS API Changes
2413 • Breaks and formatter generating functions have been converted to
2415 classes, with a __call__ method. How they are used has not changed,
2416 but this makes them move flexible.
2417 • ExtendedWilkson class has been removed. extended_breaks() now con‐
2419 tains the implementation of the break calculating algorithm.
2420 v0.3.4
2422 (2017-09-12) .INDENT 0.0
2423 • Fixed issue where some formatters methods failed if passed empty
2425 breaks argument.
2426 • Fixed issue with log_breaks() where if the limits were with in the
2428 same order of magnitude the calculated breaks were always the ends of
2429 the order of magnitude.
2430 Now log_breaks()((35, 50)) returns [35, 40, 45, 50] as breaks in‐
2432 stead of [1, 100].
2433 v0.3.3
2435 (2017-08-30) .INDENT 0.0
2436 • Fixed SettingWithCopyWarnings in squish_infinite().
2438 • Added log_format().
2440 API Changes
2442 • Added log_trans now uses log_format() as the formatting method.
2443 v0.3.2
2445 (2017-07-14) .INDENT 0.0
2446 • Added expand_range_distinct()
2448 v0.3.1
2450 (2017-06-22) .INDENT 0.0
2451 • Fixed bug where using log_breaks() with Numpy 1.13.0 led to a Val‐
2453 ueError.
2454 v0.3.0
2456 (2017-04-24) .INDENT 0.0
2457 • Added xkcd_palette(), a palette that selects from 954 named colors.
2459 • Added crayon_palette(), a palette that selects from 163 named colors.
2461 • Added cubehelix_pal(), a function that creates a continuous palette
2463 from the cubehelix system.
2464 • Fixed bug where a color palette would raise an exception when passed
2466 a single scalar value instead of a list-like.
2467 • extended_breaks() and mpl_breaks() now return a single break if the
2469 limits are equal. Previous, one run into an Overflow and the other
2470 returned a sequence filled with n of the same limit.
2471 API Changes
2473 • mpl_breaks() now returns a function that (strictly) expects a tuple
2474 with the minimum and maximum values.
2475 v0.2.0
2477 (2017-01-27) .INDENT 0.0
2478 • Fixed bug in censor() where a sequence of values with an irregular
2480 index would lead to an exception.
2481 • Fixed boundary issues due internal loss of precision in ported func‐
2483 tion seq().
2484 • Added mizani.breaks.extended_breaks() which computes breaks using a
2486 modified version of Wilkinson's tick algorithm.
2487 • Changed the default function mizani.transforms.trans.breaks_() used
2489 by mizani.transforms.trans to compute breaks from
2490 mizani.breaks.mpl_breaks() to mizani.breaks.extended_breaks().
2491 • mizani.breaks.timedelta_breaks() now uses
2493 mizani.breaks.extended_breaks() internally instead of
2494 mizani.breaks.mpl_breaks().
2495 • Added manual palette function mizani.palettes.manual_pal().
2497 • Requires pandas version 0.19.0 or higher.
2499 v0.1.0
2501 (2016-06-30)
2502 First public release
2504
2506 Hassan Kibirige
2507
2509 2022, Hassan Kibirige
25100.8.1 Oct 21, 2022 MIZANI(1)