How to Format Numbers, Dates, and Time Using D3 HTMLWidgets in R
If you have ever spent any time investigating where the cool kids play in the data visualization world you will know it is all about D3. For most of us, D3 is a bit too hard to use directly. It is a JavaScript library, which means that to use it you need to be a half-decent programmer.
Fortunately, we get to use it in all the cool htmlwidgets that have been built for R, such as plotly. However, a practical challenge when using these htmlwidgets is that they require you to know enough D3 in order to provide formatting instructions for numbers, dates, and times. This post provides a cheat sheet explaining how to do this.
Formatting Numbers
The general structure of a D3 number format is [,][.precision][type]. The square brackets are not part of the format but signify 3 distinct parts:
- The first character is an optional comma. This determines whether to separate groups of 3 digits (before the decimal place) by commas.
- Second, there is a dot followed by an integer (which I labeled as "precision" in the above). The integer usually sets the number of decimal places. There are exceptions, where the integer sets the number of significant digits.
- The final part is a single character code, with meanings and examples as described in the table below.
| Type | Description | Example: 1/17 with precision = 3 | Example: 123456789 with precision = 1 and comma separation |
|---|---|---|---|
| f | Fixed number of decimal places | 0.059 | 123,456,789.0 |
| % | Multiplied by 100 with % symbol and fixed number of decimal places | 5.882% | 12,345,678,900.0% |
| e | Scientific (exponential) notation. A coefficient with a fixed number of decimal places, multiplied by a power of 10. | 5.882e-2 | 1.2e+8 |
| s | Metric (SI) units suffix with a fixed number of significant digits. | 58.8m | 100M |
There is a lot more to D3 number formats than I have just shown. If you want to know more about alignment, handling negative signs and bases then click here.
Formatting Dates and Times
"May 15 2017 3pm" could also be written as "15/5/17 15:00". Many people and organizations have their own conventions for dates. It is frustrating not to be able to show a date in the format you want, which is where D3's flexibility comes in.
The general structure of a date or time format is a sequence of directives, each of which is a letter preceded by the percentage sign. Each directive specifies a unit of time. For example, "%Y %b %d" means 4 digit year followed by 3 letter month followed by 2 digit day, such as "2016 Dec 25". A list of useful directives is shown below:
%a- abbreviated weekday name%A- full weekday name%b- abbreviated month name%B- full month name%d- zero-padded day of the month as a decimal number [01,31]%H- hour (24-hour clock) as a decimal number [00,23]%I- hour (12-hour clock) as a decimal number [01,12]%m- month as a decimal number [01,12]%M- minute as a decimal number [00,59]%p- either AM or PM%S- second as a decimal number [00,59]%y- year without century as a decimal number [00,99]%Y- year with century as a decimal number
A more complex example would be "%m/%d/%y %I:%M %p", which produces output such as "02/28/17 03:35 PM". Note that here I have used the colon and forward slash as separators. In the previous example, the separator was the space.
As with numbers, a lot more options are available for dates and times which are listed here.
Conclusion
D3 is a powerful and concise way to specify the format that you want. You can use D3 within the R charting packages plotly and flipChart.
