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
• Custom RGraph events that are available
• 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
• Animation 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
• Other label properties
• Margin properties
• Tickmark properties
• Title properties
• Interactive features properties
• Line properties
• Trend line 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

Other label 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: "1 px solid #ddd";
}

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

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

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

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

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

Line properties

Trend line 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.

Custom RGraph events that are available

Custom RGraph events are events that RGraph fires when certain actions occur. There is a more comprehensive list of these events here . Here's some example code that show you how to add these events to your chart.

• click
• mousemove
• mouseover
• mouseout

There's more documentation about events available here: Summary of events documentation

<script>
    scatter = new RGraph.Scatter({
        id: 'cvs',
        data: [[1,1],[2,2],[3,3],[4,4],[5,5]],
        options: {
            xaxisScaleMax: 10
        }
    }).draw().on('click', function (e, shape)
    {
        // Add your click event listener code here

    }).on('mousemove', function (e, shape)
    {
        // Add your mousemove event listener code here

    }).on('mouseover', function (e, shape)
    {
        // Add your mouseover event listener code here

    }).on('mouseout', function (obj)
    {
        // Add your mouseout event listener code here
    });
</script>

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>

Animation 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>