Source code for mizani.labels

"""
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.
"""
from __future__ import annotations

import re
import typing
from bisect import bisect_right
from dataclasses import dataclass
from zoneinfo import ZoneInfo

import numpy as np

from .breaks import timedelta_helper
from .utils import (
    match,
    precision,
    round_any,
    same_log10_order_of_magnitude,
)

if typing.TYPE_CHECKING:
    from datetime import datetime, tzinfo
    from typing import Literal, Optional, Sequence

    from mizani.typing import (
        BytesSymbol,
        DurationUnit,
        FloatArrayLike,
        NDArrayTimedelta,
        TupleInt2,
    )

__all__ = [
    "label_comma",
    "label_custom",
    "label_currency",
    "label_dollar",
    "label_percent",
    "label_scientific",
    "label_date",
    "label_number",
    "label_log",
    "label_timedelta",
    "label_pvalue",
    "label_ordinal",
    "label_bytes",
]

UTC = ZoneInfo("UTC")


[docs] @dataclass class label_number: """ Labelling numbers Parameters ---------- precision : int Number of digits after the decimal point. suffix : str What to put after the value. big_mark : str The thousands separator. This is usually a comma or a dot. decimal_mark : str 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)'] """ accuracy: Optional[float] = None precision: Optional[int] = 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: Optional[int] = None def __post_init__(self): if self.precision is not None: if self.accuracy is not None: raise ValueError("Specify only one of precision or accuracy") self.accuracy = 10**-self.precision
[docs] def __call__(self, x: FloatArrayLike) -> Sequence[str]: # Construct formatting according to # https://docs.python.org/3/library/string.html#format-string-syntax # Specfically using the Format Specification Mini-Language # python format only accepts ",", "_" to separate the thousands # if we have a non-standard value, we use "," & replace it after valid_big_mark = self.big_mark in ("", ",", "_") sep = self.big_mark if valid_big_mark else "," fmt = ( f"{self.prefix}" f"{{num:{sep}.{{precision}}f}}" f"{self.suffix}" ).format x = np.asarray(x) x_scaled = x * self.scale if self.accuracy is None: accuracy = precision(x_scaled) else: accuracy = self.accuracy x = round_any(x, accuracy / self.scale) digits = -np.floor(np.log10(accuracy)).astype(int) digits = np.minimum(np.maximum(digits, 0), 20) res = [fmt(num=abs(n), precision=digits) for n in x_scaled] if not valid_big_mark: res = [s.replace(",", self.big_mark) for s in res] if self.decimal_mark != ".": res = [s.replace(".", self.decimal_mark) for s in res] pos_fmt = f"{self.style_positive}{{s}}".format if self.style_negative == "-": neg_fmt = "-{s}".format elif self.style_negative == "hyphen": neg_fmt = "\u2212{s}".format else: neg_fmt = "({s})".format res = [ neg_fmt(s=s) if num < 0 else pos_fmt(s=s) for num, s in zip(x, res) ] if self.width is not None: fmt = f"{{s:{self.fill}{self.align}{self.width}}}".format res = [fmt(s=s) for s in res] return res
[docs] @dataclass class label_custom: """ Creating a custom labelling function 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 :meth:`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'] """ fmt: str = "{}" style: Literal["old", "new"] = "new"
[docs] def __call__(self, x: FloatArrayLike) -> Sequence[str]: """ Format a sequence of inputs Parameters ---------- x : array Input Returns ------- out : list List of strings. """ if self.style == "new": return [self.fmt.format(val) for val in x] elif self.style == "old": return [self.fmt % val for val in x] else: raise ValueError("style should be either 'new' or 'old'")
# formatting functions
[docs] @dataclass class label_currency(label_number): """ Labelling currencies Parameters ---------- prefix : str 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'] """ prefix: str = "$" def __post_init__(self): if self.precision is None and self.accuracy is None: self.precision = 2 super().__post_init__()
label_dollar = label_currency dollar = label_dollar()
[docs] @dataclass class label_comma(label_currency): """ Labels of numbers with commas as separators Parameters ---------- precision : int Number of digits after the decimal point. Examples -------- >>> label_comma()([1000, 2, 33000, 400]) ['1,000', '2', '33,000', '400'] """ prefix: str = "" precision: int = 0 big_mark: str = ","
[docs] @dataclass class label_percent(label_number): """ 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%'] """ scale: float = 100 suffix: str = "%"
percent = label_percent()
[docs] @dataclass class label_scientific: """ Scientific number labels Parameters ---------- digits : int Significant digits. Examples -------- >>> x = [.12, .23, .34, 45] >>> label_scientific()(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`_. .. _machine epsilon: https://en.wikipedia.org/wiki/Machine_epsilon """ digits: int = 3 def __post_init__(self): tpl = f"{{:.{self.digits}e}}" self._label = label_custom(tpl) self.trailling_zeros_pattern = re.compile(r"(0+)e")
[docs] def __call__(self, x: FloatArrayLike) -> Sequence[str]: if len(x) == 0: return [] def count_zeros(s): match = self.trailling_zeros_pattern.search(s) if match: return len(match.group(1)) else: return 0 # format and then remove superfluous zeros labels = self._label(x) n = min([count_zeros(val) for val in labels]) if n: labels = [val.replace("0" * n + "e", "e") for val in labels] return labels
scientific = label_scientific()
[docs] @dataclass class label_log: """ Log number labels 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. mathtex : bool 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}$'] """ base: float = 10 exponent_limits: TupleInt2 = (-4, 4) mathtex: bool = False def _tidyup_labels(self, labels: Sequence[str]) -> Sequence[str]: """ Make all labels uniform in format Remove redundant zeros for labels in exponential format. Parameters ---------- labels : list-like Labels to be tidied. Returns ------- out : list-like Labels """ def remove_zeroes(s: str) -> str: """ Remove unnecessary zeros for float string s """ tup = s.split("e") if len(tup) == 2: mantissa = tup[0].rstrip("0").rstrip(".") exponent = int(tup[1]) s = f"{mantissa}e{exponent}" if exponent else mantissa return s def as_exp(s: str) -> str: """ Float string s as in exponential format """ return s if "e" in s else "{:1.0e}".format(float(s)) def as_mathtex(s: str) -> str: """ Mathtex for maplotlib """ if "e" not in s: assert s == "1", f"Unexpected value {s = }, instead of '1'" return f"${self.base}^{{0}}$" exp = s.split("e")[1] return f"${self.base}^{{{exp}}}$" # If any are in exponential format, make all of # them expontential has_e = ["e" in x for x in labels] if not all(has_e) and sum(has_e): labels = [as_exp(x) for x in labels] labels = [remove_zeroes(x) for x in labels] has_e = ["e" in x for x in labels] if self.mathtex and any(has_e): labels = [as_mathtex(x) for x in labels] return labels
[docs] def __call__(self, x: FloatArrayLike) -> Sequence[str]: """ Format a sequence of inputs Parameters ---------- x : array Input Returns ------- out : list List of strings. """ if len(x) == 0: return [] # Decide on using exponents if self.base == 10: xmin = int(np.floor(np.log10(np.min(x)))) xmax = int(np.ceil(np.log10(np.max(x)))) emin, emax = self.exponent_limits all_multiples = np.all([np.log10(num).is_integer() for num in x]) beyond_threshold = xmin <= emin or emax <= xmax use_exponents = ( same_log10_order_of_magnitude(x) or all_multiples ) and beyond_threshold fmt = "{:1.0e}" if use_exponents else "{:g}" labels = [fmt.format(num) for num in x] return self._tidyup_labels(labels) else: def _exp(num, base): e = np.log(num) / np.log(base) e_round = np.round(e) e = int(e_round) if np.isclose(e, e_round) else np.round(e, 3) return e base_txt = f"{self.base}" if self.base == np.e: base_txt = "e" if self.mathtex: fmt_parts = (f"${base_txt}^", "{{{e}}}$") else: fmt_parts = (f"{base_txt}^", "{e}") fmt = "".join(fmt_parts) exps = [_exp(num, self.base) for num in x] labels = [fmt.format(e=e) for e in exps] return labels
[docs] @dataclass class label_date: """ Datetime labels Parameters ---------- fmt : str Format string. See :ref:`strftime <strftime-strptime-behavior>`. 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 -------- >>> 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'] """ fmt: str = "%Y-%m-%d" tz: Optional[tzinfo] = None def __post_init__(self): if isinstance(self.tz, str): self.tz = ZoneInfo(self.tz)
[docs] def __call__(self, x: Sequence[datetime]) -> Sequence[str]: """ Format a sequence of inputs Parameters ---------- x : array Input Returns ------- out : list List of strings. """ if self.tz is not None: x = [d.astimezone(self.tz) for d in x] return [d.strftime(self.fmt) for d in x]
[docs] @dataclass class label_timedelta: """ Timedelta labels 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' # seconds 'min' # minute 'h' # hour 'day' # day 'week' # week 'month' # month 'year' # year show_units : bool Whether to append the units symbol to the values. zero_has_units : bool If True a value of zero usetex : bool If True, they microseconds identifier string is rendered with greek letter *mu*. Default is False. space : bool If True add a space between the value and the units use_plurals : bool 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'] """ units: Optional[DurationUnit] = None show_units: bool = True zero_has_units: bool = True usetex: bool = False space: bool = True use_plurals: bool = True
[docs] def __call__(self, x: NDArrayTimedelta) -> Sequence[str]: if len(x) == 0: return [] values, units = timedelta_helper.format_info(x, self.units) labels = list(label_number()(values)) if self.show_units: if self.usetex and units == "us": units = r"$\mu s$" if self.use_plurals and units in ("day", "week", "month", "year"): units_plural = f"{units}s" else: units_plural = units if self.space: units = f" {units}" units_plural = f" {units_plural}" for i, (num, label) in enumerate(zip(values, labels)): if num == 0 and not self.zero_has_units: continue elif num == 1: labels[i] = f"{label}{units}" else: labels[i] = f"{label}{units_plural}" return labels
[docs] @dataclass class label_pvalue: """ p-values labelling 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] >>> 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'] """ accuracy: float = 0.001 add_p: float = False
[docs] def __call__(self, x: FloatArrayLike) -> Sequence[str]: """ Format a sequence of inputs Parameters ---------- x : array Input Returns ------- out : list List of strings. """ x = round_any(x, self.accuracy) below = [num < self.accuracy for num in x] if self.add_p: eq_fmt = "p={:g}".format below_label = f"p<{self.accuracy:g}" else: eq_fmt = "{:g}".format below_label = f"<{self.accuracy:g}" labels = [below_label if b else eq_fmt(i) for i, b in zip(x, below)] return labels
def ordinal(n: float, prefix="", suffix="", big_mark=""): # General Case: 0th, 1st, 2nd, 3rd, 4th, 5th, 6th, 7th, 8th, 9th # Special Case: 10th, 11th, 12th, 13th n = int(n) idx = np.min((n % 10, 4)) _suffix = ("th", "st", "nd", "rd", "th")[idx] if 11 <= (n % 100) <= 13: _suffix = "th" if big_mark: s = f"{n:,}" if big_mark != ",": s = s.replace(",", big_mark) else: s = f"{n}" return f"{prefix}{s}{_suffix}{suffix}"
[docs] @dataclass class label_ordinal: """ Ordinal number labelling 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 -------- >>> 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'] """ prefix: str = "" suffix: str = "" big_mark: str = ""
[docs] def __call__(self, x: FloatArrayLike) -> Sequence[str]: labels = [ ordinal(num, self.prefix, self.suffix, self.big_mark) for num in x ] return labels
[docs] @dataclass class label_bytes: """ Labelling byte numbers 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] >>> label_bytes()(x) ['1000 B', '977 KiB', '391 KiB'] >>> label_bytes(units='si')(x) ['1 kB', '1 MB', '400 kB'] """ symbol: Literal["auto"] | BytesSymbol = "auto" units: Literal["binary", "si"] = "binary" fmt: str = "{:.0f} " def __post_init__(self): if self.units == "si": self.base = 1000 self._all_symbols = ( "B", "kB", "MB", "GB", "TB", "PB", "EB", "ZB", "YB", ) else: self.base = 1024 self._all_symbols = ( "B", "KiB", "MiB", "GiB", "TiB", "PiB", "EiB", "ZiB", "YiB", ) # possible exponents of base: eg 1000^1, 1000^2, 1000^3, ... exponents = np.arange(1, len(self._all_symbols) + 1, dtype=float) self._powers = self.base**exponents self._validate_symbol(self.symbol, ("auto",) + self._all_symbols)
[docs] def __call__(self, x: FloatArrayLike) -> Sequence[str]: _all_symbols = self._all_symbols symbol = self.symbol if symbol == "auto": power = [bisect_right(self._powers, val) for val in x] symbols = [_all_symbols[p] for p in power] else: power = np.array(match([symbol], _all_symbols)) symbols = [symbol] * len(x) x = np.asarray(x) power = np.asarray(power, dtype=float) values = x / self.base**power fmt = (self.fmt + "{}").format labels = [fmt(v, s) for v, s in zip(values, symbols)] return labels
def _validate_symbol(self, symbol: str, allowed_symbols: Sequence[str]): if symbol not in allowed_symbols: raise ValueError( "Symbol must be one of {}".format(allowed_symbols) )
# Deprecated comma_format = label_comma custom_format = label_custom currency_format = label_currency label_dollar = label_dollar percent_format = label_percent scientific_format = label_scientific date_format = label_date number_format = label_number log_format = label_log timedelta_format = label_timedelta pvalue_format = label_pvalue ordinal_format = label_ordinal number_bytes_format = label_bytes