dc.js

Mixin: CapMixin

CapMixin

Cap is a mixin that groups small data elements below a cap into an others grouping for both the Row and Pie Charts.

The top ordered elements in the group up to the cap amount will be kept in the chart, and the rest will be replaced with an others element, with value equal to the sum of the replaced values. The keys of the elements below the cap limit are recorded in order to filter by those keys when the others* element is clicked.

Source:

Methods

cap( [count])

Get or set the count of elements to that will be included in the cap. If there is an othersGrouper, any further elements will be combined in an extra element with its name determined by othersLabel.

As of dc.js 2.1 and onward, the capped charts use group.all() and BaseMixin.ordering() to determine the order of elements. Then cap and takeFront determine how many elements to keep, from which end of the resulting array.

Migration note: Up through dc.js 2.0.*, capping used group.top(N), which selects the largest items according to group.order(). The chart then sorted the items according to baseMixin.ordering(). So the two values essentially had to agree, but if the group.order() was incorrect (it's easy to forget about), the wrong rows or slices would be displayed, in the correct order.

If your chart previously relied on group.order(), use chart.ordering() instead. As of 2.1.5, the ordering defaults to sorting from greatest to least like group.top(N) did.

If you want to cap by one ordering but sort by another, you can still do this by specifying your own .data() callback. For details, see the example Cap and Sort Differently.

Parameters:
Name Type Argument Default Description
count Number <optional>
 Infinity
Source:
Returns:
Type
Number | CapMixin

othersGrouper( [grouperFunction])

Get or set the grouper function that will perform the insertion of data for the Others slice if the slices cap is specified. If set to a falsy value, no others will be added.

The grouper function takes an array of included ("top") items, and an array of the rest of the items. By default the grouper function computes the sum of the rest.

Parameters:
Name Type Argument Description
grouperFunction function <optional>
Source:
Returns:
Type
function | CapMixin
Example
// Do not show others
chart.othersGrouper(null);
// Default others grouper
chart.othersGrouper(function (topItems, restItems) {
    var restItemsSum = d3.sum(restItems, _chart.valueAccessor()),
        restKeys = restItems.map(_chart.keyAccessor());
    if (restItemsSum > 0) {
        return topItems.concat([{
            others: restKeys,
            key: _chart.othersLabel(),
            value: restItemsSum
        }]);
    }
    return topItems;
});

othersLabel( [label])

Get or set the label for Others slice when slices cap is specified.

Parameters:
Name Type Argument Default Description
label String <optional>
 "Others"
Source:
Returns:
Type
String | CapMixin

takeFront( [takeFront])

Get or set the direction of capping. If set, the chart takes the first cap elements from the sorted array of elements; otherwise it takes the last cap elements.

Parameters:
Name Type Argument Default Description
takeFront Boolean <optional>
 true
Source:
Returns:
Type
Boolean | CapMixin