DSPL Gen — это утилита командной строки, которая помогает преобразовать таблицу данных CSV в простой набор данных DSPL. Инструмент анализирует входной файл, создает все необходимые таблицы данных и размещает XML-файл DSPL. В результате получается почти полный «шаблон» набора данных, который требует лишь незначительной доработки перед загрузкой и визуализацией.
Фундаментальное предположение, лежащее в основе DSPL Gen, заключается в том, что каждый столбец во входном файле CSV соответствует одной концепции DSPL , а каждая строка представляет собой одно наблюдение для комбинации измерений. Инструмент работает, перебирая столбцы, устанавливая соответствующие метаданные для каждого столбца/концепции (например, его идентификатор, тип, является ли это измерением или метрикой и т. д.), а затем генерирует все необходимые определения концепций и таблицы срезов. .
Запуск генератора DSPL
Синтаксис
Примечание. Эти инструкции предполагают, что вы уже выполнили инструкции по установке , приведенные на странице «Инструменты DSPL».
Чтобы запустить DSPL Gen, перейдите в терминал/подсказку вашей системы и введите:
python dsplgen.py -o [output path] [path to CSV file]
где члены в квадратных скобках заменены следующим образом:
-
[output path]: путь к каталогу, в котором вы хотите разместить выходные файлы; этот каталог уже должен существовать в вашей файловой системе. -
[path to CSV file]: путь к входному файлу CSV. Дополнительные сведения о форматировании этого файла см. в разделе ниже.
Компонент -o [output path] не является обязательным; если этот параметр опущен, выходные файлы будут помещены в текущий каталог.
Затем инструмент запускается, просматривая ваш CSV-файл, извлекая определения понятий и создавая таблицы срезов. Если не обнаружены какие-либо ошибки, файл XML и один или несколько файлов CSV записываются в выходной каталог.
Наконец, откройте XML-файл в текстовом редакторе по вашему выбору и внесите необходимые изменения. Как минимум, вы должны заполнить имена, описания и другие значения, помеченные инструментом с помощью нотации ** INSERT ... ** .
Простой пример
Предположим, что у нас есть CSV, в котором указано общее количество случаев заболевания с разбивкой по месяцам, странам и возрастным группам. Для простоты предположим, что существует два значения каждого измерения:
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
Запуск инструмента на приведенных выше входных данных создает 4 файла:
-
dataset.xml: XML-шаблон DSPL. -
country_table.csv: значения концепцииcountry. -
age_group_table.csv: значения концепцииage_group -
slice_0_table.csv: Таблица для среза набора данных (идентична входной таблице, за исключением сортировки)
В этом конкретном случае инструмент способен правильно угадать все типы и форматы столбцов. Итак, все, что осталось сделать, — это зайти в XML-файл и отредактировать различные имена, описания и URL-адреса в метаданных набора данных.
Аннотирование входного CSV-файла
Основные параметры
Во многих случаях, как в приведенном выше примере, DSPL Gen может угадать основные метаданные для каждого столбца, например, тип, формат и то, является ли это измерением или показателем. Однако в других случаях инструмент может быть не в состоянии их угадать, угадать неправильно или угадать правильно, но, тем не менее, не следовать желаемому поведению.
Чтобы справиться с этими случаями, инструмент поддерживает добавление опций/"подсказок" генерации DSPL в строку заголовка CSV. Синтаксис для них следующий:
column1[option1=value1;option2=value2;...],column2[option1=value1;option2=value2;...],column3[...],...
В частности, обратите внимание, что список опций помещается в скобки справа от имени столбца, а последующие настройки опций разделяются точкой с запятой . Каждая опция состоит из имени опции, знака равенства и значения опции.
DSPL Gen в настоящее время поддерживает следующие основные опции:
| Вариант | Описание | По умолчанию |
|---|---|---|
type | Тип данных DSPL для этого столбца; должно быть одним из date , float , integer или string . | Предполагается по данным |
format | Формат этого столбца даты; как и в DSPL, этот формат должен быть закодирован с использованием стандарта Joda DateTime . | Предполагается по данным |
slice_role | Какова роль этого столбца в любых срезах; должен быть либо dimension , либо metric . | dimension , если столбец имеет тип date или string , в противном случае metric |
concept | Каноническое понятие, которое представляет этот столбец, например geo:country ; если задано, то концепция импортируется, а определение в XML-файле не создается. | Никто |
extends | Каноническая концепция, которую расширяет этот столбец, например, entity:entity . | Никто |
parent | Родительское понятие для этого столбца. Этот родительский элемент должен быть концепцией измерения, определенной внутри набора данных (т. е. не импортированной); если да, эта информация будет использоваться для определения иерархии понятий в наборе данных. Обратите внимание, что каждый дочерний экземпляр может иметь только одного родителя. Если обнаружено несколько родительских значений, инструмент выдаст ошибку. | Никто |
Сводные значения значений
В дополнение к базовым опциям «подсказки», описанным выше, DSPL Gen также поддерживает свертывание срезов: при наличии одной входной таблицы инструмент может автоматически создавать дополнительные таблицы с ограниченными подмножествами измерений. Так, например, если ваша входная таблица соответствует срезу с тремя невременными измерениями (например, dimension1 , dimension2 и dimensions3 ), инструмент также может создать несколько дополнительных срезов: просто dimension1 , только dimension2 , просто dimension1 и dimension2 , и т. д.
Добавление этих дополнительных срезов может облегчить изучение вашего набора данных, поскольку уменьшает количество фильтров измерений, необходимых для создания визуализаций. С другой стороны, этот процесс может привести к появлению «новых» данных, которых нет в исходном файле, поэтому при неправильном использовании он также может привести к ошибкам; внимательно проверьте сверенные цифры перед публикацией набора данных.
Процесс объединения запускается путем включения некоторых дополнительных параметров во входной заголовок CSV:
| Вариант | Описание | По умолчанию |
|---|---|---|
aggregation | Метод агрегирования, который будет использоваться при объединении нескольких значений этого столбца; должно быть одним из AVG , COUNT , MAX , MIN или SUM ; имеет смысл только для метрик . | SUM |
rollup | Если значение равно true , концепция этого столбца «сведена» (т. е. агрегирована); имеет смысл только для концепций измерений . | ЛОЖЬ |
total_val | Значение в этом столбце, указывающее строки, которые следует сохранить при свертывании этого столбца; имеет смысл только для концепций измерений . | None |
Затем DSPL Gen вычисляет свертки, используя следующий алгоритм:
- Используя значения тегов
rollup, вычислите все возможные комбинации столбцов. - Для каждой комбинации:
- Если какие-либо свернутые столбцы имеют набор параметров
total_val, отфильтруйте строки по этому значению; в противном случае выберите все строки
- Если какие-либо свернутые столбцы имеют набор параметров
- Отбросьте свернутые столбцы
- Сгруппируйте строки по значениям остальных столбцов измерения.
- Агрегируйте каждую метрику, используя метод, указанный в ее параметре
aggregation. - Создайте срез и связанную с ним таблицу для результата.
Обратите внимание: если в каждой группе имеется только одно значение и для функции агрегирования установлено значение SUM (значение по умолчанию), то значения показателей в исходной и созданной таблицах будут одинаковыми, т. е. новые значения не генерируются. Таким образом, использование параметра total_val и обеспечение наличия только одной строки «итого» для каждой комбинации других измерений позволяет хранить предварительно вычисленные агрегаты непосредственно в источнике.
Внимание: количество сгенерированных срезов равно двум свернутым столбцам . Применение этой опции к большому количеству столбцов может привести к очень длительному времени выполнения и/или большим наборам данных.
Расширенный пример
Предположим, что у нас есть те же входные данные, что и в предыдущем примере, но теперь включая агрегаты по странам:
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
Итоговое значение для каждой возрастной группы может не совпадать с суммой значений по странам из-за, например, различий в методологии или существования других стран, не перечисленных в списке.
Теперь мы хотим создать набор данных DSPL, который имеет следующие дополнительные функции:
- «Объедините» страны, чтобы получить общее количество случаев заболевания только по возрастным группам.
- Используйте каноническую концепцию
geo:countryдля столбцаcountry, чтобы мы могли автоматически получать полные имена, местоположения и т. д. для этих стран. - Расширьте концепцию
disease_casesquantity:amount, чтобы мы могли (вручную) добавлять информацию о единицах измерения в XML-файл.
Для этого мы модифицируем строку заголовка входного CSV следующим образом:
date,country[concept=geo:country;rollup=true;total_val=total],age_group,disease_cases[extends=quantity:amount]
Запустив инструмент еще раз, мы теперь получаем дополнительную таблицу срезов, которая устраняет различие по странам:
date,age_group,disease_cases 01/2000,old,152012 02/2000,old,211310 01/2000,young,241011 02/2000,young,240131
Обратите внимание: если бы мы не включили итоговые значения и тег total_val в исходную таблицу, мы бы получили рассчитанную сумму для каждой возрастной группы.
Кроме того, определение disease_cases в XML-файле теперь по желанию включает расширение quantity:amount . Определение country исключено из XML-файла, поскольку вместо этого мы используем импортированное понятие.
После заполнения различных имен, описаний и информации о единицах мы можем заархивировать пакет набора данных и загрузить его в Public Data Explorer для визуализации.