データの種類に応じて、カンマや単位を付与したり、数値を丸めたいケースがある。D3.jsには、こうした数値の整形に使う関数を返す2つのメソッドが用意されている。

d3.format(specifier)メソッドとd3.formatPrefix(specifier,value)メソッドの2つだ。

いきなりややこしいが、これら2つのメソッドはlocaleオブジェクトが保持する同名メソッドのエイリアスである。D3.jsでの数値のフォーマットを理解するには、まずロケールを理解する必要がある。

ロケール

数値のフォーマット（整形）は、ロケールに基づいて行われる。ロケールとは、地域ごとの数値の表現形式である。例えば通貨や小数点、3桁区切りにどの記号を使うか、というようなものだ。

D3.jsでは、以下のようなプロパティを持つオブジェクトによって、ロケールの設定を行う。

js
const difinition = {
  decimal: ".", // 小数点記号。
  thousands: ",", // 桁区切りに使う記号。
  grouping: [3], // 桁区切りに使う単位。
  currency: ["$", ""], // 通過記号の接頭辞と接尾辞
  //numerals: undefined,//オプション。"0"から"9"までを置き換える文字列の配列。
  //percent:"%", //オプション。%記号。
  //minus:"-", //オプション。マイナス記号。
  //nan: "NaN"//オプション。非数(Not-a-number)。
};

各値はデフォルト値である(numeralsのみ、デフォルト値がない)。

ロケールの設定

ロケールの設定は、以下の2つのいずれかを用いて行う。

メソッド名 概要
formatLocale(definition) 定義に基づいてlocaleオブジェクトを返す。
formatDefaultLocale(definition) 定義に基づいてlocaleオブジェクトを返す。D3.jsのデフォルトの整形用メソッドを新しいロケールに置き換える。

D3.jsのデフォルトの整形メソッドとは、先に触れたd3.format(specifier)メソッドとd3.formatPrefix(specifier,value)メソッドの2つである。デフォルトのロケール（US）で事足りる場合は、別途ロケールを作ることなくd3オブジェクトからこれらのメソッドを呼び出せる。

formatDefaultLocale(definition)メソッドは、デフォルトの設定を任意に設定したロケールで上書きする。

フォーマット指定子

冒頭に巻き戻ったようだが、D3.jsでは以下の2つのメソッドを使って、数値整形用の関数を作る。

メソッド名 概要
d3.format(specifier) 渡されたフォーマット指定子(specifier)に基づいて、数値をフォーマットする関数を返す。
d3.formatPrefix(specifier,value) 渡されたフォーマット指定子に基づいて、数値フォーマットし、適切なSI接頭辞を付与する関数を返す。valueの扱いが謎かもしれない。valueに渡された値を基準にSI接頭辞を定め、それが整形用関数で使われる。SI接頭辞とは、m(ミリ)とかk(キロ)とかM(メガ)とかである。

D3.jsのフォーマット指定子(specifier)は、Python3の書式指定ミニ言語仕様（の数値データを対象とする仕様）を参考にしつつ、以下のように定義されている。

const difinition = {
  decimal: ".", // 小数点記号。
  thousands: ",", // 桁区切りに使う記号。
  grouping: [3], // 桁区切りに使う単位。
  currency: ["$", ""], // 通過記号の接頭辞と接尾辞
  //numerals: undefined,//オプション。"0"から"9"までを置き換える文字列の配列。
  //percent:"%", //オプション。%記号。
  //minus:"-", //オプション。マイナス記号。
  //nan: "NaN"//オプション。非数(Not-a-number)。
};

整形オプション

fillは、余白を埋める任意の1文字、alignは、整形オプションである。値は以下のいずれかとなる。

整形オプションの種類 概要
>桁数 右詰め。デフォルト値。
<桁数 左詰め。
^桁数 中央寄せ。
=桁数 右詰めと似ているが、符号を埋めた余白の左側に置く

桁数には、符号と数値も含まれる。以下、サンプルである。

js
d3.format("タ>5")(-7); //"タタタ-7"
d3.format("ス<5")(-7); //"-7ススス"
d3.format("ケ^5")(-7); //"ケ-7ケケ"
d3.format("テ=5")(-7); //"-テテテ7"

符号オプション

signは、符号をどう表示するかを指定するオプションである。以下のいずれかの値を指定できる。

符号オプションの種類 概要
+ 正負両方とも符号をつける。
- 負の場合のみ符号をつける。
( 負の場合のみ、符号なしで丸括弧で囲う。
（半角スペース） 正の場合は空白、負の場合は負号をつける。

マイナスの数値を符号なしで丸括弧で囲うのは、海外の会計の分野でよく見られる慣習だそうである。

js
console.log(d3.format("+")(7)); //"+7"
console.log(d3.format("-")(-7)); //"-7"
console.log(d3.format("(")(-7)); //"(7)"
console.log(d3.format(" ")(7)); //" 7"

記号オプション

記号オプションの種類 概要
$ ロケール設定に応じた通過記号を数値につける。
# #bで2進数、#oで8進数、#xで16進数のプレフィクスをそれぞれ数値につける。

D3.jsでは、数値はd3.formatLocale()メソッド、日付はd3.timeForatLocale()メソッドを通してロケールの設定を行う。これらのメソッドについては後述する。

js
const locale = d3.formatLocale({ currency: ["¥", ""] });
console.log(locale.format("$")(15)); //"¥15"
console.log(d3.format("#b")(15)); //"0b1111"
console.log(d3.format("#o")(15)); //"0o17"
console.log(d3.format("#x")(15)); // "0xf"

ゼロ埋めオプションとカンマ区切りオプション

オプションの種類 概要
0桁数 ゼロ埋めする。
, 3桁ごとにカンマで区切る。
js
console.log(d3.format("05")(1000)); //"01000"
console.log(d3.format(",")(1000)); //"1,000"

桁数オプションと表示形式オプション

オプションの種類 概要
.桁数 小数点以下の最大桁数を指定する。省略すると6。
f 固定小数点形式で返す。
% 100倍し、後ろに%をつけて返す。

上のテーブルでは1つにまとめてしまったが、桁数オプションの後に表示形式オプションを続ける。例えば小数点以下の桁数が2の場合、以下のようにする。

js
console.log(d3.format(".2f")(3.1421356)); //"3.14"
console.log(d3.format(".2%")(1)); //"100.00%"

また、以下の表示形式オプションでは、.桁数の指定が有効桁数となる。

有効桁数(=significant digits)とは、ゼロ以外の最初に表れる数値から何桁目までを有効とするか、という概念である。例えば有効桁数が1のとき、1987という値は2000に丸められる。また、同様に0.01987という値は0.02となる。

その数値の意味を左右する、最も重要な桁数を示すのが有効桁数と言える。

オプションの種類 概要
.桁数 有効桁数を指定する。省略すると6。
e 指数形式で返す。
r 有効桁数までを四捨五入して返す
g 有効桁数におさまる数値は固定小数点形式、おさまらない数値は指数形式で返す。
s 有効桁数までを四捨五入して、SI接頭辞（kとかMとか）をつけて返す。
p 100倍し、有効桁数に丸め、%記号付きの10進数で返す。
js
console.log(d3.format(".1e")(1)); //"1.0e+0"
console.log(d3.format(".1g")(9)); //"9"
console.log(d3.format(".1g")(10)); //"1e+1"
console.log(d3.format(".1r")(0.99)); //"1"
console.log(d3.format(".1s")(1000)); //"1k"
console.log(d3.format(".1p")(0.99)); //"100%"

2,8,10,16進数のそれぞれに変換するよう指定もできる。

オプションの種類 概要
b 2進数形式で整数に丸めて返す。
o 8進数形式で整数に丸めて返す。
d 10進数形式で整数に丸めて返す。
x 小文字の16進数形式で整数に丸めて返す。
X 大文字の16進数形式で整数に丸めて返す。
c 数値を文字列に変換して返す。
js
console.log(d3.format("b")(2)); //"10"
console.log(d3.format("o")(8)); //"10"
console.log(d3.format("d")(0.5)); //"1"
console.log(d3.format("x")(15)); //"f"
console.log(d3.format("X")(15)); //"F"
console.log(typeof d3.format("c")(1)); // "string"

すべての表示形式オプションには、末尾の不要なゼロをトリミングする~オプションも用意されている。

js
console.log(d3.format(".2r")(1.0)); //"1.0"
console.log(d3.format(".2~r")(1.0)); //"1"
console.log(d3.format(".2%")(1)); //"100.00%"
console.log(d3.format(".2~%")(1)); //"100%"
console.log(d3.format(".2e")(1.0)); //"1.00e+0"
console.log(d3.format(".2~e")(1.0)); //"1e+0"

ショートハンド

オプションの種類 概要
(半角スペース) ~gのショートハンド。デフォルトの有効桁数は6ではなく12となる
n ,gのショートハンド。
js
console.log(d3.format(" ")(1000000.0));
console.log(d3.format("n")(10000));

このほか、値から妥当な精度を算出するお役立ちメソッドも用意されている。が、まだよく理解できない上に脳みそがパンクしそうなのでおいおいまとめたいと思う。

参考資料