Поваренная книга DSPL

Этот документ содержит кулинарную книгу полезных DSPL и канонических понятий «рецепты». В них содержатся пошаговые инструкции для различных задач, которые выходят за рамки базовых функций языка, описанных в Учебнике и Руководстве разработчика . Содержимое ниже предполагает знание предыдущих документов, поэтому обязательно прочитайте их перед тем, как начать «готовку».

Каждый рецепт начинается с цели, за которой следует определенный список шагов, которым нужно следовать. Многие также включают фрагменты DSPL или ссылки на внешние примеры. Если у вас есть какие-либо отзывы о рецепте или вы хотите предложить другие, опубликуйте сообщение на форуме DSPL .

Основные рецепты

Указание отображаемых имен

Цель

Свяжите «отображаемое имя» с каждым экземпляром концепции (параметра). Эти имена будут отображаться в пользовательском интерфейсе Public Data Explorer вместо идентификаторов экземпляров концепций, которые обычно короче и сложнее для понимания пользователями.

Шаги

1. Сделайте так, чтобы ваша концепция расширяла entity:entity.
2. Добавьте столбец name в связанную таблицу определений понятий.
3. Заполните последнее свойство именем каждого экземпляра.

Ноты

• Нет необходимости явно определять свойство name в метаданных концепции; это определение автоматически включается при расширении entity:entity .
• Вы также можете добавить столбцы description и info_url , чтобы предоставить описания и URL-адреса на уровне экземпляра соответственно.

Создание иерархий концепций

Цель

Создайте иерархию понятий (измерений). Они будут отображаться в пользовательском интерфейсе Public Data Explorer в виде дерева, позволяя пользователям понимать группы и перемещаться между ними.

Шаги

1. Определите «родительское» понятие (например, region ).
2. Определите «дочернее» понятие (например, subregion ).
3. Добавьте в дочерний элемент свойство, которое ссылается на родителя и включает атрибут isParent :

   <property concept="..." isParent="true"/>
   

   , где точки заменены идентификатором родителя.
4. В таблице определений дочернего элемента добавьте столбец, который ссылается на родительский элемент.
5. Для каждого дочернего экземпляра заполните последний действительным экземпляром родительского понятия.

Ноты

• См. пример отношения country / state в наборе учебных данных .
• Каждый родительский идентификатор, на который ссылается дочерний элемент, должен находиться в родительской таблице определений. В противном случае импортер выдаст ошибку.
• Родительский и дочерний элементы могут быть одним и тем же понятием (т. е. самореферентной иерархией). В качестве примера см. business -концепцию в наборе данных по розничным продажам США .

Классификация экземпляров концепции

Цель

Создайте категории для экземпляров концепции, которые будут отображаться в качестве параметров в палитре цветов Public Data Explorer.

Шаги

1. Определите концепцию «категории» (например, income_level ).
2. Определите «дочернее» понятие (например, country ).
3. Добавьте в дочерний элемент свойство, которое ссылается на понятие категории и включает элемент name :

   <property concept="..."/>
     <info>
       <name><value>"..."</value></name>
     </info>
   </property>
   

   , где первый набор точек заменяется идентификатором понятия категории, а второй набор заменяется желаемым отображаемым именем для вашего свойства (например, "Уровень доходов").
4. В таблице определений дочернего элемента добавьте столбец, который ссылается на концепцию категории.
5. Для каждого дочернего экземпляра заполните последний действительным экземпляром концепции категории.

Ноты

• Концепция может иметь несколько свойств, которые служат категориями; в этом случае пользователь увидит их все как варианты в палитре цветов.
• Одна из категорий также может быть родительской для целей иерархической организации экземпляров в пользовательском интерфейсе. Подробности смотрите в предыдущем рецепте.

Указание порядка сортировки экземпляров концепции

Цель

Укажите порядок сортировки экземпляров концепции. Этот порядок используется при перечислении экземпляров в левой части страниц визуализации Public Data Explorer.

Шаги

1. Сделайте так, чтобы ваша концепция расширяла entity:entity или один из ее дочерних элементов (например, geo:location ).
2. Добавьте атрибут entity_order в метаданные концепции.
3. Установите значение предыдущего на одно из ALPHA или TABLE ; первый приведет к тому, что экземпляры будут перечислены в порядке их отображаемых имен, тогда как последний сохранит экземпляры в том же порядке, в котором они появляются в таблице определений понятий.

Ноты

• ALPHA — это текущее значение по умолчанию, поэтому, если вы хотите использовать этот порядок, указанные выше шаги необязательны.
• См . документацию entity:entity для примера.

Рецепты времени

Квартальные данные

Цель

Визуализируйте данные, указанные с квартальными интервалами.

Шаги

1. Преобразуйте все кварталы в данных среза в месяцы (например, первый месяц квартала).
2. Рассматривайте это измерение как time:month в XML-фрагменте.

Еженедельные данные

Цель

Визуализируйте данные, указанные с недельными интервалами.

Шаги

1. Преобразуйте все недели в данных среза в дни (например, первый день недели).
2. Рассматривайте это измерение как time:day в XML-фрагменте.

Гео Рецепты

Использование канонических понятий country или state

Цель

Используйте канонические концепции country или state , импортируя все значения широты/долготы и т. д., чтобы их не нужно было определять в наборе данных.

Шаги

1. Убедитесь, что все ссылки на страны и/или штаты США в CSV-файлах данных срезов являются действительными идентификаторами из канонических таблиц определения стран и штатов .
2. Добавьте geo:country и/или geo_us:state в качестве измерений в соответствующие срезы.
3. Убедитесь, что имена столбцов для них совпадают с именами предыдущих понятий (не включая имя импортированного набора данных, например, country ), или, если нет, включите операторы mapDimension в определение среза. Пример:

   <slice id="...">
     ...
     <dimension concept="geo:country"/>
     ...
     <mapDimension concept="geo:country" toColumn="my_country"/>
   </slice>
   

Использование только части канонических стран или штатов

Цель

Используйте подмножество канонической географической концепции, чтобы только это подмножество (а не весь список, например, все страны мира) отображалось в пользовательском интерфейсе Public Data Explorer.

Шаги

1. Определите локальную концепцию, которая расширяет концепцию надмножества. Пример:

   <concept id="my_country_subset" extends="geo:country">
   ...
   </concept>
   

2. В связанный CSV-файл определения понятия включите только идентификаторы расширенного понятия, которое вы хотите использовать. Пример:

   my_country_subset
   FR  
   MX
   US
   

Ноты

• Каждый экземпляр вашей концепции подмножества должен быть действительным экземпляром концепции надмножества; вы не можете «расширить» концепцию новыми экземплярами.

Определение собственных географических понятий

Цель

Создавайте свои собственные географические концепции, которые можно исследовать и наносить на карту, точно так же, как канонические, определенные Google.

Шаги

1. Создайте концепцию, которая расширяет geo:location .
2. В связанную таблицу определений понятий включите name столбцов, latitude и longitude .
3. Заполните последние свойства для каждого экземпляра вашей концепции; значения широты и долготы являются числами с плавающей запятой с соглашением, что N и E положительные, а W и S отрицательные.

Ноты

• Нет необходимости явно включать свойства name , latitude и longitude в ваше определение понятия, так как они автоматически включаются при расширении geo:location .
• В качестве примера см. определение state в учебном наборе данных .

Рецепты метрики и единицы измерения

Использование процентов

Цель

Определите (метрическую) концепцию, которая представляет собой процент от чего-то другого.

Шаги

1. Сделайте так, чтобы ваша концепция расширила quantity:ratio .
2. Установите для атрибута is_percentage значение true .

   <attribute id="is_percentage">
     <value>true</value>
   </attribute>
   

3. При необходимости установите атрибут percentage_of в зависимости от того, процентом от чего является это понятие. Пример:

   <attribute id="percentage_of">
     <value>labor force</value>
   </attribute>
   

Использование currency единиц

Цель

Определите концепцию (метрики), которая имеет денежную единицу (например, доллар США).

Шаги

1. Сделайте так, чтобы ваша метрика расширяла quantity:quantity или один из ее дочерних элементов, например, quantity:amount .
2. Добавьте атрибут unit , который ссылается на unit:currency , и задайте для этого значения идентификатор из связанной таблицы определения валюты . Пример:

   <concept id="...">
     <attribute concept="unit:currency">
       <value>EUR</value>
     </attribute>
   </concept>
   

Создание пользовательской единицы

Цель

Создайте пользовательскую единицу для одной или нескольких ваших метрик.

Шаги

1. Создайте концепцию, расширяющую unit:unit .
2. Добавьте столбцы unit_text и symbol в связанную таблицу определений. При желании, если вы хотите настроить положение символа, вы также можете добавить столбец symbol_position .
3. Заполните значения для последних свойств для каждого экземпляра вашего устройства. Пример CSV для единиц площади:

   my_unit,unit_text,symbol,symbol_position
   SQKM,square kilometers,km²,END
   SQML,square miles,miles²,END
   

4. Чтобы использовать только что созданную единицу измерения в (метрической) концепции, убедитесь, что последняя расширяет quantity:quantity или один из ее дочерних элементов. Затем добавьте атрибут, который ссылается на концепцию вашего устройства. Пример:

   <concept id="..." extends="quantity:amount">
     ...
     <attribute concept="my_unit">
       <value>SQKM</value>
     </attribute>
     ...
   </concept>
   

Ноты

• Если ваша концепция единицы имеет только один экземпляр, вы можете опустить столбец идентификатора из таблицы его определения, а также теги value в метриках, которые его используют.
• Полный пример см. в определении концепции канонической валюты .