Number formatting

Note

This help should be accurate and comprehensive. If you see anything missing or that needs to be fixed, see How to Contribute or let us know in the Juice Slack #documentation channel.

You can define a format for Metrics and Dimensions that define how numbers are displayed. Juicebox’s number formatting is an extension of D3 Formats (https://github.com/d3/d3-format/blob/master/README.md#format). Juicebox’s extensions support prefixes and suffixes, separate positive, negative, and zero formatting, ordinal formatting, and better formatting for business numbers.

Format options

Number formats in juicebox have the following parts

"<prefix>"<positive_format>;<negative_format>;<zero_format>;<null_format>"<suffix>"

Every part of the number format is optional except for the positive_format . If only the positive_format is given, it will be used for all numbers.

prefix and suffix

Prefix can be any text that appears before the number, while suffix will appear after the number. They must be between double quotes. Prefix and suffix support a special command pluralize(singular, plural) which choses between two strings. If the number being formatted is one, the singular value will be displayed, otherwise the plural value will be displayed.

Prefix and suffix examples

Format	Number	Result
"Total sales: ".0f	1234	Total sales: 1234
,.0f" days until Christmas"	1234	1,234 days until Christmas
,.0f"pluralize( student, students)"	4	4 students
,.0f"pluralize( student, students)"	1	1 student

formats

This format documentation is adapted from https://github.com/d3/d3-format/blob/master/README.md#format

Formats have the following parts

[[fill]align][sign][symbol][0][width][,][.precision][type]

You can optionally provide extra formats for negative, zero, or null values. The positive_format will be used when other formats aren’t provided.

[fill[align]]

The fill can be any character. The presence of a fill character is signaled by the align character following it, which must be one of the following:

Align character	Description
>	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]

The sign can be:

Sign character	Description
-	nothing for positive and a minus sign for negative. (Default behavior.)
+	a plus sign for positive and a minus sign for negative.
(	nothing for positive and parentheses for negative.
SPACE	a space for positive and a minus sign for negative.

[symbol]

The symbol can be

Symbol character	Description
$	apply currency symbols per the locale definition.
#	for binary, octal, or hexadecimal notation, prefix by 0b, 0o, or 0x, respectively.

[0]

The zero (0) option enables zero-padding; this implicitly sets fill to 0 and align to =. The width defines the minimum field width; if not specified, then the width will be determined by the content. The comma (,) option enables the use of a group separator, such as a comma for thousands.

[width] and [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). See precisionFixed and precisionRound for help picking an appropriate precision.

The available type values are:

Format	Description
f	fixed point notation.
s	decimal notation with an SI prefix, rounded to significant digits. Note Juicebox changes numbers lower than 1 to be formatted with equivalent f notation.
%	multiply by 100, and then decimal notation with a percent sign.
ordinal	Display as an ordinal number (like 1st, 2nd, 3rd)
e	exponent notation.
g	either decimal or exponent notation, rounded to significant digits.
r	decimal notation, rounded to significant digits.
p	multiply by 100, round to significant digits, 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	converts the integer to the corresponding unicode character before printing.
(none)	like g, but trim insignificant trailing zeros.

Examples

This format will show a certain number of digits. If the number is in the thousands, it wil be

s, f, $, and % formats

• .Ns formats display numbers with N digits of precisions. This is a good way to display numbers that differ greatly in size.
• .Nf displays numbers with a N digits after the decimal place.
• Starting your format with a comma will put commas between 000s.

Format	Number	Result
.1s	0.9241	0.9
.1s	0.9123	0.9
.1s	0	0.0
.1s	0.00000000001	0.0
.2s	0.9123	0.91
.2s	-0.9123	-0.91
.2s	0	0.00
.2s	0.00000000001	0.00
.1s	0.9123	0.9
.1s	0	0.0
.1s	0.00000000001	0.0
.2s	0	0.00
.1s	0.1234567	0.1
.1s	1.234567	1
.1s	12.34567	10
.1s	123.4567	100
.1s	1234.567	1K
.1s	12345.67	10K
.1s	123456.7	100K
.1s	1234567	1M
.1s	12345678	10M
$.1s	12345678	$10M
.1s	123456789	100M
.1s	1234567891	1B
.1s	12345678912	10B
.3s	0.1234567	0.123
.3s	1.234567	1.23
$.3s	1.234567	$1.23
.3s	12.34567	12.3
.3s	123.4567	123
.3s	1234.567	1.23K
.3s	12345.67	12.3K
$.3s	12345.67	$12.3K
.3s	123456.7	123K
.3s	1234567	1.23M
.3s	12345678	12.3M
.3s	123456789	123M
.3s	1234567891	1.23B
.3s	12345678912	12.3B
.1s	0.9	0.9
.1s	-0.9	-0.9
.1s	0	0.0
.1s	100	100
.1s	1100	1K
.1s	10000	10K
,.3s	0.000123	0.000
,.3s	0.001234	0.001
,.2s	0.012345	0.01
,.4s	0.12345	0.1235
,.3s	1.2345	1.23
,.3s	123	123
,.2s	12345.56	12K
,.2s	1234567	1.2M
,.2s	1234567890	1.2B
,.2s	123456789012	120B
,.2s	1234567890123	1.2T
.2f	1203	1203.00
.2f	-1203	-1203.00
,.2f	-1203	-1,203.00 Note Note the commas between the 000s caused by the starting ‘,’
.2f	null	0.00
.2f	NaN	NaN
.1%	.12345	12.3%
.2%	.12345	12.34%
.2%	123.45	12345.00%
,.2%	123.45	12,345.00%

Prefixes and suffixes

• Use double quotes to add prefixes or suffixes to your format.

Format	Number	Result
.2f	1203	1203.00
"sales: ".2f	1203	sales: 1203.00
.2f" cows"	1203	1203.00 cows
"sales: ".2f" cows"	1203	sales: 1203.00 cows
"moo"	1203	moo Note A double quoted prefix with no specifier will just show the prefix.
"moo"	-1203	moo
"moo"	0	moo
"moo"	null	moo
.2f"pluralize( cow, cows)"	0	0.00 cows
.2f"pluralize( cow, cows)"	1	1.00 cow
.2f"pluralize( cow, cows)"	2	2.00 cows
"pluralize(There is ,There are )".2f"pluralize( cow, cows)"	0	There are 0.00 cows
"pluralize(There is ,There are )".2f"pluralize( cow, cows)"	1	There is 1.00 cow
"pluralize(There is ,There are )".2f"pluralize( cow, cows)"	2	There are 2.00 cows

Missing formats

• If the format is missing the raw number or value will be displayed.

Format	Number	Result
(nothing)	1203	1203
(nothing)	-1203	-1203
(nothing)	0	0
(nothing)	null	null
(nothing)	abcd	abcd

Positive, negative, zero and null formats

Format	Number	Result
.2s;.3s	1234	1.2K
.2s;.3s	-1234	-1.23K
.2s;.3s;.4s	0	0.0000
,.0f" days from now";|,.0f|" days ago";"today";"--unknown--"	1234	1,234 days from now
,.0f" days from now";|,.0f|" days ago";"today";"--unknown--"	-1234	1,234 days ago
,.0f" days from now";|,.0f|" days ago";"today";"--unknown--"	0	today
,.0f" days from now";|,.0f|" days ago";"today";"--unknown--"	null	–unknown–

Absolute values

Format	Number	Result
\|.2s\|	1234	1.2K
\|.2s\|	-1234	1.2K
.2s;"negative "\|.3s\|	-1234	negative 1.23K Note Negative formats can have their own prefixes.
.2s;\|.3s\|	1234	1.2K

Dates and times

• Dates and times are formatted using http://strftime.org/ options.

Format	Number	Result
<%Y-%m-%d>	dt	2014-01-01
<%Y/%m/%d>	dt	2014/01/01
<%Y-%m-%d>	dt	2014-01-01
<%Y/%m/%d>	dt	2014/01/01
<%Y-%m-%d>;;;"NODATA"	null	NODATA
<%Y/%m/%d>;;;"NODATA"	null	NODATA
"prefix"<%Y-%m-%d>	dt	prefix2014-01-01
"The "<%Y-%m-%d>" Conundrum"	dt	The 2014-01-01 Conundrum
<%Y-%m-%d>"suffix"	dt	2014-01-01suffix

Ordinal values

Format	Number	Result
ordinal	1	1st
ordinal	2	2nd
ordinal	3	3rd
ordinal	4	4th
ordinal	5	5th
ordinal	6	6th
ordinal	7	7th
ordinal	8	8th
ordinal	9	9th
ordinal	10	10th
ordinal	11	11th
ordinal	12	12th
ordinal	21	21st
ordinal	22	22nd
ordinal	23	23rd
ordinal	24	24th
ordinal	100	100th
ordinal	101	101st