Manual de DSPL

Este documento contém um manual de DSPL útil e um conceito canônico "receitas". Elas oferecem instruções passo a passo para várias tarefas que vão além dos recursos básicos descritos no Tutorial e no guia para desenvolvedores. O conteúdo abaixo pressupõe conhecimento dos documentos anteriores. Por isso, leia-os antes de começar a "cozinhar".

Cada receita começa com uma meta seguida por uma lista específica de etapas a serem seguidas. Muitos também incluem snippets de DSPL ou links para exemplos externos. Se você tiver algum feedback sobre uma receita ou quiser sugerir outras sugestões, poste uma mensagem no Fórum do DSPL.

Receitas básicas

Como especificar nomes de exibição

Meta

Associe um "nome de exibição" a cada instância de um conceito (dimensão). Esses nomes serão exibidos na IU do Explorador de dados públicos em vez dos IDs de instância conceitual, que geralmente são mais curtos e difíceis de entender.

Passos

  1. Amplie seu conceito entity:entity.
  2. Adicione uma coluna name à tabela de definição de conceito associada.
  3. Preencha a última propriedade com o nome de cada instância.

Observações

  • Não é necessário definir explicitamente uma propriedade name nos metadados do conceito. Essa definição é incluída automaticamente quando você estende o entity:entity.
  • Também é possível adicionar as colunas description e info_url, para fornecer descrições e URLs no nível da instância, respectivamente.

Como criar hierarquias de conceitos

Meta

Crie uma hierarquia de conceitos (dimensão). Eles serão exibidos na IU do Buscador de dados públicos como uma árvore, permitindo que os usuários entendam os agrupamentos e naveguem entre eles.

Passos

  1. Definir um conceito "pai", por exemplo, region.
  2. Definir um conceito "filho" (por exemplo, subregion.
  3. Adicione uma propriedade no filho que faça referência ao pai e inclua o atributo isParent: 
    <property concept="..." isParent="true"/>
    em que os pontos são substituídos pelo ID pai.
  4. Na tabela de definição do filho, adicione uma coluna que faça referência ao pai.
  5. Para cada instância filha, preencha a última com uma instância válida do conceito pai.

Observações

  • Consulte a relação country / state no conjunto de dados do tutorial para ver um exemplo.
  • Cada ID pai referenciado pelo filho precisa estar na tabela de definição do pai. Caso contrário, o importador produzirá um erro.
  • O pai e o filho podem ter o mesmo conceito (ou seja, uma hierarquia de autorreferência). Consulte o conceito business no conjunto de dados de vendas do varejo dos EUA para ver um exemplo.

Categorizar instâncias de conceito

Meta

Crie categorias para instâncias de conceito que serão exibidas como opções nos seletores de cores do Public Data Explorer.

Passos

  1. Definir um conceito de "categoria" (por exemplo, income_level.
  2. Definir um conceito "filho" (por exemplo, country.
  3. Adicione uma propriedade no filho que faça referência ao conceito de categoria e inclua um elemento name: 
    <property concept="..."/>
  <info>
    <name><value>"..."</value></name>
  </info>
</property>
    em que o primeiro conjunto de pontos é substituído pelo ID do conceito de categoria e o segundo conjunto é substituído pelo nome de exibição desejado para sua propriedade (por exemplo, "Renda").
  4. Na tabela de definição do filho, adicione uma coluna que faça referência ao conceito da categoria.
  5. Para cada instância filha, preencha a última com uma instância válida do conceito da categoria.

Observações

  • Um conceito pode ter várias propriedades que servem como categorias. Nesse caso, o usuário verá todas elas como opções nos seletores de cores.
  • Uma das categorias também pode ser mãe para organizar as instâncias hierarquicamente na IU. Veja o roteiro anterior para saber mais detalhes.

Como especificar a ordem de classificação para instâncias de conceito

Meta

Especifique a ordem de classificação para instâncias de um conceito. Essa ordem é usada ao listar as instâncias no painel de navegação esquerdo das páginas de visualização do Explorador de dados públicos.

Passos

  1. Faça seu conceito estender entity:entity ou um dos filhos dele (por exemplo, geo:location).
  2. Adicione um atributo entity_order aos metadados do conceito.
  3. Defina o valor da anterior como ALPHA ou TABLE. Com o primeiro, as instâncias vão ser listadas na ordem dos nomes de exibição, enquanto as anteriores vão manter as instâncias na mesma ordem em que aparecem na tabela de definição do conceito.

Observações

  • ALPHA é o padrão atual. Portanto, se você quiser usar essa ordem, as etapas acima são opcionais.
  • Consulte a documentação do entity:entity para ver um exemplo.

Receitas por hora

Dados trimestrais

Meta

Exibe dados especificados em intervalos trimestrais.

Passos

  1. Converta todos os trimestres nos dados de parcelas em meses (por exemplo, o primeiro mês do trimestre).
  2. Trate essa dimensão como um time:month no XML das fatias.

Dados semanais

Meta

Exibe dados especificados em intervalos semanais.

Passos

  1. Converta todas as semanas em seus dados de parcelas em dias (por exemplo, o primeiro dia da semana).
  2. Trate essa dimensão como um time:day no XML das fatias.

Receitas geográficas

Uso de conceitos canônicos country ou state

Meta

Use os conceitos canônicos country ou state, importando todos os valores de latitude/longitude etc. para que eles não precisem ser definidos no conjunto de dados.

Passos

  1. Verifique se todas as referências de estado dos países e/ou dos EUA nos CSVs de dados da fatia são IDs válidos das tabelas de definições canônicas de país e estado.
  2. Adicione geo:country e/ou geo_us:state como dimensões nas frações correspondentes.
  3. Verifique se os nomes das colunas para eles correspondem aos nomes dos conceitos anteriores (não incluindo o nome do conjunto de dados importado, por exemplo, country) ou, caso contrário, inclua instruções mapDimension na definição da fatia. Exemplo: 
    <slice id="...">
  ...
  <dimension concept="geo:country"/>
  ...
  <mapDimension concept="geo:country" toColumn="my_country"/>
</slice>

Uso de apenas um subconjunto dos países ou estados canônicos

Meta

Use um subconjunto de um conceito geográfico canônico para que apenas esse subconjunto (e não a lista inteira, por exemplo, todos os países) apareça na IU do Buscador de dados públicos.

Passos

  1. Defina um conceito local que estenda o conceito do superconjunto. Exemplo: 
    <concept id="my_country_subset" extends="geo:country">
...
</concept>
  2. No CSV de definição de conceito associado, inclua apenas os IDs do conceito do superconjunto que você quer usar. Exemplo: 
    my_country_subset
FR  
MX
US

Observações

  • Cada instância do conceito do subconjunto precisa ser uma instância válida do conceito do superconjunto. Não é possível "expandir" o conceito com novas instâncias.

Definir seus próprios conceitos geográficos

Meta

Crie seus próprios conceitos geográficos que podem ser explorados e mapeados, como os canônicos e definidos pelo Google.

Passos

  1. Crie um conceito que estenda geo:location.
  2. Na tabela de definição de conceito associada, inclua as colunas name, latitude e longitude.
  3. Preencha as últimas propriedades de cada instância do seu conceito. Os valores de latitude e longitude são flutuantes com a convenção de que N e E são positivos e W e S são negativos.

Observações

  • Não é necessário incluir explicitamente as propriedades name, latitude e longitude na definição do conceito, já que elas são incluídas automaticamente ao estender geo:location.
  • Consulte a definição de state no conjunto de dados de tutorial para ver um exemplo.

Receitas de métrica e unidade

Como usar porcentagens

Meta

Defina um conceito (métrica) que seja uma porcentagem de outra coisa.

Passos

  1. Faça seu conceito estender quantity:ratio.
  2. Defina o atributo is_percentage como true. 
    <attribute id="is_percentage">
  <value>true</value>
</attribute>
  3. Outra opção é definir o atributo percentage_of com base no qual esse conceito é uma porcentagem. Exemplo: 
    <attribute id="percentage_of">
  <value>labor force</value>
</attribute>

Usando currency unidades

Meta

Defina um conceito (métrico) com unidades monetárias (por exemplo, dólar americano).

Passos

  1. Faça com que sua métrica estenda quantity:quantity ou um dos filhos dela, por exemplo, quantity:amount.
  2. Adicione um atributo unit que faça referência a unit:currency e defina o valor dele como um ID da tabela de definição de moeda associada. Exemplo: 
    <concept id="...">
  <attribute concept="unit:currency">
    <value>EUR</value>
  </attribute>
</concept>

Criar uma unidade personalizada

Meta

Crie uma unidade personalizada para uma ou mais das suas métricas.

Passos

  1. Crie um conceito que estenda unit:unit.
  2. Adicione as colunas unit_text e symbol à tabela de definição associada. Opcionalmente, se você quiser ajustar a posição do símbolo, adicione também uma coluna symbol_position.
  3. Preencha os valores das últimas propriedades de cada instância da sua unidade. Exemplo de CSV para unidades "área". 
    my_unit,unit_text,symbol,symbol_position
SQKM,square kilometers,km²,END
SQML,square miles,miles²,END
  4. Para usar sua unidade recém-criada em um conceito (métrico), verifique se o último estende quantity:quantity ou um dos filhos dele. Em seguida, adicione um atributo que faça referência ao conceito da unidade. Exemplo: 
    <concept id="..." extends="quantity:amount">
  ...
  <attribute concept="my_unit">
    <value>SQKM</value>
  </attribute>
  ...
</concept>

Observações

  • Se o conceito de unidade tiver apenas uma instância, será possível omitir a coluna "ID" da tabela de definições e as tags value nas métricas que a utilizam.
  • Consulte a definição do conceito de moeda canônica para ver um exemplo completo.