Formatting

Number Format

The numeric format strings are used to format common numeric types. The general form of a format specifier is:

• fill - can be any character, defaults to a space if omitted. The presence of a fill character is signaled by the *align* character following it, which must be one of the alignment options.

• align - the various alignment options is as follows:

  • > - forces the field to be right-aligned within the available space (default behavior);

  • < - forces the field to be left-aligned within the available space;

  • ^ - forces the field to be centered within the available space;

  • = - like >, but with any sign and symbol to the left of any padding.

• sign can be:

  • - - nothing for zero or positive and a minus sign for negative (default behavior);

  • + - a plus sign for zero or positive and a minus sign for negative;

  • (space) - a space for zero or positive and a minus sign for negative.

• symbol can be:

  • $ - apply currency symbols per the locale definition;

  • # - for binary, octal, or hexadecimal notation, prefix by 0b, 0o, or 0x, respectively.

• zero (0) option enables zero-padding; this implicitly sets fill to 0 and align to =.

• width defines the minimum field width; if not specified, then the width will be determined by the content.

• comma (,) option enables the use of a group separator, such as a comma for thousands.

• precision depending on the type, the precision either indicates the number of digits that follow the decimal point (types f and %), or the number of significant digits (types ​, e, g, r, s and p). If the precision is not specified, it defaults to 6 for all types except ​ (none), which defaults to 12. Precision is ignored for integer formats (types b, o, d, x, X and c).

• ~ trims insignificant trailing zeros across all format types.

• type determines how the data should be presented:

  • e - exponent notation;

  • f - fixed point notation;

  • g - either decimal or exponent notation, rounded to significant digits;

  • s - decimal notation followed by SI prefix symbol, rounded to significant digits;

  • % - multiply by 100, and then decimal notation with a percent sign;

  • b - binary notation, rounded to integer;

  • o - octal notation, rounded to integer;

  • d - decimal notation, rounded to integer;

  • x - hexadecimal notation, using lower-case letters, rounded to integer;

  • X - hexadecimal notation, using upper-case letters, rounded to integer;

  • c - simple toString.

  The following prefix symbols are supported for s type:

  • y - yocto, 10⁻²⁴

  • z - zepto, 10⁻²¹

  • a - atto, 10⁻¹⁸

  • f - femto, 10⁻¹⁵

  • p - pico, 10⁻¹²

  • n - nano, 10⁻⁹

  • µ - micro, 10⁻⁶

  • m - milli, 10⁻³

  • ​ (none) - 10⁰

  • k - kilo, 10³

  • M - mega, 10⁶

  • G - giga, 10⁹

  • T - tera, 10¹²

  • P - peta, 10¹⁵

  • E - exa, 10¹⁸

  • Z - zetta, 10²¹

  • Y - yotta, 10²⁴

String Template

The number format can be used in a template to create a string with variable substitution. The string template contains “replacement fields” surrounded by curly braces {}. Anything that is not contained in braces is considered literal text, which is copied unchanged to the result string. If you need to include a brace character in the literal text, it can be escaped by doubling: {}. This approach is used in functions layerTooltips() and layerLabels() to customize the content of tooltips and annotations.

See: Tooltip Customization in Lets-Plot and Annotating Charts in Lets-Plot.

Date and Time Format

Provides formats for date and time values.

The list of supported directives to format date/time values:

• %a - weekday as an abbreviated name (Sun, Mon, …, Sat);

• %A - weekday as a full name (Sunday, Monday, …, Saturday)

• %b - month as an abbreviated name (Jan, Feb, …, Dec);

• %B - month as a full name (January, February, …, December);

• %d - day of the month as a zero-padded decimal number (01, 02, …, 31);

• %e - day of the month as a decimal number (1, 2, …, 31);

• %j - day of the year as a zero-padded decimal number (001, 002, …, 366).

• %m - month as a zero-padded decimal number (01, 02, …, 12);

• %w - weekday as a decimal number, where 0 is Sunday and 6 is Saturday (0, 1, …, 6);

• %y - year without century as a zero-padded decimal number (00, 01, …, 99);

• %Y - year with century as a decimal number (0001, 0002, …, 2013, 2014, …, 9998, 9999);

• %H - hour (24-hour clock) as a zero-padded decimal number (00, 01, …, 23);

• %I - hour (12-hour clock) as a zero-padded decimal number (01, 02, …, 12);

• %l - hour (12-hour clock) as a decimal number (1, 2, …, 12);

• %M - minute as a zero-padded decimal number (00, 01, …, 59);

• %p - "AM" or "PM" according to the given time value;

• %P - like %p but in lowercase: "am" or "pm";

• %S - second as a zero-padded decimal number (00, 01, …, 59).

Scientific Notation

The exponentFormat parameter of the theme() function controls the appearance of numbers formatted with e or g types. Scientific notation can be displayed using regular e-notation or with superscript powers of 10. For g type formatting, you can also specify when scientific notation should be applied based on exponent bounds.

The value is either a string - style, or a tuple: (style, lower exp.bound, upper exp.bound). Where the style can be:

• "e" for e-notation (e.g., 1e+6);

• "pow" for superscript powers of 10 in shortened form (e.g., );

• "pow_full" for superscript powers of 10 with coefficient (e.g., ).

For g type formatting, scientific notation is applied when the number's exponent is less than or equal to the lower exp.bound (-7 by default) or greater than or equal to the upper exp.bound (6 by default, but can be affected by precision in format specifier).

The following table demonstrates the behavior with format string ",~g":

Tooltip Customization

You can format text in tooltips, see: Tooltip Customization.

Annotating Charts

You can format text in annotations, see: Annotating Charts.

Demo Notebooks

• Formatting numbers

• Formatting labels on plots

• Text geoms

• Exponent format in Lets-Plot