⎕CHART Draw Chart of Data

Implemented on desktop editions of APLX only

⎕CHART provides a quick way of drawing a chart (graph) of data in an APL array. The right argument is the data to be plotted, which can comprise one or more data series. The optional left argument is a set of keyword/value pairs which allow you to customize the appearance of the chart. The chart appears in a new window. Once it has appeared, you can use the menu bar to alter the way in which it is displayed (for example, to switch to a logarithmic Y scale).

⎕CHART is designed to provide automatic graph-drawing facilities with very little programming effort. If you wish to have full control over how the chart is drawn, you should instead use the Chart object under ⎕WI. You can also chart data by right-clicking over the name of a variable and selecting 'Display As Chart' from the pop-up menu, or by choosing 'Chart Variable..' from the Edit menu of the session window.

Data to be Charted

The right argument to ⎕CHART is the data to be charted. It can be any of the following:

• A numeric vector (or one-row or one-column matrix). In this case, the values in the array are regarded as the Y values, and they are plotted against implicit X values 0, 1, 2...
  
  
• A numeric matrix of at least two rows and columns. In this case, APLX by default assumes that the longer dimension represents the points of each series, and the shorter dimension represents the number of series to be plotted. For example, for an array of 20 rows and 3 columns, it is assumed that there are three data sets, each containing 20 values, rather than 20 data sets, each containing 3 values.
  
  Once APLX has decided which dimension represents the data sets, it then tries to decide which data set (if any) represents the X values. APLX first looks to see whether the first or the last data set comprises a regularly incrementing series (such as 10, 14, 18, 22); if so, it is assumed to be the series of X values against which the other data sets are plotted as Y values. If neither data set comprises a regularly-increasing series (i.e. with a constant interval), APLX next looks to see if either data set comprises an irregularly incrementing series (such as 10, 12, 16, 24); if so, it is taken to represent the X values. Finally, if neither data set satisfies the criteria, it is assumed that all the data sets represent Y values, which are then plotted against implicit X values 0, 1, 2...
  
  If any of these assumptions are wrong, you can change them using the menu bar once the window has opened. You can also specify explicitly where the data is by supplying a left argument to ⎕CHART, as discussed below.
  
  
• A nested matrix of either two rows or two columns, where one of the rows (or columns) comprises a series of numbers, and the other a set of character strings. In this case, the numbers are assumed to represent data values, and the strings labels. The data is initially plotted as a Bar chart, but using the Chart menu you can change it to a different type such as a Pie chart.

Customizing the Chart

The optional left argument to ⎕CHART allows you to the determine how the chart is displayed. (If you omit it, APLX uses the above rules initially, and then the parameters can be adjusted using the Chart menu.)

It comprises a nested vector of one or more phrases of the form 'Keyword=Value'. (If there is only one such phrase, the argument can be a simple character vector). The options are as follows (case is ignored in checking the keywords):

title - Sets the title for the whole chart, for example 'title=Absorbtion of Calcium'

type - Sets the type of graph, for example 'type=area'. The value part of this phrase should be one of the following: line scatter area bar stair horizbar or pie. If you omit this phrase, a Line chart is drawn initially, unless the right argument is nested, in which case a Bar chart is drawn. Once the chart has appeared, you can change the type using the Chart menu.

data - Specifies how the data is laid out in the right argument, for example 'data=rows'. The value part of this phrase should be one of the following: rows (the data points are along the rows of the right argument, or columns or cols (the data points are laid out down the columns of the right argument). If you omit this phrase, APLX uses the rules described above. Again you can adjust the choice once the chart has been drawn.

x - Specifies which data set contains the X values. This can one of first (the X values are in the first row or column of the right argument), last (the X values are in the last row or column of the right argument), or implicit (all the rows/columns contain Y values, which should be plotted against 0, 1, 2...). If you omit this phrase, APLX tries to guess the most likely layout using the rules described above.

seriesname - Allows you to specify a label to be attached to each series of the graph. You will normally want to repeat this phrase several times, once for each series in the chart. For example, if you wanted a chart showing sales for three regions against an implicit X axis of 0,1 2, you could provide an N by 3 array as the right argument, and for the left argument specify: 'seriesname=America' 'seriesname=Europe' 'seriesname=Asia' 'x=implicit'. The data in the first row would be labelled 'America', the second 'Europe', and the third 'Asia'.

Live Charting

The 'id' keyword can be used to tell ⎕CHART to re-use an existing chart window to graph new data. This can be useful if you want to do simple animations, for example display a graph of changing data acquired from an external measuring device in real time. The keyword takes the form 'id=N', where N is a positive integer. When the id keyword is specified, ⎕CHART will check whether there is already a chart window with the same id, creating a new window only if one is not found (See examples).

Tip: If you want to chart a variable, and have the chart change when the variable changes (in desk calculator mode), you can use an expression like this in a Watch window:

      'id=1' ⎕CHART X

Examples

Draw a sine wave. Because no X values are specified, implicit X values of 0, 1, .... 99 are used:

      ⎕CHART 1○0.1×⍳100

Draw a sine wave with the X values specified in degrees. We provide a two-column matrix; APLX assumes the second column is the X axis, because it increments regularly:

      ⎕IO←1
      ⎕CHART (1○(10×0,⍳36)×○2÷360),[1.5]0,10×⍳36

Draw a bar chart:

      ⎕CHART 2 4⍴'Apples' 'Pears' 'Oranges' 'Kumquats' 445 323 345 765

Draw the same data as a pie chart:

      'type=pie' ⎕CHART 2 4⍴'Apples' 'Pears' 'Oranges' 'Kumquats' 445 323 345 765

Draw some random data as two, named series, against implicit X values 0, 1, 2..:

      'x=implicit' 'seriesname=Bicycles' 'seriesname=Tricycles' ⎕CHART ?2 8⍴100

Draw an animated graph

       ∇AnimatePulse;pulse;X
[1]   pulse←(*-X÷10)×1○4×X←⍳100      ⍝ Create some fake data
[2]   pulse←(⌽pulse),pulse
[3]   :Repeat
[4]     'id=1' ⎕CHART pulse
[5]     pulse←2⌽pulse
[6]   :EndRepeat
      ∇  

See also the Chart and Series system classes, which give you much more detailed control over the layout and appearance of graphs.