Каналы кодирования

Неотъемлемая часть визуализации данных — кодирование данных визуальными свойствами графических примитивов. Свойство encoding спецификации одиночного представления задаёт соответствие между каналами кодирования, например x, y или color, и полями данных, постоянными визуальными значениями либо постоянными значениями данных (datum).

// Спецификация одиночного представления
{
  "data": ... ,
  "mark": ... ,
  "encoding": {     // Кодирование
    // Каналы положения
    "x": ...,
    "y": ...,
    "x2": ...,
    "y2": ...,
    "xError": ...,
    "yError": ...,
    "xError2": ...,
    "yError2": ...,

    // Каналы полярных координат
    "theta": ...,
    "radius": ...,
    "theta2": ...,
    "radius2": ...,

    // Каналы географических координат
    "longitude": ...,
    "latitude": ...,
    "longitude2": ...,
    "latitude2": ...,

    // Каналы свойств примитивов
    "color": ...,
    "opacity": ...,
    "fillOpacity": ...,
    "strokeOpacity": ...,
    "strokeWidth": ...,
    "strokeDash": ...,
    "size": ...,
    "angle": ...,
    "shape": ...,

    // Каналы текста и подсказки
    "text": ...,
    "tooltip": ...,

    // Канал гиперссылки
    "href": ...,

    // Канал описания
    "description": ...,

    // Канал дополнительной детализации
    "detail": ...,

    // Канал ключа записи
    "key": ...,

    // Канал порядка
    "order": ...,

    // Каналы панелей
    "facet": ...,
    "row": ...,
    "column": ...
  },
  ...
}

Каналы кодирования

Ключи объекта encoding — это каналы кодирования. Vega-Lite поддерживает следующие группы:

• Положение: x, y, x2, y2, xError, yError, xError2, yError2.
• Смещение положения: xOffset, yOffset.
• Полярные координаты: theta, theta2, radius, radius2.
• Географические координаты: longitude, latitude, longitude2, latitude2.
• Свойства примитива: angle, color (а также fill / stroke), opacity, fillOpacity, strokeOpacity, shape, size, strokeDash, strokeWidth.
• Текст и всплывающая подсказка: text, tooltip.
• Гиперссылка: href.
• Описание: description.
• Дополнительная детализация: detail.
• Ключ записи: key.
• Порядок: order.
• Панели: facet, row, column.

Определение канала

Объект определения каждого канала должен быть одним из следующих:

• Определение поля описывает поле данных, кодируемое каналом.
• Определение значения описывает кодируемое постоянное визуальное значение.
• Определение datum описывает постоянное значение данных, кодируемое через шкалу.

Определение поля

// Спецификация одиночного представления
{
  ...,
  "encoding": {     // Кодирование
    ...: {
      "field": ...,
      "type": ...,
      ...
    },
    ...
  },
  ...
}

Чтобы закодировать определённое поле набора данных, определение поля канала должно описывать его имя field и тип type. Для удобства исследования данных Vega-Lite, помимо преобразований transform верхнего уровня, поддерживает преобразования непосредственно в определении поля: aggregate, bin, sort, stack и timeUnit.

Все определения полей поддерживают следующие свойства:

Примечание о версии: в исходной странице указано устаревшее имя band. В закреплённой схеме и используемой версии Vega-Lite это свойство называется bandPosition; см. положение внутри полосы.

Кроме того, определения полей разных каналов могут поддерживать:

• scale — функцию, преобразующую значения области данных (числа, даты, строки и т. п.) в визуальные значения (пиксели, цвета, размеры) для каналов положения и свойств примитива.
• axis — ось, помогающую интерпретировать шкалу положения.
• legend — легенду, помогающую интерпретировать каналы свойств примитива.
• format — шаблон форматирования значений текстовых каналов.
• stack — тип смещения при укладке поля положения с непрерывной областью.
• sort — порядок сортировки поля для каналов положения и свойств примитива.
• condition — правило условного кодирования для каналов свойств примитива и текста.

Перечни дополнительных свойств приведены в разделах каналов положения, свойств примитива, текста и подсказки, детализации, порядка и панелей.

Определение постоянного визуального значения

// Спецификация одиночного представления
{
  ...,
  "encoding": {     // Кодирование
    ...: {
      "value": ...
    },
    ...
  },
  ...
}

Чтобы сопоставить каналу постоянное визуальное значение, укажите свойство value в определении значения. Дополнительные примеры приведены на странице value.

Определение постоянного значения данных

// Спецификация одиночного представления
{
  ...,
  "encoding": {     // Кодирование
    ...: {
      "datum": ...
    },
    ...
  },
  ...
}

Чтобы сопоставить каналу постоянное значение данных (datum) через шкалу, укажите свойство datum в определении канала. Дополнительные примеры приведены на странице datum.

Подобно определению поля, определение datum в разных каналах может поддерживать свойства bandPosition (ранее band), scale, axis, legend, format или condition. Однако преобразования данных aggregate, bin, timeUnit и sort к определению datum не применяются.

Каналы положения

Каналы x и y определяют положение примитивов либо ширину и высоту горизонтальных и вертикальных area и bar. Каналы x2 и y2 могут задавать вторую границу области, столбца, прямоугольника и отрезка.

По умолчанию Vega-Lite автоматически создаёт шкалу и ось для каждого поля в канале положения. Если свойства не заданы, компилятор определяет их по набору правил. Свойства scale и axis определения поля позволяют изменить эти настройки.

Определение поля и datum для положения

Помимо общих свойств определения поля, определения полей каналов x и y могут включать свойства, перечисленные ниже. Определения datum для x и y также поддерживают эти свойства.

Примечание: у x2 и y2 нет собственных определений scale, axis, sort и stack, поскольку они используют шкалы и оси x и y соответственно.

Каналы смещения положения

Каналы xOffset и yOffset задают дополнительное смещение относительно положения x или y.

Определение поля и datum для смещения положения

Помимо общих свойств определения поля, определения полей каналов xOffset и yOffset могут включать свойства, перечисленные ниже. Определения datum для этих каналов также поддерживают их.

Пример: группированная столбчатая диаграмма

Примечание: о настройке размера шага шкалы смещения читайте в разделе размеров представления.

Пример: случайное смещение точек

Пример: диапазоны через количественное смещение

Каналы xOffset и yOffset также могут задавать диапазон для примитивов bar и area, если основной канал положения дискретный. В этом режиме Vega-Lite интерпретирует количественное смещение как значение от базовой линии внутри полосы (0) до значения смещения: примитивы получают протяжённость в направлении смещения.

Например, при номинальном канале y, задающем дорожки, и количественном yOffset каждый столбец простирается от базовой линии своей дорожки до yOffset внутри неё.

Это удобно для сравнения диапазонов внутри полос, когда нужно сохранить категориальные дорожки и закодировать величину смещением.

Примитивы пути (line, area и trail) рисуются единым связным путём, поэтому диаграмма с несколькими дорожками соединяет точки разных дорожек. Чтобы рисовать отдельный путь для каждой, добавьте канал группировки, например detail или color, повторно использующий поле дорожки:

Каналы полярных координат

Каналы theta и radius определяют положение или интервал в полярных координатах для примитивов arc и text.

Определение поля и datum для полярных координат

Определения полей и datum для полярных координат могут включать scale, stack и sort, подобно определениям поля и datum для положения.

Каналы географических координат

Каналы longitude и latitude кодируют географические координаты через проекцию. Каналы longitude2 и latitude2 могут задавать вторую границу географически спроецированных областей, столбцов, прямоугольников и отрезков.

Смотрите пример использования longitude и latitude на карте или пример отрезков rule между точками карты.

Каналы свойств примитивов

Эти каналы сопоставляют поля данных визуальным свойствам примитивов. По умолчанию Vega-Lite автоматически создаёт шкалу и легенду для каждого поля, связанного с таким каналом. Если их свойства не заданы, компилятор определяет их по набору правил. Свойства scale и legend определения поля позволяют изменить эти настройки. Определения каналов свойств примитива также могут включать condition, задающее условную логику.

Список каналов свойств примитива:

Определение поля и datum для свойств примитива

Определения полей этих каналов могут включать свойства из таблицы ниже, помимо field, type, bin, timeUnit и aggregate. Определения datum также поддерживают эти свойства.

Определение значения для свойств примитива

Помимо постоянного value, определения значений этих каналов могут включать свойство condition, задающее условную логику.

Примеры задания условной логики приведены на странице condition.

Каналы текста и всплывающей подсказки

Эти каналы непосредственно кодируют текстовые значения полей данных. По умолчанию Vega-Lite выбирает подходящий формат количественных и временных значений. Свойство format позволяет настроить формат чисел и времени. Как и каналы свойств примитивов, определения каналов текста и подсказки могут включать condition, задающее условную логику.

Определение поля для текста и подсказки

Помимо общих свойств определения поля, определения полей каналов text и tooltip могут включать:

Определение значения для текста и подсказки

Помимо постоянного value, определения значений каналов text и tooltip могут включать condition, задающее условную логику.

Несколько определений полей для подсказки

Подобно каналу detail, здесь можно использовать массив определений полей. Vega-Lite покажет подсказку с несколькими полями. Обработчик Vega Tooltip выводит таблицу с именами полей и их значениями. Подробнее — на странице всплывающей подсказки.

Определения полей массива также могут включать предикат filter, исключающий отдельные поля во время выполнения:

Канал гиперссылки

Если задать канал href, примитив становится гиперссылкой. Указанный URL загружается при щелчке мышью. При заданном href свойство cursor примитива по умолчанию принимает значение "pointer", обозначая возможность перехода по ссылке.

Определение поля гиперссылки

Помимо общих свойств определения поля, определение поля канала href может включать condition, задающее условную логику.

Примечание о версии: в исходной таблице указано устаревшее определение типа. Здесь приведён актуальный тип свойства condition.

Пример ниже показывает, как канал href добавляет ссылки на ресурсы с дополнительными сведениями. В русской копии ссылки ведут на внутреннюю страницу справочника.

Определение значения гиперссылки

Помимо постоянного value, определение значения канала href может включать condition, задающее условную логику.

Канал описания

Канал description добавляет примитиву текстовое описание для доступности ARIA (только при выводе SVG). Атрибут aria-label в созданном SVG получает это описание.

По умолчанию Vega-Lite создаёт описание на основе кодирования, подобно подсказкам по умолчанию. Чтобы отключить автоматические описания, задайте config.aria равным false. Если mark.aria равно false, описание не создаётся.

Определение поля описания

Помимо общих свойств определения поля, определения полей канала description могут включать:

Определение значения описания

Помимо постоянного value, определение значения канала description может включать condition, задающее условную логику.

Канал дополнительной детализации

Группировка данных — ещё одна важная операция визуализации. Для линий и областей сопоставление неагрегированного поля (без функции aggregate) любому каналу, не задающему положение, группирует линии и области с укладкой по этому полю. В агрегированных диаграммах все закодированные неагрегированные поля становятся полями группировки, подобно полям в GROUP BY SQL.

Канал detail задаёт дополнительное поле или поля группировки, не сопоставляя их визуальным свойствам.

Примеры

Диаграмма рассеяния ниже показывает среднюю мощность и рабочий объём двигателей автомобилей из разных регионов. Поле Origin сопоставлено каналу detail, чтобы использовать его для группировки без связи с визуальными свойствами примитивов.

Линейный график ниже показывает цены акций пяти технологических компаний во времени. Переменная symbol (биржевой тикер) сопоставлена detail, чтобы группировать линии.

Диаграмма с диапазонами ниже показывает изменение ожидаемой продолжительности жизни в пяти самых населённых странах с 1955 по 2000 год. Канал detail группирует линии так, чтобы каждая соединяла значения разных лет внутри одной страны, а не переходила между странами.

Канал ключа записи

Канал key позволяет сохранять соответствие объектов при переходах в визуализации с динамическими данными. Когда данные обновляются через Vega View API, значение ключа сопоставляет элементы данных существующим экземплярам примитивов.

Канал порядка

Канал order задаёт поле данных или упорядоченный список полей, определяющих порядок укладки (см. пример на странице stack), порядок точек линии в связной диаграмме рассеяния (см. пример на странице line) или то, какие точки рисуются поверх других (порядок по Z; см. пример в галерее).

Определение поля порядка

Помимо общих свойств определения поля, определения полей канала order могут включать sort.

Определение значения порядка

Помимо постоянного value, определение значения канала order может включать condition, задающее условную логику.

Каналы панелей

Каналы facet, row и column разбивают одиночную диаграмму на решётчатую диаграмму — набор небольших представлений.

Подробнее читайте в документации по разбиению на панели.