dino-graph/DOCS.md

a simple dynamic graphing library

# Documentation

## Getting started
### Installation
 - Pick one:
	1. Install with NPM: `npm install --save dino-graph`
	2. Save [`dino-graph.js`](https://raw.githubusercontent.com/DougTy/dino-graph/master/dist/dino-graph.js) locally <sub><sup>(& optional [sourcemap](https://raw.githubusercontent.com/DougTy/dino-graph/master/dist/dino-graph.js.map))</sup></sub>

### Usage
 - Pick one:
	1. ES6: `import DinoGraph from 'dino-graph'`
	2. CommonJS: `const DinoGraph = require( 'dino-graph' )`
	3. Script tag: `<script src="dino-graph.js"></script>`

## Methods
### constructor( canvasElement, data, options )
 - Creates a new graph
 - Requires reference to canvas element
 - Data and options are sent to initial `graph.setData` and `graph.setOptions` calls
```
var g = new DinoGraph
	(
		document.getElementById( 'canvas' ),
		data,
		{ /* options */ }
	)
```

### graph.setData( data )
 - Takes an array of points, or array of series
```
// both valid:
graph.setData( [ [0,1], [1,2], [2,3] ] )
graph.setData([
	[ [0,10], [1,20], [2,30] ],
	[ [0,20], [1,30], [2,40] ],
	[ [0,30], [1,40], [2,50] ] ])
```

### graph.setOptions( options )
 - Takes an object of options, or array of options for multiple series (lines)
```
// both valid:
graph.setOptions( { title: 'Y' } )
graph.setOptions([
	{ title: 'A' },
	{ title: 'B' },
	{ title: 'C' } ])
```

### graph.setLineData( lineNum, data )
 - Set a single line's data by line index (starting from 0)
```
graph.setLineData( 0, [ /* data */ ] )
```

### graph.setLineOptions( lineNum, options )
 - Set a single line's options by line index (starting from 0)
```
graph.setLineOptions( 0, { /* options */ } )
```

### graph.updateGraph()
 - Updates the graph's coordinates
 - Usually not necessary to call manually
 - Automatically called every time data or options are changed
 - Can use in conjunction with `graph.manualUpdates` to batch updates
```
graph.manualUpdates = true
graph.setLineData( 0, dataA )
graph.setLineData( 1, dataB )
graph.setLineData( 2, dataC )
graph.updateGraph()
// coordinates are only recalculated once
// instead of 3 times, one per setLineData call
```

### graph.options.dataFormat( data, lineOpts )
 - Used to format data for display
 - Can be overridden per-graph to format data however you like
 - Line options are passed in for optional use
 - Return x and y values in an array
```
function exampleDataFormat( data, lineOpts )
{
	var x = new Date( data[0] )
	var y = parseFloat( data[1] ).toFixed(1)
	if ( lineOpts.title )
		y = lineOpts.title + ': ' + y
	return [ x, y ]
}
```


## Global options
variable | description | default
--- | ---  | ---
maxY | Maximum Y value of the graph | null
stacked | Stack series on top of eachother | false
split | Split the graph in two (second line is negative) | false
allowZoom | Allow zooming into a selected region | true
keepZoomScale | Keep unzoomed X-axis scale while zooming | false
regionColour | Selected region colour while zooming | 'rgba( 0, 0, 0, 0.25 )'
showZoomBar | Draw zoom & pan scrollbar | true
zoomBarColour | HEX or RGBA | 'rgba( 0, 0, 0, 0.25 )'
zoomBarThickness | Thickness (height) of zoom bar | 10
showZoomNotice | Display 'zoomed, right click to restore' message | true
zoomNoticeFontSize | Font size in px | 10
zoomNoticeFont | Font name or family | 'Arial'
zoomNoticeColour | Hex or RGBA | 'rgba( 0, 0, 0, 0.5 )'
zoomNoticePadding | Padding from bottom and right of graph | 5
allowPanning | Allow panning by dragging the zoom bar | true
panStep | Pixels mouse must move before panning occurs | 5
xRange | Maximum range of X values to display (default zoom level) | false
interpShade | Colour to shade interpolated regions, ie 'rgba( 255, 0, 0, 0.3 )' | false
interpShadeThreshold | Threshold of X value difference to shade | 10
interpShadeLine | If set, only check points in this line for interp shading threshold | false
paddingTop | Top padding of data area | 5
paddingLeft | Left padding of data area | 20
paddingBottom | Bottom padding of data area | 10
paddingRight | Right padding of data area | 45
dataPadding | Offset Y values by this amount for visual effect | 0
centerPadding | Visual Y value offset for split graphs | 0
showLabels | Draw axis value labels | true
showLabelsX | Draw X axis labels | true
showLabelsY | Draw Y axis labels | true
originLabel | Show combined origin label (overriddden by bottom two) | true
xOriginLabel | Show origin label on X axis | false
yOriginLabel | Show origin label on Y axis | false
originText | Static text for origin | null
numLabelsX | Number of X axis labels | 5
numLabelsY | Number of Y axis labels | 5
labelPadding | Padding between axis border and text | 4
labelFontSize | Font size in px | 10
labelFontWeight | Font weight | 'normal'
labelFont | Font name or family | 'Arial'
labelFontSizeX | Font size in px | 10
labelFontWeightX | Font weight | 'normal'
labelFontX | Font name or family | 'Arial'
labelFontSizeY | Font size in px | 10
labelFontWeightY | Font weight | 'normal'
labelFontY | Font name or family | 'Arial'
labelColour | Hex or RGBA | 'black'
labelColours | Parse label colours (ex: "\#ffffff text") | false
showGrid | Draw grid lines | true
showGridX | Draw X axis grid | true
showGridY | Draw Y axis grid | true
gridColour | Hex or RGBA | 'rgba( 0, 0, 0, 0.1 )'
gridWidth | Grid line width | 1
backgroundColour | Hex or RGBA, transparent if null | null
axisColour | X and Y axis lines (Hex or RGBA) | 'black'
axisWidth | Axis line width | 1
showValues | Draw graph values where the mouse is hovered | true
showLatest | Draw latest values if mouse not hovered | true
sliderColour | Slider on mouse hover (Hex or RGBA) | 'rgba( 0, 0, 0, 0.5 )'
sliderWidth | Slider line width | 1
valuePos | Position to display values, 'right' or 'bottom' | 'right'
valueOffset | Text offset from the top of the canvas | 20
valueSpacing | Spacing between values | 2
valuePadding | Padding from the data area to the text | 4
valueFontSize | Font size in px | 11
valueFontWeight | Font weight | 0
valueFont | Font name or family | 'Arial'
valueColour | Hex or RGBA | 'black'
valueColours | Use labelColours for value display | false
xTitle | Title of X values | 'X'
stackedTitle | Title for total Y values in a stacked graph (hidden if false) | 'Y'
lineColours | Base line colours -- shaded when looped | [ '#2B55CE', '#D80500', '#038818', '#7A0091', '#E37F00' ]
dataFormat | Function to format data values for display | function( data[ x, y ], lineOpts ) return [ x, y ]
frameRate | Maximum FPS to render the graph, -1 for browser-managed limit | -1
debug | Enable debug display | false
debugColour | Change debug text colour | #000000


## Line options
variable | description | default
--- | ---  | ---
title | Title of this line's Y values to display | null
lines | Draw lines | true
points | Draw points | true
fill | Fill area below this line | false
quadratic | Render graph as quadratic | false
lineColour | Hex or RGBA, uses global lineColours if not set | null
pointColour | Hex or RGBA, uses global lineColours if not set | null
fillColour | Hex or RGBA, uses global lineColours if not set | null
lineWidth | Line thickness in px | 1
pointRadius | Point radius in px | 2
lineStyle | 'miter', 'bevel', or 'round' | miter
hideValues | Hide value display for this line | false