Permalink
Switch branches/tags
Find file Copy path
76071f7 May 12, 2018
1 contributor

Users who have contributed to this file

5469 lines (4159 sloc) 253 KB

dc : object

The entire dc.js library is scoped under the dc name space. It does not introduce anything else into the global name space.

Most dc functions are designed to allow function chaining, meaning they return the current chart instance whenever it is appropriate. The getter forms of functions do not participate in function chaining because they return values that are not the chart, although some, such as .svg and .xAxis, return values that are themselves chainable d3 objects.

Kind: global namespace
Version: 2.1.10
Example

// Example chaining
chart.width(300)
     .height(300)
     .filter('sunday');

dc.pieChart

Kind: static class of dc
Mixes: capMixin, colorMixin, baseMixin

new pieChart(parent, [chartGroup])

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:

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 = dc.pieChart('#chart-container1');
// create a pie chart under #chart-container2 element using chart group A
var chart2 = dc.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

dc.barChart

Kind: static class of dc
Mixes: stackMixin, coordinateGridMixin

new barChart(parent, [chartGroup])

Concrete bar chart/histogram implementation.

Examples:

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 = dc.barChart('#chart-container1');
// create a bar chart under #chart-container2 element using chart group A
var chart2 = dc.barChart('#chart-container2', 'chartGroupA');
// create a sub-chart under a composite parent chart
var chart3 = dc.barChart(compositeChart);

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

dc.lineChart

Kind: static class of dc
Mixes: stackMixin, coordinateGridMixin

new lineChart(parent, [chartGroup])

Concrete line/area chart implementation.

Examples:

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 = dc.lineChart('#chart-container1');
// create a line chart under #chart-container2 element using chart group A
var chart2 = dc.lineChart('#chart-container2', 'chartGroupA');
// create a sub-chart under a composite parent chart
var chart3 = dc.lineChart(compositeChart);

lineChart.interpolate([interpolate]) ⇒ String | lineChart

Gets or sets the interpolator to use for lines drawn, by string name, allowing e.g. step functions, splines, and cubic interpolation. This is passed to d3.svg.line.interpolate and d3.svg.area.interpolate, where you can find a complete list of valid arguments.

Kind: instance method of lineChart
See

Param Type Default
[interpolate] String 'linear'

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

Gets or sets the tension to use for lines drawn, in the range 0 to 1. This parameter further customizes the interpolation behavior. It is passed to d3.svg.line.tension and d3.svg.area.tension.

Kind: instance method of lineChart
See

Param Type Default
[tension] Number 0.7

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 d3.svg.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: d3.svg.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.8, radius: 2}

Example

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

dc.dataCount

Kind: static class of dc
Mixes: baseMixin

new dataCount(parent, [chartGroup])

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:

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

dc.dataCount('.dc-data-count')
    .dimension(ndx)
    .group(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'))

dc.dataTable

Kind: static class of dc
Mixes: baseMixin

new dataTable(parent, [chartGroup])

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

Note: Unlike other charts, the data table (and data grid chart) use the group attribute as a keying function for nesting the data together in groups. Do not pass in a crossfilter group as this will not work.

Another interesting feature of the data table is that you can pass a crossfilter group to the dimension, 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.

Examples:

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.group(groupFunction) ⇒ function | dataTable

Get or set the group function for the data table. The group function takes a data row and returns the key to specify to d3.nest to split rows into groups.

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

Kind: instance method of dataTable

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

Example

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

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()> - |dc.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.showGroups([showGroups]) ⇒ Boolean | dataTable

Get or set if group rows will be shown. The dataTable group function must be specified even if groups are not shown.

Kind: instance method of dataTable

Param Type Default
[showGroups] Boolean true

Example

chart
    .group([value], [name])
    .showGroups(true|false);

dc.dataGrid

Kind: static class of dc
Mixes: baseMixin

new dataGrid(parent, [chartGroup])

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

Note: Unlike other charts, the data grid chart (and data table) use the group attribute as a keying function for nesting the data together in groups. Do not pass in a crossfilter group as this will not work.

Examples:

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.group(groupFunction) ⇒ function | dataTable

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

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

Kind: instance method of dataGrid

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

Example

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

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.htmlGroup([htmlGroup]) ⇒ function | dataGrid

Get or set the function that formats a group label.

Kind: instance method of dataGrid

Param Type
[htmlGroup] function

Example

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

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

dc.bubbleChart

Kind: static class of dc
Mixes: bubbleMixin, coordinateGridMixin

new bubbleChart(parent, [chartGroup])

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:

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 = dc.bubbleChart('#chart-container1');
// create a bubble chart under #chart-container2 element using chart group A
var bubbleChart2 = dc.bubbleChart('#chart-container2', 'chartGroupA');

bubbleChart.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: instance method of bubbleChart

Param Type Default
[elasticRadius] Boolean false

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

dc.compositeChart

Kind: static class of dc
Mixes: coordinateGridMixin

new compositeChart(parent, [chartGroup])

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.

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 = dc.compositeChart('#chart-container1');
// create a composite chart under #chart-container2 element using chart group A
var compositeChart2 = dc.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
    dc.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);
        }),
    dc.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.

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.svg.axis | 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 axis object therefore it supports any valid d3 axis manipulation.

Caution: The y axis is usually generated internally by dc; resetting it may cause unexpected results.

Kind: instance method of compositeChart
See: d3.svg.axis

Param Type
[rightYAxis] d3.svg.axis

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

dc.seriesChart

Kind: static class of dc
Mixes: compositeChart

new seriesChart(parent, [chartGroup])

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:

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 = dc.seriesChart("#chart-container1");
// create a series chart under #chart-container2 element using chart group A
var seriesChart2 = dc.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 dc.lineChart

Example

// put interpolation on the line charts used for the series
chart.chart(function(c) { return dc.lineChart(c).interpolate('basis'); })
// do a scatter series chart
chart.chart(dc.scatterPlot)

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

dc.geoChoroplethChart

Kind: static class of dc
Mixes: colorMixin, baseMixin

new geoChoroplethChart(parent, [chartGroup])

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:

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 = dc.geoChoroplethChart('#us-chart');
// create a choropleth chart under '#us-chart2' element using chart group A
var chart2 = dc.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]) ⇒ geoChoroplethChart

Set custom geo projection function. See the available d3 geo projection functions.

Kind: instance method of geoChoroplethChart
See

Param Type Default
[projection] d3.projection d3.geo.albersUsa()

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.geo.path

Returns the d3.geo.path 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.geo.path

geoChoroplethChart.removeGeoJson(name) ⇒ geoChoroplethChart

Remove a GeoJson layer from this chart by name

Kind: instance method of geoChoroplethChart

Param Type
name String

dc.bubbleOverlay

Kind: static class of dc
Mixes: bubbleMixin, baseMixin

new bubbleOverlay(parent, [chartGroup])

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:

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 = dc.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 = dc.compositeChart('#chart-container2', 'chartGroupA').svg(d3.select('#chart-container2 svg'));

bubbleOverlay.svg([imageElement]) ⇒ 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 method 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

dc.rowChart

Kind: static class of dc
Mixes: capMixin, marginMixin, colorMixin, baseMixin

new rowChart(parent, [chartGroup])

Concrete row chart implementation.

Examples:

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 = dc.rowChart('#chart-container1');
// create a row chart under #chart-container2 element using chart group A
var chart2 = dc.rowChart('#chart-container2', 'chartGroupA');

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

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

Kind: instance method of rowChart
See: quantitive 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() ⇒ d3.svg.axis

Get the x axis for the row chart instance. Note: not settable for row charts. See the d3 axis object documention for more information.

Kind: instance method of rowChart
See: d3.svg.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]);

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 rescle 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

dc.legend

Kind: static class of dc

new legend()

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

Examples:

Example

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

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.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(dc.pluck('name'))

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

// create legend displaying group counts
chart.legend(dc.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

dc.scatterPlot

Kind: static class of dc
Mixes: coordinateGridMixin

new scatterPlot(parent, [chartGroup])

A scatter plot chart

Examples:

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 = dc.scatterPlot('#chart-container1');
// create a scatter plot under #chart-container2 element using chart group A
var chart2 = dc.scatterPlot('#chart-container2', 'chartGroupA');
// create a sub-chart under a composite parent chart
var chart3 = dc.scatterPlot(compositeChart);

scatterPlot.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 property of scatterPlot

Param Type Default
[emptyColor] String

scatterPlot.emptyOpacity ⇒ Number | scatterPlot

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

Kind: instance property of scatterPlot

Param Type Default
[emptyOpacity] Number 0

scatterPlot.nonemptyOpacity ⇒ Number | scatterPlot

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

Kind: instance property of scatterPlot

Param Type Default
[nonemptyOpacity] Number 1

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]) ⇒ String | function | scatterPlot

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

Kind: instance method of scatterPlot
See: d3.svg.symbol.type

Param Type Default
[type] String | function 'circle'

Example

// Circle type
chart.symbol('circle');
// Square type
chart.symbol('square');

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

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

Kind: instance method of scatterPlot
See

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

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

Set or get radius for symbols.

Kind: instance method of scatterPlot
See: d3.svg.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.svg.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.svg.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.svg.symbol.size

Param Type Default
[emptySize] Number 0

dc.numberDisplay

Kind: static class of dc
Mixes: baseMixin

new numberDisplay(parent, [chartGroup])

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.

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 = dc.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')

dc.heatMap

Kind: static class of dc
Mixes: colorMixin, marginMixin, baseMixin

new heatMap(parent, [chartGroup])

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

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 = dc.heatMap('#chart-container1');
// create a heat map under #chart-container2 element using chart group A
var heatMap2 = dc.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.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.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;
    dc.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

dc.boxPlot

Kind: static class of dc
Mixes: coordinateGridMixin

new boxPlot(parent, [chartGroup])

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

Examples:

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 = dc.boxPlot('#chart-container1');
// create a box plot under #chart-container2 element using chart group A
var boxPlot2 = dc.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.scale.ordinal.rangeBands

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

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

dc.selectMenu

Kind: static class of dc
Mixes: baseMixin

new selectMenu(parent, [chartGroup])

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.

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 = dc.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

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 property 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

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

Kind: instance property of selectMenu

Param Type Default
[promptText] String 'Select all'

Example

chart.promptText('All states');

selectMenu.filterDisplayed

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 property of selectMenu

Param Type
[filterDisplayed] function

Example

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

selectMenu.multiple

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

Kind: instance property of selectMenu

Param Type Default
[multiple] boolean false

Example

chart.multiple(true);

selectMenu.promptValue

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 property of selectMenu

Param Type Default
[promptValue] *

selectMenu.numberItems

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 property of selectMenu

Param Type Default
[numberVisible] number

Example

chart.numberVisible(10);

dc.baseMixin ⇒ baseMixin

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

Kind: static mixin of dc

Param Type
_chart Object

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(dc.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(dc.pluck('key'));
chart.dimension(dimension);
chart.group(dimension.group(crossfilter.reduceSum()));

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

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

Kind: instance method of baseMixin
See: crossfilter.quicksort.by

Param Type
[orderFunction] function

Example

// Default ordering accessor
_chart.ordering(dc.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() ⇒ 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
Example

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

baseMixin.selectAll() ⇒ 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
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 dc.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 ' + dc.utils.printSingleValue(filters[0][0]) +
    ' extent ' + dc.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() ⇒ 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 filtered. The callback has the standard node.js continuation signature with error first and result second.

Kind: instance method of baseMixin

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 dc.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 dc.filters.RangedFilter, which is different
// from the syntax for filtering a crossfilter dimension directly, dimension.filter([15,20])
chart.filter(dc.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)

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.

Kind: instance method of baseMixin

Param Type
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.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());
});

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 dc.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(dc.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){...})

dc.marginMixin ⇒ marginMixin

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

Kind: static mixin of dc

Param Type
_chart 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

dc.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: static mixin of dc

Param Type
_chart Object

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.scale.category20c()

Example

// alternate categorical scale
chart.colors(d3.scale.category20b());
// ordinal scale
chart.colors(d3.scale.ordinal().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.scale.ordinal 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.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.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.colorCalculator([colorCalculator]) ⇒ function | colorMixin

Deprecated. Get/set the color calculator. This actually replaces the getColor method!

This is not recommended, since using a colorAccessor and color scale (.colors) is more powerful and idiomatic d3.

Kind: instance method of colorMixin

Param Type
[colorCalculator] *

dc.coordinateGridMixin ⇒ 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: static mixin of dc
Mixes: colorMixin, marginMixin, baseMixin

Param Type
_chart Object

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 quantitive 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.scale.linear().domain([-2500, 2500]))
// set x to a time scale to generate histogram
chart.x(d3.time.scale().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 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 x axis, or the number of points on the axis. d3 time range functions d3.time.days, d3.time.months, and d3.time.years are all valid xUnits function. dc.js also provides a few units function, see the Units Namespace for a list of built-in units functions.

Kind: instance method of coordinateGridMixin
Todo

  • Add docs for utilities
Param Type Default
[xUnits] function dc.units.integers

Example

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

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

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

coordinateGridMixin.xAxis([xAxis]) ⇒ d3.svg.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 axis object; therefore it supports any valid d3 axis 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, {@link https://github.com/dc-js/dc.js/wiki/FAQ#why-does-everything-break-after-a-call-to-xaxis-or-yaxis so attempting to call chart functions after calling .xAxis() will fail}.

Kind: instance method of coordinateGridMixin
See: d3.svg.axis

Param Type Default
[xAxis] d3.svg.axis d3.svg.axis().orient('bottom')

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.

Padding unit is a string that will be used when the padding is calculated. Available parameters are the available d3 time intervals; see d3.time.interval.

Kind: instance method of coordinateGridMixin

Param Type Default
[unit] String 'days'

coordinateGridMixin.xUnitCount() ⇒ Number

Returns the number of units displayed on the x axis using the unit measure configured by xUnits.

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.svg.axis | 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. The y axis in dc.js is simply an instance of a d3 axis object; 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, {@link https://github.com/dc-js/dc.js/wiki/FAQ#why-does-everything-break-after-a-call-to-xaxis-or-yaxis so attempting to call chart functions after calling .yAxis() will fail}.

Kind: instance method of coordinateGridMixin
See: d3.svg.axis

Param Type Default
[yAxis] d3.svg.axis d3.svg.axis().orient('left')

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.time.month.round);

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])

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.

Kind: instance method of coordinateGridMixin

Param Type
[range] Array.<Number>

Example

chart.on('renderlet', function(chart) {
    // smooth the rendering through event throttling
    dc.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

dc.stackMixin ⇒ stackMixin

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

Kind: static mixin of dc

Param Type
_chart Object

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.layout.stack

Param Type Default
[stack] function d3.layout.stack

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

dc.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: static mixin of dc

Param Type
_chart 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, please file an issue - it's still possible but we'll need to work up an example.

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

dc.bubbleMixin ⇒ bubbleMixin

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

Kind: static mixin of dc
Mixes: colorMixin

Param Type
_chart Object

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

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

Kind: instance method of bubbleMixin
See: d3.scale

Param Type Default
[bubbleRadiusScale] d3.scale d3.scale.linear().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

dc.disableTransitions : Boolean

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

Kind: static property of dc
Default: false

dc.dateFormat : function

The default date format for dc.js

Kind: static property of dc
Default: d3.time.format('%m/%d/%Y')

dc.chartRegistry : object

The dc.chartRegistry object maintains sets of all instantiated dc.js charts under named groups and the default group.

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: static namespace of dc

chartRegistry.has(chart) ⇒ Boolean

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

Kind: static method of chartRegistry

Param Type Description
chart Object dc.js chart instance

chartRegistry.register(chart, [group])

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

Kind: static method of chartRegistry

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

chartRegistry.deregister(chart, [group])

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

Kind: static method of chartRegistry

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

chartRegistry.clear(group)

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

Kind: static 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: static method of chartRegistry

Param Type Description
[group] String Group name

dc.units : object

Kind: static namespace of dc

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(dc.units.fp.precision(0.1)
// there are 500 units between 0.5 and 1 if the precision is 0.001
var thousandths = dc.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(dc.units.integers) // already the default

units.ordinal(start, end, domain) ⇒ Array.<String>

This argument can be passed to the .xUnits function of the to specify ordinal units for the x axis. Usually this parameter is used in combination with passing d3.scale.ordinal to .x. It just returns the domain passed to it, which for ordinal charts is an array of all values.

Kind: static method of units
See

Param Type
start *
end *
domain Array.<String>

Example

chart.xUnits(dc.units.ordinal)
     .x(d3.scale.ordinal())

dc.printers : object

Kind: static namespace of dc

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>

dc.utils : object

Kind: static namespace of dc

utils.printSingleValue(filter) ⇒ String

Print a single value filter.

Kind: static method of utils

Param Type
filter any

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

Arbitrary add one value to another.

Kind: static method of utils
Todo

  • These assume than any string r is a percentage (whether or not it includes %). They also generate strange results if l is a string.
Param Type Description
l String | Date | Number the value to modify
r Number the amount by which to modify the value
[t] String if l is a Date, the interval in the d3.time namespace

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

Arbitrary subtract one value from another.

Kind: static method of utils
Todo

  • These assume than any string r is a percentage (whether or not it includes %). They also generate strange results if l is a string.
Param Type Description
l String | Date | Number the value to modify
r Number the amount by which to modify the value
[t] String if l is a Date, the interval in the d3.time namespace

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.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

dc.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: static namespace of dc

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>>

dc.registerChart(chart, [group])

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

Kind: static method of dc

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

dc.deregisterChart(chart, [group])

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

Kind: static method of dc

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

dc.hasChart(chart) ⇒ Boolean

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

Kind: static method of dc

Param Type Description
chart Object dc.js chart instance

dc.deregisterAllCharts(group)

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

Kind: static method of dc

Param Type Description
group String Group name

dc.filterAll([group])

Clear all filters on all charts within the given chart group. If the chart group is not given then only charts that belong to the default chart group will be reset.

Kind: static method of dc

Param Type
[group] String

dc.refocusAll([group])

Reset zoom level / focus on all charts that belong to the given chart group. If the chart group is not given then only charts that belong to the default chart group will be reset.

Kind: static method of dc

Param Type
[group] String

dc.renderAll([group])

Re-render all charts belong to the given chart group. If the chart group is not given then only charts that belong to the default chart group will be re-rendered.

Kind: static method of dc

Param Type
[group] String

dc.redrawAll([group])

Redraw all charts belong to the given chart group. If the chart group is not given then only charts that belong to the default chart group will be re-drawn. Redraw is different from re-render since when redrawing dc tries to update the graphic incrementally, using transitions, instead of starting from scratch.

Kind: static method of dc

Param Type
[group] String

dc.transition(selection, [duration], [delay], [name]) ⇒ d3.transition | d3.selection

Start a transition on a selection if transitions are globally enabled (disableTransitions is false) and the duration is greater than zero; otherwise return the selection. Since most operations are the same on a d3 selection and a d3 transition, this allows a common code path for both cases.

Kind: static method of dc

Param Type Default Description
selection d3.selection the selection to be transitioned
[duration] Number | function 250 the duration of the transition in milliseconds, a function returning the duration, or 0 for no transition
[delay] Number | function the delay of the transition in milliseconds, or a function returning the delay, or 0 for no delay
[name] String the name of the transition (if concurrent transitions on the same elements are needed)

dc.pluck(n, [f]) ⇒ function

Returns a function that given a string property name, can be used to pluck the property off an object. A function can be passed as the second argument to also alter the data being returned.

This can be a useful shorthand method to create accessor functions.

Kind: static method of dc

Param Type
n String
[f] function

Example

var xPluck = dc.pluck('x');
var objA = {x: 1};
xPluck(objA) // 1

Example

var xPosition = dc.pluck('x', function (x, i) {
    // `this` is the original datum,
    // `x` is the x property of the datum,
    // `i` is the position in the array
    return this.radius + x;
});
dc.selectAll('.circle').data(...).x(xPosition);