formatters - Labelling breaks

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

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

class mizani.formatters.custom_format(fmt='{}', style='new')[source]

Custom format

Parameters:
fmt : str, optional

Format string. Default is the generic new style format braces, {}.

style : 'new' | 'old'

Whether to use new style or old style formatting. New style uses the str.format() while old style uses %. The format string must be written accordingly.

Examples

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

Format a sequence of inputs

Parameters:
x : array

Input

Returns:
out : list

List of strings.

class mizani.formatters.currency_format(prefix='$', suffix='', digits=2, big_mark='')[source]

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 a comma or a dot.

Examples

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

Format a sequence of inputs

Parameters:
x : array

Input

Returns:
out : list

List of strings.

mizani.formatters.dollar_format

alias of mizani.formatters.currency_format

class mizani.formatters.percent_format(use_comma=False)[source]

Percent formatter

Multiply by one hundred and display percent sign

Parameters:
use_comma : bool

If True, use a comma to separate the thousands. Default is False.

Examples

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

Format a sequence of inputs

Parameters:
x : array

Input

Returns:
out : list

List of strings.

class mizani.formatters.scientific_format(digits=3)[source]

Scientific formatter

Parameters:
digits : int

Significant digits.

Notes

Be careful when using many digits (15+ on a 64 bit computer). Consider of the machine epsilon.

Examples

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

Call self as a function.

class mizani.formatters.mpl_format[source]

Format using MPL formatter for scalars

Examples

>>> mpl_format()([.654, .8963, .1])
['0.6540', '0.8963', '0.1000']
__call__(self, x)[source]

Format a sequence of inputs

Parameters:
x : array

Input

Returns:
out : list

List of strings.

class mizani.formatters.log_format(base=10, exponent_limits=(-4, 4), **kwargs)[source]

Log Formatter

Parameters:
base : int

Base of the logarithm. Default is 10.

exponent_limits : tuple

limits (int, int) where if the any of the powers of the numbers falls outside, then the labels will be in exponent form. This only applies for base 10.

Examples

>>> log_format()([0.001, 0.1, 100])
['0.001', '0.1', '100']
>>> log_format()([0.0001, 0.1, 10000])
['1e-4', '1e-1', '1e4']
__call__(self, x)[source]

Format a sequence of inputs

Parameters:
x : array

Input

Returns:
out : list

List of strings.

class mizani.formatters.date_format(fmt='%Y-%m-%d', tz=None)[source]

Datetime formatter

Parameters:
fmt : str

Format string. See strftime.

tz : datetime.tzinfo, optional

Time zone information. If none is specified, the time zone will be that of the first date. If the first date has no time information then a time zone is chosen by other means.

Examples

>>> import pytz
>>> 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']

Can format time

>>> x = [datetime(2017, 12, 1, 16, 5, 7)]
>>> date_format("%Y-%m-%d %H:%M:%S")(x)
['2017-12-01 16:05:07']

Time zones are respected

>>> utc = pytz.timezone('UTC')
>>> ug = pytz.timezone('Africa/Kampala')
>>> x = [datetime(2010, 1, 1, i) for i in [8, 15]]
>>> x_tz = [datetime(2010, 1, 1, i, tzinfo=ug) for i in [8, 15]]
>>> date_format('%Y-%m-%d %H:%M')(x)
['2010-01-01 08:00', '2010-01-01 15:00']
>>> date_format('%Y-%m-%d %H:%M')(x_tz)
['2010-01-01 08:33', '2010-01-01 15:33']

Format with a specific time zone

>>> date_format('%Y-%m-%d %H:%M', tz=utc)(x_tz)
['2010-01-01 05:33', '2010-01-01 12:33']
__call__(self, x)[source]

Format a sequence of inputs

Parameters:
x : array

Input

Returns:
out : list

List of strings.

class mizani.formatters.timedelta_format(units=None, add_units=True, usetex=False)[source]

Timedelta formatter

Parameters:
units : str, optional

The units in which the breaks will be computed. If None, they are decided automatically. Otherwise, the value should be one of:

'ns'    # nanoseconds
'us'    # microseconds
'ms'    # milliseconds
's'     # secondss
'm'     # minute
'h'     # hour
'd'     # day
'w'     # week
'M'     # month
'y'     # year
add_units : bool

Whether to append the units identifier string to the values.

usetext : bool

If True, they microseconds identifier string is rendered with greek letter mu. Default is False.

Examples

>>> 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']
>>> timedelta_format(units='d', add_units=False)(x)
['0', '31', '62', '93', '124']
__call__(self, x)[source]

Call self as a function.

class mizani.formatters.pvalue_format(accuracy=0.001, add_p=False)[source]

p-values Formatter

Parameters:
accuracy : float

Number to round to

add_p : bool

Whether to prepend "p=" or "p<" to the output

Examples

>>> x = [.90, .15, .015, .009, 0.0005]
>>> pvalue_format()(x)
['0.9', '0.15', '0.015', '0.009', '<0.001']
>>> pvalue_format(0.1)(x)
['0.9', '0.1', '<0.1', '<0.1', '<0.1']
>>> pvalue_format(0.1, True)(x)
['p=0.9', 'p=0.1', 'p<0.1', 'p<0.1', 'p<0.1']
__call__(self, x)[source]

Format a sequence of inputs

Parameters:
x : array

Input

Returns:
out : list

List of strings.

class mizani.formatters.ordinal_format(prefix='', suffix='', big_mark='')[source]

Ordinal Formatter

Parameters:
prefix : str

What to put before the value.

suffix : str

What to put after the value.

big_mark : str

The thousands separator. This is usually a comma or a dot.

Examples

>>> ordinal_format()(range(8))
['0th', '1st', '2nd', '3rd', '4th', '5th', '6th', '7th']
>>> ordinal_format(suffix=' Number')(range(11, 15))
['11th Number', '12th Number', '13th Number', '14th Number']
__call__(self, x)[source]

Call self as a function.

class mizani.formatters.number_bytes_format(symbol='auto', units='binary', fmt='{:.0f} ')[source]

Bytes Formatter

Parameters:
symbol : str

Valid symbols are "B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", and "YB" for SI units, and the "iB" variants for binary units. Default is "auto" where the symbol to be used is determined separately for each value of 1x.

units : "binary" | "si"

Which unit base to use, 1024 for "binary" or 1000 for "si".

fmt : str, optional

Format sting. Default is {:.0f}.

Examples

>>> x = [1000, 1000000, 4e5]
>>> number_bytes_format()(x)
['1000 B', '977 KiB', '391 KiB']
>>> number_bytes_format(units='si')(x)
['1 kB', '1 MB', '400 kB']
__call__(self, x)[source]

Call self as a function.