units

units(value, numeric=None, dest=None, *, fontsize=None, figure=None, axes=None, width=None)[source]

Convert values between arbitrary physical units. This is used internally all over ultraplot, permitting flexible units for various keyword arguments.

Parameters:

  • value (float or str or sequence) – A size specifier or sequence of size specifiers. If numeric, units are converted from numeric to dest. If string, units are converted to dest according to the string specifier. The string should look like '123.456unit', where the number is the magnitude and 'unit' matches a key in the below table.

    Key

    Description

    'm'

    Meters

    'dm'

    Decimeters

    'cm'

    Centimeters

    'mm'

    Millimeters

    'yd'

    Yards

    'ft'

    Feet

    'in'

    Inches

    'pc'

    Pica (1/6 inches)

    'pt'

    Points (1/72 inches)

    'px'

    Pixels on screen, using dpi of rc['figure.dpi']

    'pp'

    Pixels once printed, using dpi of rc['savefig.dpi']

    'em'

    Em square for rc['font.size']

    'en'

    En square for rc['font.size']

    'Em'

    Em square for rc['axes.titlesize']

    'En'

    En square for rc['axes.titlesize']

    'ax'

    Axes-relative units (not always available)

    'fig'

    Figure-relative units (not always available)

    'ly'

    Light years ;)

  • numeric (str, default: 'in') – The units associated with numeric input.

  • dest (str, default: numeric) – The destination units.

  • fontsize (str or float, default: rc['font.size'] = 9.0 or rc['axes.titlesize'] = 'med-large') – The font size in points used for scaling. Default is rc['font.size'] for em and en units and rc['axes.titlesize'] for Em and En units.

  • axes (Axes, optional) – The axes to use for scaling units that look like '0.1ax'.

  • figure (Figure, optional) – The figure to use for scaling units that look like '0.1fig'. If not provided we try to get the figure from axes.figure.

  • width (bool, optional) – Whether to use the width or height for the axes and figure relative coordinates.