Стек-макет

Справочник API ▸ Макеты ▸ Стек-макет

Стек-макет принимает массив объектов слоев, каждый из которых содержит серию (массив) объектов точек. Объекты точек содержат пару ординат (как минимум), которые отображают горизонтальное положение каждой точки и ее вертикальную толщину. Результатом работы стека-макета является тот же массив слоев, но с добавленным состоянием в объекты точек для облегчения выбранной стратегии стекирования. Макет вычисляет базу для первого слоя, а затем распространяет ее на вышележащие слои, чтобы получить структурированные данные. Поддерживаются несколько алгоритмов расчета базы, а также эвристики сортировки для улучшения восприятия, как описано в “Stacked Graphs—Geometry & Aesthetics” Брайоном и Ваттенбергом.

Стек-макет работает в произвольном двумерном пространстве координат x и y, подобно другим макетам D3, включая дерево. Таким образом, слои могут быть расположены вертикально, горизонтально или даже радиально. Хотя значение по умолчанию для смещения равно «нулю», диаграмму потока можно сгенерировать, используя смещение «волнообразное», которое пытается свести к минимуму изменение наклона, взвешенное толщиной слоя.

d3.layout.stack()

Создает новый макет стека с по умолчанию смещением (ноль) и порядком (null). Возвращаемый объект макета является одновременно объектом и функцией. То есть: вы можете вызвать макет как любую другую функцию, и у макета есть дополнительные методы для изменения его поведения. Как и другие классы в D3, макеты следуют шаблону цепочки методов, где методы установщиков возвращают сам макет, позволяя вызывать несколько установщиков в одном сжатом операторе.

stack(layers[, index])

Вычисляет базу координат y для каждого слоя в массиве layers, а затем распространяет эту базу на другие слои. В самом простом случае layers — это двумерный массив объектов точек, все с одинаковой длиной, и каждый с вертикальной и горизонтальной ординатой для определения толщины y каждого слоя в заданной позиции x.

Более сложные структуры принимаются макетом, но только если функция селектора передана в values, которая абстрагирует структуру обратно к простому случаю, описанному выше. В любом случае, сложность ограничивается массивом объектов слоя, каждый из которых имеет массив точек в качестве члена. Например, невозможно использовать хеш-таблицу (объект) со значениями, содержащими пары ключ-значение, представляющие координаты. Такая структура может быть абстрагирована в требуемый формат с помощью функции-селектора, но возвращаемый объектом макета не будет добавлено состояние смещения, так как в настоящее время нет способа абстрагировать вывод с учетом слоя.

Макет по умолчанию ожидает, что объекты точек будут содержать члены x и y, к которым он добавит член y0, чтобы сохранить значения смещения, полученные выбранным алгоритмом вычисления базы. Если свойства координат (сырые или абстрагированные) не названы x и y, то селекторы x и y должны быть предоставлены для завершения абстрагирования и предоставления указанной выше структуры.

Таким образом, каждый объект точки имеет следующую абстрактную структуру:

• x — положение x значения.
• y — толщина y значения.
• y0 — минимальное положение y значения (база).

Последние два физически добавляются в объекты точек, если это необходимо.

Необязательный аргумент index не используется макетом по умолчанию, но предоставляется для пользовательских объектов order и offset.

stack.values([accessor])

Указывает, как извлечь массив points из элементов layer массива layers; accessor — это функция, которая вызывается для каждого входного слоя, переданного в stack, эквивалентно вызову layers.map(accessor) перед вычислением стека. Функция-селектор по умолчанию — функция тождества. Если accessor не указан, возвращает текущий селектор значений.

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

var layers = [
  {
    "name": "apples",
    "values": [
      { "x": 0, "y":  91},
      { "x": 1, "y": 290}
    ]
  },
  {
    "name": "oranges",
    "values": [
      { "x": 0, "y":  9},
      { "x": 1, "y": 49}
    ]
  }
];

Укажите селектор значений, который извлекает массив точек для каждого слоя:

var stack = d3.layout.stack()
    .offset("wiggle")
    .values(function(d) { return d.values; });

Затем, если вы хотите добавить всплывающую подсказку для каждого слоя, вы можете сказать:

svg.selectAll("path")
    .data(stack(layers))
  .enter().append("path")
    .attr("d", function(d) { return area(d.values); })
  .append("title")
    .text(function(d) { return d.name; });

stack.offset([offset])

Если offset указан, устанавливает алгоритм смещения стека в указанное значение. Если offset не указан, возвращает текущий алгоритм смещения. Поддерживаются следующие строковые значения:

• silhouette — центрирует поток, как в ThemeRiver.
• wiggle — минимизирует взвешенное изменение наклона.
• expand — нормализует слои, чтобы заполнить диапазон [0,1].
• zero — использует нулевую базу, т.е., ось y.

В дополнение к строке, offset может быть указан как функция. Входной функцией смещения является набор данных слоя, преобразованный в стандартное представление: двумерный массив значений, где каждое значение представлено массивом из двух элементов [x, y]. Возвращаемое значение функции смещения должно быть массивом значений, представляющих координаты y базы. Например, смещение по умолчанию «ноль» реализуется следующим образом:

function offset(data) {
  var j = -1,
      m = data[0].length,
      y0 = [];
  while (++j < m) y0[j] = 0;
  return y0;
}

stack.order([order])

Если order указан, устанавливает порядок стека в указанное значение. Если order не указан, возвращает текущий порядок. Поддерживаются следующие строковые значения:

• inside-out — сортировка по индексу максимального значения, затем использование сбалансированного взвешивания.
• reverse — обратный порядок входного слоя.
• default — использование порядка входного слоя.

В дополнение к строке, order может быть указан как функция. Входной функцией порядка является набор данных слоя, преобразованный в стандартное представление: двумерный массив значений, где каждое значение представлено массивом из двух элементов [x, y]. Возвращаемое значение функции порядка должно быть массивом индексов, представляющих порядок слоя. Например, порядок по умолчанию реализуется следующим образом:

function order(data) {
  return d3.range(data.length);
}

См. также d3.range.

stack.x([accessor])

Указывает, как получить координату x позиции каждого значения. Если accessor указан, устанавливает селектор в указанную функцию. Если accessor не указан, возвращает текущую функцию, которая по умолчанию предполагает, что каждое входное значение имеет атрибут x:

function x(d) {
  return d.x;
}

Селектор x вызывается для каждого входного значения, для каждого входного слоя, передавая текущие данные (d) и индекс (i). Возвращаемое значение селектора должно быть числом.

Координата x влияет только на поведение смещения «волнообразного» offset; изменение этого селектора не влияет на то, как данные сгруппированы в стеки. Хотя селектор x вызывается для всех слоев (а не только для нижнего слоя), макет стека предполагает, что координаты x всех слоев однородны и согласованы. Другими словами, каждый слой должен содержать одинаковое количество значений в тех же координатах x в том же порядке. Если ваши данные нерегулярны, вам нужно будет переинтерполировать или переупорядочить данные перед вычислением стека.

stack.y([accessor])

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

function y(d) {
  return d.y;
}

Селектор y вызывается для каждого входного значения, для каждого входного слоя, передавая текущие данные (d) и индекс (i). Возвращаемое значение селектора должно быть числом. За исключением смещения «expand», макет стека не выполняет автоматическую масштабировку данных. Для упрощения масштабирования используйте этот макет в сочетании с линейной шкалой или аналогичной.

stack.out([setter])

Указывает, как распространить вычисленную базу на вышележащие слои. Если setter указан, он используется в качестве функции вывода. Если setter не указан, возвращает текущую функцию вывода, которая по умолчанию предполагает, что каждое входное значение имеет атрибуты y и y0:

function out(d, y0, y) {
  d.y0 = y0;
  d.y = y;
}

Селектор setter вызывается для каждого входного значения, для каждого входного слоя, передавая текущие данные (d), вычисленное значение y0 и вычисленную толщину y. Во всех случаях, кроме смещения «expand», толщина y такая же, как входное значение, возвращенное селектором y, и поэтому может быть проигнорирована.