Scatter chart API reference

• Example
• How to specify the Scatter chart data
• Using dates and times instead of numeric X values
• How to specify errorbars
• Using image-based tickmarks
• Adding a line connecting the tickmarks
• Showing the coordinates using the labelsAbove feature
• The coordinates properties
• Properties
• Methods
• Data properties that are used on the tickmarks
• Events

Example

<script>
    tooltip = 'Result: <b>%{value_formatted}</b>'

    data1 = [
        {x:'1st January',  y:0,tooltip: tooltip},  {x:'5th April',      y:5.56,tooltip: tooltip},
        {x:'27th February',y:23,tooltip: tooltip}, {x:'4th April',      y:46,tooltip: tooltip},
        {x:'1st October',  y:18,tooltip: tooltip}, {x:'28th September', y:43,tooltip: tooltip},
        {x:'23rd August',  y:50,tooltip: tooltip}, {x:'1st June',       y:12,tooltip: tooltip},
        {x:'1st March',    y:32,tooltip: tooltip}, {x:'27th July',      y:12,tooltip: tooltip},
        {x:'23rd April',   y:32,tooltip: tooltip}, {x:'1st January',    y:50,tooltip: tooltip},
        {x:'3rd November', y:23,tooltip: tooltip}, {x:'12th December',  y:15,tooltip: tooltip},
        {x:'4th May',      y:41,tooltip: tooltip}
    ];
    
    data2 = [
        {x:'4th January',   y:0,  tooltip: tooltip, color: 'red'},  {x:'9th April',      y:5.56, tooltip: tooltip, color: 'red'},
        {x:'24th February', y:23, tooltip: tooltip, color: 'red' }, {x:'8th April',      y:46,   tooltip: tooltip, color: 'red'},
        {x:'9th October',   y:18, tooltip: tooltip, color: 'red' }, {x:'24th September', y:43,   tooltip: tooltip, color: 'red'},
        {x:'21st August',   y:50, tooltip: tooltip, color: 'red' }, {x:'2nd June',       y:12,   tooltip: tooltip, color: 'red'},
        {x:'19th March',    y:32, tooltip: tooltip, color: 'red' }, {x:'25th July',      y:12,   tooltip: tooltip, color: 'red'},
        {x:'24th April',    y:32, tooltip: tooltip, color: 'red' }, {x:'9th January',    y:50,   tooltip: tooltip, color: 'red'},
        {x:'16th November', y:23, tooltip: tooltip, color: 'red' }, {x:'14th December',  y:15,   tooltip: tooltip, color: 'red'},
        {x:'8th May',       y:41, tooltip: tooltip, color: 'red' }
    ];

    scatter = new RGraph.SVG.Scatter({
        id: 'chart-container',
        data: [data1, data2],
        options: {
            marginLeft: 100,
            yaxisScaleDecimals: 2,
            xaxisScaleMin: '1st January 00:00:00',
            xaxisScaleMax: '31st December 23:59:59',
            xaxisLabels: ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'],
            tickmarksStyle: 'circle',
            tooltipsFormattedUnitsPost: 'kg',
            tooltipsCss: {
                backgroundColor: '#333',
                fontWeight: 'bold',
                fontSize: '14pt',
                opacity: 0.85
            }
        }
    }).draw();
</script>

How to specify the Scatter chart data

The Scatter chart is slightly different from other charts because, whereas other charts (usually) use arrays of information to specify values, the Scatter chart uses an array of objects. This should come quite naturally though as each Scatter chart point can have several different attributes (eg x-axis value, y-axis value, tooltip etc). At its most basic it looks like this:

var data = [
    {x:5,y:7}, {x:7,y:9}, {x:1,y:3}
];

That would define three points, each with x-axis and y-axis values. There are other things that you can add to each object (or just one/two etc) and they are:

• type (If not specified the default is the tickmarksStyle property, possible types are listed here)
• color (If not specified the default is the colors property (one color per dataset, not each individual point) )
• size (If not specified the default is the tickmarksSize property)
• opacity (If not specified the default is 1
• tooltip (If not specified, no tooltip will be present for this tickmark)

Another example where each point has all of the options specified is:

var data = [
    {x:5,y:7,type: 'triangle',color: 'green', size: 10,opacity: 0.75,tooltip: 'The first tickmark'},
    {x:7,y:9,type: 'square',color: 'red', size: 15,opacity: 0.5,tooltip: 'The second tickmark'},
    {x:1,y:3,type: 'cross',color: 'cyan', size: 15,opacity: 0.25,tooltip: 'The third tickmark'}
];

Using dates and times instead of numeric x-axis values

Instead of numeric x-axis values, you can instead give a DateTime string that RGraph will parse (using the RGraph.SVG.parseDate function) and use as the value instead. The xaxisScaleMin and xaxisScaleMax values can also be specified like this. The format of the DateTime string can be varied (as you can see from the example below). Here's an example of a DateTime chart.

<script>
    data = [
        {x:'23:59 15-01-2012', y:5},
        {x:'2012 15th February', y:6},
        {x:'Mar 15 2012', y:6},
        {x:'2012/04/15', y:6},
        {x:'2012-05.15', y:5},
        {x:'2012 June 15', y:4},
        {x:'July 2012 15th', y:5},
        {x:'Aug 15th 2012', y:6},
        {x:'15th September 2012', y:7},
        {x:'15 Oct 2012', y:6},
        {x:'2012.11.15', y:4},
        {x:'2012.12-15 00:00:00', y:5}
    ];
    
    new RGraph.SVG.Scatter({
        id: 'chart-container',
        data: data,
        options: {
            backgroundGridVlines: false,
            backgroundGridBorder: false,
            yaxis: false,
            colors: ['red'],
            title: 'A Scatter chart using DateTime values',
            xaxisScaleMin: '2012/01/06 12:14:12',
            xaxisScaleMax: '31st dec 2012'
        }
    }).draw();
</script>

How to specify errorbars

You can specify errorbars on your Scatter chart by using the errorbar option in the data array. The value can be either a simple number or an object which allows you a little extra control. The example code below can be seen in a demo file in the download archive named svg-scatter-errorbars.html.

<script>
    var data1 = [
        {x:1, y:7, errorbar: 3, color: 'red'},
        {x:2, y:5, errorbar: {max: 6, color: 'red', linewidth: 2}, color: 'red'},
        {x:3, y:3, errorbar: {min: 1, max: 1}, color: 'red'}
    ];

    var data = [
        {x:7,  y:7, errorbar: {min: 1, max: null}, color: 'red'},
        {x:8,  y:5, errorbar: {min: 1, max: 1}, color: 'red'},
        {x:10, y:3, errorbar: {min: 1, max: 1}, color: 'red'}
    ];


    new RGraph.SVG.Scatter({
        id: 'chart-container',
        data: [data, data1],
        options: {
            //errorbarsLinewidth: 5,
            //errorbarsCapwidth: 20,
            //errorbarsColor: 'pink',
            marginLeft: 35,
            xaxisScaleMin: 0,
            xaxisScaleMax: 12,
            xaxisLabels: ['Q1', 'Q2','Q3','Q4'],
            tickmarksStyle: 'circle'
        }
    }).draw();
</script>

Using image-based tickmarks

If the list of tickmarks does not suit your needs you can use an image as your tickmark instead. You can specify one by doing this:

<script>
    new RGraph.SVG.Scatter({
        id: 'image-based-tickmarks',
        data: [
            {x: 50, y: 26, type:'image:/images/a.png'},
            {x: 100, y: 26, type:'image:/images/b.png'},
            {x: 150, y: 26, type:'image:/images/c.png'},
            {x: 200, y: 26, type:'image:/images/d.png'},
            {x: 250, y: 26, type:'image:/images/e.png'}
        ],
        options: {
            title: 'A Scatter chart using image-based tickmarks',
            xaxisScaleMin: 0,
            xaxisScaleMax: 365,
            xaxisLabels: ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
        }
    }).draw();
</script>

Adding a line connecting the tickmarks

By using the line option you can have a line connecting the points, therefore, creating a Line chart - but with this Line chart (instead of the regular Line chart ) the points are not necessarily a fixed width apart - the x-axis value is totally down to you along with the y-axis value. The DateTime chart above is also showing an example of using the line option.

With a little configuration, you can use the Scatter chart with this line option to show a Vertical Line chart instead of a horizontal one. There's an example that shows you an example of it in the download archive.

Showing the coordinates using the labelsAbove feature

The Scatter chart has the labelsAbove feature - just like the Bar, Line and Waterfall charts. It's enabled a little differently though. Instead of setting the labelsAbove property to true you set the above property in each points configuration object in the data to true. Like this:

<script>
    var data = [
        {x:0,   y:0,  above:true},
        {x:100, y:5,  above:true},
        {x:84,  y:23, above:true},
        {x:65,  y:46, above:true},
        {x:221, y:18, above:true}
    ];

    new RGraph.SVG.Scatter({
        id: 'chart-container',
        data: data,
        options: {
            xaxisScaleMax: 365,
            xaxisLabels: ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec']
        }
    }).draw();
</script>

You can then use the labelsAbove configuration properties that are shown below to configure their appearance as normal.

The coordinates properties

The coordinates of all of the marks that are on the Scatter chart are held in the obj.coords and obj.coords2 arrays. The difference between the two is how they're indexed - the obj.coords array is simply a sequential array where each points information is simply appended to the array. The obj.coords2 array on the other hand is indexed by dataset and then by the index in that dataset. So if you have two datasets each having six points then the obj.coords array would look like this:

• obj.coords[0]
• obj.coords[1]
• obj.coords[2]
• obj.coords[3]
• obj.coords[4]
• obj.coords[5]
• obj.coords[6]
• obj.coords[7]
• obj.coords[8]
• obj.coords[9]
• obj.coords[10]
• obj.coords[12]

• obj.coords2[0][0]
• obj.coords2[0][1]
• obj.coords2[0][2]
• obj.coords2[0][3]
• obj.coords2[0][4]
• obj.coords2[0][5]
• obj.coords2[1][0]
• obj.coords2[1][1]
• obj.coords2[1][2]
• obj.coords2[1][3]
• obj.coords2[1][4]
• obj.coords2[1][5]

• element The tickmark svg element
• object The Scatter chart object
• type A string that denotes the type of the tickmark (eg cross)
• x The x-axis coordinate
• y The y-axis coordinate
• z The Z-axis coordinate (commonly this is the size of the tickmark)

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
• Margin properties
• Tickmark properties
• X-axis properties
• Y-axis properties
• Other text properties
• Line properties
• Key properties
• Tooltip properties
• Title properties
• Bubble chart properties
• Error bar properties
• Trend line properties
• Miscellaneous properties

xaxisFormatter: function (obj, num)
{
    return num;
}

yaxisFormatter: function (obj, num)
{
}

tooltipsOverride: function (obj, opt)
{
    // Show tooltip
}

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'
}

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

This can be used to get properties if necessary. It's normally used after the chart is drawn if you need to get parameters (if you're doing custom coding for example).

This can be used to set properties if necessary. It's normally used after the chart is drawn if you need to set additional parameters or change them.

This method can be used to get an appropriate x-axis coordinate for a value when you're doing custom drawing on the chart. It returns null if the value is out of range.

This method can be used to get an appropriate y-axis coordinate for a value when you're doing custom drawing on the chart. It returns null if the value is out of range.

This function adds an event listener (such as beforedraw or draw) to the chart object. For example:

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

This function can be used to execute a function (immediately). It's not event-based (ie it doesn't run when something happens) - it just runs immediately - and only once. You might use it when you need to get something from the chart when it's drawn and then call the redraw function. Because this function only runs once the RGraph.SVG.redraw function would not cause a loop - which would happen if you used the draw event.

obj.exec(function (obj)
{
    // Put your code 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.

Data properties that are used on the tickmarks

The svg elements that represent the tickmarks (eg path, circle elements) on the Scatter chart have various data attributes added to them that hold various bits of information. These are:

• data-index
• data-dataset
• data-original-opacity
• data-original-color
• data-original-coordx
• data-original-coordy
• data-size
• data-sequential
• data-type

These can be retrieved by using standard dom methods:

obj.coords[0].element.getAttribute('data-index');

Events

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

• beforedraw This event fires at the start of the draw method before anything has been done.
• draw This event fires at the end of the draw function.
• firstdraw This event fires at the end of the draw function - but only the first time and so it fires only once after the first draw call.
• beforetooltip This event fires at the start of the tooltip showing process.
• tooltip This event fires after a tooltip has been shown.

new RGraph.SVG.Scatter({
    id: 'chart-container',
    data: [
        {x:355, y:18, color: 'red'},  {x: 25, y:35, color: 'red'},
        {x:120, y:23, color: 'red' }, {x: 65, y:46, color: 'red'},
    ],
    options: {
        xaxisScaleMax: 365
    }
}).on('tooltip', function (obj)
{
    console.log('The draw event has fired');
    
}).draw();