d3-array summarize module
The summarize module provides functions to compute summary statistics.
d3-array
116 notes in this subject, read out of this brain and free to use. This is page 1 of 2.
d3-array ticks module
The ticks module provides functions to generate representative values from a continuous interval.
d3-array module overview
The d3-array module provides functions for array manipulation, ordering, searching, and summarizing. It contains the following categories of operations: adding numbers, binning data, bisecting data, blurring data, grouping data, interning values, set operations, sorting data, summarizing data, ticks, and transforming data.
d3-array transform module
The transform module provides functions to derive new arrays.
d3-array add module
The add module provides functions to add floating point values with full precision.
d3-array bin module
The bin module provides functions to bin discrete samples into continuous, non-overlapping intervals.
d3-array bisect module
The bisect module provides functions to quickly find a value in a sorted array.
d3-array blur module
The blur module provides functions to blur quantitative values in one or two dimensions.
d3-array group module
The group module provides functions to group discrete values.
d3-array intern module
The intern module provides functions to create maps and sets with non-primitive values such as dates.
d3-array sets module
The sets module provides functions for logical operations on sets.
d3-array sort module
The sort module provides functions to sort and reorder arrays of values.
fcumsum full-precision example
d3.fcumsum([1, 1e-14, -1]) returns [1, 1.00000000000001, 1e-14], demonstrating full-precision cumulative summation that correctly preserves very small values in the running sum.
Adder constructor
The d3.Adder constructor creates a new adder with an initial value of 0. Usage: const adder = new d3.Adder();
adder.valueOf() method
The valueOf method returns the IEEE 754 double-precision representation of the adder's current value. It can be used with the shorthand notation +adder or when coercing as Number(adder).
fsum full-precision example
d3.fsum([0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1, 0.1]) returns 1, demonstrating full-precision addition that handles floating point rounding errors correctly.
fcumsum signature and purpose
d3.fcumsum(values, accessor) returns a full-precision cumulative sum of the given values as a Float64Array. The values parameter is an array. The accessor parameter is optional; when specified, it is invoked for each element in values as accessor(d, i, data), and the returned values contribute to the cumulative sum. This provides greater precision than d3.cumsum.
adder.add() method
The add method accepts a number parameter, adds it to the adder's current value, and returns the adder for chaining. Usage: adder.add(42)
bisect function signature
d3.bisect(*array*, *x*, *lo*, *hi*) is an alias for bisectRight. It finds the insertion point for x in array to maintain sorted order, with optional lo and hi arguments to specify a subset.
bisector function signature and accessor
d3.bisector(*accessor*) returns a new bisector using the specified accessor function. The accessor can take one argument (element d) to extract the sort key, or two arguments (element d, search value x) to act as a comparator function comparing d with x.
bisector.left method signature
bisector.left(*array*, *x*, *lo*, *hi*) behaves like bisectLeft but uses the bisector's accessor. It returns an insertion point before any existing entries equivalent to x in array. All values v < x appear in array.slice(lo, i) and all v >= x appear in array.slice(i, hi).
bisector.center method signature
bisector.center(*array*, *x*, *lo*, *hi*) returns the index of the closest value to x in the given sorted array. The accessor should return a quantitative value, or the comparator should return a signed distance. The arguments lo (inclusive) and hi (exclusive) specify a subset; by default the entire array is considered.
bisectLeft function signature
d3.bisectLeft(*array*, *x*, *lo*, *hi*) returns the insertion point for x in array to maintain sorted order. The returned insertion point i partitions the array so that all v < x appear in array.slice(lo, i) and all v >= x appear in array.slice(i, hi). If x is already present, the insertion point will be before any existing entries.
bisectCenter function signature
d3.bisectCenter(*array*, *x*, *lo*, *hi*) returns the index of the value closest to x in the given array of numbers. The arguments lo (inclusive) and hi (exclusive) may be used to specify a subset of the array; by default the entire array is used.
bisect example with accessor
Example: const bisector = d3.bisector((d) => d.Date); creates a bisector for extracting the Date property. This bisector can then be used with .left(), .right(), or .center() methods on sorted arrays of objects.
bisect example with comparator
Example: const bisector = d3.bisector((d, x) => d.Date - x); creates a bisector using a comparator function. This is equivalent to d3.bisector((d) => d.Date) and allows custom sort orders.
bisectLeft example
Example: d3.bisectLeft(aapl.map((d) => d.Date), new Date('2014-01-02')) returns 162, finding the insertion point before Jan 2, 2014 in a date array.
bisectCenter example
Example: d3.bisectCenter(aapl.map((d) => d.Date), new Date('2013-12-31')) returns 161, finding the index of the date closest to Dec 31, 2013 in a date array.
bisector comparator with two arguments interpretation
When a bisector's accessor takes two arguments, it is interpreted as a comparator function for comparing an element d in the data with a search value x. Use this to implement custom sort orders, such as descending rather than ascending order.
bisect use case
Bisection (binary search) quickly finds a given value in a sorted array and is often used to find the position at which to insert a new value into an array while maintaining sorted order.
blur(data, radius) signature and behavior
blur(data, radius) blurs an array of data in-place by applying three iterations of a moving average transform (box filter) for a fast approximation of a Gaussian kernel of the given radius, which is a non-negative number. Returns the given data.
blur(data, radius) example with cumsum
const numbers = d3.cumsum({length: 1000}, () => Math.random() - 0.5); d3.blur(numbers, 5); // a smoothed random walk
blur2({data, width, height}, rx, ry) signature and behavior
blur2({data, width, height}, rx, ry) blurs a matrix in-place by applying a horizontal blur of radius rx and a vertical blur of radius ry (which defaults to rx). The matrix values data are stored in a flat one-dimensional array. If height is not specified, it is inferred from the given width and data.length. Returns the blurred matrix {data, width, height}.
blur2({data, width, height}, rx, ry) example
const matrix = {width: 4, height: 3, data: [1, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 1]}; d3.blur2(matrix, 1);
blurImage(imageData, rx, ry) signature and behavior
blurImage(imageData, rx, ry) blurs the given ImageData in-place, blurring each of the RGBA layers independently by applying a horizontal blur of radius rx and a vertical blur of radius ry (which defaults to rx). Returns the blurred ImageData.
blurImage(imageData, rx, ry) example
const imageData = context.getImageData(0, 0, width, height); d3.blurImage(imageData, 5);
group() signature and return type
group(iterable, ...keys) groups the specified iterable of values into an InternMap from key to array of values. It returns an InternMap where each key maps to an array of values that share that key. Elements are returned in the order of the first instance of each key.
group() with single key example
const species = d3.group(penguins, (d) => d.species); species.get("Adelie") // Array(152). This groups the penguins dataset by species and returns an InternMap where getting "Adelie" returns an array of 152 penguin objects.
group() with multiple keys returns nested InternMap
When more than one key function is specified to group(), a nested InternMap is returned. For example, d3.group(penguins, (d) => d.species, (d) => d.sex) returns an InternMap where each key (species) maps to another InternMap, which maps sex values to arrays of penguins matching both criteria.
group() with multiple keys nested access example
const speciesSex = d3.group(penguins, (d) => d.species, (d) => d.sex); speciesSex.get("Adelie").get("FEMALE") // Array(73). This accesses nested maps to get an array of 73 Adelie penguins that are female.
groups() signature and return type
groups(iterable, ...keys) is equivalent to group() but returns an array of [key, value] entries instead of a map. If more than one key is specified, each value will be a nested array of [key, value] entries. Elements are returned in the order of the first instance of each key.
groups() example
const species = d3.groups(penguins, (d) => d.species); // [["Adelie", Array(152)], …]. This returns an array of [species name, array of penguins] pairs instead of a map.
rollup() signature and return type
rollup(iterable, reduce, ...keys) groups and reduces the specified iterable of values into an InternMap from key to reduced value. The reduce function takes the array of grouped values and returns a single reduced value for each group.
rollup() with single key example
const speciesCount = d3.rollup(penguins, (D) => D.length, (d) => d.species); speciesCount.get("Adelie") // 152. This groups penguins by species and reduces each group to its length, returning an InternMap from species name to count.
rollup() with multiple keys example
const speciesSexCount = d3.rollup(penguins, (D) => D.length, (d) => d.species, (d) => d.sex); speciesSexCount.get("Adelie").get("FEMALE") // 73. This creates a nested InternMap where the count of Adelie females is 73.
rollups() signature and return type
rollups(iterable, reduce, ...keys) is equivalent to rollup() but returns an array of [key, value] entries instead of a map. If more than one key is specified, each value will be a nested array of [key, value] entries. Elements are returned in the order of the first instance of each key.
rollups() example
const speciesCounts = d3.rollups(penguins, (D) => D.length, (d) => d.species); // [["Adelie", 152], …]. This returns an array of [species name, count] pairs instead of a map.
index() signature and purpose
index(iterable, ...keys) uses rollup() with a reducer that extracts the first element from each group and throws an error if the group has more than one element. It returns an InternMap indexed by the key function, useful for quick value retrieval by a unique key. Elements are returned in input order.
index() example
const aaplDate = d3.index(aapl, (d) => d.Date); aaplDate.get(new Date("2013-12-31")).Close // 80.145714. This indexes the AAPL dataset by date and allows quick retrieval of a single value by its date key.
indexes() signature and purpose
indexes(iterable, ...keys) is like index() but returns an array of [key, value] entries instead of a map. It is included for symmetry with groups() and rollups().
flatGroup() signature and purpose
flatGroup(iterable, ...keys) is equivalent to group() but returns a flat array of [key0, key1, …, values] instead of nested maps. This is useful for iterating over all groups when multiple keys are provided.
flatRollup() signature and purpose
flatRollup(iterable, reduce, ...keys) is equivalent to rollup() but returns a flat array of [key0, key1, …, value] instead of nested maps. This is useful for iterating over all groups and their reduced values when multiple keys are provided.
groupSort() signature and return type
groupSort(iterable, comparator, key) groups the specified iterable of elements according to the specified key function, sorts the groups according to the specified comparator function, and returns an array of keys in sorted order.
groupSort() with median example
d3.groupSort(penguins, (D) => d3.median(D, (d) => d.body_mass_g), (d) => d.species) // ["Adelie", "Chinstrap", "Gentoo"]. This groups penguins by species, sorts the groups by ascending median body mass, and returns species names in sorted order.
groupSort() descending order with negation
To sort groups in descending order with groupSort(), negate the group value: d3.groupSort(penguins, (D) => -d3.median(D, (d) => d.body_mass_g), (d) => d.species) // ["Gentoo", "Adelie", "Chinstrap"]. This returns species sorted by descending median body mass.
groupSort() comparator function signature
If a comparator function is passed to groupSort() as the second argument (detected by having exactly two parameters), it will be asked to compare two groups a and b and should return a negative value if a should be before b, a positive value if a should be after b, or zero for a partial ordering.
InternMap and InternSet purpose
InternMap and InternSet allow Dates and other non-primitive keys by bypassing the SameValueZero algorithm when determining key equality. This enables using objects like Dates as keys, which would not work with native Map and Set classes.
InternMap constructor signature
new InternMap(iterable, key) constructs a new Map given an iterable of [key, value] entries. The keys are interned using the specified key function, which defaults to object.valueOf for non-primitive values. InternMap extends the native JavaScript Map class.
InternSet constructor signature
new InternSet(iterable, key) constructs a new Set given an iterable of values. The values are interned using the specified key function, which defaults to object.valueOf for non-primitive values. InternSet extends the native JavaScript Set class.
d3.group, d3.rollup, and d3.index use InternMap
d3.group, d3.rollup, and d3.index use an InternMap rather than a native Map internally, allowing them to work with non-primitive keys.