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.breaks_log(n: int = 5, base: float = 10)[source]¶
Integer breaks on log transformed scales
- Parameters:
- n
python:int
Desired number of breaks
- base
python:int
Base of logarithm
- n
Examples
>>> x = np.logspace(3, 6) >>> limits = min(x), max(x) >>> breaks_log()(limits) array([ 1000, 10000, 100000, 1000000]) >>> breaks_log(2)(limits) array([ 1000, 100000]) >>> breaks_log()([0.1, 1]) array([0.1, 0.3, 1. , 3. ])
- class mizani.breaks.breaks_symlog[source]¶
Breaks for the Symmetric Logarithm Transform
- Parameters:
- n
python:int
Desired number of breaks
- base
python:int
Base of logarithm
- n
Examples
>>> limits = (-100, 100) >>> breaks_symlog()(limits) array([-100, -10, 0, 10, 100])
- class mizani.breaks.minor_breaks(n: int = 1)[source]¶
Compute minor breaks
This is the naive method. It does not take into account the transformation.
- Parameters:
- n
python:int
Number of minor breaks between the major breaks.
- n
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__(major: FloatArrayLike, limits: TupleFloat2 | None = None, n: int | None = None) NDArrayFloat [source]¶
Minor breaks
- Parameters:
- majornumpy:array_like
Major breaks
- limitsnumpy:array_like |
python: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
python:int
Number of minor breaks between the major breaks. If None, then self.n is used.
- Returns:
- outnumpy:array_like
Minor beraks
- class mizani.breaks.minor_breaks_trans(trans: Trans, n: int = 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()
likelog10_trans
.- Parameters:
- trans
trans
or type Trans object or trans class.
- n
python:int
Number of minor breaks between the major breaks.
- trans
Examples
>>> from mizani.transforms import sqrt_trans >>> major = [1, 2, 3, 4] >>> limits = [0, 5] >>> t1 = sqrt_trans() >>> t1.minor_breaks(major, limits) array([1.58113883, 2.54950976, 3.53553391])
# Changing the regular minor_breaks method
>>> t2 = sqrt_trans() >>> t2.minor_breaks = minor_breaks() >>> t2.minor_breaks(major, limits) array([0.5, 1.5, 2.5, 3.5, 4.5])
More than 1 minor break
>>> major = [1, 10] >>> limits = [1, 10] >>> t2.minor_breaks(major, limits, 4) array([2.8, 4.6, 6.4, 8.2])
- __call__(major: FloatArrayLike, limits: TupleFloat2 | None = None, n: int | None = None) NDArrayFloat [source]¶
Minor breaks for transformed scales
- Parameters:
- majornumpy:array_like
Major breaks
- limitsnumpy:array_like |
python: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
python:int
Number of minor breaks between the major breaks. If None, then self.n is used.
- Returns:
- outnumpy:array_like
Minor breaks
- class mizani.breaks.breaks_date(n: int = 5, width: str | None = None)[source]¶
Regularly spaced dates
- Parameters:
- n
Desired number of breaks.
- width
python:str
|python: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 >>> limits = (datetime(2010, 1, 1), datetime(2026, 1, 1))
Default breaks will be regularly spaced but the spacing is automatically determined
>>> breaks = breaks_date(9) >>> [d.year for d in breaks(limits)] [2010, 2012, 2014, 2016, 2018, 2020, 2022, 2024, 2026]
Breaks at 4 year intervals
>>> breaks = breaks_date('4 year') >>> [d.year for d in breaks(limits)] [2010, 2014, 2018, 2022, 2026]
- class mizani.breaks.breaks_timedelta(n: int = 5, Q: Sequence[float] = (1, 2, 5, 10))[source]¶
Timedelta breaks
- Returns:
- out
python:callable()
f(limits)
A function that takes a sequence of two
datetime.timedelta
values and returns a sequence of break points.
- out
Examples
>>> from datetime import timedelta >>> breaks = breaks_timedelta() >>> 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]
- class mizani.breaks.breaks_extended(n: int = 5, Q: Sequence[float] = (1, 5, 2, 2.5, 4, 3), only_inside: bool = False, w: Sequence[float] = (0.25, 0.2, 0.5, 0.05))[source]¶
An extension of Wilkinson's tick position algorithm
- Parameters:
- n
python:int
Desired number of breaks
- Q
python:list
List of nice numbers
- only_insidebool
If
True
, then all the breaks will be within the given range.- w
python:list
Weights applied to the four optimization components (simplicity, coverage, density, and legibility). They should add up to 1.
- n
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) >>> breaks_extended()(limits) array([ 0. , 2.5, 5. , 7.5, 10. ]) >>> breaks_extended(n=6)(limits) array([ 0., 2., 4., 6., 8., 10.])