SVG Scatter charts API reference

  Read comments...

Summary
Documentation about the SVG Scatter chart including information on all the options and methods that are available to you.

 

Example

<script>
    var data = [
        {x:16,y:42},{x:15,y:43},{x:58,y:12},{x:84,y:23},{x:65,y:46},{x:221,y:18},{x:263,y:43},{x:121,y:50},
        {x:215,y:12},{x:222,y:32},{x:344,y:12},{x:123,y:32},{x:2,y:50},{x:355,y:23},{x:125,y:15},{x:85,y:41}
    ];
    
    new RGraph.SVG.Scatter({
        id: 'chart-container',
        data: data,
        options: {
            xaxisMax: 365,
            xaxisLabels: ['Jan','Feb','Mar','Apr','May','Jun','Jul','Aug','Sep','Oct','Nov','Dec'],
            tickmarksStyle: 'plus',
            colors: ['red']
        }
    }).draw();
</script>

The code above produces a chart like this:

 

How to specify the Scatter chart data

The Scatter chart is a touch different than other charts because whereas they (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 value, Y 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 and Y values. There are other things that you can add to each object (or just one/two etc) and they are:

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 values

Instead of numeric X 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 xaxisMin and xaxisMax values can also be specified like this too. 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',
            xaxisMin: '2012/01/06 12:14:12',
            xaxisMax: '31st dec 2012'
        }
    }).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/logo.png'},
            {x: 100, y: 26, type:'image:/images/coins.png'},
            {x: 150, y: 26, type:'image:/images/atom.png'},
            {x: 200, y: 26, type:'image:/images/alert.png'},
            {x: 250, y: 26, type:'image:/images/alex.png'}
        ],
        options: {
            title: 'A Scatter chart using image based tickmarks',
            xaxisMin: 0,
            xaxisMax: 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 neccarsarily a fixed width apart - the X value is totally down to you along with the Y value. The datetime chart above is also showing an example of using the line option.

 

Properties

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

 

Background

Properties: backgroundColor, backgroundImage, backgroundImageAspect, backgroundImageOpacity, backgroundImageStretch, backgroundImageX, backgroundImageX, backgroundImageW, backgroundImageH, backgroundGrid, backgroundGridColor, backgroundGridLinewidth, backgroundGridBorder, backgroundGridHlines, backgroundGridHlinesCount, backgroundGridVlines, backgroundGridVlinesCount

backgroundColor
The color of the background.
Default: null

backgroundImage
A URL of an image to render to the background
Default: null

backgroundImageAspect
The aspect ration setting of the SVG image tag, eg it could be XMinYMin meet
Default: none

backgroundImageOpacity
The alpha/opacity value of the background image.
Default: 0.5

backgroundImageStretch
Whether the background image is stretched across the whole chart (except the gutters).
Default: true

backgroundImageX
If you're not using the stretch option you can specify the X coordinate of the image.
Default: null

backgroundImageX
If you're not using the stretch option you can specify the Y coordinate of the image.
Default: null

backgroundImageW
If you're not using the stretch option you can specify the width of the image.
Default: null

backgroundImageH
If you're not using the stretch option you can specify the height of the image.
Default: null

backgroundGrid
Whether to show the background grid or not.
Default: true

backgroundGridColor
The color of the background grid.
Default: #ddd

backgroundGridLinewidth
The linewidth that the background grid lines are. Decimals (eg 0.5) are permitted.
Default: 1

backgroundGridBorder
Determines whether a border line is drawn around the grid.
Default: true

backgroundGridHlines
Determines whether to draw the horizontal grid lines.
Default: true

backgroundGridHlinesCount
Determines how many horizontal grid lines you have. The default is linked to how many scale labels that you have.
Default: null

backgroundGridVlines
Determines whether to draw the vertical grid lines.
Default: true

backgroundGridVlinesCount
Determines how many vertical grid lines you have. The default is to be linked to how many scale labels that you have.
Default: null

 

Margins

Properties: gutterLeft, gutterRight, gutterTop, gutterBottom

gutterLeft
The left gutter of the chart, (the gutter is where the labels and title are)).
Default: 35

gutterRight
The right gutter of the chart, (the gutter is where the labels and title are).
Default: 35

gutterTop
The top gutter of the chart, (the gutter is where the labels and title are).
Default: 35

gutterBottom
The bottom gutter of the chart, (the gutter is where the labels and title are).
Default: 35

 

Colors

Properties: colors

colors
An array of the colors of the bars.
Default: null

 

Tickmarks

Properties: tickmarksStyle, tickmarksSize

tickmarksStyle
The style of the tickmarks. This can be a string, or it can also be an array of different types which are used on a per-dataset basis. You can also specify the type: attribute in the data set (see above). Possible types are:
Default: cross

tickmarksSize
The size of the tickmarks. It can be a number or an array of numbers, one for each dataset. This can be overridden on a per-point basis by using the size property in each points configuration data.
Default: 7

 

X axis

Properties: xaxis, xaxisTickmarks, xaxisTickmarksLength, xaxisLabelsOffsetx, xaxisLabelsOffsety, xaxisColor, xaxisTextColor, xaxisTextBold, xaxisTextItalic, xaxisTextFont, xaxisTextSize

xaxis
Whether the X axis is shown or not.
Default: true

xaxisTickmarks
Whether the X axis has tickmarks or not.
Default: true

xaxisTickmarksLength
The size of the X axis tickmarks
Default: 5

xaxisLabelsOffsetx
The X pixel offset thats added to the X axis labels.
Default: 0

xaxisLabelsOffsety
The Y pixel offset thats added to the X axis labels.
Default: 0

xaxisColor
The color of the X axis.
Default: black

xaxisTextColor
The color of the X axis text (this overrides the textColor option)
Default: null

xaxisTextBold
Whether the X axis text is bold or not (this overrides the textColor option)
Default: null

xaxisTextItalic
Whether the X axis text is italic or not (this overrides the textItalic option)
Default: null

xaxisTextFont
The font of the X axis text (this overrides the textFont option)
Default: null

xaxisTextSize
The size of the X axis text (this overrides the textSize option)
Default: null

 

Y axis

Properties: yaxis, yaxisColor, yaxisTickmarks, yaxisTickmarksLength, yaxisScale, yaxisLabelsOffsetx, yaxisLabelsOffsety, yaxisLabelsCount, yaxisUnitsPre, yaxisUnitsPost, yaxisDecimals, yaxisPoint, yaxisThousand, yaxisRound, yaxisMax, yaxisMin, yaxisFormatter, yaxisTextColor, yaxisTextBold, yaxisTextItalic, yaxisTextFont, yaxisTextSize

yaxis
Whether the Y axis is shown or not.
Default: true

yaxisColor
The color of the Y axis.
Default: black

yaxisTickmarks
Whether the Y axis has tickmarks or not.
Default: true

yaxisTickmarksLength
The size of the Y axis tickmarks
Default: 5

yaxisScale
Whether the the Y axis scale is shown.
Default: true

yaxisLabelsOffsetx
The X pixel offset thats added to the Y axis labels.
Default: 0

yaxisLabelsOffsety
The Y pixel offset thats added to the Y axis labels.
Default: 0

yaxisLabelsCount
The number of Y labels.
Default: 5

yaxisUnitsPre
Units that are prepended to the scale numbers.
Default: (An empty string

yaxisUnitsPost
Units that are appended to the scale numbers.
Default: (An empty string

yaxisDecimals
The number of decimals that the scale will show.
Default: 0

yaxisPoint
The character(s) used as the decimal point.
Default: .

yaxisThousand
The character(s) used as the thousand seperator.
Default: ,

yaxisRound
If set to true the max scale value will be rounded up.
Default: false

yaxisMax
The maximum scale value (you will need to set yaxisStrict to true if you want the maximum value to be exactly this value).
Default: null

yaxisMin
The minimum Y value. As well as a numeric value you can also set this to mirror so that the X axis is put in the center.
Default: 0

yaxisFormatter
This option should be a function. This function handles the entirety of the number formatting for the yaxis. Units are not added, decimals are not added - its all up to you. The function is passed two arguments - the chart object and the number. It should look like this:
yaxisFormatter: function (obj, num)
{
}

Default: null

yaxisTextColor
The color of the Y axis text (this overrides the textColor option)
Default: null

yaxisTextBold
Whether the Y axis text is bold or not (this overrides the textColor option)
Default: null

yaxisTextItalic
Whether the Y axis text is italic or not (this overrides the textItalic option)
Default: null

yaxisTextFont
The font of the Y axis text (this overrides the textFont option)
Default: null

yaxisTextSize
The size of the Y axis text (this overrides the textSize option)
Default: null

 

Text

Properties: textColor, textFont, textSize, textBold, textItalic

textColor
The color of the text.
Default: black

textFont
The font used for text.
Default: sans-serif

textSize
The size of the text.
Default: 12

textBold
Whether the text is bold or not.
Default: false

textItalic
Whether the text is italic or not.
Default: false

 

Line

Properties: line, lineColors, lineLinewidth

line
This can either be a boolean or an array of booleans that determines whether a line is drawn connecting the points (for each dataset).
Default: false

lineColors
This can either be a string or an array of strings that determines the colors of the lines that are drawn.
Default: black

lineLinewidth
This can either be a number or an array of numbers that determines the colors of the lines that are drawn.
Default: black

 

Tooltips

Properties: tooltipsOverride, tooltipsCssClass, tooltipsEvent, highlightFill

tooltipsOverride
If required, this can be a function that totally handles the tooltip showing instead of the default RGraph tooltips. It should look like this:
tooltipsOverride: function (obj, opt)
{
    // Show tooltip
}
The opt is an argument that contains these items:
Default: null

tooltipsCssClass
The CSS class thats applied to the tooltip DIV.
Default: RGraph_tooltip

tooltipsEvent
The event used for tooltips (either click or mousemove.
Default: click

highlightFill
The fill color that's used when highlighting the chart.
Default: rgba(255,255,255,0.7)

 

Title

Properties: title, titleX, titleY, titleHalign, titleValign, titleColor, titleFont, titleSize, titleBold, titleItalic, titleSubtitle, titleSubtitleX, titleSubtitleY, titleSubtitleHalign, titleSubtitleValign, titleSubtitleColor, titleSubtitleFont, titleSubtitleSize, titleBold, titleSubtitleItalic

title
The title of the chart.
Default: (An empty string)

titleX
The specific X coordinate of the title.
Default: null

titleY
The specific Y coordinate of the title.
Default: null

titleHalign
The horizontal alignment of the title.
Default: center

titleValign
The vertical alignment of the title.
Default: bottom

titleColor
The color of the title.
Default: black

titleFont
The font used to render the title.
Default: null

titleSize
The size of the font used to render the title.
Default: 16

titleBold
Whether the title is bold or not.
Default: false

titleItalic
Whether the title is italic or not.
Default: false

titleSubtitle
The subtitle of the chart. If a subtitle is specified the title is moved up to accommodate it. As such you might need to give a larger gutterTop value.
Default: (An empty string)

titleSubtitleX
The specific X coordinate of the subtitle.
Default: null

titleSubtitleY
The specific Y coordinate of the subtitle.
Default: null

titleSubtitleHalign
The horizontal alignment of the subtitle.
Default: center

titleSubtitleValign
The vertical alignment of the subtitle.
Default: top

titleSubtitleColor
The color of the subtitle.
Default: #aaa

titleSubtitleFont
The font used to render the subtitle.
Default: null

titleSubtitleSize
The size of the font used to render the subtitle. It defaults to be the same as the textSize setting.
Default: 10

titleBold
Whether the subtitle is bold or not.
Default: false

titleSubtitleItalic
Whether the subtitle is italic or not.
Default: false

 

Attribution

Properties: attribution, attributionX, attributionY, attributionHref, attributionHalign, attributionValign, attributionFont, attributionSize, attributionColor, attributionItalic, attributionBold

attribution
Whether to show the attribution link or not. If you're going to link to the RGraph website elsewhere on your site then set this to false.
Default: true

attributionX
The X coordinate of the link. This can be a number (in which case it's treated as the absolute coordinate) or it can be a string starting with a + or - (in which case it's treated as an adjustment to the default value).
Default: (bottom right corner of the SVG tag)

attributionY
The Y coordinate of the link. This can be a number (in which case it's treated as the absolute coordinate) or it can be a string starting with a + or - (in which case it's treated as an adjustment to the default value).
Default: (bottom right corner of the SVG tag)

attributionHref
The href of the link (ie the page to link to).
Default: http://www.rgraph.net/svg/index.html

attributionHalign
The horizontal alignment of the link.
Default: right

attributionValign
The vertical alignment of the link
Default: bottom

attributionFont
The font used to render the link.
Default: sans-serif

attributionSize
The point size of the link.
Default: 7

attributionColor
The color of the link.
Default: gray

attributionItalic
Whether the link is italic or not.
Default: false

attributionBold
Whether the link is bold or not.
Default: false

 

Methods

 

obj.set(name, value)

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.

 

obj.getYCoord(value)

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

 

obj.on(event, handler)

This function adds an event listener (such as onbeforedraw or ondraw) to the chart object.

 

obj.exec(func)

This function simply executes the function that you give it (there and then - not on any particular event)

If you like RGraph please share it: