このページでは、グラフのデータ表でのロールのコンセプトと使用方法について説明します。
ロールとは
Google DataTable オブジェクトと DataView オブジェクトで、明示的に割り当てられた列ロールがサポートされるようになりました。列のロールは、その列内のデータの目的を記述します。たとえば、列にはツールチップ テキスト、データポイント アノテーション、不確実性インジケーターを説明するデータを保持できます。ほとんどの列のロールは、直前のデータ列にあるか、連続するロール列のグループの先頭にあるかに関係なく、先行する「データ」列に適用されます。たとえば、「データ」列の後に「ツールチップ」と「アノテーション」の 2 つの列を配置できます。ただし、「domain」列以降では、通常は「annotation」列と「annotationText」列のロールも許可しています。
注: ユーザーがグラフにカーソルを合わせたときに表示されるツールチップの内容を制御する場合は、ツールチップをご覧ください。
元々、1 つの列で使用できるロールは、主軸の値を指定する「domain」と、棒の高さや円グラフの幅を指定する「data」の 2 つのみでした。これらのロールは、テーブル内の列の順序とタイプに基づいて暗黙的に割り当てられました。ただし、列のロールを明示的に割り当てることにより、任意のアノテーション ラベル、ホバーテキスト、不確実性バーなど、興味深い新機能を提供するオプションの列をグラフに追加できるようになりました。
列のロールを明示的に割り当てていない場合、そのロールは、グラフのデータ形式の仕様に従って、テーブル内の列の順序によって推定されます。このページでは、明示的に割り当てることのできるロールとその割り当て方法について説明します。
ここでは、デフォルトの推定ロールのみを使用した場合と、明示的に割り当てられている追加のロールを使用した場合の折れ線グラフでできることを比較します。
折れ線グラフのデータ表の形式:
| 列 0 | 列 1 | ... | 列 N | |
|---|---|---|---|---|
| 目的 | 行 1 の値 | ... | 行 N の値 | |
| データの種類 |
|
数値 | ... | 数値 |
| ロール | ドメイン | データ | ... | データ |
| サポートされる 列のロール（オプション） |
|
|
... |
|
| 明示的な列の役割のないグラフ | 明示的な列ロールのグラフ |
|---|---|
|
|
|
このグラフではロールが明示的に適用されていないため、上記の基本データとドメイン列のレイアウトのみを使用できます。 データテーブル: var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addRows([
['April',1000],
['May', 1170],
['June', 660],
['July', 1030]
]); |
このグラフではロールを明示的に割り当てているため、オプションの列を追加できます。このグラフには、annotation、annotationText、間隔、確実性ロールのオプションの列があります。
データテーブル: var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain label col.
data.addColumn('number', 'Sales'); // Implicit series 1 data col.
data.addColumn({type:'number', role:'interval'}); // interval role col.
data.addColumn({type:'number', role:'interval'}); // interval role col.
data.addColumn({type:'string', role:'annotation'}); // annotation role col.
data.addColumn({type:'string', role:'annotationText'}); // annotationText col.
data.addColumn({type:'boolean',role:'certainty'}); // certainty col.
data.addRows([
['April',1000, 900, 1100, 'A','Stolen data', true],
['May', 1170, 1000, 1200, 'B','Coffee spill', true],
['June', 660, 550, 800, 'C','Wumpus attack', true],
['July', 1030, null, null, null, null, false]
]); |
使用可能なロール
次の表に、Google Charts でサポートされているすべてのロールを示します。すべてのロールがすべてのグラフタイプでサポートされているわけではありません。各グラフのドキュメントでは、使用可能なロールと使用できる場所について説明します。ロールは、グラフの種類によってレンダリング方法が異なります。
| ロール | 説明 | 例 |
|---|---|---|
| アノテーション | グラフの関連するデータポイントの近くに表示するテキスト。テキストはユーザーの操作なしで表示されます。アノテーションとアノテーション テキストは、データポイントとカテゴリ（軸ラベル）の両方に割り当てることができます。 アノテーションには 2 つのスタイルがあります。point（デフォルト）は、指定したポイントの近くにアノテーション テキストを描画します。line は、グラフ領域を 2 等分する線上にアノテーション テキストを描画します。グラフ オプション データ型: string デフォルト: 空の文字列 |
データ: label: 'Year', 'Sales', null, null, 'Expenses', null, null
role: domain、data, annotation, annotationText, data, annotation, annotationText
'2004', 1000, null, null, 400, null, null
'2005', 1170, null, null'A '2005', 1170, null, null, 4
このグラフの「A」と「B」は注釈です。アノテーションにカーソルを合わせると、アノテーション テキストが表示されます。annotationText 値を表示するには、アノテーションが適用されているデータポイントではなく、アノテーションにカーソルを合わせる必要があります。 annotationText セルと annotationText セルの両方に null 値も使用できますが、annotationText 値がある場合は関連付けられたアノテーション値が必要です。 |
| annotationText | ユーザーが関連するアノテーションにカーソルを合わせたときに表示される拡張テキスト。アノテーションとアノテーション テキストは、データポイントとカテゴリ（軸ラベル）の両方に割り当てることができます。annotationText 列がある場合は、アノテーション列も必要です。一方、ツールチップ テキストは、グラフ上の関連するデータポイントにカーソルを合わせると表示されます。 データ型: string デフォルト: 空の文字列 |
|
| 確実性 | データポイントが確定しているかどうかを表します。どのように表示されるかはグラフの種類によって異なります。たとえば、破線やストライプの塗りつぶしで示される場合があります。 折れ線グラフと面グラフでは、2 つのデータポイント間のセグメントは、両方のデータポイントが確定している場合にのみ確定します。 データ型: boolean。true は確定、false は不確定。 デフォルト: true |
|
| 強調 | 指定したグラフのデータポイントを強調表示します。太い線や大きなポイントとして表示されます。 折れ線グラフと面グラフでは、2 つのデータポイント間のセグメントは、両方のデータポイントが強調表示されている場合にのみ強調表示されます。 データ型: boolean デフォルト: false |
データ: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, emphasis, data, emphasis
'2004', 1000, true, 400, false
'2005', 1170, true, 460, true
'2006', 660, false, 1120, true
'2007', 1030, false, 540, true
このグラフの「販売」系列には 1 つの強調セグメントがあり、列 3、行 1、行 2 で指定されています。「経費」系列には、5 列目の行 2、3、4 が強調表示されている 2 つのセグメントがあります。強調するには、両方の境界ポイントを強調する必要があることに注意してください。 |
| 間隔 | 特定のポイントの潜在的なデータ範囲を示します。区間は通常、I バースタイルの範囲インジケーターとして表示されます。区間の列は数値列です。区間の列をペアで追加して、バーの下限値と上限値をマークします。区間の値は、左から右に値を増加させていく必要があります。 データ型: number デフォルト: 間隔なし |
データ: label: 'Day', 'Stock value', null, null
role: domain, data, interval, interval
'Mon', 38, 20, 45
'Tue', 55, 31, 66
'Wed', 77, 50, 80
'Thurs', 66, 50, 77
このグラフでは、区間の値により各点を囲む I バーが定義されます。値は左から右に増加します。ある点を中心とする最大区間と最低区間は、棒の上部と下部を表します。 注: 間隔の詳細については、間隔をご覧ください。 |
| スコープ | 拡張ポイントが対象範囲内か範囲外かを示します。ポイントが範囲外の場合、強調表示は解除されます。 折れ線グラフと面グラフでは、いずれかのエンドポイントが対象であれば、2 つのデータポイント間のセグメントも対象になります。 データ型: ブール値。true はスコープ内にあることを意味します。 デフォルト: true |
データ: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, scope, data, scope
'2004', 1000, false, 400, true
'2005', 1170, false, 460, false
'2006', 660, true, 1120, false
'2007', 1030, true, 540, false
最初のスコープ列は、その左側の「販売」データ列に適用されます。最初のセグメントは、両方の境界ポイントが対象範囲外であるため、対象範囲外となります。範囲の 2 つ目の列は、その左側の [費用] データ列に適用されます。最初のセグメントは、境界ポイントの 1 つが対象範囲外であるため、対象範囲内としてマークされています。残りの線は、他のすべてのポイントが対象範囲外としてマークされているため、対象範囲外となっています。 |
| スタイル |
データのさまざまな側面の特定のプロパティのスタイルを設定します。これらの値は次のとおりです。
データ型: 文字列。 デフォルト: null |
データ:
label: 'Character', 'Popularity', 'Style',
role: domain, data, style,
'Hulk', 50, 'color: green',
'Captain America', 75, 'color: #0000cf;' +
'stroke-color: #cf001d',
'Wolverine', 90, 'opacity: 0.5;' +
'stroke-width: 5;' +
'stroke-color: #01a0ff;' +
'fill-color: #fff600',
'Iron Man', 60, 'color: #db9500;' +
'stroke-width: 10;' +
'stroke-color: #a30300',
'Spider Man', 100, 'bar {' +
'fill-color: #c8001d;' +
'stroke-width: 3;' +
'stroke-color: #1800c8}'
このグラフでは、 注: 詳細については、ポイント、線、棒のスタイルをカスタマイズする方法に関する別の記事で説明しています。グラフの種類ごとに、他の種類のエンティティ（面、テキスト、ボックスなど）にスタイルを指定することもできます。それぞれのオプションもご覧ください。 |
| ツールチップ |
ユーザーがこの行に関連付けられたデータポイントにカーソルを合わせたときに表示されるテキスト。 注: これは、バブルチャートの可視化ではサポートされていません。バブルチャートの HTML ツールチップのコンテンツはカスタマイズできません。 データ型: string デフォルト: データポイント値 |
データ: label: 'Year', 'Sales', null, 'Expenses', null
role: domain, data, tooltip, data, tooltip
'2004', 1000, '1M$ sales, 400, '$0.4M expenses
in 2004' in 2004'
'2005', 1170, '1.17M$ sales, 460, '$0.46M expenses
in 2005' in 2005'
'2006', 660, '.66$ sales, 1120, '$1.12M expenses
in 2006' in 2006'
'2007', 1030, '1.03M$ sales, 540, '$0.54M expenses
in 2007' in 2007'
データポイントにカーソルを合わせると、ツールチップ テキストが表示されます。ツールチップ データは、両方の行（列 3 と 5）のすべてのポイントに割り当てられます。 注: ツールチップのカスタマイズについて詳しくは、ツールチップをご覧ください。 |
| ドメイン | マルチドメイン グラフ（以下を参照）を設計しない限り、このロールを明示的に割り当てる必要はありません。データテーブルの基本形式により、どの列がドメイン列であるかをチャート エンジンが推測できます。ただし、どの列がドメイン列であるかを認識し、他のどの列が変更できるかを把握する必要があります。 ドメイン列では、グラフの主軸に沿ってラベルを指定します。同じグラフ内で複数のスケールをサポートするために、複数のドメイン列を使用できる場合があります。 データ型: 通常は文字列（数値や日付の場合もあります） |
データ:
label: '2009, '2009, '2009, '2008, '2008 '2008
Quarter', Sales', Expenses', Quarter', Sales', Expenses'
role: domain, data, data, domain, data, data
'Q1/09', 1000, 400, 'Q1/08', 800, 300
'Q2/09', 1170, 460, 'Q2/08', 750, 400
'Q3/09', 660, 1120, 'Q3/08', 700, 540
'Q4/09', 1030, 540, 'Q4/08', 820, 620
この例では、マルチドメイン グラフを示しています。最初の 2 つのデータ列で最初のドメイン（「2009 Quarter」）が、最後の 2 つのデータ列で 2 番目のドメイン（「2008 Quarter」）が変更されます。両方のドメインが同じ軸スケールに重ねて表示されている。 |
| データ | このロールを明示的に割り当てる必要はありません。データテーブルの基本形式により、どの列がドメイン列であるかをチャート エンジンが推測できます。ただし、どの列がデータ列を変更できるかを把握するために、どの列がデータ列であるかを認識しておく必要があります。 データロールの列には、グラフに表示する系列データを指定します。ほとんどのグラフでは、1 つの列は 1 つの系列になりますが、これはグラフの種類によって異なります（たとえば、散布図の場合、最初の系列用に 2 つのデータ列が必要で、その他の系列ごとに 1 つのデータ列が必要です。ローソク足チャートでは、系列ごとに 4 つのデータ列が必要です）。 データ型: number |
ロールの階層と関連付け
次の図は、どのロール列がどのロール列に適用できるかを示しています。ドメイン列を除くすべての列は、適用可能な最近傍の左ネイバーに適用されます。
たとえば、scope 列は、その左側にある最も近い data 列に適用されます。annotationText 列は、その左側にある最も近い annotation 列に適用されます。annotation は、その左に最も近い data 列または domain 列に適用されます。
ロールの割り当て
ロールは、DataTable オブジェクトの列のプロパティとして割り当てられます。ロール列を作成するにはいくつかの方法がありますが、最も一般的なものは次のとおりです。
最初の 2 つの手法では、次のチャートのようになります。
DataTable.addColumn メソッド
次の例では、3 つの棒に区間マーカーを配置した棒グラフを作成します。区間マーカーは、DataTable.addColumn() メソッドを使用して 3 列目と 4 列目に指定します。
var data = new google.visualization.DataTable();
data.addColumn('string', 'Month'); // Implicit domain column.
data.addColumn('number', 'Sales'); // Implicit data column.
data.addColumn({type:'number', role:'interval'});
data.addColumn({type:'number', role:'interval'});
data.addColumn('number', 'Expenses');
data.addRows([
['April',1000, 900, 1100, 400],
['May', 1170, 1000, 1200, 460],
['June', 660, 550, 800, 1120],
['July', 1030, , , 540]
]);
var chart = new google.visualization.BarChart(
document.getElementById('visualization'));
chart.draw(data,
{width: 800, height: 600, title: 'Company Performance'});
JavaScript のリテラル表記
JSON リテラルでは、値が "role":"role-type" の列の p プロパティを指定する必要があります。次の例は、JavaScript のリテラル表記を使用してロールを指定する方法を示しています。これはテーブルの作成時にのみ行うことができます。
{"cols":[
{"id":"","label":"Month","pattern":"","type":"string"},
{"id":"","label":"Sales","pattern":"","type":"number"},
{"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
{"id":"","label":"","pattern":"","type":"number","p":{"role":"interval"}},
{"id":"","label":"Expenses","pattern":"","type":"number"}],
"rows":[
{"c":[
{"v":"April","f":null},
{"v":1000,"f":null},
{"v":900,"f":null},
{"v":1100,"f":null},
{"v":400,"f":null}]},
{"c":[
{"v":"May","f":null},
{"v":1170,"f":null},
{"v":1000,"f":null},
{"v":1200,"f":null},
{"v":460,"f":null}]},
{"c":[{"v":"June","f":null},
{"v":660,"f":null},
{"v":550,"f":null},
{"v":800,"f":null},
{"v":1120,"f":null}]},
{"c":[
{"v":"July","f":null},
{"v":1030,"f":null},
{"v":null,"f":null},
{"v":null,"f":null},
{"v":540,"f":null}]}],
"p":null
}
DataView.setColumns メソッド
ビューを作成するときに、列のロールを明示的に設定できます。これは、新しい計算された列を作成するときに便利です。詳しくは、DataView.setColumns() をご覧ください。