labels - 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 label_* 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.labels.label_comma(accuracy: float | None = None, precision: int = 0, scale: float = 1, prefix: str = '', suffix: str = '', big_mark: str = ',', decimal_mark: str = '.', fill: str = '', style_negative: Literal['-', 'hyphen', 'parens'] = '-', style_positive: Literal['', '+', ' '] = '', align: Literal['<', '>', '=', '^'] = '>', width: int | None = None)[source]¶

Labels of numbers with commas as separators

Parameters:

precisionint: Number of digits after the decimal point.

Examples

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

class mizani.labels.label_custom(fmt: str = '{}', style: Literal['old', 'new'] = 'new')[source]¶

Creating a custom labelling function

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

>>> label = label_custom('{:.2f} USD')
>>> label([3.987, 2, 42.42])
['3.99 USD', '2.00 USD', '42.42 USD']

__call__(x: FloatArrayLike) → Sequence[str][source]¶

Format a sequence of inputs

Parameters:

xarray: Input

Returns:

outlist: List of strings.

class mizani.labels.label_currency(accuracy: float | None = None, precision: int | None = None, scale: float = 1, prefix: str = '$', suffix: str = '', big_mark: str = '', decimal_mark: str = '.', fill: str = '', style_negative: Literal['-', 'hyphen', 'parens'] = '-', style_positive: Literal['', '+', ' '] = '', align: Literal['<', '>', '=', '^'] = '>', width: int | None = None)[source]¶

Labelling currencies

Parameters:

prefixstr: What to put before the value.

Examples

>>> x = [1.232, 99.2334, 4.6, 9, 4500]
>>> label_currency()(x)
['$1.23', '$99.23', '$4.60', '$9.00', '$4500.00']
>>> label_currency(prefix='C$', precision=0, big_mark=',')(x)
['C$1', 'C$99', 'C$5', 'C$9', 'C$4,500']

mizani.labels.label_dollar¶: alias of label_currency

class mizani.labels.label_percent(accuracy: float | None = None, precision: int | None = None, scale: float = 100, prefix: str = '', suffix: str = '%', big_mark: str = '', decimal_mark: str = '.', fill: str = '', style_negative: Literal['-', 'hyphen', 'parens'] = '-', style_positive: Literal['', '+', ' '] = '', align: Literal['<', '>', '=', '^'] = '>', width: int | None = None)[source]¶

Labelling percentages

Multiply by one hundred and display percent sign

Examples

>>> label = label_percent()
>>> label([.45, 9.515, .01])
['45%', '952%', '1%']
>>> label([.654, .8963, .1])
['65%', '90%', '10%']

class mizani.labels.label_scientific(digits: int = 3)[source]¶

Scientific number labels

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]
>>> label_scientific()(x)
['1.2e-01', '2.3e-01', '3.4e-01', '4.5e+01']

__call__(x: FloatArrayLike) → Sequence[str][source]¶: Call self as a function.

class mizani.labels.label_date(fmt: str = '%Y-%m-%d', tz: tzinfo | None = None)[source]¶

Datetime labels

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]]
>>> label_date()(x)
['2010-01-01', '2014-01-01', '2018-01-01', '2022-01-01']
>>> label_date('%Y')(x)
['2010', '2014', '2018', '2022']

Can format time

>>> x = [datetime(2017, 12, 1, 16, 5, 7)]
>>> label_date("%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]]
>>> label_date('%Y-%m-%d %H:%M')(x)
['2010-01-01 08:00', '2010-01-01 15:00']
>>> label_date('%Y-%m-%d %H:%M')(x_tz)
['2010-01-01 08:00', '2010-01-01 15:00']

Format with a specific time zone

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

__call__(x: Sequence[datetime]) → Sequence[str][source]¶

Format a sequence of inputs

Parameters:

xarray: Input

Returns:

outlist: List of strings.

class mizani.labels.label_number(accuracy: float | None = None, precision: int | None = None, scale: float = 1, prefix: str = '', suffix: str = '', big_mark: str = '', decimal_mark: str = '.', fill: str = '', style_negative: Literal['-', 'hyphen', 'parens'] = '-', style_positive: Literal['', '+', ' '] = '', align: Literal['<', '>', '=', '^'] = '>', width: int | None = None)[source]¶

Labelling numbers

Parameters:

precisionint: Number of digits after the decimal point.
suffixstr: What to put after the value.
big_markstr: The thousands separator. This is usually a comma or a dot.
decimal_markstr: What to use to separate the decimals digits.

Examples

>>> label_number()([.654, .8963, .1])
['0.65', '0.90', '0.10']
>>> label_number(accuracy=0.0001)([.654, .8963, .1])
['0.6540', '0.8963', '0.1000']
>>> label_number(precision=4)([.654, .8963, .1])
['0.6540', '0.8963', '0.1000']
>>> label_number(prefix="$")([5, 24, -42])
['$5', '$24', '-$42']
>>> label_number(suffix="s")([5, 24, -42])
['5s', '24s', '-42s']
>>> label_number(big_mark="_")([1e3, 1e4, 1e5, 1e6])
['1_000', '10_000', '100_000', '1_000_000']
>>> label_number(width=3)([1, 10, 100, 1000])
['  1', ' 10', '100', '1000']
>>> label_number(align="^", width=5)([1, 10, 100, 1000])
['  1  ', ' 10  ', ' 100 ', '1000 ']
>>> label_number(style_positive=" ")([5, 24, -42])
[' 5', ' 24', '-42']
>>> label_number(style_positive="+")([5, 24, -42])
['+5', '+24', '-42']
>>> label_number(prefix="$", style_negative="braces")([5, 24, -42])
['$5', '$24', '($42)']

__call__(x: FloatArrayLike) → Sequence[str][source]¶: Call self as a function.

class mizani.labels.label_log(base: float = 10, exponent_limits: TupleInt2 = (-4, 4), mathtex: bool = False)[source]¶

Log number labels

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

>>> label_log()([0.001, 0.1, 100])
['0.001', '0.1', '100']

>>> label_log()([0.0001, 0.1, 10000])
['1e-4', '1e-1', '1e4']

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

__call__(x: FloatArrayLike) → Sequence[str][source]¶

Format a sequence of inputs

Parameters:

xarray: Input

Returns:

outlist: List of strings.

class mizani.labels.label_timedelta(units: DurationUnit | None = None, show_units: bool = True, zero_has_units: bool = True, usetex: bool = False, space: bool = True, use_plurals: bool = True)[source]¶

Timedelta labels

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'     # seconds
'min'   # minute
'h'     # hour
'day'     # day
'week'  # week
'month' # month
'year'  # year

show_unitsbool

Whether to append the units symbol to the values.

zero_has_unitsbool

If True a value of zero

usetexbool

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

spacebool

If True add a space between the value and the units

use_pluralsbool

If True, for the when the value is not 1 and the units are one of week, month and year, the plural form of the unit is used e.g. 2 weeks.

Examples

>>> from datetime import timedelta
>>> x = [timedelta(days=31*i) for i in range(5)]
>>> label_timedelta()(x)
['0 months', '1 month', '2 months', '3 months', '4 months']
>>> label_timedelta(use_plurals=False)(x)
['0 month', '1 month', '2 month', '3 month', '4 month']
>>> label_timedelta(units='day')(x)
['0 days', '31 days', '62 days', '93 days', '124 days']
>>> label_timedelta(units='day', zero_has_units=False)(x)
['0', '31 days', '62 days', '93 days', '124 days']
>>> label_timedelta(units='day', show_units=False)(x)
['0', '31', '62', '93', '124']

__call__(x: NDArrayTimedelta) → Sequence[str][source]¶: Call self as a function.

class mizani.labels.label_pvalue(accuracy: float = 0.001, add_p: float = False)[source]¶

p-values labelling

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]
>>> label_pvalue()(x)
['0.9', '0.15', '0.015', '0.009', '<0.001']
>>> label_pvalue(0.1)(x)
['0.9', '0.1', '<0.1', '<0.1', '<0.1']
>>> label_pvalue(0.1, True)(x)
['p=0.9', 'p=0.1', 'p<0.1', 'p<0.1', 'p<0.1']

__call__(x: FloatArrayLike) → Sequence[str][source]¶

Format a sequence of inputs

Parameters:

xarray: Input

Returns:

outlist: List of strings.

class mizani.labels.label_ordinal(prefix: str = '', suffix: str = '', big_mark: str = '')[source]¶

Ordinal number labelling

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

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

__call__(x: FloatArrayLike) → Sequence[str][source]¶: Call self as a function.

class mizani.labels.label_bytes(symbol: Literal['auto'] | BytesSymbol = 'auto', units: Literal['binary', 'si'] = 'binary', fmt: str = '{:.0f} ')[source]¶

Labelling byte numbers

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]
>>> label_bytes()(x)
['1000 B', '977 KiB', '391 KiB']
>>> label_bytes(units='si')(x)
['1 kB', '1 MB', '400 kB']

__call__(x: FloatArrayLike) → Sequence[str][source]¶: Call self as a function.