Ящик с усами

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

Ящик с усами показывает распределение количественных значений через сводные статистики. Линия внутри ящика обозначает медиану, нижняя и верхняя границы ящика — первый и третий квартили. Концы «усов» зависят от варианта диаграммы. Для построения задайте mark: "boxplot".

Содержание страницы

Свойства ящика с усами

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

Свойство Тип Описание
type BoxPlot Тип примитива: базовый ("bar", "circle", "square", "tick", "line", "area", "point", "geoshape", "rule", "text") или составной ("boxplot", "errorband", "errorbar").
extent "min-max", number Границы усов. Допустимы:
• "min-max" — нижний и верхний усы заканчиваются соответственно на минимуме и максимуме.
• Число — множитель межквартильного размаха (IQR). Усы идут от наименьшего до наибольшего значения внутри интервала [Q1 − k × IQR, Q3 + k × IQR], где Q1 и Q3 — первый и третий квартили, IQR = Q3 − Q1.

По умолчанию: 1.5.
orient Orientation Ориентация ящика с усами. Обычно определяется автоматически по типам полей каналов X и Y. Если ориентация неоднозначна, её можно задать явно.

По умолчанию: "vertical".
size number Размер ящика и штриха медианы.
color Color, Gradient, ExprRef Цвет по умолчанию.

По умолчанию: ■ "#4c78a8".

Примечания: это свойство нельзя задавать в конфигурации стилей. Свойства fill и stroke имеют более высокий приоритет и переопределяют color.
opacity number Непрозрачность примитива, от 0 до 1.
invalid MarkInvalidDataMode, null Режим обработки некорректных данных: определяет, как примитивы и соответствующие шкалы представляют null и NaN в непрерывных шкалах, для которых не задано выходное значение для некорректных данных.

• "filter" — исключает все некорректные значения из примитивов и шкал. Для линий, областей и trail соединяет допустимые точки, как если бы некорректных строк данных не было.
• "break-paths-filter-domains" — разрывает линии, области и trail на некорректных значениях. Для остальных примитивов равнозначен "filter". Все области данных шкал исключают отфильтрованные точки.
• "break-paths-show-domains" — разрывает пути на некорректных значениях; для остальных примитивов скрывает такие значения. Области данных всех шкал включают эти отфильтрованные точки.
• "show" или null — показывает все точки в примитивах и областях данных шкал. Каждая шкала использует выходное значение из config.scale.invalid; если оно не задано, некорректные значения получают тот же вид, что ноль (если шкала включает ноль), или минимальное значение (если не включает).
• "break-paths-show-path-domains" (по умолчанию) — равнозначен "break-paths-show-domains" для линий, областей и trail, а для остальных примитивов — "filter".

Примечание: если в config.scale.invalid задан выход для некорректных значений шкалы канала, все значения этой шкалы считаются допустимыми, поскольку могут дать определённый результат. Поля таких каналов не фильтруются и не вызывают разрывы путей.

Свойства box, median, rule, outliers и ticks позволяют отдельно оформить части диаграммы через свойства базовых примитивов.

Варианты диаграммы

Ящик Тьюки используется по умолчанию. Его усы идут от наименьшего до наибольшего значения внутри интервала [Q1 − k × IQR, Q3 + k × IQR]. Здесь Q1 и Q3 — первый и третий квартили, IQR = Q3 − Q1 — межквартильный размах, а множитель k задаётся числовым свойством extent. Значения за пределами усов показываются отдельными точками. По умолчанию extent равен 1.5:

Явное extent: 1.5 даёт ту же диаграмму:

Ящик «минимум–максимум» задаётся extent: "min-max". Его усы заканчиваются на минимуме и максимуме, поэтому выбросов за пределами усов не остаётся:

Измерения и ориентация

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

Ориентация определяется осью непрерывного поля. Если поле находится на оси y, ящик будет вертикальным:

Двумерная диаграмма показывает распределение непрерывного поля по категориям. При непрерывном поле на оси x ящики горизонтальны:

При непрерывном поле на оси y — вертикальны:

Из каких частей состоит ящик

boxplot — составной примитив, который разворачивается в несколько слоёв. Например, одномерный ящик можно описать так:

Отдельные части настраиваются через определение примитива или конфигурацию. Например, задайте "color": "red" для штриха "median", а "ticks": true добавит штрихи на концах усов:

Каналы цвета, размера и прозрачности

Каналы кодирования color, size и opacity управляют составным примитивом по-разному: size влияет только на ящик и медиану, color — на ящик и точки выбросов, opacity — на всю диаграмму.

Примеры с каналом size и совместным кодированием цвета и размера:

Всплывающие подсказки

Пользовательская подсказка заменяет стандартную. Если поле подсказки не агрегировано, она заменяет подсказки точек выбросов:

Если поле агрегировано, она заменяет подсказки ящика и усов:

Настройка по умолчанию

{
  "boxplot": {
    "size": ...,
    "extent": ...,
    "box": ...,
    "median": ...,
    "rule": ...,
    "outliers": ...
  }
}

config.boxplot задаёт свойства ящика по умолчанию. В этой конфигурации сейчас не поддерживаются color, opacity и orient.

Диаграмма по заранее рассчитанным статистикам

Если сводные показатели уже есть в данных, ящик с усами можно собрать из отдельных слоёв: