DSPL Gen

DSPL Gen 是一個指令列公用程式，可協助您將 CSV 資料表轉換為簡單的 DSPL 資料集。這項工具會剖析輸入檔案、建立所有必要的資料表，並配置 DSPL XML 檔案。結果是近乎完整的資料集「範本」，只需小幅修正，即可上傳並視覺化呈現。

DSPL Gen 背後的基本假設是輸入 CSV 檔案中的每個資料欄都對應於單一 DSPL 概念，每一資料列都是單一維度組合的單一觀察結果。這項工具會疊代這些資料欄，為每個資料欄 / 概念建立適當的中繼資料 (例如資料欄 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 檔案和一或多個 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 檔案並編輯資料集中繼資料中的各種名稱、說明和網址即可。

為輸入內容輸入 CSV 註解

基本選項

在許多情況下，和上述範例一樣，DSPL Gen 可以猜測每個資料欄的基本中繼資料，例如類型、格式，以及維度是維度或指標。然而，在其他情況下，該工具可能無法猜測這些問題、猜測或猜錯，或看不懂，但仍然不符合所需行為。

為因應這種情況，工具支援在 CSV 標題列中新增 DSPL 產生選項/「提示」。相關語法如下：

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

請特別注意，選項清單位於資料欄名稱右側的方括號內，連續選項的設定則會以分號分隔。每個選項都包含一個選項名稱、等號和選項值。

DSPL Gen 目前支援下列基本選項：

選項 說明 預設
type 這個資料欄的 DSPL 資料類型，必須是 date、float、integer 或 string 其中之一。 根據資料進行猜測
format 這個日期欄的格式；如同 DSPL，這種格式應使用 Joda DateTime 標準來編碼。 根據資料進行猜測
slice_role 這一欄在任何區塊中扮演的角色；必須是 dimension 或 metric。 dimension：如果資料欄的類型是 date 或 string，否則為 metric
concept 此資料欄代表的標準概念，例如 geo:country；如果指定的話，概念會匯入，而且 XML 檔案不會產生任何定義。 無
extends 這個資料欄延伸的標準概念，例如 entity:entity。 無
parent

這個資料欄的父項概念。這個父項必須是資料集內定義的維度概念 (亦即未匯入)；如果提供，此資訊將用於定義資料集中的概念階層。

請注意，每個子執行個體只能有一個父項。如果偵測到多個父項值，工具就會產生錯誤。

 無

價值綜覽

除了上述基本「提示」選項之外，DSPL Gen 也支援切片綜覽：只要指定單一資料表輸入，工具就能自動建立額外的維度有限的額外資料表。舉例來說，如果輸入資料表會對應至含有三個非時間維度 (例如dimension1、dimension2 和 dimensions3) 也可以建立其他額外區塊：僅 dimension1、dimension2、dimension1 和 dimension2 等。

新增這些額外資料部分可讓資料集更易於探索，因為這樣可以減少產生視覺化內容所需的維度篩選器數量。另一方面，這個程序可能會導入原本在原始檔案中找不到「新」的資料，因此如果無法正確使用，可能會產生錯誤；在發布資料集之前，請先仔細查看綜覽編號。

只要在輸入 CSV 標頭中加入一些額外選項，就會觸發綜覽程序：

選項 說明 預設
aggregation 用於合併此欄多個值的匯總方法，必須是 AVG、COUNT、MAX、MIN 或 SUM 其中之一；只對指標有意義。 SUM
rollup 如果值為 true，這個資料欄的概念會「復原」(即匯總)，且僅適用於「維度」概念。 否
total_val 此欄的值表示此資料欄綜覽時要保留的資料列，對維度概念才有意義。 None

DSPL Gen 會使用以下演算法計算綜覽資源：

  • 使用 rollup 標記的值，計算所有可能的欄組合
  • 針對每個組合：
    • 如果有任何綜覽資料欄已設定 total_val 參數，則請依據這個值篩選資料列；否則，選取所有資料列
    • 捨棄綜覽欄
    • 按照其餘維度欄的值將列分組
    • 使用 aggregation 參數中指定的方法匯總每個指標
    • 為結果建立 Slice 和關聯資料表

請注意，如果每個分組中只有一個值，並將匯總函式設為 SUM (預設值)，則來源和產生的資料表中的指標值將相同，亦即不會產生任何新值。因此，使用 total_val 參數並確保各維度組合的一個「總計」列可讓您直接在來源儲存預先計算的匯總。

警告：產生的 Slice 數量等於 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]

現在再次執行這個工具，現在我們得到一個新的 S D 表格，這個表格可以排除國家/地區的區別：

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 副檔名。系統會從 XML 檔案中捨棄 country 的定義，因為我們現在改用匯入的概念。

填寫各種名稱、說明和單位資訊後，我們就能將資料集組合壓縮，並上傳到公開資料瀏覽器，以視覺化方式呈現資料。