MizaniDocumentation · MizaniDocumentation,Release0+untagged.4.g46cd51e.dirty mizani.bounds.squish_infinite(x, range=(0, 1))Truncate inﬁnite values to a range Parameters • x (array_like)

Mizani DocumentationRelease 0+untagged.4.g46cd51e.dirty

Hassan Kibirige

July 03, 2016

Contents

1 Installation 3

2 Contents 52.1 bounds - Limiting data values for a palette . . . . . . . . . . . . . . . . . 52.2 breaks - Partitioning a scale for readability . . . . . . . . . . . . . . . . 92.3 formatters - Labelling breaks . . . . . . . . . . . . . . . . . . . . . . . . 112.4 palettes - Mapping values onto the domain of a scale . . . . . . . . . . 142.5 transforms - Transforming variables, scales and coordinates . . . . . . . 192.6 scale - Implementing a scale . . . . . . . . . . . . . . . . . . . . . . . . 242.7 Changelog . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26

Python Module Index 27

i

ii

Mizani Documentation, Release 0+untagged.4.g46cd51e.dirty

Mizani is Python package that provides the pieces necessary to create scales for a graph-ics system. It is based on Hadley Wickham’s Scales package.

Contents 1

https://github.com/hadley/scales


2 Contents

CHAPTER1

Installation

Mizani can be installed in a handful of ways.

1. Official release (Recommended)

$ pip install mizani

If you don’t have pip installed, this Python installation guide can guide youthrough the process.

2. Development sources

$ pip install git+https://github.com/has2k1/mizani.git

Or

$ git clone https://github.com/has2k1/mizani.git$ cd mizani$ python setup.py install

Or

$ curl -OL https://github.com/has2k1/mizani/archive/master.zip$ unzip master$ cd mizani-master$ python setup.py install

3

https://pip.pypa.io

http://docs.python-guide.org/en/latest/starting/installation/


4 Chapter 1. Installation

CHAPTER2

Contents

2.1 bounds - Limiting data values for a palette

Continuous variables have values anywhere in the range minus infinite to plus infinite.However, when creating a visual representation of these values what usually matters isthe relative difference between the values. This is where rescaling comes into play.

The values are mapped onto a range that a scale can deal with. For graphical repre-sentation that range tends to be [0, 1] or [0, 𝑛], where 𝑛 is some number that makes theplotted object overflow the plotting area.

Although a scale may be able handle the [0, 𝑛] range, it may be desirable to have alower bound greater than zero. For example, if data values get mapped to zero on ascale whose graphical representation is the size/area/radius/length some data will beinvisible. The solution is to restrict the lower bound e.g. [0.1, 1]. Similarly you canrestrict the upper bound – using these functions.

mizani.bounds.rescale(x, to=(0, 1), _from=None)Rescale numeric vector to have specified minimum and maximum.

Parameters

• x (array_like | numeric) – 1D vector of values to manipulate.

• to (tuple) – output range (numeric vector of length two)

• _from (tuple) – input range (numeric vector of length two). Ifnot given, is calculated from the range of x

Returns out – Rescaled values

Return type array_like

>>> x = [0, 2, 4, 6, 8, 10]>>> rescale(x)array([ 0. , 0.2, 0.4, 0.6, 0.8, 1. ])>>> rescale(x, to=(0, 2))array([ 0. , 0.4, 0.8, 1.2, 1.6, 2. ])>>> rescale(x, to=(0, 2), _from=(0, 20))array([ 0. , 0.2, 0.4, 0.6, 0.8, 1. ])

5

https://docs.python.org/library/functions.html#tuple



mizani.bounds.rescale_mid(x, to=(0, 1), _from=None, mid=0)Rescale numeric vector to have specified minimum, midpoint, and maximum.

Parameters



• _from (tuple) – input range (numeric vector of length two). Ifnot given, is calculated from the range of x

• mid (numeric) – mid-point of input range



>>> rescale_mid([1, 2, 3], mid=1)array([ 0.5 , 0.75, 1. ])>>> rescale_mid([1, 2, 3], mid=2)array([ 0. , 0.5, 1. ])

mizani.bounds.rescale_max(x, to=(0, 1), _from=None)Rescale numeric vector to have specified maximum.

Parameters



• _from (tuple) – input range (numeric vector of length two). Ifnot given, is calculated from the range of x. Only the 2nd (max)element is essential to the output.



>>> x = [0, 2, 4, 6, 8, 10]>>> rescale_max(x, (0, 3))array([ 0. , 0.6, 1.2, 1.8, 2.4, 3. ])

Only the 2nd (max) element of the parameters to and _from are essential to theoutput.

>>> rescale_max(x, (1, 3))array([ 0. , 0.6, 1.2, 1.8, 2.4, 3. ])>>> rescale_max(x, (0, 20))array([ 0., 4., 8., 12., 16., 20.])

If max(x) < _from[1] then values will be scaled beyond the requested (to[1])maximum.

>>> rescale_max(x, to=(1, 3), _from=(-1, 6))array([ 0., 1., 2., 3., 4., 5.])

6 Chapter 2. Contents






mizani.bounds.squish_infinite(x, range=(0, 1))Truncate infinite values to a range

Parameters

• x (array_like) – Values that should have infinities squished.

• range (tuple) – The range onto which to squish the infinites.Must be of size 2.

Returns out – Values with infinites squished.


>>> squish_infinite([0, .5, .25, np.inf, .44])[0.0, 0.5, 0.25, 1.0, 0.44]>>> squish_infinite([0, -np.inf, .5, .25, np.inf], (-10, 9))[0.0, -10.0, 0.5, 0.25, 9.0]

mizani.bounds.censor(x, range=(0, 1), only_finite=True)Convert any values outside of range to a NULL type object.

The NULL type object depends on the type of values in x.

•float - float(’nan’)

•int - float(’nan’)

•datetime.datetime : np.datetime64(NaT)

•datetime.timedelta : np.timedelta64(NaT)

Parameters

• x (array_like) – Values to manipulate

• range (tuple) – (min, max) giving desired output range

• only_finite (bool) – If True (the default), will only modifyfinite values.

Returns x – Censored array


>>> a = [1, 2, np.inf, 3, 4, -np.inf, 5]>>> censor(a, (0, 10))[1, 2, inf, 3, 4, -inf, 5]>>> censor(a, (0, 10), False)[1, 2, nan, 3, 4, nan, 5]>>> censor(a, (2, 4))[nan, 2, inf, 3, 4, -inf, nan]

Note: All values in x should be of the same type. only_finite parameter is notconsidered for Datetime and Timedelta types.

2.1. bounds - Limiting data values for a palette 7


https://docs.python.org/library/functions.html#float

https://docs.python.org/library/functions.html#int

https://docs.python.org/library/datetime.html#datetime.datetime

https://docs.python.org/library/datetime.html#datetime.timedelta


https://docs.python.org/library/functions.html#bool


mizani.bounds.zero_range(x, tol=2.2204460492503131e-14)Determine if range of vector is close to zero.

Parameters

• x (array_like | numeric) – Value(s) to check. If it is an ar-ray_like, it should be of length 2.

• tol (float) – Tolerance. Default tolerance is the machine ep-silon times 102.

Returns out – Whether x has zero range.

Return type bool

>>> zero_range([1, 1])True>>> zero_range([1, 2])False>>> zero_range([1, 2], tol=2)True

mizani.bounds.expand_range(range, mul=0, add=0, zero_width=1)Expand a range with a multiplicative or additive constant

Parameters

• range (tuple) – Range of data. Size 2.

• mul (int | float) – Multiplicative constant

• add (int | float | timedelta) – Additive constant

• zero_width (int | float | timedelta) – Distance to use ifrange has zero width

Returns out – Expanded range

Return type tuple

>>> expand_range((3, 8))(3, 8)>>> expand_range((0, 10), mul=0.1)(-1.0, 11.0)>>> expand_range((0, 10), add=2)(-2, 12)>>> expand_range((0, 10), mul=.1, add=2)(-3.0, 13.0)>>> expand_range((0, 1))(0, 1)

When the range has zero width

>>> expand_range((5, 5))(4.5, 5.5)



https://en.wikipedia.org/wiki/Machine_epsilon






Note: If expanding datetime or timedelta types, add and zero_width must besuitable timedeltas i.e. You should not mix types between Numpy, Pandas andthe datetime module.

In Python 2, you cannot multiplicative constant mul cannot be a float.

2.2 breaks - Partitioning a scale for readability

All scales have a means by which the values that are mapped onto the scale are in-terpreted. Numeric digital scales put out numbers for direct interpretation, but mostscales cannot do this. What they offer is named markers/ticks that aid in assessing thevalues e.g. the common odometer will have ticks and values to help gauge the speed ofthe vehicle.

The named markers are what we call breaks. Properly calculated breaks make inter-pretation straight forward. These functions provide ways to calculate good(hopefully)breaks.

mizani.breaks.mpl_breaks(*args, **kwargs)Compute breaks using MPL’s default locator

See MaxNLocator for the parameter descriptions

Returns out – A function that takes a sequence of values and returns asequence of break points.

Return type function

>>> x = range(10)>>> limits = (0, 9)>>> mpl_breaks()(limits)array([ 0., 1., 2., 3., 4., 5., 6., 7., 8., 9.])>>> mpl_breaks(nbins=2)(limits)array([ 0., 5., 10.])

mizani.breaks.log_breaks(n=5, base=10)Integer breaks on log transformed scales

Parameters

• n (int) – Desired number of breaks

• base (int) – Base of logarithm

Returns out – A function that takes a tuple with 2 limit values andreturns a sequence of break points.


>>> x = np.logspace(3, 7)>>> limits = min(x), max(x)

2.2. breaks - Partitioning a scale for readability 9

https://docs.python.org/library/datetime.html#module-datetime


http://matplotlib.org/api/ticker_api.html#matplotlib.ticker.MaxNLocator




>>> log_breaks()(limits)array([ 100, 10000, 1000000])>>> log_breaks(2)(limits)array([ 100, 100000])

mizani.breaks.minor_breaks(n=1)Compute minor breaks

Parameters n (int) – Number of minor breaks between the majorbreaks.

Returns out – Function that computes minor breaks.


>>> major = [1, 2, 3, 4]>>> limits = [0, 5]>>> minor_breaks()(major, limits)array([ 0.5, 1.5, 2.5, 3.5, 4.5])

mizani.breaks.trans_minor_breaks(n=1)Compute minor breaks for transformed scales

The minor breaks are computed in data space. This together with major breakscomputed in transform space reveals the non linearity of of a scale. See the logtransforms created with log_trans() like log10_trans.

Parameters n (int) – Number of minor breaks between the majorbreaks.

Returns out – Method for the transform class that computes minorbreaks.

Return type classmethod

>>> from mizani.transforms import sqrt_trans>>> major = [1, 2, 3, 4]>>> limits = [0, 5]>>> sqrt_trans.minor_breaks(major, limits)array([ 0.5, 1.5, 2.5, 3.5, 4.5])>>> class sqrt_trans2(sqrt_trans):... minor_breaks = trans_minor_breaks()>>> sqrt_trans2.minor_breaks(major, limits)array([ 1.58113883, 2.54950976, 3.53553391])

mizani.breaks.date_breaks(width=None)Regularly spaced dates

Parameters width (str | None) – An interval specification. Must beone of [minute, hour, day, week, month, year] If None, the intervalautomatic.

Returns out – A function that takes a tuple of two datetime.datetimevalues and returns a sequence of break points.




https://docs.python.org/library/functions.html#classmethod

https://docs.python.org/library/datetime.html#datetime.datetime



>>> from datetime import datetime>>> x = [datetime(year, 1, 1) for year in [2010, 2026, 2015]]

Default breaks will be regularly spaced but the spacing is automatically deter-mined

>>> limits = min(x), max(x)>>> breaks = date_breaks()>>> [d.year for d in breaks(limits)][2014, 2019, 2024]

Breaks at 4 year intervals

>>> breaks = date_breaks('4 year')>>> [d.year for d in breaks(limits)][2008, 2012, 2016, 2020, 2024, 2028]

mizani.breaks.timedelta_breaks()Timedelta breaks

Returns out – A function that takes a sequence of twodatetime.timedelta values and returns a sequence of breakpoints.


>>> from datetime import timedelta>>> breaks = timedelta_breaks()>>> x = [timedelta(days=i*365) for i in range(25)]>>> limits = min(x), max(x)>>> major = breaks(limits)>>> [val.total_seconds()/(365*24*60*60)for val in major][0.0, 5.0, 10.0, 15.0, 20.0, 25.0]

2.3 formatters - Labelling breaks

Scales have guides and these are what help users make sense of the data mapped ontothe scale. Common examples of guides include the x-axis, the y-axis, the keyed legendand a colorbar legend. The guides have demarcations(breaks), some of which must belabelled.

The *_format functions below create functions that convert data values as understoodby a specific scale and return string representations of those values. Manipulating thestring representation of a value helps improve readability of the guide.

mizani.formatters.custom_format(fmt, style=’new’)Return a function that formats a sequence of inputs

Parameters

2.3. formatters - Labelling breaks 11

https://docs.python.org/library/datetime.html#datetime.timedelta


• fmt (str) – Format string

• style (’new’ | ’old’) – Whether to use new style or old styleformatting. New style uses the str.format() while old styleuses %. The format string must be written accordingly.

Returns out – Formatting function. It takes a sequence of values andreturns a sequence of strings.


>>> formatter = custom_format('{:.2f} USD')>>> formatter([3.987, 2, 42.42])['3.99 USD', '2.00 USD', '42.42 USD']

mizani.formatters.currency_format(prefix=’$’, suffix=’‘, digits=2,big_mark=’‘)

Currency formatter

Parameters

• prefix (str) – What to put before the value.

• suffix (str) – What to put after the value.

• digits (int) – Number of significant digits

• big_mark (str) – The thousands separator. This is usually acomma or a dot.

Returns out – Formatting function. It takes a sequence of numericalvalues and and returns a sequence of strings.


>>> x = [1.232, 99.2334, 4.6, 9, 4500]>>> currency_format()(x)['$1.23', '$99.23', '$4.60', '$9.00', '$4500.00']>>> currency_format('C$', digits=0, big_mark=',')(x)['C$1', 'C$99', 'C$5', 'C$9', 'C$4,500']

mizani.formatters.dollar_format(prefix=’$’, suffix=’‘, digits=2, big_mark=’‘)Currency formatter

Parameters

• prefix (str) – What to put before the value.

• suffix (str) – What to put after the value.

• digits (int) – Number of significant digits

• big_mark (str) – The thousands separator. This is usually acomma or a dot.



https://docs.python.org/library/functions.html#str

https://docs.python.org/library/stdtypes.html#str.format











>>> x = [1.232, 99.2334, 4.6, 9, 4500]>>> currency_format()(x)['$1.23', '$99.23', '$4.60', '$9.00', '$4500.00']>>> currency_format('C$', digits=0, big_mark=',')(x)['C$1', 'C$99', 'C$5', 'C$9', 'C$4,500']

mizani.formatters.percent_format(use_comma=False)Percent formatter

Multiply by one hundred and display percent sign



>>> formatter = percent_format()>>> formatter([.45, 9.515, .01])['45%', '952%', '1%']>>> formatter([.654, .8963, .1])['65.4%', '89.6%', '10.0%']

mizani.formatters.scientific_format(digits=3)Scientific formatter

Parameters digits (int) – Significant digits.



>>> x = [.12, .23, .34, 45]>>> scientific_format()(x)['1.2e-01', '2.3e-01', '3.4e-01', '4.5e+01']

Note: Be careful when using many digits (15+ on a 64 bit computer). Considerof the machine epsilon.

mizani.formatters.mpl_format()Format using MPL formatter for scalars



>>> mpl_format()([.654, .8963, .1])['0.6540', '0.8963', '0.1000']

mizani.formatters.date_format(fmt=’%Y-%m-%d’)Datetime formatter

2.3. formatters - Labelling breaks 13




Parameters fmt (str) – Format string. See strftime.



>>> from datetime import datetime>>> x = [datetime(x, 1, 1) for x in [2010, 2014, 2018, 2022]]>>> date_format()(x)['2010-01-01', '2014-01-01', '2018-01-01', '2022-01-01']>>> date_format('%Y')(x)['2010', '2014', '2018', '2022']

mizani.formatters.timedelta_format(units=None, add_units=True, use-tex=False)

Timedelta formatter

Returns out – Formatting function. It takes a sequence of timedeltavalues and returns a sequence of strings.


>>> from datetime import timedelta>>> x = [timedelta(days=31*i) for i in range(5)]>>> timedelta_format()(x)['0', '1 month', '2 months', '3 months', '4 months']>>> timedelta_format(units='d')(x)['0', '31 days', '62 days', '93 days', '124 days']

2.4 palettes -Mapping values onto the domain of a scale

Palettes are the link between data values and the values along the dimension of a scale.Before a collection of values can be represented on a scale, they are transformed by apalette. This transformation is knowing as mapping. Values are mapped onto a scaleby a palette.

Scales tend to have restrictions on the magnitude of quantities that they can intelligiblyrepresent. For example, the size of a point should be significantly smaller than the plotpanel onto which it is plotted or else it would be hard to compare two or more points.Therefore palettes must be created that enforce such restrictions. This is the reason forthe *_pal functions that create and return the actual palette functions.

mizani.palettes.hls_palette(n_colors=6, h=0.01, l=0.6, s=0.65)Get a set of evenly spaced colors in HLS hue space.

h, l, and s should be between 0 and 1

Parameters

• n_colors (int) – number of colors in the palette

• h (float) – first hue



https://docs.python.org/library/datetime.html#strftime-strptime-behavior




• l (float) – lightness

• s (float) – saturation

Returns palette – List-like object of colors as RGB tuples.

Return type seaborn color palette

See also:

husl_palette() Make a palette using evenly spaced circular hues in the HUSLsystem.

>>> len(hls_palette(2))2>>> len(hls_palette(9))9

mizani.palettes.husl_palette(n_colors=6, h=0.01, s=0.9, l=0.65)Get a set of evenly spaced colors in HUSL hue space.

h, s, and l should be between 0 and 1

Parameters

• n_colors (int) – number of colors in the palette

• h (float) – first hue

• s (float) – saturation

• l (float) – lightness

Returns palette – List-like object of colors as RGB tuples.

Return type seaborn color palette

See also:

hls_palette() Make a palette using evenly spaced circular hues in the HSL sys-tem.

>>> len(husl_palette(3))3>>> len(husl_palette(11))11

mizani.palettes.rescale_pal(range=(0.1, 1))Rescale the input to the specific output range.

Useful for alpha, size, and continuous position.

Parameters range (tuple) – Range of the scale

Returns out – Palette function that takes a sequence of values in therange [0, 1] and returns values in the specified range.

2.4. palettes -Mapping values onto the domain of a scale 15










>>> palette = rescale_pal()>>> palette([0, .2, .4, .6, .8, 1])array([ 0.1 , 0.28, 0.46, 0.64, 0.82, 1. ])

The returned palette expects inputs in the [0, 1] range. Any value outside thoselimits is clipped to range[0] or range[1].

>>> palette([-2, -1, 0.2, .4, .8, 2, 3])array([ 0.1 , 0.1 , 0.28, 0.46, 0.82, 1. , 1. ])

mizani.palettes.area_pal(range=(1, 6))Point area palette (continuous).

Parameters range (tuple) – Numeric vector of length two, giving rangeof possible sizes. Should be greater than 0.

Returns out – Palette function that takes a sequence of values in therange [0, 1] and returns values in the specified range.


>>> x = np.arange(0, .6, .1)**2>>> palette = area_pal()>>> palette(x)array([ 1. , 1.5, 2. , 2.5, 3. , 3.5])

The results are equidistant because the input x is in area space, i.e it is squared.

mizani.palettes.abs_area(max)Point area palette (continuous), with area proportional to value.

Parameters max (float) – A number representing the maximum size

Returns out – Palette function that takes a sequence of values in therange [0, 1] and returns values in the range [0, max].


>>> x = np.arange(0, .8, .1)**2>>> palette = abs_area(5)>>> palette(x)array([ 0. , 0.5, 1. , 1.5, 2. , 2.5, 3. , 3.5])

Compared to area_pal(), abs_area() will handle values in the range [-1, 0]without returning np.nan. And values whose absolute value is greater than 1 willbe clipped to the maximum.

mizani.palettes.grey_pal(start=0.2, end=0.8)Utility for creating discrete grey scale palette

Parameters

• start (float) – grey value at low end of palette

• end (float) – grey value at high end of palette







Returns out – Continuous color palette that takes a single int parame-ter n and returns n equally spaced colors.


>>> palette = grey_pal()>>> palette(5)['#333333', '#737373', '#989898', '#b5b5b5', '#cccccc']

mizani.palettes.hue_pal(h=0.01, l=0.6, s=0.65, color_space=’hls’)Utility for making hue palettes for color schemes.

Parameters

• h (float) – first hue. In the [0, 1] range

• l (float) – lightness. In the [0, 1] range

• s (float) – saturation. In the [0, 1] range

• color_space (’hls’ | ’husl’) – Color space to use for thepalette

Returns out – Continuous color palette that takes a single int param-eter n and returns n equally spaced colors. Though the palette iscontinuous, since it is varies the hue it is good for categorical data.However if n is large enough the colors show continuity.


>>> hue_pal()(5)['#db5f57', '#b9db57', '#57db94', '#5784db', '#c957db']>>> hue_pal(color_space='husl')(5)['#e0697e', '#9b9054', '#569d79', '#5b98ab', '#b675d7']

mizani.palettes.brewer_pal(type=’seq’, palette=1)Utility for making a brewer palette

Parameters

• type (’sequential’ | ’qualitative’ | ’diverging’) – Typeof palette. Sequential, Qualitative or Diverging. The followingabbreviations may be used, seq, qual or div.

• palette (int | str) – Which palette to choose from. If is aninteger, it must be in the range [0, m], where m depends on thenumber sequential, qualitative or diverging palettes. If it is astring, then it is the name of the palette.

Returns out – A color palette that takes a single int parameter n andreturns n colors. The maximum value of n varies depending on theparameters.


2.4. palettes -Mapping values onto the domain of a scale 17








>>> brewer_pal()(5)['#EFF3FF', '#BDD7E7', '#6BAED6', '#3182BD', '#08519C']>>> brewer_pal('qual')(5)['#7FC97F', '#BEAED4', '#FDC086', '#FFFF99', '#386CB0']>>> brewer_pal('qual', 2)(5)['#1B9E77', '#D95F02', '#7570B3', '#E7298A', '#66A61E']>>> brewer_pal('seq', 'PuBuGn')(5)['#F6EFF7', '#BDC9E1', '#67A9CF', '#1C9099', '#016C59']

The available color names for each palette type can be obtained using the follow-ing code:

import palettable.colorbrewer as brewer

print([k for k in brewer.COLOR_MAPS['Sequential'].keys()])print([k for k in brewer.COLOR_MAPS['Qualitative'].keys()])print([k for k in brewer.COLOR_MAPS['Diverging'].keys()])

mizani.palettes.gradient_n_pal(colors, values=None, name=’gradientn’)Create a n color gradient palette

Parameters

• colors (list) – list of colors

• values (list, optional) – list of points in the range [0, 1]at which to place each color. Must be the same size as colors.Default to evenly space the colors

• name (str) – Name to call the resultant MPL colormap

Returns out – Continuous color palette that takes a single parametereither a float or a sequence of floats maps those value(s) onto thepalette and returns color(s). The float(s) must be in the range [0,1].


>>> palette = gradient_n_pal(['red', 'blue'])>>> palette([0, .25, .5, .75, 1])['#ff0000', '#bf0040', '#7f0080', '#3f00c0', '#0000ff']

mizani.palettes.cmap_pal(name=None, lut=None)Create a palette using an MPL colormap

Parameters

• name (str) – Name of colormap

• lut (None | int) – This is the number of entries desired in thelookup table. Default is None, leave it up Matplotlib.

Returns out – Continuous color palette that takes a single parametereither a float or a sequence of floats maps those value(s) onto the


https://docs.python.org/library/functions.html#list






palette and returns color(s). The float(s) must be in the range [0,1].


>>> palette = cmap_pal('viridis')>>> palette([.1, .2, .3, .4, .5])['#482475', '#414487', '#355f8d', '#2a788e', '#21918c']

mizani.palettes.desaturate_pal(color, prop, reverse=False)Create a palette that desaturate a color by some proportion

Parameters

• color (matplotlib color) – hex, rgb-tuple, or html color name

• prop (float) – saturation channel of color will be multiplied bythis value

• reverse (bool) – Whether to reverse the palette.

Returns out – Continuous color palette that takes a single parametereither a float or a sequence of floats maps those value(s) onto thepalette and returns color(s). The float(s) must be in the range [0,1].


>>> palette = desaturate_pal('red', .1)>>> palette([0, .25, .5, .75, 1])['#ff0000', '#e21d1d', '#c53a3a', '#a95656', '#8c7373']

2.5 transforms - Transforming variables, scales and coordi-nates

“The Grammar of Graphics (2005)” by Wilkinson, Anand and Grossman describesthree types of transformations.

• Variable transformations - Used to make statistical operations on variables ap-propriate and meaningful. They are also used to new variables.

• Scale transformations - Used to make statistical objects displayed on dimensionsappropriate and meaningful.

• Coordinate transformations - Used to manipulate the geometry of graphics tohelp perceive relationships and find meaningful structures for representing varia-tions.

Variable and scale transformations are similar in-that they lead to plotted objects thatare indistinguishable. Typically, variable transformation is done outside the graphicssystem and so the system cannot provide transformation specific guides & decorations

2.5. transforms - Transforming variables, scales and coordinates 19





for the plot. The trans is aimed at being useful for scale and coordinate transformations.

class mizani.transforms.transBase class for all transforms

This class is used to transform data and also tell the x and y axes how to createand label the tick locations.

The key methods to override are trans.transform() and trans.inverse(). Alter-nately, you can quickly create a transform class using the trans_new() function.

aesthetic = NoneAesthetic that the transform works on

dataspace_is_numerical = TrueWhether the untransformed data is numerical

domain = (-inf, inf)Limits of the transformed data

static breaks_(x)Function to calculate breaks

static minor_breaks(major, limits=None)Function to calculate minor_breaks

static format(x)Function to format breaks

static transform(x)Transform of x

static inverse(x)Inverse of x

classmethod breaks(limits)Calculate breaks in data space and return them in transformed space.

Expects limits to be in transform space, this is the same space as that wherethe domain is specified.

This method wraps around breaks_() to ensure that the calculated breaksare within the domain the transform. This is helpful in cases where an aes-thetic requests breaks with limits expanded for some padding, yet the expan-sion goes beyond the domain of the transform. e.g for a probability transformthe breaks will be in the domain [0, 1] despite any outward limits.

Parameters limits (tuple) – The scale limits. Size 2.

Returns out – Major breaks





mizani.transforms.trans_new(name, transform, inverse, breaks=None, mi-nor_breaks=None, _format=None, domain=(-inf,inf), doc=’‘)

Create a transformation class object

Parameters

• name (str) – Name of the transformation

• transform (function) – A function (preferably a ufunc) thatcomputes the transformation.

• inverse (function) – A function (preferably a ufunc) that com-putes the inverse of the transformation.

• breaks (function) – Function to compute the breaks for thistransform. If None, then a default good enough for a lineardomain is used.

• minor_breaks (function) – Function to compute the minorbreaks for this transform. If None, then a default good enoughfor a linear domain is used.

• _format (function) – Function to format the generated breaks.

• domain (array_like) – Domain over which the transformationis valid. It should be of length 2.

• doc (str) – Docstring for the class.

Returns out – Transform class

Return type trans

mizani.transforms.log_trans(base=None, **kwargs)Create a log transform class for base

Parameters

• base (float) – Base for the logarithm. If None, then the naturallog is used.

• kwargs (dict) – Keyword arguments passed onto trans_new().Should not include the transform or inverse.

Returns out – Log transform class

Return type type

class mizani.transforms.log10_transLog 10 Transformation

classmethod minor_breaks(trans, major, limits=None)Minor breaks for transformed scales

Parameters

• major (array_like) – Major breaks





https://docs.python.org/library/stdtypes.html#dict

https://docs.python.org/library/functions.html#type


• limits (array_like | None) – Limits of the scale. If ar-ray_like, must be of size 2. If None, then the minimum andmaximum of the major breaks are used.

transform = <ufunc ‘log10’>

class mizani.transforms.log2_transLog 2 Transformation

classmethod minor_breaks(trans, major, limits=None)Minor breaks for transformed scales

Parameters

• major (array_like) – Major breaks

• limits (array_like | None) – Limits of the scale. If ar-ray_like, must be of size 2. If None, then the minimum andmaximum of the major breaks are used.

transform = <ufunc ‘log2’>

mizani.transforms.exp_trans(base=None, **kwargs)Create a exponential transform class for base

This is inverse of the log transform.

Parameters

• base (float) – Base of the logarithm


Returns out – Exponential transform class

Return type type

class mizani.transforms.log1p_transLog plus one Transformation

transform = <ufunc ‘log1p’>

inverse = <ufunc ‘expm1’>

class mizani.transforms.identity_transIdentity Transformation

class mizani.transforms.reverse_transReverse Transformation

transform = <ufunc ‘negative’>

inverse = <ufunc ‘negative’>

class mizani.transforms.sqrt_transSquare-root Transformation

transform = <ufunc ‘sqrt’>




https://docs.python.org/library/functions.html#type


inverse = <ufunc ‘square’>

class mizani.transforms.asn_transArc-sin square-root Transformation

class mizani.transforms.atanh_transArc-tangent Transformation

transform = <ufunc ‘arctanh’>

inverse = <ufunc ‘tanh’>

mizani.transforms.boxcox_trans(p, **kwargs)Boxcox Transformation

Parameters

• p (float) – Power parameter, commonly denoted by lower-caselambda in formulae


mizani.transforms.probability_trans(distribution, *args, **kwargs)Probability Transformation

Parameters

• distribution (str) – Name of the distribution. Valid distri-butions are listed at scipy.stats. Any of the continuous ordiscrete distributions.

• args (tuple) – Arguments passed to the distribution functions.

• kwargs (dict) – Keyword arguments passed to the distributionfunctions.

Note: Make sure that the distribution is a good enough approximation for thedata. When this is not the case, computations may run into errors. Absence ofany errors does not imply that the distribution fits the data.

class mizani.transforms.logit_transLogit Transformation

mizani.transforms.probit_transalias of norm_trans

class mizani.transforms.datetime_transDatetime Transformation

static transform(x)Transform from date to a numerical format

static inverse(x)Transform to date from numerical format





http://docs.scipy.org/doc/scipy/reference/stats.html#module-scipy.stats




class mizani.transforms.timedelta_transTimedelta Transformation

static transform(x)Transform from Timeddelta to numerical format

static inverse(x)Transform to Timedelta from numerical format

class mizani.transforms.timedelta_transTimedelta Transformation

static transform(x)Transform from Timeddelta to numerical format

static inverse(x)Transform to Timedelta from numerical format

mizani.transforms.gettrans(t)Return a trans object

Parameters t (string | function | class | trans object) – nameof transformation function

Returns out

Return type trans

2.6 scale - Implementing a scale

According to On the theory of scales of measurement by S.S. Stevens, scales can beclassified in four ways – norminal, ordinal, interval and ratio. Using current(2016)terminology, norminal data is made up of unordered categories, ordinal data is madeup of ordered categories and the two can be classified as discrete. On the other handboth interval and ratio data are continuous.

The scale classes below show how the rest of the Mizani package can be used to imple-ment the two categories of scales. The key tasks are training and mapping and thesecorrespond to the train and map methods.

To train a scale on data means, to make the scale learn the limits of the data. This iselaborate (or worthy of a dedicated method) for two reasons:

• Practical – data may be split up across more than one object, yet all will be repre-sented by a single scale.

• Conceptual – training is a key action that may need to be inserted into multiplelocations of the data processing pipeline before a graphic can be created.

To map data onto a scale means, to associate data values with values(potential read-ings) on a scale. This is perhaps the most important concept unpinning a scale.

The apply methods are simple examples of how to put it all together.



class mizani.scale.scale_continuousContinuous scale

classmethod apply(x, palette, nan_value=None, trans=None)Scale data continuously

Parameters

• x (array_like) – Continuous values to scale

• palette (function) – Palette to use

• nan_value (object) – Value to use for missing values.

• trans (trans) – How to transform the data before scaling. IfNone, no transformation is done.

Returns out – Scaled values


classmethod train(new_data, old=None)Train a continuous scale

Parameters

• new_data (array_like) – New values

• old (array_like) – Old range. Most likely a tuple of length 2.

Returns out – Limits(range) of the scale

Return type tuple

classmethod map(x, palette, limits, nan_value=None, oob=<function cen-sor>)

Map values to a continuous palette

Parameters


• palette (function) – palette to use


• oob (function) – Function to deal with values that are beyondthe limits

Returns out – Values mapped onto a palette


class mizani.scale.scale_discreteDiscrete scale

classmethod apply(x, palette, nan_value=None)Scale data discretely

Parameters

2.6. scale - Implementing a scale 25

https://docs.python.org/library/functions.html#object




• x (array_like) – Discrete values to scale

• palette (palette) – Palette to use


Returns out – Scaled values


classmethod train(new_data, old=None, drop=False)Train a continuous scale

Parameters

• new_data (array_like) – New values

• old (array_like) – Old range. List of values known to thescale.

• drop (bool) – Whether to drop(not include) unused categories

Returns out – Values covered by the scale

Return type list

classmethod map(x, palette, limits, nan_value=None)Map values to a discrete palette

Parameters

• palette (palette) – palette to use



Returns out – Values mapped onto a palette


2.7 Changelog

2.7.1 v0.1.0

(2016-06-30)

First public release




https://docs.python.org/library/functions.html#list


Python Module Index

mmizani.bounds, 5mizani.breaks, 9mizani.formatters, 11mizani.palettes, 14mizani.scale, 24mizani.transforms, 19

27


28 PythonModule Index

Index

Aabs_area() (in module mizani.palettes),

16aesthetic (mizani.transforms.trans at-

tribute), 20apply() (mizani.scale.scale_continuous

class method), 25apply() (mizani.scale.scale_discrete class

method), 25area_pal() (in module mizani.palettes), 16asn_trans (class in mizani.transforms), 23atanh_trans (class in mizani.transforms),

23

Bboxcox_trans() (in module

mizani.transforms), 23breaks() (mizani.transforms.trans class

method), 20breaks_() (mizani.transforms.trans static

method), 20brewer_pal() (in module mizani.palettes),

17

Ccensor() (in module mizani.bounds), 7cmap_pal() (in module mizani.palettes),

18currency_format() (in module

mizani.formatters), 12custom_format() (in module

mizani.formatters), 11

Ddataspace_is_numerical

(mizani.transforms.trans at-tribute), 20

date_breaks() (in module mizani.breaks),10

date_format() (in modulemizani.formatters), 13

datetime_trans (class inmizani.transforms), 23

desaturate_pal() (in modulemizani.palettes), 19

dollar_format() (in modulemizani.formatters), 12

domain (mizani.transforms.trans at-tribute), 20

Eexp_trans() (in module

mizani.transforms), 22expand_range() (in module

mizani.bounds), 8

Fformat() (mizani.transforms.trans static

method), 20

Ggettrans() (in module mizani.transforms),

24gradient_n_pal() (in module

mizani.palettes), 18grey_pal() (in module mizani.palettes), 16

Hhls_palette() (in module mizani.palettes),

14hue_pal() (in module mizani.palettes), 17husl_palette() (in module

mizani.palettes), 15

29


Iidentity_trans (class in

mizani.transforms), 22inverse (mizani.transforms.atanh_trans at-

tribute), 23inverse (mizani.transforms.log1p_trans at-

tribute), 22inverse (mizani.transforms.reverse_trans

attribute), 22inverse (mizani.transforms.sqrt_trans at-

tribute), 22inverse() (mizani.transforms.datetime_trans

static method), 23inverse() (mizani.transforms.timedelta_trans

static method), 24inverse() (mizani.transforms.trans static

method), 20

Llog10_trans (class in mizani.transforms),

21log1p_trans (class in mizani.transforms),

22log2_trans (class in mizani.transforms), 22log_breaks() (in module mizani.breaks), 9log_trans() (in module

mizani.transforms), 21logit_trans (class in mizani.transforms),

23

Mmap() (mizani.scale.scale_continuous

class method), 25map() (mizani.scale.scale_discrete class

method), 26minor_breaks() (in module

mizani.breaks), 10minor_breaks()

(mizani.transforms.log10_transclass method), 21

minor_breaks()(mizani.transforms.log2_transclass method), 22

minor_breaks() (mizani.transforms.transstatic method), 20

mizani.bounds (module), 5mizani.breaks (module), 9mizani.formatters (module), 11

mizani.palettes (module), 14mizani.scale (module), 24mizani.transforms (module), 19mpl_breaks() (in module mizani.breaks),

9mpl_format() (in module

mizani.formatters), 13

Ppercent_format() (in module

mizani.formatters), 13probability_trans() (in module

mizani.transforms), 23probit_trans (in module

mizani.transforms), 23

Rrescale() (in module mizani.bounds), 5rescale_max() (in module

mizani.bounds), 6rescale_mid() (in module mizani.bounds),

5rescale_pal() (in module mizani.palettes),

15reverse_trans (class in mizani.transforms),

22

Sscale_continuous (class in mizani.scale),

24scale_discrete (class in mizani.scale), 25scientific_format() (in module

mizani.formatters), 13sqrt_trans (class in mizani.transforms), 22squish_infinite() (in module

mizani.bounds), 6

Ttimedelta_breaks() (in module

mizani.breaks), 11timedelta_format() (in module

mizani.formatters), 14timedelta_trans (class in

mizani.transforms), 23, 24train() (mizani.scale.scale_continuous

class method), 25train() (mizani.scale.scale_discrete class

method), 26trans (class in mizani.transforms), 20

30 Index


trans_minor_breaks() (in modulemizani.breaks), 10

trans_new() (in modulemizani.transforms), 20

transform (mizani.transforms.atanh_transattribute), 23

transform (mizani.transforms.log10_transattribute), 22

transform (mizani.transforms.log1p_transattribute), 22

transform (mizani.transforms.log2_transattribute), 22

transform (mizani.transforms.reverse_transattribute), 22

transform (mizani.transforms.sqrt_transattribute), 22

transform() (mizani.transforms.datetime_transstatic method), 23

transform() (mizani.transforms.timedelta_transstatic method), 24

transform() (mizani.transforms.transstatic method), 20

Zzero_range() (in module mizani.bounds),

7

Index 31

Documents

MizaniDocumentation · MizaniDocumentation,Release0+untagged.4.g46cd51e.dirty mizani.bounds.squish_infinite(x, range=(0, 1))Truncate inﬁnite values to a range Parameters • x (array_like)