Class Dygraph

Creates an interactive, zoomable chart.
Defined in: dygraph.js.

Class Summary
Constructor Attributes	Constructor Name and Description
	Dygraph(div, file, attrs)

Field Summary
Field Attributes	Field Name and Description
<static>	Dygraph.Plotters Standard plotters.
<static>	Dygraph.PointType Point structure.

Method Summary
Method Attributes	Method Name and Description
	adjustRoll(length) Adjusts the number of points in the rolling average.
	annotations() Return the list of annotations.
	clearSelection() Clears the current selection (i.e.
	destroy() Detach DOM elements in the dygraph and null out all data references.
	eventToDomCoords(event) Convert a mouse event to DOM coordinates relative to the graph origin.
	getArea() Get the current graph's area object.
	getColors() Return the list of colors.
	getHighlightSeries() Returns the name of the currently-highlighted series.
	getLabels() Get the list of label names for this graph.
	getOption(name, opt_seriesName) Returns the current value for an option, as set in the constructor or via updateOptions.
	getPropertiesForSeries(series_name) Returns a few attributes of a series, i.e.
	getRowForX(xVal) Find the row number corresponding to the given x-value.
	getSelection() Returns the number of the currently selected row.
	getValue(row, col) Returns the value in the given row and column.
	indexFromSetName(name) Get the index of a series (column) given its name.
	isSeriesLocked() Returns true if the currently-highlighted series was locked via setSelection(.
	isZoomed(axis) Returns the zoomed status of the chart for one or both axes.
	numAxes() Returns the number of y-axes on the chart.
	numColumns() Returns the number of columns (including the independent variable).
	numRows() Returns the number of rows (excluding any header/label row).
	ready(callback) Trigger a callback when the dygraph has drawn itself and is ready to be manipulated.
	resetZoom() Reset the zoom to the original view coordinates.
	resize(width, height) Resizes the dygraph.
	rollPeriod() Returns the current rolling period, as set by the user or an option.
	setAnnotations(ann, suppressDraw) Update the list of annotations and redraw the chart.
	setSelection(row, optional, optional, optional) Manually set the selected points and display information about them in the legend.
	setVisibility(num, value) Changes the visibility of one or more series.
	toDataCoords(x, y, axis) Convert from canvas/div coords to data coordinates.
	toDataXCoord(x) Convert from canvas/div x coordinate to data coordinate.
	toDataYCoord(y, axis) Convert from canvas/div y coord to value.
	toDomCoords(x, y, axis) Convert from data coordinates to canvas/div X/Y coordinates.
	toDomXCoord(x) Convert from data x coordinates to canvas/div X coordinate.
	toDomYCoord(y, axis) Convert from data x coordinates to canvas/div Y coordinate and optional axis.
	toPercentXCoord(x) Converts an x value to a percentage from the left to the right of the drawing area.
	toPercentYCoord(y, axis) Converts a y for an axis to a percentage from the top to the bottom of the drawing area.
	toString() Returns information about the Dygraph object, including its containing ID.
	updateOptions(input_attrs, block_redraw) Changes various properties of the graph.
	visibility() Returns a boolean array of visibility statuses.
	xAxisExtremes() Returns the lower- and upper-bound x-axis values of the data set.
	xAxisRange() Returns the currently-visible x-range.
	yAxisExtremes() Returns the lower- and upper-bound y-axis values for each axis.
	yAxisRange(idx) Returns the currently-visible y-range for an axis.
	yAxisRanges() Returns the currently-visible y-ranges for each axis.

Class Detail

Dygraph(div, file, attrs)

Parameters:
{div | String} div: A div or the id of a div into which to construct the chart. Must not have any padding.
{String | Function} file: A file containing CSV data or a function that returns this data. The most basic expected format for each line is "YYYY/MM/DD,val1,val2,...". For more information, see http://dygraphs.com/data.html.
{Object} attrs: Various other attributes, e.g. errorBars determines whether the input data contains error ranges. For a complete list of options, see http://dygraphs.com/options.html.

Field Detail

<static> Dygraph.Plotters

Standard plotters. These may be used by clients. Available plotters are: - Dygraph.Plotters.linePlotter: draws central lines (most common) - Dygraph.Plotters.errorPlotter: draws high/low bands - Dygraph.Plotters.fillPlotter: draws fills under lines (used with fillGraph) By default, the plotter is [fillPlotter, errorPlotter, linePlotter]. This causes all the lines to be drawn over all the fills/bands.

<static> Dygraph.PointType

Point structure. xval_* and yval_* are the original unscaled data values, while x_* and y_* are scaled to the range (0.0-1.0) for plotting. yval_stacked is the cumulative Y value used for stacking graphs, and bottom/top/minus/plus are used for high/low band graphs.

Method Detail

adjustRoll(length)

Adjusts the number of points in the rolling average. Updates the graph to reflect the new averaging period.

Parameters:
{number} length: Number of points over which to average the data.

annotations()

Return the list of annotations.

clearSelection()

Clears the current selection (i.e. points that were highlighted by moving the mouse over the chart).

destroy()

Detach DOM elements in the dygraph and null out all data references. Calling this when you're done with a dygraph can dramatically reduce memory usage. See, e.g., the tests/perf.html example.

eventToDomCoords(event)

Convert a mouse event to DOM coordinates relative to the graph origin. Returns a two-element array: [X, Y].

Parameters:
event

getArea()

Get the current graph's area object. Returns: {x, y, w, h}

{Array.} getColors()

Return the list of colors. This is either the list of colors passed in the attributes or the autogenerated list of rgb(r,g,b) strings. This does not return colors for invisible series.

Returns:: {Array.} The list of colors.

getHighlightSeries()

Returns the name of the currently-highlighted series. Only available when the highlightSeriesOpts option is in use.

getLabels()

Get the list of label names for this graph. The first column is the x-axis, so the data series names start at index 1. Returns null when labels have not yet been defined.

{*} getOption(name, opt_seriesName)

Returns the current value for an option, as set in the constructor or via updateOptions. You may pass in an (optional) series name to get per-series values for the option. All values returned by this method should be considered immutable. If you modify them, there is no guarantee that the changes will be honored or that dygraphs will remain in a consistent state. If you want to modify an option, use updateOptions() instead.

Parameters:
{string} name: The name of the option (e.g. 'strokeWidth')
{string=} opt_seriesName: Series name to get per-series values.

Returns:: {*} The value of the option.

getPropertiesForSeries(series_name)

Returns a few attributes of a series, i.e. its color, its visibility, which axis it's assigned to, and its column in the original data. Returns null if the series does not exist. Otherwise, returns an object with column, visibility, color and axis properties. The "axis" property will be set to 1 for y1 and 2 for y2. The "column" property can be fed back into getValue(row, column) to get values for this series.

Parameters:
series_name

{?number} getRowForX(xVal)

Find the row number corresponding to the given x-value. Returns null if there is no such x-value in the data. If there are multiple rows with the same x-value, this will return the first one.

Parameters:
{number} xVal: The x-value to look for (e.g. millis since epoch).

Returns:: {?number} The row number, which you can pass to getValue(), or null.

{number} getSelection()

Returns the number of the currently selected row. To get data for this row, you can use the getValue method.

Returns:: {number} row number, or -1 if nothing is selected

{number} getValue(row, col)

Returns the value in the given row and column. If the row and column exceed the bounds on the data, returns null. Also returns null if the value is missing.

Parameters:
{number} row: The row number of the data (0-based). Row 0 is the first row of data, not a header row.
{number} col: The column number of the data (0-based)

Returns:: {number} The value in the specified cell or null if the row/col were out of range.

indexFromSetName(name)

Get the index of a series (column) given its name. The first column is the x-axis, so the data series start with index 1.

Parameters:
name

isSeriesLocked()

Returns true if the currently-highlighted series was locked via setSelection(..., seriesName, true).

isZoomed(axis)

Returns the zoomed status of the chart for one or both axes. Axis is an optional parameter. Can be set to 'x' or 'y'. The zoomed status for an axis is set whenever a user zooms using the mouse or when the dateWindow or valueRange are updated. Double-clicking or calling resetZoom() resets the zoom status for the chart.

Parameters:
axis

{number} numAxes()

Returns the number of y-axes on the chart.

Returns:: {number} the number of axes.

{number} numColumns()

Returns the number of columns (including the independent variable).

Returns:: {number} The number of columns.

{number} numRows()

Returns the number of rows (excluding any header/label row).

Returns:: {number} The number of rows, less any header.

ready(callback)

Trigger a callback when the dygraph has drawn itself and is ready to be manipulated. This is primarily useful when dygraphs has to do an XHR for the data (i.e. a URL is passed as the data source) and the chart is drawn asynchronously. If the chart has already drawn, the callback will fire immediately. This is a good place to call setAnnotation().

Parameters:
{function(!Dygraph)} callback: The callback to trigger when the chart is ready.

resetZoom()

Reset the zoom to the original view coordinates. This is the same as double-clicking on the graph.

resize(width, height)

Resizes the dygraph. If no parameters are specified, resizes to fill the containing div (which has presumably changed size since the dygraph was instantiated). If the width/height are specified, the div will be resized. This is far more efficient than destroying and re-instantiating a Dygraph, since it doesn't have to reparse the underlying data.

Parameters:
{number} width: Width (in pixels)
{number} height: Height (in pixels)

{number} rollPeriod()

Returns the current rolling period, as set by the user or an option.

Returns:: {number} The number of points in the rolling window

setAnnotations(ann, suppressDraw)

Update the list of annotations and redraw the chart. See dygraphs.com/annotations.html for more info on how to use annotations.

Parameters:
ann: {Array} An array of annotation objects.
suppressDraw: {Boolean} Set to "true" to block chart redraw (optional).

setSelection(row, optional, optional, optional)

Manually set the selected points and display information about them in the legend. The selection can be cleared using clearSelection() and queried using getSelection(). To set a selected series but not a selected point, call setSelection with row=false and the selected series name.

Parameters:
{number} row: Row number that should be highlighted (i.e. appear with hover dots on the chart).
{seriesName} optional: series name to highlight that series with the the highlightSeriesOpts setting.
{locked} optional: If true, keep seriesName selected when mousing over the graph, disabling closest-series highlighting. Call clearSelection() to unlock it.
{trigger_highlight_callback} optional: If true, trigger any user-defined highlightCallback if highlightCallback has been set.

setVisibility(num, value)

Changes the visibility of one or more series.

Parameters:
{number|number[]|object} num: the series index or an array of series indices or a boolean array of visibility states by index or an object mapping series numbers, as keys, to visibility state (boolean values)
{boolean} value: the visibility state expressed as a boolean

toDataCoords(x, y, axis)

Convert from canvas/div coords to data coordinates. If specified, do this conversion for the coordinate system of a particular axis. Uses the first axis by default. Returns a two-element array: [X, Y]. Note: use toDataXCoord instead of toDataCoords(x, null) and use toDataYCoord instead of toDataCoords(null, y, axis).

Parameters:
x
y
axis

toDataXCoord(x)

Convert from canvas/div x coordinate to data coordinate. If x is null, this returns null.

Parameters:
x

toDataYCoord(y, axis)

Convert from canvas/div y coord to value. If y is null, this returns null. if axis is null, this uses the first axis.

Parameters:
y
axis

toDomCoords(x, y, axis)

Convert from data coordinates to canvas/div X/Y coordinates. If specified, do this conversion for the coordinate system of a particular axis. Uses the first axis by default. Returns a two-element array: [X, Y] Note: use toDomXCoord instead of toDomCoords(x, null) and use toDomYCoord instead of toDomCoords(null, y, axis).

Parameters:
x
y
axis

toDomXCoord(x)

Convert from data x coordinates to canvas/div X coordinate. If specified, do this conversion for the coordinate system of a particular axis. Returns a single value or null if x is null.

Parameters:
x

toDomYCoord(y, axis)

Convert from data x coordinates to canvas/div Y coordinate and optional axis. Uses the first axis by default. returns a single value or null if y is null.

Parameters:
y
axis

{number} toPercentXCoord(x)

Converts an x value to a percentage from the left to the right of the drawing area. If the coordinate represents a value visible on the canvas, then the value will be between 0 and 1, where 0 is the left of the canvas. However, this method will return values outside the range, as values can fall outside the canvas. If x is null, this returns null.

Parameters:
{number} x: The data x-coordinate.

Returns:: {number} A fraction in [0, 1] where 0 = the left edge.

{number} toPercentYCoord(y, axis)

Converts a y for an axis to a percentage from the top to the bottom of the drawing area. If the coordinate represents a value visible on the canvas, then the value will be between 0 and 1, where 0 is the top of the canvas. However, this method will return values outside the range, as values can fall outside the canvas. If y is null, this returns null. if axis is null, this uses the first axis.

Parameters:
{number} y: The data y-coordinate.
{number} axis Optional: The axis number on which the data coordinate lives.

Returns:: {number} A fraction in [0, 1] where 0 = the top edge.

toString()

Returns information about the Dygraph object, including its containing ID.

updateOptions(input_attrs, block_redraw)

Changes various properties of the graph. These can include:

file: changes the source data for the graph
errorBars: changes whether the data contains stddev

There's a huge variety of options that can be passed to this method. For a full list, see http://dygraphs.com/options.html.

Parameters:
{Object} input_attrs: The new properties and values
{boolean} block_redraw: Usually the chart is redrawn after every call to updateOptions(). If you know better, you can pass true to explicitly block the redraw. This can be useful for chaining updateOptions() calls, avoiding the occasional infinite loop and preventing redraws when it's not necessary (e.g. when updating a callback).

visibility()

Returns a boolean array of visibility statuses.

xAxisExtremes()

Returns the lower- and upper-bound x-axis values of the data set.

xAxisRange()

Returns the currently-visible x-range. This can be affected by zooming, panning or a call to updateOptions. Returns a two-element array: [left, right]. If the Dygraph has dates on the x-axis, these will be millis since epoch.

yAxisExtremes()

Returns the lower- and upper-bound y-axis values for each axis. These are the ranges you'll get if you double-click to zoom out or call resetZoom(). The return value is an array of [low, high] tuples, one for each y-axis.

yAxisRange(idx)

Returns the currently-visible y-range for an axis. This can be affected by zooming, panning or a call to updateOptions. Axis indices are zero-based. If called with no arguments, returns the range of the first axis. Returns a two-element array: [bottom, top].

Parameters:
idx

yAxisRanges()

Returns the currently-visible y-ranges for each axis. This can be affected by zooming, panning, calls to updateOptions, etc. Returns an array of [bottom, top] pairs, one for each y-axis.

Classes

Class Dygraph