Skip to content

/ dc.js

Permalink
Branch: master
Find file Copy path

dc.js/docs/api-latest.md

Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
6286 lines (4737 sloc) 263 KB
Raw Blame History

Classes

Logger

Provides basis logging and deprecation utilities

Config

General configuration

ChartRegistry

The ChartRegistry maintains sets of all instantiated dc.js charts under named groups and the default group. There is a single global ChartRegistry object named chartRegistry

A chart group often corresponds to a crossfilter instance. It specifies the set of charts which should be updated when a filter changes on one of the charts or when the global functions filterAll, refocusAll, renderAll, redrawAll, or chart functions baseMixin.renderGroup, baseMixin.redrawGroup are called.

BarChart

Concrete bar chart/histogram implementation.

Examples:

BoxPlot

A box plot is a chart that depicts numerical data via their quartile ranges.

Examples:

BubbleChart

A concrete implementation of a general purpose bubble chart that allows data visualization using the following dimensions:

  • x axis position
  • y axis position
  • bubble radius
  • color

Examples:

BubbleOverlay

The bubble overlay chart is quite different from the typical bubble chart. With the bubble overlay chart you can arbitrarily place bubbles on an existing svg or bitmap image, thus changing the typical x and y positioning while retaining the capability to visualize data using bubble radius and coloring.

Examples:

CboxMenu

The CboxMenu is a simple widget designed to filter a dimension by selecting option(s) from a set of HTML <input /> elements. The menu can be made into a set of radio buttons (single select) or checkboxes (multiple).

CompositeChart

Composite charts are a special kind of chart that render multiple charts on the same Coordinate Grid. You can overlay (compose) different bar/line/area charts in a single composite chart to achieve some quite flexible charting effects.

DataCount

The data count widget is a simple widget designed to display the number of records selected by the current filters out of the total number of records in the data set. Once created the data count widget will automatically update the text content of child elements with the following classes:

  • .total-count - total number of records
  • .filter-count - number of records matched by the current filters

Note: this widget works best for the specific case of showing the number of records out of a total. If you want a more general-purpose numeric display, please use the NumberDisplay widget instead.

Examples:

DataGrid

Data grid is a simple widget designed to list the filtered records, providing a simple way to define how the items are displayed.

Note: Formerly the data grid chart (and data table) used the group attribute as a keying function for nesting the data together in sections. This was confusing so it has been renamed to section, although group still works.

Examples:

DataTable

The data table is a simple widget designed to list crossfilter focused data set (rows being filtered) in a good old tabular fashion.

An interesting feature of the data table is that you can pass a crossfilter group to the dimension, if you want to show aggregated data instead of raw data rows. This requires no special code as long as you specify the order as d3.descending, since the data table will use dimension.top() to fetch the data in that case, and the method is equally supported on the crossfilter group as the crossfilter dimension.

If you want to display aggregated data in ascending order, you will need to wrap the group in a fake dimension to support the .bottom() method. See the example linked below for more details.

Note: Formerly the data table (and data grid chart) used the group attribute as a keying function for nesting the data together in sections. This was confusing so it has been renamed to section, although group still works. Examples:

GeoChoroplethChart

The geo choropleth chart is designed as an easy way to create a crossfilter driven choropleth map from GeoJson data. This chart implementation was inspired by the great d3 choropleth example.

Examples:

HeatMap

A heat map is matrix that represents the values of two dimensions of data using colors.

HtmlLegend

htmlLegend is a attachable widget that can be added to other dc charts to render horizontal/vertical legend labels.

Legend

Legend is a attachable widget that can be added to other dc charts to render horizontal legend labels.

Examples:

LineChart

Concrete line/area chart implementation.

Examples:

NumberDisplay

A display of a single numeric value.

Unlike other charts, you do not need to set a dimension. Instead a group object must be provided and a valueAccessor that returns a single value.

If the group is a groupAll then its .value() will be displayed. This is the recommended usage.

However, if it is given an ordinary group, the numberDisplay will show the last bin's value, after sorting with the ordering function. numberDisplay defaults the ordering function to sorting by value, so this will display the largest value if the values are numeric.

PieChart

The pie chart implementation is usually used to visualize a small categorical distribution. The pie chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each slice relative to the sum of all values. Slices are ordered by ordering which defaults to sorting by key.

Examples:

RowChart

Concrete row chart implementation.

Examples:

ScatterPlot

A scatter plot chart

Examples:

SelectMenu

The select menu is a simple widget designed to filter a dimension by selecting an option from an HTML <select/> menu. The menu can be optionally turned into a multiselect.

SeriesChart

A series chart is a chart that shows multiple series of data overlaid on one chart, where the series is specified in the data. It is a specialization of Composite Chart and inherits all composite features other than recomposing the chart.

Examples:

SunburstChart

The sunburst chart implementation is usually used to visualize a small tree distribution. The sunburst chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each slice relative to the sum of all values. Slices are ordered by ordering which defaults to sorting by key.

The keys used in the sunburst chart should be arrays, representing paths in the tree.

When filtering, the sunburst chart creates instances of HierarchyFilter.

TextFilterWidget

Text Filter Widget

The text filter widget is a simple widget designed to display an input field allowing to filter data that matches the text typed. As opposed to the other charts, this doesn't display any result and doesn't update its display, it's just to input an filter other charts.

Mixins

BaseMixin

BaseMixin is an abstract functional object representing a basic dc chart object for all chart and widget implementations. Methods from the BaseMixin are inherited and available on all chart implementations in the dc library.

ColorMixin ⇒ ColorMixin

The Color Mixin is an abstract chart functional class providing universal coloring support as a mix-in for any concrete chart implementation.

BubbleMixin ⇒ BubbleMixin

This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles.

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.

MarginMixin ⇒ MarginMixin

Margin is a mixin that provides margin utility functions for both the Row Chart and Coordinate Grid Charts.

CoordinateGridMixin

Coordinate Grid is an abstract base chart designed to support a number of coordinate grid based concrete chart types, e.g. bar chart, line chart, and bubble chart.

StackMixin

Stack Mixin is an mixin that provides cross-chart support of stackability using d3.stack.

Objects

filters : object

The dc.js filters are functions which are passed into crossfilter to chose which records will be accumulated to produce values for the charts. In the crossfilter model, any filters applied on one dimension will affect all the other dimensions but not that one. dc always applies a filter function to the dimension; the function combines multiple filters and if any of them accept a record, it is filtered in.

These filter constructors are used as appropriate by the various charts to implement brushing. We mention below which chart uses which filter. In some cases, many instances of a filter will be added.

Each of the dc.js filters is an object with the following properties:

  • isFiltered - a function that returns true if a value is within the filter
  • filterType - a string identifying the filter, here the name of the constructor

Currently these filter objects are also arrays, but this is not a requirement. Custom filters can be used as long as they have the properties above.

utils : object
printers : object
units : object

Functions

elasticRadius([elasticRadius]) ⇒ Boolean | BubbleChart

Turn on or off the elastic bubble radius feature, or return the value of the flag. If this feature is turned on, then bubble radii will be automatically rescaled to fit the chart better.

Logger

Provides basis logging and deprecation utilities

Kind: global class

logger.enableDebugLog

Enable debug level logging. Set to false by default.

Kind: instance property of Logger

logger.warn([msg]) ⇒ Logger

Put a warning message to console

Kind: instance method of Logger

Param Type
[msg] String

Example

logger.warn('Invalid use of .tension on CurveLinear');

logger.warnOnce([msg]) ⇒ Logger

Put a warning message to console. It will warn only on unique messages.

Kind: instance method of Logger

Param Type
[msg] String

Example

logger.warnOnce('Invalid use of .tension on CurveLinear');

logger.debug([msg]) ⇒ Logger

Put a debug message to console. It is controlled by logger.enableDebugLog

Kind: instance method of Logger

Param Type
[msg] String

Example

logger.debug('Total number of slices: ' + numSlices);

Config

General configuration

Kind: global class

config.dateFormat : function

The default date format for dc.js

Kind: instance property of Config
Default: d3.timeFormat('%m/%d/%Y')

config.disableTransitions : Boolean

If this boolean is set truthy, all transitions will be disabled, and changes to the charts will happen immediately.

Kind: instance property of Config
Default: false

config.defaultColors([colors]) ⇒ Array | config

Set the default color scheme for ordinal charts. Changing it will impact all ordinal charts.

By default it is set to a copy of d3.schemeCategory20c for backward compatibility. This color scheme has been removed from D3v5. In DC 3.1 release it will change to a more appropriate default.

Kind: instance method of Config

Param Type
[colors] Array

Example

config.defaultColors(d3.schemeSet1)

ChartRegistry

The ChartRegistry maintains sets of all instantiated dc.js charts under named groups and the default group. There is a single global ChartRegistry object named chartRegistry

A chart group often corresponds to a crossfilter instance. It specifies the set of charts which should be updated when a filter changes on one of the charts or when the global functions filterAll, refocusAll, renderAll, redrawAll, or chart functions baseMixin.renderGroup, baseMixin.redrawGroup are called.

Kind: global class

chartRegistry.has(chart) ⇒ Boolean

Determine if a given chart instance resides in any group in the registry.

Kind: instance method of ChartRegistry

Param Type Description
chart Object dc.js chart instance

chartRegistry.register(chart, [group]) ⇒ undefined

Add given chart instance to the given group, creating the group if necessary. If no group is provided, the default group constants.DEFAULT_CHART_GROUP will be used.

Kind: instance method of ChartRegistry

Param Type Description
chart Object dc.js chart instance
[group] String Group name

chartRegistry.deregister(chart, [group]) ⇒ undefined

Remove given chart instance from the given group, creating the group if necessary. If no group is provided, the default group constants.DEFAULT_CHART_GROUP will be used.

Kind: instance method of ChartRegistry

Param Type Description
chart Object dc.js chart instance
[group] String Group name

chartRegistry.clear(group) ⇒ undefined

Clear given group if one is provided, otherwise clears all groups.

Kind: instance method of ChartRegistry

Param Type Description
group String Group name

chartRegistry.list([group]) ⇒ Array.<Object>

Get an array of each chart instance in the given group. If no group is provided, the charts in the default group are returned.

Kind: instance method of ChartRegistry

Param Type Description
[group] String Group name

BarChart

Concrete bar chart/histogram implementation.

Examples:

Kind: global class
Mixes: StackMixin

new BarChart(parent, [chartGroup])

Create a Bar Chart

Param Type Description
parent String | node | d3.selection | CompositeChart Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection. If the bar chart is a sub-chart in a Composite Chart then pass in the parent composite chart instance instead.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a bar chart under #chart-container1 element using the default global chart group
var chart1 = new BarChart('#chart-container1');
// create a bar chart under #chart-container2 element using chart group A
var chart2 = new BarChart('#chart-container2', 'chartGroupA');
// create a sub-chart under a composite parent chart
var chart3 = new BarChart(compositeChart);

barChart.outerPadding([padding]) ⇒ Number | BarChart

Get or set the outer padding on an ordinal bar chart. This setting has no effect on non-ordinal charts. Will pad the width by padding * barWidth on each side of the chart.

Kind: instance method of BarChart

Param Type Default
[padding] Number 0.5

barChart.centerBar([centerBar]) ⇒ Boolean | BarChart

Whether the bar chart will render each bar centered around the data position on the x-axis.

Kind: instance method of BarChart

Param Type Default
[centerBar] Boolean false

barChart.barPadding([barPadding]) ⇒ Number | BarChart

Get or set the spacing between bars as a fraction of bar size. Valid values are between 0-1. Setting this value will also remove any previously set gap. See the d3 docs for a visual description of how the padding is applied.

Kind: instance method of BarChart

Param Type Default
[barPadding] Number 0

barChart.gap([gap]) ⇒ Number | BarChart

Manually set fixed gap (in px) between bars instead of relying on the default auto-generated gap. By default the bar chart implementation will calculate and set the gap automatically based on the number of data points and the length of the x axis.

Kind: instance method of BarChart

Param Type Default
[gap] Number 2

barChart.alwaysUseRounding([alwaysUseRounding]) ⇒ Boolean | BarChart

Set or get whether rounding is enabled when bars are centered. If false, using rounding with centered bars will result in a warning and rounding will be ignored. This flag has no effect if bars are not centered. When using standard d3.js rounding methods, the brush often doesn't align correctly with centered bars since the bars are offset. The rounding function must add an offset to compensate, such as in the following example.

Kind: instance method of BarChart

Param Type Default
[alwaysUseRounding] Boolean false

Example

chart.round(function(n) { return Math.floor(n) + 0.5; });

BoxPlot

A box plot is a chart that depicts numerical data via their quartile ranges.

Examples:

Kind: global class
Mixes: CoordinateGridMixin

new BoxPlot(parent, [chartGroup])

Create a BoxP lot.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a box plot under #chart-container1 element using the default global chart group
var boxPlot1 = new BoxPlot('#chart-container1');
// create a box plot under #chart-container2 element using chart group A
var boxPlot2 = new BoxPlot('#chart-container2', 'chartGroupA');

boxPlot.boxPadding([padding]) ⇒ Number | BoxPlot

Get or set the spacing between boxes as a fraction of box size. Valid values are within 0-1. See the d3 docs for a visual description of how the padding is applied.

Kind: instance method of BoxPlot
See: d3.scaleBand

Param Type Default
[padding] Number 0.8

boxPlot.outerPadding([padding]) ⇒ Number | BoxPlot

Get or set the outer padding on an ordinal box chart. This setting has no effect on non-ordinal charts or on charts with a custom .boxWidth. Will pad the width by padding * barWidth on each side of the chart.

Kind: instance method of BoxPlot

Param Type Default
[padding] Number 0.5

boxPlot.boxWidth([boxWidth]) ⇒ Number | function | BoxPlot

Get or set the numerical width of the boxplot box. The width may also be a function taking as parameters the chart width excluding the right and left margins, as well as the number of x units.

Kind: instance method of BoxPlot

Param Type Default
[boxWidth] Number | function 0.5

Example

// Using numerical parameter
chart.boxWidth(10);
// Using function
chart.boxWidth((innerChartWidth, xUnits) { ... });

boxPlot.tickFormat([tickFormat]) ⇒ Number | function | BoxPlot

Get or set the numerical format of the boxplot median, whiskers and quartile labels. Defaults to integer formatting.

Kind: instance method of BoxPlot

Param Type
[tickFormat] function

Example

// format ticks to 2 decimal places
chart.tickFormat(d3.format('.2f'));

boxPlot.yRangePadding([yRangePadding]) ⇒ Number | function | BoxPlot

Get or set the amount of padding to add, in pixel coordinates, to the top and bottom of the chart to accommodate box/whisker labels.

Kind: instance method of BoxPlot

Param Type Default
[yRangePadding] function 8

Example

// allow more space for a bigger whisker font
chart.yRangePadding(12);

boxPlot.renderDataPoints([show]) ⇒ Boolean | BoxPlot

Get or set whether individual data points will be rendered.

Kind: instance method of BoxPlot

Param Type Default
[show] Boolean false

Example

// Enable rendering of individual data points
chart.renderDataPoints(true);

boxPlot.dataOpacity([opacity]) ⇒ Number | BoxPlot

Get or set the opacity when rendering data.

Kind: instance method of BoxPlot

Param Type Default
[opacity] Number 0.3

Example

// If individual data points are rendered increase the opacity.
chart.dataOpacity(0.7);

boxPlot.dataWidthPortion([percentage]) ⇒ Number | BoxPlot

Get or set the portion of the width of the box to show data points.

Kind: instance method of BoxPlot

Param Type Default
[percentage] Number 0.8

Example

// If individual data points are rendered increase the data box.
chart.dataWidthPortion(0.9);

boxPlot.showOutliers([show]) ⇒ Boolean | BoxPlot

Get or set whether outliers will be rendered.

Kind: instance method of BoxPlot

Param Type Default
[show] Boolean true

Example

// Disable rendering of outliers
chart.showOutliers(false);

boxPlot.boldOutlier([show]) ⇒ Boolean | BoxPlot

Get or set whether outliers will be drawn bold.

Kind: instance method of BoxPlot

Param Type Default
[show] Boolean false

Example

// If outliers are rendered display as bold
chart.boldOutlier(true);

BubbleChart

A concrete implementation of a general purpose bubble chart that allows data visualization using the following dimensions:

  • x axis position
  • y axis position
  • bubble radius
  • color

Examples:

Kind: global class
Mixes: BubbleMixin, CoordinateGridMixin

new BubbleChart(parent, [chartGroup])

Create a Bubble Chart.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a bubble chart under #chart-container1 element using the default global chart group
var bubbleChart1 = new BubbleChart('#chart-container1');
// create a bubble chart under #chart-container2 element using chart group A
var bubbleChart2 = new BubbleChart('#chart-container2', 'chartGroupA');

bubbleChart.sortBubbleSize([sortBubbleSize]) ⇒ Boolean | BubbleChart

Turn on or off the bubble sorting feature, or return the value of the flag. If enabled, bubbles will be sorted by their radius, with smaller bubbles in front.

Kind: instance method of BubbleChart

Param Type Default
[sortBubbleSize] Boolean false

BubbleOverlay

The bubble overlay chart is quite different from the typical bubble chart. With the bubble overlay chart you can arbitrarily place bubbles on an existing svg or bitmap image, thus changing the typical x and y positioning while retaining the capability to visualize data using bubble radius and coloring.

Examples:

Kind: global class
Mixes: BubbleMixin, BaseMixin

new BubbleOverlay(parent, [chartGroup])

Create a Bubble Overlay.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a bubble overlay chart on top of the '#chart-container1 svg' element using the default global chart group
var bubbleChart1 = BubbleOverlayChart('#chart-container1').svg(d3.select('#chart-container1 svg'));
// create a bubble overlay chart on top of the '#chart-container2 svg' element using chart group A
var bubbleChart2 = new CompositeChart('#chart-container2', 'chartGroupA').svg(d3.select('#chart-container2 svg'));

bubbleOverlay._g ⇒ BubbleOverlay

mandatory

Set the underlying svg image element. Unlike other dc charts this chart will not generate a svg element; therefore the bubble overlay chart will not work if this function is not invoked. If the underlying image is a bitmap, then an empty svg will need to be created on top of the image.

Kind: instance property of BubbleOverlay

Param Type
[imageElement] SVGElement | d3.selection

Example

// set up underlying svg element
chart.svg(d3.select('#chart svg'));

bubbleOverlay.point(name, x, y) ⇒ BubbleOverlay

mandatory

Set up a data point on the overlay. The name of a data point should match a specific 'key' among data groups generated using keyAccessor. If a match is found (point name <-> data group key) then a bubble will be generated at the position specified by the function. x and y value specified here are relative to the underlying svg.

Kind: instance method of BubbleOverlay

Param Type
name String
x Number
y Number

CboxMenu

The CboxMenu is a simple widget designed to filter a dimension by selecting option(s) from a set of HTML <input /> elements. The menu can be made into a set of radio buttons (single select) or checkboxes (multiple).

Kind: global class
Mixes: BaseMixin

new CboxMenu(parent, [chartGroup])

Create a Cbox Menu.

Param Type Description
parent String | node | d3.selection | CompositeChart Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this widget should be placed in. Interaction with the widget will only trigger events and redraws within its group.

Example

// create a cboxMenu under #cbox-container using the default global chart group
var cbox = new CboxMenu('#cbox-container')
               .dimension(states)
               .group(stateGroup);
// the option text can be set via the title() function
// by default the option text is '`key`: `value`'
cbox.title(function (d){
    return 'STATE: ' + d.key;
})

cboxMenu.order([order]) ⇒ function | CboxMenu

Get or set the function that controls the ordering of option tags in the cbox menu. By default options are ordered by the group key in ascending order.

Kind: instance method of CboxMenu

Param Type
[order] function

Example

// order by the group's value
chart.order(function (a,b) {
    return a.value > b.value ? 1 : b.value > a.value ? -1 : 0;
});

cboxMenu.promptText([promptText]) ⇒ String | CboxMenu

Get or set the text displayed in the options used to prompt selection.

Kind: instance method of CboxMenu

Param Type Default
[promptText] String 'Select all'

Example

chart.promptText('All states');

cboxMenu.filterDisplayed([filterDisplayed]) ⇒ function | CboxMenu

Get or set the function that filters options prior to display. By default options with a value of < 1 are not displayed.

Kind: instance method of CboxMenu

Param Type
[filterDisplayed] function

Example

// display all options override the `filterDisplayed` function:
chart.filterDisplayed(function () {
    return true;
});

cboxMenu.multiple([multiple]) ⇒ Boolean | CboxMenu

Controls the type of input element. Setting it to true converts the HTML input tags from radio buttons to checkboxes.

Kind: instance method of CboxMenu

Param Type Default
[multiple] boolean false

Example

chart.multiple(true);

cboxMenu.promptValue([promptValue]) ⇒ * | CboxMenu

Controls the default value to be used for dimension.filter when only the prompt value is selected. If null (the default), no filtering will occur when just the prompt is selected.

Kind: instance method of CboxMenu

Param Type Default
[promptValue] *

CompositeChart

Composite charts are a special kind of chart that render multiple charts on the same Coordinate Grid. You can overlay (compose) different bar/line/area charts in a single composite chart to achieve some quite flexible charting effects.

Kind: global class
Mixes: CoordinateGridMixin

new CompositeChart(parent, [chartGroup])

Create a Composite Chart.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a composite chart under #chart-container1 element using the default global chart group
var compositeChart1 = new CompositeChart('#chart-container1');
// create a composite chart under #chart-container2 element using chart group A
var compositeChart2 = new CompositeChart('#chart-container2', 'chartGroupA');

compositeChart.useRightAxisGridLines([useRightAxisGridLines]) ⇒ Boolean | CompositeChart

Get or set whether to draw gridlines from the right y axis. Drawing from the left y axis is the default behavior. This option is only respected when subcharts with both left and right y-axes are present.

Kind: instance method of CompositeChart

Param Type Default
[useRightAxisGridLines] Boolean false

compositeChart.childOptions([childOptions]) ⇒ Object | CompositeChart

Get or set chart-specific options for all child charts. This is equivalent to calling .options on each child chart.

Kind: instance method of CompositeChart

Param Type
[childOptions] Object

compositeChart.rightYAxisLabel([rightYAxisLabel], [padding]) ⇒ String | CompositeChart

Set or get the right y axis label.

Kind: instance method of CompositeChart

Param Type
[rightYAxisLabel] String
[padding] Number

compositeChart.compose([subChartArray]) ⇒ CompositeChart

Combine the given charts into one single composite coordinate grid chart.

Kind: instance method of CompositeChart

Param Type
[subChartArray] Array.<Chart>

Example

moveChart.compose([
    // when creating sub-chart you need to pass in the parent chart
    new LineChart(moveChart)
        .group(indexAvgByMonthGroup) // if group is missing then parent's group will be used
        .valueAccessor(function (d){return d.value.avg;})
        // most of the normal functions will continue to work in a composed chart
        .renderArea(true)
        .stack(monthlyMoveGroup, function (d){return d.value;})
        .title(function (d){
            var value = d.value.avg?d.value.avg:d.value;
            if(isNaN(value)) value = 0;
            return dateFormat(d.key) + '\n' + numberFormat(value);
        }),
    new BarChart(moveChart)
        .group(volumeByMonthGroup)
        .centerBar(true)
]);

compositeChart.children() ⇒ Array.<BaseMixin>

Returns the child charts which are composed into the composite chart.

Kind: instance method of CompositeChart

compositeChart.shareColors([shareColors]) ⇒ Boolean | CompositeChart

Get or set color sharing for the chart. If set, the .colors() value from this chart will be shared with composed children. Additionally if the child chart implements Stackable and has not set a custom .colorAccessor, then it will generate a color specific to its order in the composition.

Kind: instance method of CompositeChart

Param Type Default
[shareColors] Boolean false

compositeChart.shareTitle([shareTitle]) ⇒ Boolean | CompositeChart

Get or set title sharing for the chart. If set, the .title() value from this chart will be shared with composed children.

Note: currently you must call this before compose or the child will still get the parent's title function!

Kind: instance method of CompositeChart

Param Type Default
[shareTitle] Boolean true

compositeChart.rightY([yScale]) ⇒ d3.scale | CompositeChart

Get or set the y scale for the right axis. The right y scale is typically automatically generated by the chart implementation.

Kind: instance method of CompositeChart
See: d3.scale

Param Type
[yScale] d3.scale

compositeChart.alignYAxes([alignYAxes]) ⇒ Chart

Get or set alignment between left and right y axes. A line connecting '0' on both y axis will be parallel to x axis. This only has effect when elasticY is true.

Kind: instance method of CompositeChart

Param Type Default
[alignYAxes] Boolean false

compositeChart.rightYAxis([rightYAxis]) ⇒ d3.axisRight | CompositeChart

Set or get the right y axis used by the composite chart. This function is most useful when y axis customization is required. The y axis in dc.js is an instance of a d3.axisRight therefore it supports any valid d3 axis manipulation.

Caution: The right y axis is usually generated internally by dc; resetting it may cause unexpected results. Note also that when used as a getter, this function is not chainable: it returns the axis, not the chart, so attempting to call chart functions after calling .yAxis() will fail.

Kind: instance method of CompositeChart
See: https://github.com/d3/d3-axis/blob/master/README.md#axisRight

Param Type
[rightYAxis] d3.axisRight

Example

// customize y axis tick format
chart.rightYAxis().tickFormat(function (v) {return v + '%';});
// customize y axis tick values
chart.rightYAxis().tickValues([0, 100, 200, 300]);

DataCount

The data count widget is a simple widget designed to display the number of records selected by the current filters out of the total number of records in the data set. Once created the data count widget will automatically update the text content of child elements with the following classes:

  • .total-count - total number of records
  • .filter-count - number of records matched by the current filters

Note: this widget works best for the specific case of showing the number of records out of a total. If you want a more general-purpose numeric display, please use the NumberDisplay widget instead.

Examples:

Kind: global class
Mixes: BaseMixin

new DataCount(parent, [chartGroup])

Create a Data Count widget.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

var ndx = crossfilter(data);
var all = ndx.groupAll();

new DataCount('.dc-data-count')
    .crossfilter(ndx)
    .groupAll(all);

dataCount.html([options]) ⇒ Object | DataCount

Gets or sets an optional object specifying HTML templates to use depending how many items are selected. The text %total-count will replaced with the total number of records, and the text %filter-count will be replaced with the number of selected records.

  • all: HTML template to use if all items are selected
  • some: HTML template to use if not all items are selected

Kind: instance method of DataCount

Param Type
[options] Object

Example

counter.html({
     some: '%filter-count out of %total-count records selected',
     all: 'All records selected. Click on charts to apply filters'
})

dataCount.formatNumber([formatter]) ⇒ function | DataCount

Gets or sets an optional function to format the filter count and total count.

Kind: instance method of DataCount
See: d3.format

Param Type Default
[formatter] function d3.format('.2g')

Example

counter.formatNumber(d3.format('.2g'))

DataGrid

Data grid is a simple widget designed to list the filtered records, providing a simple way to define how the items are displayed.

Note: Formerly the data grid chart (and data table) used the group attribute as a keying function for nesting the data together in sections. This was confusing so it has been renamed to section, although group still works.

Examples:

Kind: global class
Mixes: BaseMixin

new DataGrid(parent, [chartGroup])

Create a Data Grid.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

dataGrid.section(section) ⇒ function | DataGrid

Get or set the section function for the data grid. The section function takes a data row and returns the key to specify to d3.nest to split rows into sections.

Do not pass in a crossfilter section as this will not work.

Kind: instance method of DataGrid

Param Type Description
section function Function taking a row of data and returning the nest key.

Example

// section rows by the value of their field
chart
    .section(function(d) { return d.field; })

dataGrid.group(section) ⇒ function | DataGrid

Backward-compatible synonym for section.

Kind: instance method of DataGrid

Param Type Description
section function Function taking a row of data and returning the nest key.

dataGrid.beginSlice([beginSlice]) ⇒ Number | DataGrid

Get or set the index of the beginning slice which determines which entries get displayed by the widget. Useful when implementing pagination.

Kind: instance method of DataGrid

Param Type Default
[beginSlice] Number 0

dataGrid.endSlice([endSlice]) ⇒ Number | DataGrid

Get or set the index of the end slice which determines which entries get displayed by the widget. Useful when implementing pagination.

Kind: instance method of DataGrid

Param Type
[endSlice] Number

dataGrid.size([size]) ⇒ Number | DataGrid

Get or set the grid size which determines the number of items displayed by the widget.

Kind: instance method of DataGrid

Param Type Default
[size] Number 999

dataGrid.html([html]) ⇒ function | DataGrid

Get or set the function that formats an item. The data grid widget uses a function to generate dynamic html. Use your favourite templating engine or generate the string directly.

Kind: instance method of DataGrid

Param Type
[html] function

Example

chart.html(function (d) { return '<div class='item '+data.exampleCategory+''>'+data.exampleString+'</div>';});

dataGrid.htmlSection([htmlSection]) ⇒ function | DataGrid

Get or set the function that formats a section label.

Kind: instance method of DataGrid

Param Type
[htmlSection] function

Example

chart.htmlSection (function (d) { return '<h2>'.d.key . 'with ' . d.values.length .' items</h2>'});

dataGrid.htmlGroup([htmlSection]) ⇒ function | DataGrid

Backward-compatible synonym for htmlSection.

Kind: instance method of DataGrid

Param Type
[htmlSection] function

dataGrid.sortBy([sortByFunction]) ⇒ function | DataGrid

Get or set sort-by function. This function works as a value accessor at the item level and returns a particular field to be sorted.

Kind: instance method of DataGrid

Param Type
[sortByFunction] function

Example

chart.sortBy(function(d) {
    return d.date;
});

dataGrid.order([order]) ⇒ function | DataGrid

Get or set sort the order function.

Kind: instance method of DataGrid
See

Param Type Default
[order] function d3.ascending

Example

chart.order(d3.descending);

DataTable

The data table is a simple widget designed to list crossfilter focused data set (rows being filtered) in a good old tabular fashion.

An interesting feature of the data table is that you can pass a crossfilter group to the dimension, if you want to show aggregated data instead of raw data rows. This requires no special code as long as you specify the order as d3.descending, since the data table will use dimension.top() to fetch the data in that case, and the method is equally supported on the crossfilter group as the crossfilter dimension.

If you want to display aggregated data in ascending order, you will need to wrap the group in a fake dimension to support the .bottom() method. See the example linked below for more details.

Note: Formerly the data table (and data grid chart) used the group attribute as a keying function for nesting the data together in sections. This was confusing so it has been renamed to section, although group still works. Examples:

Kind: global class
Mixes: BaseMixin

new DataTable(parent, [chartGroup])

Create a Data Table.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

dataTable.section(section) ⇒ function | DataTable

Get or set the section function for the data table. The section function takes a data row and returns the key to specify to d3.nest to split rows into sections. By default there will be only one section with no name.

Set showSections to false to hide the section headers

Kind: instance method of DataTable

Param Type Description
section function Function taking a row of data and returning the nest key.

Example

// section rows by the value of their field
chart
    .section(function(d) { return d.field; })

dataTable.group(section) ⇒ function | DataTable

Backward-compatible synonym for section.

Kind: instance method of DataTable

Param Type Description
section function Function taking a row of data and returning the nest key.

dataTable.size([size]) ⇒ Number | DataTable

Get or set the table size which determines the number of rows displayed by the widget.

Kind: instance method of DataTable

Param Type Default
[size] Number 25

dataTable.beginSlice([beginSlice]) ⇒ Number | DataTable

Get or set the index of the beginning slice which determines which entries get displayed by the widget. Useful when implementing pagination.

Note: the sortBy function will determine how the rows are ordered for pagination purposes. See the table pagination example to see how to implement the pagination user interface using beginSlice and endSlice.

Kind: instance method of DataTable

Param Type Default
[beginSlice] Number 0

dataTable.endSlice([endSlice]) ⇒ Number | DataTable

Get or set the index of the end slice which determines which entries get displayed by the widget. Useful when implementing pagination. See beginSlice for more information.

Kind: instance method of DataTable

Param Type
[endSlice] Number | undefined

dataTable.columns([columns]) ⇒ Array.<function()>

Get or set column functions. The data table widget supports several methods of specifying the columns to display.

The original method uses an array of functions to generate dynamic columns. Column functions are simple javascript functions with only one input argument d which represents a row in the data set. The return value of these functions will be used to generate the content for each cell. However, this method requires the HTML for the table to have a fixed set of column headers.

chart.columns([
    function(d) { return d.date; },
    function(d) { return d.open; },
    function(d) { return d.close; },
    function(d) { return numberFormat(d.close - d.open); },
    function(d) { return d.volume; }
]);

In the second method, you can list the columns to read from the data without specifying it as a function, except where necessary (ie, computed columns). Note the data element name is capitalized when displayed in the table header. You can also mix in functions as necessary, using the third {label, format} form, as shown below.

chart.columns([
    "date",    // d["date"], ie, a field accessor; capitalized automatically
    "open",    // ...
    "close",   // ...
    {
        label: "Change",
        format: function (d) {
            return numberFormat(d.close - d.open);
        }
    },
    "volume"   // d["volume"], ie, a field accessor; capitalized automatically
]);

In the third example, we specify all fields using the {label, format} method:

chart.columns([
    {
        label: "Date",
        format: function (d) { return d.date; }
    },
    {
        label: "Open",
        format: function (d) { return numberFormat(d.open); }
    },
    {
        label: "Close",
        format: function (d) { return numberFormat(d.close); }
    },
    {
        label: "Change",
        format: function (d) { return numberFormat(d.close - d.open); }
    },
    {
        label: "Volume",
        format: function (d) { return d.volume; }
    }
]);

You may wish to override the dataTable functions _doColumnHeaderCapitalize and _doColumnHeaderFnToString, which are used internally to translate the column information or function into a displayed header. The first one is used on the "string" column specifier; the second is used to transform a stringified function into something displayable. For the Stock example, the function for Change becomes the table header d.close - d.open.

Finally, you can even specify a completely different form of column definition. To do this, override _chart._doColumnHeaderFormat and _chart._doColumnValueFormat Be aware that fields without numberFormat specification will be displayed just as they are stored in the data, unformatted.

Kind: instance method of DataTable
Returns: Array.<function()> - |DataTable}

Param Type Default
[columns] Array.<function()> []

dataTable.sortBy([sortBy]) ⇒ function | DataTable

Get or set sort-by function. This function works as a value accessor at row level and returns a particular field to be sorted by.

Kind: instance method of DataTable

Param Type Default
[sortBy] function identity function

Example

chart.sortBy(function(d) {
    return d.date;
});

dataTable.order([order]) ⇒ function | DataTable

Get or set sort order. If the order is d3.ascending, the data table will use dimension().bottom() to fetch the data; otherwise it will use dimension().top()

Kind: instance method of DataTable
See

Param Type Default
[order] function d3.ascending

Example

chart.order(d3.descending);

dataTable.showSections([showSections]) ⇒ Boolean | DataTable

Get or set if section header rows will be shown.

Kind: instance method of DataTable

Param Type Default
[showSections] Boolean true

Example

chart
    .section([value], [name])
    .showSections(true|false);

dataTable.showGroups([showSections]) ⇒ Boolean | DataTable

Backward-compatible synonym for showSections.

Kind: instance method of DataTable

Param Type Default
[showSections] Boolean true

GeoChoroplethChart

The geo choropleth chart is designed as an easy way to create a crossfilter driven choropleth map from GeoJson data. This chart implementation was inspired by the great d3 choropleth example.

Examples:

Kind: global class
Mixes: ColorMixin, BaseMixin

new GeoChoroplethChart(parent, [chartGroup])

Create a Geo Choropleth Chart.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a choropleth chart under '#us-chart' element using the default global chart group
var chart1 = new GeoChoroplethChart('#us-chart');
// create a choropleth chart under '#us-chart2' element using chart group A
var chart2 = new CompositeChart('#us-chart2', 'chartGroupA');

geoChoroplethChart.overlayGeoJson(json, name, keyAccessor) ⇒ GeoChoroplethChart

mandatory

Use this function to insert a new GeoJson map layer. This function can be invoked multiple times if you have multiple GeoJson data layers to render on top of each other. If you overlay multiple layers with the same name the new overlay will override the existing one.

Kind: instance method of GeoChoroplethChart
See

Param Type Description
json _geoJson a geojson feed
name String name of the layer
keyAccessor function accessor function used to extract 'key' from the GeoJson data. The key extracted by this function should match the keys returned by the crossfilter groups.

Example

// insert a layer for rendering US states
chart.overlayGeoJson(statesJson.features, 'state', function(d) {
     return d.properties.name;
});

geoChoroplethChart.projection([projection]) ⇒ d3.projection | GeoChoroplethChart

Gets or sets a custom geo projection function. See the available d3 geo projection functions.

Starting version 3.0 it has been deprecated to rely on the default projection being d3.geoAlbersUsa(). Please set it explicitly. Considering that null is also a valid value for projection, if you need projection to be null please set it explicitly to null.

Kind: instance method of GeoChoroplethChart
See

Param Type Default
[projection] d3.projection d3.geoAlbersUsa()

geoChoroplethChart.geoJsons() ⇒ Array.<{name:String, data: Object, accessor: function()}>

Returns all GeoJson layers currently registered with this chart. The returned array is a reference to this chart's internal data structure, so any modification to this array will also modify this chart's internal registration.

Kind: instance method of GeoChoroplethChart

geoChoroplethChart.geoPath() ⇒ d3.geoPath

Returns the d3.geoPath object used to render the projection and features. Can be useful for figuring out the bounding box of the feature set and thus a way to calculate scale and translation for the projection.

Kind: instance method of GeoChoroplethChart
See: d3.geoPath

geoChoroplethChart.removeGeoJson(name) ⇒ GeoChoroplethChart

Remove a GeoJson layer from this chart by name

Kind: instance method of GeoChoroplethChart

Param Type
name String

HeatMap

A heat map is matrix that represents the values of two dimensions of data using colors.

Kind: global class
Mixes: ColorMixin, MarginMixin, BaseMixin

new HeatMap(parent, [chartGroup])

Create a Heat Map

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a heat map under #chart-container1 element using the default global chart group
var heatMap1 = new HeatMap('#chart-container1');
// create a heat map under #chart-container2 element using chart group A
var heatMap2 = new HeatMap('#chart-container2', 'chartGroupA');

heatMap.colsLabel([labelFunction]) ⇒ function | HeatMap

Set or get the column label function. The chart class uses this function to render column labels on the X axis. It is passed the column name.

Kind: instance method of HeatMap

Param Type Default
[labelFunction] function function(d) { return d; }

Example

// the default label function just returns the name
chart.colsLabel(function(d) { return d; });

heatMap.rowsLabel([labelFunction]) ⇒ function | HeatMap

Set or get the row label function. The chart class uses this function to render row labels on the Y axis. It is passed the row name.

Kind: instance method of HeatMap

Param Type Default
[labelFunction] function function(d) { return d; }

Example

// the default label function just returns the name
chart.rowsLabel(function(d) { return d; });

heatMap.rows([rows]) ⇒ Array.<(String|Number)> | HeatMap

Gets or sets the values used to create the rows of the heatmap, as an array. By default, all the values will be fetched from the data using the value accessor.

Kind: instance method of HeatMap

Param Type
[rows] Array.<(String|Number)>

heatMap.rowOrdering([rowOrdering]) ⇒ function | HeatMap

Get or set a comparator to order the rows. Default is d3.ascending.

Kind: instance method of HeatMap

Param Type
[rowOrdering] function

heatMap.cols([cols]) ⇒ Array.<(String|Number)> | HeatMap

Gets or sets the keys used to create the columns of the heatmap, as an array. By default, all the values will be fetched from the data using the key accessor.

Kind: instance method of HeatMap

Param Type
[cols] Array.<(String|Number)>

heatMap.colOrdering([colOrdering]) ⇒ function | HeatMap

Get or set a comparator to order the columns. Default is d3.ascending.

Kind: instance method of HeatMap

Param Type
[colOrdering] function

heatMap.boxOnClick([handler]) ⇒ function | HeatMap

Gets or sets the handler that fires when an individual cell is clicked in the heatmap. By default, filtering of the cell will be toggled.

Kind: instance method of HeatMap

Param Type
[handler] function

Example

// default box on click handler
chart.boxOnClick(function (d) {
    var filter = d.key;
    events.trigger(function () {
        _chart.filter(filter);
        _chart.redrawGroup();
    });
});

heatMap.xAxisOnClick([handler]) ⇒ function | HeatMap

Gets or sets the handler that fires when a column tick is clicked in the x axis. By default, if any cells in the column are unselected, the whole column will be selected, otherwise the whole column will be unselected.

Kind: instance method of HeatMap

Param Type
[handler] function

heatMap.yAxisOnClick([handler]) ⇒ function | HeatMap

Gets or sets the handler that fires when a row tick is clicked in the y axis. By default, if any cells in the row are unselected, the whole row will be selected, otherwise the whole row will be unselected.

Kind: instance method of HeatMap

Param Type
[handler] function

heatMap.xBorderRadius([xBorderRadius]) ⇒ Number | HeatMap

Gets or sets the X border radius. Set to 0 to get full rectangles.

Kind: instance method of HeatMap

Param Type Default
[xBorderRadius] Number 6.75

heatMap.yBorderRadius([yBorderRadius]) ⇒ Number | HeatMap

Gets or sets the Y border radius. Set to 0 to get full rectangles.

Kind: instance method of HeatMap

Param Type Default
[yBorderRadius] Number 6.75

HtmlLegend

htmlLegend is a attachable widget that can be added to other dc charts to render horizontal/vertical legend labels.

Kind: global class

htmlLegend.container([container]) ⇒ String | HtmlLegend

Set the container selector for the legend widget. Required.

Kind: instance method of HtmlLegend

Param Type
[container] String

htmlLegend.legendItemClass([legendItemClass]) ⇒ String | HtmlLegend

This can be optionally used to override class for legenditem and just use this class style. This is helpful for overriding the style of a particular chart rather than overriding the style for all charts.

Setting this will disable the highlighting of selected items also.

Kind: instance method of HtmlLegend

Param Type
[legendItemClass] String

htmlLegend.highlightSelected([highlightSelected]) ⇒ String | HtmlLegend

This can be optionally used to enable highlighting legends for the selections/filters for the chart.

Kind: instance method of HtmlLegend

Param Type
[highlightSelected] String

htmlLegend.horizontal([horizontal]) ⇒ String | HtmlLegend

Display the legend horizontally instead of vertically

Kind: instance method of HtmlLegend

Param Type
[horizontal] String

htmlLegend.legendText([legendText]) ⇒ function | HtmlLegend

Set or get the legend text function. The legend widget uses this function to render the legend text for each item. If no function is specified the legend widget will display the names associated with each group.

Kind: instance method of HtmlLegend

Param Type
[legendText] function

Example

// default legendText
legend.legendText(pluck('name'))

// create numbered legend items
chart.legend(new HtmlLegend().legendText(function(d, i) { return i + '. ' + d.name; }))

// create legend displaying group counts
chart.legend(new HtmlLegend().legendText(function(d) { return d.name + ': ' d.data; }))

htmlLegend.maxItems([maxItems]) ⇒ HtmlLegend

Maximum number of legend items to display

Kind: instance method of HtmlLegend

Param Type
[maxItems] Number

Legend

Legend is a attachable widget that can be added to other dc charts to render horizontal legend labels.

Examples:

Kind: global class

legend.x([x]) ⇒ Number | Legend

Set or get x coordinate for legend widget.

Kind: instance method of Legend

Param Type Default
[x] Number 0

legend.y([y]) ⇒ Number | Legend

Set or get y coordinate for legend widget.

Kind: instance method of Legend

Param Type Default
[y] Number 0

legend.gap([gap]) ⇒ Number | Legend

Set or get gap between legend items.

Kind: instance method of Legend

Param Type Default
[gap] Number 5

legend.highlightSelected([highlightSelected]) ⇒ String | dc.legend

This can be optionally used to enable highlighting legends for the selections/filters for the chart.

Kind: instance method of Legend

Param Type
[highlightSelected] String

legend.itemHeight([itemHeight]) ⇒ Number | Legend

Set or get legend item height.

Kind: instance method of Legend

Param Type Default
[itemHeight] Number 12

legend.horizontal([horizontal]) ⇒ Boolean | Legend

Position legend horizontally instead of vertically.

Kind: instance method of Legend

Param Type Default
[horizontal] Boolean false

legend.legendWidth([legendWidth]) ⇒ Number | Legend

Maximum width for horizontal legend.

Kind: instance method of Legend

Param Type Default
[legendWidth] Number 500

legend.itemWidth([itemWidth]) ⇒ Number | Legend

Legend item width for horizontal legend.

Kind: instance method of Legend

Param Type Default
[itemWidth] Number 70

legend.autoItemWidth([autoItemWidth]) ⇒ Boolean | Legend

Turn automatic width for legend items on or off. If true, itemWidth is ignored. This setting takes into account the gap.

Kind: instance method of Legend

Param Type Default
[autoItemWidth] Boolean false

legend.legendText([legendText]) ⇒ function | Legend

Set or get the legend text function. The legend widget uses this function to render the legend text for each item. If no function is specified the legend widget will display the names associated with each group.

Kind: instance method of Legend

Param Type
[legendText] function

Example

// default legendText
legend.legendText(pluck('name'))

// create numbered legend items
chart.legend(new Legend().legendText(function(d, i) { return i + '. ' + d.name; }))

// create legend displaying group counts
chart.legend(new Legend().legendText(function(d) { return d.name + ': ' d.data; }))

legend.maxItems([maxItems]) ⇒ Legend

Maximum number of legend items to display

Kind: instance method of Legend

Param Type
[maxItems] Number

LineChart

Concrete line/area chart implementation.

Examples:

Kind: global class
Mixes: StackMixin, CoordinateGridMixin

new LineChart(parent, [chartGroup])

Create a Line Chart.

Param Type Description
parent String | node | d3.selection | CompositeChart Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection. If the line chart is a sub-chart in a Composite Chart then pass in the parent composite chart instance instead.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a line chart under #chart-container1 element using the default global chart group
var chart1 = new LineChart('#chart-container1');
// create a line chart under #chart-container2 element using chart group A
var chart2 = new LineChart('#chart-container2', 'chartGroupA');
// create a sub-chart under a composite parent chart
var chart3 = new LineChart(compositeChart);

lineChart.curve([curve]) ⇒ d3.curve | LineChart

Gets or sets the curve factory to use for lines and areas drawn, allowing e.g. step functions, splines, and cubic interpolation. Typically you would use one of the interpolator functions provided by d3 curves.

Replaces the use of interpolate and tension in dc.js < 3.0

This is passed to line.curve and area.curve.

Kind: instance method of LineChart
See

Param Type Default
[curve] d3.curve d3.curveLinear

Example

// default
chart
    .curve(d3.curveLinear);
// Add tension to curves that support it
chart
    .curve(d3.curveCardinal.tension(0.5));
// You can use some specialized variation like
// https://en.wikipedia.org/wiki/Centripetal_Catmull%E2%80%93Rom_spline
chart
    .curve(d3.curveCatmullRom.alpha(0.5));

lineChart.interpolate([interpolate]) ⇒ d3.curve | LineChart

Deprecated

Gets or sets the interpolator to use for lines drawn, by string name, allowing e.g. step functions, splines, and cubic interpolation.

Possible values are: 'linear', 'linear-closed', 'step', 'step-before', 'step-after', 'basis', 'basis-open', 'basis-closed', 'bundle', 'cardinal', 'cardinal-open', 'cardinal-closed', and 'monotone'.

This function exists for backward compatibility. Use curve which is generic and provides more options. Value set through .curve takes precedence over .interpolate and .tension.

Kind: instance method of LineChart
See: curve

Param Type Default
[interpolate] d3.curve d3.curveLinear

lineChart.tension([tension]) ⇒ Number | LineChart

Deprecated

Gets or sets the tension to use for lines drawn, in the range 0 to 1.

Passed to the d3 curve function if it provides a .tension function. Example: curveCardinal.tension.

This function exists for backward compatibility. Use curve which is generic and provides more options. Value set through .curve takes precedence over .interpolate and .tension.

Kind: instance method of LineChart
See: curve

Param Type Default
[tension] Number 0

lineChart.defined([defined]) ⇒ function | LineChart

Gets or sets a function that will determine discontinuities in the line which should be skipped: the path will be broken into separate subpaths if some points are undefined. This function is passed to line.defined

Note: crossfilter will sometimes coerce nulls to 0, so you may need to carefully write custom reduce functions to get this to work, depending on your data. See this GitHub comment for more details and an example.

Kind: instance method of LineChart
See: line.defined

Param Type
[defined] function

lineChart.dashStyle([dashStyle]) ⇒ Array.<Number> | LineChart

Set the line's d3 dashstyle. This value becomes the 'stroke-dasharray' of line. Defaults to empty array (solid line).

Kind: instance method of LineChart
See: stroke-dasharray

Param Type Default
[dashStyle] Array.<Number> []

Example

// create a Dash Dot Dot Dot
chart.dashStyle([3,1,1,1]);

lineChart.renderArea([renderArea]) ⇒ Boolean | LineChart

Get or set render area flag. If the flag is set to true then the chart will render the area beneath each line and the line chart effectively becomes an area chart.

Kind: instance method of LineChart

Param Type Default
[renderArea] Boolean false

lineChart.xyTipsOn([xyTipsOn]) ⇒ Boolean | LineChart

Turn on/off the mouseover behavior of an individual data point which renders a circle and x/y axis dashed lines back to each respective axis. This is ignored if the chart brush is on

Kind: instance method of LineChart

Param Type Default
[xyTipsOn] Boolean false

lineChart.dotRadius([dotRadius]) ⇒ Number | LineChart

Get or set the radius (in px) for dots displayed on the data points.

Kind: instance method of LineChart

Param Type Default
[dotRadius] Number 5

lineChart.renderDataPoints([options]) ⇒ Object | LineChart

Always show individual dots for each datapoint.

If options is falsy, it disables data point rendering. If no options are provided, the current options values are instead returned.

Kind: instance method of LineChart

Param Type Default
[options] Object {fillOpacity: 0.8, strokeOpacity: 0.0, radius: 2}

Example

chart.renderDataPoints({radius: 2, fillOpacity: 0.8, strokeOpacity: 0.0})

NumberDisplay

A display of a single numeric value.

Unlike other charts, you do not need to set a dimension. Instead a group object must be provided and a valueAccessor that returns a single value.

If the group is a groupAll then its .value() will be displayed. This is the recommended usage.

However, if it is given an ordinary group, the numberDisplay will show the last bin's value, after sorting with the ordering function. numberDisplay defaults the ordering function to sorting by value, so this will display the largest value if the values are numeric.

Kind: global class
Mixes: BaseMixin

new NumberDisplay(parent, [chartGroup])

Create a Number Display widget.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a number display under #chart-container1 element using the default global chart group
var display1 = new NumberDisplay('#chart-container1');

numberDisplay.html([html]) ⇒ Object | NumberDisplay

Gets or sets an optional object specifying HTML templates to use depending on the number displayed. The text %number will be replaced with the current value.

  • one: HTML template to use if the number is 1
  • zero: HTML template to use if the number is 0
  • some: HTML template to use otherwise

Kind: instance method of NumberDisplay

Param Type Default
[html] Object {one: '', some: '', none: ''}

Example

numberWidget.html({
     one:'%number record',
     some:'%number records',
     none:'no records'})

numberDisplay.value() ⇒ Number

Calculate and return the underlying value of the display.

Kind: instance method of NumberDisplay

numberDisplay.formatNumber([formatter]) ⇒ function | NumberDisplay

Get or set a function to format the value for the display.

Kind: instance method of NumberDisplay
See: d3.format

Param Type Default
[formatter] function d3.format('.2s')

PieChart

The pie chart implementation is usually used to visualize a small categorical distribution. The pie chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each slice relative to the sum of all values. Slices are ordered by ordering which defaults to sorting by key.

Examples:

Kind: global class
Mixes: CapMixin, ColorMixin, BaseMixin

new PieChart(parent, [chartGroup])

Create a Pie Chart

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a pie chart under #chart-container1 element using the default global chart group
var chart1 = new PieChart('#chart-container1');
// create a pie chart under #chart-container2 element using chart group A
var chart2 = new PieChart('#chart-container2', 'chartGroupA');

pieChart.slicesCap([cap]) ⇒ Number | PieChart

Get or set the maximum number of slices the pie chart will generate. The top slices are determined by value from high to low. Other slices exeeding the cap will be rolled up into one single Others slice.

Kind: instance method of PieChart

Param Type
[cap] Number

pieChart.externalRadiusPadding([externalRadiusPadding]) ⇒ Number | PieChart

Get or set the external radius padding of the pie chart. This will force the radius of the pie chart to become smaller or larger depending on the value.

Kind: instance method of PieChart

Param Type Default
[externalRadiusPadding] Number 0

pieChart.innerRadius([innerRadius]) ⇒ Number | PieChart

Get or set the inner radius of the pie chart. If the inner radius is greater than 0px then the pie chart will be rendered as a doughnut chart.

Kind: instance method of PieChart

Param Type Default
[innerRadius] Number 0

pieChart.radius([radius]) ⇒ Number | PieChart

Get or set the outer radius. If the radius is not set, it will be half of the minimum of the chart width and height.

Kind: instance method of PieChart

Param Type
[radius] Number

pieChart.cx([cx]) ⇒ Number | PieChart

Get or set center x coordinate position. Default is center of svg.

Kind: instance method of PieChart

Param Type
[cx] Number

pieChart.cy([cy]) ⇒ Number | PieChart

Get or set center y coordinate position. Default is center of svg.

Kind: instance method of PieChart

Param Type
[cy] Number

pieChart.minAngleForLabel([minAngleForLabel]) ⇒ Number | PieChart

Get or set the minimal slice angle for label rendering. Any slice with a smaller angle will not display a slice label.

Kind: instance method of PieChart

Param Type Default
[minAngleForLabel] Number 0.5

pieChart.emptyTitle([title]) ⇒ String | PieChart

Title to use for the only slice when there is no data.

Kind: instance method of PieChart

Param Type
[title] String

pieChart.externalLabels([externalLabelRadius]) ⇒ Number | PieChart

Position slice labels offset from the outer edge of the chart.

The argument specifies the extra radius to be added for slice labels.

Kind: instance method of PieChart

Param Type
[externalLabelRadius] Number

pieChart.drawPaths([drawPaths]) ⇒ Boolean | PieChart

Get or set whether to draw lines from pie slices to their labels.

Kind: instance method of PieChart

Param Type
[drawPaths] Boolean

RowChart

Concrete row chart implementation.

Examples:

Kind: global class
Mixes: CapMixin, MarginMixin, ColorMixin, BaseMixin

new RowChart(parent, [chartGroup])

Create a Row Chart.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a row chart under #chart-container1 element using the default global chart group
var chart1 = new RowChart('#chart-container1');
// create a row chart under #chart-container2 element using chart group A
var chart2 = new RowChart('#chart-container2', 'chartGroupA');

rowChart.x([scale]) ⇒ d3.scale | RowChart

Gets or sets the x scale. The x scale can be any d3 d3.scale.

Kind: instance method of RowChart
See: d3.scale

Param Type
[scale] d3.scale

rowChart.renderTitleLabel([renderTitleLabel]) ⇒ Boolean | RowChart

Turn on/off Title label rendering (values) using SVG style of text-anchor 'end'.

Kind: instance method of RowChart

Param Type Default
[renderTitleLabel] Boolean false

rowChart.xAxis([xAxis]) ⇒ d3.axis | RowChart

Get or sets the x axis for the row chart instance. See the d3.axis documention for more information.

Kind: instance method of RowChart

Param Type
[xAxis] d3.axis

Example

// customize x axis tick format
chart.xAxis().tickFormat(function (v) {return v + '%';});
// customize x axis tick values
chart.xAxis().tickValues([0, 100, 200, 300]);
// use a top-oriented axis. Note: position of the axis and grid lines will need to
// be set manually, see https://dc-js.github.io/dc.js/examples/row-top-axis.html
chart.xAxis(d3.axisTop())

rowChart.fixedBarHeight([fixedBarHeight]) ⇒ Boolean | Number | RowChart

Get or set the fixed bar height. Default is [false] which will auto-scale bars. For example, if you want to fix the height for a specific number of bars (useful in TopN charts) you could fix height as follows (where count = total number of bars in your TopN and gap is your vertical gap space).

Kind: instance method of RowChart

Param Type Default
[fixedBarHeight] Boolean | Number false

Example

chart.fixedBarHeight( chartheight - (count + 1) * gap / count);

rowChart.gap([gap]) ⇒ Number | RowChart

Get or set the vertical gap space between rows on a particular row chart instance.

Kind: instance method of RowChart

Param Type Default
[gap] Number 5

rowChart.elasticX([elasticX]) ⇒ Boolean | RowChart

Get or set the elasticity on x axis. If this attribute is set to true, then the x axis will rescale to auto-fit the data range when filtered.

Kind: instance method of RowChart

Param Type
[elasticX] Boolean

rowChart.labelOffsetX([labelOffsetX]) ⇒ Number | RowChart

Get or set the x offset (horizontal space to the top left corner of a row) for labels on a particular row chart.

Kind: instance method of RowChart

Param Type Default
[labelOffsetX] Number 10

rowChart.labelOffsetY([labelOffsety]) ⇒ Number | RowChart

Get or set the y offset (vertical space to the top left corner of a row) for labels on a particular row chart.

Kind: instance method of RowChart

Param Type Default
[labelOffsety] Number 15

rowChart.titleLabelOffsetX([titleLabelOffsetX]) ⇒ Number | RowChart

Get of set the x offset (horizontal space between right edge of row and right edge or text.

Kind: instance method of RowChart

Param Type Default
[titleLabelOffsetX] Number 2

ScatterPlot

A scatter plot chart

Examples:

Kind: global class
Mixes: CoordinateGridMixin

new ScatterPlot(parent, [chartGroup])

Create a Scatter Plot.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a scatter plot under #chart-container1 element using the default global chart group
var chart1 = new ScatterPlot('#chart-container1');
// create a scatter plot under #chart-container2 element using chart group A
var chart2 = new ScatterPlot('#chart-container2', 'chartGroupA');
// create a sub-chart under a composite parent chart
var chart3 = new ScatterPlot(compositeChart);

scatterPlot.resetSvg() ⇒ SVGElement

Method that replaces original resetSvg and appropriately inserts canvas element along with svg element and sets their CSS properties appropriately so they are overlapped on top of each other. Remove the chart's SVGElements from the dom and recreate the container SVGElement.

Kind: instance method of ScatterPlot
See: SVGElement

scatterPlot.useCanvas([useCanvas]) ⇒ Boolean | d3.selection

Set or get whether to use canvas backend for plotting scatterPlot. Note that the canvas backend does not currently support customSymbol or symbol methods and is limited to always plotting with filled circles. Symbols are drawn with symbolSize radius. By default, the SVG backend is used when useCanvas is set to false.

Kind: instance method of ScatterPlot

Param Type Default
[useCanvas] Boolean false

scatterPlot.canvas([canvasElement]) ⇒ CanvasElement | d3.selection

Set or get canvas element. You should usually only ever use the get method as dc.js will handle canvas element generation. Provides valid canvas only when useCanvas is set to true

Kind: instance method of ScatterPlot

Param Type
[canvasElement] CanvasElement | d3.selection

scatterPlot.context() ⇒ CanvasContext

Get canvas 2D context. Provides valid context only when useCanvas is set to true

Kind: instance method of ScatterPlot

scatterPlot.existenceAccessor([accessor]) ⇒ function | ScatterPlot

Get or set the existence accessor. If a point exists, it is drawn with symbolSize radius and opacity 1; if it does not exist, it is drawn with emptySize radius and opacity 0. By default, the existence accessor checks if the reduced value is truthy.

Kind: instance method of ScatterPlot
See

Param Type
[accessor] function

Example

// default accessor
chart.existenceAccessor(function (d) { return d.value; });

scatterPlot.symbol([type]) ⇒ function | ScatterPlot

Get or set the symbol type used for each point. By default the symbol is a circle (d3.symbolCircle). Type can be a constant or an accessor.

Kind: instance method of ScatterPlot
See: symbol.type

Param Type Default
[type] function d3.symbolCircle

Example

// Circle type
chart.symbol(d3.symbolCircle);
// Square type
chart.symbol(d3.symbolSquare);

scatterPlot.customSymbol([customSymbol]) ⇒ String | function | ScatterPlot

Get or set the symbol generator. By default ScatterPlot will use d3.symbol() to generate symbols. ScatterPlot will set the symbol size accessor on the symbol generator.

Kind: instance method of ScatterPlot
See

Param Type Default
[customSymbol] String | function d3.symbol()

scatterPlot.symbolSize([symbolSize]) ⇒ Number | ScatterPlot

Set or get radius for symbols.

Kind: instance method of ScatterPlot
See: d3.symbol.size

Param Type Default
[symbolSize] Number 3

scatterPlot.highlightedSize([highlightedSize]) ⇒ Number | ScatterPlot

Set or get radius for highlighted symbols.

Kind: instance method of ScatterPlot
See: d3.symbol.size

Param Type Default
[highlightedSize] Number 5

scatterPlot.excludedSize([excludedSize]) ⇒ Number | ScatterPlot

Set or get size for symbols excluded from this chart's filter. If null, no special size is applied for symbols based on their filter status.

Kind: instance method of ScatterPlot
See: d3.symbol.size

Param Type Default
[excludedSize] Number

scatterPlot.excludedColor([excludedColor]) ⇒ Number | ScatterPlot

Set or get color for symbols excluded from this chart's filter. If null, no special color is applied for symbols based on their filter status.

Kind: instance method of ScatterPlot

Param Type Default
[excludedColor] Number

scatterPlot.excludedOpacity([excludedOpacity]) ⇒ Number | ScatterPlot

Set or get opacity for symbols excluded from this chart's filter.

Kind: instance method of ScatterPlot

Param Type Default
[excludedOpacity] Number 1.0

scatterPlot.emptySize([emptySize]) ⇒ Number | ScatterPlot

Set or get radius for symbols when the group is empty.

Kind: instance method of ScatterPlot
See: d3.symbol.size

Param Type Default
[emptySize] Number 0

scatterPlot.emptyColor([emptyColor]) ⇒ String | ScatterPlot

Set or get color for symbols when the group is empty. If null, just use the colorMixin.colors color scale zero value.

Kind: instance method of ScatterPlot

Param Type Default
[emptyColor] String

scatterPlot.emptyOpacity([emptyOpacity]) ⇒ Number | ScatterPlot

Set or get opacity for symbols when the group is empty.

Kind: instance method of ScatterPlot

Param Type Default
[emptyOpacity] Number 0

scatterPlot.nonemptyOpacity([nonemptyOpacity]) ⇒ Number | ScatterPlot

Set or get opacity for symbols when the group is not empty.

Kind: instance method of ScatterPlot

Param Type Default
[nonemptyOpacity] Number 1

SelectMenu

The select menu is a simple widget designed to filter a dimension by selecting an option from an HTML <select/> menu. The menu can be optionally turned into a multiselect.

Kind: global class
Mixes: BaseMixin

new SelectMenu(parent, [chartGroup])

Create a Select Menu.

Param Type Description
parent String | node | d3.selection | CompositeChart Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this widget should be placed in. Interaction with the widget will only trigger events and redraws within its group.

Example

// create a select menu under #select-container using the default global chart group
var select = new SelectMenu('#select-container')
               .dimension(states)
               .group(stateGroup);
// the option text can be set via the title() function
// by default the option text is '`key`: `value`'
select.title(function (d){
    return 'STATE: ' + d.key;
})

selectMenu.order([order]) ⇒ function | SelectMenu

Get or set the function that controls the ordering of option tags in the select menu. By default options are ordered by the group key in ascending order.

Kind: instance method of SelectMenu

Param Type
[order] function

Example

// order by the group's value
chart.order(function (a,b) {
    return a.value > b.value ? 1 : b.value > a.value ? -1 : 0;
});

selectMenu.promptText([promptText]) ⇒ String | SelectMenu

Get or set the text displayed in the options used to prompt selection.

Kind: instance method of SelectMenu

Param Type Default
[promptText] String 'Select all'

Example

chart.promptText('All states');

selectMenu.filterDisplayed([filterDisplayed]) ⇒ function | SelectMenu

Get or set the function that filters option tags prior to display. By default options with a value of < 1 are not displayed.

Kind: instance method of SelectMenu

Param Type
[filterDisplayed] function

Example

// display all options override the `filterDisplayed` function:
chart.filterDisplayed(function () {
    return true;
});

selectMenu.multiple([multiple]) ⇒ boolean | SelectMenu

Controls the type of select menu. Setting it to true converts the underlying HTML tag into a multiple select.

Kind: instance method of SelectMenu

Param Type Default
[multiple] boolean false

Example

chart.multiple(true);

selectMenu.promptValue([promptValue]) ⇒ * | SelectMenu

Controls the default value to be used for dimension.filter when only the prompt value is selected. If null (the default), no filtering will occur when just the prompt is selected.

Kind: instance method of SelectMenu

Param Type Default
[promptValue] *

selectMenu.numberVisible([numberVisible]) ⇒ number | SelectMenu

Controls the number of items to show in the select menu, when .multiple() is true. This controls the size attribute of the select element. If null (the default), uses the browser's default height.

Kind: instance method of SelectMenu

Param Type Default
[numberVisible] number

Example

chart.numberVisible(10);

SeriesChart

A series chart is a chart that shows multiple series of data overlaid on one chart, where the series is specified in the data. It is a specialization of Composite Chart and inherits all composite features other than recomposing the chart.

Examples:

Kind: global class
Mixes: CompositeChart

new SeriesChart(parent, [chartGroup])

Create a Series Chart.

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a series chart under #chart-container1 element using the default global chart group
var seriesChart1 = new SeriesChart("#chart-container1");
// create a series chart under #chart-container2 element using chart group A
var seriesChart2 = new SeriesChart("#chart-container2", "chartGroupA");

seriesChart.chart([chartFunction]) ⇒ function | SeriesChart

Get or set the chart function, which generates the child charts.

Kind: instance method of SeriesChart

Param Type Default
[chartFunction] function (anchor) => new LineChart(anchor)

Example

// put curve on the line charts used for the series
chart.chart(function(c) { return new LineChart(c).curve(d3.curveBasis); })
// do a scatter series chart
chart.chart(anchor => new ScatterPlot(anchor))

seriesChart.seriesAccessor([accessor]) ⇒ function | SeriesChart

mandatory

Get or set accessor function for the displayed series. Given a datum, this function should return the series that datum belongs to.

Kind: instance method of SeriesChart

Param Type
[accessor] function

Example

// simple series accessor
chart.seriesAccessor(function(d) { return "Expt: " + d.key[0]; })

seriesChart.seriesSort([sortFunction]) ⇒ function | SeriesChart

Get or set a function to sort the list of series by, given series values.

Kind: instance method of SeriesChart
See

Param Type Default
[sortFunction] function d3.ascending

Example

chart.seriesSort(d3.descending);

seriesChart.valueSort([sortFunction]) ⇒ function | SeriesChart

Get or set a function to sort each series values by. By default this is the key accessor which, for example, will ensure a lineChart series connects its points in increasing key/x order, rather than haphazardly.

Kind: instance method of SeriesChart
See

Param Type
[sortFunction] function

Example

// Default value sort
_chart.valueSort(function keySort (a, b) {
    return d3.ascending(_chart.keyAccessor()(a), _chart.keyAccessor()(b));
});

SunburstChart

The sunburst chart implementation is usually used to visualize a small tree distribution. The sunburst chart uses keyAccessor to determine the slices, and valueAccessor to calculate the size of each slice relative to the sum of all values. Slices are ordered by ordering which defaults to sorting by key.

The keys used in the sunburst chart should be arrays, representing paths in the tree.

When filtering, the sunburst chart creates instances of HierarchyFilter.

Kind: global class
Mixes: CapMixin, ColorMixin, BaseMixin

new SunburstChart(parent, [chartGroup])

Create a Sunburst Chart

Param Type Description
parent String | node | d3.selection Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

// create a sunburst chart under #chart-container1 element using the default global chart group
var chart1 = new SunburstChart('#chart-container1');
// create a sunburst chart under #chart-container2 element using chart group A
var chart2 = new SunburstChart('#chart-container2', 'chartGroupA');

sunburstChart.innerRadius([innerRadius]) ⇒ Number | SunburstChart

Get or set the inner radius of the sunburst chart. If the inner radius is greater than 0px then the sunburst chart will be rendered as a doughnut chart. Default inner radius is 0px.

Kind: instance method of SunburstChart

Param Type Default
[innerRadius] Number 0

sunburstChart.radius([radius]) ⇒ Number | SunburstChart

Get or set the outer radius. If the radius is not set, it will be half of the minimum of the chart width and height.

Kind: instance method of SunburstChart

Param Type
[radius] Number

sunburstChart.cx([cx]) ⇒ Number | SunburstChart

Get or set center x coordinate position. Default is center of svg.

Kind: instance method of SunburstChart

Param Type
[cx] Number

sunburstChart.cy([cy]) ⇒ Number | SunburstChart

Get or set center y coordinate position. Default is center of svg.

Kind: instance method of SunburstChart

Param Type
[cy] Number

sunburstChart.minAngleForLabel([minAngleForLabel]) ⇒ Number | SunburstChart

Get or set the minimal slice angle for label rendering. Any slice with a smaller angle will not display a slice label.

Kind: instance method of SunburstChart

Param Type Default
[minAngleForLabel] Number 0.5

sunburstChart.emptyTitle([title]) ⇒ String | SunburstChart

Title to use for the only slice when there is no data.

Kind: instance method of SunburstChart

Param Type
[title] String

sunburstChart.externalLabels([externalLabelRadius]) ⇒ Number | SunburstChart

Position slice labels offset from the outer edge of the chart.

The argument specifies the extra radius to be added for slice labels.

Kind: instance method of SunburstChart

Param Type
[externalLabelRadius] Number

TextFilterWidget

Text Filter Widget

The text filter widget is a simple widget designed to display an input field allowing to filter data that matches the text typed. As opposed to the other charts, this doesn't display any result and doesn't update its display, it's just to input an filter other charts.

Kind: global class
Mixes: BaseMixin

new TextFilterWidget(parent, [chartGroup])

Create Text Filter widget

Param Type Description
parent String | node | d3.selection | CompositeChart Any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection.
[chartGroup] String The name of the chart group this chart instance should be placed in. Interaction with a chart will only trigger events and redraws within the chart's group.

Example

var data = [{"firstName":"John","lastName":"Coltrane"}{"firstName":"Miles",lastName:"Davis"}]
var ndx = crossfilter(data);
var dimension = ndx.dimension(function(d) {
    return d.lastName.toLowerCase() + ' ' + d.firstName.toLowerCase();
});

new TextFilterWidget('#search')
    .dimension(dimension);
    // you don't need the group() function

textFilterWidget.normalize([normalize]) ⇒ TextFilterWidget | function

This function will be called on values before calling the filter function.

Kind: instance method of TextFilterWidget

Param Type
[normalize] function

Example

// This is the default
chart.normalize(function (s) {
  return s.toLowerCase();
});

textFilterWidget.placeHolder([placeHolder]) ⇒ TextFilterWidget | string

Placeholder text in the search box.

Kind: instance method of TextFilterWidget

Param Type Default
[placeHolder] function 'search'

Example

// This is the default
chart.placeHolder('type to filter');

textFilterWidget.filterFunctionFactory([filterFunctionFactory]) ⇒ TextFilterWidget | function

This function will be called with the search text, it needs to return a function that will be used to filter the data. The default function checks presence of the search text.

Kind: instance method of TextFilterWidget

Param Type
[filterFunctionFactory] function

Example

// This is the default
function (query) {
    query = _normalize(query);
    return function (d) {
        return _normalize(d).indexOf(query) !== -1;
    };
};

BaseMixin

BaseMixin is an abstract functional object representing a basic dc chart object for all chart and widget implementations. Methods from the BaseMixin are inherited and available on all chart implementations in the dc library.

Kind: global mixin

baseMixin.height([height]) ⇒ Number | BaseMixin

Set or get the height attribute of a chart. The height is applied to the SVGElement generated by the chart when rendered (or re-rendered). If a value is given, then it will be used to calculate the new height and the chart returned for method chaining. The value can either be a numeric, a function, or falsy. If no value is specified then the value of the current height attribute will be returned.

By default, without an explicit height being given, the chart will select the width of its anchor element. If that isn't possible it defaults to 200 (provided by the minHeight property). Setting the value falsy will return the chart to the default behavior.

Kind: instance method of BaseMixin
See: minHeight

Param Type
[height] Number | function

Example

// Default height
chart.height(function (element) {
    var height = element && element.getBoundingClientRect && element.getBoundingClientRect().height;
    return (height && height > chart.minHeight()) ? height : chart.minHeight();
});

chart.height(250); // Set the chart's height to 250px;
chart.height(function(anchor) { return doSomethingWith(anchor); }); // set the chart's height with a function
chart.height(null); // reset the height to the default auto calculation

baseMixin.width([width]) ⇒ Number | BaseMixin

Set or get the width attribute of a chart.

Kind: instance method of BaseMixin
See

Param Type
[width] Number | function

Example

// Default width
chart.width(function (element) {
    var width = element && element.getBoundingClientRect && element.getBoundingClientRect().width;
    return (width && width > chart.minWidth()) ? width : chart.minWidth();
});

baseMixin.minWidth([minWidth]) ⇒ Number | BaseMixin

Set or get the minimum width attribute of a chart. This only has effect when used with the default width function.

Kind: instance method of BaseMixin
See: width

Param Type Default
[minWidth] Number 200

baseMixin.minHeight([minHeight]) ⇒ Number | BaseMixin

Set or get the minimum height attribute of a chart. This only has effect when used with the default height function.

Kind: instance method of BaseMixin
See: height

Param Type Default
[minHeight] Number 200

baseMixin.useViewBoxResizing([useViewBoxResizing]) ⇒ Boolean | BaseMixin

Turn on/off using the SVG viewBox attribute. When enabled, viewBox will be set on the svg root element instead of width and height. Requires that the chart aspect ratio be defined using chart.width(w) and chart.height(h).

This will maintain the aspect ratio while enabling the chart to resize responsively to the space given to the chart using CSS. For example, the chart can use width: 100%; height: 100% or absolute positioning to resize to its parent div.

Since the text will be sized as if the chart is drawn according to the width and height, and will be resized if the chart is any other size, you need to set the chart width and height so that the text looks good. In practice, 600x400 seems to work pretty well for most charts.

You can see examples of this resizing strategy in the Chart Resizing Examples; just add ?resize=viewbox to any of the one-chart examples to enable useViewBoxResizing.

Kind: instance method of BaseMixin

Param Type Default
[useViewBoxResizing] Boolean false

baseMixin.dimension([dimension]) ⇒ crossfilter.dimension | BaseMixin

mandatory

Set or get the dimension attribute of a chart. In dc, a dimension can be any valid crossfilter dimension

If a value is given, then it will be used as the new dimension. If no value is specified then the current dimension will be returned.

Kind: instance method of BaseMixin
See: crossfilter.dimension

Param Type
[dimension] crossfilter.dimension

Example

var index = crossfilter([]);
var dimension = index.dimension(pluck('key'));
chart.dimension(dimension);

baseMixin.data([callback]) ⇒ * | BaseMixin

Set the data callback or retrieve the chart's data set. The data callback is passed the chart's group and by default will return group.all. This behavior may be modified to, for instance, return only the top 5 groups.

Kind: instance method of BaseMixin

Param Type
[callback] function

Example

// Default data function
chart.data(function (group) { return group.all(); });

chart.data(function (group) { return group.top(5); });

baseMixin.group([group], [name]) ⇒ crossfilter.group | BaseMixin

mandatory

Set or get the group attribute of a chart. In dc a group is a crossfilter group. Usually the group should be created from the particular dimension associated with the same chart. If a value is given, then it will be used as the new group.

If no value specified then the current group will be returned. If name is specified then it will be used to generate legend label.

Kind: instance method of BaseMixin
See: crossfilter.group

Param Type
[group] crossfilter.group
[name] String

Example

var index = crossfilter([]);
var dimension = index.dimension(pluck('key'));
chart.dimension(dimension);
chart.group(dimension.group().reduceSum());

baseMixin.ordering([orderFunction]) ⇒ function | BaseMixin

Get or set an accessor to order ordinal dimensions. The chart uses Array.sort to sort elements; this accessor returns the value to order on.

Kind: instance method of BaseMixin

Param Type
[orderFunction] function

Example

// Default ordering accessor
_chart.ordering(pluck('key'));

baseMixin.filterAll() ⇒ BaseMixin

Clear all filters associated with this chart. The same effect can be achieved by calling chart.filter(null).

Kind: instance method of BaseMixin

baseMixin.select(sel) ⇒ d3.selection

Execute d3 single selection in the chart's scope using the given selector and return the d3 selection.

This function is not chainable since it does not return a chart instance; however the d3 selection result can be chained to d3 function calls.

Kind: instance method of BaseMixin
See: d3.select

Param Type Description
sel String CSS selector string

Example

// Has the same effect as d3.select('#chart-id').select(selector)
chart.select(selector)

baseMixin.selectAll(sel) ⇒ d3.selection

Execute in scope d3 selectAll using the given selector and return d3 selection result.

This function is not chainable since it does not return a chart instance; however the d3 selection result can be chained to d3 function calls.

Kind: instance method of BaseMixin
See: d3.selectAll

Param Type Description
sel String CSS selector string

Example

// Has the same effect as d3.select('#chart-id').selectAll(selector)
chart.selectAll(selector)

baseMixin.anchor([parent], [chartGroup]) ⇒ String | node | d3.selection | BaseMixin

Set the root SVGElement to either be an existing chart's root; or any valid d3 single selector specifying a dom block element such as a div; or a dom element or d3 selection. Optionally registers the chart within the chartGroup. This class is called internally on chart initialization, but be called again to relocate the chart. However, it will orphan any previously created SVGElements.

Kind: instance method of BaseMixin

Param Type
[parent] anchorChart | anchorSelector | anchorNode
[chartGroup] String

baseMixin.anchorName() ⇒ String

Returns the DOM id for the chart's anchored location.

Kind: instance method of BaseMixin

baseMixin.root([rootElement]) ⇒ HTMLElement | BaseMixin

Returns the root element where a chart resides. Usually it will be the parent div element where the SVGElement was created. You can also pass in a new root element however this is usually handled by dc internally. Resetting the root element on a chart outside of dc internals may have unexpected consequences.

Kind: instance method of BaseMixin
See: HTMLElement

Param Type
[rootElement] HTMLElement

baseMixin.svg([svgElement]) ⇒ SVGElement | d3.selection | BaseMixin

Returns the top SVGElement for this specific chart. You can also pass in a new SVGElement, however this is usually handled by dc internally. Resetting the SVGElement on a chart outside of dc internals may have unexpected consequences.

Kind: instance method of BaseMixin
See: SVGElement

Param Type
[svgElement] SVGElement | d3.selection

baseMixin.resetSvg() ⇒ SVGElement

Remove the chart's SVGElements from the dom and recreate the container SVGElement.

Kind: instance method of BaseMixin
See: SVGElement

baseMixin.filterPrinter([filterPrinterFunction]) ⇒ function | BaseMixin

Set or get the filter printer function. The filter printer function is used to generate human friendly text for filter value(s) associated with the chart instance. The text will get shown in the `.filter element; see turnOnControls.

By default dc charts use a default filter printer filters that provides simple printing support for both single value and ranged filters.

Kind: instance method of BaseMixin

Param Type Default
[filterPrinterFunction] function printers.filters

Example

// for a chart with an ordinal brush, print the filters in upper case
chart.filterPrinter(function(filters) {
  return filters.map(function(f) { return f.toUpperCase(); }).join(', ');
});
// for a chart with a range brush, print the filter as start and extent
chart.filterPrinter(function(filters) {
  return 'start ' + utils.printSingleValue(filters[0][0]) +
    ' extent ' + utils.printSingleValue(filters[0][1] - filters[0][0]);
});

baseMixin.controlsUseVisibility([controlsUseVisibility]) ⇒ Boolean | BaseMixin

If set, use the visibility attribute instead of the display attribute for showing/hiding chart reset and filter controls, for less disruption to the layout.

Kind: instance method of BaseMixin

Param Type Default
[controlsUseVisibility] Boolean false

baseMixin.turnOnControls() ⇒ BaseMixin

Turn on optional control elements within the root element. dc currently supports the following html control elements.

  • root.selectAll('.reset') - elements are turned on if the chart has an active filter. This type of control element is usually used to store a reset link to allow user to reset filter on a certain chart. This element will be turned off automatically if the filter is cleared.
  • root.selectAll('.filter') elements are turned on if the chart has an active filter. The text content of this element is then replaced with the current filter value using the filter printer function. This type of element will be turned off automatically if the filter is cleared.

Kind: instance method of BaseMixin

baseMixin.turnOffControls() ⇒ BaseMixin

Turn off optional control elements within the root element.

Kind: instance method of BaseMixin
See: turnOnControls

baseMixin.transitionDuration([duration]) ⇒ Number | BaseMixin

Set or get the animation transition duration (in milliseconds) for this chart instance.

Kind: instance method of BaseMixin

Param Type Default
[duration] Number 750

baseMixin.transitionDelay([delay]) ⇒ Number | BaseMixin

Set or get the animation transition delay (in milliseconds) for this chart instance.

Kind: instance method of BaseMixin

Param Type Default
[delay] Number 0

baseMixin.render() ⇒ BaseMixin

Invoking this method will force the chart to re-render everything from scratch. Generally it should only be used to render the chart for the first time on the page or if you want to make sure everything is redrawn from scratch instead of relying on the default incremental redrawing behaviour.

Kind: instance method of BaseMixin

baseMixin.redraw() ⇒ BaseMixin

Calling redraw will cause the chart to re-render data changes incrementally. If there is no change in the underlying data dimension then calling this method will have no effect on the chart. Most chart interaction in dc will automatically trigger this method through internal events (in particular redrawAll); therefore, you only need to manually invoke this function if data is manipulated outside of dc's control (for example if data is loaded in the background using crossfilter.add).

Kind: instance method of BaseMixin

baseMixin.commitHandler(commitHandler) ⇒ BaseMixin

Gets/sets the commit handler. If the chart has a commit handler, the handler will be called when the chart's filters have changed, in order to send the filter data asynchronously to a server.

Unlike other functions in dc.js, the commit handler is asynchronous. It takes two arguments: a flag indicating whether this is a render (true) or a redraw (false), and a callback to be triggered once the commit is done. The callback has the standard node.js continuation signature with error first and result second.

Kind: instance method of BaseMixin

Param Type
commitHandler function

baseMixin.redrawGroup() ⇒ BaseMixin

Redraws all charts in the same group as this chart, typically in reaction to a filter change. If the chart has a commitHandler, it will be executed and waited for.

Kind: instance method of BaseMixin

baseMixin.renderGroup() ⇒ BaseMixin

Renders all charts in the same group as this chart. If the chart has a commitHandler, it will be executed and waited for

Kind: instance method of BaseMixin

baseMixin.hasFilterHandler([hasFilterHandler]) ⇒ function | BaseMixin

Set or get the has-filter handler. The has-filter handler is a function that checks to see if the chart's current filters (first argument) include a specific filter (second argument). Using a custom has-filter handler allows you to change the way filters are checked for and replaced.

Kind: instance method of BaseMixin

Param Type
[hasFilterHandler] function

Example

// default has-filter handler
chart.hasFilterHandler(function (filters, filter) {
    if (filter === null || typeof(filter) === 'undefined') {
        return filters.length > 0;
    }
    return filters.some(function (f) {
        return filter <= f && filter >= f;
    });
});

// custom filter handler (no-op)
chart.hasFilterHandler(function(filters, filter) {
    return false;
});

baseMixin.hasFilter([filter]) ⇒ Boolean

Check whether any active filter or a specific filter is associated with particular chart instance. This function is not chainable.

Kind: instance method of BaseMixin
See: hasFilterHandler

Param Type
[filter] *

baseMixin.removeFilterHandler([removeFilterHandler]) ⇒ function | BaseMixin

Set or get the remove filter handler. The remove filter handler is a function that removes a filter from the chart's current filters. Using a custom remove filter handler allows you to change how filters are removed or perform additional work when removing a filter, e.g. when using a filter server other than crossfilter.

The handler should return a new or modified array as the result.

Kind: instance method of BaseMixin

Param Type
[removeFilterHandler] function

Example

// default remove filter handler
chart.removeFilterHandler(function (filters, filter) {
    for (var i = 0; i < filters.length; i++) {
        if (filters[i] <= filter && filters[i] >= filter) {
            filters.splice(i, 1);
            break;
        }
    }
    return filters;
});

// custom filter handler (no-op)
chart.removeFilterHandler(function(filters, filter) {
    return filters;
});

baseMixin.addFilterHandler([addFilterHandler]) ⇒ function | BaseMixin

Set or get the add filter handler. The add filter handler is a function that adds a filter to the chart's filter list. Using a custom add filter handler allows you to change the way filters are added or perform additional work when adding a filter, e.g. when using a filter server other than crossfilter.

The handler should return a new or modified array as the result.

Kind: instance method of BaseMixin

Param Type
[addFilterHandler] function

Example

// default add filter handler
chart.addFilterHandler(function (filters, filter) {
    filters.push(filter);
    return filters;
});

// custom filter handler (no-op)
chart.addFilterHandler(function(filters, filter) {
    return filters;
});

baseMixin.resetFilterHandler([resetFilterHandler]) ⇒ BaseMixin

Set or get the reset filter handler. The reset filter handler is a function that resets the chart's filter list by returning a new list. Using a custom reset filter handler allows you to change the way filters are reset, or perform additional work when resetting the filters, e.g. when using a filter server other than crossfilter.

The handler should return a new or modified array as the result.

Kind: instance method of BaseMixin

Param Type
[resetFilterHandler] function

Example

// default remove filter handler
function (filters) {
    return [];
}

// custom filter handler (no-op)
chart.resetFilterHandler(function(filters) {
    return filters;
});

baseMixin.replaceFilter([filter]) ⇒ BaseMixin

Replace the chart filter. This is equivalent to calling chart.filter(null).filter(filter) but more efficient because the filter is only applied once.

Kind: instance method of BaseMixin

Param Type
[filter] *

baseMixin.filter([filter]) ⇒ BaseMixin

Filter the chart by the given parameter, or return the current filter if no input parameter is given.

The filter parameter can take one of these forms:

Note that this is always a toggle (even when it doesn't make sense for the filter type). If you wish to replace the current filter, either call chart.filter(null) first - or it's more efficient to call chart.replaceFilter(filter) instead.

Each toggle is executed by checking if the value is already present using the hasFilterHandler; if it is not present, it is added using the addFilterHandler; if it is already present, it is removed using the removeFilterHandler.

Once the filters array has been updated, the filters are applied to the crossfilter dimension, using the filterHandler.

Once you have set the filters, call chart.redrawGroup() (or redrawAll()) to redraw the chart's group.

Kind: instance method of BaseMixin
See

Param Type
[filter] *

Example

// filter by a single string
chart.filter('Sunday');
// filter by a single age
chart.filter(18);
// filter by a set of states
chart.filter([['MA', 'TX', 'ND', 'WA']]);
// filter by range -- note the use of filters.RangedFilter, which is different
// from the syntax for filtering a crossfilter dimension directly, dimension.filter([15,20])
chart.filter(filters.RangedFilter(15,20));

baseMixin.filters() ⇒ Array.<*>

Returns all current filters. This method does not perform defensive cloning of the internal filter array before returning, therefore any modification of the returned array will effect the chart's internal filter storage.

Kind: instance method of BaseMixin

baseMixin.onClick(datum) ⇒ undefined

This function is passed to d3 as the onClick handler for each chart. The default behavior is to filter on the clicked datum (passed to the callback) and redraw the chart group.

This function can be replaced in order to change the click behavior (but first look at

Kind: instance method of BaseMixin

Param Type
datum *

Example

var oldHandler = chart.onClick;
chart.onClick = function(datum) {
  // use datum.

baseMixin.filterHandler([filterHandler]) ⇒ function | BaseMixin

Set or get the filter handler. The filter handler is a function that performs the filter action on a specific dimension. Using a custom filter handler allows you to perform additional logic before or after filtering.

Kind: instance method of BaseMixin
See: crossfilter.dimension.filter

Param Type
[filterHandler] function

Example

// the default filter handler handles all possible cases for the charts in dc.js
// you can replace it with something more specialized for your own chart
chart.filterHandler(function (dimension, filters) {
    if (filters.length === 0) {
        // the empty case (no filtering)
        dimension.filter(null);
    } else if (filters.length === 1 && !filters[0].isFiltered) {
        // single value and not a function-based filter
        dimension.filterExact(filters[0]);
    } else if (filters.length === 1 && filters[0].filterType === 'RangedFilter') {
        // single range-based filter
        dimension.filterRange(filters[0]);
    } else {
        // an array of values, or an array of filter objects
        dimension.filterFunction(function (d) {
            for (var i = 0; i < filters.length; i++) {
                var filter = filters[i];
                if (filter.isFiltered && filter.isFiltered(d)) {
                    return true;
                } else if (filter <= d && filter >= d) {
                    return true;
                }
            }
            return false;
        });
    }
    return filters;
});

// custom filter handler
chart.filterHandler(function(dimension, filter){
    var newFilter = filter + 10;
    dimension.filter(newFilter);
    return newFilter; // set the actual filter value to the new value
});

baseMixin.keyAccessor([keyAccessor]) ⇒ function | BaseMixin

Set or get the key accessor function. The key accessor function is used to retrieve the key value from the crossfilter group. Key values are used differently in different charts, for example keys correspond to slices in a pie chart and x axis positions in a grid coordinate chart.

Kind: instance method of BaseMixin

Param Type
[keyAccessor] function

Example

// default key accessor
chart.keyAccessor(function(d) { return d.key; });
// custom key accessor for a multi-value crossfilter reduction
chart.keyAccessor(function(p) { return p.value.absGain; });

baseMixin.valueAccessor([valueAccessor]) ⇒ function | BaseMixin

Set or get the value accessor function. The value accessor function is used to retrieve the value from the crossfilter group. Group values are used differently in different charts, for example values correspond to slice sizes in a pie chart and y axis positions in a grid coordinate chart.

Kind: instance method of BaseMixin

Param Type
[valueAccessor] function

Example

// default value accessor
chart.valueAccessor(function(d) { return d.value; });
// custom value accessor for a multi-value crossfilter reduction
chart.valueAccessor(function(p) { return p.value.percentageGain; });

baseMixin.label([labelFunction], [enableLabels]) ⇒ function | BaseMixin

Set or get the label function. The chart class will use this function to render labels for each child element in the chart, e.g. slices in a pie chart or bubbles in a bubble chart. Not every chart supports the label function, for example line chart does not use this function at all. By default, enables labels; pass false for the second parameter if this is not desired.

Kind: instance method of BaseMixin

Param Type Default
[labelFunction] function
[enableLabels] Boolean true

Example

// default label function just return the key
chart.label(function(d) { return d.key; });
// label function has access to the standard d3 data binding and can get quite complicated
chart.label(function(d) { return d.data.key + '(' + Math.floor(d.data.value / all.value() * 100) + '%)'; });

baseMixin.renderLabel([renderLabel]) ⇒ Boolean | BaseMixin

Turn on/off label rendering

Kind: instance method of BaseMixin

Param Type Default
[renderLabel] Boolean false

baseMixin.title([titleFunction]) ⇒ function | BaseMixin

Set or get the title function. The chart class will use this function to render the SVGElement title (usually interpreted by browser as tooltips) for each child element in the chart, e.g. a slice in a pie chart or a bubble in a bubble chart. Almost every chart supports the title function; however in grid coordinate charts you need to turn off the brush in order to see titles, because otherwise the brush layer will block tooltip triggering.

Kind: instance method of BaseMixin

Param Type
[titleFunction] function

Example

// default title function shows "key: value"
chart.title(function(d) { return d.key + ': ' + d.value; });
// title function has access to the standard d3 data binding and can get quite complicated
chart.title(function(p) {
   return p.key.getFullYear()
       + '\n'
       + 'Index Gain: ' + numberFormat(p.value.absGain) + '\n'
       + 'Index Gain in Percentage: ' + numberFormat(p.value.percentageGain) + '%\n'
       + 'Fluctuation / Index Ratio: ' + numberFormat(p.value.fluctuationPercentage) + '%';
});

baseMixin.renderTitle([renderTitle]) ⇒ Boolean | BaseMixin

Turn on/off title rendering, or return the state of the render title flag if no arguments are given.

Kind: instance method of BaseMixin

Param Type Default
[renderTitle] Boolean true

baseMixin.chartGroup([chartGroup]) ⇒ String | BaseMixin

Get or set the chart group to which this chart belongs. Chart groups are rendered or redrawn together since it is expected they share the same underlying crossfilter data set.

Kind: instance method of BaseMixin

Param Type
[chartGroup] String

baseMixin.expireCache() ⇒ BaseMixin

Expire the internal chart cache. dc charts cache some data internally on a per chart basis to speed up rendering and avoid unnecessary calculation; however it might be useful to clear the cache if you have changed state which will affect rendering. For example, if you invoke crossfilter.add function or reset group or dimension after rendering, it is a good idea to clear the cache to make sure charts are rendered properly.

Kind: instance method of BaseMixin

baseMixin.legend([legend]) ⇒ Legend | BaseMixin

Attach a Legend widget to this chart. The legend widget will automatically draw legend labels based on the color setting and names associated with each group.

Kind: instance method of BaseMixin

Param Type
[legend] Legend

Example

chart.legend(new Legend().x(400).y(10).itemHeight(13).gap(5))

baseMixin.chartID() ⇒ String

Returns the internal numeric ID of the chart.

Kind: instance method of BaseMixin

baseMixin.options(opts) ⇒ BaseMixin

Set chart options using a configuration object. Each key in the object will cause the method of the same name to be called with the value to set that attribute for the chart.

Kind: instance method of BaseMixin

Param Type
opts Object

Example

chart.options({dimension: myDimension, group: myGroup});

baseMixin.on(event, listener) ⇒ BaseMixin

All dc chart instance supports the following listeners. Supports the following events:

  • renderlet - This listener function will be invoked after transitions after redraw and render. Replaces the deprecated renderlet method.
  • pretransition - Like .on('renderlet', ...) but the event is fired before transitions start.
  • preRender - This listener function will be invoked before chart rendering.
  • postRender - This listener function will be invoked after chart finish rendering including all renderlets' logic.
  • preRedraw - This listener function will be invoked before chart redrawing.
  • postRedraw - This listener function will be invoked after chart finish redrawing including all renderlets' logic.
  • filtered - This listener function will be invoked after a filter is applied, added or removed.
  • zoomed - This listener function will be invoked after a zoom is triggered.

Kind: instance method of BaseMixin
See: d3.dispatch.on

Param Type
event String
listener function

Example

.on('renderlet', function(chart, filter){...})
.on('pretransition', function(chart, filter){...})
.on('preRender', function(chart){...})
.on('postRender', function(chart){...})
.on('preRedraw', function(chart){...})
.on('postRedraw', function(chart){...})
.on('filtered', function(chart, filter){...})
.on('zoomed', function(chart, filter){...})

baseMixin.renderlet(renderletFunction) ⇒ BaseMixin

Deprecated

A renderlet is similar to an event listener on rendering event. Multiple renderlets can be added to an individual chart. Each time a chart is rerendered or redrawn the renderlets are invoked right after the chart finishes its transitions, giving you a way to modify the SVGElements. Renderlet functions take the chart instance as the only input parameter and you can use the dc API or use raw d3 to achieve pretty much any effect.

Use on with a 'renderlet' prefix. Generates a random key for the renderlet, which makes it hard to remove.

Kind: instance method of BaseMixin

Param Type
renderletFunction function

Example

// do this instead of .renderlet(function(chart) { ... })
chart.on("renderlet", function(chart){
    // mix of dc API and d3 manipulation
    chart.select('g.y').style('display', 'none');
    // its a closure so you can also access other chart variable available in the closure scope
    moveChart.filter(chart.filter());
});

ColorMixin ⇒ ColorMixin

The Color Mixin is an abstract chart functional class providing universal coloring support as a mix-in for any concrete chart implementation.

Kind: global mixin

Param Type
Base Object

colorMixin.getColor(d, [i]) ⇒ String

Get the color for the datum d and counter i. This is used internally by charts to retrieve a color.

Kind: instance method of ColorMixin

Param Type
d *
[i] Number

colorMixin.calculateColorDomain() ⇒ ColorMixin

Set the domain by determining the min and max values as retrieved by .colorAccessor over the chart's dataset.

Kind: instance method of ColorMixin

colorMixin.colors([colorScale]) ⇒ d3.scale | ColorMixin

Retrieve current color scale or set a new color scale. This methods accepts any function that operates like a d3 scale.

Kind: instance method of ColorMixin
See: d3.scale

Param Type Default
[colorScale] d3.scale d3.scaleOrdinal(d3.schemeCategory20c)

Example

// alternate categorical scale
chart.colors(d3.scale.category20b());
// ordinal scale
chart.colors(d3.scaleOrdinal().range(['red','green','blue']));
// convenience method, the same as above
chart.ordinalColors(['red','green','blue']);
// set a linear scale
chart.linearColors(["#4575b4", "#ffffbf", "#a50026"]);

colorMixin.ordinalColors(r) ⇒ ColorMixin

Convenience method to set the color scale to d3.scaleOrdinal with range r.

Kind: instance method of ColorMixin

Param Type
r Array.<String>

colorMixin.linearColors(r) ⇒ ColorMixin

Convenience method to set the color scale to an Hcl interpolated linear scale with range r.

Kind: instance method of ColorMixin

Param Type
r Array.<Number>

colorMixin.colorAccessor([colorAccessor]) ⇒ function | ColorMixin

Set or the get color accessor function. This function will be used to map a data point in a crossfilter group to a color value on the color scale. The default function uses the key accessor.

Kind: instance method of ColorMixin

Param Type
[colorAccessor] function

Example

// default index based color accessor
.colorAccessor(function (d, i){return i;})
// color accessor for a multi-value crossfilter reduction
.colorAccessor(function (d){return d.value.absGain;})

colorMixin.colorDomain([domain]) ⇒ Array.<String> | ColorMixin

Set or get the current domain for the color mapping function. The domain must be supplied as an array.

Note: previously this method accepted a callback function. Instead you may use a custom scale set by .colors.

Kind: instance method of ColorMixin

Param Type
[domain] Array.<String>

colorMixin.colorCalculator([colorCalculator]) ⇒ function | ColorMixin

Overrides the color selection algorithm, replacing it with a simple function.

Normally colors will be determined by calling the colorAccessor to get a value, and then passing that value through the colorScale.

But sometimes it is difficult to get a color scale to produce the desired effect. The colorCalculator takes the datum and index and returns a color directly.

Kind: instance method of ColorMixin

Param Type
[colorCalculator] *

BubbleMixin ⇒ BubbleMixin

This Mixin provides reusable functionalities for any chart that needs to visualize data using bubbles.

Kind: global mixin
Mixes: ColorMixin

Param Type
Base Object

bubbleMixin.r([bubbleRadiusScale]) ⇒ d3.scale | BubbleMixin

Get or set the bubble radius scale. By default the bubble chart uses d3.scaleLinear().domain([0, 100]) as its radius scale.

Kind: instance method of BubbleMixin
See: d3.scale

Param Type Default
[bubbleRadiusScale] d3.scale d3.scaleLinear().domain([0, 100])

bubbleMixin.radiusValueAccessor([radiusValueAccessor]) ⇒ function | BubbleMixin

Get or set the radius value accessor function. If set, the radius value accessor function will be used to retrieve a data value for each bubble. The data retrieved then will be mapped using the r scale to the actual bubble radius. This allows you to encode a data dimension using bubble size.

Kind: instance method of BubbleMixin

Param Type
[radiusValueAccessor] function

bubbleMixin.minRadius([radius]) ⇒ Number | BubbleMixin

Get or set the minimum radius. This will be used to initialize the radius scale's range.

Kind: instance method of BubbleMixin

Param Type Default
[radius] Number 10

bubbleMixin.minRadiusWithLabel([radius]) ⇒ Number | BubbleMixin

Get or set the minimum radius for label rendering. If a bubble's radius is less than this value then no label will be rendered.

Kind: instance method of BubbleMixin

Param Type Default
[radius] Number 10

bubbleMixin.maxBubbleRelativeSize([relativeSize]) ⇒ Number | BubbleMixin

Get or set the maximum relative size of a bubble to the length of x axis. This value is useful when the difference in radius between bubbles is too great.

Kind: instance method of BubbleMixin

Param Type Default
[relativeSize] Number 0.3

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.

Kind: global mixin

Param Type
Base Object

capMixin.cap([count]) ⇒ Number | CapMixin

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.

Kind: instance method of CapMixin

Param Type Default
[count] Number Infinity

capMixin.takeFront([takeFront]) ⇒ Boolean | CapMixin

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.

Kind: instance method of CapMixin

Param Type Default
[takeFront] Boolean true

capMixin.othersLabel([label]) ⇒ String | CapMixin

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

Kind: instance method of CapMixin

Param Type Default
[label] String "Others"

capMixin.othersGrouper([grouperFunction]) ⇒ function | CapMixin

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.

Kind: instance method of CapMixin

Param Type
[grouperFunction] function

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

MarginMixin ⇒ MarginMixin

Margin is a mixin that provides margin utility functions for both the Row Chart and Coordinate Grid Charts.

Kind: global mixin

Param Type
Base Object

marginMixin.margins([margins]) ⇒ Object | MarginMixin

Get or set the margins for a particular coordinate grid chart instance. The margins is stored as an associative Javascript array.

Kind: instance method of MarginMixin

Param Type Default
[margins] Object {top: 10, right: 50, bottom: 30, left: 30}

Example

var leftMargin = chart.margins().left; // 30 by default
chart.margins().left = 50;
leftMargin = chart.margins().left; // now 50

marginMixin.effectiveWidth() ⇒ number

Effective width of the chart excluding margins (in pixels).

Kind: instance method of MarginMixin

marginMixin.effectiveHeight() ⇒ number

Effective height of the chart excluding margins (in pixels).

Kind: instance method of MarginMixin

CoordinateGridMixin

Coordinate Grid is an abstract base chart designed to support a number of coordinate grid based concrete chart types, e.g. bar chart, line chart, and bubble chart.

Kind: global mixin
Mixes: ColorMixin, MarginMixin

coordinateGridMixin.rescale() ⇒ CoordinateGridMixin

When changing the domain of the x or y scale, it is necessary to tell the chart to recalculate and redraw the axes. (.rescale() is called automatically when the x or y scale is replaced with .x() or .y(), and has no effect on elastic scales.)

Kind: instance method of CoordinateGridMixin

coordinateGridMixin.rangeChart([rangeChart]) ⇒ CoordinateGridMixin

Get or set the range selection chart associated with this instance. Setting the range selection chart using this function will automatically update its selection brush when the current chart zooms in. In return the given range chart will also automatically attach this chart as its focus chart hence zoom in when range brush updates.

Usually the range and focus charts will share a dimension. The range chart will set the zoom boundaries for the focus chart, so its dimension values must be compatible with the domain of the focus chart.

See the Nasdaq 100 Index example for this effect in action.

Kind: instance method of CoordinateGridMixin

Param Type
[rangeChart] CoordinateGridMixin

coordinateGridMixin.zoomScale([extent]) ⇒ Array.<(Number|Date)> | CoordinateGridMixin

Get or set the scale extent for mouse zooms.

Kind: instance method of CoordinateGridMixin

Param Type Default
[extent] Array.<(Number|Date)> [1, Infinity]

coordinateGridMixin.zoomOutRestrict([zoomOutRestrict]) ⇒ Boolean | CoordinateGridMixin

Get or set the zoom restriction for the chart. If true limits the zoom to origional domain of the chart.

Kind: instance method of CoordinateGridMixin

Param Type Default
[zoomOutRestrict] Boolean true

coordinateGridMixin.g([gElement]) ⇒ SVGElement | CoordinateGridMixin

Get or set the root g element. This method is usually used to retrieve the g element in order to overlay custom svg drawing programatically. Caution: The root g element is usually generated by dc.js internals, and resetting it might produce unpredictable result.

Kind: instance method of CoordinateGridMixin

Param Type
[gElement] SVGElement

coordinateGridMixin.mouseZoomable([mouseZoomable]) ⇒ Boolean | CoordinateGridMixin

Set or get mouse zoom capability flag (default: false). When turned on the chart will be zoomable using the mouse wheel. If the range selector chart is attached zooming will also update the range selection brush on the associated range selector chart.

Kind: instance method of CoordinateGridMixin

Param Type Default
[mouseZoomable] Boolean false

coordinateGridMixin.chartBodyG([chartBodyG]) ⇒ SVGElement

Retrieve the svg group for the chart body.

Kind: instance method of CoordinateGridMixin

Param Type
[chartBodyG] SVGElement

coordinateGridMixin.x([xScale]) ⇒ d3.scale | CoordinateGridMixin

mandatory

Get or set the x scale. The x scale can be any d3 d3.scale or ordinal scale

Kind: instance method of CoordinateGridMixin
See: d3.scale

Param Type
[xScale] d3.scale

Example

// set x to a linear scale
chart.x(d3.scaleLinear().domain([-2500, 2500]))
// set x to a time scale to generate histogram
chart.x(d3.scaleTime().domain([new Date(1985, 0, 1), new Date(2012, 11, 31)]))

coordinateGridMixin.xUnits([xUnits]) ⇒ function | CoordinateGridMixin

Set or get the xUnits function. The coordinate grid chart uses the xUnits function to calculate the number of data projections on the x axis such as the number of bars for a bar chart or the number of dots for a line chart.

This function is expected to return a Javascript array of all data points on the x axis, or the number of points on the axis. d3 time range functions d3.timeDays, d3.timeMonths, and d3.timeYears are all valid xUnits functions.

dc.js also provides a few units function, see the Units Namespace for a list of built-in units functions.

Note that as of dc.js 3.0, units.ordinal is not a real function, because it is not possible to define this function compliant with the d3 range functions. It was already a magic value which caused charts to behave differently, and now it is completely so.

Kind: instance method of CoordinateGridMixin

Param Type Default
[xUnits] function units.integers

Example

// set x units to count days
chart.xUnits(d3.timeDays);
// set x units to count months
chart.xUnits(d3.timeMonths);

// A custom xUnits function can be used as long as it follows the following interface:
// units in integer
function(start, end) {
     // simply calculates how many integers in the domain
     return Math.abs(end - start);
}

// fixed units
function(start, end) {
     // be aware using fixed units will disable the focus/zoom ability on the chart
     return 1000;
}

coordinateGridMixin.xAxis([xAxis]) ⇒ d3.axis | CoordinateGridMixin

Set or get the x axis used by a particular coordinate grid chart instance. This function is most useful when x axis customization is required. The x axis in dc.js is an instance of a d3 bottom axis object; therefore it supports any valid d3 axisBottom manipulation.

Caution: The x axis is usually generated internally by dc; resetting it may cause unexpected results. Note also that when used as a getter, this function is not chainable: it returns the axis, not the chart, so attempting to call chart functions after calling .xAxis() will fail.

Kind: instance method of CoordinateGridMixin
See: d3.axisBottom

Param Type Default
[xAxis] d3.axis d3.axisBottom()

Example

// customize x axis tick format
chart.xAxis().tickFormat(function(v) {return v + '%';});
// customize x axis tick values
chart.xAxis().tickValues([0, 100, 200, 300]);

coordinateGridMixin.elasticX([elasticX]) ⇒ Boolean | CoordinateGridMixin

Turn on/off elastic x axis behavior. If x axis elasticity is turned on, then the grid chart will attempt to recalculate the x axis range whenever a redraw event is triggered.

Kind: instance method of CoordinateGridMixin

Param Type Default
[elasticX] Boolean false

coordinateGridMixin.xAxisPadding([padding]) ⇒ Number | String | CoordinateGridMixin

Set or get x axis padding for the elastic x axis. The padding will be added to both end of the x axis if elasticX is turned on; otherwise it is ignored.

Padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to number or date x axes. When padding a date axis, an integer represents number of units being padded and a percentage string will be treated the same as an integer. The unit will be determined by the xAxisPaddingUnit variable.

Kind: instance method of CoordinateGridMixin

Param Type Default
[padding] Number | String 0

coordinateGridMixin.xAxisPaddingUnit([unit]) ⇒ String | CoordinateGridMixin

Set or get x axis padding unit for the elastic x axis. The padding unit will determine which unit to use when applying xAxis padding if elasticX is turned on and if x-axis uses a time dimension; otherwise it is ignored.

The padding unit should be a d3 time interval. For backward compatibility with dc.js 2.0, it can also be the name of a d3 time interval ('day', 'hour', etc). Available arguments are the [d3 time intervals](https://github.com/d3/d3-time/blob/master/README.md#intervals d3.timeInterval).

Kind: instance method of CoordinateGridMixin

Param Type Default
[unit] String d3.timeDay

coordinateGridMixin.xUnitCount() ⇒ Number

Returns the number of units displayed on the x axis. If the x axis is ordinal (xUnits is units.ordinal), this is the number of items in the domain of the x scale. Otherwise, the x unit count is calculated using the xUnits function.

Kind: instance method of CoordinateGridMixin

coordinateGridMixin.useRightYAxis([useRightYAxis]) ⇒ Boolean | CoordinateGridMixin

Gets or sets whether the chart should be drawn with a right axis instead of a left axis. When used with a chart in a composite chart, allows both left and right Y axes to be shown on a chart.

Kind: instance method of CoordinateGridMixin

Param Type Default
[useRightYAxis] Boolean false

coordinateGridMixin.isOrdinal() ⇒ Boolean

Returns true if the chart is using ordinal xUnits (ordinal, or false otherwise. Most charts behave differently with ordinal data and use the result of this method to trigger the appropriate logic.

Kind: instance method of CoordinateGridMixin

coordinateGridMixin.xAxisLabel([labelText], [padding]) ⇒ String

Set or get the x axis label. If setting the label, you may optionally include additional padding to the margin to make room for the label. By default the padded is set to 12 to accomodate the text height.

Kind: instance method of CoordinateGridMixin

Param Type Default
[labelText] String
[padding] Number 12

coordinateGridMixin.yAxisLabel([labelText], [padding]) ⇒ String | CoordinateGridMixin

Set or get the y axis label. If setting the label, you may optionally include additional padding to the margin to make room for the label. By default the padding is set to 12 to accommodate the text height.

Kind: instance method of CoordinateGridMixin

Param Type Default
[labelText] String
[padding] Number 12

coordinateGridMixin.y([yScale]) ⇒ d3.scale | CoordinateGridMixin

Get or set the y scale. The y scale is typically automatically determined by the chart implementation.

Kind: instance method of CoordinateGridMixin
See: d3.scale

Param Type
[yScale] d3.scale

coordinateGridMixin.yAxis([yAxis]) ⇒ d3.axisLeft | d3.axisRight | CoordinateGridMixin

Set or get the y axis used by the coordinate grid chart instance. This function is most useful when y axis customization is required. Depending on useRightYAxis the y axis in dc.js is an instance of either d3.axisLeft or d3.axisRight; therefore it supports any valid d3 axis manipulation.

Caution: The y axis is usually generated internally by dc; resetting it may cause unexpected results. Note also that when used as a getter, this function is not chainable: it returns the axis, not the chart, so attempting to call chart functions after calling .yAxis() will fail. In addition, depending on whether you are going to use the axis on left or right you need to appropriately pass d3.axisLeft or d3.axisRight

Kind: instance method of CoordinateGridMixin
See: d3.axis

Param Type
[yAxis] d3.axisLeft | d3.axisRight

Example

// customize y axis tick format
chart.yAxis().tickFormat(function(v) {return v + '%';});
// customize y axis tick values
chart.yAxis().tickValues([0, 100, 200, 300]);

coordinateGridMixin.elasticY([elasticY]) ⇒ Boolean | CoordinateGridMixin

Turn on/off elastic y axis behavior. If y axis elasticity is turned on, then the grid chart will attempt to recalculate the y axis range whenever a redraw event is triggered.

Kind: instance method of CoordinateGridMixin

Param Type Default
[elasticY] Boolean false

coordinateGridMixin.renderHorizontalGridLines([renderHorizontalGridLines]) ⇒ Boolean | CoordinateGridMixin

Turn on/off horizontal grid lines.

Kind: instance method of CoordinateGridMixin

Param Type Default
[renderHorizontalGridLines] Boolean false

coordinateGridMixin.renderVerticalGridLines([renderVerticalGridLines]) ⇒ Boolean | CoordinateGridMixin

Turn on/off vertical grid lines.

Kind: instance method of CoordinateGridMixin

Param Type Default
[renderVerticalGridLines] Boolean false

coordinateGridMixin.xAxisMin() ⇒ *

Calculates the minimum x value to display in the chart. Includes xAxisPadding if set.

Kind: instance method of CoordinateGridMixin

coordinateGridMixin.xAxisMax() ⇒ *

Calculates the maximum x value to display in the chart. Includes xAxisPadding if set.

Kind: instance method of CoordinateGridMixin

coordinateGridMixin.yAxisMin() ⇒ *

Calculates the minimum y value to display in the chart. Includes yAxisPadding if set.

Kind: instance method of CoordinateGridMixin

coordinateGridMixin.yAxisMax() ⇒ *

Calculates the maximum y value to display in the chart. Includes yAxisPadding if set.

Kind: instance method of CoordinateGridMixin

coordinateGridMixin.yAxisPadding([padding]) ⇒ Number | CoordinateGridMixin

Set or get y axis padding for the elastic y axis. The padding will be added to the top and bottom of the y axis if elasticY is turned on; otherwise it is ignored.

Padding can be an integer or percentage in string (e.g. '10%'). Padding can be applied to number or date axes. When padding a date axis, an integer represents number of days being padded and a percentage string will be treated the same as an integer.

Kind: instance method of CoordinateGridMixin

Param Type Default
[padding] Number | String 0

coordinateGridMixin.round([round]) ⇒ function | CoordinateGridMixin

Set or get the rounding function used to quantize the selection when brushing is enabled.

Kind: instance method of CoordinateGridMixin

Param Type
[round] function

Example

// set x unit round to by month, this will make sure range selection brush will
// select whole months
chart.round(d3.timeMonth.round);

coordinateGridMixin.brush([_]) ⇒ d3.brush | CoordinateGridMixin

Get or set the brush. Brush must be an instance of d3 brushes https://github.com/d3/d3-brush/blob/master/README.md You will use this only if you are writing a new chart type that supports brushing.

Caution: dc creates and manages brushes internally. Go through and understand the source code if you want to pass a new brush object. Even if you are only using the getter, the brush object may not behave the way you expect.

Kind: instance method of CoordinateGridMixin

Param Type
[_] d3.brush

coordinateGridMixin.clipPadding([padding]) ⇒ Number | CoordinateGridMixin

Get or set the padding in pixels for the clip path. Once set padding will be applied evenly to the top, left, right, and bottom when the clip path is generated. If set to zero, the clip area will be exactly the chart body area minus the margins.

Kind: instance method of CoordinateGridMixin

Param Type Default
[padding] Number 5

coordinateGridMixin.focus([range], [noRaiseEvents]) ⇒ undefined

Zoom this chart to focus on the given range. The given range should be an array containing only 2 elements ([start, end]) defining a range in the x domain. If the range is not given or set to null, then the zoom will be reset. _For focus to work elasticX has to be turned off; otherwise focus will be ignored.

To avoid ping-pong volley of events between a pair of range and focus charts please set noRaiseEvents to true. In that case it will update this chart but will not fire zoom event and not try to update back the associated range chart. If you are calling it manually - typically you will leave it to false (the default).

Kind: instance method of CoordinateGridMixin

Param Type Default
[range] Array.<Number>
[noRaiseEvents] Boolean false

Example

chart.on('renderlet', function(chart) {
    // smooth the rendering through event throttling
    events.trigger(function(){
         // focus some other chart to the range selected by user on this chart
         someOtherChart.focus(chart.filter());
    });
})

coordinateGridMixin.brushOn([brushOn]) ⇒ Boolean | CoordinateGridMixin

Turn on/off the brush-based range filter. When brushing is on then user can drag the mouse across a chart with a quantitative scale to perform range filtering based on the extent of the brush, or click on the bars of an ordinal bar chart or slices of a pie chart to filter and un-filter them. However turning on the brush filter will disable other interactive elements on the chart such as highlighting, tool tips, and reference lines. Zooming will still be possible if enabled, but only via scrolling (panning will be disabled.)

Kind: instance method of CoordinateGridMixin

Param Type Default
[brushOn] Boolean true

coordinateGridMixin.parentBrushOn([brushOn]) ⇒ Boolean | CoordinateGridMixin

This will be internally used by composite chart onto children. Please go not invoke directly.

Kind: instance method of CoordinateGridMixin
Access: protected

Param Type Default
[brushOn] Boolean false

StackMixin

Stack Mixin is an mixin that provides cross-chart support of stackability using d3.stack.

Kind: global mixin
Mixes: CoordinateGridMixin

stackMixin.stack(group, [name], [accessor]) ⇒ Array.<{group: crossfilter.group, name: String, accessor: function()}> | StackMixin

Stack a new crossfilter group onto this chart with an optional custom value accessor. All stacks in the same chart will share the same key accessor and therefore the same set of keys.

For example, in a stacked bar chart, the bars of each stack will be positioned using the same set of keys on the x axis, while stacked vertically. If name is specified then it will be used to generate the legend label.

Kind: instance method of StackMixin
See: crossfilter.group

Param Type
group crossfilter.group
[name] String
[accessor] function

Example

// stack group using default accessor
chart.stack(valueSumGroup)
// stack group using custom accessor
.stack(avgByDayGroup, function(d){return d.value.avgByDay;});

stackMixin.hidableStacks([hidableStacks]) ⇒ Boolean | StackMixin

Allow named stacks to be hidden or shown by clicking on legend items. This does not affect the behavior of hideStack or showStack.

Kind: instance method of StackMixin

Param Type Default
[hidableStacks] Boolean false

stackMixin.hideStack(stackName) ⇒ StackMixin

Hide all stacks on the chart with the given name. The chart must be re-rendered for this change to appear.

Kind: instance method of StackMixin

Param Type
stackName String

stackMixin.showStack(stackName) ⇒ StackMixin

Show all stacks on the chart with the given name. The chart must be re-rendered for this change to appear.

Kind: instance method of StackMixin

Param Type
stackName String

stackMixin.title([stackName], [titleAccessor]) ⇒ String | StackMixin

Set or get the title function. Chart class will use this function to render svg title (usually interpreted by browser as tooltips) for each child element in the chart, i.e. a slice in a pie chart or a bubble in a bubble chart. Almost every chart supports title function however in grid coordinate chart you need to turn off brush in order to use title otherwise the brush layer will block tooltip trigger.

If the first argument is a stack name, the title function will get or set the title for that stack. If stackName is not provided, the first stack is implied.

Kind: instance method of StackMixin

Param Type
[stackName] String
[titleAccessor] function

Example

// set a title function on 'first stack'
chart.title('first stack', function(d) { return d.key + ': ' + d.value; });
// get a title function from 'second stack'
var secondTitleFunction = chart.title('second stack');

stackMixin.stackLayout([_stack]) ⇒ function | StackMixin

Gets or sets the stack layout algorithm, which computes a baseline for each stack and propagates it to the next.

Kind: instance method of StackMixin
See: d3.stackD3v3

Param Type Default
[_stack] function d3.stackD3v3

stackMixin.evadeDomainFilter([evadeDomainFilter]) ⇒ Boolean | StackMixin

Since dc.js 2.0, there has been an issue where points are filtered to the current domain. While this is a useful optimization, it is incorrectly implemented: the next point outside the domain is required in order to draw lines that are clipped to the bounds, as well as bars that are partly clipped.

A fix will be included in dc.js 2.1.x, but a workaround is needed for dc.js 2.0 and until that fix is published, so set this flag to skip any filtering of points.

Once the bug is fixed, this flag will have no effect, and it will be deprecated.

Kind: instance method of StackMixin

Param Type Default
[evadeDomainFilter] Boolean false

filters : object

The dc.js filters are functions which are passed into crossfilter to chose which records will be accumulated to produce values for the charts. In the crossfilter model, any filters applied on one dimension will affect all the other dimensions but not that one. dc always applies a filter function to the dimension; the function combines multiple filters and if any of them accept a record, it is filtered in.

These filter constructors are used as appropriate by the various charts to implement brushing. We mention below which chart uses which filter. In some cases, many instances of a filter will be added.

Each of the dc.js filters is an object with the following properties:

  • isFiltered - a function that returns true if a value is within the filter
  • filterType - a string identifying the filter, here the name of the constructor

Currently these filter objects are also arrays, but this is not a requirement. Custom filters can be used as long as they have the properties above.

Kind: global namespace

filters.RangedFilter

Kind: static class of filters

new RangedFilter(low, high)

RangedFilter is a filter which accepts keys between low and high. It is used to implement X axis brushing for the coordinate grid charts.

Its filterType is 'RangedFilter'

Param Type
low Number
high Number

filters.TwoDimensionalFilter

Kind: static class of filters

new TwoDimensionalFilter(filter)

TwoDimensionalFilter is a filter which accepts a single two-dimensional value. It is used by the heat map chart to include particular cells as they are clicked. (Rows and columns are filtered by filtering all the cells in the row or column.)

Its filterType is 'TwoDimensionalFilter'

Param Type
filter Array.<Number>

filters.RangedTwoDimensionalFilter

Kind: static class of filters

new RangedTwoDimensionalFilter(filter)

The RangedTwoDimensionalFilter allows filtering all values which fit within a rectangular region. It is used by the scatter plot to implement rectangular brushing.

It takes two two-dimensional points in the form [[x1,y1],[x2,y2]], and normalizes them so that x1 <= x2 and y1 <= y2. It then returns a filter which accepts any points which are in the rectangular range including the lower values but excluding the higher values.

If an array of two values are given to the RangedTwoDimensionalFilter, it interprets the values as two x coordinates x1 and x2 and returns a filter which accepts any points for which x1 <= x < x2.

Its filterType is 'RangedTwoDimensionalFilter'

Param Type
filter Array.<Array.<Number>>

filters.HierarchyFilter

Kind: static class of filters

new HierarchyFilter(path)

HierarchyFilter is a filter which accepts a key path as an array. It matches any node at, or child of, the given path. It is used by the sunburst chart to include particular cells and all their children as they are clicked.

Param Type
path String

utils : object

Kind: global namespace

utils.printSingleValue(filter) ⇒ String

Print a single value filter.

Kind: static method of utils

Param Type
filter any

utils.add(l, r, [t]) ⇒ Date | Number

Arbitrary add one value to another.

If the value l is of type Date, adds r units to it. t becomes the unit. For example utils.add(dt, 3, 'week') will add 3 (r = 3) weeks (t= 'week') to dt.

If l is of type numeric, t is ignored. In this case if r is of type string, it is assumed to be percentage (whether or not it includes %). For example utils.add(30, 10) will give 40 and utils.add(30, '10') will give 33.

They also generate strange results if l is a string.

Kind: static method of utils

Param Type Default Description
l Date | Number the value to modify
r String | Number the amount by which to modify the value
[t] function | String d3.timeDay if l is a Date, then this should be a d3 time interval. For backward compatibility with dc.js 2.0, it can also be the name of an interval, i.e. 'millis', 'second', 'minute', 'hour', 'day', 'week', 'month', or 'year'

utils.subtract(l, r, [t]) ⇒ Date | Number

Arbitrary subtract one value from another.

If the value l is of type Date, subtracts r units from it. t becomes the unit. For example utils.subtract(dt, 3, 'week') will subtract 3 (r = 3) weeks (t= 'week') from dt.

If l is of type numeric, t is ignored. In this case if r is of type string, it is assumed to be percentage (whether or not it includes %). For example utils.subtract(30, 10) will give 20 and utils.subtract(30, '10') will give 27.

They also generate strange results if l is a string.

Kind: static method of utils

Param Type Default Description
l Date | Number the value to modify
r String | Number the amount by which to modify the value
[t] function | String d3.timeDay if l is a Date, then this should be a d3 time interval. For backward compatibility with dc.js 2.0, it can also be the name of an interval, i.e. 'millis', 'second', 'minute', 'hour', 'day', 'week', 'month', or 'year'

utils.isNumber(n) ⇒ Boolean

Is the value a number?

Kind: static method of utils

Param Type
n any

utils.isFloat(n) ⇒ Boolean

Is the value a float?

Kind: static method of utils

Param Type
n any

utils.isInteger(n) ⇒ Boolean

Is the value an integer?

Kind: static method of utils

Param Type
n any

utils.isNegligible(n) ⇒ Boolean

Is the value very close to zero?

Kind: static method of utils

Param Type
n any

utils.clamp(val, min, max) ⇒ any

Ensure the value is no greater or less than the min/max values. If it is return the boundary value.

Kind: static method of utils

Param Type
val any
min any
max any

utils.constant(x) ⇒ function

Given x, return a function that always returns x.

d3.functor was removed in d3 version 4. This function helps to implement the replacement, typeof x === "function" ? x : utils.constant(x)

Kind: static method of utils

Param Type
x any

utils.uniqueId() ⇒ Number

Using a simple static counter, provide a unique integer id.

Kind: static method of utils

utils.nameToId(name) ⇒ String

Convert a name to an ID.

Kind: static method of utils

Param Type
name String

utils.appendOrSelect(parent, selector, tag) ⇒ d3.selection

Append or select an item on a parent element.

Kind: static method of utils

Param Type
parent d3.selection
selector String
tag String

utils.safeNumber(n) ⇒ Number

Return the number if the value is a number; else 0.

Kind: static method of utils

Param Type
n Number | any

utils.arraysEqual(a1, a2) ⇒ Boolean

Return true if both arrays are equal, if both array are null these are considered equal

Kind: static method of utils

Param Type
a1 Array | null
a2 Array | null

printers : object

Kind: global namespace

printers.filters(filters) ⇒ String

Converts a list of filters into a readable string.

Kind: static method of printers

Param Type
filters Array.<filters>

printers.filter(filter) ⇒ String

Converts a filter into a readable string.

Kind: static method of printers

Param Type
filter filters | any | Array.<any>

units : object

Kind: global namespace

units.fp : object

Kind: static namespace of units

fp.precision(precision) ⇒ function

This function generates an argument for the Coordinate Grid Chart .xUnits function specifying that the x values are floating-point numbers with the given precision. The returned function determines how many values at the given precision will fit into the range supplied in its start and end parameters.

Kind: static method of fp
Returns: function - start-end unit function
See: coordinateGridMixin.xUnits

Param Type
precision Number

Example

// specify values (and ticks) every 0.1 units
chart.xUnits(units.fp.precision(0.1)
// there are 500 units between 0.5 and 1 if the precision is 0.001
var thousandths = units.fp.precision(0.001);
thousandths(0.5, 1.0) // returns 500

units.integers(start, end) ⇒ Number

The default value for .xUnits for the Coordinate Grid Chart and should be used when the x values are a sequence of integers. It is a function that counts the number of integers in the range supplied in its start and end parameters.

Kind: static method of units
See: coordinateGridMixin.xUnits

Param Type
start Number
end Number

Example

chart.xUnits(units.integers) // already the default

units.ordinal() ⇒ uncallable

This argument can be passed to the .xUnits function of a coordinate grid chart to specify ordinal units for the x axis. Usually this parameter is used in combination with passing d3.scaleOrdinal to .x.

As of dc.js 3.0, this is purely a placeholder or magic value which causes the chart to go into ordinal mode; the function is not called.

Kind: static method of units
See

Example

chart.xUnits(units.ordinal)
     .x(d3.scaleOrdinal())

elasticRadius([elasticRadius]) ⇒ Boolean | BubbleChart

Turn on or off the elastic bubble radius feature, or return the value of the flag. If this feature is turned on, then bubble radii will be automatically rescaled to fit the chart better.

Kind: global function

Param Type Default
[elasticRadius] Boolean false
You can’t perform that action at this time.