Manual de DSPL

Este documento contém um manual de DSPL útil e de conceitos canônicos "receitas". Elas fornecem instruções passo a passo para vários tarefas que vão além dos recursos básicos de linguagem descritos no Tutorial e Guia para desenvolvedores. O conteúdo requer conhecimento dos documentos anteriores, então não deixe de ler antes de começar a cozinhar.

Cada roteiro começa com um objetivo seguido por uma lista específica de etapas para seguir. Muitos também incluem snippets DSPL ou links para exemplos externos. Se você tiver algum feedback sobre uma receita ou gostaria de sugerir outras, poste uma mensagem no Fórum DSPL (em inglês).

Receitas básicas

Como especificar nomes de exibição

Meta

Associar um "nome de exibição" com cada instância de uma dimensão conceito. Esses nomes aparecerão na interface do Explorador de dados públicos em vez de IDs de instância de conceito, que geralmente são mais curtos e mais difíceis para os usuários entender.

Etapas

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

Observações

  • Não é necessário definir explicitamente uma propriedade name na os metadados do conceito, essa definição é incluída automaticamente quando você estendem entity:entity.
  • Você também pode adicionar description e info_url para fornecer descrições e URLs no nível da instância, respectivamente.

Como criar hierarquias de conceito

Meta

Criar uma hierarquia de conceitos (dimensão). Eles vão aparecer Interface do Explorador de dados públicos como uma árvore, permitindo que os usuários entendam os agrupamentos e navegar entre eles.

Etapas

  1. Definir um "pai" conceito (por exemplo, region).
  2. Defina um "filho" conceito (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 filho, preencha a última com uma instância válida do conceito pai.

Observações

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

Como categorizar instâncias de conceito

Meta

Criar categorias para instâncias de conceito que serão exibidas como opções nos seletores de cores do Explorador de dados públicos.

Etapas

  1. Defina uma "categoria" conceito (por exemplo, income_level).
  2. Defina um "filho" conceito (por exemplo, country).
  3. Adicione uma propriedade no filho que faça referência ao conceito da categoria e inclui 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 da categoria e pelo o segundo conjunto é substituído pelo nome de exibição desejado para sua propriedade (por exemplo, "Nível de renda").
  4. Na tabela de definição do filho, adicione uma coluna que faça referência ao de categoria.
  5. Para cada instância filho, preencha a última com uma instância válida do o conceito de categoria.

Observações

  • Um conceito pode ter várias propriedades que servem como categorias. neste caso, o usuário verá todas elas como opções nos seletores de cores.
  • Uma das categorias também pode ser mãe para fins de organizar as instâncias hierarquicamente na IU. Consulte a anterior para 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 quando listando as instâncias na barra de navegação esquerda do Public Data Explorer de visualização de dados.

Etapas

  1. Faça seu conceito estender entity:entity ou um dos próprios filhos (por exemplo, geo:location).
  2. Adicione um atributo entity_order aos metadados do conceito.
  3. Defina o valor do anterior como ALPHA ou TABLE a primeira fará com que as instâncias sejam listadas ordem dos nomes de exibição, enquanto o último mantém as instâncias na mesma ordem em que aparecem na tabela de definição de conceitos.

Observações

  • ALPHA é o padrão atual, então, se você quiser usá-lo ordem, as etapas acima são opcionais.
  • Consulte a entity:entity documentação para ver um exemplo.

Receitas de Tempo

Dados trimestrais

Meta

Conferir dados especificados em intervalos trimestrais.

Etapas

  1. Converta todos os trimestres dos seus dados de fração em meses (por exemplo, o primeiro mês do trimestre).
  2. Trate essa dimensão como um time:month na sua fatia XML

Dados semanais

Meta

Conferir dados especificados em intervalos semanais.

Etapas

  1. Converter todas as semanas dos dados de fração em dias (por exemplo, a primeira dia da semana).
  2. Trate essa dimensão como um time:day no XML da fração.

Receitas geográficas

Como usar country ou state conceitos canônicos

Meta

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

Etapas

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

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

Meta

Use um subconjunto de um conceito geográfico canônico para que somente esse subconjunto (e não a lista inteira, por exemplo, todos os países do mundo) aparece na Comunidade Interface do Data Explorer.

Etapas

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

Observações

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

Como definir seus próprios conceitos geográficos

Meta

Crie seus próprios conceitos geográficos que são exploráveis e mapeáveis, apenas como as canônicas, definidas pelo Google.

Etapas

  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 para cada instância do seu conceito. as 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 name, latitude e longitude na sua definição de conceito, já que são incluídos automaticamente ao estender geo:location.
  • Veja a definição de state no conjunto de dados do tutorial para um exemplo.

Roteiros de métricas e unidades

Como usar porcentagens

Meta

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

Etapas

  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. Também é possível definir o atributo percentage_of com base em que esse conceito é uma porcentagem. Exemplo: 
    <attribute id="percentage_of">
  <value>labor force</value>
</attribute>

Usando unidades de currency

Meta

Defina um conceito (métrica) que tenha unidades monetárias (por exemplo, dólares americanos).

Etapas

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

Como criar uma unidade personalizada

Meta

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

Etapas

  1. Crie um conceito que estenda unit:unit.
  2. Adicione as colunas unit_text e symbol ao tabela de definições associada. Se quiser ajustar na posição do símbolo symbol_position, .
  3. Preencha os valores das últimas propriedades para cada instância do unidade. Exemplo de CSV para "área" unidades: 
    my_unit,unit_text,symbol,symbol_position
SQKM,square kilometers,km²,END
SQML,square miles,miles²,END
  4. Para usar o bloco recém-criado em um conceito (métrica), verifique se último estende quantity:quantity ou um dos filhos dele. Depois, adicione um atributo que faça referência ao conceito de 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, você poderá omitir o ID coluna da tabela de definição, bem como as tags value na as métricas que o utilizam.
  • Veja a definição da moeda canônica conceitual para um exemplo completo.