Scatter chart API reference

Summary: Documentation about the Scatter chart including information about all of the options that are available to you. The Scatter chart can show various points on X/Y scales as well as a time scale. The Scatter chart is quite versatile and can be used to show a variety of different types of data.

• Example
• Format of the data array (colors/tooltips)
• Properties
• Methods
• Box/Whisker (candlestick) plots
• Specific points for labels on the X axis
• Custom tickmarks
• Note about colors and the key
• Note about the crosshairs event
• Adding a trend line to your chart
• Note about the data_arr array
• Date/time based charts
• Bubble charts
• Events
• Effects

Example

<script>
    tooltip = '%{key}';

    new RGraph.Scatter({
        id: 'cvs',
        data: [
            [
                [10,78,null,tooltip],
                [20,69,null,tooltip],
                [34,42,null,tooltip],
                [35,66,null,tooltip],
                [46,45,null,tooltip],
                [64,38,null,tooltip],
                [78,29,null,tooltip],
                [78,34,null,tooltip],
                [112,26,null,tooltip],
                [119,15,null,tooltip]
            ],
            [
                [186,54,'red',tooltip],
                [195,56,'red',tooltip],
                [210,58,'red',tooltip],
                [214,53,'blue',tooltip],
                [233,51,'red',tooltip],
                [245,48,'red',tooltip],
                [270,61,'red',tooltip],
                [281,43,'red',tooltip],
                [299,52,'red',tooltip],
                [312,77,'red',tooltip]
            ]
        ],
        options: {
            tooltipsFormattedKeyLabels: ['Richard','John','Luis','Pob','Pete','Olga','Kiffen','Hevin','Joy','Hoolio'],
            tooltipsFormattedKeyColors: ['black','red'],
            tooltipsCss: {
                fontSize: '16pt',
                boxShadow: '',
                textAlign: 'left'
            },
            trendline: true,
            trendlineColor: ['gray','red'],
            trendlineMargin: 5,
            backgroundGridBorder: false,
            backgroundGridVlines: false,
            yaxis: false,
            backgroundGridColor: '#eee',
            marginLeft: 30,
            xaxisLabels: ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'],
            xaxisScaleMax: 365,
            tickmarksSize: 10
        }
    }).draw();
</script>

Format of the data array (colors/tooltips)

Each point on the Scatter chart is made by supplying an array of up to 4 elements:

• The X value (required)
• The Y value (required). As well as a single number this can also be an array of numbers that describe a boxplot/whisker.
• The color (optional)
• The tooltip for this mark (optional)

If you wish to specify a tooltip, but not a color (ie use the default color instead), you can pass null instead of a color.

<script>
    // A regular dataset
    data = [
        [67,78],                            // A basic datapoint
        [67,40,'red'],                      // A datapoint with a color specified
        [150,26,'green','A tooltip!'],      // A datapoint with a color and tooltip specified
        [164,35, null, 'Just the tooltip'], // A datapoint with no color and a tooltip
        [203,53]
    ];

    new RGraph.Scatter({
        id: 'cvs',
        data: data,
        options: {
            xaxisScaleMax: 365
        }
    }).draw();
</script>

Properties

You can use these properties to control how the chart appears. You can set them by including them in the options section of the configuration as above.

• Background properties
• X axis properties
• Y axis properties
• Color properties
• Labels and text properties
• Margin properties
• Tickmark properties
• Title properties
• Interactive features properties
• Line properties
• Trend line properties
• Bubble properties
• Key properties
• Miscellaneous properties

Background properties

myScatter.set('backgroundHbars', [[75, 10, 'yellow'], [85, 15, 'red']]);

myScatter.set('backgroundVbars', [[0, 181, 'rgba(0,255,0,0.5)']]);

obj.set('backgroundVbars', [['2013/06/01','2013/07/01','pink']]);

myScatter.set('backgroundHbars', [[75, 10, 'yellow'], [85, 15, 'red']]);

myScatter.set('backgroundVbars', [[0, 181, 'rgba(0,255,0,0.5)']]);

obj.set('backgroundVbars', [['2013/06/01','2013/07/01','pink']]);

X axis properties

function myFormatter(opt)
{
    var obj = opt.object,
        num = opt.number;

    return num + 'F'; // An example of formatting
}

function myFormatter(opt)
{
    var obj = opt.object,
        num = opt.number;

    return num + 'F'; // An example of formatting
}

Y axis properties

function myFormatter(opt)
{
    var num = Number(opt.number) * 5;

    return String(num)
}
obj.set('yaxisScaleFormatter', myFormatter);

function myFormatter(opt)
{
    var num = Number(opt.number) * 5;

    return String(num)
}
obj.set('yaxisScaleFormatter', myFormatter);

Color properties

Labels and text properties

labelsAboveFormatterX: function (obj, value)
{
    var d = new Date(value);
        date = d.getDate();
        month = d.getMonth();
        year  = d.getFullYear();
    
    return '{1}/{2}/{3}'.format(date, month, year);
},

labelsAboveFormatterY: function (obj, value)
{
    return value;
},

<div style="margin-left: 50px; display: inline-block">
    <canvas id="cvs" width="650" height="250"></canvas>
</div>

labelsAboveFormatterX: function (obj, value)
{
    var d = new Date(value);
        date = d.getDate();
        month = d.getMonth();
        year  = d.getFullYear();
    
    return '{1}/{2}/{3}'.format(date, month, year);
},

labelsAboveFormatterY: function (obj, value)
{
    return value;
},

<div style="margin-left: 50px; display: inline-block">
    <canvas id="cvs" width="650" height="250"></canvas>
</div>

Margin properties

Tickmark properties

Title properties

Interactive features properties

tooltipsFormattedKeyColorsCss : {
    border: "1px solid #ddd";
}

tooltipsFormattedListItems: [
    ['Bill','Jerry','Berty'], // First tooltip
    ['Gill','Carrie','Lucy'], // Second tooltip
    ['Pob','Nobby','Hilda']   // Third tooltip
]

.RGraph_tooltip ul#rgraph_formatted_tooltips_list li {
    text-align: left;
    color: yellow;
}

tooltips: {
    borderLeft: 'gray 2px solid',
    borderBottom: 'gray 2px solid'
}

tooltipsCss: {
    fontFamily: 'Verdana',
    fontSize: '20pt'
}

tooltipsFormattedKeyColorsCss : {
    border: "1px solid #ddd";
}

tooltipsFormattedListItems: [
    ['Bill','Jerry','Berty'], // First tooltip
    ['Gill','Carrie','Lucy'], // Second tooltip
    ['Pob','Nobby','Hilda']   // Third tooltip
]

.RGraph_tooltip ul#rgraph_formatted_tooltips_list li {
    text-align: left;
    color: yellow;
}

tooltips: {
    borderLeft: 'gray 2px solid',
    borderBottom: 'gray 2px solid'
}

tooltipsCss: {
    fontFamily: 'Verdana',
    fontSize: '20pt'
}

Line properties

Trend line properties

Bubble properties

Key properties

Miscellaneous properties

Methods

obj.get(name)
An accessor that you can use to retrieve the values of properties.

obj.set(name, value)
An accessor that you can use to set the values of properties.

This function makes it easier to get hold of which point on the Scatter chart has been clicked or hovered over. It returns an object that has the following properties:

<script>
    scatter.canvas.onmousemove = function (e)
    {
        var canvas  = e.target;
        var obj     = canvas.__object__;
        var shape   = obj.getShape(e);

        if (shape) {
            obj.path(
                'b a % % 5 0 6.29 f red',
                shape.x, shape.y
            );
        }
    }
</script>

In boxplots the shape object is slightly different:

<script>
    scatter.canvas.onclick = function (e)
    {
        RGraph.redraw();
    
        var canvas = e.target,
            obj    = canvas.__object__,
            shape  = obj.getShape(e);

        if (shape) {
            obj.path(
                'lc square lj square b r % % % % f red',
                shape.x, shape.y, shape.width, shape.height
            );
        }
    }
</script>

This method can be used to get the X value at a particular point or at the mouse coordinates, based on the X maximum value that is being used. Not simply the coordinates of the mouse. The argument can either be an event object (for use in event listener functions) OR a two element array consisting of the X and Y coordinates (ie when you're not necessarily in an event listener). It returns null if the mouse or coordinates are in the margin areas.

This method can be used to get the Y value at a particular point or at the mouse coordinates, based on the scale that is in use. Not simply the coordinates of the mouse. The argument can either be an event object (for use in event listener functions) OR a two element array consisting of the X and Y coordinates (ie when you're not necessarily in an event listener). It returns null if the mouse or coordinates are in the margin areas.

This method can be used to get an appropriate Y coordinate for a value when you're doing custom drawing on the chart. It returns the coordinate for the max/min value if the given number is out of range.

This method can be used to get an appropriate X coordinate for a value when you're doing custom drawing on the chart. It returns null if the given number is out of range. If you're using a date/time chart with the min and max set to date/time strings you can also pass this function a date/time string eg:

obj.getXCoord('2013-06-12T15:14:16');

This method can be used to set an event listener on an object. It operates in a similar way to the jQuery on() function. The first argument is the event that you wish to attach to and the second is the handler function. For example:

obj.on('draw', function (obj)
{
    // Put your event code here
});

The function is useful if you use method chaining when creating your charts:

<script>
    new RGraph.Scatter({
        id: 'cvs',
        data: [ [12,35],[23,53],[35,35],[45,58],[56,55],[86,86] ],
        xaxisScaleMax: 100
    }).on('draw', function (obj)
    {
        // Put your draw event code here

    }).on('click', function (e, shape)
    {
        // Put your click event code here
    }).draw();
</script>

The exec function is documented here.

The responsive() function helps your charts respond to different browser window sizes and screen resolutions. For example for smaller screens you might want to have angled labels or show shorter versions of them completely.

The responsive() function is documented on its own page here.

Box/Whisker (candlestick) plots

Instead of a single Y value, you have the ability to specify an array of 5, 6, 7 or 8 values, which will be used to make a box plot (also known as a candlestick plot). These values are (in order):

• Lower whisker
• Bottom of the box
• Middle value (which isn't necessarily in the center of the box - this depends on your data)
• Top of the box
• Upper whisker
• Upper color (optional)
• Lower color (optional)
• Width (optional)

<script>
    new RGraph.Scatter({
        id: 'scatter8',
        data: [
            [10,[1,1,16,24,24, 'red', 'green']],
            [105,[5,10,15,25,25, 'red', 'green']],
            [125,[10,15,25,35,45, 'red', 'green']],
            [325,[10,15,25,35,45, 'red', 'green', 30]]
        ],
        options: {
            title: 'An example of a boxplot',
            xaxisLabels: ['Q1', 'Q2', 'Q3', 'Q4'],
            xaxisScaleMax: 365,
            yaxisScaleMax: 50,
            boxplotWidth: 12 // the default width
        }
    }).draw();
</script>

Capped ends

For better compatibility with stock charts, you can now specify that the horizontal lines at the ends of the box plot are not shown with the boxplotCapped option.

Specific points for labels on the X axis

Instead of a simple string which is used as the label, each entry of the labels array can be a two element array consisting of the label and the X value that the label should be placed at. For example:

scatter.set({
    xaxisLabels:[
        ['Quarter 1', 0],
        ['Quarter 2', 90],
        ['Quarter 3', 181],
        ['Quarter 4', 273]
    ]
});

Custom tickmarks

If none of the available tickmark styles are suitable, you can specify a function that draws the tickmark, enabling you to draw the tickmark yourself. For example:

<script>
    line.set('tickmarksStyle', myTick);

    /**
    * The function that is called once per tickmark, to draw it
    * 
    * @param object obj           The chart object
    * @param object data          The chart data
    * @param number x             The X coordinate
    * @param number y             The Y coordinate
    * @param number xVal          The X value
    * @param number yVal          The Y value
    * @param number xMax          The maximum X scale value
    * @param number yMax          The maximum Y scale value
    * @param string color        The color of the tickmark
    * @param string dataset_index The index of the data (which starts at zero
    * @param string data_index    The index of the data in the dataset (which starts at zero)
    */
    function myTick (obj, data, x, y, xVal, yVal, xMax, yMax, color, dataset_index, data_index)
    {
        // Draw your custom tick here
    }
</script>

As of August 2014 you can also specify an image to use as a tickmark. Various styles of URL are supported:

obj.set({tickmarks: 'image:foo.png'});     // Starts with image: prefix
obj.set({tickmarks: '/images/foo.png'});   // Starts with a /
obj.set({tickmarks: '../images/foo.png'}); // Starts with ../
obj.set({tickmarks: 'data: ...'});         // Starts with data: (for inline images)
obj.set({tickmarks: 'images/foo.png'});    // Starts with images/

Note about colors and the key

If you're using a key you may need to set lineColors to allow it to use the correct colors. For example:

obj.set('lineColors', ['red','green','blue']);

Note about the crosshairs event

With the Scatter chart you can use the crosshairs custom event to pull out the crosshair coordinates like this (the coordinates are only available if you have them displayed):

function myFunc (obj)
{
    var xCoord = obj.canvas.__crosshairs_x__;
    var yCoord = obj.canvas.__crosshairs_y__;
}
RGraph.addCustomEventListener(obj, 'crosshairs', function ()
{
    // Handle the event here
});

Adding a trend line to your chart

Since version 5.22 RGraph has supported trend lines on the Scatter chart. This is as easy as setting the trendline option to true and RGraph will calculate the best-fit line for your data. The Scatter chart at the top of the page is using the trendline option and there's also an example here.

There are a few ways to configure the lines which you can see in the trend line section of the API documentation.

Note about the data_arr array

Date/time based charts

Instead of using a number as the X coordinate you can instead use a date/time value instead. Likewise you can use the same style date/time values as the xaxisScaleMin and xaxisScaleMax values. The underlying date/time parsing uses the Date.parse() function (via the RGraph.parseDate() function) so you can use values such as: 2012-01-01 00:00:00 There's an example of a date/time chart in the download archive (scatter-date-time-values.html)

Update (version 5.25) - Moment.js added to RGraph
The date/time parsing in RGraph is versatile and recognises a lot of formats. The Moment.js library however is a dedicated library for parsing and manipulating dates and times. From version 5.25 the Moment.js library is bundled with RGraph. You can include it in your page by including the file RGraph.common.moment.js in your page. Once you've done that you can use the Moment.js API to manipulate dates as you require. Here's a very simplistic example of using Moment.js to set the minimum and maximum values of a Scatter chart:

new RGraph.Scatter({
    id: 'cvs',
    data: data,
    options: {
        tickmarksSize: 10,
        xaxisTickmarksCount: 7,
        xaxisScaleMin: moment('2020-01-01'),
        xaxisScaleMax: moment('2020-01-01').add(1, 'year'),
        backgroundGridVlines: false,
        marginRight: 100
    }
}).draw();

The HTML tag to include the Moment.js library in your page is this:

    <script src="RGraph.moment.js"></script>

Bubble charts

The RGraph Scatter chart can show Bubble charts natively - as shown by the chart here. From version 5.26 the way you make Bubble charts has changed and been integrated into the Scatter chart.

There's an example of the code that's necessary to show this type of chart shown below. The various properties are:

<script>
    scatter = new RGraph.Scatter({
        id: 'cvs2',
        data: [
            [30,15,  'red',   'Red bubble tooltip'],
            [60,5,   'blue',  'Blue bubble tooltip'],
            [90,8,   'pink',  'Pink bubble tooltip'],
            [120,19, 'green', 'Green bubble tooltip'],
            [150,14, 'gray',  'Gray bubble tooltip'],
            [50,12,  'red',   'Red bubble tooltip'],
            [180,24, 'gray',  'Gray bubble tooltip'],
            [250,21, 'black', 'Black bubble tooltip']
        ],
        options: {
            xaxisScaleMax: 365,
            xaxisLabels: ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'],
            textSize:14,
            backgroundGridVlines: false,
            backgroundGridBorder: false,
            xaxisTickmarks:false,
            yaxisTickmarks:false,
            xaxisLinewidth: 2,
            yaxisLinewidth: 2,
            tooltipsHotspot: 10,
            title: 'A bubble chart',
            titleBold: true,
            titleSize: 16,
            titleY: '-5',
            
            bubbleMin: 0,                           // The minimum for the bubble values
            bubbleMax: 100,                         // The maximum for the bubble values
            bubbleWidth: 50,                        // The maximum width of the bubbles
            bubbleData: [50,60,70,80,90,84,86,87]   // The values of the bubbles (ie how big the bubbles are)
        }
    }).draw().on('mouseout', function (e)
    {
        RGraph.hideTooltip();
        RGraph.redraw();
    });
</script>

Events

RGraph supports custom events that allow you to easily add interactivity to your charts if required. The following events are available:

• annotatebegin This event fires at the start of annotating - like the standard mousedown event.
• annotate This event fires (repeatedly) during annotating - like the standard mousemove event.
• annotateend This event fires at the end of annotating - like the standard mouseup event.
• annotateclear This event fires at the end of the RGraph.clearAnnotations() function.
• beforeclear This event fires at the start of the RGraph.clear() function.
• clear This event fires at the end of the RGraph.clear() function.
• click This is similar to the standard canvas click event but this only fires when you click on a bar - not the whole canvas.
• beforecontextmenu This event fires when you have the contextmenu enabled and it is about to appear.
• contextmenu This event fires when you have the contextmenu enabled and it has been displayed.
• beforedraw This event fires at the start of the draw() method before anything has been done.
• firstdraw This event fires at the end of the draw() function - but only the first time that the draw() function is called.
• draw This event fires at the end of the draw() function.
• beforeinteractivekey When you're using the interactive key this event fires just before the key and chart are highlighted.
• afterinteractivekey When you're using the interactive key this event fires just after the key and chart are highlighted.
• keyclick This event fires when you click on the key - you don't have to be using the interactive key however.
• mousemove This event is similar to the standard mousemove event but only fires when you move the mouse over a bar on the chart.
• mouseover This event is similar to the standard mouseover event but only fires when you move the mouse over a bar on the chart.
• mouseout This event is similar to the standard mouseout event but only fires when you move the mouse away from a bar on the chart that you've previously hovered over.
• beforetooltip This event fires at the start of the tooltip showing process.
• tooltip This event fires after a tooltip has been shown.

new RGraph.Scatter({
    id: 'cvs',
    data: [[5,3],[6,5],[4,8]],
    options: {
    }
}).on('draw', function (obj)
{
    console.log('The draw event has fired');
    
}).draw();

Effects

• The Trace effect (effects-scatter-trace2.html in the download archive)

<script>
    // Optional callback function that's called when the effect is complete
    function myCallback (obj)
    {
        // ...
    }

    new RGraph.Scatter({
        id: 'cvs',
        data: [[5,5],[10,10],[15,15],[20,20]],
        options: {
            xaxisScaleMax: 90
        }
    }).trace({frames: 60}, myCallback)
</script>