RChart, User Guide

J4L-CHART for Ruby

Copyright 2011, J4L Components (http://www.java4less.com)
Go bak to contents

Linechart configuration / parameters

Linechart
Areachart
Scatterchart
Curves
OHLC and Candlestick
Bubblechart
Linechart 3D

Linechart

The following table constains an example of a linechart with 2 lines (series):

*Parameters*	*Description*	*Equivalent Ruby class/property*
TITLECHART=Sales 2001 XLABEL=Month YLABEL=Million $ YSCALE_MIN=0 TICK_INTERVALY=2 BIG_TICK_INTERVALX=1 XAXIS_GRID=0.2\|WHITE\|DASHED YAXIS_GRID=0.2\|#ffffff\|DASHED GRIDY=true XAXIS_LABELS=June\|July\|Aug.\|Sept.\|Oct.\|Nov.\|Dec. YAXIS_START_WITH_BIG_TICK=true LEGEND=FALSE SERIE_1=Products SERIE_2=Services SERIE_FONT_1=Arial\|PLAIN\|8 SERIE_FONT_2=Arial\|PLAIN\|8 SERIE_COLOR_1=RED SERIE_COLOR_2=BLUE SERIE_DATA_1=12\|43\|50\|45\|30\|32\|42 SERIE_DATA_2=20\|41\|48\|39\|36\|34\|50 SERIE_STYLE_1=0.2\|RED\|LINE SERIE_STYLE_2=0.2\|BLUE\|LINE SERIE_POINT_2=false SERIE_POINT_COLOR_1=RED SERIE_POINT_COLOR_2=BLUE LEGEND_POSITION=BOTTOM LEFT_MARGIN=0.18 CHART_FILL=#ffcc00	Title Definition of the scale Activate grids Grid at big ticks only Labels of the x axis Big tick at possition 0 Hide legend Serie name Font for value color of font values to be plotted line style do not paint points color of points possition of legend Space reserved for y axis. background color	J4LChart::Title.new("Sales 2001") chart.xLabel= J4LChart::HAxisLabel.new("Month",color,font) chart.yLabel= J4LChart::VAxisLabel.new("Million $",color,font) chart.yAxis.scale.min=0 chart.xAxis.scaleTickInterval=2 chart.xAxis.bigTickInterval=1 chart.xAxis.gridStyle= J4LChart::LineStyle.new(...) chart.yAxis.gridStyle= J4LChart::LineStyle.new(...) chart.xAxis.bigTicksGrid=true chart.xAxis.tickLabels=["June",...] chart.yAxis.startWithBigTick=true chart.legend=null serie1= J4LChart::LineDataSerie.new(lineStyle,values) serie1.valueFont= J4LChart::GraphicsProvider.getfont(...) see values in LineDataSerie constructor see lineStyle in LineDataSerie constructor serie2.drawPoint=false serie1.pointColor= J4LChart::GraphicsProvider.getcolor(J4LChart::RED) chart.layout= J4LChart::LAYOUT_LEGEND_BOTTOM chart.leftMargin=0.18 chart.back= J4LChart::GraphicsProvider.getcolorRGB(#ff,#cc,0)

Points outside the chart

If you want to have a fixed maximum value for your Y Scale and leave some points outside the chart you can do it like this:

*Parameters*	*Description*	*Equivalent Ruby class/property*
YSCALE_MAX=50 YSCALE_MIN=0 SERIE_DATA_1=12\|43\|90\|45\|30\|32\|42 SERIE_DATA_2=20\|31\|38\|39\|36\|34\|50 LINECHART_FIXED_LIMITS=TRUE	Definition of the scale Values to be plotter. The 90 is outside the chart Allow points to be outside the chart	chart.xAxis.scale.max=50 chart.xAxis.scale.max=0 linePlotter.fixedLimits=true

the result is:

null values

If you serie has some missing points you can use NULL as value to paint a discontinued line. This feature is not compatible with (LINECHART_FIXED_LIMITS=TRUE)

*Parameters*	*Description*	*Equivalent Ruby class/property*
YSCALE_MAX=50 YSCALE_MIN=0 SERIE_DATA_1=12\|43\|50\|45\|30\|32\|42 SERIE_DATA_2=20\|31\|null\|39\|36\|34\|50	Definition of the scale Values to be plotter. The null is a missing value (discontinued line)	values=[20, 30, nil, ...] serie2= J4LChart::LineDataSerie.new(lineStyle,values)

As you see the blue series does not a value for July.

Areachart

Areacharts are exactly like linecharts, you only need to provide a fill color for the area. When designing these kind of charts keep in mind that serie 1 is painted first (in the background) and serie 2 in the foreground.

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_STYLE_1=0.2\|0000\|NORMAL SERIE_STYLE_2=0.2\|0\|NORMAL SERIE_FILL_1=#ff0000 SERIE_FILL_2=#0000ff	Black line used as border Color used for filling the areas	see lineStyle in LineDataSerie constructor serie1.fillStyle= J4LChart::FillStyle.new(...)

Scatterchart

Scatter chart are linecharts where:

no lines are painted between points (SERIE_DRAW_LINE_*=false).
and you must provide the Y and X coordinates for each point (SERIE_DATA_* and SERIE_DATAX_*).

For example:

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_DATA_1=12\|43\|50\|45\|30\|32\|42\|3\|11 SERIE_POINT_1=TRUE SERIE_DATAX_1=1\|2\|2\|1\|3\|4\|6\|7\|3\|1\|2 SERIE_DRAW_LINE_1=FALSE SERIE_POINT_COLOR_1=#0000ff LINECHART_POINT_SIZE=6	Y Values Paint blue squares X possition of the points. Do not paint lines between points Points are blue Size of squares is 6 pixels	serie1= J4LChart::LineDataSerie.new(lineStyle,values) serie1.drawPoint=true serie1.setDatax(...) lineStyle=null in LineDataSerie constructor serie1.pointColor= J4LChart::GraphicsProvider.getcolorRGB(#ff,0,0) linePlotter.pointSize=6

Other usefull parameters are:

LINECHART_POINT_SIZE: size of the squares used to paint points.
SERIE_POINT_COLOR_1: color of the point (only LINE type).

You can also use images instead of squares for plotting the points:

SERIE_POINT_IMAGE_1: Name of the image file used for the points (gif or jpg). The file must be either relative to the java classes (e.g. "point.gif" or "..\images\point.gif") or absolute (e.g. "http://www.mysite.com/images/point.gif").

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_POINT_IMAGE_1=point.gif	Use point.gif as image for the points	serie1.icon=image

If you want to have 2 Y axis you must use the following parameter:

SERIE_SECONDYAXIS: if "true" this data serie will use the second Y axis. The second YAxis is painted on the right side of the chart.

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_SECONDYAXIS_2=TRUE Y2LABEL=Local Currency Y2LABEL_VERTICAL=TRUE Y2AXIS=TRUE Y2SCALE_MIN=0 Y2SCALE_MAX=100 TICK_INTERVALY2=2 BIG_TICK_INTERVALY2=10 Y2AXIS_INTEGER=TRUE RIGHT_MARGIN=0.15	Second serie (blue) uses axis Y2 (right Y axis) Definition of the Y2 axis Activate right Y axis Definition of the scale (0-100) Space for the right axis	serie1.secondYAxis=true chart.y2Label= J4LChart::VAxisLabel.new("local currency",color,font) chart.y2Label.vertical=true cY2Axis= J4LChart::Axis.new(J4LChart::VERTICAL,scY2) chart.setY2Scale(cY2Axis) cY2Axis.scale.min=0 cY2Axis.scale.max=100 cY2Axis.scaleTickInterval=2 cY2Axis.bigTickIntervaL=10 cY2Axis.integerScale=true chart.rightMargin=0.15

It is possible to define a different color for the chart's background and the plotter's background:

LINECHART_BACK: background style.

*Parameters*	*Description*	*Equivalent Ruby class/property*
CHART_FILL= #ffcc00 LINECHART_BACK= #cccc00	Background color of the chart. Background color of the plotter area.	chart.back= J4LChart::GraphicsProvider.getcolorRGB(#ff,#cc,00) linePlotter.back = J4LChart::GraphicsProvider.getcolorRGB(#cc,#cc,00)

Tips

You can add tips to the points of your chart like this:

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_POINT_1=TRUE SERIE_TIPS_1=12\|43\|50\|45\|30\|32\|42 CHART_SHOW_TIPS=TRUE	Tips require points to be activated Tips for each point Activate tips

Curves

J4L-Chart offers you 3 type of curves:

Cubic curves: the points you provide will be contained in the curve.

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_TYPE_1=CURVE	Use cubic natural curves	plot= J4LChart::CurvePlotter.new() lineDataSerie.lineType= J4LChart::TYPE_CUBIC_NATURAL

B-SpLines: The points will not be contained in the curve but the curve will be smoother than cubic curves.

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_TYPE_1=B-SPLINES	Use B-SPLines	plot= J4LChart::CurvePlotter.new() lineDataSerie.lineType= J4LChart::TYPE_B_SPLINES

The last type is not a curve but a line calculated using the least squares algorithm.

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_TYPE_1=LINE_LEAST_SQUARES	Use least squares	plot= J4LChart::CurvePlotter.new() lineDataSerie.lineType= J4LChart::TYPE_LEAST_SQUARES_LINE

OHLC and Candlestick

In order to create a Candlestick chart you must use the following additional parameters:

SERIE_MAX_DATA_*: maximum values.
SERIE_MIN_DATA_*: minimum values.
SERIE_CLOSE_DATA_*: close values.
SERIE_LINE_TYPE_1=CANDLESTICK.

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_DATA_1=12\|43\|50\|45\|30\|32\|42 SERIE_MAX_DATA_1=18\|48\|55\|53\|35\|45\|44 SERIE_MIN_DATA_1=20\|30\|40\|30\|28\|20\|34 SERIE_CLOSE_DATA_1=15\|38\|45\|50\|28\|35\|40 SERIE_LINE_TYPE_1=CANDLESTICK SERIE_CANDLE_POSITIVE_COLOR_1=#00ff00 SERIE_CANDLE_NEGATIVE_COLOR_1=#ff0000 SERIE_MAXMIN_STYLE_1=0.2\|#0000ff\|NORMAL	Open values Maximum values Minimum values Close values Select candlestick type Color of candlesitck is open<close Color of candlesitck is open>close Style of the line	serie= J4LChart::MaxMinDataSerie.new(lineStyle,values) serie.initMaxMin(values,closeValues, minValues,maxValues, nil) linePlotter.maxMinType= J4LChart::MM_CANDLESTICK serie.maxminStyle= J4LChart::LineStyle.new(...)

If you want to create a OHLC chart you must change the SERIE_LINE_TYPE_1 parameter:

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_DATA_1=12\|43\|50\|45\|30\|32\|42 SERIE_MAX_DATA_1=18\|48\|55\|48\|35\|35\|44 SERIE_MIN_DATA_1=8\|30\|40\|30\|28\|20\|34 SERIE_CLOSE_DATA_1=9\|33\|45\|40\|28\|30\|40 SERIE_LINE_TYPE_1=OHLC SERIE_OPENCLOSE_WIDTH_1=10	Open values Maximum values Minimum values Close values Select OHLC type Length of the open/close lines	serie= J4LChart::MaxMinDataSerie.new(lineStyle,values) serie.initMaxMin(values,closeValues, minValues,maxValues, nil) linePlotter.maxMinType= J4LChart::MM_OHLC

If you only want to display the maximum and minimum values (no open/close values) you can use:

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_LINE_END_1=TRUE SERIE_DATA_1=12\|43\|50\|45\|30\|32\|42 SERIE_MAX_DATA_1=18\|48\|55\|48\|35\|35\|44 SERIE_MIN_DATA_1=8\|30\|40\|30\|28\|20\|34	Draw line end. Open values Maximum values Minimum values	linePlotter.maxMinType= J4LChart::MM_NORMAL serie= J4LChart::MaxMinDataSerie.new(lineStyle,values) serie.setMaxMinValues(maxValues,minValues)

Bubblechart

Bubblecharts will draw a circle around points of the line. The radius of the circle is defined using the SERIE_MAX_DATA_* parameter.

For example:

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_BUBBLE_1=TRUE SERIE_FILL_BUBBLE_1=TRUE SERIE_DATA_1=12\|43\|50\|45\|30\|32\|42 SERIE_MAX_DATA_1=2\|3\|4\|3\|2\|2\|3\|2	Activate bubbles Bubbles should be filled Values of the points Values of the radius of the bubbles in (Y axis units)	maxMinDataSerie.bubbleChart=true maxMinDataSerie.fillBubble=true maxMinDataSerie= J4LChart::MaxMinDataSerie.new(lstyle,data) maxMinDataSerie.setMaxMinValues(radiusValues,null)

if you want to remove the line and only point the bubbles you must use SERIE_DRAW_LINE_1=false;

Linechart 3D

In order to create a 3D linechart you only need to add the parameter: SERIE_TYPE_1=LINE3D (or use LinePlotter3D in java code).

The order 3D specific parameters are:

LINECHART3D_DEPTH=20
LINECHART3D_BORDER=0.2|BLACK|LINE
LINECHART3D_BACK=WHITE

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_TYPE_1=LINE3D LINECHART3D_DEPTH=20 LINECHART3D_BORDER=0.2\|BLACK\|LINE LINECHART3D_BACK=WHITE LINECHART3D_SEPARATOR=0	Use 3D lines Length of the Z axis (depth) Border of the surface of the line. Space between lines.	linePlotter3D= J4LChart::LinePlotter3D.new() linePlotter3D.depth linePlotter3D.border linePlotter3D.back linePlotter3D.interLineSpace

As in the 2D lineharts you can create an arechart by adding the fill color for the area.

*Parameters*	*Description*	*Equivalent Ruby class/property*
SERIE_FILL_1=#ff0000	Fill area with red color	serie1.fillStyle= J4LChart::FillStyle.new( J4LChart::GraphicsProvider.getcolor( J4LChart::RED))