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.

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`

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.

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` |

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.

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. |

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. |

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. |

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.

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 |

`%` |
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. |

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

`.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% |

- 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 |

- 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 |

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– |

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 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 |

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 |