========================
Number formatting
========================

.. include:: ../../complete.rst

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

.. code-block:: python

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

.. list-table:: Prefix and suffix examples
   :header-rows: 1

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

.. code-block:: python

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

.. list-table::
   :header-rows: 1

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

.. list-table::
   :header-rows: 1

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

.. list-table::
   :header-rows: 1

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

.. list-table::
   :header-rows: 1

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

.. list-table::
  :header-rows: 1

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

.. list-table:: 
  :header-rows: 1

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

.. list-table:: 
  :header-rows: 1

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


Positive, negative, zero and null formats
------------------------------------------

.. list-table:: 
  :header-rows: 1

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

.. list-table::
  :header-rows: 1

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

.. list-table::
  :header-rows: 1

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

.. list-table::
  :header-rows: 1

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