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: ColorScheme | ColorSchemeShort =
1240 'seq', palette: int = 1, direction: Literal[1, -1] = 1)
1241 Utility for making a brewer palette
1242 Parameters
1244 type 'sequential' | 'qualitative' | 'diverging' Type of
1246 palette. Sequential, Qualitative or Diverging. The
1247 following abbreviations may be used, seq, qual or
1248 div.
1249 palette
1251 python:int | python:str Which palette to choose
1252 from. If is an integer, it must be in the range
1253 [0, m], where m depends on the number sequential,
1254 qualitative or diverging palettes. If it is a
1255 string, then it is the name of the palette.
1256 direction
1258 python:int The order of colours in the scale. If
1259 -1 the order of colors is reversed. The default is
1260 1.
1261 Returns
1263 out function A color palette that takes a single int
1265 parameter n and returns n colors. The maximum
1266 value of n varies depending on the parameters.
1267 Examples
1269 >>> brewer_pal()(5)
1271 ['#EFF3FF', '#BDD7E7', '#6BAED6', '#3182BD', '#08519C']
1272 >>> brewer_pal('qual')(5)
1273 ['#7FC97F', '#BEAED4', '#FDC086', '#FFFF99', '#386CB0']
1274 >>> brewer_pal('qual', 2)(5)
1275 ['#1B9E77', '#D95F02', '#7570B3', '#E7298A', '#66A61E']
1276 >>> brewer_pal('seq', 'PuBuGn')(5)
1277 ['#F6EFF7', '#BDC9E1', '#67A9CF', '#1C9099', '#016C59']
1278 The available color names for each palette type can be obtained
1280 using the following code:
1281 from mizani.colors.brewer import get_palette_names
1283 print(get_palette_names("sequential"))
1285 print(get_palette_names("qualitative"))
1286 print(get_palette_names("diverging"))
1287 mizani.palettes.gradient_n_pal(colors, values=None, name='gradientn')
1289 Create a n color gradient palette
1290 Parameters
1292 colors python:list list of colors
1294 values python:list, optional list of points in the range
1296 [0, 1] at which to place each color. Must be the
1297 same size as colors. Default to evenly space the
1298 colors
1299 name python:str Name to call the resultant MPL colormap
1301 Returns
1303 out function Continuous color palette that takes a
1305 single parameter either a float or a sequence of
1306 floats maps those value(s) onto the palette and
1307 returns color(s). The float(s) must be in the
1308 range [0, 1].
1309 Examples
1311 >>> palette = gradient_n_pal(['red', 'blue'])
1313 >>> palette([0, .25, .5, .75, 1])
1314 ['#ff0000', '#bf0040', '#7f0080', '#3f00c0', '#0000ff']
1315 >>> palette([-np.inf, 0, np.nan, 1, np.inf])
1316 [nan, '#ff0000', nan, '#0000ff', nan]
1317 mizani.palettes.cmap_pal(name, lut=None)
1319 Create a continuous palette using an MPL colormap
1320 Parameters
1322 name python:str Name of colormap
1324 lut python:None | python:int This is the number of en‐
1326 tries desired in the lookup table. Default is
1327 None, leave it up Matplotlib.
1328 Returns
1330 out function Continuous color palette that takes a
1332 single parameter either a float or a sequence of
1333 floats maps those value(s) onto the palette and
1334 returns color(s). The float(s) must be in the
1335 range [0, 1].
1336 Examples
1338 >>> palette = cmap_pal('viridis')
1340 >>> palette([.1, .2, .3, .4, .5])
1341 ['#482475', '#414487', '#355f8d', '#2a788e', '#21918c']
1342 mizani.palettes.cmap_d_pal(name, lut=None)
1344 Create a discrete palette using an MPL Listed colormap
1345 Parameters
1347 name python:str Name of colormap
1349 lut python:None | python:int This is the number of en‐
1351 tries desired in the lookup table. Default is
1352 None, leave it up Matplotlib.
1353 Returns
1355 out function A discrete color palette that takes a
1357 single int parameter n and returns n colors. The
1358 maximum value of n varies depending on the parame‐
1359 ters.
1360 Examples
1362 >>> palette = cmap_d_pal('viridis')
1364 >>> palette(5)
1365 ['#440154', '#3b528b', '#21918c', '#5cc863', '#fde725']
1366 mizani.palettes.desaturate_pal(color, prop, reverse=False)
1368 Create a palette that desaturate a color by some proportion
1369 Parameters
1371 color matplotlib color hex, rgb-tuple, or html color
1373 name
1374 prop python:float saturation channel of color will be
1376 multiplied by this value
1377 reverse
1379 bool Whether to reverse the palette.
1380 Returns
1382 out function Continuous color palette that takes a
1384 single parameter either a float or a sequence of
1385 floats maps those value(s) onto the palette and
1386 returns color(s). The float(s) must be in the
1387 range [0, 1].
1388 Examples
1390 >>> palette = desaturate_pal('red', .1)
1392 >>> palette([0, .25, .5, .75, 1])
1393 ['#ff0000', '#e21d1d', '#c53a3a', '#a95656', '#8c7373']
1394 mizani.palettes.manual_pal(values)
1396 Create a palette from a list of values
1397 Parameters
1399 values python:sequence Values that will be returned by
1401 the palette function.
1402 Returns
1404 out function A function palette that takes a single
1406 int parameter n and returns n values.
1407 Examples
1409 >>> palette = manual_pal(['a', 'b', 'c', 'd', 'e'])
1411 >>> palette(3)
1412 ['a', 'b', 'c']
1413 mizani.palettes.xkcd_palette(colors)
1415 Make a palette with color names from the xkcd color survey.
1416 See xkcd for the full list of colors: http://xkcd.com/color/rgb/
1418 Parameters
1420 colors python:list of strings List of keys in the
1422 mizani.external.xkcd_rgb dictionary.
1423 Returns
1425 palette
1427 python:list List of colors as RGB hex strings.
1428 Examples
1430 >>> palette = xkcd_palette(['red', 'green', 'blue'])
1432 >>> palette
1433 ['#e50000', '#15b01a', '#0343df']
1434 >>> from mizani.external import xkcd_rgb
1436 >>> list(sorted(xkcd_rgb.keys()))[:5]
1437 ['acid green', 'adobe', 'algae', 'algae green', 'almost black']
1438 mizani.palettes.crayon_palette(colors)
1440 Make a palette with color names from Crayola crayons.
1441 The colors come from
1443 http://en.wikipedia.org/wiki/List_of_Crayola_crayon_colors
1444 Parameters
1446 colors python:list of strings List of keys in the
1448 mizani.external.crayloax_rgb dictionary.
1449 Returns
1451 palette
1453 python:list List of colors as RGB hex strings.
1454 Examples
1456 >>> palette = crayon_palette(['almond', 'silver', 'yellow'])
1458 >>> palette
1459 ['#eed9c4', '#c9c0bb', '#fbe870']
1460 >>> from mizani.external import crayon_rgb
1462 >>> list(sorted(crayon_rgb.keys()))[:5]
1463 ['almond', 'antique brass', 'apricot', 'aquamarine', 'asparagus']
1464 mizani.palettes.cubehelix_pal(start=0, rot=0.4, gamma=1.0, hue=0.8,
1466 light=0.85, dark=0.15, reverse=False)
1467 Utility for creating continuous palette from the cubehelix sys‐
1468 tem.
1469 This produces a colormap with linearly-decreasing (or increas‐
1471 ing) brightness. That means that information will be preserved
1472 if printed to black and white or viewed by someone who is color‐
1473 blind.
1474 Parameters
1476 start python:float (0 <= start <= 3) The hue at the
1478 start of the helix.
1479 rot python:float Rotations around the hue wheel over
1481 the range of the palette.
1482 gamma python:float (0 <= gamma) Gamma factor to empha‐
1484 size darker (gamma < 1) or lighter (gamma > 1)
1485 colors.
1486 hue python:float (0 <= hue <= 1) Saturation of the
1488 colors.
1489 dark python:float (0 <= dark <= 1) Intensity of the
1491 darkest color in the palette.
1492 light python:float (0 <= light <= 1) Intensity of the
1494 lightest color in the palette.
1495 reverse
1497 bool If True, the palette will go from dark to
1498 light.
1499 Returns
1501 out function Continuous color palette that takes a
1503 single int parameter n and returns n equally
1504 spaced colors.
1505 References
1507 Green, D. A. (2011). "A colour scheme for the display of astro‐
1509 nomical intensity images". Bulletin of the Astromical Society of
1510 India, Vol. 39, p. 289-295.
1511 Examples
1513 >>> palette = cubehelix_pal()
1515 >>> palette(5)
1516 ['#edd1cb', '#d499a7', '#aa688f', '#6e4071', '#2d1e3e']
1517 transforms - Transforming variables, scales and coordinates
1519 "The Grammar of Graphics [4m(2005)" by Wilkinson, Anand and Grossman de‐
1520 scribes three types of transformations.
1521 • Variable transformations - Used to make statistical operations on
1523 variables appropriate and meaningful. They are also used to new vari‐
1524 ables.
1525 • Scale transformations - Used to make statistical objects displayed on
1527 dimensions appropriate and meaningful.
1528 • Coordinate transformations - Used to manipulate the geometry of
1530 graphics to help perceive relationships and find meaningful struc‐
1531 tures for representing variations.
1532 Variable and scale transformations are similar in-that they lead to
1534 plotted objects that are indistinguishable. Typically, variable trans‐
1535 formation is done outside the graphics system and so the system cannot
1536 provide transformation specific guides & decorations for the plot. The
1537 trans is aimed at being useful for scale and coordinate transforma‐
1538 tions.
1539 class mizani.transforms.asn_trans(**kwargs)
1541 Arc-sin square-root Transformation
1542 static transform(x)
1544 Transform of x
1545 static inverse(x)
1547 Inverse of x
1548 class mizani.transforms.atanh_trans(**kwargs)
1550 Arc-tangent Transformation
1551 transform(x, /, out=None, *, where=True, casting='same_kind',
1553 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1554 'arctanh'>
1555 inverse(x, /, out=None, *, where=True, casting='same_kind', or‐
1557 der='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1558 'tanh'>
1559 mizani.transforms.boxcox_trans(p, offset=0, **kwargs)
1561 Boxcox Transformation
1562 The Box-Cox transformation is a flexible transformation, often
1564 used to transform data towards normality.
1565 The Box-Cox power transformation (type 1) requires strictly pos‐
1567 itive values and takes the following form for y \gt 0:
1568 y^{(\lambda)} = \frac{y^\lambda - 1}{\lambda}
1570 When y = 0, the natural log transform is used.
1572 Parameters
1574 p python:float Transformation exponent \lambda.
1576 offset python:int Constant offset. 0 for Box-Cox type 1,
1578 otherwise any non-negative constant (Box-Cox type
1579 2). The default is 0. modulus_trans() sets the
1580 default to 1.
1581 kwargs python:dict Keyword arguments passed onto
1583 trans_new(). Should not include the transform or
1584 inverse.
1585 SEE ALSO:
1587 modulus_trans()
1589 References
1591 • Box, G. E., & Cox, D. R. (1964). An analysis of transforma‐
1593 tions. Journal of the Royal Statistical Society. Series B
1594 (Methodological), 211-252.
1595 https://www.jstor.org/stable/2984418
1596 • John, J. A., & Draper, N. R. (1980). An alternative family of
1598 transformations. Applied Statistics, 190-197.
1599 http://www.jstor.org/stable/2986305
1600 mizani.transforms.modulus_trans(p, offset=1, **kwargs)
1602 Modulus Transformation
1603 The modulus transformation generalises Box-Cox to work with both
1605 positive and negative values.
1606 When y \neq 0
1608 y^{(\lambda)} = sign(y) * \frac{(|y| + 1)^\lambda - 1}{\lambda}
1610 and when y = 0
1612 y^{(\lambda)} = sign(y) * \ln{(|y| + 1)}
1614 Parameters
1616 p python:float Transformation exponent \lambda.
1618 offset python:int Constant offset. 0 for Box-Cox type 1,
1620 otherwise any non-negative constant (Box-Cox type
1621 2). The default is 1. boxcox_trans() sets the de‐
1622 fault to 0.
1623 kwargs python:dict Keyword arguments passed onto
1625 trans_new(). Should not include the transform or
1626 inverse.
1627 SEE ALSO:
1629 boxcox_trans()
1631 References
1633 • Box, G. E., & Cox, D. R. (1964). An analysis of transforma‐
1635 tions. Journal of the Royal Statistical Society. Series B
1636 (Methodological), 211-252.
1637 https://www.jstor.org/stable/2984418
1638 • John, J. A., & Draper, N. R. (1980). An alternative family of
1640 transformations. Applied Statistics, 190-197.
1641 http://www.jstor.org/stable/2986305
1642 class mizani.transforms.datetime_trans(tz=None, **kwargs)
1644 Datetime Transformation
1645 Parameters
1647 tz python:str | ZoneInfo Timezone information
1649 Examples
1651 >>> # from zoneinfo import ZoneInfo
1653 >>> # from backports.zoneinfo import ZoneInfo # for python < 3.9
1654 >>> UTC = ZoneInfo("UTC")
1655 >>> EST = ZoneInfo("EST")
1656 >>> t = datetime_trans(EST)
1657 >>> x = datetime.datetime(2022, 1, 20, tzinfo=UTC)
1658 >>> x2 = t.inverse(t.transform(x))
1659 >>> x == x2
1660 True
1661 >>> x.tzinfo == x2.tzinfo
1662 False
1663 >>> x.tzinfo.key
1664 'UTC'
1665 >>> x2.tzinfo.key
1666 'EST'
1667 dataspace_is_numerical = False
1669 Whether the untransformed data is numerical
1670 domain = (datetime.datetime(1, 1, 1, 0, 0, tzinfo=zoneinfo.Zone‐
1672 Info(key='UTC')), datetime.datetime(9999, 12, 31, 0, 0, tz‐
1673 info=zoneinfo.ZoneInfo(key='UTC')))
1674 Limits of the transformed data
1675 breaks_ = <mizani.breaks.date_breaks object>
1677 Callable to calculate breaks
1678 format = <mizani.formatters.date_format object>
1680 Function to format breaks
1681 transform(x)
1683 Transform from date to a numerical format
1684 inverse(x)
1686 Transform to date from numerical format
1687 property tzinfo
1689 Alias of tz
1690 mizani.transforms.exp_trans(base=None, **kwargs)
1692 Create a exponential transform class for base
1693 This is inverse of the log transform.
1695 Parameters
1697 base python:float Base of the logarithm
1699 kwargs python:dict Keyword arguments passed onto
1701 trans_new(). Should not include the transform or
1702 inverse.
1703 Returns
1705 out type Exponential transform class
1707 class mizani.transforms.identity_trans(**kwargs)
1709 Identity Transformation
1710 class mizani.transforms.log10_trans(**kwargs)
1712 Log 10 Transformation
1713 breaks_ = <mizani.breaks.log_breaks object>
1715 Callable to calculate breaks
1716 domain = (2.2250738585072014e-308, inf)
1718 Limits of the transformed data
1719 format = <mizani.formatters.log_format object>
1721 Function to format breaks
1722 static inverse(x)
1724 Inverse of x
1725 minor_breaks = <mizani.breaks.trans_minor_breaks object>
1727 Callable to calculate minor_breaks
1728 transform(x, /, out=None, *, where=True, casting='same_kind',
1730 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1731 'log10'>
1732 class mizani.transforms.log1p_trans(**kwargs)
1734 Log plus one Transformation
1735 transform(x, /, out=None, *, where=True, casting='same_kind',
1737 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1738 'log1p'>
1739 inverse(x, /, out=None, *, where=True, casting='same_kind', or‐
1741 der='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1742 'expm1'>
1743 class mizani.transforms.log2_trans(**kwargs)
1745 Log 2 Transformation
1746 breaks_ = <mizani.breaks.log_breaks object>
1748 Callable to calculate breaks
1749 domain = (2.2250738585072014e-308, inf)
1751 Limits of the transformed data
1752 format = <mizani.formatters.log_format object>
1754 Function to format breaks
1755 static inverse(x)
1757 Inverse of x
1758 minor_breaks = <mizani.breaks.trans_minor_breaks object>
1760 Callable to calculate minor_breaks
1761 transform(x, /, out=None, *, where=True, casting='same_kind',
1763 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1764 'log2'>
1765 mizani.transforms.log_trans(base=None, **kwargs)
1767 Create a log transform class for base
1768 Parameters
1770 base python:float Base for the logarithm. If None, then
1772 the natural log is used.
1773 kwargs python:dict Keyword arguments passed onto
1775 trans_new(). Should not include the transform or
1776 inverse.
1777 Returns
1779 out type Log transform class
1781 class mizani.transforms.logit_trans(**kwargs)
1783 Logit Transformation
1784 domain = (0, 1)
1786 Limits of the transformed data
1787 static inverse(x)
1789 Inverse of x
1790 static transform(x)
1792 Transform of x
1793 mizani.transforms.probability_trans(distribution, *args, **kwargs)
1795 Probability Transformation
1796 Parameters
1798 distribution
1800 python:str Name of the distribution. Valid distri‐
1801 butions are listed at scipy.stats. Any of the con‐
1802 tinuous or discrete distributions.
1803 args python:tuple Arguments passed to the distribution
1805 functions.
1806 kwargs python:dict Keyword arguments passed to the dis‐
1808 tribution functions.
1809 Notes
1811 Make sure that the distribution is a good enough approximation
1813 for the data. When this is not the case, computations may run
1814 into errors. Absence of any errors does not imply that the dis‐
1815 tribution fits the data.
1816 mizani.transforms.probit_trans
1818 alias of norm_trans
1819 class mizani.transforms.reverse_trans(**kwargs)
1821 Reverse Transformation
1822 transform(x, /, out=None, *, where=True, casting='same_kind',
1824 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1825 'negative'>
1826 inverse(x, /, out=None, *, where=True, casting='same_kind', or‐
1828 der='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1829 'negative'>
1830 class mizani.transforms.sqrt_trans(**kwargs)
1832 Square-root Transformation
1833 transform(x, /, out=None, *, where=True, casting='same_kind',
1835 order='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1836 'sqrt'>
1837 inverse(x, /, out=None, *, where=True, casting='same_kind', or‐
1839 der='K', dtype=None, subok=True[, signature, extobj]) = <ufunc
1840 'square'>
1841 domain = (0, inf)
1843 Limits of the transformed data
1844 class mizani.transforms.timedelta_trans(**kwargs)
1846 Timedelta Transformation
1847 dataspace_is_numerical = False
1849 Whether the untransformed data is numerical
1850 domain = (datetime.timedelta(days=-999999999), date‐
1852 time.timedelta(days=999999999, seconds=86399, microsec‐
1853 onds=999999))
1854 Limits of the transformed data
1855 breaks_ = <mizani.breaks.timedelta_breaks object>
1857 Callable to calculate breaks
1858 format = <mizani.formatters.timedelta_format object>
1860 Function to format breaks
1861 static transform(x)
1863 Transform from Timeddelta to numerical format
1864 static inverse(x)
1866 Transform to Timedelta from numerical format
1867 class mizani.transforms.pd_timedelta_trans(**kwargs)
1869 Pandas timedelta Transformation
1870 dataspace_is_numerical = False
1872 Whether the untransformed data is numerical
1873 domain = (Timedelta('-106752 days +00:12:43.145224193'),
1875 Timedelta('106751 days 23:47:16.854775807'))
1876 Limits of the transformed data
1877 breaks_ = <mizani.breaks.timedelta_breaks object>
1879 Callable to calculate breaks
1880 format = <mizani.formatters.timedelta_format object>
1882 Function to format breaks
1883 static transform(x)
1885 Transform from Timeddelta to numerical format
1886 static inverse(x)
1888 Transform to Timedelta from numerical format
1889 mizani.transforms.pseudo_log_trans(sigma=1, base=None, **kwargs)
1891 Pseudo-log transformation
1892 A transformation mapping numbers to a signed logarithmic scale
1894 with a smooth transition to linear scale around 0.
1895 Parameters
1897 sigma python:float Scaling factor for the linear part.
1899 base python:int Approximate logarithm used. If None,
1901 then the natural log is used.
1902 kwargs python:dict Keyword arguments passed onto
1904 trans_new(). Should not include the transform or
1905 inverse.
1906 class mizani.transforms.reciprocal_trans(**kwargs)
1908 Reciprocal Transformation
1909 static transform(x)
1911 Transform of x
1912 static inverse(x)
1914 Inverse of x
1915 class mizani.transforms.trans(**kwargs)
1917 Base class for all transforms
1918 This class is used to transform data and also tell the x and y
1920 axes how to create and label the tick locations.
1921 The key methods to override are trans.transform() and
1923 trans.inverse(). Alternately, you can quickly create a transform
1924 class using the trans_new() function.
1925 Parameters
1927 kwargs python:dict Attributes of the class to set/over‐
1929 ride
1930 Examples
1932 By default trans returns one minor break between every pair of
1934 major break
1935 >>> major = [0, 1, 2]
1937 >>> t = trans()
1938 >>> t.minor_breaks(major)
1939 array([0.5, 1.5])
1940 Create a trans that returns 4 minor breaks
1942 >>> t = trans(minor_breaks=minor_breaks(4))
1944 >>> t.minor_breaks(major)
1945 array([0.2, 0.4, 0.6, 0.8, 1.2, 1.4, 1.6, 1.8])
1946 aesthetic = None
1948 Aesthetic that the transform works on
1949 dataspace_is_numerical = True
1951 Whether the untransformed data is numerical
1952 domain = (-inf, inf)
1954 Limits of the transformed data
1955 format = <mizani.formatters.mpl_format object>
1957 Function to format breaks
1958 breaks_ = None
1960 Callable to calculate breaks
1961 minor_breaks = None
1963 Callable to calculate minor_breaks
1964 static transform(x)
1966 Transform of x
1967 static inverse(x)
1969 Inverse of x
1970 breaks(limits)
1972 Calculate breaks in data space and return them in trans‐
1973 formed space.
1974 Expects limits to be in transform space, this is the same
1976 space as that where the domain is specified.
1977 This method wraps around breaks_() to ensure that the
1979 calculated breaks are within the domain the transform.
1980 This is helpful in cases where an aesthetic requests
1981 breaks with limits expanded for some padding, yet the ex‐
1982 pansion goes beyond the domain of the transform. e.g for
1983 a probability transform the breaks will be in the domain
1984 [0, 1] despite any outward limits.
1985 Parameters
1987 limits python:tuple The scale limits. Size 2.
1989 Returns
1991 out numpy:array_like Major breaks
1993 mizani.transforms.trans_new(name, transform, inverse, breaks=None, mi‐
1995 nor_breaks=None, _format=None, domain=(-inf, inf), doc='', **kwargs)
1996 Create a transformation class object
1997 Parameters
1999 name python:str Name of the transformation
2001 transform
2003 python:callable() f(x) A function (preferably a
2004 ufunc) that computes the transformation.
2005 inverse
2007 python:callable() f(x) A function (preferably a
2008 ufunc) that computes the inverse of the transfor‐
2009 mation.
2010 breaks python:callable() f(limits) Function to compute
2012 the breaks for this transform. If None, then a
2013 default good enough for a linear domain is used.
2014 minor_breaks
2016 python:callable() f(major, limits) Function to
2017 compute the minor breaks for this transform. If
2018 None, then a default good enough for a linear do‐
2019 main is used.
2020 _format
2022 python:callable() f(breaks) Function to format the
2023 generated breaks.
2024 domain numpy:array_like Domain over which the transforma‐
2026 tion is valid. It should be of length 2.
2027 doc python:str Docstring for the class.
2029 **kwargs
2031 python:dict Attributes of the transform, e.g if
2032 base is passed in kwargs, then t.base would be a
2033 valied attribute.
2034 Returns
2036 out trans Transform class
2038 mizani.transforms.gettrans(t)
2040 Return a trans object
2041 Parameters
2043 t python:str | python:callable() | type | trans name
2045 of transformation function
2046 Returns
2048 out trans.UNINDENT
2050 scale - Implementing a scale
2052 According to On the theory of scales of measurement by S.S. Stevens,
2053 scales can be classified in four ways -- nominal, ordinal, interval and
2054 ratio. Using current(2016) terminology, nominal data is made up of un‐
2055 ordered categories, ordinal data is made up of ordered categories and
2056 the two can be classified as discrete. On the other hand both interval
2057 and ratio data are continuous.
2058 The scale classes below show how the rest of the Mizani package can be
2060 used to implement the two categories of scales. The key tasks are
2061 training and mapping and these correspond to the train and map methods.
2062 To train a scale on data means, to make the scale learn the limits of
2064 the data. This is elaborate (or worthy of a dedicated method) for two
2065 reasons:
2066 • Practical -- data may be split up across more than one object, yet
2068 all will be represented by a single scale.
2069 • Conceptual -- training is a key action that may need to be in‐
2071 serted into multiple locations of the data processing pipeline be‐
2072 fore a graphic can be created.
2073 To map data onto a scale means, to associate data values with val‐
2075 ues(potential readings) on a scale. This is perhaps the most important
2076 concept unpinning a scale.
2077 The apply methods are simple examples of how to put it all together.
2079 class mizani.scale.scale_continuous
2081 Continuous scale
2082 classmethod apply(x, palette, na_value=None, trans=None)
2084 Scale data continuously
2085 Parameters
2087 x numpy:array_like Continuous values to scale
2089 palette
2091 python:callable() f(x) Palette to use
2092 na_value
2094 object Value to use for missing values.
2095 trans trans How to transform the data before
2097 scaling. If None, no transformation is
2098 done.
2099 Returns
2101 out numpy:array_like Scaled values
2103 classmethod train(new_data, old=None)
2105 Train a continuous scale
2106 Parameters
2108 new_data
2110 numpy:array_like New values
2111 old numpy:array_like Old range. Most likely a
2113 tuple of length 2.
2114 Returns
2116 out python:tuple Limits(range) of the scale
2118 classmethod map(x, palette, limits, na_value=None, oob=<function
2120 censor>)
2121 Map values to a continuous palette
2122 Parameters
2124 x numpy:array_like Continuous values to scale
2126 palette
2128 python:callable() f(x) palette to use
2129 na_value
2131 object Value to use for missing values.
2132 oob python:callable() f(x) Function to deal
2134 with values that are beyond the limits
2135 Returns
2137 out numpy:array_like Values mapped onto a pal‐
2139 ette
2140 class mizani.scale.scale_discrete
2142 Discrete scale
2143 classmethod apply(x, palette, na_value=None)
2145 Scale data discretely
2146 Parameters
2148 x numpy:array_like Discrete values to scale
2150 palette
2152 python:callable() f(x) Palette to use
2153 na_value
2155 object Value to use for missing values.
2156 Returns
2158 out numpy:array_like Scaled values
2160 classmethod train(new_data, old=None, drop=False, na_rm=False)
2162 Train a continuous scale
2163 Parameters
2165 new_data
2167 numpy:array_like New values
2168 old numpy:array_like Old range. List of values
2170 known to the scale.
2171 drop bool Whether to drop(not include) unused
2173 categories
2174 na_rm bool If True, remove missing values. Miss‐
2176 ing values are either NaN or None.
2177 Returns
2179 out python:list Values covered by the scale
2181 classmethod map(x, palette, limits, na_value=None)
2183 Map values to a discrete palette
2184 Parameters
2186 palette
2188 python:callable() f(x) palette to use
2189 x numpy:array_like Continuous values to scale
2191 na_value
2193 object Value to use for missing values.
2194 Returns
2196 out numpy:array_like Values mapped onto a pal‐
2198 ette
2199 Installation
2201 mizani can be can be installed in a couple of ways depending on pur‐
2202 pose.
2203 Official release installation
2205 For a normal user, it is recommended to install the official release.
2206 $ pip install mizani
2208 Development installation
2210 To do any development you have to clone the mizani source repository
2211 and install the package in development mode. These commands do all of
2212 that:
2213 $ git clone https://github.com/has2k1/mizani.git
2215 $ cd mizani
2216 $ pip install -e .
2217 If you only want to use the latest development sources and do not care
2219 about having a cloned repository, e.g. if a bug you care about has been
2220 fixed but an official release has not come out yet, then use this com‐
2221 mand:
2222 $ pip install git+https://github.com/has2k1/mizani.git
2224 Changelog
2226 v0.9.3
2227 2023-09-01
2228 Enhancements
2230 • Removed FutureWarnings when using pandas 2.1.0
2231 v0.9.2
2233 2023-05-25
2234 Bug Fixes
2236 • Fixed regression in but in date_format where it cannot deal with UTC
2237 timezone from timezone #30.
2238 v0.9.1
2240 2023-05-19 .SS Bug Fixes
2241 • Fixed but in date_format to handle datetime sequences within the same
2243 timezone but a mixed daylight saving state. (plotnine #687)
2244 v0.9.0
2246 2023-04-15 .SS API Changes
2247 • palettable dropped as a dependency.
2249 Bug Fixes
2251 • Fixed bug in datetime_trans where a pandas series with an index that
2252 did not start at 0 could not be transformed.
2253 • Install tzdata on pyiodide/emscripten. #27
2255 v0.8.1
2257 2022-09-28 .SS Bug Fixes
2258 • Fixed regression bug in log_format for where formatting for bases 2,
2260 8 and 16 would fail if the values were float-integers.
2261 Enhancements
2263 • log_format now uses exponent notation for bases other than base 10.
2264 v0.8.0
2266 2022-09-26 .SS API Changes
2267 • The lut parameter of cmap_pal and cmap_d_pal has been deprecated and
2269 will removed in a future version.
2270 • datetime_trans gained parameter tz that controls the timezone of the
2272 transformation.
2273 • log_format gained boolean parameter mathtex for TeX values as under‐
2275 stood matplotlib instead of values in scientific notation.
2276 Bug Fixes
2278 • Fixed bug in zero_range where uint64 values would cause a RuntimeEr‐
2279 ror.
2280 v0.7.4
2282 2022-04-02 .SS API Changes
2283 • comma_format is now imported automatically when using *.
2285 • Fixed issue with scale_discrete so that if you train on data with Nan
2287 and specify and old range that also has NaN, the result range does
2288 not include two NaN values.
2289 v0.7.3
2291 (2020-10-29) .SS Bug Fixes
2292 • Fixed log_breaks for narrow range if base=2 (#76).
2294 v0.7.2
2296 (2020-10-29) .SS Bug Fixes
2297 • Fixed bug in rescale_max() to properly handle values whose maximum is
2299 zero (#16).
2300 v0.7.1
2302 (2020-06-05) .SS Bug Fixes
2303 • Fixed regression in mizani.scales.scale_discrete.train() when train‐
2305 ning on values with some categoricals that have common elements.
2306 v0.7.0
2308 (2020-06-04) .SS Bug Fixes
2309 • Fixed issue with mizani.formatters.log_breaks where non-linear breaks
2311 could not be generated if the limits where greater than the largest
2312 integer sys.maxsize.
2313 • Fixed mizani.palettes.gradient_n_pal() to return nan for nan values.
2315 • Fixed mizani.scales.scale_discrete.train() when training categoricals
2317 to maintain the order. (plotnine #381)
2318 v0.6.0
2320 (2019-08-15) .SS New
2321 • Added pvalue_format
2323 • Added ordinal_format
2325 • Added number_bytes_format
2327 • Added pseudo_log_trans()
2329 • Added reciprocal_trans
2331 • Added modulus_trans()
2333 Enhancements
2335 •
2336 mizani.breaks.date_breaks now supports intervals in the
2338 order of seconds.
2339 • mizani.palettes.brewer_pal now supports a direction argument to con‐
2341 trol the order of the returned colors.
2342 API Changes
2344 • boxcox_trans() now only accepts positive values. For both positive
2345 and negative values, modulus_trans() has been added.
2346 v0.5.4
2348 (2019-03-26) .SS Enhancements
2349 • mizani.formatters.log_format now does a better job of approximating
2351 labels for numbers like 3.000000000000001e-05.
2352 API Changes
2354 • exponent_threshold parameter of mizani.formatters.log_format has been
2355 deprecated.
2356 v0.5.3
2358 (2018-12-24) .SS API Changes
2359 • Log transforms now default to base - 2 minor breaks. So base 10 has
2361 8 minor breaks and 9 partitions, base 8 has 6 minor breaks and 7 par‐
2362 titions, ..., base 2 has 0 minor breaks and a single partition.
2363 v0.5.2
2365 (2018-10-17) .SS Bug Fixes
2366 • Fixed issue where some functions that took pandas series would return
2368 output where the index did not match that of the input.
2369 v0.5.1
2371 (2018-10-15) .SS Bug Fixes
2372 • Fixed issue with log_breaks, so that it does not fail needlessly when
2374 the limits in the (0, 1) range.
2375 Enhancements
2377 • Changed log_format to return better formatted breaks.
2378 v0.5.0
2380 (2018-11-10) .SS API Changes
2381 • Support for python 2 has been removed.
2383 •
2385 call() and
2387 meth:~mizani.breaks.trans_minor_breaks.call now accept op‐
2388 tional parameter n which is the number of minor breaks between
2389 any two major breaks.
2390 • The parameter nan_value has be renamed to na_value.
2392 • The parameter nan_rm has be renamed to na_rm.
2394 Enhancements
2396 • Better support for handling missing values when training discrete
2397 scales.
2398 • Changed the algorithm for log_breaks, it can now return breaks that
2400 do not fall on the integer powers of the base.
2401 v0.4.6
2403 (2018-03-20) .INDENT 0.0
2404 • Added squish
2406 v0.4.5
2408 (2018-03-09) .INDENT 0.0
2409 • Added identity_pal
2411 • Added cmap_d_pal
2413 v0.4.4
2415 (2017-12-13) .INDENT 0.0
2416 • Fixed date_format to respect the timezones of the dates (#8).
2418 v0.4.3
2420 (2017-12-01) .INDENT 0.0
2421 • Changed date_breaks to have more variety in the spacing between the
2423 breaks.
2424 • Fixed date_format to respect time part of the date (#7).
2426 v0.4.2
2428 (2017-11-06) .INDENT 0.0
2429 • Fixed (regression) break calculation for the non ordinal transforms.
2431 v0.4.1
2433 (2017-11-04) .INDENT 0.0
2434 • trans objects can now be instantiated with parameter to override at‐
2436 tributes of the instance. And the default methods for computing
2437 breaks and minor breaks on the transform instance are not class at‐
2438 tributes, so they can be modified without global repercussions.
2439 v0.4.0
2441 (2017-10-24) .SS API Changes
2442 • Breaks and formatter generating functions have been converted to
2444 classes, with a __call__ method. How they are used has not changed,
2445 but this makes them move flexible.
2446 • ExtendedWilkson class has been removed. extended_breaks() now con‐
2448 tains the implementation of the break calculating algorithm.
2449 v0.3.4
2451 (2017-09-12) .INDENT 0.0
2452 • Fixed issue where some formatters methods failed if passed empty
2454 breaks argument.
2455 • Fixed issue with log_breaks() where if the limits were with in the
2457 same order of magnitude the calculated breaks were always the ends of
2458 the order of magnitude.
2459 Now log_breaks()((35, 50)) returns [35, 40, 45, 50] as breaks in‐
2461 stead of [1, 100].
2462 v0.3.3
2464 (2017-08-30) .INDENT 0.0
2465 • Fixed SettingWithCopyWarnings in squish_infinite().
2467 • Added log_format().
2469 API Changes
2471 • Added log_trans now uses log_format() as the formatting method.
2472 v0.3.2
2474 (2017-07-14) .INDENT 0.0
2475 • Added expand_range_distinct()
2477 v0.3.1
2479 (2017-06-22) .INDENT 0.0
2480 • Fixed bug where using log_breaks() with Numpy 1.13.0 led to a Val‐
2482 ueError.
2483 v0.3.0
2485 (2017-04-24) .INDENT 0.0
2486 • Added xkcd_palette(), a palette that selects from 954 named colors.
2488 • Added crayon_palette(), a palette that selects from 163 named colors.
2490 • Added cubehelix_pal(), a function that creates a continuous palette
2492 from the cubehelix system.
2493 • Fixed bug where a color palette would raise an exception when passed
2495 a single scalar value instead of a list-like.
2496 • extended_breaks() and mpl_breaks() now return a single break if the
2498 limits are equal. Previous, one run into an Overflow and the other
2499 returned a sequence filled with n of the same limit.
2500 API Changes
2502 • mpl_breaks() now returns a function that (strictly) expects a tuple
2503 with the minimum and maximum values.
2504 v0.2.0
2506 (2017-01-27) .INDENT 0.0
2507 • Fixed bug in censor() where a sequence of values with an irregular
2509 index would lead to an exception.
2510 • Fixed boundary issues due internal loss of precision in ported func‐
2512 tion seq().
2513 • Added mizani.breaks.extended_breaks() which computes breaks using a
2515 modified version of Wilkinson's tick algorithm.
2516 • Changed the default function mizani.transforms.trans.breaks_() used
2518 by mizani.transforms.trans to compute breaks from
2519 mizani.breaks.mpl_breaks() to mizani.breaks.extended_breaks().
2520 • mizani.breaks.timedelta_breaks() now uses
2522 mizani.breaks.extended_breaks() internally instead of
2523 mizani.breaks.mpl_breaks().
2524 • Added manual palette function mizani.palettes.manual_pal().
2526 • Requires pandas version 0.19.0 or higher.
2528 v0.1.0
2530 (2016-06-30)
2531 First public release
2533
2535 Hassan Kibirige
2536
2538 2023, Hassan Kibirige
25390.9.3 Sep 03, 2023 MIZANI(1)