Поваренная книга 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 в метриках, которые его используют.
  • Полный пример см. в определении концепции канонической валюты .