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

Format a sequence of inputs

Parameters:x (array) -- Input
Returns:out -- List of strings.
Return type:list
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__(x)[source]

Format a sequence of inputs

Parameters:x (array) -- Input
Returns:out -- List of strings.
Return type:list
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__(x)[source]

Format a sequence of inputs

Parameters:x (array) -- Input
Returns:out -- List of strings.
Return type:list
class mizani.formatters.scientific_format(digits=3)[source]

Scientific formatter

Parameters:digits (int) -- Significant digits.

Examples

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

Notes

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

__call__(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__(x)[source]

Format a sequence of inputs

Parameters:x (array) -- Input
Returns:out -- List of strings.
Return type:list
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__(x)[source]

Format a sequence of inputs

Parameters:x (array) -- Input
Returns:out -- List of strings.
Return type:list
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__(x)[source]

Format a sequence of inputs

Parameters:x (array) -- Input
Returns:out -- List of strings.
Return type:list
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__(x)[source]

Call self as a function.