Tutorial de DSPL

DSPL significa linguagem de publicação de conjunto de dados. Os conjuntos de dados descritos em DSPL podem ser importados para o Google Public Data Explorer, uma ferramenta que permite uma exploração visual rica dos dados.

Observação:para fazer o upload de dados para o Google Public Data usando a ferramenta de upload de dados públicos, você precisa ter uma Conta do Google.

Neste tutorial, fornecemos um exemplo passo a passo de como preparar um conjunto de dados DSPL básico.

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, usuários não especialistas podem explorar e visualizar seus dados.

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

Visão geral

Antes de começar a criar nosso conjunto de dados, veja uma 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.)
  • Slices:combinações de conceitos para os quais há dados
  • Tabelas:dados de conceitos e frações. As tabelas conceituais contêm enumerações, e as fatias contê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 em todo este 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 conjunto de dados de exemplo define os seguintes conceitos:

  • country
  • gender
  • population
  • state
  • taxa de desemprego
  • year

Os 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 colunas adicionais para propriedades, como o nome ou o país de um estado.

Frações 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 são azuis e as métricas são 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 fração, chamada country_slice, informa os números da população anual total (métrica) para os 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, vejamos passo a passo a criação desse conjunto de dados no DSPL.

Informações do conjunto de dados

Para começar, precisamos criar um arquivo XML para nosso conjunto de dados. Este é 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 durante a publicação, porque será o identificador global do conjunto de dados e o meio para outros usuários se referirem a ele.

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á usado como referência.

No nosso conjunto de dados de exemplo, vamos precisar 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> superior 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 que tem o namespace associado ao prefixo time.

Informações do conjunto de dados e do provedor

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

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).

definir conceitos

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

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

Um conceito é a 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 após as informações do conjunto de dados e do provedor.

Este é um conceito de preenchimento 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 de maneira exclusiva dentro do conjunto de dados. Isso significa que dois conceitos definidos no mesmo conjunto de dados não podem ter o mesmo ID.
  • Assim como o conjunto de dados e o provedor, os elementos <info> fornecem informações textuais sobre o conceito, como o nome e a descrição.
  • O elemento <type> especifica o tipo de dados para as instâncias do conceito, ou seja, os "valores" dele. Neste exemplo, o tipo de population é integer. O DSPL oferece suporte aos 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 id, info e type.

Valores de conceito

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 que podem ser referenciados. Para isso, cada país precisa de um identificador exclusivo. Este exemplo usa códigos de país ISO para identificar países. Esses códigos são do tipo string.

Nesse exemplo, não é necessário usar o código ISO, mas sim o nome do país. No entanto, os nomes variam de acordo com o idioma, podem mudar com o tempo e nem sempre são usados de maneira consistente nos conjuntos de dados. Para países e para conceitos categóricos em geral, é recomendável escolher identificadores curtos, estáveis, usados com frequência e independentes de linguagem (se existirem).

Propriedades do conceito

Além de 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 id IE. As propriedades são como a DSPL fornece mais informações estruturadas sobre as instâncias de um conceito.

Assim como o conceito em si, as propriedades têm id, info e type.

Dados conceituais

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.

O uso de tabelas faz sentido para alguns conceitos, mas não para outros. Por exemplo, não faz sentido enumerar todos os valores possíveis para o preenchimento do conceito. No entanto, se você fizer referência a uma tabela para um conceito, essa tabela precisará conter todas as instâncias do conceito. Por exemplo, ela precisa listar todos os países, não apenas alguns exemplos.

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 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 pode ser acessado remotamente via HTTP, HTTPS ou FTP. Nos últimos casos, substitua countries.csv por um URL, por exemplo, http://www.myserver.com/mydata/countries.csv.

Onde quer que esteja armazenado, o arquivo CSV tem a seguinte 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 do DSPL. Cada uma das linhas a seguir corresponde a uma instância do conceito de país. Se o conceito tiver uma tabela, a tabela precisará conter todas as instâncias do conceito. Nesse caso, ela precisa listar todos os países.

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

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

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

Ano

O último conceito necessário para os dados populacionais do país é um conceito que represente 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 isso, precisamos referenciá-lo como time:year, em que time representa o conjunto de dados referenciado e year identifica o conceito.

Conceitos canônicos

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

Na verdade, o conceito de país definido acima existe como um conceito canônico. Ele foi criado aqui apenas para fins ilustrativos. Sempre que possível, use conceitos canônicos nos conjuntos de dados, seja diretamente ou estendendo-os. Confira mais informações sobre 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 depende do uso dos conceitos canônicos time e geo, respectivamente.

Primeira fração

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

Para isso, precisamos criar uma fatia que os combine. Em DSPL, uma fração é uma combinação de conceitos para os quais há dados.

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

As Slices aparecem no arquivo DSPL sob 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 fração tem um id (countries_slice) que a identifica exclusivamente dentro do conjunto de dados.

Uma fração contém dois tipos de referências de conceito: 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 fração. Assim como nos conceitos, as dimensões e métricas da fração são mapeadas para as colunas da tabela com os mesmos códigos.

Tabela de fração

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 compatíveis 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 de dados contém uma combinação exclusiva das dimensões country e year, além do valor correspondente da métrica population (por exemplo, população - métrica - do Afeganistão em 1960 - dimensões).

Observe que 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 fração precisam atender às seguintes restrições:

  • Cada valor de um campo de dimensão (como country e year) não pode ficar em branco. Os valores dos campos de métricas (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 conceituais country.
  • Cada combinação exclusiva de valores de dimensão, por exemplo, AF, 2000, pode ocorrer apenas uma vez.
  • Os dados devem ser classificados pelas colunas de dimensão que não sejam de tempo (em qualquer ordem) e depois, opcionalmente, por qualquer uma das outras colunas. Assim, por exemplo, em uma tabela com as colunas [date, dimension1, dimension2, metric1, metric2], é possível classificar por dimension1, depois dimension2, depois date, mas não por date e, em seguida, as dimensões.

Resumo

Neste ponto, temos o suficiente em nossa DSPL para descrever os dados populacionais do país. Para recapitular, o que tínhamos que fazer foi:

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

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

Adição de uma dimensão: estados dos EUA

Agora, vamos enriquecer nosso conjunto de dados adicionando dados populacionais dos estados dos EUA. Primeiro precisamos definir um conceito para os estados. Isso se parece muito 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 de DSPL.

Primeiro, o estado extends outro conceito, geo:location, definido no conjunto de dados geográficos externo que importamos no início do conjunto. Semanticamente, isso significa que state é um tipo de geo:location. Como consequência, ela herda todos os atributos e propriedades de geo:location. Em particular, 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 a localização herda de entity:entity, o estado também recebe todas as propriedades deste último, incluindo name, description e info_url.

Observação:tecnicamente, o conceito de país definido anteriormente precisa ter também uma extensão de geo:location. Esse ponto foi omitido anteriormente para simplificar. No entanto, incluímos o local na herança do país no arquivo XML final.

Observação: você pode usar a construção extends nos seus próprios conjuntos de dados para reutilizar informações definidas por outros conjuntos de dados. O uso de extends requer que todas as instâncias do conceito sejam instâncias válidas do conceito que você está estendendo. As extensões permitem adicionar propriedades e atributos adicionais e restringir 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 references de conceito. Em particular, o conceito de estado tem uma propriedade chamada country, que faz referência ao conceito de país que criamos acima. Isso é feito usando um atributo concept. Essa propriedade não fornece um ID, apenas uma referência de conceito. Isso equivale 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 por um atributo isParent="true" na referência. Em geral, as dimensões com relações hierárquicas, como geografias, precisam ser representadas desta 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 para os 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 no 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, como description) não têm colunas. Tudo bem: se uma propriedade for omitida de uma tabela de definição de conceitos, seu valor será considerado 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 ano, podemos reutilizá-los para definir uma nova fração para a população dos 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 é semelhante a esta:

<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 ficará assim:

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

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

Uma fração com dimensões para estado e país não estaria correta, porque algumas linhas servem para dados do país e outras para dados do estado. A tabela teria "buracos" em algumas dimensões, o que não é permitido. Valores ausentes são permitidos somente para métricas, e não dimensões.

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

Como adicionar uma métrica: taxa de desemprego

Agora, vamos adicionar outra métrica ao nosso 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 à Secretaria de Estatísticas Trabalhistas dos EUA).

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

Atributos de conceito

Esse conceito também introduz a construção de um atributo. Neste exemplo, um atributo é usado para dizer que unemployment_rate é uma porcentagem. O atributo is_percentage é herdado do conceito quantity:rate que esse conceito estende. Essas informações são usadas pelo Public Data Explorer para mostrar sinais de porcentagem ao visualizar os dados.

Os atributos oferecem um mecanismo geral para anexar pares de chave-valor a um conceito, em contraste com as propriedades, que associam outros valores a instâncias de um conceito. Assim como os conceitos e as propriedades, os atributos têm id, info e type. Assim como as propriedades, elas podem fazer referência a outros conceitos.

Os atributos não servem apenas para coisas gerais predefinidas, como propriedades numéricas. Você pode definir seus próprios atributos para os conceitos.

Como adicionar dados de taxa de desemprego para estados dos EUA

Agora estamos prontos para adicionar dados de taxa de desemprego para estados dos EUA. Como a taxa de desemprego é uma métrica e já temos dados populacionais para os estados, basta adicioná-los à fração que já criamos para as dimensões "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 adicione 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 ao 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

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

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 nos países. A essa altura, você já está começando a entender o procedimento... 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 info do conceito de gênero 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, você precisa fornecê-los para conceitos que podem ser usados como dimensões.

O conceito de gênero também está se estendendo de entity:entity. Essa é uma boa prática 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 de gênero e os nomes de exibição deles (omitidos aqui).

Para adicionar população por gênero ao nosso conjunto de dados, precisamos criar uma nova fração (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 fração é semelhante a:

<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 países, população e parcela de desemprego anteriores, este tem uma dimensão adicional. Cada valor da métrica de população corresponde não apenas a um país e ano específicos, mas também a um determinado gênero.

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

Tópicos

O último recurso do DSPL que usaremos no conjunto de dados são os topics. Os tópicos são usados para classificar conceitos hierarquicamente e por aplicativos para ajudar os usuários a navegar até os 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 tópicos o mais profundamente necessário.

Para usar tópicos, você só precisa referenciá-los a partir da 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 tópico.

Como enviar seu conjunto de dados

Agora que você criou o 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ê tiver problemas, consulte as Perguntas frequentes, que incluem uma discussão sobre os problemas de envio mais comuns.

Para referência, você também pode fazer o download do arquivo XML completo e do pacote completo do conjunto de dados associado a este tutorial.

O que fazer depois

Parabéns por criar seu primeiro conjunto de dados DSPL! Agora que você entende os conceitos básicos, recomendamos a leitura do guia para desenvolvedores, que, entre outras coisas, documenta recursos "avançados" de DSPL, como a compatibilidade com vários idiomas e conceitos mapeáveis.

Você também pode ver mais alguns conjuntos de dados de exemplo.