Tutorial de DSPL

DSPL é a sigla em inglês de linguagem de publicação de conjunto de dados. Os conjuntos de dados descritos no DSPL podem ser importados para o Explorador de dados públicos do Google, uma ferramenta que permite a exploração visual e avançada dos dados.

Observação:para fazer upload de dados para dados públicos do Google usando a ferramenta de upload de dados públicos, é preciso ter uma Conta do Google.

Neste tutorial, você verá um exemplo detalhado de como preparar um conjunto de dados básico do DSPL.

Um conjunto de dados DSPL é um pacote que contém um arquivo XML e um conjunto de arquivos CSV. Os arquivos CSV são tabelas simples que contêm os dados do conjunto de dados. O arquivo XML descreve os metadados do conjunto de dados, incluindo metadados informativos, como descrições de medidas, e metadados estruturais, como referências entre tabelas. Com os metadados, os usuários não especialistas podem explorar e visualizar seus dados.

O único pré-requisito para entender este tutorial é um bom nível de compreensão do XML. Algum conhecimento sobre conceitos simples de banco de dados (por exemplo, tabelas e chaves primárias) pode ajudar, mas não é obrigatório. Para referência, o arquivo XML completo e o pacote completo de conjuntos de dados associados a este tutorial também estão disponíveis para revisão.

Visão geral

Antes de criar nosso conjunto de dados, confira esta visão geral de alto nível do que um conjunto de dados DSPL contém:

  • Informações gerais: sobre o conjunto de dados
  • Conceitos: definições de "coisas" que aparecem no conjunto de dados (por exemplo, países, taxa de desemprego, gênero etc.)
  • Fatias: combinações de conceitos que contêm dados
  • Tabelas: dados para conceitos e frações. As tabelas de conceito contêm enumerações e as tabelas de fatia têm dados estatísticos
  • Tópicos: usado para organizar os conceitos do conjunto de dados em uma hierarquia significativa por meio de rotulagem

Para ilustrar essas noções bastante abstratas, considere o conjunto de dados (com dados fictícios) usado neste tutorial: séries temporais estatísticas para população e desemprego, agregadas por várias combinações de país, estado dos EUA e gênero.

Este exemplo de conjunto de dados define os seguintes conceitos:

  • country [país]
  • gender
  • population
  • estado
  • taxa de desemprego
  • year

Conceitos categóricos, como estado, são associados a tabelas de conceito, que enumeram todos os valores possíveis (Califórnia, Arizona etc.). Os conceitos podem ter outras colunas para propriedades, como o nome ou o país de um estado.

Slices definem cada combinação de conceitos para os quais há dados estatísticos no conjunto de dados. Uma fração contém dimensões e métricas. Na imagem acima, as dimensões estão em azul e as métricas estão em laranja. Neste exemplo, a fração gender_country_slice tem dados para a métrica population e as dimensões country, year e gender. Outra fatia, chamada country_slice, fornece o número total da população anual (métrica) para países.

Além das dimensões e métricas, as fatias também fazem referência a tabelas, que contêm os dados reais.

Agora vamos ver as etapas para criar esse conjunto de dados na DSPL.

Informações do conjunto de dados

Para começar, precisamos criar um arquivo XML para nosso conjunto de dados. Veja o início de uma descrição de DSPL para nosso conjunto de dados de exemplo:

<?xml version="1.0" encoding="UTF-8"?>
<dspl targetNamespace="http://www.stats-bureau.com/mystats"
   xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
   xmlns="http://schemas.google.com/dspl/2010"
   xmlns:time="http://www.google.com/publicdata/dataset/google/time"
   xmlns:geo="http://www.google.com/publicdata/dataset/google/geo"
   xmlns:entity="http://www.google.com/publicdata/dataset/google/entity"
   xmlns:quantity="http://www.google.com/publicdata/dataset/google/quantity">

  <import namespace="http://www.google.com/publicdata/dataset/google/time"/>
  <import namespace="http://www.google.com/publicdata/dataset/google/entity"/>
  <import namespace="http://www.google.com/publicdata/dataset/google/geo"/>
  <import namespace="http://www.google.com/publicdata/dataset/google/quantity"/>

  <info>
    <name>
      <value>My statistics</value>
    </name>
    <description>
      <value>Some very interesting statistics about countries</value>
    </description>
    <url>
      <value>http://www.stats-bureau.com/mystats/info.html</value>
    </url>
    </info>

  <provider>
    <name>
      <value>Bureau of Statistics</value>
    </name>
    <url>
      <value>http://www.stats-bureau.com</value>
    </url>
  </provider>
 ...
</dspl>

A descrição do conjunto de dados começa com um elemento <dspl> de nível superior. O atributo targetNamespace contém um URI que identifica exclusivamente esse conjunto de dados. O namespace do conjunto de dados é especialmente importante ao publicar o conjunto de dados, porque será o identificador global do seu conjunto de dados e o meio para que outras pessoas o consultem.

O atributo targetNamespace pode ser omitido. Nesse caso, um namespace exclusivo é gerado automaticamente quando o conjunto de dados é importado.

Como usar informações de outros conjuntos de dados

Os conjuntos de dados podem reutilizar definições e dados de outros conjuntos de dados importando-os. Cada elemento <import> especifica o namespace de outro conjunto de dados que será referenciado.

Em nosso conjunto de dados de exemplo, precisaremos de algumas definições de http://www.google.com/publicdata/dataset/google/quantity (um conjunto de dados criado pelo Google que contém conceitos úteis para definir quantidades numéricas) e dos conjuntos de dados time, entity e geo, que fornecem definições relacionadas a tempo, entidades e geografia, respectivamente.

O elemento <dspl> principal fornece uma declaração de prefixo de namespace (por exemplo, xmlns:time="http://...") para cada um dos conjuntos de dados importados. As declarações de prefixo são necessárias para referenciar elementos de outros conjuntos de dados de maneira concisa. Por exemplo, time:year faz referência à definição de year no conjunto de dados importado cujo namespace está associado ao prefixo time.

Informações do provedor e do conjunto de dados

O elemento <info> contém informações gerais sobre o conjunto de dados: nome, descrição e um URL em que mais informações podem ser encontradas.

O elemento <provider> contém informações sobre o provedor do conjunto de dados: o nome dele e um URL em que mais informações podem ser encontradas (geralmente, a página inicial do provedor de dados).

Definição de conceitos

Agora que fornecemos algumas informações gerais sobre o conjunto de dados, estamos prontos para começar a definir o conteúdo dele. O próximo objetivo é adicionar estatísticas populacionais de países nos últimos 50 anos.

A primeira coisa a se fazer é fornecer algumas definições para as noções de população, país e ano. Na DSPL, essas definições são chamadas de conceitos.

Um conceito é uma definição de um tipo de dados que aparece em um conjunto de dados. Os valores de dados que correspondem a um determinado conceito são chamados de instâncias desse conceito.

População

Vamos começar definindo o conceito de população. Em um documento DSPL, os conceitos são definidos em um elemento <concepts> que vem logo depois das informações do conjunto de dados e do provedor.

Veja um conceito de população com apenas as informações mínimas necessárias para qualquer conceito: id (um identificador exclusivo), name e type.

<dspl ...>
  ...
  <concepts>
    <concept id="population">
      <info>
        <name>
          <value>Population</value>
        </name>
      </info>
      <type ref="integer"/>
    </concept>
  ...
  </concepts>

Como a amostra funciona:

  • Cada conceito precisa fornecer um id que o identifique exclusivamente no conjunto de dados. Isso significa que dois conceitos definidos no mesmo conjunto de dados não podem ter o mesmo ID.
  • Assim como no conjunto de dados e no provedor, os elementos <info> fornecem informações textuais sobre o conceito, como nome e descrição.
  • O elemento <type> especifica o tipo de dados das instâncias do conceito (ou seja, os "valores"). Neste exemplo, o tipo de population é integer. A DSPL é compatível com os seguintes tipos de dados:
    • string
    • integer
    • float
    • boolean
    • date

País

Agora vamos escrever a definição do conceito de país:

<concept id="country">
  <info>
    <name><value>Country</value></name>
    <description>
      <value>My list of countries.</value>
    </description>
  </info>
  <type ref="string"/>
  <property id="name">
    <info>
      <name><value>Name</value></name>
      <description>
        <value>The official name of the country</value>
      </description>
    </info>
    <type ref="string" />
  </property>
  <table ref="countries_table" />
</concept>

A definição do conceito de país começa como a anterior, com um id, info e um type.

Valores conceituais

Conceitos categóricos, como países, têm uma enumeração de todas as instâncias possíveis. Em outras palavras, é possível listar todos os países possíveis de referência. No entanto, para fazer isso, cada país precisa de um identificador exclusivo. Este exemplo usa códigos de países ISO para identificar países. Esses códigos são do tipo string.

Neste exemplo, você não precisa usar o código ISO, mas pode usar o mesmo nome de país. No entanto, os nomes diferem por idioma, podem mudar ao longo do tempo e nem sempre são usados de forma consistente em conjuntos de dados. Para países e para conceitos categóricos em geral, é recomendável escolher identificadores curtos, estáveis, mais usados e independentes de idioma (se houver).

Propriedades de conceito

Além do id, o conceito de país tem um elemento <property> que especifica o nome do país. Em outras palavras, o nome do país ("Irlanda") é uma propriedade do país com o IE id. As propriedades são como a DSPL fornece informações estruturadas adicionais sobre as instâncias de um conceito.

Assim como o próprio conceito, as propriedades têm id, info e type.

Dados do conceito

Por fim, o conceito de país tem um elemento <table>. Esse elemento faz referência a uma tabela que enumera a lista de todos os países.

Usar tabelas faz sentido para alguns conceitos, mas não para outros. Por exemplo, não faz sentido enumerar todos os valores possíveis para a população do conceito. No entanto, se você referenciar uma tabela para um conceito, ela precisará conter todas as instâncias do conceito. Por exemplo, uma lista de todos os países, e não apenas uma amostra pequena.

O conjunto de dados define a tabela countries_table da seguinte maneira:

...
<tables>
  <table id="countries_table">
    <column id="country" type="string"/>
    <column id="name" type="string"/>
    <data>
      <file format="csv" encoding="utf-8">countries.csv</file>
    </data>
  </table>
  ...
</tables>

A tabela de países especifica as colunas da tabela e os tipos delas e faz referência a um arquivo CSV que contém os dados. Esse CSV pode ser empacotado e enviado com o XML do conjunto de dados ou acessado remotamente por HTTP, HTTPS ou FTP. Nos últimos casos, substitua countries.csv por um URL, por exemplo, http://www.myserver.com/mydata/countries.csv.

Não importa onde ele esteja armazenado, o arquivo CSV tem esta aparência:

country, name
AD,      Andorra
AF,      Afghanistan
AI,      Anguilla
AL,      Albania
US,      United States

A primeira linha da tabela lista os IDs de coluna, conforme especificado na definição de table da DSPL. Cada uma das linhas a seguir corresponde a uma instância do conceito de país. Se o conceito tiver uma tabela, ela precisará conter todas as instâncias dele. Nesse caso, ela precisa listar todos os países.

As colunas são mapeadas para o conceito de país e as propriedades dele com base no ID. O ID da primeira coluna, country, corresponde ao ID do conceito. Isso significa que a coluna contém o identificador exclusivo de país definido pelo conceito de país. A próxima coluna corresponde à propriedade name do conceito de país. Os valores nesta coluna correspondem aos valores da propriedade name.

Há alguns requisitos para os dados CSV da tabela de conceitos:

  • Os cabeçalhos das colunas na primeira linha do arquivo de dados precisam corresponder exatamente ao conceito id e à propriedade id do conceito a que os dados estão associados, embora a ordem possa variar.
  • Cada linha precisa ter exatamente o mesmo número de elementos que o número de propriedades no conceito, mesmo que o valor esteja vazio.
  • Cada valor do campo id do conceito (aqui, o código do país) precisa ser exclusivo e não vazio (um campo vazio é aquele com zero ou apenas caracteres de espaço em branco).
  • Os valores de propriedades que fazem referência a outros conceitos precisam estar vazios ou ser um valor válido do conceito referenciado.
  • Os valores que contêm vírgulas, aspas duplas ou caracteres de nova linha precisam ser totalmente colocados entre aspas duplas.
  • Qualquer caractere literal entre aspas duplas dentro de um valor precisa ser imediatamente precedido por outra aspa dupla.

Ano

O último conceito necessário para os dados populacionais do nosso país é um conceito que representa anos. Em vez de definir um novo conceito, usaremos o conceito de ano de um dos conjuntos de dados que importamos: "http://www.google.com/publicdata/dataset/google/time". Para fazer isso, precisamos referenciá-lo como time:year, em que time representa o conjunto de dados referenciado e year identifica o conceito.

Conceitos canônicos

O time:year faz parte de um pequeno conjunto de conceitos canônicos definidos pelo Google. Os conceitos canônicos fornecem definições básicas de tempo, geografia, quantidades numéricas, unidades etc.

Na verdade, o conceito de país definido acima existe como um conceito canônico. Ela foi criada apenas para fins ilustrativos. Sempre que possível, use conceitos canônicos nos seus conjuntos de dados, diretamente ou ao estendê-los (mais informações sobre a extensão abaixo). Os conceitos canônicos tornam os dados comparáveis a outros conjuntos de dados e ativam recursos para seus conjuntos de dados no Explorador de dados públicos. Por exemplo, a animação de dados ao longo do tempo ou a exibição de dados geográficos em um mapa dependem do uso dos conceitos canônicos time e geo, respectivamente.

Primeiro fatia

Agora que temos conceitos de população, país e ano, é hora de reuni-los.

Para isso, precisamos criar uma fatia que os combine. No DSPL, uma parcela é uma combinação de conceitos que contêm dados.

Por que não criar uma tabela com as colunas certas? Porque as fatias capturam as informações do conjunto de dados em termos de conceitos. Isso vai ficar mais claro à medida que criarmos mais partes do nosso conjunto de dados.

Slices aparecem no arquivo DSPL em um elemento <slices>, que precisa aparecer logo após a seção concepts.

<slices>
  <slice id="countries_slice">
    <dimension concept="country"/>
    <dimension concept="time:year"/>
    <metric concept="population"/>
    <table ref="countries_slice_table"/>
  </slice>
</slices>

Assim como os conceitos, cada fatia tem uma id (countries_slice) que a identifica exclusivamente no conjunto de dados.

Uma fração contém dois tipos de referências de conceitos: Dimensões e métricas. Os valores das métricas variam de acordo com os valores das dimensões. Aqui, o valor de population (a métrica) varia de acordo com as dimensões country e year.

Assim como os conceitos, as fatias incluem uma referência a uma tabela que contém os dados delas. A tabela referenciada precisa ter uma coluna para cada dimensão e métrica da fatia. Assim como nos conceitos, as dimensões e métricas da fração são mapeadas para as colunas da tabela com os mesmos IDs.

Tabela Slice

A tabela da nossa fração de população aparece na seção tables do arquivo DSPL:

<tables>
  ...
  <table id="countries_slice_table">
    <column id="country" type="string"/>
    <column id="year" type="date" format="yyyy"/>
    <column id="population" type="integer"/>
    <data>
      <file format="csv" encoding="utf-8">country_slice.csv</file>
    </data>
  </table>
  ...
</tables>

Observe que a coluna year vem com um atributo format que especifica como os anos são formatados. Os formatos de data aceitos são aqueles definidos pelo formato Joda DateTime.

A tabela countries_slice especifica as colunas da tabela e os tipos delas e aponta para um arquivo CSV que contém os dados. O arquivo CSV tem esta aparência:

country, year,  population
AF,      1960,  9616353
AF,      1961,  9799379
AF,      1962,  9989846
AF,      1963,  10188299
...

Cada linha da tabela contém uma combinação única das dimensões country e year, além do valor correspondente da métrica population (por exemplo, a população - métrica - do Afeganistão em 1960 - dimensões).

Os valores na coluna country correspondem ao valor/identificador do conceito country, que é o código ISO 3166 de duas letras do país.

Os dados CSV de uma fatia precisam atender às seguintes restrições:

  • Cada valor de um campo de dimensão (como country e year) não pode estar vazio. Os valores dos campos de métrica (como population) podem estar vazios. Um valor vazio é representado por nenhum caractere.
  • Cada valor de um campo de dimensão que faz referência a um conceito precisa estar presente nos dados dele. Por exemplo, o valor AF precisa estar presente na tabela de dados do conceito country.
  • Cada combinação exclusiva de valores de dimensão, por exemplo, AF, 2000, pode ocorrer apenas uma vez.
  • Os dados precisam ser classificados pelas colunas de dimensão sem tempo (em qualquer ordem) e, opcionalmente, por qualquer uma das outras colunas. Por exemplo, em uma tabela com as colunas [date, dimension1, dimension2, metric1, metric2], é possível classificar por dimension1, então dimension2 e depois date, mas não por date e depois pelas dimensões.

Resumo

No momento, temos o suficiente na DSPL para descrever os dados populacionais do país. Recapitulando:

  • Criar o cabeçalho DSPL e a descrição do conjunto de dados e do provedor dele
  • Crie um conceito para a população e outro para o país, com um arquivo csv enumerando todos os países e os nomes deles.
  • Crie uma parcela com nossos números populacionais para países ao longo do tempo, referenciando o conceito de ano já definido no conjunto de dados importado do Google.

No restante deste tutorial, vamos enriquecer nosso conjunto de dados adicionando mais dimensões em mais frações, bem como mais métricas agrupadas por tópico.

Como adicionar uma dimensão: estados dos EUA

Agora, vamos enriquecer nosso conjunto de dados adicionando dados populacionais para estados nos EUA. Primeiro precisamos definir um conceito para os estados. Isso é muito parecido com o conceito de país que definimos antes.

<concept id="state" extends="geo:location">
  <info>
    <name>
      <value>state</value>
    </name>
    <description>
      <value>US states, identified by their two-letter code.</value>
    </description>
  </info>
  <property concept="country" isParent="true" />
  <table ref="states_table"/>
</concept>

Extensões de conceito e referências de propriedade

O conceito de estado introduz vários novos recursos da DSPL.

Primeiro, o estado estende outro conceito, geo:location (definido no conjunto de dados geográficos externos que importamos no início do conjunto de dados). Semanticamente, isso significa que state é um tipo de geo:location. Uma consequência é que ela herda todos os atributos e propriedades de geo:location. Especificamente, o local define propriedades para latitude e longitude. Ao estender o conceito anterior, essas propriedades também são aplicadas ao estado. Além disso, como o local é herdado de entity:entity, o estado também recebe todas as propriedades da última, incluindo name, description e info_url.

Observação:o conceito de país definido anteriormente também precisa ser estendido de geo:location. Para simplificar, esse ponto foi omitido antes. No entanto, incluímos a localização em herança de país, no arquivo XML final.

Observação: é possível usar a construção extends nos seus próprios conjuntos de dados para reutilizar as informações definidas por outros conjuntos de dados. O uso de extends exige que todas as instâncias do conceito sejam válidas. As extensões permitem adicionar outras propriedades e atributos e restringem o conjunto de instâncias a um subconjunto das instâncias do conceito estendido.

Além da herança, a propriedade de estado também introduz a ideia de referências de conceitos. Mais especificamente, o conceito de estado tem uma propriedade chamada country, que faz referência ao conceito de país que criamos acima. Isso é feito com um atributo concept. Essa propriedade não fornece um ID, apenas uma referência de conceito. Isso é equivalente a criar um ID com o mesmo valor do ID do conceito referenciado (ou seja, country neste exemplo). A relação hierárquica entre estado e condado é capturada com um atributo isParent="true" na referência. Em geral, as dimensões com relações hierárquicas, como regiões geográficas, precisam ser representadas dessa forma, com o conceito filho tendo uma propriedade que faça referência ao conceito pai usando o atributo isParent.

A definição da tabela de estados tem esta aparência:

<tables>
  ...
  <table id="states_table">
    <column id="state" type="string"/>
    <column id="name" type="string"/>
    <column id="country" type="string">
      <value>US</value>
    </column>
    <column id="latitude" type="float"/>
    <column id="longitude" type="float"/>
    <data>
      <file format="csv" encoding="utf-8">states.csv</file>
    </data>
  </table>
  ...
</tables>

A coluna "país" tem um valor constante para todos os estados. Especificá-lo na DSPL evita repetir esse valor para cada estado nos dados. Também incluímos colunas para name, latitude e longitude, já que o estado herdou essas propriedades de geo:location. Por outro lado, algumas propriedades herdadas (por exemplo, description) não têm colunas. Tudo bem. Se uma propriedade for omitida de uma tabela de definição de conceito, o valor dela será definido como indefinido para cada instância do conceito.

O arquivo CSV tem esta aparência:

state, name,        latitude,  longitude
AL,    Alabama,     32.318231, -86.902298
AK,    Alaska,      63.588753, -154.493062
AR,    Arkansas,    35.20105,  -91.831833
AZ,    Arizona,     34.048928, -111.093731
CA,    California,  36.778261, -119.417932
CO,    Colorado,    39.550051, -105.782067
CT,    Connecticut, 41.603221, -73.087749
...

Como já temos conceitos de população e de ano, podemos reutilizá-los para definir uma nova fração para a população de estados.

<slices>
  <slice id="states_slice">
    <dimension concept="state"/>
    <dimension concept="time:year"/>
    <metric concept="population"/>
    <table ref="states_slice_table"/>
  </slice>
</slices>

A definição da tabela de dados tem esta aparência:

<tables>
  ...
  <table id="states_slice_table">
    <column id="state" type="string"/>
    <column id="year" type="date" format="yyyy"/>
    <column id="population" type="integer"/>
    <file format="csv" encoding="utf-8">state_slice.csv</file>
  </table>
  ...
</tables>

E o arquivo CSV terá esta aparência:

state, year, population
AL,    1960, 9616353
AL,    1961, 9799379
AL,    1962, 9989846
AL,    1963, 10188299

Por que criamos uma nova porção em vez de adicionar outra dimensão à anterior?

Uma fatia com dimensões para estado e país não estaria correta, porque algumas linhas estariam para dados do país e outras para dados do estado. A tabela teria "buracos" para algumas dimensões, o que não é permitido. Lembre-se de que valores ausentes são permitidos somente para métricas, e não dimensões.

As dimensões funcionam como uma "chave primária" para a fatia. Isso significa que cada linha de dados precisa ter valores para todas as dimensões, e duas linhas de dados não podem ter os mesmos valores para todas as dimensões.

Como adicionar uma métrica: taxa de desemprego

Agora vamos adicionar outra métrica ao conjunto de dados:

<concept id="unemployment_rate" extends="quantity:rate">
  <info>
    <name>
      <value>Unemployment rate</value>
    </name>
    <description>
      <value>The percent of the labor force that is unemployed.</value>
    </description>
    <url>
      <value>http://www.bls.gov/cps/cps_htgm.htm</value>
    </url>
  </info>
  <type ref="float/>
  <attribute id="is_percentage">
    <type ref="boolean"/>
    <value>true</value>
  </attribute>
</concept>

A seção info dessa métrica tem um nome, uma descrição e um URL (que leva ao Departamento de Estatísticas do Trabalho dos EUA).

Esse conceito também estende o conceito canônico quantity:rate. O conjunto de dados de quantidade define os principais conceitos para representar quantidades numéricas. No seu conjunto de dados, crie seus conceitos numéricos estendendo o conceito de quantidade apropriado. Assim, o conceito population definido acima precisa ter sido tecnicamente estendido de quantity:amount.

Atributos do conceito

Esse conceito também introduz a construção de um atributo. Nesse exemplo, um atributo é usado para dizer que unemployment_rate é uma porcentagem. O atributo is_percentage é herdado do conceito quantity:rate estendido. Essas informações são usadas pelo Explorador de dados públicos para mostrar sinais de porcentagem ao visualizar os dados.

Os atributos oferecem um mecanismo geral para anexar pares de chave-valor a um conceito (por exemplo, propriedades, que associam valores adicionais a instâncias de um conceito). Assim como conceitos e propriedades, os atributos têm id, info e type. Assim como as propriedades, elas podem referenciar outros conceitos.

Os atributos não são apenas para itens gerais predefinidos, como propriedades numéricas. É possível definir atributos para seus conceitos.

Adição de dados sobre a taxa de desemprego nos EUA

Agora já podemos adicionar dados sobre a taxa de desemprego nos estados dos EUA. Como a taxa de desemprego é uma métrica e já temos dados populacionais para estados, basta adicioná-los à fração já criada para as dimensões de estado e ano:

<slices>
  ...
  <slice id="states_slice">
    <dimension concept="state"/>
    <dimension concept="time:year"/>
    <metric concept="population"/>
    <metric concept="unemployment_rate"/>
    <table ref="states_slice_table"/>
  </slice>
  ...
</slices>

... e adicionar outra coluna à definição da tabela:

<tables>
  ...
  <table id="states_slice_table">
    <column id="state" type="string"/>
    <column id="year" type="date" format="yyyy"/>
    <column id="population" type="integer"/>
    <column id="unemployment_rate" type="float"/>
    <data>
      <file format="csv" encoding="utf-8">state_slice.csv</file>
    </data>
  </table>
  ...
</tables>

... e para o arquivo CSV:

state, year, population, unemployment_rate
AL,    1960, 9616353,    5.1
AL,    1961, 9799379,    5.2
AL,    1962, 9989846,    4.8
AL,    1963, 10188299,   6.9

Vimos anteriormente que, para cada fatia, as dimensões formam uma chave primária. Além disso, cada conjunto de dados só pode conter uma fatia para uma combinação específica de dimensões. Todas as métricas disponíveis para essas dimensões precisam pertencer à mesma fração.

Mais dimensões: detalhamento da população por gênero

Vamos enriquecer nosso conjunto de dados com um detalhamento da população por gênero para países. Você já começou a conhecer a furadeira... Primeiro precisamos adicionar um conceito de gênero:

<concept id="gender" extends="entity:entity">
  <info>
    <name>
      <value>Gender</value>
    </name>
    <description>
      <value>Gender, Male or Female</value>
    </description>
    <pluralName>
      <value>Genders</value>
    </pluralName>
    <totalName>
      <value>Both genders</value>
    </totalName>
  </info>
  <type ref="string"/>
  <table ref="genders_table"/>
</concept>

A seção de conceito do gênero info tem um pluralName, que fornece o texto a ser usado para se referir a várias instâncias do conceito de gênero. A seção info também inclui um totalName, que fornece o texto a ser usado para se referir a todas as instâncias do conceito de gênero como um todo. Ambos são usados pelo Explorador de dados públicos para exibir informações relacionadas ao conceito de gênero. Em geral, forneça-os para conceitos que podem ser usados como dimensões.

O conceito de gênero também se estende de entity:entity. Essa é uma prática recomendada para conceitos usados como dimensões, porque permite adicionar nomes, URLs e cores personalizados às várias instâncias de conceito.

O conceito de gênero se refere à tabela genders_table, que contém os valores possíveis para o gênero e os nomes de exibição (omitidos aqui).

Para adicionar população por gênero ao nosso conjunto de dados, precisamos criar uma nova fatia (lembre-se: cada combinação disponível de dimensões corresponde a uma fração no conjunto de dados).

<slice id="countries_gender_slice">
  <dimension concept="country"/>
  <dimension concept="gender"/>
  <dimension concept="time:year"/>
  <metric concept="population"/>
  <table ref="countries_gender_slice_table"/>
</slice>

A definição da tabela para a fatia tem esta aparência:

<table id="countries_gender_slice_table">
  <column id="country" type="string"/>
  <column id="gender" type="string"/>
  <column id="year" type="date" format="yyyy"/>
  <column id="population" type="integer"/>
  <data>
    <file format="csv" encoding="utf-8">gender_country_slice.csv</file>
  </data>
</table>

O arquivo CSV da tabela tem esta aparência:

country, gender, year, population
AF,      M,      1960, 4808176
AF,      F,      1960, 4808177
AF,      M,      1961, 4899689
AF,      F,      1961, 4899690...

Em comparação com os países, a população e as parcelas de desemprego anteriores, este tem uma dimensão adicional. Cada valor da métrica de população corresponde não só a um determinado país e ano, mas também a um gênero específico.

Observe que criamos um conjunto de dados "esparso". Nem todas as métricas estão disponíveis para todas as dimensões: a população está disponível para países e estados dos EUA anualmente, enquanto a taxa de desemprego está disponível apenas para países. O detalhamento por gênero está disponível apenas para a população por país. Ele não está disponível para a métrica de taxa de desemprego e não para a dimensão de estado. A esparsidade também pode existir no nível de dados, com determinadas métricas que não têm valores para determinados valores de dimensão, mas isso não é representado na DSPL.

Tópicos

O último recurso da DSPL que vamos usar no nosso conjunto de dados é o topics. Os temas são usados para classificar conceitos de forma hierárquica e são usados por aplicativos para ajudar os usuários a navegar até seus dados.

No arquivo DSPL, os tópicos aparecem logo antes dos conceitos. Veja um exemplo de hierarquia de tópicos:

<dspl ... >
  ...
  <topics>
    <topic id="geography">
      <info>
        <name>
          <value>Geography</value>
        </name>
      </info>
    </topic>
    <topic id="social_indicators">
      <info>
        <name>
          <value>Social indicators</value>
        </name>
      </info>
    </topic>
    <topic id="population_indicators">
      <info>
        <name>
          <value>Population indicators</value>
        </name>
      </info>
    </topic>
    <topic id="poverty_and_income">
      <info>
        <name>
          <value>Poverty & income</value>
        </name>
      </info>
    </topic>
    <topic id="health">
      <info>
        <name>
          <value>Health</value>
        </name>
      </info>
    </topic>
  </topics>

É possível aninhar temas conforme necessário.

Para usar tópicos, basta referenciá-los na definição de conceito, da seguinte maneira:

<concept id="population">
  <info>
    <name>
      <value>Population</value>
    </name>
    <description>
      <value>Size of the resident population.</value>
    </description>
  </info>
  <topic ref="population_indicators"/>
  <type ref="integer"/>
</concept>

Um conceito pode fazer referência a mais de um tema.

Como enviar seu conjunto de dados

Agora que você criou seu conjunto de dados, a próxima etapa é compactá-lo e fazer upload do arquivo ZIP para a ferramenta Explorador de dados públicos do Google. Se você encontrar problemas, consulte as Perguntas frequentes, que incluem uma discussão sobre os problemas de upload mais comuns.

Como referência, também é possível fazer o download do arquivo XML completo e do pacote completo de conjunto de dados associados a este tutorial.

O que fazer depois

Parabéns por criar seu primeiro conjunto de dados DSPL. Agora que você entendeu o básico, recomendamos a leitura do Guia para desenvolvedores, que, entre outras informações, documenta recursos DSPL "avançados", como suporte a vários idiomas e conceitos mapeáveis.

Talvez você também queira analisar mais alguns exemplos de conjuntos de dados.