DSPL 生成

DSPL Gen は、CSV データテーブルをシンプルな DSPL データセットに変換するためのコマンドライン ユーティリティです。このツールは、入力ファイルを解析して、必要なすべてのデータテーブルを作成し、DSPL XML ファイルをレイアウトします。その結果、完全に近いデータセット「テンプレート」になり、アップロードと可視化を行う前にわずかな絞り込みで済みます。

DSPL Gen の基本は、入力 CSV ファイルの各行は 1 つの DSPL コンセプトに対応しており、各行はディメンションの組み合わせに対して 1 つのモニタリングであることを示しています。このツールは、列を反復処理し、列やコンセプトごとに適切なメタデータ（ID やタイプ、ディメンションか指標かなど）を確立してから、必要なコンセプト定義とスライス テーブルをすべて生成します。

DSPL Gen の実行

構文

注: 以下の説明は、DSPL ツールページに掲載されているインストール手順がすでに完了していることを前提としています。

DSPL Gen を実行するには、システムのターミナル / プロンプトで次のように入力します。

python dsplgen.py -o [output path] [path to CSV file]

角かっこで囲んだ用語は次のようになります。

  • [output path]: 出力ファイルを配置するディレクトリのパス。このディレクトリは、ファイル システム内にすでに存在している必要があります。
  • [path to CSV file]: 入力 CSV ファイルのパス。このファイルの形式について詳しくは、後述のセクションをご覧ください。

-o [output path] コンポーネントは省略可能です。省略すると、出力ファイルは現在のディレクトリに配置されます。

次に、ツールの実行、CSV ファイルの反復処理、コンセプト定義の抽出、スライス テーブルの生成が行われます。エラーが検出されない限り、XML ファイルと 1 つ以上の CSV ファイルが出力ディレクトリに書き込まれます。

最後に、任意のテキスト エディタで XML ファイルを開き、必要な変更を加えます。少なくとも、ツールによってマークされた名前、説明、その他の値を ** INSERT ... ** という表記で入力する必要があります。

簡単な例

月、国、年齢層別に分類された感染者の総数を示す CSV があるとします。わかりやすくするため、各ディメンションの値が 2 つあるとします。

date,country,age_group,disease_cases
01/2000,US,old,102030
01/2000,MX,old,192939
01/2000,US,young,23131
01/2000,MX,young,12311
02/2000,US,old,143135
02/2000,MX,old,203131
02/2000,US,young,22990
02/2000,MX,young,12591

上記の入力でツールを実行すると、次の 4 つのファイルが生成されます。

  • dataset.xml: DSPL XML テンプレート
  • country_table.csv: country コンセプトの値
  • age_group_table.csv: age_group コンセプトの値
  • slice_0_table.csv: データセット スライスのテーブル（並べ替えを除いて入力テーブルと同一）

この場合、ツールはすべての列の型と形式を正しく推測できます。あとは XML ファイルを開き、データセットのメタデータに含まれるさまざまな名前、説明、URL を編集するだけです。

入力 CSV にアノテーションを付ける

基本オプション

多くの場合、上記の例のように、DSPL Gen は列の基本メタデータ（タイプ、形式、ディメンションまたは指標）を推測できます。しかし、場合によっては他のツールが推測できず、正しく推測できない、正しく推測できても期待どおりに動作しない可能性があります。

このツールは、このようなケースに対応するために、CSV ヘッダー行で DSPL 生成オプション / ヒントの追加をサポートしています。構文は次のとおりです。

column1[option1=value1;option2=value2;...],column2[option1=value1;option2=value2;...],column3[...],...

特に、オプション リストは列名の右のかっこで囲んでいます。後続のオプション設定はセミコロンで区切ります。各オプションは、オプション名、等号、オプション値で構成されます。

DSPL Gen は現在、次の基本的なオプションをサポートしています。

オプション 説明 Default
type この列の DSPL データ型。date、float、integer、string のいずれかにする必要があります。 推定データ
format 日付列の形式。DSPL と同様、この形式は Joda DateTime 標準を使用してエンコードする必要があります。 推定データ
slice_role スライスのロールは、dimension または metric のいずれかです。 列の型が date または string の場合は dimension、そうでない場合は metric
concept この列が表す正規のコンセプト（例: geo:country）。指定すると、コンセプトがインポートされ、XML ファイルで定義が生成されません。 なし
extends この列が拡張する正規のコンセプト（例: entity:entity）。 なし
parent

この列の親コンセプト。この親は、データセット内で定義されているディメンション コンセプト（インポートされていないもの）である必要があります。指定されている場合、この情報はデータセットのコンセプト コンセプトの定義に使用されます。

それぞれの子インスタンスに設定できる親は 1 つのみです。複数の親値が検出されると、ツールによりエラーが生成されます。

 なし

価値のまとめ

上記の基本的な「ヒント」オプションに加えて、DSPL Gen はスライスのロールアップもサポートしています。このツールは、単一のテーブル入力に基づいて、ディメンションのサブセットが限定された追加のテーブルを自動的に作成できます。たとえば、入力テーブルが 3 つの時間以外のディメンション（たとえば、dimension1、dimension2、dimensions3 など）では、追加のスライスも作成できます。たとえば、dimension1 のみ、dimension2 のみ、dimension1 と dimension2 などです。

スライスを追加すると、可視化に必要となるディメンション フィルタの数が少なくなるため、データセットの探索が容易になります。一方、元のファイルには見つかっていない「新規」データが存在する場合があります。正しく使用しないとエラーが発生する可能性があります。データセットを公開する前に、統合番号を注意深く確認してください。

入力 CSV ヘッダーに追加のオプションを含めると、統合プロセスがトリガーされます。

オプション 説明 Default
aggregation この列の複数の値を組み合わせるときに使用する集計方法。AVG、COUNT、MAX、MIN、SUM のいずれかにする必要があります。これは、指標でのみ有効です。 SUM
rollup 値が true の場合、この列のコンセプトは「ロールアップ」（つまり集計）され、ディメンションのコンセプトにのみ意味があります。 False
total_val この列がロールアップされたときに保持される行を示す列の値。ディメンションのコンセプトでのみ有効です。 None

DSPL Gen は以下のアルゴリズムを使用してロールアップを計算します。

  • rollup タグの値を使用して、考えられるすべての列の組み合わせを計算します
  • 各組み合わせについて、次の操作を行います。
    • 統合列に total_val パラメータが設定されている場合は、この値で行をフィルタし、それ以外の場合はすべての行を選択します。
    • 統合列を削除する
    • 残りのディメンション列の値によって行をグループ化します。
    • aggregation パラメータで指定されたメソッドを使用して各指標を集計する
    • 結果のスライスと関連テーブルを作成する

各グループに 1 つの値しかなく、集計関数が SUM（デフォルト値）に設定されている場合、ソーステーブルと生成されたテーブルの指標値は同じになります。つまり、新しい値は生成されません。したがって、total_val パラメータを使用して、他のディメンションの組み合わせごとに「合計」行が 1 つだけになるようにすることで、事前に計算された集計データを直接ソースに格納できます。

警告: 生成されるスライスの数は、2 ロールアップ列と同じです。このオプションを多数の列に適用すると、実行時間やデータセットが非常に大きくなる可能性があります。

高度な例

前の例と同じ入力データがあり、さらに国全体の集計が含まれているとします。 

date,country,age_group,disease_cases
01/2000,US,old,102030
01/2000,MX,old,192939
01/2000,total,old,152012
01/2000,US,young,23131
01/2000,MX,young,12311
01/2000,total,young,241011
02/2000,US,old,143135
02/2000,MX,old,203131
02/2000,total,old,211310
02/2000,US,young,22990
02/2000,MX,young,12591
02/2000,total,young,240131

各年齢層の合計は、国の値の合計と一致しない場合があります。たとえば、手法の違いや、リストにない他の国が存在するためです。

ここでは、以下の追加項目を含む DSPL データセットを作成します。

  1. 国を「ロールアップ」して、年齢層のみで総感染者数を取得します。
  2. country 列で正規の geo:country コンセプトを使用して、これらの名前や場所などを自動的に取得します。
  3. disease_cases のコンセプトは quantity:amount を拡張して、（手動で）単位情報を XML ファイルに追加できるようにします

これを行うには、入力 CSV のヘッダー行を次のように変更します。

date,country[concept=geo:country;rollup=true;total_val=total],age_group,disease_cases[extends=quantity:amount]

ツールを再度実行すると、国別の分割を排除する追加のスライス テーブルが得られます。

date,age_group,disease_cases
01/2000,old,152012
02/2000,old,211310
01/2000,young,241011
02/2000,young,240131

ソーステーブルに合計値と total_val タグを追加しないと、各年齢層について計算された合計が取得されます。

さらに、XML ファイルの disease_cases の定義には、必要に応じて quantity:amount の拡張機能が含まれるようになりました。代わりに country の定義をインポートしたため、この定義を XML ファイルから削除します。

さまざまな名前、説明、ユニット情報を入力したら、データセット バンドルを ZIP 形式で圧縮し、Public Data Explorer にアップロードして可視化します。