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, в котором указано общее количество случаев заболевания с разбивкой по месяцам, странам и возрастным группам. Для простоты предположим, что есть 2 значения каждого измерения:
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 и гарантируя наличие только одной «итоговой» строки для каждой комбинации других измерений, вы можете хранить предварительно вычисленные агрегаты непосредственно в источнике.
Внимание! Количество сгенерированных фрагментов равно 2 свернутым столбцам . Применение этого параметра к большому количеству столбцов может привести к очень длительному времени выполнения и/или большим наборам данных.
Расширенный пример
Предположим, что у нас есть те же входные данные, что и в предыдущем примере, но теперь они включают агрегаты по странам:
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_casesрасширяющейquantity: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-файла, потому что вместо этого мы используем импортированное понятие.
После заполнения различных имен, описаний и информации о единицах измерения мы можем заархивировать пакет набора данных и загрузить его в обозреватель общедоступных данных для визуализации.