type
The
type property determines
the type of chart. It is a text string, which is one of the
following values (case is ignored when you assign the string):
'line' (default)
Selects a Line Chart. Each
series is drawn as lines between successive X, Y points. By default,
markers are not shown at each point. (If you want markers, set the
marker property for the
series). You can specify the color and line type for each series
individually, or leave the Chart object to select a default.
'stair'
Selects a Stair Chart. Same
as a Line chart, except that instead of the line being drawn directly
from each X,Y point to the next, a horizontal line is drawn first to
the next X position, and then a vertical line is drawn to the next Y
position.
This
sort of chart is useful for displaying series where the
Y values change in step-wise fashion (for example, a chart of interest rates set by
a central bank against time, or a chart showing a digital
representation of an analog value).
'area'
Selects an Area Chart. Similar
to a line chart, except that each series is drawn as a filled area
between the lines connecting the X,Y points, and the X axis. The
series are drawn in the order in which they were created, so a later
series may conceal some or all of an earlier series. You can specify
the color and fill pattern for each series individually, or leave the
Chart object to select a default. (Tip: If you want to avoid
concealing one series underneath another, you can set the
fillpattern property of
each series to be something other than solid).
'scatter'
Selects a Scatter Chart. No
line is drawn between the X,Y points of the series; instead, a marker
is drawn at each X,Y point. You can leave the Chart object to choose
a default marker type, or specify it yourself using the marker
property of each series.
This
sort of chart is useful for displaying experimental results.
(Sometimes, you will also want to include a separate line series
showing a theoretical fit to the experimental results, or a
least-squares regression to show a trend. You can do this using the
mixed chart type).
'bar'
Selects a Bar Chart. The
graph is drawn as a series of filled vertical bars from the X axis.
(The X values are ignored, except possibly to set labels for the
bars). If you have more than one series, the bars for each series
are displayed side-by-side. As with the other chart types, you can
set the fill color and/or pattern individually for each series, or
leave the Chart object to choose defaults. You can also set the
thickness of each bar (relative to the available space) using the
barwidth property.
'stackedbar'
Selects a Stacked Bar Chart. Like
a bar chart, but the bars for each series are placed on top of each
other at each data point, rather than side-by-side. This type of
chart is useful for showing both the total value of a quantity (for
example, total sales by quarter), and the contributions to the total
(for example, how much each region contributed to the total).
Normally,
stacked bar charts are used only for series where all the Y data
values are positive. If there are negative Y values encountered at a
given X value, there will in effect be two stacked bars drawn; the
positive ones will be stacked on top of each other in the positive
direction, and the negative ones will be stacked on top of each other
in the negative direction.
'horizbar'
Selects a Horizontal Bar Chart. Same
as a Bar chart, except that the bars are drawn horizontally.
'horizstackedbar'
Selects a Horizontal stacked bar chart. Same
as a Stacked Bar chart, except that the bars are drawn horizontally.
'hilo'
Selects a High-Low-Open-Close
(HLOC) chart. Unlike
the previous chart types, for an HLOC chart you need to specify more
than one Y value for each X value for a series. As a minimum, you
should specify the High and Low values (using the properties
highvalues and lowvalues).
For a financial chart, these typically represent the highest price
and the lowest price reached by a stock or commodity during a
particular trading period. The chart is drawn as a series of
vertical bars between the High and Low values for each X value (thus
showing the price range for the period). You can optionally specify
Open values for the series (using the property openvalues),
typically representing the opening price for the period. These are
drawn as a small tick to the left of the vertical bar. You can also
optionally specify Close values for the series (using the property
closevalues, which is a
synonym for yvalues).
These are drawn as a small tick to the right of the vertical bar.
Although
primarily used for financial data, this type of chart can also be
used for other applications, such as displaying experimental results.
In this case, the Open and Close values would both be specified to
represent the primary experimental results, with the High and Low
values representing the confidence limits.
'candle'
Selects a Candlestick chart. This
is a variant of the High-Low-Open-Close chart. Again, a line is
drawn between the High and Low values, but the difference between the
Open and Close values is shown by a rectangle. If the Open value is
greater than the Close, the rectangle is filled with the series
foreground color, otherwise it is filled with the background color.
This
type of chart is often used to show price trends over time; the
filled rectangles make it very obvious whether the closing prices
were higher or lower than the opening prices for each trading period.
'pie'
Selects a Pie chart. Draws
one or more circular areas, where each value is shown as a slice of
the circle representing the proportion of the total attributable to
each series. As such, they are rather like stacked bar charts,
except that you cannot tell the total value at each point, only the
proportion contributed by each series. Negative values are ignored.
If there are multiple pie charts displayed, they are automatically
arranged in rows and columns to make the best use of the available
space. Each pie will have the same radius.
By
default, the pie chart will be accompanied by a 'legend'
which shows the colors used for each series (provided you have
specified a caption
property for the series). However, the pie chart often looks better
if you disable the legend (by setting the placelegend
property of the Chart object to 'none'),
and use the style property
to cause each pie slice to be labelled with the series caption and a
percentage value.
Caution:
The Chart object displays one pie chart for each X value,
with each series contributing a slice to each pie (unless the value
is zero or negative). It does NOT display one pie per series. Thus,
in the limiting case where you want a single pie showing four
segments, you need to create four separate series, each with just one
value. Although this may seem somewhat unnatural at first, it is
implemented in this way for consistency with other chart types
(especially bars and stacked bars). This means you can swap between
the different chart types to display the same data in different ways.
This approach also allows you to set the color, fill pattern and
caption for each segment by setting properties of the Series objects.
The QUICKPIE
function in the workspace 10
SAMPLESCHART can be used if you want to create a simple
pie chart from an APL array.
You
can label the individual pies by setting xlabels
property of the Chart object.
'mixed'
Selects a Mixed chart type,
with different types for each Series. For
all of the Chart types above, each series in the chart in displayed
in the same way. Sometimes, however, you might want to mix different
types of chart together. For example, you might want to show
experimental results as a Scatter chart, and the prediction of a
mathematical model of the data as a Line chart. Or you might want to
show monthly profit figures as a Bar chart, and the cumulative
year-to-date profit as a Line chart.
If
you set the type property
of the Chart object to 'mixed',
then each series will be drawn according to the type
property of the individual Series object. This can be any of the
above types except for horizontal or stacked bars, or pies.
title
or caption
subtitle
note
These
properties are all text vectors, and are simply labels displayed
around the chart. Normally, the title
property is displayed in the largest font, and is intended to
represent the title for the whole chart. The subtitle
property is displayed below the title, in a slightly smaller font,
and is intended as a sub-title for the whole chart. The note
property is typically displayed in a small font, and is intended to
represent additional information such as a copyright notice or
acknowledgement. However, you can use these labels in any way you
wish, or omit them altogether by leaving them as empty vectors.
xaxislabel
yaxislabel
yaltaxislabel
These
properties are also text vectors, and are labels displayed adjacent
to the axes. They are usually used to indicate the units or meaning
of the scale along the axis.
placetitle
placenote
placelegend
These
properties determine where various labels of the chart are drawn.
The
placetitle property
determines where the title
and subtitle (if any) are
drawn. It is a text string, and can be one of the values 'top',
'topleft',
'topright',
'bottom',
'bottomleft',
'bottomright'.
The default is 'top', meaning the title is centered above the chart.
The
placenote property
determines where the note
(if any) is drawn. It can have the same values as the placetitle
property. The default is 'bottomright'.
The
placelegend property
determines where the chart legend is drawn. The legend shows, for
each series which has a non-empty caption
property, a sample line, marker, or filled rectangle as appropriate,
next to the caption. (If a given series has no caption, it will not
appear in the legend). This property is a text string, which can be
one of the values 'top',
'left',
'right',
'none',
or an empty vector. If it is 'none'
or an empty vector, the legend is not shown. The default is 'top'.
font
The
font property determines
the base font used for the Chart object. By default, the Chart
object uses this base font for every text element it draws, with the
size being chosen as a proportion of the window size, and different
sizes for the different elements (for example, the title
is drawn as the biggest). By changing the font
property, you can change the font family used to display all elements
unless they are specifically altered using one of the specific font
properties described below. The font property uses the same form as
the font property of other controls, i.e. it is a nested vector of
(Font name) (Size) (Style) (Character set). However, the Size
parameter is not used. The default is Arial, plain text.
Note:
Take care when changing this property to use a font which
displays well at a wide range of sizes, unless the chart is not
resizable. We recommend that you use a TrueType or OpenType font in
all cases.
fontaxis
fontlegend
fontnote
fonttitle
These
properties allow you to specify the font for individual elements of
the chart. Any changes you make to these override the setting of the
base font property.
These
properties are specified in a similar way to ordinary font
properties, as a nested vector of (Font name) (Size) (Style)
(Character set). However, the Size is defined in a special way. If
it is set to a value between 0 and 1, it means that the height of the
font should be the specified proportion of the window size, defined
as the smaller of the window height and width. Values in the region
of 0.03 to 0.05 are reasonable. This is recommended for resizable
charts, to ensure that the labels remain in proportion to the chart
as a whole. (If the font gets too small, a lower limit is imposed).
If the font size is specified as an integer greater than 1, it is
interpreted as a font size in Points, and will be fixed irrespective
of the size of the Chart. This is likely to mean that the chart does
not display well at very small or large sizes.
If
the Font name is an empty vector, the base font family is used. If
the Size or Style element is ¯1,
the corresponding font attribute is left unchanged.
xmajorticks
ymajorticks
yaltmajorticks
xminorticks
yminorticks
yaltminorticks
By
default, the Chart object chooses a suitable scale automatically, and
chooses sensible major and minor tick positions. It labels the major
tick positions with the corresponding numeric value.
These
properties allow you to specify your own positions for the major or
minor ticks along the X axis, Y axis, and alternate Y axis (if used).
Each property is a numeric vector, specifying where each tick
should be drawn. If both the major and minor tick vectors for a
particular axis are empty (which is the default), the Chart object
will position the tick marks automatically. If either the major or
minor tick vector is not empty, ticks will be drawn only where you
have specified them.
If
you specify your own tick positions, the scale for a particular axis
will usually range from the lowest tick mark you specify to the
highest. However, it will be extended to include any data point
which would otherwise fall outside the range.
xlabels
ylabels
yaltlabels
These
properties can be used to change the labels written next to the major
tick marks. By default, the Chart object labels the major ticks with
the corresponding numeric value. If you specify one of these
properties, then your labels will be used instead. However, (except
for the X axis of a bar chart or pie chart), you must also specify
the corresponding major tick positions, otherwise the Chart object
will not know where the labels should be placed.
The
labels can be specified either as a character vector with embedded
carriage returns, or as a text matrix, or as a nested vector of
character vectors. The first label is used for the first major tick
position, and so on. If there are more labels specified than tick
positions, the surplus labels are ignored. If there are fewer, the
ticks which do not have user-defined labels are labelled with the
default numeric value.
xlogscale
ylogscale
yaltlogscale
These
are Boolean scalar properties. If set to 0 (which is the default), a
normal linear scale applies. If set to 1, a logarithmic scale is used
for the corresponding axis.
You
cannot set a logarithmic scale for an axis where any data point is 0
or negative. If this situation occurs, the scale will revert to
linear.
xintercept
yintercept
These
properties can be used to specify where the X axis and main Y axis should cross the other axis. By default the X axis is placed at the bottom edge of the graph, or at the Y value of 0 if the Y axis ranges from negative to positive values, but you can specify a different position by changing the yintercept property. Similarly, the Y axis is by default placed at the left edge of the graph, or at X value 0 if the X axis ranges from negative to positive values, but you can specify a different value using the xintercept property.
xaltintercept
Returns the X position where the alternate Y axis (if any) crosses the X axis. Because the alternate Y axis is always drawn on the right-hand edge of the chart, this property is read-only.
xscale
yscale
yaltscale
These
are read-only properties, each comprising a two-element numeric
vector. They return the limits of the X, Y and Alternate Y axes
respectively.
style
The
style property of a Chart
object is the sum of a set of flags:
1 |
Draw
box around graph drawing area (i.e. the axes or individual pie
charts) |
2 |
Draw grid lines on X major ticks |
4 |
Draw grid lines on X minor ticks |
8 |
Draw grid lines on X major ticks |
16 |
Draw grid lines on Y minor ticks |
64 |
Draw the Y axis on the right as well as left |
128 |
Label pie slices with the series name |
256 |
Label pie slices with the percentage |
512 |
Label pie slices with the actual value |
The default is 0.
border
The
border property is a
Boolean scalar. If it is set to 1, a border is drawn around the
whole Chart object, including the titles and other labels.
monochrome
Normally,
charts are drawn in color, with different series being drawn in
different colors to distinguish them. Sometimes, however, you may
want the chart to be drawn in monochrome, for example if you are
printing it on a black-and-white printer. The monochrome
property allows this. If you set it to 1, all the elements of the
chart will be drawn in the Chart object's Foreground color (by
default, black). Since this means that the different series cannot
be distinguished by color, they will instead be distinguished by line
type (solid, dashed, dotted, etc) or by fill pattern (vertical
hatch, horizontal hatch etc). See the linetype
and fillpattern properties
of the Series object for more information on these.
color
or colour
The
color property is defined
in the same way as for other objects. It sets the Foreground and
Background color of the Chart as a whole. Colors can be specified in
one of two ways. In the first way, you specify a vector of three
integers (Red, Green and Blue), so that for example 255 0 0 is pure
red and 255 255 255 is white. In the second way, you specify a single
integer which encodes the three values in base 256 as 256 ƒ Blue Green Red. In addition, three special values are recognised; ¯1 means use the parent's foreground or background color as appropriate;
¯2 means use the default color (black for foreground and white
for background); ¯3 (valid only for the Background) means that
the background of the Chart is transparent, allowing you to draw the
chart on top of a picture.
When
the Chart is drawn, the control is first set to the Background color
(unless it is transparent), and then the various graphics elements
are drawn. By default, the axes, grids, labels and titles are all
drawn in the Foreground color, but you can change this using more
specific properties (see below). The data lines, markers, bars, or
pie slices for each series are drawn in the color associated with the
series (or in the Foreground color if the monochrome
property is set to 1). Note that the Chart object chooses a default
color for each series when it is created; you can change this by
setting the color property
for the child Series object.
coloraxis
or colouraxis
colorgrid
or colourgrid
colorlegend
or colourlegend
colornote
or colournote
colortitle
or colourtitle
These
properties allow you to set specific colors for the various
individual elements of the chart. They are specified as a single
color value (vector of three separate RGB values, or a single integer
encoding the three values). The default is ¯1, meaning use the
Chart object's foreground color. These properties are ignored if the
monochrome property is set
to 1.
linewidth
The
linewidth property of the
Chart is an integer scalar, which specifies the width in pixels of
lines drawn in the chart. The default is 1. The value set here is
used for all lines (axes, grids, and the data series lines), unless
you specify a different value for a particular element using one of
the more specific properties described below. You can set the line
width for a particular data series by using the linewidth
property of the child Series object.
axiswidth
gridwidth
These
two properties allow you to specify the line width (in pixels) for
the axis and grid lines respectively, as an integer scalar. The
default is ¯1, which means use the value set in the Chart
object's linewidth
property.
barwidth
The
barwidth property allow
you to specify the width of the bars used in bar charts. It is an
integer scalar, in the range 0 to 100, representing the percentage of
the available width used to draw the bars at each X value. (For a
Bar or Horizontal Bar chart with multiple series where the bars for
each series are placed side by side, this width is shared equally
between the different series). If the barwidth
property is set to 100, then 100% of the available space is used, so
there will be no gaps between the bars. If it is set to a low value
(say 20), then the bars will be very narrow, with lots of white space
between them. The default is 80.
margin
This
property sets the space which the Chart object leaves around the
chart. (In addition to this, the Chart object automatically allows
extra space for the titles, legend, axis labels, and tick labels.)
It is a numeric vector of four elements, representing the Left,
Right, Top and Bottom margins, in the units set by the standard scale
property of the control (do not confuse this with the X and Y scales
used for plotting data). The default is 16 pixels for all four
margins.
When
you use the Print method
to print the chart, the values in this property are added to the
print margins specified on the Printing tab of the APLX Preferences
dialog.
workarea
This
is a read-only property. It returns a vector of four numbers,
representing the Top Left Bottom Right of the data area of the graph
within the control (i.e. the area enclosed by the axes, excluding any
margin, titles, legend, or axis labels). It is expressed in the
units set by the standard scale
property of the control. It can be used if you need to draw extra
features on the chart (see the notes on the Draw
method below).
update
Normally,
any changes you make to the chart take effect almost immediately
(when events are next processed). In some cases, this might give a
flickering effect if the chart ends up being redrawn several times because
you are making a lot of changes to it. You can temporarily disable redraws
by setting the update
property to 0, and then making a sequence of changes to the chart.
When you set the update
property back to 1, the chart will be redrawn once, with all of the
changed properties.
bitmap
The bitmap
property is read-only. It returns a numeric matrix, which represents the image of the chart as an array of pixel values, with each pixel encoded as the RGB value. The image can be displayed in a Picture object, or (using an Image object), manipulated further and saved to file in any of the supported formats (such as JPEG or GIF).
picture
The picture
property is read-only. It is similar to the bitmap property, in that it represents the image of the chart. However, instead of representing each pixel of the chart it is currently drawn, it contains the series of drawing commands (encoded in a platform-specific way into a vector of integers). It is thus a vector-graphics version of the chart image, and can be re-drawn in good quality at different sizes, typically in a Picture object. You can also write it to file, or to the clipboard. (The picture property is not currently implemented under Linux).
svg
This read-only property returns the representation of the chart in Scalable Vector Graphics (SVG) format. This format is ideal for publishing your charts, since SVG will retain high-quality output on high-resolution devices.