mozilla/metrics-graphics

View on GitHub
lib/docs/API.md

Summary

Maintainability
Test Coverage
<!-- Generated by documentation.js. Update this documentation by updating the source code. -->

### Table of Contents

-   [HistogramChart][1]
    -   [Parameters][2]
    -   [mountRects][3]
    -   [onPointHandler][4]
    -   [onLeaveHandler][5]
    -   [mountDelaunay][6]
-   [ScatterChart][7]
    -   [Parameters][8]
    -   [mountRugs][9]
        -   [Parameters][10]
    -   [mountPoints][11]
    -   [onPointHandler][12]
    -   [onLeaveHandler][13]
    -   [mountDelaunay][14]
-   [LineChart][15]
    -   [Parameters][16]
    -   [mountLines][17]
    -   [mountActivePoints][18]
        -   [Parameters][19]
    -   [mountAreas][20]
        -   [Parameters][21]
    -   [mountConfidenceBand][22]
        -   [Parameters][23]
    -   [mountMarkers][24]
    -   [onPointHandler][25]
    -   [onLeaveHandler][26]
    -   [mountDelaunay][27]
        -   [Parameters][28]
    -   [normalizeData][29]
-   [AbstractChart][30]
    -   [Parameters][31]
    -   [abstractRedraw][32]
    -   [redraw][33]
    -   [mountLegend][34]
        -   [Parameters][35]
    -   [mountXAxis][36]
        -   [Parameters][37]
    -   [mountYAxis][38]
        -   [Parameters][39]
    -   [mountTooltip][40]
        -   [Parameters][41]
    -   [mountContainer][42]
    -   [setDataTypeFlags][43]
    -   [mountSvg][44]
    -   [normalizeData][45]
    -   [computeDomains][46]
        -   [Parameters][47]
    -   [computeXAxisType][48]
    -   [computeYAxisType][49]

## HistogramChart

**Extends AbstractChart**

Creates a new histogram graph.

### Parameters

-   `args` **[Object][50]** argument object. See [AbstractChart][30] for general parameters.
    -   `args.binCount` **[Number][51]?** approximate number of bins that should be used for the histogram. Defaults to what d3.bin thinks is best.
    -   `args.args` **...any** 

### mountRects

Mount the histogram rectangles.

Returns **void** 

### onPointHandler

Handle move events from the delaunay triangulation.

Returns **[Function][52]** handler function.

### onLeaveHandler

Handle leaving the delaunay triangulation area.

Returns **[Function][52]** handler function.

### mountDelaunay

Mount new delaunay triangulation.

Returns **void** 

## ScatterChart

**Extends AbstractChart**

Creates a new scatter graph.

### Parameters

-   `args` **[Object][50]** argument object. See [AbstractChart][30] for general parameters.
    -   `args.sizeAccessor` **([String][53] \| [Function][52])** accesor specifying the size of a data point. Can be either a string (name of the size field) or a function (receiving a data point and returning its size). (optional, default `d=>3`)
    -   `args.xRug` **[Boolean][54]** whether or not to generate a rug for the x axis. (optional, default `false`)
    -   `args.yRug` **[Boolean][54]** whether or not to generate a rug for the y axis. (optional, default `false`)
    -   `args.args` **...any** 

### mountRugs

Mount new rugs.

#### Parameters

-   `xRug` **[Boolean][54]** whether or not to generate a rug for the x axis. (optional, default `false`)
-   `yRug` **[Boolean][54]** whether or not to generate a rug for the y axis. (optional, default `false`)

Returns **void** 

### mountPoints

Mount scatter points.

Returns **void** 

### onPointHandler

Handle incoming points from the delaunay triangulation.

Returns **[Function][52]** handler function

### onLeaveHandler

Handle leaving the delaunay area.

Returns **[Function][52]** handler function

### mountDelaunay

Mount new delaunay triangulation instance.

Returns **void** 

## LineChart

**Extends AbstractChart**

Creates a new line graph.

### Parameters

-   `$0` **[Object][50]** 
    -   `$0.area`  
    -   `$0.confidenceBand`  
    -   `$0.voronoi`  
    -   `$0.defined`   (optional, default `null`)
    -   `$0.activeAccessor`   (optional, default `null`)
    -   `$0.activePoint`  
    -   `$0.args` **...any** 
-   `args` **[Object][50]** argument object. See [AbstractChart][30] for general parameters.
    -   `args.area` **([Boolean][54] \| [Array][55])** specifies for which sub-array of data an area should be shown. Boolean if data is a simple array. (optional, default `[]`)
    -   `args.confidenceBand` **[Array][55]?** array with two elements specifying how to access the lower (first) and upper (second) value for the confidence band. The two elements work like accessors and are either a string or a function.
    -   `args.voronoi` **[Object][50]?** custom parameters passed to the voronoi generator.
    -   `args.defined` **[Function][52]?** optional function specifying whether or not to show a given data point.
    -   `args.activeAccessor` **([String][53] \| [Function][52])?** accessor specifying for a given data point whether or not to show it as active.
-   `activePoint` **[Object][50]?** custom parameters passed to the active point generator. See {@see Point} for a list of parameters.

### mountLines

Mount lines for each array of data points.

Returns **void** 

### mountActivePoints

If an active accessor is specified, mount active points.

#### Parameters

-   `params` **[Object][50]?** custom parameters for point generation. See {@see Point} for a list of options.

Returns **void** 

### mountAreas

Mount all specified areas.

#### Parameters

-   `area` **([Boolean][54] \| [Array][55])** specifies for which sub-array of data an area should be shown. Boolean if data is a simple array. (optional, default `[]`)

Returns **void** 

### mountConfidenceBand

Mount the confidence band specified by two accessors.

#### Parameters

-   `$0` **[Object][50]** 
    -   `$0.lowerAccessor`  
    -   `$0.upperAccessor`  
-   `lowerAccessor` **([Function][52] \| [String][53])** for the lower confidence bound. Either a string (specifying the property of the object representing the lower bound) or a function (returning the lower bound when given a data point).
-   `upperAccessor` **([Function][52] \| [String][53])** for the upper confidence bound. Either a string (specifying the property of the object representing the upper bound) or a function (returning the upper bound when given a data point).

Returns **void** 

### mountMarkers

Mount markers, if any.

Returns **void** 

### onPointHandler

Handle incoming points from the delaunay move handler.

Returns **[Function][52]** handler function.

### onLeaveHandler

Handles leaving the delaunay area.

Returns **[Function][52]** handler function.

### mountDelaunay

Mount a new delaunay triangulation instance.

#### Parameters

-   `customParameters` **[Object][50]** custom parameters for [Delaunay][56].

Returns **void** 

### normalizeData

Normalizes the passed data to a nested array of objects.

isSingleObject: return error
isArrayOfObjects: nest once
isNestedArrayOfArrays: do nothing, assume index-based accessor
isNestedArrayOfObjects: do nothing

Returns **void** 

## AbstractChart

This abstract chart class implements all functionality that is shared between all available chart types.
This is not meant to be directly instantiated.

### Parameters

-   `$0` **[Object][50]** 
    -   `$0.data`  
    -   `$0.target`  
    -   `$0.markers`  
    -   `$0.baselines`  
    -   `$0.xAccessor`   (optional, default `'date'`)
    -   `$0.yAccessor`   (optional, default `'value'`)
    -   `$0.margin`  
    -   `$0.buffer`  
    -   `$0.width`  
    -   `$0.height`  
    -   `$0.color`  
    -   `$0.colors`  
    -   `$0.xScale`  
    -   `$0.yScale`  
    -   `$0.xAxis`  
    -   `$0.yAxis`  
    -   `$0.showTooltip`  
    -   `$0.tooltipFunction`  
    -   `$0.legend`  
    -   `$0.legendTarget`  
    -   `$0.brush`  
    -   `$0.custom` **...any** 
-   `args` **[Object][50]** argument object.
    -   `args.data` **[Array][55]** data that needs to be visualized.
    -   `args.target` **([String][53] \| [Object][50])** DOM node to which the graph should be mounted. Either D3 selection or D3 selection specifier.
    -   `args.width` **[Number][51]** total width of the graph.
    -   `args.height` **[Number][51]** total height of the graph.
    -   `args.markers` **[Array][55]** markers that should be added to the chart. Each marker object should be accessible through the xAccessor and contain a label field. (optional, default `[]`)
    -   `args.baselines` **[Array][55]** baselines that should be added to the chart. Each baseline object should be accessible through the yAccessor and contain a label field. (optional, default `[]`)
    -   `args.xAccessor` **([String][53] \| [Function][52])** either name of the field that contains the x value or function that receives a data object and returns its x value. (optional, default `d=>d`)
    -   `args.yAccessor` **([String][53] \| [Function][52])** either name of the field that contains the y value or function that receives a data object and returns its y value. (optional, default `d=>d`)
    -   `args.margin` **[Object][50]** margin object specifying top, bottom, left and right margin. (optional, default `{top:10,left:60,right:20,bottom:40}`)
    -   `args.buffer` **[Number][51]** amount of buffer between the axes and the graph. (optional, default `10`)
    -   `args.color` **([String][53] \| [Array][55])?** custom color scheme for the graph.
    -   `args.colors` **([String][53] \| [Array][55])** alternative to color. (optional, default `schemeCategory10`)
    -   `args.xScale` **[Object][50]?** object that can be used to overwrite parameters of the auto-generated x [Scale][57].
    -   `args.yScale` **[Object][50]?** object that can be used to overwrite parameters of the auto-generated y [Scale][57].
    -   `args.xAxis` **[Object][50]?** object that can be used to overwrite parameters of the auto-generated x [Axis][58].
    -   `args.yAxis` **[Object][50]?** object that can be used to overwrite parameters of the auto-generated y [Axis][58].
    -   `args.showTooltip` **[Boolean][54]?** whether or not to show a tooltip.
    -   `args.tooltipFunction` **[Function][52]?** function that receives a data object and returns the string displayed as tooltip.
    -   `args.legend` **[Array][55]?** names of the sub-arrays of data, used as legend labels.
    -   `args.legendTarget` **([String][53] \| [Object][50])?** DOM node to which the legend should be mounted.
-   `brush` **([Boolean][54] \| [String][53])?** if truthy, add a bidirectional brush. If `x` or `y`, add one-directional brush.

### abstractRedraw

Draw the abstract chart.

Returns **void** 

### redraw

Draw the actual chart.
This is meant to be overridden by chart implementations.

Returns **void** 

### mountLegend

Mount a new legend if necessary

#### Parameters

-   `symbolType` **[String][53]** symbol type (circle, square, line)

Returns **void** 

### mountXAxis

Mount new x axis.

#### Parameters

-   `xAxis` **[Object][50]?** object that can be used to overwrite parameters of the auto-generated x [Axis][58].

Returns **void** 

### mountYAxis

Mount new y axis.

#### Parameters

-   `yAxis` **[Object][50]?** object that can be used to overwrite parameters of the auto-generated y [Axis][58].

Returns **void** 

### mountTooltip

Mount a new tooltip if necessary.

#### Parameters

-   `showTooltip` **[Boolean][54]?** whether or not to show a tooltip.
-   `tooltipFunction` **[Function][52]?** function that receives a data object and returns the string displayed as tooltip.

Returns **void** 

### mountContainer

Mount the main container.

Returns **void** 

### setDataTypeFlags

This method is called by the abstract chart constructor.
In order to simplify parsing of passed data, set flags specifying what types of data we're dealing with.

Returns **void** 

### mountSvg

This method is called by the abstract chart constructor.
Append the local svg node to the specified target, if necessary.
Return existing svg node if it's already present.

Returns **void** 

### normalizeData

If needed, charts can implement data normalizations, which are applied when instantiating a new chart.

Returns **void** 

### computeDomains

Usually, the domains of the chart's scales depend on the chart type and the passed data, so this should usually be overwritten by chart implementations.

#### Parameters

-   `params` **[Object][50]** object of custom parameters for the specific chart type

Returns **[Object][50]** specifying the domain for x and y axis as separate properties.

### computeXAxisType

Meant to be overwritten by chart implementations.
Set tick format of the x axis.

Returns **void** 

### computeYAxisType

Meant to be overwritten by chart implementations.
Set tick format of the y axis.

Returns **void** 

[1]: #histogramchart

[2]: #parameters

[3]: #mountrects

[4]: #onpointhandler

[5]: #onleavehandler

[6]: #mountdelaunay

[7]: #scatterchart

[8]: #parameters-1

[9]: #mountrugs

[10]: #parameters-2

[11]: #mountpoints

[12]: #onpointhandler-1

[13]: #onleavehandler-1

[14]: #mountdelaunay-1

[15]: #linechart

[16]: #parameters-3

[17]: #mountlines

[18]: #mountactivepoints

[19]: #parameters-4

[20]: #mountareas

[21]: #parameters-5

[22]: #mountconfidenceband

[23]: #parameters-6

[24]: #mountmarkers

[25]: #onpointhandler-2

[26]: #onleavehandler-2

[27]: #mountdelaunay-2

[28]: #parameters-7

[29]: #normalizedata

[30]: #abstractchart

[31]: #parameters-8

[32]: #abstractredraw

[33]: #redraw

[34]: #mountlegend

[35]: #parameters-9

[36]: #mountxaxis

[37]: #parameters-10

[38]: #mountyaxis

[39]: #parameters-11

[40]: #mounttooltip

[41]: #parameters-12

[42]: #mountcontainer

[43]: #setdatatypeflags

[44]: #mountsvg

[45]: #normalizedata-1

[46]: #computedomains

[47]: #parameters-13

[48]: #computexaxistype

[49]: #computeyaxistype

[50]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object

[51]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Number

[52]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Statements/function

[53]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String

[54]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean

[55]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array

[56]: Delaunay

[57]: Scale

[58]: Axis