DSPL Gen es una utilidad de línea de comandos que ayuda a convertir una tabla de datos CSV en un conjunto de datos de DSL simple. La herramienta analiza el archivo de entrada, crea todas las tablas de datos necesarias y dispone un archivo XML de DSPL. El resultado es una “plantilla” de conjunto de datos casi completa que solo requiere una optimización menor antes de subirse y visualizarse.
La suposición fundamental detrás de la generación de DSPL es que cada columna en el archivo CSV de entrada corresponde a un solo concepto de DSPL y cada fila es una observación única para una combinación de dimensiones. La herramienta funciona mediante la iteración a través de las columnas, el establecimiento de los metadatos adecuados para cada columna o concepto (p.ej., su ID, tipo, si es una dimensión o una métrica, etc.) y, luego, genera todas las definiciones de concepto y las tablas de segmentos necesarias.
Ejecutar la generación de DSPL
Sintaxis
Nota: En estas instrucciones, se da por sentado que ya seguiste las instrucciones de instalación proporcionadas en la página de herramientas de DSPL.
Para ejecutar DSPL de generación, dirígete a la terminal o solicitud en tu sistema y escribe lo siguiente:
python dsplgen.py -o [output path] [path to CSV file]
donde los términos entre corchetes se reemplazan de la siguiente manera:
[output path]: Es la ruta de acceso al directorio en el que deseas que se coloquen los archivos de salida. Este directorio ya debe existir en el sistema de archivos.[path to CSV file]: Ruta de acceso al archivo CSV de entrada. Consulta la siguiente sección para obtener más detalles sobre cómo dar formato a este archivo.
El componente -o [output path] es opcional; si se omite, los archivos de salida se colocarán en el directorio actual.
Luego, la herramienta se ejecuta a través de la iteración de tu archivo CSV, extrae definiciones de conceptos y genera tablas de segmentos. A menos que se encuentren errores, se escriben un archivo XML y uno o más archivos CSV en el directorio de salida.
Por último, abre el archivo XML en el editor de texto que prefieras y realiza los cambios que quieras. Como mínimo, debes completar los nombres, las descripciones y otros valores que la herramienta haya marcado con la notación ** INSERT ... **.
Ejemplo simple
Supongamos que tenemos un archivo CSV que muestra la cantidad total de casos por enfermedad, desglosados por mes, país y edad. Para simplificar, supongamos que hay 2 valores de cada dimensión:
date,country,age_group,disease_cases 01/2000,US,old,102030 01/2000,MX,old,192939 01/2000,US,young,23131 01/2000,MX,young,12311 02/2000,US,old,143135 02/2000,MX,old,203131 02/2000,US,young,22990 02/2000,MX,young,12591
Cuando se ejecuta la herramienta en la entrada anterior, se producen 4 archivos:
dataset.xml: Es la plantilla XML de DSPL.country_table.csv: Valores del conceptocountryage_group_table.csv: Valores del conceptoage_groupslice_0_table.csv: Tabla de fragmento de conjunto de datos (idéntica a la tabla de entrada, excepto la clasificación).
En este caso particular, la herramienta puede adivinar correctamente todos los tipos y formatos de columnas. Por lo tanto, lo único que queda por hacer es ir al archivo XML y editar los distintos nombres, descripciones y URL en los metadatos del conjunto de datos.
Anotar tu CSV de entrada
Opciones básicas
En muchos casos, como en el ejemplo anterior, la generación de DSPL puede adivinar los metadatos básicos para cada columna, p.ej., el tipo, el formato y si es una dimensión o una métrica. Sin embargo, en otros casos, es posible que la herramienta no pueda adivinarlos, es posible que adivine de forma incorrecta o que adivine correctamente, pero aun así no seguir el comportamiento deseado.
Para manejar estos casos, la herramienta admite la adición de opciones de generación de DSPL o "sugerencias" en la fila del encabezado CSV. La sintaxis de estos elementos es la siguiente:
column1[option1=value1;option2=value2;...],column2[option1=value1;option2=value2;...],column3[...],...
En particular, ten en cuenta que la lista de opciones se coloca dentro de corchetes a la derecha del nombre de la columna y que la configuración de opción sucesiva se separa con puntos y medio. Cada opción consta de un nombre, un signo igual y un valor de opción.
Por el momento, DSPL Gen admite las siguientes opciones básicas:
| Opción | Descripción | Predeterminado |
|---|---|---|
type |
El tipo de datos DSPL para esta columna; debe ser date, float, integer o string. |
Adivinado a partir de datos |
format |
El formato de esta columna de fechas; al igual que en DSPL, este formato se debe codificar mediante el uso del estándar de fecha y hora de Joda. | Adivinado a partir de datos |
slice_role |
La función de esta columna en cualquier porción. Debe ser dimension o metric. |
dimension si la columna es de tipo date o string; de lo contrario, metric |
concept |
El concepto canónico que representa esta columna, p.ej., geo:country; si se proporciona, se importa el concepto y no se produce ninguna definición en el archivo en formato XML. |
Ninguna |
extends |
El concepto canónico que extiende esta columna, p.ej., entity:entity. |
Ninguna |
parent |
El concepto superior para esta columna. Este superior debe ser un concepto de dimensión definido dentro del conjunto de datos (es decir, no importado). Si se proporciona, se usará esta información para definir una jerarquía de conceptos en el conjunto de datos. Ten en cuenta que cada instancia secundaria solo puede tener una superior. Si se detectan varios valores superiores, la herramienta producirá un error. |
Ninguna |
Resúmenes de valor
Además de las opciones básicas de “sugerencia” que se describieron arriba, la generación de DSL también admite segmentos roll-up: con una entrada de tabla única, la herramienta puede crear de forma automática tablas adicionales con subconjuntos limitados de dimensiones. Por ejemplo, si tu tabla de entrada corresponde a una porción con tres dimensiones sin tiempo (p.ej., dimension1, dimension2 y dimensions3), la herramienta también puede crear porciones adicionales: solo dimension1, solo dimension2, solo dimension1 y
dimension2, etcétera.
Agregar estas secciones adicionales puede facilitar la exploración de tu conjunto de datos, ya que reduce la cantidad de filtros de dimensiones necesarios para generar visualizaciones. Por otro lado, este proceso puede ingresar datos “nuevos” que no se encuentran en el archivo original, por lo que también puede generar errores si no se usan de forma correcta. Revisa con cuidado los números integrados antes de publicar el conjunto de datos.
El proceso de lista completa se activa mediante la inclusión de algunas opciones adicionales en el encabezado CSV de entrada:
| Opción | Descripción | Predeterminado |
|---|---|---|
aggregation |
El método de agregación que se usa cuando se combinan varios valores de esta columna; debe ser AVG, COUNT, MAX, MIN o SUM; solo es significativo para las métricas. |
SUM |
rollup |
Si el valor es true, el concepto de esta columna es "completado" (es decir, agregado de manera remota). Solo es significativo para los conceptos de dimensión. |
Falso |
total_val |
El valor en esta columna que indica que hay filas que se conservarán cuando se pliegue esta columna. Solo es relevante para los conceptos de dimensión. | None |
Luego, la DSPL genera el cálculo con el siguiente algoritmo:
- Con los valores de las etiquetas
rollup, calcula todas las combinaciones de columnas posibles - Para cada combinación, haga lo siguiente:
- Si alguna de las columnas agrupadas tiene un parámetro
total_valestablecido, filtra las filas por este valor; de lo contrario, selecciona todas las filas. - Descartar las columnas agrupadas
- Agrupe las filas por los valores de las columnas de dimensiones restantes.
- Agrega cada métrica mediante el método especificado en su parámetro
aggregation - Crea una porción y una tabla asociada para el resultado
- Si alguna de las columnas agrupadas tiene un parámetro
Ten en cuenta que, si hay un solo valor en cada agrupación y que la función de agregación se establece en SUM (el valor predeterminado), los valores de las métricas en las tablas de origen y generados serán los mismos, es decir, no se generarán valores nuevos. Por lo tanto, si usas el parámetro total_val y te aseguras de que solo haya una fila "total" para cada combinación de las otras dimensiones, podrás almacenar los agregados que se calcularon de forma previa directamente en la fuente.
Advertencia: La cantidad de secciones generadas es igual a 2 columnas agrupadas. Aplicar esta opción a una gran cantidad de columnas puede generar tiempos de ejecución muy largos o conjuntos de datos grandes.
Ejemplo avanzado
Supongamos que tenemos los mismos datos de entrada que en el ejemplo anterior, pero ahora incluimos agregados en todos los países:
date,country,age_group,disease_cases 01/2000,US,old,102030 01/2000,MX,old,192939 01/2000,total,old,152012 01/2000,US,young,23131 01/2000,MX,young,12311 01/2000,total,young,241011 02/2000,US,old,143135 02/2000,MX,old,203131 02/2000,total,old,211310 02/2000,US,young,22990 02/2000,MX,young,12591 02/2000,total,young,240131
Es posible que el total de cada edad no coincida con la suma de los valores de país porque, por ejemplo, hay diferencias en la metodología o la existencia de otros países que no se enumeran en la lista.
Ahora queremos crear un conjunto de datos de DSPL que tenga las siguientes características adicionales:
- Agrupa los países para obtener el total de casos de enfermedades por grupo etario.
- Usa el concepto canónico
geo:countrypara la columnacountrya fin de que podamos obtener automáticamente los nombres completos, las ubicaciones, etcétera. - Haz que el concepto
disease_casesextiendaquantity:amountpara que podamos agregar información de la unidad (de forma manual) en el archivo en formato XML.
Para ello, modificamos la fila del encabezado del CSV de entrada de la siguiente manera:
date,country[concept=geo:country;rollup=true;total_val=total],age_group,disease_cases[extends=quantity:amount]
Cuando vuelvas a ejecutar la herramienta, obtendremos una tabla de segmentos adicional, que elimina la distinción por país:
date,age_group,disease_cases 01/2000,old,152012 02/2000,old,211310 01/2000,young,241011 02/2000,young,240131
Ten en cuenta que, si no hubiéramos incluido los valores totales y la etiqueta total_val en la tabla de origen, habríamos obtenido la suma calculada para cada grupo etario.
Además, la definición de disease_cases en el archivo XML ahora incluye la extensión de quantity:amount, como se desea. La definición de country se descarta del archivo en formato XML porque, en su lugar, usamos un concepto importado.
Después de completar la información de unidades, nombres y descripciones, podemos comprimir el paquete de conjuntos de datos y subirlo al Explorador de datos públicos para su visualización.