Guía de soluciones de DSPL

Este documento contiene una guía de referencia sobre la DSPL y el concepto canónico "recetas". Estas proporcionan instrucciones paso a paso para una variedad de tareas que van más allá de las funciones básicas de lenguaje que se describen en el instructivo y la Guía para desarrolladores. En el siguiente contenido, se asume que ya conoces los documentos anteriores, así que asegúrate de leerlos antes de comenzar tu "cocina".

Cada receta comienza con un objetivo seguido de una lista específica de pasos que seguir. En muchos de ellos, también se incluyen fragmentos de la DSPL o vínculos a ejemplos externos. Si tienes comentarios sobre una receta o deseas sugerir otros, publica un mensaje en el foro de DSPL.

Recetas básicas

Especifica nombres visibles

Objetivo

Asocia un “nombre visible” con cada instancia de un concepto (dimensión). Estos nombres aparecerán en la IU de Public Data Explorer en lugar de los ID de instancia de concepto, que suelen ser más cortos y difíciles de entender para los usuarios.

Pasos

  1. Haz que tu concepto extienda entity:entity.
  2. Agrega una columna name a la tabla de definición de conceptos asociada.
  3. Propaga la última propiedad con el nombre de cada instancia.

Notas

  • No es necesario definir de forma explícita una propiedad name en los metadatos de tu concepto. Esta definición se incluye automáticamente cuando extiendes entity:entity.
  • También puedes agregar las columnas description y info_url para proporcionar URL y descripciones a nivel de la instancia, respectivamente.

Crea jerarquías de conceptos

Objetivo

Crea una jerarquía de conceptos (dimensión). Estas aparecerán en la IU del Explorador de datos públicos como un árbol, lo que permitirá a los usuarios comprender las agrupaciones y navegar entre ellas.

Pasos

  1. Definir un concepto "superior" (p.ej., region).
  2. Definir un concepto "secundario" (p.ej., subregion).
  3. Agrega una propiedad en el elemento secundario que haga referencia al elemento superior y que incluya el atributo isParent: 
    <property concept="..." isParent="true"/>
    , en el que el ID superior reemplaza los puntos.
  4. En la tabla de definición para el elemento secundario, agrega una columna que haga referencia al elemento superior.
  5. Para cada instancia secundaria, propaga esta última con una instancia válida del concepto superior.

Notas

  • Consulta la relación country / state en el conjunto de datos del instructivo para ver un ejemplo de esto.
  • Cada ID superior al que se hace referencia desde el elemento secundario debe estar en la tabla de definición superior. De lo contrario, el importador producirá un error.
  • El elemento principal y el secundario pueden ser el mismo concepto (es decir, una jerarquía de autorreferencia). Consulta el concepto de business en el conjunto de datos de ventas minoristas de EE.UU. para ver un ejemplo de esto.

Categorizar instancias de conceptos

Objetivo

Crea categorías para las instancias de conceptos que aparecerán como opciones en los selectores de color de Public Data Explorer.

Pasos

  1. Defina un concepto de "categoría" (p.ej., income_level).
  2. Definir un concepto "secundario" (p.ej., country).
  3. Agrega una propiedad en el elemento secundario que haga referencia al concepto de categoría y que incluya un elemento name: 
    <property concept="..."/>
  <info>
    <name><value>"..."</value></name>
  </info>
</property>
    en el que el primer conjunto de puntos se reemplaza por el ID de concepto de categoría y el segundo conjunto por el nombre visible deseado para tu propiedad (p.ej., "Nivel de ingresos").
  4. En la tabla de definición para el elemento secundario, agrega una columna que haga referencia al concepto de categoría.
  5. Para cada instancia secundaria, propaga esta última con una instancia válida del concepto de categoría.

Notas

  • Un concepto puede tener varias propiedades que sirven como categorías; en este caso, el usuario las verá todas como opciones en los selectores de color.
  • Una de las categorías también puede ser un superior para organizar las instancias de manera jerárquica en la IU. Consulta la receta anterior para obtener más información.

Especifica el orden de clasificación para las instancias de conceptos

Objetivo

Especifica el orden de clasificación para las instancias de un concepto. Este orden se usa cuando se enumeran las instancias en el panel de navegación izquierdo de las páginas de visualización de Public Data Explorer.

Pasos

  1. Haz que tu concepto extienda entity:entity o uno de sus elementos secundarios (p.ej., geo:location).
  2. Agrega un atributo entity_order a los metadatos de tu concepto.
  3. Establece el valor del anterior en uno de ALPHA o TABLE; el primero hará que las instancias se ordenen por orden de nombre visible, mientras que el último mantendrá las instancias en el mismo orden en el que aparecen en la tabla de definición de conceptos.

Notas

  • ALPHA es el valor predeterminado actual, por lo que, si deseas usar este orden, los pasos anteriores son opcionales.
  • Consulta la documentación de entity:entity para ver un ejemplo.

Recetas de la hora

Datos trimestrales

Objetivo

Visualiza los datos que se especifican en intervalos trimestrales.

Pasos

  1. Convierte todos los trimestres en los datos de tu porción en meses (p.ej., el primer mes del trimestre).
  2. Trata esta dimensión como una time:month en la porción XML.

Datos semanales

Objetivo

Visualiza los datos que se especifican en intervalos semanales.

Pasos

  1. Convierte todas las semanas en tus datos de segmentos en días (p.ej., el primer día de la semana).
  2. Trata esta dimensión como una time:day en la porción XML.

Recetas geográficas

Uso de conceptos canónicos country o state

Objetivo

Usa los conceptos country o state canónicos. Para ello, importa todos los valores de latitud y longitud, etc., a fin de que no necesiten definirse dentro del conjunto de datos.

Pasos

  1. Asegúrate de que todas las referencias a los estados de EE.UU. o país de los CSV de datos de fragmentos sean ID válidos de las tablas de definición canónicas de country y state.
  2. Agrega geo:country o geo_us:state como dimensiones en las porciones correspondientes.
  3. Asegúrate de que los nombres de las columnas coincidan con los nombres de los conceptos anteriores (sin incluir el nombre del conjunto de datos importado, p.ej., country) o, si no lo es, incluye las declaraciones mapDimension en la definición de la porción. Ejemplo: 
    <slice id="...">
  ...
  <dimension concept="geo:country"/>
  ...
  <mapDimension concept="geo:country" toColumn="my_country"/>
</slice>

Usar solo un subconjunto de los países o estados canónicos

Objetivo

Usa un subconjunto de un concepto de ubicación geográfica canónica, de manera que solo este subconjunto (y no toda la lista, p.ej., todos los países del mundo) aparezca en la IU del Explorador de datos públicos.

Pasos

  1. Define un concepto local que extienda el concepto de superconjunto. Ejemplo: 
    <concept id="my_country_subset" extends="geo:country">
...
</concept>
  2. En el CSV de definición de conceptos asociados, solo incluye los ID del concepto de superconjunto que deseas usar. Ejemplo: 
    my_country_subset
FR  
MX
US

Notas

  • Cada instancia de tu concepto de subconjunto debe ser una instancia válida del concepto de superconjunto; no puedes “expandir” el concepto con instancias nuevas.

Definir sus propios conceptos geográficos

Objetivo

Crea tus propios conceptos geográficos que sean explorables y mapeables, al igual que los canónicos y definidos por Google.

Pasos

  1. Crea un concepto que extienda geo:location.
  2. En la tabla de definición de conceptos asociados, incluye las columnas name, latitude y longitude.
  3. Propaga las últimas propiedades para cada instancia de tu concepto. Los valores de latitud y longitud son flotantes con la convención de que N y E son positivas, y W y S son negativos.

Notas

  • No es necesario incluir de manera explícita las propiedades name, latitude y longitude en tu definición de concepto, ya que se incluyen de manera automática cuando se extiende geo:location.
  • Consulta la definición de state en el conjunto de datos del instructivo para ver un ejemplo.

Recetas de métricas y unidades

Uso de porcentajes

Objetivo

Define un concepto (métrico) que sea un porcentaje de otra cosa.

Pasos

  1. Haz que tu concepto extienda quantity:ratio.
  2. Establece el atributo is_percentage en true. 
    <attribute id="is_percentage">
  <value>true</value>
</attribute>
  3. De manera opcional, establece el atributo percentage_of según el porcentaje de este concepto. Ejemplo: 
    <attribute id="percentage_of">
  <value>labor force</value>
</attribute>

Con unidades de currency

Objetivo

Definir un concepto (métrico) que tenga unidades monetarias (p.ej., dólares estadounidenses.

Pasos

  1. Haz que tu métrica extienda quantity:quantity o uno de sus elementos secundarios, p.ej., quantity:amount.
  2. Agrega un atributo unit que haga referencia a unit:currency y establece su valor como un ID de la tabla de definición de monedas asociada. Ejemplo: 
    <concept id="...">
  <attribute concept="unit:currency">
    <value>EUR</value>
  </attribute>
</concept>

Cómo crear una unidad personalizada

Objetivo

Crea una unidad personalizada para una o más de tus métricas.

Pasos

  1. Crea un concepto que extienda unit:unit.
  2. Agrega las columnas unit_text y symbol a la tabla de definición asociada. De manera opcional, si deseas ajustar la posición del símbolo, también puedes agregar una columna symbol_position.
  3. Completa los valores de las últimas propiedades de cada instancia de la unidad. CSV de ejemplo de unidades de “área”: 
    my_unit,unit_text,symbol,symbol_position
SQKM,square kilometers,km²,END
SQML,square miles,miles²,END
  4. Para usar la unidad recién creada en un concepto (métrica), asegúrate de que la última extienda quantity:quantity o uno de sus elementos secundarios. Luego, agrega un atributo que haga referencia al concepto de tu unidad. Ejemplo: 
    <concept id="..." extends="quantity:amount">
  ...
  <attribute concept="my_unit">
    <value>SQKM</value>
  </attribute>
  ...
</concept>

Notas

  • Si el concepto de tu unidad solo tiene una instancia, puedes omitir la columna de ID de su tabla de definición y las etiquetas value en las métricas que la usan.
  • Consulta la definición del concepto de moneda canónica para obtener un ejemplo completo.