d3-array

Данные в JavaScript часто представляются итерируемым объектом (таким как массив, множество или генератор), поэтому работа с итерируемыми объектами является распространённой задачей при анализе или визуализации данных. Например, вы можете взять непрерывный срез (подмножество) массива, отфильтровать массив с помощью предикатной функции или отобразить массив в параллельный набор значений с помощью функции преобразования. Перед изучением методов, предоставляемых d3-array, ознакомьтесь с мощными методами массивов, встроенными в 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. Вы также можете скачать последнюю версию с GitHub. Для обычного HTML в современных браузерах импортируйте d3-array из Skypack:

<script type="module">

import {min} from "https://cdn.skypack.dev/d3-array@3";

const m = min(array);

</script>

Для устаревших сред вы можете загрузить пакет UMD d3-array с npm-основанного CDN, такого как jsDelivr; экспортируется глобальная переменная d3:

<script src="https://cdn.jsdelivr.net/npm/d3-array@3"></script>
<script>

const m = d3.min(array);

</script>

Справочник API

• Статистика
• Поиск
• Преобразования
• Итерируемые объекты
• Множества
• Бинны
• Интернирование

Статистика

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

d3.min(iterable[, accessor]) · Исходный код, Примеры

Возвращает минимальное значение в заданном iterable в естественном порядке. Если iterable не содержит сравнимых значений, возвращает undefined. Можно указать необязательную функцию accessor, что эквивалентно вызову Array.from перед вычислением минимального значения.

В отличие от встроенной Math.min, этот метод игнорирует undefined, null и NaN значения; это полезно для игнорирования пропущенных данных. Кроме того, элементы сравниваются в естественном порядке, а не в числовом.

Например, минимум строк [“20”, “3”] — “20”, в то время как минимум чисел [20, 3] — 3.

См. также extent.

d3.minIndex(iterable[, accessor]) · Исходный код, Примеры

Возвращает индекс минимального значения в заданном iterable в естественном порядке. Если iterable не содержит сравнимых значений, возвращает -1. Можно указать необязательную функцию accessor, что эквивалентно вызову Array.from перед вычислением минимального значения.

В отличие от встроенной Math.min, этот метод игнорирует undefined, null и NaN значения; это полезно для игнорирования пропущенных данных. Кроме того, элементы сравниваются в естественном порядке, а не в числовом.

Например, минимум строк [“20”, “3”] — “20”, в то время как минимум чисел [20, 3] — 3.

d3.max(iterable[, accessor]) · Исходный код, Примеры

Возвращает максимальное значение в заданном iterable в естественном порядке. Если iterable не содержит сравнимых значений, возвращает undefined. Можно указать необязательную функцию accessor, что эквивалентно вызову Array.from перед вычислением максимального значения.

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

См. также extent.

d3.maxIndex(iterable[, accessor]) · Исходный код, Примеры

Возвращает индекс максимального значения в заданном iterable в естественном порядке. Если iterable не содержит сравнимых значений, возвращает -1. Можно указать необязательную функцию accessor, что эквивалентно вызову Array.from перед вычислением максимального значения.

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

d3.extent(iterable[, accessor]) · Исходный код, Примеры

Возвращает минимальное и максимальное значение в заданном iterable в естественном порядке. Если iterable не содержит сравнимых значений, возвращает [undefined, undefined]. Можно указать необязательную функцию accessor, что эквивалентно вызову Array.from перед вычислением extent.

d3.mode(iterable[, accessor]) · Исходный код, Примеры

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

d3.sum(iterable[, accessor]) · Исходный код, Примеры

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

d3.mean(итерируемый[, accessor]) · Исходный код, Примеры

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

d3.median(итерируемый[, accessor]) · Исходный код, Примеры

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

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

Аналогично median, но возвращает индекс элемента слева от медианы.

d3.cumsum(итерируемый[, accessor]) · Исходный код, Примеры

Возвращает кумулятивную сумму заданного итерируемого набора чисел в виде Float64Array той же длины. Если итерируемый набор не содержит чисел, возвращает нули. Можно указать необязательную функцию accessor, которая эквивалентна вызову Array.from перед вычислением кумулятивной суммы. Этот метод игнорирует значения 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, которая эквивалентна вызову array.map(accessor) перед вычислением квантили.

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

Аналогично quantile, но возвращает индекс слева от p.

d3.quantileSorted(массив, p[, accessor]) · Исходный код, Примеры

Аналогично quantile, но ожидает входной отсортированный массив значений. В отличие от quantile, функция доступа вызывается только для элементов, необходимых для вычисления квантили.

d3.rank(итерируемый[, компаратор]) · Исходный код, Примеры
d3.rank(итерируемый[, accessor])

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

d3.rank([{x: 1}, {}, {x: 2}, {x: 0}], d => d.x); // [1, NaN, 2, 0]
d3.rank(["b", "c", "b", "a"]); // [1, 3, 1, 0]
d3.rank([1, 2, 3], d3.descending); // [2, 1, 0]

d3.variance(итерируемый[, accessor]) · Исходный код, Примеры

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

d3.deviation(итерируемый[, accessor]) · Исходный код, Примеры

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

d3.fsum([значения][, accessor]) · Исходный код, Примеры

Возвращает полную сумму с высокой точностью для заданных значений.

d3.fsum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]); // 1
d3.sum([.1, .1, .1, .1, .1, .1, .1, .1, .1, .1]); // 0.9999999999999999

Несмотря на то, что d3.fsum медленнее, он может заменить d3.sum там, где требуется большая точность. Использует d3.Adder.

d3.fcumsum([значения][, accessor]) · Исходный код, Примеры

Возвращает кумулятивную сумму с высокой точностью для заданных значений.

d3.fcumsum([1, 1e-14, -1]); // [1, 1.00000000000001, 1e-14]
d3.cumsum([1, 1e-14, -1]); // [1, 1.00000000000001, 9.992e-15]

Несмотря на то, что d3.fcumsum медленнее, он может заменить d3.cumsum, когда требуется большая точность. Использует d3.Adder.

new d3.Adder()

Создает полное суммирование с высокой точностью для чисел с плавающей точкой IEEE 754, установив его начальное значение в 0.

adder.add(число)

Добавляет указанное число к текущему значению суммирования и возвращает суммирующий объект.

adder.valueOf()

Возвращает представление двойной точности IEEE 754 текущего значения суммирующего объекта. Наиболее полезно как краткая запись +adder.

Поиск

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

d3.least(итерируемый[, компаратор]) · Исходный код, Примеры
d3.least(итерируемый[, accessor])

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

const array = [{foo: 42}, {foo: 91}];
d3.least(array, (a, b) => a.foo - b.foo); // {foo: 42}
d3.least(array, (a, b) => b.foo - a.foo); // {foo: 91}
d3.least(array, a => a.foo); // {foo: 42}

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

d3.leastIndex(итерируемый[, компаратор]) · Исходный код, Примеры
d3.leastIndex(итерируемый[, accessor])

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

const array = [{foo: 42}, {foo: 91}];
d3.leastIndex(array, (a, b) => a.foo - b.foo); // 0
d3.leastIndex(array, (a, b) => b.foo - a.foo); // 1
d3.leastIndex(array, a => a.foo); // 0

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

d3.greatest(итерируемый[, компаратор]) · Исходный код, Примеры
d3.greatest(итерируемый[, accessor])

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

const array = [{foo: 42}, {foo: 91}];
d3.greatest(array, (a, b) => a.foo - b.foo); // {foo: 91}
d3.greatest(array, (a, b) => b.foo - a.foo); // {foo: 42}
d3.greatest(array, a => a.foo); // {foo: 91}

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

d3.greatestIndex(iterable[, comparator]) · Source, Примеры
d3.greatestIndex(iterable[, accessor])

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

const array = [{foo: 42}, {foo: 91}];
d3.greatestIndex(array, (a, b) => a.foo - b.foo); // 1
d3.greatestIndex(array, (a, b) => b.foo - a.foo); // 0
d3.greatestIndex(array, a => a.foo); // 1

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

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

Возвращает точку вставки для x в array для поддержания упорядоченного порядка. Аргументы lo и hi могут использоваться для указания подмножества массива, которое следует рассматривать; по умолчанию используется весь массив. Если x уже присутствует в array, точка вставки будет перед (слева от) любыми существующими записями. Возвращаемое значение подходит для использования в качестве первого аргумента к splice, предполагая, что array уже отсортирован. Возвращаемая точка вставки i разделяет array на две половины таким образом, что все 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]])

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

d3.bisectCenter(array, x[, lo[, hi]]) · Source, Примеры

Возвращает индекс значения, наиболее близкого к x в заданном array чисел. Аргументы lo (включительно) и hi (исключительно) могут использоваться для указания подмножества массива, которое следует рассматривать; по умолчанию используется весь массив.

См. bisector.center.

d3.bisector(accessor) · Source
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]]) · Source

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

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

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

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

Возвращает индекс ближайшего значения к x в заданном отсортированном array. Это предполагает, что ассоциированный аксессор бисектора возвращает количественное значение или что ассоциированный компаратор бисектора возвращает подписанное расстояние; в противном случае этот метод эквивалентен bisector.left.

d3.quickselect(array, k, left = 0, right = array.length - 1, compare = ascending) · Source, Примеры

См. mourner/quickselect.

d3.ascending(a, b) · Source, Примеры

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

function ascending(a, b) {
  return a == null || b == null ? NaN : 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 a == null || b == null ? NaN : b < a ? -1 : b > a ? 1 : b >= a ? 0 : NaN;
}

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

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

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

d3.group(iterable, ...keys) · Source, Примеры

Группирует указанное iterable значений в InternMap из key к массиву значений. Например, заданы некоторые данные:

data = [
  {name: "jim",   amount: "34.0",   date: "11/12/2015"},
  {name: "carl",  amount: "120.11", date: "11/12/2015"},
  {name: "stacy", amount: "12.01",  date: "01/04/2016"},
  {name: "stacy", amount: "34.05",  date: "01/04/2016"}
]

Для группировки данных по имени:

d3.group(data, d => d.name)

Это даёт:

Map(3) {
  "jim" => Array(1)
  "carl" => Array(1)
  "stacy" => Array(2)
}

Если указано более одного key, возвращается вложенный InternMap. Например:

d3.group(data, d => d.name, d => d.date)

Это даёт:

Map(3) {
  "jim" => Map(1) {
    "11/12/2015" => Array(1)
  }
  "carl" => Map(1) {
    "11/12/2015" => Array(1)
  }
  "stacy" => Map(1) {
    "01/04/2016" => Array(2)
  }
}

Чтобы преобразовать Map в массив, используйте Array.from. Например:

Array.from(d3.group(data, d => d.name))

Это даёт:

[
  ["jim", Array(1)],
  ["carl", Array(1)],
  ["stacy", Array(2)]
]

Вы также можете одновременно преобразовать [key, value] в другую форму, передав функцию преобразования в Array.from:

Array.from(d3.group(data, d => d.name), ([key, value]) => ({key, value}))

Это даёт:

[
  {key: "jim", value: Array(1)},
  {key: "carl", value: Array(1)},
  {key: "stacy", value: Array(2)}
]

selection.data принимает iterable напрямую, что означает, что вы можете использовать Map (или Set или другие iterable) для выполнения соединения данных без предварительного преобразования в массив.

d3.groups(iterable, ...keys) · Source, Примеры

Эквивалентно group, но возвращает вложенные массивы вместо вложенных карт.

d3.flatGroup(iterable, ...keys) · Source, Примеры

Эквивалентно group, но возвращает плоский массив [key0, key1, …, values] вместо вложенных карт.

d3.index(iterable, ...keys) · Source, Примеры

Эквивалентно group, но возвращает уникальное значение на составной ключ вместо массива, выбрасывая ошибку, если ключ не уникален.

Например, заданы данные, определённые выше,

d3.index(data, d => d.amount)

возвращает

Map(4) {
  "34.0" => Object {name: "jim", amount: "34.0", date: "11/12/2015"}
  "120.11" => Object {name: "carl", amount: "120.11", date: "11/12/2015"}
  "12.01" => Object {name: "stacy", amount: "12.01", date: "01/04/2016"}
  "34.05" => Object {name: "stacy", amount: "34.05", date: "01/04/2016"}
}

С другой стороны,

d3.index(data, d => d.name)

выбрасывает ошибку, потому что два объекта имеют одинаковое имя.

d3.indexes(iterable, ...keys) · Source, Примеры

Эквивалентно index, но возвращает вложенные массивы вместо вложенных карт.

d3.rollup(iterable, reduce, ...keys) · Source, Примеры

Группирует и сводит указанный итерируемый набор значений в InternMap из ключа в значение. Например, при наличии данных:

data = [
  {name: "jim",   amount: "34.0",   date: "11/12/2015"},
  {name: "carl",  amount: "120.11", date: "11/12/2015"},
  {name: "stacy", amount: "12.01",  date: "01/04/2016"},
  {name: "stacy", amount: "34.05",  date: "01/04/2016"}
]

Для подсчёта количества элементов по имени:

d3.rollup(data, v => v.length, d => d.name)

Это даёт:

Map(3) {
  "jim" => 1
  "carl" => 1
  "stacy" => 2
}

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

d3.rollup(data, v => v.length, d => d.name, d => d.date)

Это даёт:

Map(3) {
  "jim" => Map(1) {
    "11/12/2015" => 1
  }
  "carl" => Map(1) {
    "11/12/2015" => 1
  }
  "stacy" => Map(1) {
    "01/04/2016" => 2
  }
}

Для преобразования карты в массив используйте Array.from. Смотрите d3.group для примеров.

d3.rollups(iterable, reduce, ...keys) · Source, Примеры

Эквивалентно rollup, но возвращает вложенные массивы вместо вложенных карт.

d3.flatRollup(iterable, reduce, ...keys) · Source, Примеры

Эквивалентно rollup, но возвращает плоский массив [key0, key1, …, value] вместо вложенных карт.

d3.groupSort(iterable, comparator, key) · Source, Примеры
d3.groupSort(iterable, accessor, key)

Группирует указанный итерируемый набор элементов в соответствии с указанной функцией key, сортирует группы в соответствии с указанным comparator, а затем возвращает массив ключей в отсортированном порядке. Например, если у вас есть таблица урожаев ячменя для различных сортов, мест и годов, для сортировки сортов ячменя по возрастанию медианного урожая:

d3.groupSort(barley, g => d3.median(g, d => d.yield), d => d.variety)

Для убывающего порядка, отрицаем значение группы:

d3.groupSort(barley, g => -d3.median(g, d => d.yield), d => d.variety)

Если вместо accessor передаётся comparator (то есть, если второй аргумент — функция, принимающая ровно два аргумента), она будет сравнивать две группы a и b и должна возвращать отрицательное значение, если a должно стоять перед b, положительное значение, если a должно стоять после b, или ноль для частичного упорядочения.

d3.count(iterable[, accessor]) · Source, Примеры

Возвращает количество действительных числовых значений (т.е., не null, NaN или undefined) в заданном итерируемом; принимает функцию-аксессор.

Например:

d3.count([{n: "Alice", age: NaN}, {n: "Bob", age: 18}, {n: "Other"}], d => d.age) // 1

d3.cross(...iterables[, 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(iterables) · Source, Примеры

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

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

d3.pairs(iterable[, 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(source, keys) · Source, Примеры

Возвращает перестановку указанного объекта source (или массива) с использованием указанного итерируемого набора ключей. Возвращаемый массив содержит соответствующее свойство объекта source для каждого ключа в keys, в порядке. Например:

permute(["a", "b", "c"], [1, 2, 0]); // returns ["b", "c", "a"]

Допустимо, чтобы ключей было больше, чем элементов source, и чтобы ключи были дублированы или опущены.

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

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

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

d3.shuffle(array[, start[, stop]]) · Source, Примеры

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

d3.shuffler(random) · Source

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

const random = d3.randomLcg(0.9051667019185816);
const shuffle = d3.shuffler(random);

shuffle([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); // returns [7, 4, 5, 3, 9, 0, 6, 1, 2, 8]

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 всегда меньше или равен stop, и если шаг деления для заданных start, stop и count был бы меньше единицы, возвращается обратный шаг деления. Этот метод всегда гарантирует возврат целого числа и используется в d3.ticks для обеспечения того, что возвращаемые значения деления представляются как можно точнее в формате IEEE 754 с плавающей запятой.

d3.tickStep(start, stop, count) · Source, Примеры

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

d3.nice(start, stop, count) · Source

Возвращает новый интервал [niceStart, niceStop], охватывающий данный интервал [start, stop], где niceStart и niceStop гарантированно согласованы с соответствующим шагом деления. Как и в d3.tickIncrement, это требует, чтобы start было меньше или равно stop.

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]

Это неожиданное поведение обусловлено 64-битной плавающей точкой 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]]

Размытие

d3.blur(data, radius) · Source, Примеры

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

const randomWalk = d3.cumsum({length: 1000}, () => Math.random() - 0.5);
blur(randomWalk, 5);

Скопируйте данные, если вы не хотите размыть их на месте:

const smoothed = blur(randomWalk.slice(), 5);

d3.blur2({data, width[, height]}, rx[, ry]) · Source, Примеры

Размывает матрицу заданной width и height на месте, применяя горизонтальное размытие радиусом rx и вертикальное размытие радиусом ry (по умолчанию rx). Матрица data хранится в плоском массиве, используемом для определения height, если она не указана. Возвращает размытую {data, width, height}.

data = [
  1, 0, 0,
  0, 0, 0,
  0, 0, 1
];
blur2({data, width: 3}, 1);

d3.blurImage(imageData, rx[, ry]) · Source, Примеры

Размывает структуру ImageData на месте, размывая каждый из слоёв RGBA независимо, применяя горизонтальное размытие радиусом rx и вертикальное размытие радиусом ry (по умолчанию rx). Возвращает размытую ImageData.

const imData = context.getImageData(0, 0, width, height);
blurImage(imData, 5);

Итерируемые объекты

Эти методы эквивалентны встроенным методам массивов, но работают с любым итерируемым объектом, включая Map, Set и Generator.

d3.every(iterable, test) · Source

Возвращает true, если заданная функция test возвращает true для каждого значения в заданном iterable. Этот метод возвращает значение, как только test возвращает неправдивое значение или все значения перебираются. Эквивалентно array.every:

d3.every(new Set([1, 3, 5, 7]), x => x & 1) // true

d3.some(iterable, test) · Source

Возвращает true, если заданная функция test возвращает true для любого значения в заданном iterable. Этот метод возвращает значение, как только test возвращает истинное значение или все значения перебираются. Эквивалентно array.some:

d3.some(new Set([0, 2, 3, 4]), x => x & 1) // true

d3.filter(iterable, test) · Source

Возвращает новый массив, содержащий значения из iterable в порядке, для которых заданная функция test возвращает true. Эквивалентно array.filter:

d3.filter(new Set([0, 2, 3, 4]), x => x & 1) // [3]

d3.map(iterable, mapper) · Source

Возвращает новый массив, содержащий отображённые значения из iterable в порядке, как определено заданной функцией mapper. Эквивалентно array.map и Array.from:

d3.map(new Set([0, 2, 3, 4]), x => x & 1) // [0, 0, 1, 0]

d3.reduce(iterable, reducer[, initialValue]) · Source

Возвращает уменьшенное значение, определённое заданной функцией reducer, которая многократно вызывается для каждого значения в iterable, передавая текущее уменьшенное значение и следующее значение. Эквивалентно array.reduce:

d3.reduce(new Set([0, 2, 3, 4]), (p, v) => p + v, 0) // 9

d3.reverse(iterable) · Source

Возвращает массив, содержащий значения в заданном iterable в обратном порядке. Эквивалентно array.reverse, за исключением того, что не изменяет заданный iterable:

d3.reverse(new Set([0, 2, 3, 1])) // [1, 3, 2, 0]

d3.sort(iterable, comparator = d3.ascending) · Source
d3.sort(iterable, ...accessors)

Возвращает массив, содержащий значения в заданном iterable в отсортированном порядке, определённом заданной функцией comparator или accessor. Если comparator не указан, он по умолчанию равен d3.ascending. Эквивалентно array.sort, за исключением того, что не изменяет заданный iterable, и компаратор по умолчанию устанавливается в естественный порядок вместо лексикографического:

d3.sort(new Set([0, 2, 3, 1])) // [0, 1, 2, 3]

Если указан accessor (функция, которая не принимает ровно два аргумента),

d3.sort(data, d => d.value)

это эквивалентно comparator с использованием естественного порядка:

d3.sort(data, (a, b) => d3.ascending(a.value, b.value))

Accessor вызывается только один раз на каждый элемент, и поэтому возвращаемый отсортированный порядок согласован, даже если accessor не является детерминированным.

Можно указать несколько accessor для обработки совпадений:

d3.sort(points, ({x}) => x, ({y}) => y)

Это эквивалентно:

d3.sort(data, (a, b) => d3.ascending(a.x, b.x) || d3.ascending(a.y, b.y))

Множества

Эти методы реализуют основные операции над множествами для любого итерируемого объекта.

d3.difference(iterable, ...others) · Source

Возвращает новое множество InternSet, содержащее все значения из iterable, которые не находятся ни в одном из others итерируемых объектов.

d3.difference([0, 1, 2, 0], [1]) // Set {0, 2}

d3.union(...iterables) · Source

Возвращает новое множество InternSet, содержащее каждое (различное) значение, которое встречается в любом из заданных iterables. Порядок значений в возвращаемом множестве основан на их первом появлении в заданных iterables.

d3.union([0, 2, 1, 0], [1, 3]) // Set {0, 2, 1, 3}

d3.intersection(...iterables) · Source

Возвращает новое множество InternSet, содержащее каждое (различное) значение, которое встречается во всех заданных iterables. Порядок значений в возвращаемом множестве основан на их первом появлении в заданных iterables.

d3.intersection([0, 2, 1, 0], [1, 3]) // Set {1}

d3.superset(a, b) · Source

Возвращает true, если a является надмножеством b: если каждое значение в заданном итерируемом b также присутствует в заданном итерируемом a.

d3.superset([0, 2, 1, 3, 0], [1, 3]) // true

d3.subset(a, b) · Source

Возвращает true, если a является подмножеством b: если каждое значение в заданном итерируемом a также присутствует в заданном итерируемом b.

d3.subset([1, 3], [0, 2, 1, 3, 0]) // true

d3.disjoint(a, b) · Source

Возвращает true, если a и b не пересекаются: если a и b не содержат общих значений.

d3.disjoint([1, 3], [2, 4]) // true

Бины

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

d3.bin() · Исходный код, Примеры

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

bin(data) · Исходный код, Примеры

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

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

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

bin.value([value]) · Исходный код, Примеры

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

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

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

bin.domain([domain]) · Исходный код, Примеры

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

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

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

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

var bins = bin(numbers);

Если используется домен по умолчанию extent, и пороговые значения заданы как количество (а не явными значениями), то вычисленный домен будет улучшен таким образом, что все бины имеют равную ширину.

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

bin.thresholds([count]) · Исходный код, Примеры
bin.thresholds([thresholds])

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

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

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

Пороговые значения бинов

Эти функции обычно не используются напрямую; вместо этого передавайте их в bin.thresholds.

d3.thresholdFreedmanDiaconis(values, min, max) · Исходный код, Примеры

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

d3.thresholdScott(values, min, max) · Исходный код, Примеры

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

d3.thresholdSturges(values) · Исходный код, Примеры

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

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

Например, при бинировании значений дат, вы можете использовать метки с масштабом времени (Пример).

Интернирование

new d3.InternMap([iterable][, key]) · Исходный код, Примеры
new d3.InternSet([iterable][, key]) · Исходный код, Примеры

Классы InternMap и InternSet расширяют классы JavaScript Map и Set соответственно, позволяя использовать даты и другие не примитивные ключи, минуя алгоритм SameValueZero при определении равенства ключей. d3.group, d3.rollup и d3.index используют InternMap вместо обычного Map. Эти два класса экспортированы для удобства.