d3-array

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

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

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

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

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

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

массив.filter - Создаёт новый массив, содержащий только элементы, для которых предикат истиннен.
массив.forEach - Вызывает функцию для каждого элемента в массиве.
массив.every - Проверяет, удовлетворяют ли все элементы массива предикату.
массив.map - Создаёт новый массив с результатом вызова функции для каждого элемента в массиве.
массив.some - Проверяет, удовлетворяет ли хотя бы один элемент массива предикату.
массив.reduce - Применяет функцию для сокращения массива до единственного значения (слева направо).
массив.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(массив[, accessor]) Исходный код

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

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

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

d3.max(массив[, accessor]) Исходный код

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

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

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

d3.extent(массив[, accessor]) Исходный код

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

d3.sum(массив[, accessor]) Исходный код

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

d3.mean(массив[, accessor]) Исходный код

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

d3.median(массив[, accessor]) Исходный код

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

d3.quantile(массив, 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, что эквивалентно вызову массив.map(accessor) перед вычислением квантиля.

d3.variance(массив[, accessor]) Исходный код

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

d3.deviation(массив[, accessor]) Исходный код

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

Поиск

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

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

Выполняет линейный поиск в указанном массиве, возвращая индекс наименьшего элемента в соответствии с указанным comparator. Если заданный массив не содержит сравнимых элементов (т.е., comparator возвращает NaN при сравнении каждого элемента с самим собой), возвращает undefined. Если comparator не указан, по умолчанию используется 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]]) Источник

Возвращает точку вставки для 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]]) Источник
d3.bisectRight(array, x[, lo[, hi]]) Источник

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

d3.bisector(accessor) Источник
d3.bisector(comparator) Источник

Возвращает новый бисектор, использующий указанную функцию 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]]) Источник

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

bisector.right(array, x[, lo[, hi]]) Источник

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

d3.ascending(a, b) Источник

Возвращает -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) Источник

Возвращает -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]) Источник

Возвращает декартово произведение двух массивов 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) Источник

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

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

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

Для каждой смежной пары элементов в заданном массиве, в порядке, вызывает заданную функцию 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) Источник

Возвращает перестановку указанного массива, используя указанный массив indexes. Возвращаемый массив содержит соответствующий элемент в массиве для каждого индекса в indexes, в порядке. Например, 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[, start[, stop]]) Источник

Перемешивает порядок заданного массива на месте с помощью перемешивания Фишера–Йейтса и возвращает массив. Если start указан, он является начальным индексом (включительно) массива для перемешивания; если start не указан, он по умолчанию равен нулю. Если stop указан, он является конечным индексом (исключительно) массива для перемешивания; если stop не указан, он по умолчанию равен array.length. Например, чтобы перемешать первые десять элементов массива: shuffle(array, 0, 10).

d3.ticks(start, stop, count) Источник

Возвращает массив примерно из 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) Источник

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

END_OF_DOCUMENT_MARKER

d3.tickStep(start, stop, count) Source

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

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

Возвращает массив, содержащий арифметическую прогрессию, аналогично встроенной функции range в Python. Этот метод часто используется для итерации по последовательности равномерно распределённых числовых значений, таких как индексы массива или метки линейной шкалы. (См. также 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) Source

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

d3.zip(arrays…) Source

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

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

Гистограммы

Histogram

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

d3.histogram() Source

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

histogram(data) Source

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

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

histogram.value([value]) Source

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

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

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

histogram.domain([domain]) Source

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

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

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

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

var bins = histogram(numbers);

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

histogram.thresholds([count]) Source
histogram.thresholds([thresholds]) Source

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

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

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

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

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

d3.thresholdFreedmanDiaconis(values, min, max) Source

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

d3.thresholdScott(values, min, max) Source

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

d3.thresholdSturges(values) Source

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