breaks - Partitioning a scale for readability

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

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

class mizani.breaks.mpl_breaks(*args, **kwargs)[source]

Compute breaks using MPL's default locator

See MaxNLocator for the parameter descriptions

Examples

>>> 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.])
__call__(self, limits)[source]

Compute breaks

Parameters:
limits : tuple

Minimum and maximum values

Returns:
out : array_like

Sequence of breaks points

class mizani.breaks.log_breaks(n=5, base=10)[source]

Integer breaks on log transformed scales

Parameters:
n : int

Desired number of breaks

base : int

Base of logarithm

Examples

>>> x = np.logspace(3, 6)
>>> limits = min(x), max(x)
>>> log_breaks()(limits)
array([     100,     1000,    10000,   100000,  1000000])
>>> log_breaks(2)(limits)
array([   100, 100000])
>>> log_breaks()([0.1, 1])
array([0.1, 0.3, 1. , 3. ])
__call__(self, limits)[source]

Compute breaks

Parameters:
limits : tuple

Minimum and maximum values

Returns:
out : array_like

Sequence of breaks points

class mizani.breaks.minor_breaks(n=1)[source]

Compute minor breaks

Parameters:
n : int

Number of minor breaks between the major breaks.

Examples

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

More than 1 minor break.

>>> minor_breaks(3)([1, 2], (1, 2))
array([1.25, 1.5 , 1.75])
>>> minor_breaks()([1, 2], (1, 2), 3)
array([1.25, 1.5 , 1.75])
__call__(self, major, limits=None, n=None)[source]

Minor breaks

Parameters:
major : array_like

Major breaks

limits : array_like | None

Limits of the scale. If array_like, must be of size 2. If None, then the minimum and maximum of the major breaks are used.

n : int

Number of minor breaks between the major breaks. If None, then self.n is used.

Returns:
out : array_like

Minor beraks

class mizani.breaks.trans_minor_breaks(trans, n=1)[source]

Compute minor breaks for transformed scales

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

Parameters:
trans : trans or type

Trans object or trans class.

n : int

Number of minor breaks between the major breaks.

Examples

>>> 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):
...     def __init__(self):
...         self.minor_breaks = trans_minor_breaks(sqrt_trans2)
>>> sqrt_trans2().minor_breaks(major, limits)
array([1.58113883, 2.54950976, 3.53553391])

More than 1 minor break

>>> major = [1, 10]
>>> limits = [1, 10]
>>> sqrt_trans().minor_breaks(major, limits, 4)
array([2.8, 4.6, 6.4, 8.2])
__call__(self, major, limits=None, n=None)[source]

Minor breaks for transformed scales

Parameters:
major : array_like

Major breaks

limits : array_like | None

Limits of the scale. If array_like, must be of size 2. If None, then the minimum and maximum of the major breaks are used.

n : int

Number of minor breaks between the major breaks. If None, then self.n is used.

Returns:
out : array_like

Minor breaks

class mizani.breaks.date_breaks(width=None)[source]

Regularly spaced dates

Parameters:
width : str | None

An interval specification. Must be one of [second, minute, hour, day, week, month, year] If None, the interval automatic.

Examples

>>> 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 determined

>>> limits = min(x), max(x)
>>> breaks = date_breaks()
>>> [d.year for d in breaks(limits)]
[2010, 2012, 2014, 2016, 2018, 2020, 2022, 2024, 2026]

Breaks at 4 year intervals

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

Compute breaks

Parameters:
limits : tuple

Minimum and maximum datetime.datetime values.

Returns:
out : array_like

Sequence of break points.

class mizani.breaks.timedelta_breaks(n=5, Q=(1, 2, 5, 10))[source]

Timedelta breaks

Returns:
out : callable() f(limits)

A function that takes a sequence of two datetime.timedelta values and returns a sequence of break points.

Examples

>>> 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]
__call__(self, limits)[source]

Compute breaks

Parameters:
limits : tuple

Minimum and maximum datetime.timedelta values.

Returns:
out : array_like

Sequence of break points.

class mizani.breaks.extended_breaks(n=5, Q=[1, 5, 2, 2.5, 4, 3], only_inside=False, w=[0.25, 0.2, 0.5, 0.05])[source]

An extension of Wilkinson's tick position algorithm

Parameters:
n : int

Desired number of ticks

Q : list

List of nice numbers

only_inside : bool

If True, then all the ticks will be within the given range.

w : list

Weights applied to the four optimization components (simplicity, coverage, density, and legibility). They should add up to 1.

References

  • Talbot, J., Lin, S., Hanrahan, P. (2010) An Extension of Wilkinson's Algorithm for Positioning Tick Labels on Axes, InfoVis 2010.

Additional Credit to Justin Talbot on whose code this implementation is almost entirely based.

Examples

>>> limits = (0, 9)
>>> extended_breaks()(limits)
array([  0. ,   2.5,   5. ,   7.5,  10. ])
>>> extended_breaks(n=6)(limits)
array([  0.,   2.,   4.,   6.,   8.,  10.])
__call__(self, limits)[source]

Calculate the breaks

Parameters:
limits : array

Minimum and maximum values.

Returns:
out : array_like

Sequence of break points.