d3-array

Данные в JavaScript часто представляются в виде массива, поэтому при визуализации или анализе данных часто приходится работать с массивами. Некоторые распространенные операции включают взятие непрерывного среза (подмножества) массива, фильтрацию массива с помощью предикатной функции и отображение массива на параллельный набор значений с помощью функции преобразования. Перед изучением набора утилит, предоставляемых этим модулем, ознакомьтесь с мощными методами массивов, встроенными в JavaScript методами массивов JavaScript.

JavaScript включает методы изменения, которые изменяют массив:

array.pop - Удаляет последний элемент из массива.
array.push - Добавляет один или несколько элементов в конец массива.
array.reverse - Изменяет порядок элементов массива на обратный.
array.shift - Удаляет первый элемент из массива.
array.sort - Сортирует элементы массива.
array.splice - Добавляет или удаляет элементы из массива.
array.unshift - Добавляет один или несколько элементов в начало массива.

Также существуют методы доступа, которые возвращают некоторое представление массива:

array.concat - Объединяет массив с другими массивом(ами) или значением(и).
array.join - Объединяет все элементы массива в строку.
array.slice - Извлекает часть массива.
array.indexOf - Находит первое вхождение значения в массиве.
array.lastIndexOf - Находит последнее вхождение значения в массиве.

И, наконец, методы итерации, которые применяют функции к элементам массива:

array.filter - Создаёт новый массив, содержащий только те элементы, для которых предикат истиннен.
array.forEach - Вызывает функцию для каждого элемента в массиве.
array.every - Проверяет, удовлетворяет ли каждый элемент массива предикату.
array.map - Создаёт новый массив с результатом вызова функции для каждого элемента в массиве.
array.some - Проверяет, удовлетворяет ли хотя бы один элемент массива предикату.
array.reduce - Применяет функцию для сведения массива к одному значению (слева направо).
array.reduceRight - Применяет функцию для сведения массива к одному значению (справа налево).

Установка

Если вы используете NPM, npm install d3-array. В противном случае загрузите последнюю версию. Вы также можете загрузить непосредственно с d3js.org, как отдельную библиотеку или как часть D3 4.0. Поддерживаются среды AMD, CommonJS и vanilla. В vanilla экспортируется глобальная переменная d3:

<script src="https://d3js.org/d3-array.v1.min.js"></script>
<script>

var min = d3.min(array);

</script>

Попробуйте d3-array в вашем браузере.

Статистические данные

Методы для вычисления основных сводных статистических данных.

d3.min(array[, accessor]) Источник

Возвращает минимальное значение в данном массиве в соответствии с естественным порядком. Если массив пуст, возвращает undefined. В качестве необязательной функции accessor может быть указана функция, что эквивалентно вызову array.map(accessor) перед вычислением минимального значения.

В отличие от встроенной функции Math.min, этот метод игнорирует undefined, null и NaN; это полезно для игнорирования отсутствующих данных. Кроме того, элементы сравниваются в соответствии с естественным порядком, а не числовым. Например, минимум строк [“20”, “3”] — это “20”, а минимум чисел [20, 3] — это 3.

См. также scan и extent.

d3.max(array[, accessor]) Источник

Возвращает максимальное значение в данном массиве в соответствии с естественным порядком. Если массив пуст, возвращает undefined. В качестве необязательной функции accessor может быть указана функция, что эквивалентно вызову array.map(accessor) перед вычислением максимального значения.

В отличие от встроенной функции Math.max, этот метод игнорирует undefined; это полезно для игнорирования отсутствующих данных. Кроме того, элементы сравниваются в соответствии с естественным порядком, а не числовым. Например, максимум строк [“20”, “3”] — это “3”, а максимум чисел [20, 3] — это 20.

См. также scan и extent.

d3.extent(array[, accessor]) Источник

Возвращает минимальное и максимальное значения в данном массиве в соответствии с естественным порядком. Если массив пуст, возвращает [undefined, undefined]. В качестве необязательной функции accessor может быть указана функция, что эквивалентно вызову array.map(accessor) перед вычислением диапазона.

d3.sum(array[, accessor]) Источник

Возвращает сумму данного массива чисел. Если массив пуст, возвращает 0. В качестве необязательной функции accessor может быть указана функция, что эквивалентно вызову array.map(accessor) перед вычислением суммы. Этот метод игнорирует undefined и NaN; это полезно для игнорирования отсутствующих данных.

d3.mean(array[, accessor]) Источник

Возвращает среднее значение данного массива чисел. Если массив пуст, возвращает undefined. В качестве необязательной функции accessor может быть указана функция, что эквивалентно вызову array.map(accessor) перед вычислением среднего значения. Этот метод игнорирует undefined и NaN; это полезно для игнорирования отсутствующих данных.

d3.median(array[, accessor]) Источник

Возвращает медиану данного массива чисел, используя метод R-7. Если массив пуст, возвращает undefined. В качестве необязательной функции accessor может быть указана функция, что эквивалентно вызову array.map(accessor) перед вычислением медианы. Этот метод игнорирует undefined и NaN; это полезно для игнорирования отсутствующих данных.

d3.quantile(array, p[, accessor]) Источник

Возвращает p-квантиль данного отсортированного массива чисел, где p — число в диапазоне [0, 1]. Например, медиана может быть вычислена с помощью p = 0,5, первый квартиль при p = 0,25, а третий квартиль при p = 0,75. Эта конкретная реализация использует метод R-7, который является стандартным для языка программирования R и Excel.

var a = [0, 10, 30];
d3.quantile(a, 0); // 0
d3.quantile(a, 0.5); // 10
d3.quantile(a, 1); // 30
d3.quantile(a, 0.25); // 5
d3.quantile(a, 0.75); // 20
d3.quantile(a, 0.1); // 2

В качестве необязательной функции accessor может быть указана функция, что эквивалентно вызову array.map(accessor) перед вычислением квантиля.

d3.variance(array[, accessor]) Источник

Возвращает несмещенную оценку дисперсии генеральной совокупности данного массива чисел. Если массив содержит меньше двух значений, возвращает undefined. В качестве необязательной функции accessor может быть указана функция, что эквивалентно вызову array.map(accessor) перед вычислением дисперсии. Этот метод игнорирует undefined и NaN; это полезно для игнорирования отсутствующих данных.

d3.deviation(array[, accessor]) Источник

Возвращает стандартное отклонение, определяемое как квадратный корень из исправленной дисперсии, данного массива чисел. Если массив содержит меньше двух значений, возвращает undefined. В качестве необязательной функции accessor может быть указана функция, что эквивалентно вызову array.map(accessor) перед вычислением стандартного отклонения. Этот метод игнорирует undefined и NaN; это полезно для игнорирования отсутствующих данных.

Поиск

Методы поиска элементов в массивах.

d3.scan(array[, comparator]) Source

Выполняет линейный поиск в заданном массиве, возвращая индекс наименьшего элемента в соответствии со заданным компаратором. Если заданный массив не содержит сравнимых элементов (т.е., компаратор возвращает NaN при сравнении каждого элемента с самим собой), возвращает undefined. Если компаратор не указан, он по умолчанию равен ascending. Например:

var array = [{foo: 42}, {foo: 91}];
d3.scan(array, function(a, b) { return a.foo - b.foo; }); // 0
d3.scan(array, function(a, b) { return b.foo - a.foo; }); // 1

Эта функция похожа на min, за исключением того, что она позволяет использовать компаратор вместо доступара, и она возвращает индекс вместо значения доступа. См. также bisect.

d3.bisectLeft(array, x[, lo[, hi]]) Source

Возвращает точку вставки для x в массиве для поддержания сортированного порядка. Аргументы lo и hi могут быть использованы для указания подмножества массива, которое следует учитывать; по умолчанию используется весь массив. Если x уже присутствует в массиве, точка вставки будет находиться перед (слева от) любыми существующими записями. Возвращаемое значение подходит для использования в качестве первого аргумента splice, предполагая, что массив уже отсортирован. Возвращаемая точка вставки i разделяет массив на две половины, так что все v < x для v в array.slice(lo, i) для левой стороны и все v >= x для v в array.slice(i, hi) для правой стороны.

d3.bisect(array, x[, lo[, hi]]) Source
d3.bisectRight(array, x[, lo[, hi]]) Source

Аналогично bisectLeft, но возвращает точку вставки, которая находится после (справа от) любых существующих записей x в массиве. Возвращаемая точка вставки i разделяет массив на две половины, так что все v <= x для v в array.slice(lo, i) для левой стороны и все v > x для v в array.slice(i, hi) для правой стороны.

d3.bisector(accessor) Source
d3.bisector(comparator) Source

Возвращает новый бисектор, использующий указанную функцию accessor или comparator. Этот метод может использоваться для бисекции массивов объектов вместо ограничения простыми массивами примитивов. Например, приведён следующий массив объектов:

var data = [
  {date: new Date(2011, 1, 1), value: 0.5},
  {date: new Date(2011, 2, 1), value: 0.6},
  {date: new Date(2011, 3, 1), value: 0.7},
  {date: new Date(2011, 4, 1), value: 0.8}
];

Подходящая функция бисекции может быть построена как:

var bisectDate = d3.bisector(function(d) { return d.date; }).right;

Это эквивалентно указанию компаратора:

var bisectDate = d3.bisector(function(d, x) { return d.date - x; }).right;

И затем применяется как bisectDate(array, date), возвращающая индекс. Обратите внимание, что компаратор всегда получает значение поиска x в качестве второго аргумента. Используйте компаратор вместо доступара, если вы хотите, чтобы значения были отсортированы в порядке, отличном от естественного, например, в порядке убывания, а не возрастания.

bisector.left(array, x[, lo[, hi]]) Source

Эквивалентно bisectLeft, но использует связанный с этим бисектором компаратор.

bisector.right(array, x[, lo[, hi]]) Source

Эквивалентно bisectRight, но использует связанный с этим бисектором компаратор.

d3.ascending(a, b) Source

Возвращает -1, если a меньше b, или 1, если a больше b, или 0. Это функция компаратора для естественного порядка и может использоваться совместно с встроенным методом array.sort для упорядочения элементов в порядке возрастания. Она реализована как:

function ascending(a, b) {
  return a < b ? -1 : a > b ? 1 : a >= b ? 0 : NaN;
}

Обратите внимание, что если функция компаратора не указана для встроенного метода sort, по умолчанию порядок является лексикографическим (алфавитным), а не естественным! Это может привести к неожиданному поведению при сортировке массива чисел.

d3.descending(a, b) Source

Возвращает -1, если a больше b, или 1, если a меньше b, или 0. Это функция компаратора для обратного естественного порядка, и может использоваться совместно со встроенным методом сортировки массивов для упорядочения элементов в порядке убывания. Она реализована как:

function descending(a, b) {
  return b < a ? -1 : b > a ? 1 : b >= a ? 0 : NaN;
}

Преобразования

Методы преобразования массивов и генерации новых массивов.

d3.cross(a, b[, reducer]) Source

Возвращает декартово произведение двух массивов a и b. Для каждого элемента i в заданном массиве a и каждого элемента j в заданном массиве b, в порядке, вызывает заданную функцию reducer, передавая элемент i и элемент j. Если reducer не указан, он по умолчанию равен функции, которая создаёт массив из двух элементов для каждой пары:

function pair(a, b) {
  return [a, b];
}

Например:

d3.cross([1, 2], ["x", "y"]); // returns [[1, "x"], [1, "y"], [2, "x"], [2, "y"]]
d3.cross([1, 2], ["x", "y"], (a, b) => a + b); // returns ["1x", "1y", "2x", "2y"]

d3.merge(arrays) Source

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

d3.merge([[1], [2, 3]]); // returns [1, 2, 3]

d3.pairs(array[, reducer]) Source

Для каждой пары соседних элементов в указанном массиве, в порядке, вызывает заданную функцию reducer, передавая элемент i и элемент i - 1. Если reducer не указан, он по умолчанию равен функции, которая создаёт массив из двух элементов для каждой пары:

function pair(a, b) {
  return [a, b];
}

Например:

d3.pairs([1, 2, 3, 4]); // returns [[1, 2], [2, 3], [3, 4]]
d3.pairs([1, 2, 3, 4], (a, b) => b - a); // returns [1, 1, 1];

Если заданный массив содержит менее двух элементов, возвращает пустой массив.

d3.permute(array, indexes) Source

Возвращает перестановку указанного массива, используя указанный массив индексов. Возвращаемый массив содержит соответствующий элемент в массиве для каждого индекса в индексах, в порядке. Например, permute(["a", "b", "c"], [1, 2, 0]) возвращает ["b", "c", "a"]. Допускается, чтобы массив индексов был разной длины по отношению к массиву элементов, и чтобы индексы были дублированы или опущены.

Этот метод также может использоваться для извлечения значений из объекта в массив со стабильным порядком. Извлечение значений ключей в порядке может быть полезным для генерации массивов данных во вложенных выборках. Например:

var object = {yield: 27, variety: "Manchuria", year: 1931, site: "University Farm"},
    fields = ["site", "variety", "yield"];

d3.permute(object, fields); // returns ["University Farm", "Manchuria", 27]

d3.shuffle(array[, lo[, hi]]) Source

Случайным образом меняет порядок элементов в указанном массиве, используя алгоритм Фишера–Йейтса.

d3.ticks(start, stop, count) Source

Возвращает массив примерно из count + 1 равномерно распределённых, красиво округленных значений между start и stop (включительно). Каждое значение является степенью десяти, умноженной на 1, 2 или 5. См. также d3.tickIncrement, d3.tickStep и linear.ticks.

Штрихи включают в себя указанные start и stop значения, если (и только если) они являются точными, красиво округленными значениями, соответствующими вычисленному шагу. Более формально, каждый возвращаемый штрих t удовлетворяет условиям start ≤ t и t ≤ stop.

d3.tickIncrement(start, stop, count) Source

Подобно d3.tickStep, за исключением того, что требует, чтобы start всегда было меньше или равно step, и если шаг штрихов для заданных start, stop и count будет меньше единицы, возвращает обратный шаг штрихов вместо этого. Этот метод всегда гарантированно возвращает целое число и используется d3.ticks, чтобы избежать гарантии, что возвращаемые значения штрихов представлены так точно, как это возможно в формате с плавающей точкой IEEE 754.

d3.tickStep(start, stop, count) Source

Возвращает разницу между соседними значениями штрихов, если те же аргументы были переданы d3.ticks: красиво округленное значение, которое является степенью десяти, умноженной на 1, 2 или 5. Обратите внимание, что из-за ограниченной точности IEEE 754 с плавающей точкой, возвращаемое значение может не быть точной десятичной дробью; используйте d3-format, чтобы отформатировать числа для чтения человеком.

d3.range([start, ]stop[, step]) Source

Возвращает массив, содержащий арифметическую прогрессию, аналогично встроенной функции Python range. Этот метод часто используется для итерации по последовательности равномерно распределённых числовых значений, таких как индексы массива или отметки линейной шкалы. (См. также d3.ticks для значений с красивым округлением.)

Если step опущен, он по умолчанию равен 1. Если start опущен, он по умолчанию равен 0. Значение stop исключается; оно не включается в результат. Если step положительный, последний элемент — это наибольшее start + i * step, меньшее stop; если step отрицательный, последний элемент — это наименьшее start + i * step, большее stop. Если возвращаемый массив содержал бы бесконечное число значений, возвращается пустой диапазон.

Аргументы необязательно должны быть целыми числами; однако результаты предсказуемее, если они таковыми являются. Значения в возвращаемом массиве определяются как start + i * step, где i — целое число от нуля до одного минус общее количество элементов в возвращаемом массиве. Например:

d3.range(0, 1, 0.2) // [0, 0.2, 0.4, 0.6000000000000001, 0.8]

Это неожиданное поведение связано с двойной точностью чисел с плавающей запятой IEEE 754, которая определяет 0.2 * 3 = 0.6000000000000001. Используйте d3-format для форматирования чисел для отображения человеку с соответствующим округлением; см. также linear.tickFormat в d3-scale.

Аналогично, если возвращаемый массив должен иметь определённую длину, рассмотрите использование array.map на цельном диапазоне. Например:

d3.range(0, 1, 1 / 49); // BAD: returns 50 elements!
d3.range(49).map(function(d) { return d / 49; }); // GOOD: returns 49 elements.

d3.transpose(matrix) Исходный код

Использует оператор zip в качестве двумерной транспозиции матрицы.

d3.zip(arrays…) Исходный код

Возвращает массив массивов, где i-й массив содержит i-й элемент из каждого из аргументных массивов arrays. Возвращаемый массив усечён по длине до самого короткого массива в arrays. Если arrays содержит только один массив, возвращаемый массив содержит массивы по одному элементу. Без аргументов возвращаемый массив пустой.

d3.zip([1, 2], [3, 4]); // returns [[1, 3], [2, 4]]

Гистограммы

Histogram

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

d3.histogram() Исходный код

Создаёт новый генератор гистограмм со значениями по умолчанию.

histogram(data) Исходный код

Вычисляет гистограмму для заданного массива выборок data. Возвращает массив ячеек, где каждая ячейка — массив, содержащий соответствующие элементы из входных data. Таким образом, length ячейки — количество элементов в этой ячейке. У каждой ячейки есть два дополнительных атрибута:

x0 — нижняя граница ячейки (включая).
x1 — верхняя граница ячейки (исключая, за исключением последней ячейки).

histogram.value([value]) Исходный код

Если value указано, устанавливает функцию или константу доступа к значению и возвращает этот генератор гистограмм. Если value не указано, возвращает текущую функцию доступа к значению, которая по умолчанию является идентификационной функцией.

Когда генерируется гистограмма, функция доступа к значению вызывается для каждого элемента в массиве входных данных, получая элемент d, индекс i и массив data в качестве трёх аргументов. По умолчанию функция доступа к значению предполагает, что входные данные упорядочиваются (сравниваются), например, числа или даты. Если ваши данные не упорядочиваются, вы должны указать функцию доступа, возвращающую соответствующее упорядоченное значение для данного элемента данных.

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

histogram.domain([domain]) Исходный код

Если domain указано, устанавливает функцию или массив доступа к области и возвращает этот генератор гистограмм. Если domain не указано, возвращает текущую функцию доступа к области, которая по умолчанию равна extent. Область гистограммы определяется как массив [min, max], где min — минимальное наблюдаемое значение, а max — максимальное наблюдаемое значение; оба значения включаются. Любое значение вне этой области будет проигнорировано при генерации гистограммы.

Например, если вы используете гистограмму совместно с линейной шкалой x, вы можете сказать:

var histogram = d3.histogram()
    .domain(x.domain())
    .thresholds(x.ticks(20));

Затем вы можете вычислить ячейки из массива чисел следующим образом:

var bins = histogram(numbers);

Обратите внимание, что функция доступа к области вызывается для материализованного массива значений value, а не для массива входных данных.

histogram.thresholds([count]) Исходный код
histogram.thresholds([thresholds]) Исходный код

Если thresholds указано, устанавливает генератор пороговых значений и возвращает этот генератор гистограмм. Если thresholds не указано, возвращает текущий генератор пороговых значений, который по умолчанию реализует формулу Старджеса. (Таким образом, по умолчанию значения гистограммы должны быть числами!) Пороговые значения определяются как массив значений [x0, x1, …]. Любое значение, меньшее x0, будет помещено в первую ячейку; любое значение, большее или равное x0, но меньшее x1, будет помещено во вторую ячейку; и так далее. Таким образом, сгенерированная гистограмма будет иметь thresholds.length + 1 ячеек. См. пороговые значения гистограммы для получения дополнительной информации.

Любые пороговые значения вне области domain игнорируются. Первое bin.x0 всегда равно минимальному значению области, а последнее bin.x1 всегда равно максимальному значению области.

Если вместо массива thresholds указано count, то область domain будет разделена приблизительно на count ячеек; см. ticks.

Пороговые значения гистограммы

Эти функции обычно не используются напрямую; вместо этого передайте их в histogram.thresholds. Вы также можете реализовать свой собственный генератор пороговых значений, принимающий три аргумента: массив входных значений из данных и область наблюдения, представленную как min и max. Генератор может вернуть либо массив числовых пороговых значений, либо количество ячеек; в последнем случае область разделяется равномерно примерно на count ячеек; см. ticks.

d3.thresholdFreedmanDiaconis(values, min, max) Исходный код

Возвращает количество ячеек в соответствии с правилом Фридмана — Диакониса; входные values должны быть числами.

d3.thresholdScott(values, min, max) Исходный код

Возвращает количество ячеек в соответствии с правилом Скотта для нормального распределения; входные values должны быть числами.

d3.thresholdSturges(values) Исходный код

Возвращает количество ячеек в соответствии с формулой Старджеса; входные values должны быть числами.