Transformations

/**
 * Groups the specified iterable into an InternMap from key to array of values
 * @param iterable - The iterable to group
 * @param keys - One or more key functions for grouping
 * @returns InternMap with grouped values
 */
function group(iterable: Iterable<any>, ...keys: Array<(d: any) => any>): InternMap<any, any>;

import { group } from "d3-array";

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

// Single level grouping
group(data, d => d.name);
// Map(3) {
//   "jim" => Array(1) [{name: "jim", amount: "34.0", date: "11/12/2015"}]
//   "carl" => Array(1) [{name: "carl", amount: "120.11", date: "11/12/2015"}]
//   "stacy" => Array(2) [...]
// }

// Nested grouping
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) }
// }

/**
 * Equivalent to group, but returns nested arrays instead of nested maps
 * @param iterable - The iterable to group
 * @param keys - One or more key functions for grouping
 * @returns Nested arrays with grouped values
 */
function groups(iterable: Iterable<any>, ...keys: Array<(d: any) => any>): any[];

/**
 * Equivalent to group, but returns a flat array of [key0, key1, ..., values]
 * @param iterable - The iterable to group
 * @param keys - One or more key functions for grouping
 * @returns Flat array of [key0, key1, ..., values] arrays
 */
function flatGroup(iterable: Iterable<any>, ...keys: Array<(d: any) => any>): any[];

/**
 * Groups and reduces the specified iterable into an InternMap from key to reduced value
 * @param iterable - The iterable to group and reduce
 * @param reduce - Function to reduce each group to a single value
 * @param keys - One or more key functions for grouping
 * @returns InternMap with reduced values
 */
function rollup(
  iterable: Iterable<any>, 
  reduce: (values: any[]) => any, 
  ...keys: Array<(d: any) => any>
): InternMap<any, any>;

import { rollup } from "d3-array";

const data = [
  {name: "jim", amount: "34.0"},
  {name: "carl", amount: "120.11"},
  {name: "stacy", amount: "12.01"},
  {name: "stacy", amount: "34.05"}
];

// Count by name
rollup(data, v => v.length, d => d.name);
// Map(3) { "jim" => 1, "carl" => 1, "stacy" => 2 }

// Sum amounts by name
rollup(data, v => v.reduce((sum, d) => sum + parseFloat(d.amount), 0), d => d.name);
// Map(3) { "jim" => 34.0, "carl" => 120.11, "stacy" => 46.06 }

/**
 * Equivalent to rollup, but returns nested arrays instead of nested maps
 * @param iterable - The iterable to group and reduce
 * @param reduce - Function to reduce each group to a single value
 * @param keys - One or more key functions for grouping
 * @returns Nested arrays with reduced values
 */
function rollups(
  iterable: Iterable<any>, 
  reduce: (values: any[]) => any, 
  ...keys: Array<(d: any) => any>
): any[];

/**
 * Equivalent to rollup, but returns a flat array of [key0, key1, ..., value]
 * @param iterable - The iterable to group and reduce
 * @param reduce - Function to reduce each group to a single value
 * @param keys - One or more key functions for grouping
 * @returns Flat array of [key0, key1, ..., value] arrays
 */
function flatRollup(
  iterable: Iterable<any>, 
  reduce: (values: any[]) => any, 
  ...keys: Array<(d: any) => any>
): any[];

/**
 * Equivalent to group but returns a unique value per compound key instead of an array
 * @param iterable - The iterable to index
 * @param keys - One or more key functions for indexing
 * @returns InternMap with unique values
 * @throws Error if keys are not unique
 */
function index(iterable: Iterable<any>, ...keys: Array<(d: any) => any>): InternMap<any, any>;

import { index } from "d3-array";

const data = [
  {amount: "34.0", name: "jim"},
  {amount: "120.11", name: "carl"},
  {amount: "12.01", name: "stacy"},
  {amount: "34.05", name: "other"}
];

// Index by unique amounts
index(data, d => d.amount);
// Map(4) {
//   "34.0" => {amount: "34.0", name: "jim"}
//   "120.11" => {amount: "120.11", name: "carl"}
//   "12.01" => {amount: "12.01", name: "stacy"}
//   "34.05" => {amount: "34.05", name: "other"}
// }

// This would throw an error (duplicate names):
// index(data, d => d.name); // Error: duplicate key

/**
 * Equivalent to index, but returns nested arrays instead of nested maps
 * @param iterable - The iterable to index
 * @param keys - One or more key functions for indexing
 * @returns Nested arrays with unique values
 * @throws Error if keys are not unique
 */
function indexes(iterable: Iterable<any>, ...keys: Array<(d: any) => any>): any[];

/**
 * Groups the specified iterable and returns an array of keys in sorted order
 * @param iterable - The iterable to group and sort
 * @param comparator - Comparator function for sorting groups
 * @param key - Key function for grouping
 * @returns Array of keys in sorted order
 */
function groupSort(
  iterable: Iterable<any>, 
  comparator: (a: any[], b: any[]) => number, 
  key: (d: any) => any
): any[];

/**
 * Groups the specified iterable and returns an array of keys in sorted order
 * @param iterable - The iterable to group and sort
 * @param accessor - Function to compute sort value from each group
 * @param key - Key function for grouping
 * @returns Array of keys in sorted order
 */
function groupSort(
  iterable: Iterable<any>, 
  accessor: (group: any[]) => any, 
  key: (d: any) => any
): any[];

import { groupSort, median } from "d3-array";

const barley = [
  {variety: "Manchuria", yield: 27},
  {variety: "Wisconsin", yield: 29},
  {variety: "Manchuria", yield: 31},
  {variety: "Wisconsin", yield: 33}
];

// Sort varieties by ascending median yield
groupSort(barley, g => median(g, d => d.yield), d => d.variety);
// ["Manchuria", "Wisconsin"]

// Sort varieties by descending median yield
groupSort(barley, g => -median(g, d => d.yield), d => d.variety);
// ["Wisconsin", "Manchuria"]

/**
 * Returns the Cartesian product of the specified iterables
 * @param iterables - The iterables to compute the cross product of
 * @param reducer - Optional function to combine elements (defaults to creating pairs)
 * @returns Array of combined elements
 */
function cross(...iterables: Iterable<any>[]): any[];
function cross(...iterables: [...Iterable<any>[], ((...values: any[]) => any)]): any[];

import { cross } from "d3-array";

// Basic cross product
cross([1, 2], ["x", "y"]); 
// [[1, "x"], [1, "y"], [2, "x"], [2, "y"]]

// With custom reducer
cross([1, 2], ["x", "y"], (a, b) => a + b); 
// ["1x", "1y", "2x", "2y"]

/**
 * Merges the specified iterable of iterables into a single array
 * @param iterables - Iterable of iterables to merge
 * @returns Flattened array
 */
function merge(iterables: Iterable<Iterable<any>>): any[];

import { merge } from "d3-array";

merge([[1], [2, 3]]); // [1, 2, 3]
merge([new Set([1, 2]), [3, 4]]); // [1, 2, 3, 4]

/**
 * For each adjacent pair of elements, invokes the specified reducer function
 * @param iterable - The iterable to process
 * @param reducer - Function to combine adjacent pairs (defaults to creating pairs)
 * @returns Array of processed pairs
 */
function pairs(iterable: Iterable<any>, reducer?: (a: any, b: any) => any): any[];

import { pairs } from "d3-array";

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

/**
 * Returns a permutation of the specified source using the specified iterable of keys
 * @param source - The source array or object
 * @param keys - The keys specifying the order
 * @returns Permuted array
 */
function permute(source: any[] | Record<string, any>, keys: Iterable<string | number>): any[];

import { permute } from "d3-array";

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

// Object permutation
const obj = {yield: 27, variety: "Manchuria", year: 1931, site: "University Farm"};
const fields = ["site", "variety", "yield"];
permute(obj, fields); // ["University Farm", "Manchuria", 27]

/**
 * Randomizes the order of the specified array in-place using Fisher–Yates shuffle
 * @param array - The array to shuffle (modified in-place)
 * @param start - Starting index (inclusive, defaults to 0)
 * @param stop - Ending index (exclusive, defaults to array.length)
 * @returns The shuffled array
 */
function shuffle(array: any[], start?: number, stop?: number): any[];

/**
 * Returns a shuffle function given the specified random source
 * @param random - Random number generator function
 * @returns Shuffle function using the specified random source
 */
function shuffler(random: () => number): (array: any[], start?: number, stop?: number) => any[];

import { shuffle, shuffler } from "d3-array";

// Basic shuffle
const arr = [1, 2, 3, 4, 5];
shuffle(arr); // Randomly reorders arr in-place

// Shuffle with range
shuffle(arr, 0, 3); // Only shuffles first 3 elements

// Custom random source
import { randomLcg } from "d3-random";
const random = randomLcg(0.9051667019185816);
const customShuffle = shuffler(random);
customShuffle([0, 1, 2, 3, 4, 5, 6, 7, 8, 9]); // [7, 4, 5, 3, 9, 0, 6, 1, 2, 8]

/**
 * Uses the zip operator as a two-dimensional matrix transpose
 * @param matrix - Matrix to transpose (array of arrays)
 * @returns Transposed matrix
 */
function transpose(matrix: any[][]): any[][];

/**
 * Returns an array of arrays, where the ith array contains the ith element from each argument
 * @param arrays - Arrays to zip together
 * @returns Array of arrays with combined elements
 */
function zip(...arrays: any[][]): any[][];

import { zip, transpose } from "d3-array";

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

const matrix = [[1, 2], [3, 4], [5, 6]];
transpose(matrix); // [[1, 3, 5], [2, 4, 6]]

/**
 * Blurs an array of data in-place using moving average transform
 * @param data - Array to blur (modified in-place)
 * @param radius - Blur radius (non-negative number)
 * @returns The blurred array
 */
function blur(data: number[], radius: number): number[];

/**
 * Blurs a matrix in-place by applying horizontal and vertical blur operations
 * @param options - Object with data array and width/height dimensions
 * @param rx - Horizontal blur radius
 * @param ry - Vertical blur radius (defaults to rx)
 * @returns Object with blurred data, width, and height
 */
function blur2(
  options: {data: number[], width: number, height?: number}, 
  rx: number, 
  ry?: number
): {data: number[], width: number, height: number};

/**
 * Blurs an ImageData structure in-place, blurring each RGBA channel independently
 * @param imageData - ImageData object to blur (modified in-place)
 * @param rx - Horizontal blur radius
 * @param ry - Vertical blur radius (defaults to rx)
 * @returns The blurred ImageData
 */
function blurImage(imageData: ImageData, rx: number, ry?: number): ImageData;

import { blur, blur2, blurImage } from "d3-array";

// 1D blur
const randomWalk = [/* cumulative sum of random values */];
blur(randomWalk, 5); // Smooths the data with radius 5

// 2D blur
const data = [1, 0, 0, 0, 0, 0, 0, 0, 1];
blur2({data, width: 3}, 1); // Blurs 3x3 matrix

// Image blur
const canvas = document.createElement('canvas');
const context = canvas.getContext('2d');
const imageData = context.getImageData(0, 0, width, height);
blurImage(imageData, 5); // Blurs image with radius 5