Scatter chart

• 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
• The Lasso feature
• Marimekko 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 (from version 6.11 it can also be an object which has up to four properties - details below):

• 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 single 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
    ];
    
    //
    // Multiple datasets
    //
    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
        ],
        [
            [7,41],
            [9,45,'red'],
            [8,23,'green','A tooltip!'],
            [15,32, null, 'Just the tooltip']
        ]
    ];
    
    

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

Object based point definitions

From version 6.11 the canvas Scatter chart can handle the array for each point being an object instead. You may find that this is easier to create and understand. There's an example of this below that shows the datasets from the above code converted to use objects instead.

<script>
    //
    // A single dataset
    //
    data = [
        {x: 67,  y: 78 },                                       // A basic datapoint
        {x: 67,  y: 40, color: 'red'},                          // A datapoint with a color specified
        {x: 150, y: 26, color: 'green', tooltip: 'A tooltip!'}, // A datapoint with a color and tooltip specified
        {x: 164, y: 35, tooltip: 'Just the tooltip'}            // A datapoint with no color and a tooltip
    ];
    
    //
    // Multiple datasets
    //
    data = [
        [
            {x: 67,  y: 78},                                        // A basic datapoint
            {x: 67,  y: 40, color: 'red'},                          // A datapoint with a color specified
            {x: 150, y: 26, color: 'green', tooltip: 'A tooltip!'}, // A datapoint with a color and tooltip specified
            {x: 164, y: 35, tooltip: 'Just the tooltip'}            // A datapoint with no color and a tooltip
        ],
        [
            {x: 7,  y: 41},
            {x: 9,  y: 45, color: 'red'},
            {x: 8,  y: 23, color: 'green', tooltip: 'A tooltip!'},
            {x: 15, y: 32, tooltip: 'Just the tooltip'}
        ]
    ];
    
    

    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 shown 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
• Lasso properties
• Key properties
• Marimekko 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;
}

tooltipsPointerCss: {
    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;
}

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

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

Line properties

Trend line properties

Bubble properties

Lasso properties

// ...
lassoCallback: function (state)
{
    // You can access the state.points array to get the points which are highlighted
}
// ...

// ...
lassoPersistSave: function (state)
{
    // You can access the state.points array to get the points which are highlighted
}
// ...

// ...
lassoPersistLoad: function ()
{
    // Load the persistence data here and return it

    // return data;
}
// ...

// ...
lassoCallback: function (state)
{
    // You can access the state.points array to get the points which are highlighted
}
// ...

// ...
lassoPersistSave: function (state)
{
    // You can access the state.points array to get the points which are highlighted
}
// ...

// ...
lassoPersistLoad: function ()
{
    // Load the persistence data here and return it

    // return data;
}
// ...

Key properties

Marimekko properties

Miscellaneous properties

obj.set('horizontalLines', [
    {
        value: 'average',
        dashed: true,
        labelPosition:'left bottom'
    },
    {
        value: 10.48,
        label:'Value (%{value})',
        labelValueDecimals: 2,
        labelValueThousand: ',',
        labelValuePoint:'.',
        labelValueUnitsPre:'',
        labelValueUnitsPost:''
        //labelValueFormatter: function (opt)
        //{
        //    return opt.number;
        //}
    }
]);

obj.set('horizontalLines', [
    {
        value: 'average',
        dashed: true,
        labelPosition:'left bottom'
    },
    {
        value: 10.48,
        label:'Value (%{value})',
        labelValueDecimals: 2,
        labelValueThousand: ',',
        labelValuePoint:'.',
        labelValueUnitsPre:'',
        labelValueUnitsPost:''
        //labelValueFormatter: function (opt)
        //{
        //    return opt.number;
        //}
    }
]);

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 similarly 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] ],
        options: {
            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.

Update: There is now the responsive configuration option available to you and this is now the preferred method of configuration.

The responsive function and configuration option are documented on their own page here.

Box/Whisker (candlestick) plots

Instead of a single Y value, you can 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 that's 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>
    //
    // 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 xValue        The X value
    // @param number yValue        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 number dataset       The index of the data (which starts at zero
    // @param number index         The index of the data in the dataset (which starts at zero)
    //
    // You can set the function in the regular chart configuration:
    //
    tickmarksStyle: function (obj, data, x, y, xValue, yValue, xMax, yMax, color, dataset, index)
    {
        // Draw your custom tick here
    },
    
    //
    // Or you can set it seperately using the obj.set() function:
    //
    line.set('tickmarksStyle', function (obj, data, x, y, xValue, yValue, xMax, yMax, color, dataset, 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 example linked at the top of the page is using the trendline option and there's also an example shown below:

<script>
    new RGraph.Scatter({
        id: 'cvs',
        data: [[1,56],[2,45],[3,48],[4,65],[5,66],[6,70],[7,71],[8,69],[9,75],[8,76]],
        options: {
            yaxisScaleMax:100,
            yaxisScaleMin:40,
            xaxisScaleMax: 10,
            xaxisLabels: ['A','B','C','D','E','F','G'],
            
            trendline: true,
            trendlineColor: 'red',
            trendlineDashed: false
        }
    }).draw();
</script>

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

DateTime based charts

Instead of using a number as the X coordinate, you can use a DateTime 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. 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>
    // Create and configure the Scatter chart
    scatter = new RGraph.Scatter({
        id: 'cvs',
        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,
            bubbleMax: 100,
            bubbleWidth: 50,
            bubbleData: [60,60,70,80,90,84,86,87]
        }
    }).draw().on('mouseout', function (e)
    {
        RGraph.hideTooltip();
        RGraph.redraw();
    });
</script>

The Lasso feature

The Lasso feature is new in version 6.13 - it allows you to select points on your Scatter chart and highlight them. There are a number of properties that are available to you that allow you to customise that appearance and how the feature behaves (for example a callback function so that you can integrate it into your existing code along with persistence, custom persistence load/save functions and appearance customisation). You can read the property descriptions here.

Note: There's an obj.clearLassoState() function that you can use if you want to clear the current selections. You'll need to call RGraph.redraw() after using this function. For example:

<button onclick="myScatter.clearLassoState(); RGraph.redraw();">Reset the canvas</button>

Here's a full example:

<script>    
    data = [
        [10,1],[10,2],[10,3],[10,4],[10,5],
        [20,1],[20,2],[20,3],[20,4],[20,5],
        [30,1],[30,2],[30,3],[30,4],[30,5],
        [40,1],[40,2],[40,3, 'red', 'Hello!'],[40,4],[40,5],
        [50,1],[50,2],[50,3],[50,4],[50,5],
        [60,1],[60,2],[60,3],[60,4],[60,5]
    ];
    
    // Create and configure the Scatter chart
    scatter = new RGraph.Scatter({
        id: 'cvs',
        data: data,
        options: {
            lasso: true,
            //lassoStroke: '#006',
            //lassoFill: '#f006',
            //lassoLinewidth: 1,
            //lassoHighlightLinewidth: 2,
            //lassoHighlightStroke: '#0000',
            //lassoHighlightFill: 'red',
            
            //This callback is called what points are cleared
            //
            //lassoClearCallback: function (state)
            //{
            //    $c(state);
            //},
            
            // When points are selected - this callback function
            // is called
            //
            //lassoCallback: function (state)
            //{
            //    //$c(state);
            //},
            
            // Whether to enable persistence or not. If nothing
            // else is specified then the state information is
            // stored in the window.localStorage variable
            lassoPersist: true,
            
            // Store the state information in the browser-based
            // window.localStorage variable
            lassoPersistLocal: true,
    
            //lassoPersistSave: function (state)
            //{
            //    // Store the state information (for example,
            //    // in a database). The state information is
            //    // in the form of a JSON object.
            //
            //    console.log(state);
            //},
            //lassoPersistLoad: function ()
            //{
            //    // Get the data (for example, from a database,
            //    // and return it (it should be a valid JavaScript
            //    // object).
            //    //
            //    // return state;
            //},
    
            xaxisScaleMax: 365,
            backgroundGridVlines: false,
            backgroundGridBorder: false,
            xaxis: false,
            yaxis: false,
            tickmarksStyle: 'circle',
            tickmarksSize: 8,
        }
    }).draw();
</script>

Also, you can double-click on a selection rectangle that you've added to remove it. And you can double click on an empty area of the canvas to get rid of all of the selection rectangles.

Marimekko charts

The RGraph Scatter chart now (v6.14+) has the ability to create Marimekko charts. These could be likened to Histogram charts or stacked Bar charts because of the way that they present data. Each stack of segments can take up an arbitrary amount of space depending on the proportion of the X value. The array of Y values that you provide is then organised much like a stacked Bar chart with the values converted to percentages so the total Y value adds up to 100%. The code that creates the chart that's shown here is below.