d3-array

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

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

var min = 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 перед вычислением границ.

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

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

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

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

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

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

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

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

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

Возвращает p-квантиль заданного iterable чисел, где 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.quantileSorted(array, p[, accessor]) · Source, Примеры

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

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

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

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

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

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

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

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([values][, accessor]) · Source, Примеры

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

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(number)

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

adder.valueOf()

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

Поиск

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

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

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

Возвращает индекс наименьшего элемента заданного iterable согласно заданному comparator или accessor. Если заданный iterable не содержит сравниваемых элементов (т.е., компаратор возвращает NaN при сравнении каждого элемента с самим собой), возвращает -1. Если comparator не указан, он по умолчанию равен 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(iterable[, comparator]) · Source, Примеры
d3.greatest(iterable[, accessor])

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

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}
];

Соответствующая функция bisect может быть построена следующим образом:

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 < b ? -1 : a > b ? 1 : a >= b ? 0 : NaN;
}

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

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

Группирует указанный iterable значений в 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.group(data, d => d.name)

Это даёт:

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

Если указано более одного ключа, возвращается вложенный 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)
  }
}

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

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

Это даёт:

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

Вы также можете одновременно преобразовать [ключ, значение] в другую форму представления, передав функцию отображения в 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 принимает iterables напрямую, что означает, что вы можете использовать Map (или Set или другие итерируемые объекты) для выполнения объединения данных без предварительного преобразования в массив.

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

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

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, Примеры

Группирует и сводит указанный iterable значений в 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, ...keys) · Source, Примеры

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

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

Группирует указанный iterable элементов согласно заданной функции 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) в указанном iterable; принимает аксессор.

Например:

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

d3.cross(...iterables[, reducer]) · Source, Примеры

Возвращает декартово произведение указанных iterables. Например, если указаны два iterables 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, Примеры

Объединяет указанную итерируемую последовательность iterables в один массив. Этот метод похож на встроенный метод массива 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 (или массива) с использованием указанной итерируемой последовательности keys. Возвращаемый массив содержит соответствующее свойство объекта 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, Примеры

Перемешивает порядок элементов в указанном массиве array на месте с помощью алгоритма Фишера—Йетса и возвращает массив. Если указан start, это начальный индекс (включительно) массива array, который нужно перемешать; если start не указан, он по умолчанию равен нулю. Если указан stop, это конечный индекс (исключительно) массива array, который нужно перемешать; если 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]

Это неожиданное поведение связано с точностью с плавающей точкой двойной точности 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-й элемент из каждого из аргументных массивов. Возвращаемый массив усекается по длине до самого короткого массива в массивах. Если массивы содержат только один массив, возвращаемый массив содержит массивы по одному элементу. Без аргументов возвращаемый массив пуст.

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

Итерируемые последовательности

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

d3.every(iterable, test) · Source

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

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

d3.some(iterable, test) · Source

Возвращает true, если заданная функция test возвращает true для любого значения в заданной итерируемой последовательности. Этот метод возвращает результат, как только 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. Функция 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

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

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

d3.union(...iterables) · Source

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

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

d3.intersection(...iterables) · Source

Возвращает новое множество, содержащее все (различные) значения, которые встречаются во всех заданных 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() · Source, Примеры

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

bin(data) · Source, Примеры

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

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

bin.value([value]) · Source, Примеры

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

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

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

bin.domain([domain]) · Source, Примеры

Если 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]) · Source, Примеры
bin.thresholds([thresholds])

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

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

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

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

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

d3.thresholdFreedmanDiaconis(values, min, max) · Source, Примеры

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

d3.thresholdScott(values, min, max) · Source, Примеры

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

d3.thresholdSturges(values) · Source, Примеры

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

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

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

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

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

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