Crossfilter API Reference

API Reference
Everything in Crosslter is scoped under the crosslter namespace, which is also the
constructor. Crosslter uses semantic versioning
[1]
. You can nd the current version as
crosslter.version, which is a string of the form "X.Y.Z", where X is the major version number, Y
is the minor version number, and Z is the patch version number.
Crosslter
A crosslter represents a multi-dimensional dataset.
# crosslter([records])
Constructs a new crosslter. If records is specied, simultaneously adds the specied records.
Records can be any array of JavaScript objects or primitives. For example, you might
construct a small crosslter of payments like so:
var payments = crosslter([
{date: "2011-11-14T16:17:54Z", quantity: 2, total: 190, tip: 100, type: "tab"},
{date: "2011-11-14T16:28:54Z", quantity: 1, total: 300, tip: 200, type: "visa"},
{date: "2011-11-14T16:54:06Z", quantity: 1, total: 100, tip: 0, type: "cash"},
{date: "2011-11-14T17:25:45Z", quantity: 2, total: 200, tip: 0, type: "cash"},
{date: "2011-11-14T17:29:52Z", quantity: 1, total: 200, tip: 100, type: "visa"}
]);
# crosslter.add(records)
Adds the specied records to this crosslter.
# crosslter.remove()
Removes all records that match the current lters from this crosslter.
https://github.com/square/crosslter/wiki/API-Ref...
1 of 11 14-06-2014 05:49
# crosslter.size()
Returns the number of records in the crosslter, independent of any lters. For example, if
you only added a single batch of records to the Crosslter, this method would return
records.length.
# crosslter.groupAll()
A convenience function for grouping all records and reducing to a single value. See groupAll
for details. Note: unlike a dimension's groupAll, this grouping observes all current lters.
Dimension
# crosslter.dimension(value)
Constructs a new dimension using the specied value accessor function. The function must
return naturally-ordered values, i.e., values that behave correctly with respect to
JavaScript's <, <=, >= and > operators. This typically means primitives: booleans, numbers or
strings; however, you can override object.valueOf
[2]
to provide a comparable value from a
given object, such as a Date.
In particular, note that incomparable values such as NaN and undened are not supported. In
addition, care should be taken when mixing types, e.g., strings and numbers. If strings and
numbers are mixed, the strings will be coerced to numbers, and hence the strings must all be
coercible to number, otherwise unsupported NaN values will result.
For example, to create a dimension by payment total:
var paymentsByTotal = payments.dimension(function(d) { return d.total; });
The value returned by a dimension's accessor function for a given record should be
deterministic and never change for the existence of the crosslter. Performance note:
internally, the values for a given dimension are cached. Therefore, if the dimension value is
derived from other properties, it is not necessary to cache derived values outside of the
crosslter. The value function is only called when records are added to the Crosslter.
Dimensions are bound to the crosslter once created. Creating more than 8 dimensions, and
more than 16 dimensions, introduces additional overhead. More than 32 dimensions at once
is not currently supported, but dimensions may be disposed of using dimension.dispose to
make room for new dimensions. Dimensions are stateful, recording the associated dimension-
specic lters, if any. Initially, no lters are applied to the dimension: all records are selected.
Since creating dimensions is expensive, you should be careful to keep a reference to whatever
dimensions you create.
2 of 11 14-06-2014 05:49
# dimension.lter(value)
Filters records such that this dimension's value matches value, and returns this dimension.
The specied value may be null, in which case this method is equivalent to lterAll; or, value
may be an array, in which case this method is equivalent to lterRange; or, value may be a
function, in which case this method is equivalent to lterFunction; otherwise, this method is
equivalent to lterExact. For example:
paymentsByTotal.lter([100, 200]); // selects payments whose total is between 100 and 200
paymentsByTotal.lter(120); // selects payments whose total equals 120
paymentsByTotal.lter(function(d) { return d % 2; }); // selects payments whose total is odd
paymentsByTotal.lter(null); // selects all payments
Calling lter replaces the existing lter for this dimension, if any.
# dimension.lterExact(value)
Filters records such that this dimension's value equals value, and returns this dimension. For
example:
paymentsByTotal.lterExact(120); // selects payments whose total equals 120
Note that exact comparisons are performed using the ordering operators (<, <=, >=, >). For
example, if you pass an exact value of null, this is equivalent to 0; ltering does not use the
== or === operator.
Calling lterExact replaces the existing lter on this dimension, if any.
# dimension.lterRange(range)
Filters records such that this dimension's value is greater than or equal to range[0], and less
than range[1], returning this dimension. For example:
paymentsByTotal.lterRange([100, 200]); // selects payments whose total is between 100 and 200
Calling lterRange replaces the existing lter on this dimension, if any.
# dimension.lterFunction(function)
Filters records such that the specied function returns truthy when called with this
dimension's value, and returns this dimension. For example:
paymentsByTotal.lterFunction(function(d) { return d % 2; }); // selects payments whose total is odd
This can be used to implement a UNION lter, e.g.
3 of 11 14-06-2014 05:49
// Selects payments whose total is between 0 and 10 or 20 and 30:
paymentsByTotal.lterFunction(function(d) { return 0 <= d && d < 10 || 20 <= d && d < 30; });
# dimension.lterAll()
Clears any lters on this dimension, selecting all records and returning this dimension. For
example:
paymentsByTotal.lterAll(); // selects all payments
# dimension.top(k)
Returns a new array containing the top k records, according to the natural order of this
dimension. The returned array is sorted by descending natural order. This method intersects
the crosslter's current lters, returning only records that satisfy every active lter (including
this dimension's lter). For example, to retrieve the top 4 payments by total:
var topPayments = paymentsByTotal.top(4); // the top four payments, by total
topPayments[0]; // the biggest payment
topPayments[1]; // the second-biggest payment
// etc.
If there are fewer than k records selected according to all of the crosslter's lters, then an
array smaller than k will be returned. For example, to retrieve all selected payments in
descending order by total:
var allPayments = paymentsByTotal.top(Innity);
# dimension.bottom(k)
Returns a new array containing the bottom k records, according to the natural order of this
dimension. The returned array is sorted by ascending natural order. This method intersects
the crosslter's current lters, returning only records that satisfy every active lter (including
this dimension's lter). For example, to retrieve the bottom 4 payments by total:
var bottomPayments = paymentsByTotal.bottom(4); // the bottom four payments, by total
bottomPayments[0]; // the smallest payment
bottomPayments[1]; // the second-smallest payment
// etc.
# dimension.dispose()
Removes this dimension (and its groups) from its crosslter. This frees up space for other
dimensions to be added to this crosslter.
4 of 11 14-06-2014 05:49
Group (Map-Reduce)
# dimension.group([groupValue])
Constructs a new grouping for the given dimension, according to the specied groupValue
function, which takes a dimension value as input and returns the corresponding rounded
value. The groupValue function is optional; if not specied, it defaults to the identity function.
Like the value function, groupValue must return a naturally-ordered value; furthermore, this
order must be consistent with the dimension's value function! For example, to count
payments by dollar amount:
var paymentGroupsByTotal = paymentsByTotal.group(function(total) { return Math.oor(total / 100); });
By default, the group's reduce function will count the number of records per group. In
addition, the groups will be ordered by count.
Note: a grouping intersects the crosslter's current lters, except for the associated
dimension's lter. Thus, group methods consider only records that satisfy every lter except
this dimension's lter. So, if the crosslter of payments is ltered by type and total, then
group by total only observes the lter by type.
# group.size()
Returns the number of distinct values in the group, independent of any lters; the cardinality.
# group.reduce(add, remove, initial)
Species the reduce functions for this grouping, and returns this grouping. The default
behavior, reduce by count, is implemented as follows:
function reduceAdd(p, v) {
return p + 1;
}
function reduceRemove(p, v) {
return p - 1;
}
function reduceInitial() {
return 0;
}
To reduce by sum of total, you could change the add and remove functions as follows:
5 of 11 14-06-2014 05:49
return p + v.total;
}
return p - v.total;
}
The remove function is needed in addition to add because the group reduces are updated
incrementally as records are ltered; in some cases, it is necessary to remove records from a
previously-computed group reduction. To work with many dierent attributes, you can build
your add and remove functions in a Javascript closure.
# group.reduceCount()
A convenience method for setting the reduce functions to count records; returns this group.
# group.reduceSum(value)
A convenience method for setting the reduce functions to sum records using the specied
value accessor function; returns this group. For example, to group payments by type and sum
by total:
var paymentsByType = payments.dimension(function(d) { return d.type; }),
paymentVolumeByType = paymentsByType.group().reduceSum(function(d) { return d.total; }),
topTypes = paymentVolumeByType.top(1);
topTypes[0].key; // the top payment type (e.g., "tab")
topTypes[0].value; // the payment volume for that type (e.g., 900)
# group.order(orderValue)
Species the order value for computing the top-K groups. The default order is the identity
function, which assumes that the reduction values are naturally-ordered (such as simple
counts or sums). For example, to reduce both the count and sum simultaneously, and to order
by sum:
++p.count;
p.total += v.total;
return p;
}
--p.count;
p.total -= v.total;
return p;
6 of 11 14-06-2014 05:49
}
function reduceInitial() {
return {count: 0, total: 0};
}
function orderValue(p) {
return p.total;
}
var topTotals = paymentVolumeByType.reduce(reduceAdd, reduceRemove, reduceInitial).order(orderValue).top(2);
topTypes[0].key; // payment type with highest total (e.g., "tab")
topTypes[0].value; // reduced value for that type (e.g., {count:8, total:920})
This technique can likewise be used to compute the number of unique values in each group,
by storing a map from value to count within each group's reduction, and removing the value
from the map when the count reaches zero.
# group.orderNatural()
A convenience method for using natural order for reduce values. Returns this grouping.
# group.top(k)
Returns a new array containing the top k groups, according to the group order of the
associated reduce value. The returned array is in descending order by reduce value. For
example, to retrieve the top payment type by count:
var paymentsByType = payments.dimension(function(d) { return d.type; }),
paymentCountByType = paymentsByType.group(),
topTypes = paymentCountByType.top(1);
topTypes[0].key; // the top payment type (e.g., "tab")
topTypes[0].value; // the count of payments of that type (e.g., 8)
If there are fewer than k groups according to all of the crosslter's lters, then an array
smaller than k will be returned. If there are fewer than k non-empty groups, this method may
also return empty groups (those with zero selected records).
# group.all()
Returns the array of all groups, in ascending natural order by key. Like top, the returned
objects contain key and value attributes. The returned array may also contain empty groups,
whose value is the return value from the group's reduce initial function. For example, to count
payments by type:
7 of 11 14-06-2014 05:49
var types = paymentCountByType.all();
This method is faster than top(Innity) because the entire group array is returned as-is rather
than selecting into a new array and sorting. Do not modify the returned array!
# group.dispose()
Removes this group from its dimension. This group will no longer update when new lters are
applied to the crosslter, and it may be garbage collected if there are no other references to it
remaining.
Group All (Reduce)
# dimension.groupAll()
A convenience function for grouping all records into a single group. The returned object is
similar to a standard grouping, except it has no top or order methods. Instead, use value to
retrieve the reduce value for all matching records.
Note: a grouping intersects the crosslter's current lters, except for the associated
dimension's lter. Thus, group methods consider only records that satisfy every lter except
this dimension's lter. So, if the crosslter of payments is ltered by type and total, then
groupAll by total only observes the lter by type.
# groupAll.reduce(add, remove, initial)
Equivalent to reduce.
# groupAll.value()
Equivalent to all()[0].value.
Extras
Crosslter has a few extra goodies that you might nd useful.
# crosslter.bisect
The identity bisector; suitable for numbers, dates, strings, and other naturally-comparable
objects.
# crosslter.bisect.by(value)
Constructs a new bisector using the specied value accessor function, which must return a
8 of 11 14-06-2014 05:49
naturally-ordered value. For example, to bisect an array of objects by their property foo, say:
var bisectByFoo = crosslter.bisect.by(function(d) { return d.foo; });
The returned object is also the bisect.right function.
# bisect(array, value, lo, hi)
# bisect.right(array, value, lo, hi)
Similar to bisect.left, but returns an insertion point which comes after (to the right of) any
existing entries of value in array. The returned insertion point i partitions the array into two
halves so that all v <= value for v in array.slice(lo, i) for the left side and all v > value for v in
array.slice(i, hi) for the right side.
# bisect.left(array, value, lo, hi)
Locate the insertion point for value in array to maintain sorted order. The arguments lo and hi
specify a subset of the array which should be considered; to search the entire array, use 0 and
array.length, respectively. If value is already present in array, the insertion point will be
before (to the left of) any existing entries. The return value is suitable for use as the rst
argument to splice
[3]
assuming that array is already sorted. The returned insertion point i
partitions the array into two halves so that all v < value for v in array.slice(lo, i) for the left
side and all v >= value for v in array.slice(i, hi) for the right side.
# crosslter.heap
The identity heap function; suitable for numbers, dates, strings, and other naturally-
comparable objects.
# crosslter.heap.by(value)
Constructs a new heap function using the specied value accessor function, which must
return a naturally-ordered value. For example, to create a heap function for objects based on
their property foo, say:
var heapByFoo = crosslter.heap.by(function(d) { return d.foo; });
The returned object is a heap function.
# heap(array, lo, hi)
Reorders the specied subset of the array into a binary heap
[4]
; the lower bound lo is an
inclusive index, and the upper bound hi is an exclusive index. To convert the entire array into
a heap, specify a lo of 0 and a hi of array.length.
9 of 11 14-06-2014 05:49
# heap.sort(array, lo, hi)
Sorts the subset of the specied array, which must be a binary heap, in descending order;
the lower bound lo is an inclusive index, and the upper bound hi is an exclusive index. To sort
the entire heap, specify a lo of 0 and a hi of array.length.
# crosslter.heapselect
The identity heapselect function; suitable for numbers, dates, strings, and other naturally-
comparable objects.
# crosslter.heapselect.by(value)
Constructs a new heapselect function using the specied value accessor function, which must
return a naturally-ordered value. For example, to create a heapselect function for objects
based on their property foo, say:
var heapselectByFoo = crosslter.heapselect.by(function(d) { return d.foo; });
The returned object is a heapselect function.
# heapselect(array, lo, hi, k)
Selects
[5]
from the specied subset of the array, returning a new array containing the top k
elements; the lower bound lo is an inclusive index, and the upper bound hi is an exclusive
index. To select from the entire array, specify a lo of 0 and a hi of array.length.
# crosslter.insertionsort
The identity insertionsort function; suitable for numbers, dates, strings, and other naturally-
comparable objects. Note: you probably want to use quicksort instead.
# insertionsort(array, lo, hi)
Sorts the specied subset of the array in-place, returning the array; the lower bound lo is an
inclusive index, and the upper bound hi is an exclusive index. To sort the entire array, specify
a lo of 0 and a hi of array.length.
# crosslter.insertionsort.by(accessor)
Constructs a new insertionsort function using the specied value accessor function, which
must return a naturally-ordered value. For example, to create a insertionsort function for
objects based on their property foo, say:
var sortByFoo = crosslter.insertionsort.by(function(d) { return d.foo; });
10 of 11 14-06-2014 05:49
http://semver.org/ 1.
https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Object/ValueOf 2.
https://developer.mozilla.org/en/JavaScript/Reference/Global_Objects/Array/splice 3.
http://en.wikipedia.org/wiki/Binary_heap 4.
http://en.wikipedia.org/wiki/Selection_algorithm 5.
The returned object is an insertionsort function.
# crosslter.quicksort
The identity quicksort function; suitable for numbers, dates, strings, and other naturally-
comparable objects. This implementation uses Vladimir Yaroslavskiys dual-pivot quicksort
algorithm, and switches to insertionsort for small partitions.
# quicksort(array, lo, hi)
Sorts the specied subset of the array in-place, returning the array; the lower bound lo is an
inclusive index, and the upper bound hi is an exclusive index. To sort the entire array, specify
a lo of 0 and a hi of array.length.
# crosslter.quicksort.by(accessor)
Constructs a new quicksort function using the specied value accessor function, which must
return a naturally-ordered value. For example, to create a quicksort function for objects based
on their property foo, say:
var sortByFoo = crosslter.quicksort.by(function(d) { return d.foo; });
The returned object is a quicksort function.
# crosslter.permute(array, index)
Returns a permutation of the specied array using the specied index. The returned array
contains the corresponding element in array for each index in index, in order. For example,
permute(["a", "b", "c"], [1, 2, 0]) returns ["b", "c", "a"]. It is acceptable for the array and index
to be dierent lengths, and for indexes to be duplicated or omitted.
11 of 11 14-06-2014 05:49

Crossfilter API Reference

Enviado por

Dados do documento

Título original

Direitos autorais

Formatos disponíveis

Compartilhar este documento

Compartilhar ou incorporar documento

Opções de compartilhamento

Você considera este documento útil?

Este conteúdo é inapropriado?

Direitos autorais:

Formatos disponíveis

Crossfilter API Reference

Enviado por

Direitos autorais:

Formatos disponíveis

API Reference

Você também pode gostar