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.comma_format(digits=0)

Format number with commas separating thousands

Parameters:

digitsint

Number of digits after the decimal point.

Examples

>>> comma_format()([1000, 2, 33000, 400])
['1,000', '2', '33,000', '400']

__call__(x)

Format a sequence of inputs

Parameters:

xarray

Input

Returns:

outlist

List of strings.

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

Custom format

Parameters:

fmtstr, 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__(x)

Format a sequence of inputs

Parameters:

xarray

Input

Returns:

outlist

List of strings.

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

Currency formatter

Parameters:

prefixstr

What to put before the value.

suffixstr

What to put after the value.

digitsint

Number of significant digits

big_markstr

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__(x)

Format a sequence of inputs

Parameters:

xarray

Input

Returns:

outlist

List of strings.

mizani.formatters.dollar_format

alias of currency_format

class mizani.formatters.percent_format(use_comma=False)

Percent formatter

Multiply by one hundred and display percent sign

Parameters:

use_commabool

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__(x)

Format a sequence of inputs

Parameters:

xarray

Input

Returns:

outlist

List of strings.

class mizani.formatters.scientific_format(digits=3)

Scientific formatter

Parameters:

digitsint

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__(x)

Call self as a function.

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

Datetime formatter

Parameters:

fmtstr

Format string. See strftime.

tzdatetime.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

>>> 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 = ZoneInfo('UTC')
>>> UG = ZoneInfo('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:00', '2010-01-01 15:00']

Format with a specific time zone

>>> date_format('%Y-%m-%d %H:%M', tz=UTC)(x_tz)
['2010-01-01 05:00', '2010-01-01 12:00']
>>> date_format('%Y-%m-%d %H:%M', tz='EST')(x_tz)
['2010-01-01 00:00', '2010-01-01 07:00']

__call__(x)

Format a sequence of inputs

Parameters:

xarray

Input

Returns:

outlist

List of strings.

class mizani.formatters.mpl_format

Format using MPL formatter for scalars

Examples

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

__call__(x)

Format a sequence of inputs

Parameters:

xarray

Input

Returns:

outlist

List of strings.

class mizani.formatters.log_format(base=10, exponent_limits=(-4, 4), mathtex=False)

Log Formatter

Parameters:

baseint

Base of the logarithm. Default is 10.

exponent_limitstuple

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.

mathtexbool

If True, return the labels in mathtex format as understood by Matplotlib.

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

>>> log_format(mathtex=True)([0.0001, 0.1, 10000])
['$10^{-4}$', '$10^{-1}$', '$10^{4}$']

__call__(x)

Format a sequence of inputs

Parameters:

xarray

Input

Returns:

outlist

List of strings.

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

Timedelta formatter

Parameters:

unitsstr, 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_unitsbool

Whether to append the units identifier string to the values.

usetextbool

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__(x)

Call self as a function.

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

p-values Formatter

Parameters:

accuracyfloat

Number to round to

add_pbool

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__(x)

Format a sequence of inputs

Parameters:

xarray

Input

Returns:

outlist

List of strings.

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

Ordinal Formatter

Parameters:

prefixstr

What to put before the value.

suffixstr

What to put after the value.

big_markstr

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__(x)

Call self as a function.

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

Bytes Formatter

Parameters:

symbolstr

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".

fmtstr, 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__(x)

Call self as a function.