Series Object Properties

Setting the data for the series:

values

The values property provides a quick way of specifying the X and Y values of a series in one operation. You can assign to it in the following ways (they are tested for in this order):

(a) 2 by N numeric matrix:

In this case the first row is assumed to contain the X values, and the second row the Y values.

(b) N by 2 numeric matrix:

In this case the first column is assumed to contain the X values, and the second row the Y values. (Note: for a 2 by 2 matrix, case (a) applies).

(c) Numeric scalar, vector, 1 by N matrix, or N by 1 matrix:,

In this case the data provided is assumed to represent the Y values of the series, and the X values are implicitly set to 0, 1, 2....N-1

If you read back this property, the data is always returned in format (a), i.e. as a 2 by N matrix of X values, Y Values

xvalues
yvalues

These properties can be written as numeric scalars, vectors or one-row matrices. They provide an alternative way of specifying the X and Y values respectively for points on the series. The xvalues property can be omitted (i.e. left as an empty vector), in which case they are assumed to be 0, 1, 2... up to the number of points specified in the yvalues property less 1. Otherwise, you should always provide the same number of values for X and Y.

If you read back one of these properties, the data is always returned as a numeric vector.

highvalues
lowvalues
openvalues
closevalues

These set the data used for High-Low-Open-Close and Candlestick charts. They are numeric vectors, each representing one of the four Y data points associated with each X value in the xvalues property. You should normally provide the same number of values for each of these properties, although openvalues and closevalues are optional.

Note that the closevalues property is actually a synonym for yvalues, and contains the same data.

Using the Alternate scale for the series:

usealtscale

This is a Boolean scalar. It defaults to 0, meaning that the series should be drawn using the main Y scale (i.e. the left axis). If you set it to 1, the series will instead be drawn using the alternate Y scale (i.e. the right axis).

If you want only one Y axis, but you want it to appear on the right instead of the left, set this property to 1 for all the series in the chart, so they all use the alternate axis. Alternatively, if you want only one axis, but you want it to be drawn on both the left and the right, leave this property as 0 for all the series in the chart (so they all use the main axis), and use the style property of the Chart object to specify that you want the main axis drawn on both sides (value 64).

Enabling/Disabling and Showing/Hiding the series:

enabled

This is a Boolean scalar. It defaults to 1, meaning that the series is enabled and should be included in the chart.

If you set this property to 0, the series is not included in the chart at all. This means that it is not displayed, and also that it takes no part in determining the scale used by the chart.

visible

This is also a Boolean scalar which defaults to 1, meaning that the series is visible (provided the enabled property is also 1).

If you set this property to 0, the series is not displayed when the chart is drawn. However, unless the enabled property is set to 0, the series will be taken into account when determining the scale of the chart.

This is useful for two purposes. Firstly, you can temporarily hide a series without the scale of the chart altering. Secondly, you can force the chart to extend the scale by including a dummy series which is enabled but not visible.

You can also use the Show and Hide methods to make the series visible or not; these have the same effect as changing the visible property.

Labelling the series:

caption or title

This property is a text vector, which associates a label with the series. By default it is an empty vector, which means the series has no label. If you give it a label using this property, then it will appear in the legend for the chart, with a sample line, marker or filled rectangle to show which series is which on the chart. (The legend will not be shown if the Chart object's placelegend property is set to 'none' or to an empty vector.)

For a Pie chart, the caption can also be shown directly next to the Pie slice, if the Chart object's style property includes the value 128.

Setting the appearance of the series:

marker

When a series is drawn as a Scatter chart, each point is denoted by a marker symbol. By default, the symbol to use is selected when the series is created. By changing the marker property, you can choose a particular marker symbol. In addition, if you specify a marker using this property, the marker will be also be displayed if the series is shown as a Line chart.

The marker is specified by assigning a character scalar, which is one of the following APL symbols: + × * ○ ⌽ ⊖ ∇ ∆ ⋄ ⎕ ↑ ↓ → ← It can also be a space or empty vector, in which case no marker is drawn.

(The actual marker is drawn is not a character, but a shape similar to that of the corresponding APL symbol. The APL font is not used to render the marker shape.)

fillmarker

Where a marker is drawn, by default it is drawn in outline only. If you set the fillmarker property to 1, the marker will be filled with the current marker background color (as set by the colormarker property), provided it is one of the following shapes: ○ ⌽ ⊖ ∇ ∆ ⋄ ⎕

color or colour

By default, the Chart object will choose a unique color for each Series object when it is created, but this property allows you to select a particular color. It is specified as a single color value (vector of three separate RGB values, or a single integer encoding the three values). It is used for drawing lines, and filling bars or areas, associated with the data of the series.

The color property is ignored if the Chart's monochrome property is set to 1.

colormarker or colourmarker

Usually, any marker associated with a series is drawn in the color set for the series as a whole (i.e. the color property, which is either chosen automatically or set explicitly). If you wish, you can display the marker in a different color by setting the colormarker property. You can also specify a background color for filling the marker. It is specified either as a single color value (vector of three separate RGB values, or a single integer encoding the three values), in which case it is used for both the foreground and background colors, or as two color values (length six vector of RGB values, or two integers encoding the color values), in which case the foreground color is used to outline the marker, and the background color is used to fill it if the fillmarker property is 1. The default values of ¯2 ¯2 mean use the same color as is used for the series as a whole.

The colormarker property is ignored if the Chart's monochrome property is set to 1.

fillpattern

Normally, bars and pie slices associated with a series are filled with a solid block of color. If you wish, you can specify a different fill pattern for the series, by assigning one of the following values to the fillpattern property:

1=Solid, 2=Horizontal grid pattern, 3=Vertical grid pattern, 4=Forward diagonal, 5=Backward diagonal, 6=Cross pattern, 7=Diagonal cross pattern

If the Chart's monochrome property is set to 1, and you haven't specified your own fill pattern, a default pattern from one of the above will be assigned to the Series object to distinguish it from other series on the chart.

linetype

Normally, lines associated with a series are drawn as a continuous (solid) line. If you wish, you can specify a different line type for the series, by assigning one of the following values to the linetype property:

1=Solid, 3=Dash, 4=Dot, 5=DashDot, 6=DashDotDot

If the Chart's monochrome property is set to 1, and you haven't specified your own line type pattern, a default type from one of the above will be assigned to the Series object to distinguish it from other series on the chart.

linewidth

This property is an integer scalar, which determines the width (in pixels) of lines drawn for the series. By default, it is ¯1, which means that the width should be taken from the linewidth property of the parent Chart object. By assigning a different value, you can specify a different line width for this series only.

Setting the series type for Mixed charts:

type

Normally, each series on the chart is shown in the same way, as determined by the type property of the parent Chart object. For example, all the series are displayed as bars if the chart type is set to 'bar'.

Sometimes, however, you may wish to display different series in different ways on the same chart. To do this, you need to set the type property of the parent Chart object to 'mixed'. The way in which each series on the chart will be displayed will then depend on the type property of each individual Series object. You can set this to one of: 'line' 'scatter' 'area' 'bar' 'stair' 'hilo' 'candle'. The default is 'line'.

Caution: Be careful when mixing series displayed as bar charts with the other types. Bars are by default drawn centered at X coordinates 1, 2, 3..., if no xvalues are set. By contrast, other types of graph are drawn either with the X coordinates explicitly set using xvalues, or at X coordinates starting at 0 (not 1) if no X values are specified.