jwildfire edited this page Feb 9, 2018 · 15 revisions

chart

object

The chart object represents a chart with conventional x- and y-axes that is rendered with SVG. Customizable configuration options determine the appearance and behavior of the chart, and these options can be manipulated indirectly through a set of controls. The chart has several lifecycle methods used to instantiate the object, render necessary elements, and adjust the rendered elements as needed. The chart can therefore be updated dynamically by changing some config options (or operating directly on the chart object's properties) or by feeding it new data and then calling its draw method to trigger an animated re-render.

chart.div

string

CSS selector identifying the DOM element housing the rendered chart

chart.config

object

a reference to the config object that specifies chart settings

chart.controls

controls

a controls object associated with this chart

chart.initial_data

array

initial dataset (unfiltered, untransformed, unchanged by callbacks) stored by the chart; this dataset is provided directly as an argument to chart.init.

chart.raw_data

array

raw dataset stored by the chart; this dataset is provided directly as an argument to chart.init, but can be modified by the user using callbacks before being processed in chart.draw().

chart.filtered_data

array

chart.raw_data with any data removed as specified by control objects with control.type == "subsetter"

chart.current_data

array

fully processed data for the last mark specified in config.marks. Relying on chart.current_data in charts with multiple marks specified is likely to cause unexpected behavior and is not recommended. When in doubt, avoid chart.current_data in callbacks.

chart.filters

array

a list of objects describing the state of any data filters currently associated with the chart; this property is manipulated by controls with type='subsetter'

chart.marks

array

a list of objects describing each set of marks rendered by the chart; essentially a copy of the marks property of the configuration object, but with the mark-specfic properties listed below added.

chart.marks[].data

array

mark-specfic transformed data

chart.marks[].supergroup

d3.selection

d3 selection for the supergroup (e.g. g.point-supergroup) containing all of the point groups.

chart.marks[].groups

d3.selection

d3 selection for the groups (e.g. g.group) containing the marks.

chart.marks[].cirlces`

d3.selection

when mark.type == "points" only d3 selection of the circle marks

chart.marks[].paths

d3.selection

when mark.type == "lines" only d3 selection of the path marks

chart.marks[].texts

d3.selection

when mark.type == "text" only d3 selection of the text marks

chart.wrap

d3.selection

a d3 selection of a <div> appended within the DOM element specified by chart.div

chart.id

number

a unique identifier for this chart instance; assigned automatically

chart.x_dom

array

domain for the x-axis; computed automatically based on the provided dataset, config.x, and config.marks.

chart.y_dom

array

domain for the y-axis; computed automatically based on the provided dataset, config.y, and config.marks.

chart.on(event, callback)

a method for attaching a callback function to be called at a given point in the chart's lifecycle; the this context of the callback is automatically assigned to the current chart object, so that its properties can be accessed like so:

myChart.on('draw', function(){
  this.svg.selectAll('.bar');
  \\maniuplate bars
});
Param Type Description
event string point in the chart lifecycle at which to fire the associated callback; can be "init", "layout", "preprocess", "datatransform", "draw", "resize" or "destroy"
callback function function to run at the specified point in the chart lifecycle

chart.checkRequired()

checks raw dataset against the configuration object for the chart and throws errors if the configuration references values that are not present; called once upon initialization of chart

chart.init(data)

kicks off the lifecycle of the chart

Param Type Description
[data] array raw data to be used in the initial rendering of the chart

chart.setDefaults()

fills in default values for config object

chart.layout()

sets up the SVG that serves as the chart "canvas" and its static child elements; happens once immediately after chart.init

chart.setColorScale()

sets up the color scale for the chart, which is an ordinal d3.scale with a domain based on unique values determined by config.color_by and a range determined by config.colors

chart.makeLegend([scale], [label])

draws legend for the chart

Param Type Default Description
[scale] d3.scale scale returned by chart.setColorScale color scale to use in the legend
[label] string label for the legend

chart.draw([raw_data])

parses config object, triggers data transformation and chart rendering methods; if raw_data is provided, it will be used when rendering the chart instead of the chart's current raw data

Param Type Default Description
[raw_data] array chart.raw_data raw data to be consumed by later chart functions

chart.transformData(raw, mark)

transforms raw data into an appropriately nested format for each mark

Param Type Description
raw array raw dataset to be transformed
mark mark object describing the set of marks

chart.consolidateData(raw)

pools data for each set of marks and determines comprehensive domains for x- and y-axes

Param Type Description
raw array raw dataset to be transformed and then consolidated

chart.xScaleAxis(max_range, [domain], [type])

sets up x-scale and x-axis functions

Param Type Default Description
max_range number maximum SVG x-coordinate that can be used; typically set to the width of the chart's plotting area
[domain] array chart.x_dom Domain passed to the scale function
[type] string config.x.type Type of scale to define

chart.yScaleAxis(max_range, [domain], [type])

sets up y-scale and y-axis functions

Param Type Default Description
max_range number maximum SVG x-coordinate that can be used; typically set to the height of the chart's plotting area
[domain] array chart.y_dom domain passed to the scale function
[type] string config.y.type type of scale to define

chart.drawBars(marks)

draws bars (<rect> elements) as defined by marks with type: "bar"

Param Type Description
marks array the members of chart.marks with type: "bar"

chart.drawLines(marks)

draws lines (<path> elements) as defined by marks with type: "line"

Param Type Description
marks array the members of chart.marks with type: "line"

chart.drawPoints(marks)

draws points (<circle> elements) as defined by marks with type: "circle"

Param Type Description
marks array the members of chart.marks with type: "circle"

chart.resize()

arranges all chart components; determines final chart dimensions and triggers rendering of axes and marks

chart.updateDataMarks()

triages rendering functions for the chart's currently-defined marks

chart.drawGridlines()

draws gridlines at x and or y tick mark locations, as defined by the gridlines property in the configuration object

chart.setMargins()

determines margins for the chart automatically based on axis ticks, labels, etc.

chart.textSize(width)

determines text size for the chart automatically based on certain breakpoints

Param Type Description
width number width of the chart container

chart.destroy()

Removes all components of the chart from the DOM and deletes event listeners and, optionally, controls. Triggers the destroy callback method. Added in version 1.7.0

Param Type Default Description
destroyControls boolean true specifies whether to remove any controls bound to the chart
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.