O DSPL Gen é um utilitário de linha de comando que ajuda a converter uma tabela de dados CSV em um simples conjunto de dados DSPL. A ferramenta analisa o arquivo de entrada, cria todas as tabelas de dados necessárias e apresenta um arquivo XML DSPL. O resultado é um "modelo" de conjunto de dados quase completo que requer apenas um pequeno refinamento antes do upload e da visualização.
A suposição fundamental por trás da geração de DSPL é que cada coluna no arquivo CSV de entrada corresponde a um único conceito de DSPL, e cada linha é uma única observação para uma combinação de dimensões. A ferramenta itera as colunas, estabelecendo os metadados apropriados para cada coluna / conceito (por exemplo, ID, tipo, se é uma dimensão ou métrica etc.) e gera toda a definição de conceito necessária e as tabelas de fatias.
Executando DSPL de geração
Sintaxe
Observação: essas instruções presumem que você já tenha seguido as instruções de instalação fornecidas na página Ferramentas DSPL.
Para executar a DSPL Gen, acesse o terminal / prompt no sistema e digite:
python dsplgen.py -o [output path] [path to CSV file]
em que os termos entre colchetes são substituídos da seguinte forma:
[output path]: caminho para o diretório em que você quer que os arquivos de saída sejam colocados. Esse diretório já precisa existir no sistema de arquivos.[path to CSV file]: caminho para o arquivo CSV de entrada. Consulte a seção abaixo para ver mais detalhes sobre como formatar esse arquivo.
O componente -o [output path] é opcional. Se omitido, os arquivos de saída serão colocados no diretório atual.
Em seguida, a ferramenta é executada, iterando com seu arquivo CSV, extraindo definições de conceito e gerando tabelas de fatias. A menos que algum erro seja encontrado, um arquivo XML e um ou mais arquivos CSV são gravados no diretório de saída.
Por fim, abra o arquivo XML no editor de texto de sua preferência e faça
as mudanças desejadas. No mínimo, é preciso preencher os nomes,
as descrições e outros valores que foram marcados pela ferramenta com a
notação ** INSERT ... **.
Exemplo simples
Imagine que temos um CSV que fornece o número total de casos para uma doença, divididos por mês, país e faixa etária. Para simplificar, vamos supor que haja dois valores para cada dimensão:
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
Executar a ferramenta na entrada acima produz quatro arquivos:
dataset.xml: o modelo XML de DSPLcountry_table.csv: valores do conceitocountryage_group_table.csv: valores do conceitoage_groupslice_0_table.csv: tabela para a fatia do conjunto de dados, idêntica à tabela de entrada, exceto para classificação.
Nesse caso específico, a ferramenta consegue adivinhar corretamente todos os tipos e formatos de colunas. Agora só falta acessar o arquivo XML e editar os nomes, descrições e URLs dos metadados do conjunto de dados.
Como anotar o CSV de entrada
Opções básicas
Em muitos casos, como no exemplo acima, a DSPL Gen consegue adivinhar os metadados básicos de cada coluna, por exemplo, o tipo, o formato e se é uma dimensão ou métrica. Em outros casos, a ferramenta pode não adivinhá-las, adivinhar incorretamente ou adivinhar corretamente, mas não seguir o comportamento desejado.
Para processar esses casos, a ferramenta aceita a adição de opções de geração/dicas de DSPL na linha de cabeçalho do CSV. A sintaxe delas é a seguinte:
column1[option1=value1;option2=value2;...],column2[option1=value1;option2=value2;...],column3[...],...
Observe que a lista de opções fica dentro de colchetes à direita do nome da coluna, e as configurações de opção sucessivas são separadas por ponto e vírgula. Cada opção tem um nome, um sinal de igual e um valor.
Atualmente, a geração de DSPL oferece suporte para as seguintes opções básicas:
| Opção | Descrição | Padrão |
|---|---|---|
type |
O tipo de dados DSPL desta coluna. Precisa ser date,
float, integer ou string. |
Eliminado dos dados |
format |
O formato dessa coluna de data. Assim como na DSPL, esse formato precisa ser codificado usando o padrão Joda DateTime. | Eliminado dos dados |
slice_role |
Qual é o papel dessa coluna em todas as frações. Precisa ser
dimension ou metric. |
dimension se a coluna for do tipo date ou string. Caso contrário, metric |
concept |
O conceito canônico que essa coluna representa, por exemplo, geo:country. Se fornecido, o conceito será importado e nenhuma definição será produzida no arquivo XML. |
Nenhuma |
extends |
O conceito canônico que essa coluna estende, por exemplo,
entity:entity. |
Nenhuma |
parent |
O conceito pai desta coluna. Esse pai precisa ser um conceito de dimensão definido dentro do conjunto de dados (ou seja, não importado). Se houver, essa informação será usada para definir uma hierarquia de conceitos no conjunto de dados. Cada instância filha só pode ter um pai. Se vários valores pais forem detectados, a ferramenta produzirá um erro. |
Nenhuma |
Consolidações de valor
Além das opções básicas de "dica" descritas acima,
a DSPL Gen também oferece suporte a visualizações completas de fatias: com uma única entrada
de tabela, a ferramenta cria automaticamente outras tabelas com subconjuntos
limitados das dimensões. Por exemplo, se a tabela de entrada corresponder a uma fatia com três dimensões não relacionadas a tempo (por exemplo, dimension1, dimension2 e dimensions3), a ferramenta também pode criar algumas frações adicionais: apenas dimension1, apenas dimension2, apenas dimension1 e
dimension2 etc.
Adicionar essas frações adicionais pode facilitar a exploração do conjunto de dados, já que reduz o número de filtros de dimensão necessários para produzir visualizações. Por outro lado, esse processo pode apresentar dados "novos" não encontrados no arquivo original e, portanto, também pode introduzir erros caso não seja usado corretamente. Verifique cuidadosamente os números acumulados antes de publicar seu conjunto de dados.
O processo de visualização completa é acionado incluindo algumas opções extras no cabeçalho CSV de entrada:
| Opção | Descrição | Padrão |
|---|---|---|
aggregation |
O método de agregação a ser usado ao combinar vários valores
dessa coluna. Precisa ser AVG, COUNT,
MAX, MIN ou SUM. Só
significativo para métricas. |
SUM |
rollup |
Se o valor for true, o conceito para essa coluna será "acumulado" (ou seja, agregado) e será significativo apenas para conceitos de dimensão. |
Falso |
total_val |
O valor nesta coluna que indica as linhas que serão mantidas quando esta coluna for rolada. Somente significativo para os conceitos de dimension. | None |
A DSPL Gen então calcula as visualizações completas usando o seguinte algoritmo:
- Usando os valores das tags
rollup, calcule todas as combinações de colunas possíveis - Faça o seguinte em cada combinação:
- Se alguma coluna de visualização completa tiver um parâmetro
total_valdefinido, filtre as linhas por esse valor. Caso contrário, selecione todas as linhas. - Solte as colunas agrupadas
- Agrupar as linhas pelos valores das colunas de dimensão restantes
- Agregar cada métrica usando o método especificado no
parâmetro
aggregation - Criar uma fatia e uma tabela associada para o resultado
- Se alguma coluna de visualização completa tiver um parâmetro
Se houver apenas um valor em cada agrupamento e a função de agregação estiver definida como SUM (o valor padrão), os valores das métricas nas tabelas de origem e geradas serão os mesmos, ou seja, nenhum valor novo será gerado. Assim, o uso do parâmetro total_val e a garantia de que haja apenas uma linha "total" para cada combinação das outras dimensões permite armazenar agregados agregados pré-computados diretamente na origem.
Aviso:o número de frações geradas é igual a duas colunas agrupadas. Aplicar essa opção a um grande número de colunas pode resultar em tempos de execução muito longos e/ou grandes conjuntos de dados.
Exemplo avançado
Suponha que tenhamos os mesmos dados de entrada do exemplo anterior, mas agora incluindo agregados em todos os países:
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
O total de cada faixa etária pode não corresponder à soma dos valores dos países porque, por exemplo, há diferenças na metodologia ou na existência de outros países que não estão enumerados na lista.
Agora queremos criar um conjunto de dados DSPL que tenha os seguintes recursos adicionais:
- "Reúna" os países para ver o total de casos de doenças por faixa etária
- Use o conceito canônico
geo:countrypara a colunacountrypara que possamos ter automaticamente os nomes completos, locais etc. - Faça com que o conceito
disease_casesestendaquantity:amount, para que possamos adicionar manualmente informações do bloco ao arquivo XML.
Para fazer isso, modificamos a linha do cabeçalho do CSV de entrada da seguinte forma:
date,country[concept=geo:country;rollup=true;total_val=total],age_group,disease_cases[extends=quantity:amount]
Ao executar a ferramenta novamente, agora temos uma tabela de parcelas adicional, que elimina a distinção por país:
date,age_group,disease_cases 01/2000,old,152012 02/2000,old,211310 01/2000,young,241011 02/2000,young,240131
Se não tivéssemos incluído os valores totais e a tag total_val na tabela de origem, teríamos a soma calculada para cada faixa etária.
Além disso, a definição de disease_cases no arquivo XML
agora inclui a extensão de quantity:amount, conforme você quiser. A definição de country é descartada do arquivo XML, porque estamos usando um conceito importado para isso.
Depois de preencher os diversos nomes, descrições e informações de unidade, podemos compactar o pacote do conjunto de dados e fazer upload dele no Explorador de dados públicos para visualização.