Background to RainPro

RainPro is a Causeway product which brings true publication-quality graphics to your application. This help file gives you a brief introduction, and a handy reference to the command options available.

Basics | Getting Started
Philosophy | Understanding the Rain Approach
History | The History and Evolution of Rain
Viewer | Using the Chart Viewer
Printing | Printing the Finished Chart
Images | Saving Image Files
Internet | Publishing Charts on the Internet


Rain graphics: Getting Started

Getting Started

Installation

RainPro is shipped as an APL workspace containing a large number of sample functions, and two namespaces ch and PostScrp which contain everything that you will need in order to use it from your application. A standard Windows help file is also enclosed, containing an on-line version of this manual. Simply copy the workspace to your normal development directory, and place the help file wherever you find convenient.

To access the workspace, )load it in the usual way. You will be able to try a selection of examples immediately. To access the help file, double-click it in Explorer or add a desktop shortcut which starts it for you.

Learning by example!

By far the best way to learn RainPro is to copy and modify the examples! When you load the workspace, you will be directed to a selection of variables (such as Help) which simply list the examples for you so that you can take the cursor to the line of your choice, and <Enter>. All the sample functions place the finished chart in the variable PG, so all you need to do to see the result on screen is View PG. Experiment with ‘zoom-in’ using the left mouse button (drag a rectangle across the area you want to magnify), and try out the right-mouse menu for printing options. See Using the Chart Viewer for more detail.

If you need help on the terms used throughout Rain, the glossary illustrates many of the concepts.

Building charts into your applications

When you are comfortable with the basics, you will want to use the graphics in your own GUI application. Because Rain runs the code entirely out of the ch and PostScrp namespaces, all you need in your workspace are these two objects. For example:

   )load myws
   )copy rainpro ch PostScrp

This allows you to make your plot in myws, as a vector of PostScript code. Assuming you want to see it on screen, you could to use the PS object (see causeway.hlp for more details) which will display the result for you, and provide the same options as PostScrp.View when the user uses the right-mouse menu on the chart.

For an introduction to the capabilities in ‘Active Rain’ (which are also supported by the Causeway classes) please turn to the notes on the new functions supported by the PostScrp namespace.

Note that PS is careful to preserve the proportions of the chart – these are 4:3 by default – so either ensure your PS field has this shape, or note the shape you make it and use ch.New 0 0 w h to get your chart drawn to fit the hole on the screen! See Multiple Plots for more details.

If you are just playing around, simply copy the View function from Rain. To include the charts in your APL application (without using any Causeway classes) you can render the chart on any Windows control which supports graphic objects as children. See RawGui for details.

Note that Rain is a language, and is intended for APL programmers, not end-users! If you want to build a friendly front-end with colourful toolbars and pull-down choices, that is fine, but please acknowledge the use of RainPro in the ‘About’ box for your finished application.


Rain graphics: Understanding the Rain Approach

Understanding the Rain Approach

The world is full of ever-cleverer packages which generate ever more chartjunk. Rain is not one of these! It is philosophically aligned to Tufte’s principles of maximizing the visibility of data, and refusing to permit spurious decorations, artificial 3D effects and unnecessary ink such as grids and moiré-shadings. See “The Visual Display of Quantitative Information” (Graphics Press 1983) for some excellent background reading on good chart design.

There are three steps required to produce a completed graphic, although for really simple charts, steps 1 and 3 may not be needed.

  1. Set up the plotting space
  2. Plot the data
  3. Add any notes and extra datum lines

Stage-1 includes defining all the headings, labels and captions, as any of these operations may influence the shape of the final plotting region. A typical sequence of commands might be:

   ch.Set 'Heading' 'This is my Graph'
   ch.Set 'Key' 'Budget,Actual'
   ch.Plot mydata
   ch.Note 'May figures are low because ...' (12 56)
   PG←ch.Close
   View  PG    ⍝ To see it on the screen

Note how the plotting commands work on a high-level description of the finished graphic to produce a set of simple drawing commands (in a subset of the PostScript language) which is returned to you by ch.Close. This is actually just a simple character vector, and you can browse it in the workspace with the standard APL editor.

To see the completed chart on the screen, you must View it (obviously, you might have several charts stacked up in advance with different names): the View function runs a simplified PostScript interpreter to render the chart on the screen. You can also print it, either via normal Windows channels or direct to your PostScript printer if you have one. Namespaces are included to save the chart to SVG (Scalable Vector Graphic) or VML (Vector Markup Language) and the PostScrp namespace supports saving the chart as a varity of common image formats such as PNG.


Rain graphics: The History and Evolution of Rain

The History and Evolution of Rain

Why Rain?

All I wanted to do was to plot the records from our daily rainfall readings on a simple chart, showing monthly totals as a backcloth and a vertical line for each (non-zero) daily amount. Clearly I wanted the scale labelled up in months, with the captions centred between the tick marks, but unfortunately months have different numbers of days, so my tick-mark spacing would have to be irregular! This started me down the road of applying the syntax of IBM’s PGF package (which is still one of the best around) to the problem of drawing quite sophisticated statistical graphics with the minimum of extraneous junk.

Why PostScript?

I was lucky in one important respect: I had just become interested in the PostScript language, and by coding in the union of PostScript and APL I was able to separate the logical design from the physical necessity to render the finished graphic on the screen or to paper. This allowed me to write the bulk of the code independently of the graphics software, as it simply constructs a character vector of PostScript code.

I then had the rather simpler problem of writing the APL functions (e.g. MOVETO, SHOW) which write lines and text to the screen. Because these were quite compact, it was easy to take my first attempt (in APL*PLUS/PC with ⎕G style graphics) and redo it for the Windows interpreters. As you would expect, the improvement in quality was startling.

An advantage in working with PostScript in the APL*PLUS/PC environment was that anyone lucky enough to have a suitable printer could already generate publication-quality output, while the rest of us were stuck with low-resolution screen dumps. With Windows the problem is much reduced, as the graphs can be rendered on to any good-quality printer (such as an HP DeskJet or LaserJet). However I have retained the option of writing direct to the printer, because it is around 10 times faster than going via the Windows printer queue! It may also be useful to provide output files in .EPS form so that word-processor users can included them as graphics, so I left this in too. As the Adobe Acrobat format becomes more popular for publishing on the Internet, it is good to know that the output from Rain is in ideal format for input to the Adobe Distiller.

The functions offered by Rain have changed little over the years, as the basic set of line and bar graphs seemed all I needed. The major change in the Windows release has been to modify the syntax to match the ⎕W calls of the native Windows-APL objects. This greatly reduces the number of functions you need in the workspace, as ch.Set now handles nearly everything. It also allows me to run all the code from two namespaces ch and PostScrp, with only very minimal stubs in your workspace. This makes for easy maintenance, and keeps name-clash problems to a minimum.

Where next?

This version of Rain has limited 3D capabilities for a range of charts which have seemed useful to me at various times. It continues to avoid spurious decorations and pointless perspective effects! Now that the basic functions are in place to draw mesh surfaces, towers and scatter plots, it would be relatively easy to extend this capability to a wider range of plots. Please let me know what would be useful – Polar charts are a recent addition which came from a user-request and contour plotting is next on the list.


Rain graphics: Using the Chart Viewer

Using the Chart Viewer

This shows the viewer toolbar, which you can use to copy the chart to the clipboard, print the current page (or all pages if you are viewing a report made up of several charts), or return to full-screen view if you zoom in.

To magnify part of the chart, drag a rectangle around it with the left mouse button. The area shown will be based on the top edge of the rectangle you enclose, keeping the correct aspect ratio.

When you have zoomed in, you can ‘walk’ around the chart using the arrow keys, or zoom out with the ‘-’ key. You will notice that the (x,y) co-ordinates in the status field at the lower right track the mouse, using the co-ordinate system appropriate to your chart. You can use this to check the exact value of any data point, or to help find a good location for a key or note. If you have added ∆data hints∇ to your chart, these will be shown in the main status field in the lower centre of the window.

Right-mouse menu

This shows the standard right-mouse menu which all users can access from the chart viewer. In general, the menu simply duplicates the toolbar buttons, but you also have the extra options:

  • Clipboard as Bitmap (sized as shown)
  • Clipboard as Bitmap (custom size) – this will prompt for a scaling factor to translate from points (72 per inch) to pixels (notionally 96 per inch). If you enter 1 (the default) your graph will be clipboarded at 3/4 of the viewed size; to generate a bitmap suitable for a 300dpi printer, use 4.16 as the scale, and so on. You will need to run APL with a large MAXWS setting to generate images at higher resolutions.
  • Direct PostScript – use this if you have a genuine PostScript printer attached to your PC, or would like to save the report on file in PostScript format. It will prompt for a file name ⍎ just enter ‘prn’ for a locally attached printer.
  • EPS file – use this to save your report in ‘Encapsulated PostScript Format’ which will allow it to be included in any high-end DTP document by tools such as Adobe PageMaker. It is also supported by Microsoft Word, but you may need to install the appropriate import filter. Documents including EPS graphics may only be printed on PostScript printers.
  • Windows Metafile – this will prompt for a file name and save the report as a standard Windows metafile, with a ‘placeable header’ so that it will be sized correctly when included in a document. This is a suitable format for all the normal Microsoft Office tools and will print well on any standard Windows printer.

Note that you can customise all these menu commands by changing the phrasebook file uk-en.apb and running PostScrp.GetPhraseBook to replace the default prompts. This also allows you to remove unwanted elements by setting the prompt text to ‘~’.

See also ...

Translating the Viewer Texts


Rain graphics: Printing the Finished Chart

Printing the Finished Chart

There are two main alternatives for printing the finished chart:

PostScript printing

If you have a PostScript printer, you can use PostScrp.Write to write the chart definition directly to the printer:

PG←ch.Close              ⍝ Completed chart
View PG                  ⍝ to see it on screen
PostScrp.Write PG        ⍝ Print (portrait) to 'prn'
'myfile.prn' PostScrp.Write PG     ⍝ Print to disk file

This is recommended rather than using the Windows printer driver, as Rain is around 10 times faster and the quality of the results is a little better. You can edit PostScrp.Write to switch to Landscape orientation (1.4 times larger) or enable colour support.

Windows printing

If you have a standard Windows printer (e.g. HP LaserJet or DeskJet) you can send your chart to the Windows print queue with:

PostScrp.Print PG

This will switch the printer to the orientation which best matches your chart, and will size the chart to be as large as possible (within the printable area of the page).

Output to a DTP package

If you have a package such as Word or PageMaker, you might like to include your charts as .EPS objects within a document. To export a chart in this form:

'myfile' PostScrp.WriteEPS PG

Rain includes bounding box, date and title information, so that you will be able to size the graphic within the document, and also view the title and date on screen. Note that such documents can only be printed on PostScript printers.

Copying the chart to the clipboard

To save the current chart in ‘Placeable Metafile’ format on the clipboard, use

PostScrp.Clip PG

You can then paste the chart into most Windows applications such as Microsoft Word. It can be sized within the document as required. If you prefer to save the chart on file (in placeable metafile format) provide a left argument giving the file name:

'c:\temp\chart.wmf' PostScrp.Clip PG

You can then use Insert,Picture in Word to make a link to the file from your document.

To save a bitmap image on the Clipboard, use:

PostScrp.ClipBits PG
0.5 PostScrp.ClipBits PG  ⍝ Scale to half size
3 PostScrp.ClipBits PG    ⍝ Suitable for 300dpi printing

This defaults to 1:1 scaling, but you can choose to ‘thumbnail’ the image, or have it magnified to give reasonable results on the printer. If you scale this above 5 (suitable for 600dpi) you will need enough workspace to hold the resulting bitmap, say 4Mb minimum.

Printing from the View function

When your chart is displayed with PostScrp.View, you can use the right mouse button to choose from a list of options. If you choose Print you will write the chart to the default Windows printer as above. If you choose PostScript, you will be prompted for the device to write the output to. Just leave this as <prn> to send the chart to your printer. See Using the Chart Viewer for more detail.


Rain graphics: Saving Image Files

Saving Image Files

Dyalog APL can save images as Windows bitmaps (uncompressed), GIF format files (also uncompressed) and PNG (Portable Network Graphic) which is a lossless compressed format, and is the best for most practical purposes.

There is a simple cover function in the RainPro workspace to save any chart in PNG format:

   'c:\temp\sample' ToPNG PG
Chart written to c:\temp\sample.png

This takes the intermediate format returned by ch.Close and renders it to an image file at 1:1 scaling. You can copy and modify this function to set the scale, and you may also want to save an imagemap if you have used hyperlinks on the chart for drill-down or other effects on the web.

See also ...

Publishing Charts on the Internet


Rain graphics: Publishing Charts on the Internet

Publishing Charts on the Internet

RainPro supports two basic methods of internet publishing – you can save your chart in one of the two standard picture formats (GIF or PNG) or you can export it in text format as ‘Vector Markup Language’ (VML) which is rendered very effectively by IE5, or as SVG (the newer W3C graphics standard). The necessary support functions are in the vml and svg namespaces along with support for direct output to PDF which is included with NewLeaf.

Saving charts in picture format

From Dyalog APL you can use PostScrp.MakePNG or PostScrp.MakeGIF directly, but note that Dyalog can only make uncompressed GIF files, so if you want to use this format, it may be worth loading the file into a program such as PaintShop Pro and resaving it to reduce the file size.

To make a really simple web page, you can open Notepad, and type a couple of lines such as:

<h2>Here is My Chart</h2>
<img src="mychart.png">
<p>That was easy!</p>

Save the file as ‘c:\temp\first.htm’, and double-click it in Windows Explorer. You will see the text (with the top line in bold), a placeholder for the picture, as it doesn’t exist yet, and the last line in normal text.

To make an example chart, and save it as a picture:

ch.Set 'head' 'My First Chart'
ch.Pie 5 4 3 2
PG←ch.Close
png←PostScrp.MakePNG PG

You will find that png is a 3-element nested vector. It has the integer representation of the picture in the first element, a ‘client-side image map’ in the second element and the id of the chart in the third.

      ⍴png
3
      ⍴¨png
 5750  30  8
      2⊃png
<MAP name="chart186">
</MAP>
      3⊃png
chart186

The first element may be written ‘raw’ to file to make an image in the correct format:

      20↑⊃png
¯119 80 78 71 13 10 26 10 0 0 0 13 73 72 68 82 0 0 1 ¯80
      'c:\temp\mychart.png' PostScrp.rput ⊃png

You can now view the completed web page (with the chart in place) in your browser.

The optional left argument of MakePNG sets the scale factor – for example to make a miniature:

      'c:\temp\mychart.png' PostScrp.rput ⊃0.4 PostScrp.MakePNG PG

Press F5 again in the browser to see a much smaller pie.

Note on GIFs and PNGs

The GIF format is universally acceptable (it works in all browsers from Netscape-1 upwards) but the compression algorithm used was retrospectively claimed as copyright by Unisys who charge a ridiculous fee for developers (like us) to license it.

The PNG format is supported by any browser with a version number of 4 and above, and is an all-round better performer. It is also public, free and well supported by Microsoft tools such as Word. Use it if you are reasonably sure your readers mostly have up-to-date browsers!

Saving the chart in VML

Vector Markup Language (VML) is a new facility in IE5 which allows you to include high-quality vector graphics in your web page. These are written entirely as text, are typically much smaller than the corresponding picture, and print very much better. The VML support in RainPro is quite comprehensive, but you will notice that rotated text is not rendered particularly well by the browser, and you might prefer the PNG format for 3D charts for this reason.

To convert any Rain graph to VML, use vml.PS to convert the intermediate PostScript format to a text vector of VML code, then you can use Clip to put it on the clipboard. Simply paste the result into your HTML file, put the required magic words into the header (see vml.header) and view it in IE5 or later. See VMLTest for a simple example which you can adapt. There are several examples of VML-based graphics on the Causeway website, but of course you will need IE5 to view them.

Adding hypertext jumps to charts

If you really want to know what is going on here, you can read about “Client-side Image Maps” in any good introduction to HTML. The object is to allow any data point to act as a hypertext jump, so that you can readily implement graphically-based ‘drill-down’ applications on your website. As a simple example, we might want to see some annotations related to the second sector of a piechart:

       ch.Set 'head' 'My First Chart'
       ch.Set 'xlabs' 'One' 'Two' 'Three' 'Four'
       ch.Href 2 1 'notes.htm'
       ch.Pie 5 4 3 2
       PG←ch.Close
       png←PostScrp.MakePNG PG

The new function introduced here ch.Href has a simple job to do. For any data point (addressed by row,column – piecharts have all their values in column-1) you can associate an internet address. The map is built for you by PostScrp.MakePNG ...

      2⊃png
<MAP name="chart17487">
<area shape="poly" coords="225,159,163,208,183,226,209,236,236,237,262,228,284,211,286,208" href="notes.htm">
</MAP>

You can now paste this map into your web page (conventionally at the beginning of the body section). Typically your HTML code will now look like ...

<MAP name="chart17487">
<area shape="poly" coords="225,159,163,208,183,226,209,236,236,237,262,228,284,211,286,208" href="notes.htm">
</MAP>
<h2>Here is My Chart
<img src="mychart.png" usemap="#chart17487" border=0>
<p>That was easy!</p>

I added ‘border=0’ out of neatness, as I object to the heavy blue line that browsers put around pictorial jumps; you can safely leave it out. Now you can also see why we need those uniquely numbered maps – it allows you to have several mapped charts on the same page.

The pie should look much the same as before in the browser, but now when you wave the mouse over the second pie sector, the mouse turns into a pointing hand, and you can click anywhere on the sector to see the detailed notes. You can easily define multiple jumps, and build the correct URL strings to call back to your Dyalog web server – see the notes on ch.Href for full details.

Summary

Charts may be saved as image files, and may be referred to from the IMG tag in normal HTML code. If you make a special section called an image map, this can contain various shape definitions which may themselves act as hypertext jumps. You associate your image with the map by referring to its name in the usemap attribute of the IMG tag. In the future, the spread of VML will allow high-quality vector graphics to be viewed directly in the browser.


Tutorials

This chapter takes you through some of the examples which are included in the RainPro workspace. You can copy and adapt the source code as required to make your own charts. You might also like to read Alan Sykes∇ APL99 tutorial from our web site, which has several more examples of statistical graphics.

Tutorial | Introduction to the Tutorials
Terms | Glossary of Terms
Playfair_1 | A “Simple” Timeseries (the Playfair Plot)
Chw | Checkweigher Calibration
Population | Drawing a Population Pyramid
Multiples | Managing Multiple Plots
Sambars | Four Barcharts on One Page
Trellis | Making a Trellis of Small Plots
Positioning | Positioning Small Plots on the Page
Frequency | Some Basic Statistics (Frequency Plot)
Boxplot | How to Construct a Boxplot
ThreeD | 3D Charting
ASL91 | Illustrating a Maths Function
Rain94 | The Gilling East Rainfall Chart
Playfair_2 | Playfair Revisited


Rain graphics: Introduction to the Tutorials

Introduction to the Tutorials

The tutorial examples work through a collection of typical graphics, beginning with a simple line-chart, and ending with the same chart, presented in the same style as the classic Playfair graphic from 1786. The sections are reasonably independent, so it is fine to skip straight to the topic which appears most relevant to you.

  • Glossary ... terms used to define the charting space
  • Playfair-1 ... a simple line plot of econometric data
  • Checkweigher ... data analysis using barchart and line graph
  • Population ... the classic pyramid chart
  • Multiples ... managing multiple plots
  • Barcharts ... 4 charts on one page to show the possibilities
  • Trellis ... dividing the plotting space automatically
  • Positioning ... using xy-plots to place a collection of miniatures
  • Frequency ... a typical statistical graphic
  • Boxplot ... making Box & Whisker plots
  • 3D Charting ... towers, surfaces and scatter plots
  • ASL91... illustrating the Logistic curve
  • Rainfall ... how the Gilling Rainfall chart is done
  • Playfair Revisited ... a reasonable facsimile of the 1786 original

All the charts in these examples were drawn by functions in the RainPro workspace – please examine and modify the code to see the effect.


Rain graphics: Glossary of Terms

Glossary of Terms

Chart Area

The entire region used for the chart, axes, headings and so on. If the chart style is ∆boxed∇ (as in the diagram) a thick line is drawn around it. If you save the chart in EPS format, you will find that Word imports it at this size.

Plotting Region

The rectangle formed by the X and Y axes, stretching between the first and last tick marks in each direction. By default, Rain will leave this clear of all elements except plotted data, but you can choose to place the key here, or to add text notes after the plot is complete.

Margins

The area outside the plotting region. By default Rain leaves space for the Y≡axis on the left (with labels of up to 4 digits), the X≡axis and key at the foot, and a 1-line heading at the top. If you require longer labels or a deeper heading, you will probably need to adjust these settings with the ∆hmar∇ and ∆vmar∇ properties. These give the margins (measured in points = 1/72 inch) as shown.

Chart Heading

The main title for the chart. By default this is written centred at the top of the chart, but you can place it as required by setting the heading style.

Axis Captions

You can set captions for any of the X, Y and Z axes. You can also choose to have (short) Y-axis captions written horizontally at the end of the axis rather than up the side.

Axis Labels

These are written at each tick mark. By default, RainPro uses numeric labels, but you can scale, format, or over-ride these as required. You can also choose to have the X-axis labels written midway between tick marks, which is often suitable for weekly or monthly data.

Grid Lines

these are lightly-drawn horizontals and verticals which extend from the major tickmarks across the plotting region. By default, Rain uses light grey dotted lines for the grid but solid lines also look good in grey.

Baseline

This determines how barcharts and surface charts are shaded. You can leave the X-axis at the bottom and set a baseline part-way up the Y-axis to give the effect of bars which ∆hang∇ from a norm, or to shade above and below a standard setting.

Key or Legend

This is written (by default) across the foot of the chart, and shows a small sample of the colour / marker / fill style for each line or bar, with a short section of explanatory text beside it. You can place the key anywhere within the chart area or margins, and multiple charts may share a single key.

Value Tags

Scatter plots, piecharts and barcharts may be annotated with data values. For scatter plots these are simple numeric values written beside each data point, for barcharts you can choose to write them on top of each bar or just inside the bar, and for piecharts they will be written around the edge of the pie using radial ∆spider∇ tags from each segment.

Chart Notes

You can add free text (optionally boxed) anywhere within the chart area. Notes are positioned using the (x,y) coordinates of the last chart plotted, except for piecharts where the plotting region has a notional coordinate system of 0 – 100 in both directions.

Datum Lines

These are normally added after the plot is complete to mark important ∆cut off∇ lines, such as +/- 2 standard deviations on a control chart.


Rain graphics: A "Simple" Timeseries (the Playfair Plot)

A “Simple” Timeseries (the Playfair Plot)

This is a good place to begin – the chart we are going to build was first drawn in 1786 by William Playfair (⍋The Commercial and Political Atlas⍒, London), and was among the first recorded examples of statistical graphics. See Tufte ⍋The Graphical Presentation of Quantitative Information⍒ (page 65) for a splendid reproduction of the original chart.

In this first attempt to use a computer to reproduce this finely designed graphic, we will simply enter the data and let Rain take most of its default settings, with the addition of some simple headings and axis labels. Later on, we must re-visit the chart, and use some rather more sophisticated commands to get remarkably close to the spirit of the original.

Here are the charting commands which just plot the data:

 r←Playfair1;yrs;debt
⍝ First cut at classic Playfair chart from 1786
 yrs←1688 1701 1714 1727 1739 1748 1755 1762 1775 1784
 debt←0.2 1.3 3.2 2.4 2.1 3 2.2 4.8 4.4 9.2
 ch.Set'XYPLOT,BOXED'
 ch.Set'HEAD' 'First attempt at classic Playfair graphic'
 ch.Plot yrs,[1.5]debt
 PG←ch.Close

Note that all the setting up is done first. The graph is then drawn by ch.Plot and the result recovered by ch.Close PG is a simple text vector.

Here is the graph it draws ...

We hardly need to caption the time axis, but it might be sensible to explain the vertical dimension:

ch.Set 'ycaption' 'Millions of Pounds'

.... and possibly it would look better with the markers turned off and a lightly drawn horizontal grid:

ch.Set('style' 'nomarkers')('ystyle' 'grid')

which leaves the finished graph looking like this:


Rain graphics: Checkweigher Calibration

Checkweigher Calibration

This short article shows how easy it is to mix two quite separate chart types in the same plotting space, and using the same axes. It also shows you a little more of the formatting language, for example how to position headings and add notes to your finished graphic.

The data is typical of an experimental run of test packs over an automatic weigh-scale. Packs are made up at various exact weights and repeatedly passed over the scale (50 times in random order); the number of rejects at each weight is counted. A perfect device would reject everything below the set point, and accept everything above – but of course the edge is fuzzy and the 50% reject point is rarely where the dial says it is! In order to find the ‘safe’ set point so that no illegal packs are passed (with a pre-determined probability such as ‘no worse than 1 per 1000’) we need to model the data with a simple curve such as the logistic function. The chart shows how closely the computed function matches the data.

Here is the code which drew it:

 R←Checkweigher;PACK;EXP;FIT
⍝ VECTOR checkweigher example
 PACK←219+⍳13
 EXP←50 47 45 38 24 16 15 8 2 0 1 0 0
 FIT←50×÷1+*(PACK-224.48)÷1.31
 ch.Set('Style' 'cbar,boxed')('hmar' 60 36)
 ch.Set('Head' 'Fit of Logistic Curve;to Checkweigh Data')
   ('Key' 'Experimental Data,Logistic Fit')
 ch.Set('Hstyle' 'right')
   ('Xcap' 'Weight of Test Pack(g)')
   ('XLAB'('I3'⎕FMT PACK))
 ch.Set'Ycap' 'No of rejects (out of 50)'
 ch.Bar EXP ⋄ ch.Plot FIT
 ch.Note'Deduced Set weight = 224.48g;Uncertainty = 1.31g'(8 40)
 PG←ch.Close
 R←'View PG ⍝ to see it'

The new points to note in this example are the two plotting calls (ch.Barand ch.Plot and the addition of a note with ch.Note at position (8,40) after the plot has been drawn.


Rain graphics: Drawing a Population Pyramid

Drawing a Population Pyramid

The population pyramid is one of the commonest demographic charts, and can be programmed in Rain with two back-to-back horizontal barcharts. The final effect looks like:

This was drawn by the function Population in the RainPro workspace:

 R←Population;MAT;bands
⍝ Illustrate population pyramid (back-to-back horizontal bars)
 MAT←8 2⍴21 20,19 19,15 16,14 15,13 14,11 13,9 12,7 10
 bands←'0-9' '10-19' '20-29' '30-39' '40-49' '50-59' '60-69' '70+'
 ch.Set('STYLE' 'BOXED,hbar,cbar,relative,redraw')('xrange' ¯25 25)
⍝ Make a fat central pillar with a datum line!
 ch.Set('Ystyle' 'atend')('datum' 'solid,ne,broad')
 ch.Set('Vmar' 48 48)('gap' 0.2)('Xdatum' 0)
 ch.Set('HEAD' 'Population of Ruritania')('Ycap' 'Age band')('Xcap' 'Millions')
 ch.Set('ylab'bands)('Key' 'Male' 'Female')
⍝ Set ⎕FMT string for labels (kill -ve signs) - new facility at Jan 1998
 ch.Set('qfmt' 'M⍞⍞I6')
⍝ Test this with inside labels too!
 ch.Set('values'bands)('style' 'values') ⍝ ('vstyle' 'inside')
 ch.Bar MAT[;1]×¯1  ⍝ Go left young man!
 ch.Bar MAT[;2]     ⍝ Females to the right!
 PG←ch.Close
 R←'View PG ⍝ to see it'

Some things to note are:

  • Use of the ‘hbar’ style to get the bars drawn horizontally
  • The X-axis range is forced to ensure there is sufficient space for both charts
  • The central separator is drawn using a datum line
  • A format specification is set up so that the -ve signs are not shown on the left-hand chart

These are all useful tricks to note, and are very typical of the coding style you need when you are developing relatively complex charts which combine several data-sets on the same axes.


Rain graphics: Managing Multiple Plots

Managing Multiple Plots

When you want several plots sharing the same page, you have some design decisions to make:

  • is a simple tiled layout adequate?
  • do they share headings?
  • do they share a common key?

There are several examples to look at.

  • Sambars – four quite independent plots in a simple 2-by-2 grid
  • Intercepts – two quite different plots, independently positioned, but with a common key
  • Twopies – with a common heading, separate key
  • SmallMultiple – 12 miniatures, each showing a plane of some 3D data
  • Thumbnails – the examples used for the Rain Reference Card

Some things to note

If you want to box and title the entire set of charts as one (Twopies is a good example) you must do this first, and use ch.Nul to make an empty plot that just flushes out the ‘boilerplate’.

ch.Set 'heading' 'Several Charts'
ch.Set 'style' 'boxed'
ch.Nul

Now you can use ch.New x1 y1 x2 y2to define the plotting space for the first chart (note that points are used here, and that we are in an (x,y) system, not a (row,col) system ...

ch.New 0 0,72×5 3  ⍝ Convert from inches!

By default, RainPro will wipe the space for you with a white rectangle. Because piecharts are round (!) this prevents you from spacing them as close as you would like (the second one takes a nasty notch out of the first), so:

ch.Set 'box' 'nowipe'

comes to the rescue here.

RainPro also assumes that all the charts are to share a common key, so that whenever it encounters chSet ‘key’ ‘One,Two’ it simply adds it to the stack of key information to be output at the end of the plotting process by chClose. If you want to key each chart separately – see Thumbnails – then you must flush out the keys at the end of each section with chWriteKey Ð.

Often, the common key needs to be positioned outside any of the individual charts. The best example of this is probably Intercepts, which draw two overlapped charts and a boxed key in the lower right corner. This is done by adding:

 ch.New Ð   ⍝ default is entire plot region
 ch.WriteKey 80 20  ⍝ notional co-ordinates

at the end. This relies on the fact that RainPro establishes a default (x,y) co-ordinate system as (0,0)-(100,100) whenever you start a new chart. As soon as you plot something (the exception being a piechart) the co-ordinates become the axes of the graph you drew first within that plotting region. Keys are positioned (like notes) using this co-ordinate system.

See also ...

Making a Trellis of Small Plots | Trellis – trellis of small charts

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Four Barcharts on One Page

Four Barcharts on One Page

Anyone can plot graphs! One of the great strengths of Rain is its ability to combine several plots on the same finished graphs – see SmallMultiple for this idea taken to its logical conclusion.

This example is in the Rain workspace as Sambars – please take the code apart to see how it was done in detail.

 R←Sambars;MAT
⍝ Build set of 4 sample barcharts from MAT
 MAT←?5 3⍴36
⍝ ============== GROUPED BARCHART =============
 ch.New 0 154 205 308
 ch.Set('HMAR' 24)('HEAD' 'Here is a Simple Grouped Barchart;with a Displaced X-Axis')
 ch.Set('XLAB' 'York,Hfx,Nch,Ltr,Gls')('Hf' '8')('Yint' 20)
 ch.Bar MAT
⍝ ============== STACKED BARCHART =============
 ch.New 0 0 205 154
 ch.Set('STYLE' 'RELATIVE,CBAR,VALUES')('HMAR' 24)('HEAD' 'This is a Simple Stacked Barchart')('Hf' '8')
⍝ Angled X-labels at 25deg allow longer names (version 4.4)
 ch.Set('XLAB' 'York,Halifax,Norwich,Leicester,Glasgow')
 ch.Set('XS' 'Angled')('XA' 25)
 ch.Bar MAT
⍝ ============== FLOATING BARCHART =============
 ch.New 205 154 411 308
 ch.Set('STYLE' 'RELATIVE,FBAR,VALUES')('HMAR' 24)('HEAD' 'Here is a Floating Barchart;with Value Labels on the Bars')
 ch.Set('Values' 'York,Hfx,Nch,Ltr,Gls')
 ch.Set('YSTYLE' 'GRID,MTICK')('Hfont' '8')
 ch.Bar MAT
⍝ ==== OVERLAPPED BARCHART WITH DATUM ====
 ch.New 205 0 411 154
 ch.Set('STYLE' 'RELATIVE')('HMAR' 24)('HEAD' 'A Relative Barchart with overlapped bars;and Displaced Baseline')
 ch.Set('XLAB' 'York,Hfx,Nch,Ltr,Gls')('GAP' ¯0.5)
 ch.Set('BASELINE' 20)('Hfont' '8')
 ch.Bar MAT
 PG←ch.Close
 R←'View PG ⍝ to see it'

Some things which you might like to note are:

All measurements are in points (one point = 1/72 inch), and the default page size is 432 wide by 324 high. Astute (non-metric) readers will notice that this translates to 6” by 4.5”, and gives a proportion of exactly 4 wide by 3 high. If you simply want to divide the plotting space into for equal sections, you can ask APL to do the sums ...

 ch.New 0 0 .5 .5×4⍴432 324      ⍝ lower left
 ch.New .5 .5 1 1×4⍴432 324      ⍝ top right

... and so on.


Rain graphics: Making a Trellis of Small Plots

Making a Trellis of Small Plots

As we saw in the last example, it is possible within RainPro to place more than one chart on the page. To begin each chart, you use the command ch.New to declare the plotting region to be used, giving as right argument the co-ordinates of the bottom-left and top-right of the rectangle. The co-ordinate system works in points, with each point equal to 1/72” and with a default chart area of 6” by 4.5”. (Hence x co-ordinates vary from 0 to 432 and y co-ordinates 0 to 324.) So if you wanted to fill the plotting area with a 2 by 3 array of charts, then you would need the commands:

ch.New 144 162 288 324
ch.New 288 162 432 324
ch.New 0 0 144 162
ch.New 144 0 288 162
ch.New 288 0 432 162

separated by appropriate plotting commands for each of the six charts.

This is the job of the chart property ch.Set 'Trellis'. It automatically carves up the available space for you into a grid, and allows you to step from cell to cell with ch.NewCell as shown by:

ch.Set 'trellis' 2 3
⍎¨6⍴⊂'ch.NewCell ⋄ ch.Plot 1 2 3,[1.5]2 1 3'
View ch.Close

which gives you six identical scatterplots in each of the cells.

You can test this by constructing what S-PLUS calls a Trellis Graphics Chart. This is an attempt to deal with more than two-dimensional data by creating more than one chart as appropriate. There is a famous set of barley data, analysed by many statisticians from Fisher onwards. Here are just three of the lines of the barley data (there are 120 in all).

      ∆barley[⍳3;]
27     Manchuria  1931  University Farm
48.87  Manchuria  1931  Waseca
27.43  Manchuria  1931  Morris
      ⍴∆barley
120 4
      ⍴¨∪¨↓[1]∆barley
 114  10  2  6

The columns are yields of barley, type of barley (10 types), year of sowing (2 different years) and farms (six different farms).

Let’s plan to produce a 2 by 3 set of charts (one for each farm) with yield on the x-axis, type of barley on the y-axis, representing the different years by different markers.

The first small function we need (call it MultiScat) will produce scatterplots of x-y data using different symbols according to a third column.

     ∇ type MultiScat data;u;n;c
[1]   ⍝ Multiscatter (from Alan Sykes - APL99 tutor)
[2]    ch.Set'xyplot,nolines,marker'
[3]    n←⍴u←∪type
[4]    :For c :In ⍳n
[5]      ch.Plot(u[c]=type)⌿data
[6]    :EndFor
     ∇

Now we embed this in the function BarleyPlot which draws a single chart, with the varieties of barley on the y-axis (range 0 to 10 with tick-marks spaced 1 apart and with labels given by the names of the barley) and with x-axis of sufficient size to cope with the full range of the yields (10 to 70). The function uses as right argument the numbers 1 to 6 for each farm.

     ∇ BarleyPlot f;b;un;yield;type;year;farm
[1]   ⍝ barley plot for farm = f (1 to 6) (Alan Sykes from APL99)
[2]   ⍝ b is eventually a matrix of results for the farm
[3]   ⍝ cols=yield type year farm
[4]    ch.NewCell
[5]    b←∆barley ⋄ b←(((∪b[;4])[f])≡¨b[;4])⌿b
[6]    (yield type year farm)←↓[1]b
[7]    ch.Set('style' 'boxed')('head'(b[1;4]))
[8]    ch.Set'Vmar' 55 10
[9]    ch.Set('xrange' 10 70)('yrange' 0 10)('ytic' 1)
[10]   ch.Set('xcap' 'Yield')('key'(⍕¨∪year))
[11]   ch.Set'ylab'((⊂''),un←∪type)
[12]   year MultiScat yield,[1.5]un⍳type
[13]   ch.WriteKey ⍬
     ∇

Note that we have had to set an extra wide left-hand margin to leave room for the labels – the command ch.Set 'Vmar' 55 10 gives a vertical left-margin of 55 points. We have also included a key to indicate the years. Because we want this on all charts, it has to be ‘flushed out’ at the end of each individual chart.

This program can be run once, and viewed as usual by using the ch.Close command:

BarleyPlot 1
View PG←ch.Close

In this case, the call to ch.NewCell does nothing – there is only one cell! To produce all six charts:

ch.Set 'Trellis' 2 3
BarleyPlot¨⍳6
View PG←ch.Close

The interesting point to notice about the result is that for all farms except Morris, the yield for 1932 is greater than that for 1931 – a mistake in recording the figures? Apparently so!


Rain graphics: Positioning Small Plots on the Page

Positioning Small Plots on the Page

There are many possible techniques for representing high-dimensional data on a plane surface. One which is frequently used for geographically-based information is to use the xy co-ordinates of various survey sites (in the UK this data is easily determined from the National Grid) to position a miniature plot showing the data at that site. The RainPro workspace has a fairly complex example culled from the Proceedings of the Yorkshire Geological Society which shows alignments of various fossils in some Teesdale and Weardale quarries. Run function PYGS to see this plot:

You may find it hard to believe, but this is genuine data!

A simple example of the technique might be the relative frequency of various chemicals in a reaction vessel at different pressures and temperatures. Say we made three measurements of two compounds with (pressure,temperature) set to (100 30)(150 45)(75 60) – a simple xy-scatter will plot these values for us:

xy←3 2⍴100 30,150 45,75 60
ch.Set'boxed,xyplot,nolines'
ch.Set('xr' 50 180)('yr' 20 70)
ch.Plot xy
PG←ch.Close

Now what we need to do is to use these co-ordinates as the location for a set of small barcharts showing the detailed values measured at each point. Rather than setting up a trellis of equally sized and regularly spaced plots, we must tell Rain to record the xy locations in the scatter plot and to use these as the centres of a set of cell-locations:

⍝ Generate cells centred at the xy points
 ch.Set'xyplot,nolines,nomarkers,cells'

We might also want to adjust the default cell sizes in this case as the barcharts can be drawn quite large. Here is the complete example, with some randomly generated measurements:

 r←ScatterBar;xy;cell
⍝ Tutorial example with scattered barcharts
⍝ Illustrates the general technique of high-dimensional plotting
 xy←3 2⍴100 30,150 45,75 60
⍝ Generate cells at the xy points
 ch.Set'boxed,xyplot,nolines,nomark,cells'
 ch.Set'head' 'Cumulative Yields of Various Fractions'
 ch.Set'subhead' 'Charts show total amount of each collected'
 ch.Set('Ycap' 'Temperature')('Xcap' 'Pressure')
 ch.Set('xr' 50 180)('yr' 20 70)('cell' 144 96)
 ch.Plot xy
⍝ Force a full reset here to shake off headings etc from outer chart
 ch.Reset
⍝ Ensure the small charts don't blank out bits of the main axes etc
 ch.Set('style' 'forcezero,stacked,nowipe')
 ch.Set('gap' 0.5)('xlab' 'Ethanol,Propanol')('ycap' 'ml')('ys' 'atend')
⍝ Force them all to scale to the same y-axis for comparability
 ch.Set'yr' 0 40
⍝ Walk around the cells ...
 :For cell :In ⍳3
   ch.NewCell
   ch.Bar 2 3⍴3+?7 11
 :End
 ch.New'' ⋄ ch.Set'Key'('After 10 mins' 'After 20 mins' 'After 1 hour')
 PG←ch.Close
 r←'View PG'

Piecharts and polar charts work particularly well as miniatures, as they accurately locate the xy co-ordinate for you – see the PieMarkers example for some more ideas.

See also ...

ch.Polar – polar charts | CellSize – cell size when using markers to make cells

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Some Basic Statistics (Frequency Plot)

Some Basic Statistics (Frequency Plot)

Clearly, you can do simple statistical plotting with Rain – but this chart adds a little extra by interleaving two data sets (maybe one was “10% extra free”) to get a clear visual comparison.

The basic plotting code is quite simple, as the two histograms are interleaved automatically:

 R←Frequency;XX;YY
⍝ Test two-sample frequency plot
 ch.Set('Style' 'boxed')('Classint' 10)
 ch.Set('Head' 'Two-sample Frequency Plot')
   ('Key' 'Before,After')
 XX←?115⍴67 ⋄ XX←XX+?115⍴67 ⋄ XX←XX+?115⍴67
 YY←?115⍴72 ⋄ YY←YY+?115⍴72 ⋄ YY←YY+?115⍴72 ⋄ YY←YY+20
 XX←XX,[1.5]YY
 ch.Set'Xcaption' 'Randomly generated data ...'
 ch.Set('Ystyle' 'grid')('Patterns' 1 3)
 ch.Freq XX ⋄ BasicStats XX
 PG←ch.Close
 R←'View PG ⍝ To see it'

Have a closer look at BasicStats which does some enquiries about the current chart settings so that it can position the notes automatically. It also picks up the chart key (if any) and uses this.

You may like to skip this code and return to it later if you need to do this sort of thing!

 BasicStats  MAT;POS;DATA;MU;SD;M;STATS;lab;CT;KT;XT;YT;MI
⍝ Work out basic stats, then add to chart as a note.
⍝
 MAT←(2↑(⍴MAT),1 1)⍴MAT
 XT YT KT MI←ch.Query'XT' 'YT' 'KE' 'MI'
⍝ Add note to top left of chart space.
 POS←(0.5×+/2↑XT),(¯1↑YT),0
 STATS←'' ⋄ KT←(¯1↑⍴MAT)⍴KT
Loop:→lab←1+((¯1↑⍴MAT)⍴Loop),End,CT←1
⍝ Take cols one by one, and add to report
 DATA←MAT[;CT]~MI ⋄ →(⍴DATA)↓End
 MU←(+/DATA)÷⍴DATA
 M←(DATA-MU)*2 ⋄ SD←((+/M)÷⍴M)*÷2
⍝ Use key if available .....
 →(' '∧.=CT⊃KT)↓Key ⋄ →(1=¯1↑⍴MAT)↑Count
 STATS←STATS,'Population ',(⍕CT),': ' ⋄ →Count
Key:STATS←STATS,(CT⊃KT),': '
Count:STATS←STATS,'sample=',(⍕⍴DATA),', mean=',⍕4 ∆sigfig MU
 →(2>⍴DATA)↑Skip
 STATS←STATS,', range=',(⍕⌊/DATA),'-',⍕⌈/DATA
 STATS←STATS,', S.Dev=',(⍕4 ∆sigfig SD)
Skip:STATS←STATS,';'
End:→lab[CT←CT+1]
 →(⍴STATS)↓0
 ch.Note(¯1↓STATS)POS

The key function here is ch.Query which reports the current chart settings for any parameters you are interested in. It requires a vector of 2-element mnemonics, which match the initial two letters of the chart property names.


Rain graphics: How to Construct a Boxplot

How to Construct a Boxplot

The idea of a Boxplot is due to Tukey. He wanted a simple pictorial representation of one or more data sets highlighting (and contrasting) location and spread. The basic idea is that for each dataset, you require a box consisting of a top-half (bottom-half) which represents the 25% of the data between the median and the upper- (lower-) quartile respectively. On to each box, you can extend whiskers to indicate the range of the data. And if you want to be really sophisticated you can indicate extreme values.

Suppose that we have the following table:

 min  lq  med  uq  max
  20  35   40  60   80
   1  30   50  80   90
  10  30   35  40   95

then we can produce the boxplot in four operations:

  • draw the lower boxes using columns 2 and 3
  • draw the upper boxes using columns 3 and 4
  • draw the bottom whiskers using columns 1 and 2
  • draw the upper whiskers using columns 4 and 5

The first two operations use ch.Bar having set the option for bars to be ‘floating’. The last two operations require the use of ch.Vline using as the right argument a matrix each of whose columns gives the two y-values.

However we need to remember two important points: one is that in using the ch.Bar facility, the x-axis is automatically sorted out for us. Secondly, we cannot allow Rain to set the y-axis range as whichever graphics command we use first, it will not set the range to include the other values required. So the first step is to set the y-range.

ch.Set 'yrange' 0 100
ch.Set 'style' 'fbar'
ch.Bar 3 2⍴35 40 30 50 30 35

Add the companion line:

ch.Bar 3 2⍴40 60 50 80 35 40

Add the bottom whiskers:

ch.Vline 3 2⍴20 35 1 30 10 30

Add the top whiskers:

ch.Vline 3 2⍴60 80 80 90 40 95

and your box-plot is almost complete, save a heading and some labels for each boxplot.

ch.Set 'head' 'Trial Boxplot'
ch.Set 'yrange' 0 100
ch.Set 'style' 'fbar'
ch.Set 'xlab' 'Box 1,Box 2,Box 3'
ch.Bar 3 2⍴35 40 30 50 30 35
ch.Bar 3 2⍴40 60 50 80 35 40
ch.Vline 3 2⍴20 35 1 30 10 30
ch.Vline 3 2⍴60 80 80 90 40 95
View PG←ch.Close

This technique gives you total flexibility, and you can easily adapt it to show outliers, overlay extra information and so on. However if you are happy to let Rain do more of the work, you can have the quartiles computed for you by the supplied utility ch.Boxplot as follows:

ch.Set'head' 'Boxplot of Barley Data - Varieties'
ch.Set 'xs' 'angled'
ch.Boxplot ∆barley[;1 2]
View PG←ch.Close

This takes one of three possible slices though the barley data – try it with columns 1,3 and 1,4 also! Notice the use of angled X-labels to allow space for the rather long variety names here:

Data with multiple category axes

It is useful to be able to produce simple boxplots for a number of data sets or groups of data sets. The function ch.Boxplot does just this for you and takes care of the key and the labelling. To demonstrate this, here is a boxplot, where the groups correspond to the farms and the two boxes within a group correspond to the years – we are examining how the yields from the different varieties behave over the six farms and the two years.

ch.Set'head' 'Boxplot of Barley Data by Farm & Year'
ch.Set('ggap' 3)('xs' 'between,labmid,grid')
ch.Set'lfont' 'ti,6,neutral'
ch.Boxplot ∆barley[;1 4 3]
View PG←ch.Close

The second line has been inserted to widen the gaps between the farms to 3 times the box width, move the ticks between the groups and add vertical gridlines for clarity. The next line reduces the font size of the tick mark labels so that the farm names can be accommodated horizontally (otherwise every other farm label is missed out).

This simple boxplot also reveals the mistake alluded to in the Trellis example!


Rain graphics: 3D Charting

3D Charting

3D charts are very easy to do badly, and quite hard to do well! There are also many examples of 3D representations of essentially 2D data which do nothing other than hide the values and make it impossible to compare series accurately. Hence the functions in this section of Rain come with a health warning – use them to investigate genuinely 3D data by all means, but beware of towers and such unless your primary object is simply to make the output look pretty!

Tower Charts

The functions below are taken in order of ease of use, leaving until last ch.Cloud which is the real workhorse for genuine 3D charting. Towers are by far the simplest, as there are almost no settings to change and the data is a simple rectangular array. For example:

 ch.Set'Head' 'Standardised Test Scores'
 ch.Set('Ycap' 'Category')('Xcap' 'Pupil')('zcap' 'Score')
 ch.Set('zs' 'atend')
 ch.Set('GGap' 2)('cfont' 'ti,cyan,15')
 ch.Set'yl' 'Maths' 'English' 'Geography' 'Art'
 ch.Set'xl' 'Ian' 'John' 'Sean' 'Jon' 'Fred' 'Bert' 'Ally' 'Sue' 'Joan'
 ch.Set'Grid,walls'
⍝ Best to get the bigger numbers to the back!
 ch.Tower⊖+\+⍀?9 4⍴20
 PG←ch.Close

All the normal axis settings (ranges, tick spacing, captions) apply to the Z≡axis as you would expect. The gap between towers has been set here as twice the tower base using the Group Gap property. Note that you can only set gridlines globally here – the ‘grid’ axis style is ignored. By default, the data is arranged with the rows parallel to the X-axis and the columns retreating back into the page along the Y-axis. This means that a tower chart behaves exactly like a grouped barchart with each group of bars spread back into the Y-plane. You can set the viewpoint and perspective distortion if required, but the default settings work quite well for the majority of simple 3D charts.

Response Surfaces

As with the tower chart, this can take a simple rectangular array of data (z≡values) and draw it as a mesh surface above the XY plane. This looks best either with markers turned off completely, or with the small dots/spheres which are found as markers 9 – 15. Here is a simple array drawn as a mesh with marker 14 at the intersections:

This was drawn with the same function as the Tower chart, simply substituting ch.Resp for ch.Tower at the end and adding the marker setting. If you need to set the X and Y values explicitly, you can pass a 3≡element array giving a vector of X-values, a vector of Y-values and a matching rectangular array as before.

 ch.Set('style' 'grid')('marker' 14)
⍝ Best to get the bigger numbers to the back!
⍝ Distort axes to show non-linear mesh.
 ch.Resp(2*⍨⍳12)(0.5*⍨⍳9)(⊖12 9⍴⍳108)
 PG←ch.Close

This could be used to draw a fitted plane through a scatter of points in XYZ space, or just to illustrate the shape of an interesting maths function. The final possibility is to tile the surface, which has the effect of hiding the folded parts and giving a more solid feel to the remainder.

 ch.Set('style' 'walls,tiled')('Pattern' 2)('ls' 'flat')
 ch.Resp 2○0.2×(0,⍳24)∘.+0,⍳24
 PG←ch.Close

Cloud Charts (XYZ Scatter Plots)

The ch.Cloud function will plot arbitrary values in XYZ space, with the option of lines, markers, risers from the XY plane and filled surfaces to the XY plane or a given baseline. As is usual for charts plotted by Rain, the first call sets up the axes (auto-ranging if required) and subsequent calls plot further data against the same axes. This allows you a great deal of flexibility in drawing 3D data – see the example function Profile (in the Rain workspace) for some ideas.

In this case, you always give a 3-column matrix of XYZ triples, which will be plotted from the far back corner forward to ensure nearer points are drawn on top. A simple scatter-plot (Cloud1 in the RainPro workspace) is ideal for spotting clusters and anomalies in the data:

 ch.Set('style' 'grid,norisers,nolines')('Marker' 14)
 ch.Set('Xcap' 'Pressure in Bars')('Ycap' 'Temperature')('Zcap' 'Yield')
 ch.Cloud DATA

You can experiment with other options, such as ‘risers’ to see how they work with your data.

A second use of this function is to draw several sets of data (for example parallel time-series) as a set of independent plots against the same axes. Here is a simple example which loops across the columns of a set of invented timeseries:

 mat←+⍉↑0.8 ExpSmooth¨↓⍉?60 5⍴12
 ch.Set('HEAD' 'A Set of Shaded Planes')
 ch.Set('XT' 5)('YT' 1)('YR' 0 5)('ZS' 'forcezero')
 ch.Set'surface,grid,nomark'
⍝ Tallest first sets the Z-range!
 :For plane :In ⌽⍳¯1↑⍴mat
   ch.Cloud(¯1+⍳1↑⍴mat),plane,mat[;,plane]
 :End

Obviously you could equally well loop in the other dimension to plot surfaces parallel to the Y-axis. With careful choice of colours, patterns and markers it should be possible to construct most reasonable 3D charts with this function alone. You can then experiment with combinations, for example using a mesh surface to plot the regression result through the cloud of data points.


Rain graphics: Illustrating a Maths Function

Illustrating a Maths Function

This deceptively simple chart was drawn to illustrate the shape of the Logistic Distribution.

It is important for this kind of chart that the finished graphic accurately preserves the proportions of the original, so that circles stay circular, however you display or print them (see Circle for another example). Rain takes great care to ensure you have detailed control over the plotting space. Note the use of the Symbol font to get the Greek gamma character as a note.

In this case, I wanted a narrow plot to fit down the side of a printed page (note that when you export a plot as a .EPS file, Rain adds ∆BoundingBox∇ information so that your DTP software will get the shape right) and I did not need margins above or to the right.

 R←ASL91;PACK;FIT
⍝ VECTOR ASL example
 PACK←6+0.1×⍳120
 FIT←100×÷1+*(12-PACK)÷1.31
 ch.New 0 0 210 324 ⋄ ch.Set('Colour' 'neutral')('Nibs' 'broad')
 ch.Set('Style' 'Nomark')('Vmar' 48 0)('Hmar' 24 0)
 ch.Set'Hstyle' 'right'
 ch.Set('Xstyle' 'plain')('Xcap' 'z')
 ch.Set('Ytick' 50 100)('Ycap' 'Optical Density y')('Ylab' '0,0.5v,v')
 ch.Set('Cfont' 'TI,14')('Nfont' 'SY,14')('Lfont' 'TI,14')
 ch.Set('Xdatum' 60)('Ydatum' 50 100)
 ch.Plot FIT
 ch.Note'-g'(56 ¯4)
 PG←ch.Close
 R←'View PG ⍝ to see it'


Rain graphics: The Gilling East Rainfall Chart

The Gilling East Rainfall Chart

This chart explains the existence of the Rain workspace! It was devised in 1990 as an effective means of plotting the data from Richard Smith’s weather station (a suitable Christmas present for a 7-yr old), and drove the development of this graphics toolkit.

 R←Rain YR;DOM;MAT;TD;RN;HD;TOT;FULL
⍝ Build 'YR' rainfall graph from various bits
 DOM←LEAP YR ⋄ YR←⍕''⍴YR ⋄ RN←⍎'∆RAIN∆',YR
 TOT←DOM TOT∆MTHS RN ⋄ FULL←0≠TOT[12;2]
 ch.Set('STYLE' 'BOXED,NORISERS,VALUES')('HMAR' 36 60)('Xstyle' 'LABMID')('nstyle' 'opaque')
 HD←' Rainfall at Gilling East',FULL/';Annual Total =',(0⍕+/RN),'mm'
 HD←HD,FULL/' (',(1↓1⍕(+/RN)÷25.4),'in)'
 ch.Set'HEAD'('19',YR,HD)
 ch.Set('XLAB' 'Jan,Feb,Mar,Apr,May,Jun,Jul,Aug,Sep,Oct,Nov,Dec')
('XT'(0,+\DOM))
 ch.Set('Ystyle' 'GRID,ATEND')('YCAPTION' 'mm')('YTICK' 10 4)
 ch.Set('COLOUR' 'blue,neutral')('PATTERN' 1)
⍝ Draw completed months only ...
 ch.Set('YRANGE'(0,110⌈⌈/TOT[;2]))('YDATUM' 25.4)
 ch.Step(¯1↓1,⌽∨\⌽TOT[;2]>0)⌿TOT
 →FULL↑Daily
⍝ Rule off at latest data, and mark as 'Today' ....
 TD←(cal∆code'TODAY')-¯1+cal∆code'1 1 ',YR
 ch.Set'datum' 'cy,DD,FINE'
 ch.Set'XDATUM'TD ⋄ ch.Note'Today'((TD-2),95 90)
Daily:MAT←(⍳⍴RN),0,[1.5]RN
 ch.Set'STYLE' 'XYPLOT'
 ch.Vline(MAT[;3]>0)⌿MAT
Exit:PG←ch.Close
 R←'View PG ⍝ to see graph for 19',YR,' rainfall'

Note the calculation of the number of days in the month, and the use of this to place the X-axis tick marks correctly. Another unusual feature is the computed datum line at ‘Today’ which is written vertically up the line.


Rain graphics: Playfair Revisited

Playfair Revisited

Now we can have another go at the Playfair data, and produce something very close to the 1786 original. This is actually quite a hard graphic to draw, as it has irregularly-spaced X-ticks, vertically aligned notes, and the axis is at the ‘wrong’ side. Few commercial graphics tools come close, and yet you will find that the combined power of APL and Rain handle the challenge with some aplomb!

Here is the APL code to draw this ...

 r←Playfair;mat
⍝ Copy of classic Playfair chart from 1786
 mat←2 10⍴1688 1701 1714 1727 1739 1748 1755 1762 1775 1784,0.2 1.3 3.2 2.4 2.1 3 2.2 4.8 4.4 9.2
 ch.New 0 0 432 300
 ch.Set('style' 'XYPLOT,ROWS,BOXED,NOMARK,SURFACE,GRID')('VMAR' 12 24)('HMAR' 36 24)
 ch.Set'Ystyle' 'RIGHT'
 ch.Set('Hfont' 'GAI,12')('Lfont' 'GA')
 ch.Set('Grid' 'solid,fine,NEUTRAL')('Datum' 'medium,solid,neutral')
 ch.Set('XTICK'(mat[1;]))('YRANGE' 0 20)('YTICK' 1)
 ch.Set('WIDTH' 'MEDIUM')('PATTERN' 1)
 ch.Set'HEAD' 'Interest of the NATIONAL DEBT from the Revolution'
 ch.Set('YDATUM' 10)
 ch.Plot mat
⍝ Now annotate it ...
 ch.Set'Nfont' 'ne,GABI,12'
 ch.Note'INTEREST OF NATIONAL DEBT.'(1720 0.6)
 ch.Set'Nfont' 'GAI,9'
 ch.Note'The Bottom Line is Years, those on the Right Hand Millions of Pounds'(1710 ¯2.5)
 ch.Set('Nfont' 'GAI,6,red')('nstyle' 'opaque')
 mat[2;]+←0.5 ⋄ mat[1;]-←0.5 ⋄ mat⍪←90
 ch.Note'Revolution'(mat[;1])
 ch.Note'Accession of Queen Anne'(mat[;2])
 ch.Note'Accession of George 1st'(mat[;3])
 ch.Note'Accession of George 2nd'(mat[;4])
 ch.Note'Beginning of Spanish War'(mat[;5])
 ch.Note'End of Spanish War'(mat[;6])
 ch.Note'Beginning of Continental War'(mat[;7])
 ch.Note'End of Continental War'(mat[;8])
 ch.Note'Beginning of American War'(mat[;9])
 ch.Note'End of American War'(mat[;10])
 PG←ch.Close
 r←'View PG  ⍝ to see it'

Note the use of Garamond Italic for the titles and notes. You should refer to Setting up Custom Fonts for more information on adding your favourite PostScript and TrueType fonts to the available list.


Charting Reference

This section lists all the chart-creation functions alphabetically by function name. Each call is shown with a small sample graph ⍎ to see the source-code for any of these, please run the Thumbnails example.

chbar | ch.Bar – barcharts
chboxplot | ch.Boxplot – box and whisker charts
chbubble | ch.Bubble – bubble chart
chcloud | ch.Cloud – 3D scatter plots
chcontour | ch.Contour – contour plot
chdial | ch.Dial – dial and gauge charts
chgantt | ch.Gantt – project plans
chhistogram | ch.Histogram – simple histograms
chmultiple | ch.Multiple – small multiples
chnul | ch.Nul – flush output with no chart
chpie | ch.Pie – piecharts
chplot | ch.Plot – line graphs
chpolar | ch.Polar – polar charts
chresp | ch.Resp – response surface plots
chscatter | ch.Scatter – x/y scatter plot
chstep | ch.Step – step charts
chtable | ch.Table – table charts
chtower | ch.Tower – tower charts
chtrace | ch.Trace – trace charts
chtriangle | ch.Triangle – triangle plots
chvenn | ch.Venn – Venn Diagrams
chvectors | ch.Vectors – vector fields
chvline | ch.Vline – Hi-Lo plots
chxbar | ch.Xbar – bar charts with a defined x-axis
FNX | Other Functions
Prp | Chart Properties
Events | Chart Events
Styles | Chart Styles


Rain graphics: ch.Bar – barcharts

ch.Bar – barcharts

Accepts an array of numbers and plots a barchart according to the current settings.

ch.Bar mat

Properties Styles Style summary

The axis is always uniform, and is unlabelled unless you set the axis labels explicitly. If you need to position the bars in the x-direction, use ch.XBar instead.

Default (grouped) barchart

BMAT←3 2⍴2 1 6 4 8 10
ch.Set('style' 'Boxed,ForceZero,Values')
ch.Set('Head' 'Barchart')('Key' 'First,Second')('Xlab' 'UK,Europe,Export')
ch.Set'kstyle' 'boxed,vertical'
ch.Bar BMAT ⋄ ch.WriteKey 0.75 9
PG←ch.Close

The default barchart style (multiple bar or 'grouped' is shown here. A table (array of arrays) is taken to represent categories of data, with one reading per row, or you can use a category variable to split data from a database table. The bars are plotted in groups, with extra space between each group. Use the gap and groupgap properties to change the spacing.

Stacked barchart

ch.Set('style' 'Boxed,ForceZero,Relative,Stacked,Values')('Head' 'Stacked Bar')
ch.Set('Ycap' 'Share')('Ystyle' 'Atend')('Key' 'First,Second')('Xstyle' 'Plain')
ch.Set'Values' 'UK,Europe,Export,Other'
ch.Bar BMAT
PG←ch.Close

This is a composite barchart, with relative data. The bars are plotted as a stack, with automatic accumulation of the values. To omit the bottom bar of each stack, include the keyword ‘floating’ in the chart style.

Horizontal barchart

ch.Set('style' 'Boxed,ForceZero,Relative,hbar,cbar')('Head' 'Horizontal Bar')
ch.Set 'mleft' 32
ch.Set'YLab' 'UK,Europe,Export,Other'
ch.Bar BMAT
PG←ch.Close

This illustrates a typical horizontal barchart, in this case drawn as a composite bar. In general you will need to increase the left-hand margin to allow space for the bar labels. The grouped and floating styles also work as you would expect. If you use value-labels on horizontal bars they are drawn at the left/right end of the bar depending on which direction the bar is drawn from the Y-axis or baseline. See the Population example in the collection of barcharts.

See also ...

Four Barcharts on One Page | ch.Xbar – bar charts with a defined x-axis | Barchart style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Boxplot – box and whisker charts

ch.Boxplot – box and whisker charts

RainPro supports box and whisker charts on datasets with one or two category axes.

ch.Boxplot boxdata

Properties Styles

Examples

ch.Boxplot ∆barley[;1 3]

The first column gives the values, the second (and optionally third) items give the categorisation.

If there are two defined categories (the data is presented as a 3-element array or 3-column matrix the grouped barchart parameters are used to set the gap between bars and the gap between groups.

ch.Boxplot yield farm year

See the sample function Boxplot in the Rain workspace and the tutorial topic Boxplot for more information.

Working with tabular data

If the data has already been collected in categories you can simply pass an array of arrays of values here. If there are more than 3 columns, there is no ambiguity and the columns are simply treated as categories of data. If there are 2 or 3 columns, then you must use style ‘tabular’ to have them treated this way.

See also ...

Boxplot Style


Rain graphics: ch.Bubble – bubble chart

ch.Bubble – bubble chart

This chart is a variant of the standard ScatterPlot with the size of the markers used to show an extra dimension in the data. The third argument gives the required marker area (typically the number of incidents recorded at a certain location) and all the markers are automatically scaled to cover the range of areas given.

ch.Bubble ydata xdata scale

Properties Styles

Any marker may be used here (including user-defined markers) but simple solid circles are probably best. If a modelfit is chosen, the points are automatically weighted by the given z-values.


Rain graphics: ch.Cloud – 3D scatter plots

ch.Cloud – 3D scatter plots

This is the workhorse function of Rain’s 3D plotting capabilities. It can generate simple 3D scatter diagrams, straw and ball charts, multiple cross sections with optional risers and filled surfaces.

ch.Cloud mat

Properties Styles

Examples

 MAT←⊖+\+⍀?5 3⍴36
 ch.Set('Style' 'risers,nolines,grid')('Marker' 14)
⍝ Note that the XYZ needs a 3-column matrix
 ch.Cloud(3/⍳5),(15⍴⍳3),[1.5],MAT

The data to be passed is a simple 3-column matrix giving X, Y and Z values. Multiple sets of data may be plotted by repeated calls to ch.Cloud having set the axis ranges in advance. The usual settings for markers and lines apply, and ‘risers’ may be set to produce ‘straw and ball’ plots with verticals rising from the XY plane to each point.

If more than 3 columns are given, columns after the first two are treated as independent sets of z-values, and drawn using the current colour and marker cycles. This allows statements like:

ch.Cloud yield vs variety farm by year

to make a multiple scatter of the barley data.

See also ...

ch.Resp – response surface plots | Cloudchart Style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Contour – contour plot

ch.Contour – contour plot

Draws a contour plot from 3 arrays giving x,y,height data.

ch.Contour X Y Z

Properties Styles

Contour plots are often an excellent alternative to 3D presentations where the object is to model three-dimensional data. Obviously, they can be used ‘just like a map’ where you may have a set of spot-heights (z-values) at various locations on the xy-plane. In this case, there is no particular shape assumed for the landscape, and the contours would simply be drawn to give the best ‘smooth interpretation’ of the recorded heights.

Another good use of contour plots is to fit some kind of model to the results from any experiment where two factors are systematically altered, and a third one is measured. In this case, the contours represent the model (they will simply be angled lines if the model is linear in both x and y directions) and make it very easy to read off the predicted result for any combination of input variables.


Rain graphics: ch.Dial – dial and gauge charts

ch.Dial – dial and gauge charts

Accepts a scalar or vector of numbers and plots a ‘fuel gauge’ style plot. Would normally be used with a simple scalar value to show a single pointer, with suitable warning zones.

ch.Dial 23

Properties Styles

Examples

 ch.Set ('head' 'Simple Pointer and Scale')
 ch.Set('axes' 'Black,solid,2')('lfont' 'arb,12')
 ch.Set('nib' 2)('line' 'solid')
 ch.Set('xr' 0 30)('xt' 10)
 ch.Dial 17)
 PG←ch.Close

You can use the style ‘arrowed’ to add an arrowhead, and the XZones property to set one or more coloured bands. Set the style to ‘wedge’ to have the warning zone drawn as a complete sector – the default is ‘annular’.

Several pointers can be created if required – the standard colour, line and nib cycles are used to generate each in turn. Also the Radii property may be used to make a secondary pointer shorter, as in the example below:

 ch.Set('style' 'arrow')('nib' 2 1.2)('line' 'solid')('radii' 100 50)
 ch.Set('xr' 0 100)('xt' 20,3)('xzones' 'lime,0,10' '#F99E0F,40,70' 'Red,70')
 ch.Dial 25 56

The sample chart shows some of the possibilities, laid out as a neat dashboard.

See also ...

Dialchart Style | Radii – pie sector radii and Dial pointers | XZones – warning regions for X-axis | ZoneAttributes – for warning bands

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Gantt – project plans

ch.Gantt – project plans

This chart is typically used to print project information or production schedules. It usually has a time-based x-axis and various resources plotted vertically on the y-axis.

ch.Gantt schedule

Properties Styles

Example

MAT←?15 2⍴4+⍳6
ch.Set('Style' 'Boxed,values')('Head' 'Gantt Chart')('Yrange' 0 5)
ch.Set'Values' 'Cut' 'Mill' 'Grind' 'Polish'
ch.Gantt(⍳4),MAT[1 2 3 4;]
PG←ch.Close

It takes a 3-column matrix with Y values in col-1, X-Start/X-End in 2,3. The value labels may be drawn inside the bars or just above using vstyle 'ontop' The bars are sized by default to accommodate the current value-label font. The ‘barwidth’ setting over-rides this.

See also ...

Barchart style | BarWidth – bar width for X-bar and Gantt

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Histogram – simple histograms

ch.Histogram – simple histograms

Accepts a vector of numbers and groups into class intervals as a frequency plot with optional bellcurve overlay.

ch.Histogram vec

Properties Styles

Example

ch.Set('Style' 'Boxed')('Head' 'Frequency Plot')
ch.Set 'classint' 5
ch.Histogram 0.05×(+/?200 20⍴100)
PG←ch.Close

The class interval defaults to 1, but will be increased automatically to keep the total number of ‘buckets’ below 40.


Rain graphics: ch.Multiple – small multiples

ch.Multiple – small multiples

Multiple plots are a very effective way of viewing high-dimensional data on a flat sheet of paper. Effectively this function automates the process of setting up a trellis and looping around it cell by cell.

ch.Multiple data

Properties

Examples

ch.Set('type' 'boxplot')
ch.Multiple yield by farm year
PG←ch.Close

The chart type must be one of the standard RainPro charting functions, such as ‘Scatter’ or ‘Bar’ or ‘Frequency’. The call to ch.Multiplesimply sets up a trellis with one cell for every unique value in the ‘by’ variable (the category variable) and loops around these values, plotting one chart in each cell. For every plot type except Frequency, it will autorange the data at the start, to ensure that all the plots are ranged the same. For Frequency plots you should set the Y-range and class-interval explicitly before you run the multiple, if you want all your miniatures to be ranged consistently.

ch.Set ('type' 'freq')('yr' 0 30)('xr' 10 70)('Classint' 10)
ch.Multiple yield by year
View ch.Close

You can set the trellis-style to ‘snaking’ to have the plots work down the columns rather than across, and you can also set ‘paged’ which simply puts each plot on a separate page.

See also ...

Trellis – trellis of small charts | TrellisStyle – trellis style | TypeOfChart – chart type

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Nul – flush output with no chart

ch.Nul – flush output with no chart

It is sometimes useful to generate headings or notes without actually plotting a chart.

ch.Nul

Properties

Example

Typically you would use this (see Twopies in the collection of multiple charts) when several small charts share the same screen, but you want them all under one heading.

ch.Set ('hstyle' 'left')('Head' 'Two Piecharts;to follow')
ch.Nul

It can also be used (see Intercepts in the collection of multiple charts) when two separate charts share a single key.


Rain graphics: ch.Pie – piecharts

ch.Pie – piecharts

Accepts a numeric vector or list of vectors and plots a piechart or trellis of small piecharts.

ch.Pie 6 4 3 1

Properties Styles

Examples

BMAT←3 2⍴2 1 6 4 8 10
ch.Set('Style' 'Boxed')('Vmar' 6 0)('Hmar' 0)('Head' 'Pie;Chart')('Hstyle' 'left,bottom')
ch.Set('Xlab' 'UK and;Ireland,France,Spain,Norway,Greece,Italy')('Explode' 0 0 0 20)
ch.Pie(,BMAT)[⍒,BMAT]
PG←ch.Close

If you set X-labels (as above) or set the keys and use style ‘spider’, spider tags are used to arrange the labels radially around the pie.The data values will be appended to your labels if you set the ‘values’ style. To place the labels in a separate key, use ch.Set 'key' 'One,Two,Three'instead. You can also explode segments selectively or change the radius of each segment. Multi-line text is supported in the spider tags, but not in the key.

Plotting a collection of small pies

To plot a matrix of data as a collection of small pies, set up the headings as normal, and pass a simple numeric matrix with one row per pie. Alternatively you can pass a vector of numeric vectors, which may be convenient if the pies have different numbers of segments. By default, the cells in the trellis are used from left to right – to work down the columns set the trellis-style ‘snaking’ before making the pies.

In this case, the ‘xlabels’ will be used to label each small pie in the lower left corner using the subhead font and the keys are used as the spider tags (or a conventional key if you leave out this style).

See also ...

Piechart Style


Rain graphics: ch.Plot – line graphs

ch.Plot – line graphs

This will accept numeric data as a simple vector, a vector of vectors, or a matrix and plot a linegraph (timeseries).

ch.Plot linedata

Properties Styles

Examples

MAT←?15 2⍴4+⍳6
ch.Set('Style' 'Boxed,Nomark')('Head' 'Line Graph')('Key' 'First,Second')
ch.Set('YStyle' 'ForceZero')('Ytick' 2 1)
ch.Plot MAT
PG←ch.Close

In the case of a vector of vectors, each item is padded with the current missing value before the data is plotted.

In the case of a matrix, the chart style determines whether the data is expected in columns (the default) or in rows.

The default is to take a matrix as a set of Y-values and plot them all as lines against a uniform X-axis. This is suitable for most timeseries data. If the X-values are also irregular, you may pass them as the first column, and call ch.Set 'XYplot'to get the desired effect. Alternatively use the versus property to establish the X-variable.

See also ...

ch.Scatter – x/y scatter plot | Linegraph Style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Polar – polar charts

ch.Polar – polar charts

This is effectively a ‘wrap-around’ version of the normal line-plot. It can be used for data which is intrinsically directional (such as frequency of wind directions) or to compare several items on multiple categories.

ch.Polar values

Properties Styles

Examples

Here is an example from the Proceedings of the Yorkshire Geological Society showing how fossil corals were aligned to the prevailing current directions [PYGS 52.4 p.358]:

 ch.Set'boxed,nomarkers,surface'
 ch.Set('head' 'Coral;alignments;at Greenfield')('Hstyle' 'Left')
 ch.Set('ystyle' 'grid,forcezero')('vm' 8)('pattern' 4)
 ch.Set('xstyle' 'grid')('yr' 0 25)  ⍝ 30 degree radii
 ch.Polar 10 15 15 25 15 25 10 15 15 25 15 25
 PG←ch.Close

In this example, you can omit the X-tick setting as the default is to make tick marks at each data point. An example which compares two (imaginary) cars on 7 criteria shows this:

ch.Set'boxed,forcezero,grid'
ch.Set('head' 'Cars;compared')('Hstyle' 'Left')('vm' 8)
ch.Set'xlab' 'Speed,Fuel,Comfort,Reliability,Safety,Seating,Service interval'
ch.Set('Key' 'Volvo' 'Saab')
ch.Polar 18+?7 2⍴24
PG←ch.Close

Finally, you can use the ‘risers’ style to join each point to the centre. If you omit the lines and use arrowheads and risers, this works very well as a simple radial frequency plot:

ch.Set'boxed,nolines,risers,arrows,forcezero'
ch.Set('head' 'Frequency of;wind direction;in Gilling')('Hstyle' 'Left')
ch.Set('nib' 0.8)('vm' 4)('ystyle' 'noax')('xstyle' 'noax')('astyle' 6 30)
ch.Polar 4+?8⍴9
PG←ch.Close

All the normal axis and style settings apply as you would expect. If you use the ‘surface’ style with cumulative values, you will need to be careful to draw the outer data first. Note that the X-labels are always written radially around the circumference. You cannot use the ‘Intercept’ property here to move the axis positions – the Y-axis is always drawn to the 12-o’clock position, and the X-axis is always drawn around the outside. You may use the ‘background’ colour to fill the circle edged by the X-axis.

See also ...

Polarchart Style


Rain graphics: ch.Resp – response surface plots

ch.Resp – response surface plots

This type of plot works with a simple rectangular array of height data, and plots it on a regular x,y co-ordinate system. It is best used to illustrate the shape of mathematical functions.

ch.Resp surface

Properties Styles

Example

 MAT←⊖++⍀?5 3⍴36
 ch.Set('Pattern' 1)('Style' 'grid,tiled')
 ch.Set('XL' 'York,Hfx,Tby,Ltr,Gls')('Hfont' '8')('YL' 'Last,This,Next')
 ch.Resp MAT

You can also call this with a three-element nested vector giving:

(X-values)
(Y-values)
(XY matrix of Z-values).

Clearly the lengths must match correctly if you do this.

If you tile the surface, markers are automatically cancelled. Otherwise you have the usual choice of markers and line-styles – markers 14 and 15 (the 3D-effect circles) look good at the mesh intersections.

See also ...

Response Surface Style


Rain graphics: ch.Scatter – x/y scatter plot

ch.Scatter – x/y scatter plot

This function is almost equivalent to calling ch.Plothaving set a ‘versus’ property. However it makes for more readable code, and can additionally handle category data on the Y-axis.

ch.Scatter data

Properties Styles

Example

ch.Set 'Head' 'XY Scatter Plot'
ch.Set('Ycap' 'Age')('XCAP' 'Weight')
ch.Scatter MAT
ch.Scatter (6 5 4 2)(9 6 7 8)

It automatically turns on markers and turns off lines. If you call it with a text variable, the (sorted) unique values will be used to label the Y-axis and the current value of the ‘versus’ property will be used to generate the X-axis.

See also ...

ch.Plot – line graphs | CategoriseBy – category variable | Scatterplot Style | Versus – scatter versus this

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Step – step charts

ch.Step – step charts

Accepts an array giving the step points (e.g. month ends) and the Y-value at the top of each step.

ch.Step values

Properties Styles

Examples

ch.Set('Style' 'Boxed,Risers')('Head' 'Step Chart')('NStyle' 'Boxed')('Hmar' 14 18)
ch.Set('XStyle' 'Labmid')('Xlab' '0-9,10-20,21-35,36-50,51-70,71+')('Xtick' 0 10 20 35 50 70 100)
ch.Step(0 10 20 35 50 70 100)(12.5 14 30 28 12.5 3)
ch.Note'A note;is here!'(70 30)
PG←ch.Close

See the various Rainfall charts for examples of use. This may also be used with style ‘floating’ to draw a simple stepped line, suitable for interest-rate charts.

The Interest example hows the effect.

See also ...

Stepchart style


Rain graphics: ch.Table – table charts

ch.Table – table charts

Accepts an array of numbers and plots a table according to the current settings.

ch.Table mat

Properties Styles

The table chart may be used on its own to tabulate data (the above example is a typical CrossTab using the ‘GroupBy’ and ‘CategoriseBy’ settings). However it is most likely to be used in adding summary information to another chart, for example a correlation table to a scatterplot.

The current setting for YLabels is used for the row stubs, and the XLabels make the column titles. To label the top-left cell, set the YCaption. The usual font settings apply to the caption and both sets of labels, and you may control the appearance of the cell values with the ValueFont and Value picture format.

The Column titles may be spanned across more than one cell with Style ‘spanned’. In this case, any non-null headings will be centered across their own cell and any null cells to their right. Column titles and row stubs may be multi-line (passed using arrays of arrays or split with ‘;’) or may be wrapped automatically with the Label Format picture for the appropriate axis.

See also ...

Table Style | Table position – xpos,ypos,optional width

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Tower – tower charts

ch.Tower – tower charts

Tower charts are effectively grouped barcharts where the groups have been separated into parallel rows of equally-spaced bars. It is obviously necessary to present the data with the higher bars towards the back (the right-most columns) as otherwise data can be completely hidden behind more nearby towers.

ch.Tower mat

Properties Styles

Example

 MAT←⊖+\+⍀?5 3⍴36
ch.Set'walls,grid'
ch.Set('XL' 'York,Hfx,Nch,Ltr,Gls')('YL' 'Last,This,Next')('mg' 8 8 8 8)
ch.Tower MAT
PG←ch.Close

The data is a simple table (array of arrays) giving groups of towers. Each group is plotted parallel to the Y-axis, using a standard set of shading patterns and the colour rotation you request. The tower spacing is controlled by the group-gap property. All the usual settings (axis captions and so on) apply to all three axes.

See also ...

Towerchart Style


Rain graphics: ch.Trace – trace charts

ch.Trace – trace charts

This is a special chart type which plots a matrix of data on a set of equally-spaced parallel lines, like a seismograph or ECG trace.

ch.Trace mat

Properties Styles

Examples

ch.Set('style' 'boxed,nolines,nomarkers,xyplot')
ch.Set'key' 'Temperature in ∘C'
ch.Set'grid' 'solid,NE'
ch.Set('hmar' 54 36)('ylab' 1 2 3 4)
ch.Set('head' 'Temperature Data from Iceland Field-study')('ycap' 'Probe')('xcap' 'time')('xtic' 1 1)('xs' 'date,grid')
ch.Set'nomarkers,lines'
ch.Set('is' 'xtic')('if' 'he,4,green')
ch.Trace(∆dt+∆hm),∆log[;1 2 3 4]
PG←ch.Close

This allows for surface-fill (ideal format for plotting resource-utilisation) and ‘kite’ styles (used for pollen diagrams, see Kite for an example).

 mm←6 12⍴0
 mm[1;]←12↑0 0 1 2 2 3 3 3 2 1 1  ⍝ Oak
 mm[2;]←12↑0 0 0 0 1 1 1          ⍝ Ash
 mm[3;]←12↑0 1 1 1 2 2 2 2 2 2 1 1 1 ⍝ Birch
 mm[4;]←12↑0 1 1 2 2 2 1 0        ⍝ Hazel
 mm[5;]←12↑0 0 0 0 0 0 0 1 2 2 2 2  ⍝ Lime
 mm[6;]←12↑0 1 1 1 2 3 3 3 3 2 1  ⍝ Elm
 ch.Set('head' 'Sample Kite Chart')
 ch.Set('yc' 'Species')('ys' 'atend,grid')('yl' 'Oak,Ash,Birch,Hazel,Lime,Elm')
 ch.Set'Xcap' 'Metres from Shoreline'
 ch.Set('style' 'rows,kite')('pattern' 4)
 ch.Set'is' 'xtick'
 ch.Trace mm
 PG←ch.Close

Currently this supports horizontal charts only. Note the addition of a logical ‘Inner’ axis so you can set ‘inner style/range/intercept’ and so on for the repeated small numbers which go with each line. The properties you may change are:

  • IS – inner style sets the tickmark type as for normal axes
  • IL – inner labels can be used to label each inner major tickmark
  • IF – sets the font for the inner-axis labels
  • IR – ranges the inner axis (all copies will be ranged the same)
  • IT – sets the tick intervals (major ticks only here)
  • II – sets the intercept value where the inner axis is drawn
  • IA – sets the ‘allowance’ (default 0.8) as a fraction of the space between adjacent trace lines (determined by the major Y-ticks). This may be set to a value >1 if you have a set of lines which move along very nearly parallel to one another. However this only works well with a plain inner axis as otherwise the ticks and labels collide.

See plots Iceland and Iceland2 in the linechart examples to compare a conventional series with the trace.

See also ...

IRange – inner-axis range | ITickMarks – inner-axis tickmarks | IZones – inner-axis zones | Tracechart Style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Triangle - triangle plots

ch.Triangle – triangle plots

This is a special chart type to plot the relative value of 3 sets of observations. It is much used in geology and chemical engineering.

ch.Triangle samples

Properties Styles

Examples

 samples←(97 32 66 25 15 43 24 6 37 19)(13 63 63 48 9 15 16 17 26 46)(20 13 81 39 98 97 89 8 14 95)
 ch.SetMargins 36 36 10 10     ⍝ Symmetric LR makes sense here
 ch.SetCaptionFont'ti,12,Navy'
 ch.SetXCaption'Scissors'
 ch.SetYCaption'Paper'
 ch.SetZCaption'Stone'
 ch.SetStyle'grid,markers,halo'
 ch.SetMarkers 15
 ch.Triangle samples

This is a typical plot where the incidence on each axis must sum to one.


Rain graphics: ch.Venn – Venn Diagrams

ch.Venn – Venn Diagrams

Accepts a vector of numbers and draws a Venn diagram

ch.Venn p1,p2,overlap

Properties Styles

This draws a correctly proportioned chart for the two circles and overlap. You may also pass an array of 7 numbers, giving the values for 3 circles and the 4 overlap possibilities. In this case a simple cloverleaf diagram is drawn, as it is not possible to draw the diagram with simple shapes and have all the areas proportioned correctly.

Use the XLabels to caption each of the 3 regions, or Value tags if you prefer to have the legend written inside each region. Alternatively, you may use the Legend to key each circle (2 or 3 legend entries depending on the number of circles).


Rain graphics: ch.Vectors - vector fields

ch.Vectors – vector fields

This plot can be used for vector fields (current flows drawn on a map) or for any kind of directed graph involving nodes and connections.

ch.Vectors xyxy

Properties Styles

Description

The typical data structure is a 4-column matrix giving xyxy pair for the ends of each arrow. The data may also be passed as an array of 4-element arrays or (if data-style is set to ‘Rows’) as 4 vectors giving the (x1 y2 x2 y2) values.

By default the lines are undecorated, but you can choose to have arrowheads drawn on the ‘target’ end of the line or markers on either end (or both). This allows many variations on simple directed graphs, and network diagrams such as PERT charts.

Value tags are written along the vector, centred above the lines.

See also ...

Vector plot style


Rain graphics: ch.Vline – Hi-Lo plots

ch.Vline – Hi-Lo plots

This is a specialised plot for ranged data such as max-min temperatures, error-bars on scientific plots or ‘Hi-Lo-Close’ plots of market data. It expects a 2-column table giving the two Y-values to draw a vertical line between. If you omit the second column, it will draw lines down to zero from the Y-values in column-1.

ch.Vline minmax

Properties Styles

Examples

MAT←?15 2⍴4+⍳6
ch.Set('Style' 'Boxed')('Head' 'Vline Plot')('Key' 'Hi-Lo,Close')
ch.Vline MAT
ch.Set('Mark' 3)('mscale' 3)('Style' 'nolines,markers')
ch.Plot 0.5×+/MAT
PG←ch.Close

To plot the closing values (as shown here) simply overlay an XY plot with markers, but no lines.

See also ...

Min-Max Style


Rain graphics: ch.Xbar – bar charts with a defined x-axis

ch.Xbar – bar charts with a defined x-axis

The conventional barchart is drawn with an entirely arbitrary x-axis. Sometimes it is convenient to specify exactly where on the axis the bars should be placed, and how wide each bar should be. This function always takes a matrix of data and treats the first column as x-values.

ch.Xbar mat

Properties Styles

Example

BMAT←3 2⍴2 1 6 4 8 10
ch.Set('style' 'Boxed,ForceZero,Relative')('Head' 'X-axis Barchart')
ch.Set'subhead' 'Requires X-values in 1st Column'
ch.Xbar 2 5 6,BMAT
PG←ch.Close

Used in conjunction with the bar-width property, this gives complete control over bar placement. The normal styles of ‘floating’ and ‘relative’ apply here to generate floating and aggregated charts. Value labels may be placed on top or inside the bars as for normal barcharts. It will not automatically place bars in groups, but with careful use of bar width and placement it is easy to reproduce this layout in your application.

See also ...

Barchart style | BarWidth – bar width for X-bar and Gantt | ValueStyle – value-tag style

Send comments on this topic
© Dyalog Ltd 2007


Reference: Other Functions

This section lists all the functions (alphabetically by function name) which set up the charting environment, or add extra information such as JavaScript callbacks to your chart data.

chaddeffect | ch.AddEffect – use an animation or CSS style on text items
chbitmap | ch.Bitmap – add images to charts
chbookmark | ch.Bookmark – add outline entry for chart
chdefinedash | ch.DefineDash – generate custom dash repeats
chdefineeffect | ch.DefineEffect – set up SVG effects
chdefinemarker | ch.DefineMarker – define markers
chdefinetile | ch.DefineTile – define new fill patterns
chdraw | ch.Draw – add arbitrary polylines
chdrawaxes | ch.DrawAxes – redraw chart axes
chfix | ch.Fix – update property directly
chgroupby | ch.GroupBy – add a grouping criterion
chhelp | ch.Help – invoke help file
chhint | ch.Hint – add data hints
chhref | ch.Href – add HTML jumps
chinclude | ch.Include – add arbitrary content (SVG filters and symbols)
chinnergap | ch.InnerGap – inner gap on barcharts
chjscript | ch.JScript – define JavaScript prologue
chjset | ch.JSet – set JavaScript properties
chmapcoords | ch.MapCoords – map from chart space to frame
chmetafile | ch.Metafile – add metafiles
chname | ch.Name – give a name to the chart
chnewcell | ch.NewCell – advance to next cell in trellis
chnextnote | ch.NextNote – y-position of next note
chpasteup | ch.PasteUp – include completed chart in page layout
chrangeaxes | ch.RangeAxes – set axis ranges
chrendereps | ch.RenderEPS – render chart to an EPS file
chrenderpdf | ch.RenderPDF – render chart to PDF
chrenderpng | ch.RenderPNG – render chart to PNG image
chrendersvg | ch.RenderSVG – render chart as SVG
chrendervml | ch.RenderVML – render chart as VML text
chrenderemf | ch.RenderEMF – render chart as Windows metafile
chreset | ch.Reset – reset to defaults
chresetkey | ch.ResetKey – remove any key placeholders
chrun | ch.Run – run with preset array and type
chseries | ch.Series – name each data series
chsetdefault | ch.SetDefault – change shipped settings
chsetnewline | ch.SetNewline – change the default linebreak
chsetseparators | ch.SetSeparators – thousands and decimals
chsplitby | ch.SplitBy – add a splitting criterion
chtext | ch.Text – low-level text output
chtextwidth | ch.TextWidth – measure text
chtip | ch.Tip – supply pop-up tips for data points
chtrellis | ch.Trellis – define a matrix of cells
chusetable | ch.UseTable – add a NewLeaf table to any chart
chversion | ch.Version – return current version


Rain graphics: ch.AddEffect - use an animation or CSS style on text items

ch.AddEffect – use an animation or CSS style on text items

To include a defined effect (such as an SVG shadow filter) to any of the standard text items:

ch.AddEffect 'Heading' 'opacity:0.5'

You can call this function as many times as you like to apply several filters to the same named object. The current list of known target objects is:

Frame
Heading
Subhead
Footnote
Pagelabels
XCaption
YCaption
XLabels
YLabels
Key
Notes
Values

Any of these text items may be the subject of a special CSS style or SVG animation. for example to slide in a heading from the right, you could use:

ch.AddEffect 'Heading' '<animate attributeName="x" from="4000" to="&x" dur="5s" fill="freeze" />'

This will start the heading off-page to the right (4000 is the left edge of the text) and move it to its ‘normal’ position with a duration of 5 seconds. Please refer to any good guide to SMIL animation for more information.


Rain graphics: ch.Bitmap – add images to charts

ch.Bitmap – add images to charts

This function allows you to add raster images anywhere on the chart. It takes the image filename and the required (x,y) position as argument:

ch.Plot ⍳12
ch.Bitmap'ettons' (5 5)
View ch.Close

This will position the bitmap with the lower left corner at x=5, y=5 reference the chart axes. The extension ‘.bmp’ is assumed if you do not specify the filetype. For SVG output, you should use .PNG or .JPG only here; for PDF output, .BMP is the only supported format for PDFs.

This assumes that the picture is a screen shot at 96dpi – if you have a photograph scanned at 300dpi, pass this as the third element in the second argument:

ch.Bitmap'backdrop' (5 5 300)

The picture will now be much smaller. Note that if you call this function before you have plotted any charts, the entire chart area has notional axes of x=0⍎432, y=0⍎324. This is probably the most convenient point to call ch.Bitmapto add an element such as a company logo to your chart. However you will need to set the ‘nowipe’ style to prevent the first chart from clearing the plotting region:

ch.Bitmap'mylogo' (2 2 300)
ch.Set 'nowipe' ⋄ ch.Plot ⍳12

This adds the logo in the lower left corner of the chart. If you use -ve positions they are interpreted as the distance from the opposite corner of the chart area, so to place your logo in the top left corner:

ch.Bitmap 'mylogo' 10 ¯10

Note that you may omit the extra level of nesting in the function argument if you prefer.

Including images with VML or SVG

When the finished chart is saved as an SVG or VML graphic, the image is not actually included in the generated file. Instead, RainPro builds a link tag so that the browser will call back to the server to retrieve the image. The path that is required for this file may well be quite different to the name of the physical file which RainPro also needs in order to extract the width and height information from it. To allow for both possibilities, you can include two names here, separated with the ‘pipe’ character:

ch.Bitmap 'c:\realpath\pix\mylogo.png|../pix/mylogo.png' 10 ¯10

RainPro will use the first name to check the file, and the second as the reference in the link tag for SVG and VML. In the case of a rendered PNG image or PDF output for the finished chart, the first file will always be used. Of course you could give a completely different filename here, but if you do this, be sure it has the same size otherwise SVG will scale it to fit the wrong width and height.


Rain graphics: ch.Bookmark – add outline entry for chart

ch.Bookmark – add outline entry for chart

Multi-page collections of charts may be bookmarked with easily recognised names which can be organised into a tree structure to be shown by the Acrobat Reader as ‘Outlines’. It is also possible to create entries in the outline tree which jump to external resources, typically webpages or other PDFs.

The simple form of the command is ...

ch.Bookmark 'Sales analysis'

The bookmark will be placed on the next chart to be generated – you may call ch.Bookmark several times in succession to create an outline structure if required.

Making an indented outline for Acrobat Reader

The outline information is included in the PDF file generated using pdf.PS. It will often be helpful to indicate the outline level of the bookmark, with major sections at level-0 and subsidiary sections indented to form a contents tree.

ch.Bookmark 'Sales analysis' 0
ch.Bookmark 'Europe' 1
ch.Bar europe
ch.NewPage
ch.Bookmark 'Asia' 1
ch.Bar asia

... and so on. This structure will then appear in the Acrobat Viewer outline bar to the left of the document. By default, sections will be closed on opening the document – you can force the Acrobat Viewer to open a section automatically by appending 1 as the final parameter to the bookmark call:

ch.Bookmark 'Profit and Loss' 0 1
ch.Bookmark 'Income breakdown' 1 1

ch.Bookmark 'Consulting' 1

Linking to webpages

You can add a link to an external resource by including a 4th element in the call, for example:

ch.Bookmark 'Home page' 0 1 'http://www.grapl.com'

This will allow the user to click on the outline entry and automatically open a web-browser at the page you give. To have Acrobat Reader load another PDF, just use a filename here in place of the url.

Documents including outline information will automatically show the outline bar when opened in the Acrobat viewer unless the PDF was explicitly set to be rendered in FullScreen mode.

Checking the bookmark table

If you want to construct your own viewer, with a tree-structured table of contents, you can check the page-count, title and bookmarks table with info←PostScrp.Info spl. The bookmarks table is a 3-column matrix giving the bookmark name, page number and indent level. Page numbers of 0 represent external links and should be masked out here by your application.

See also ...

ch.NewPage – request a new page


Rain graphics: ch.DefineDash – generate custom dash repeats

ch.DefineDash – generate custom dash repeats

To generate any required sequence of repeating patterns:

ch.DefineDash 12(12 4 24 4)          ⍝ Long, longer
ch.DefineDash 18(15 3 2 2 2 5)       ⍝ Long, short short
ch.DefineDash 123(3 2 3 2 3 2 12 3)  ⍝ 3xshort, then long

The argument requires a 2-element vector, giving an integer id for the pattern (use numbers above 10 to avoid clashing with patterns preset by RainPro) and the repeat pattern (on/off) in points. The repeat pattern must be of even length. You can select the pattern as for any of the RainPro presets:

ch.Set'nomark'
ch.Set'line' 1 12 18 123

This establishes the cycle of dashed lines which will be used as data series are plotted.


Rain graphics: ch.DefineEffect – set up SVG effects

ch.DefineEffect – set up SVG effects

Effects are a general mechanism for attaching various SVG capabilities to plotted data or text such as headings and labels. Examples would include 3D ‘extrusion’ on lines or pie sectors, drop-shadows on text items, or simple animations such as growing bars or slide-in notes.

Working with filters

The SVG specification requires all filters (shadows, 3D effects) to be defined in a separate ‘definitions’ block in the file, and referenced from the object with an internal URL. This means that setting these up is a 3-stage process. Firstly, you must call ch.Include to make sure the actual filter definition forms part of the completed graphic. A typical filter would be saved in a text file and might look like:

<defs>
  <desc>A simple blurred shadow for a heading</desc>
    <filter id="MyShadow">
      <feGaussianBlur in="SourceAlpha" stdDeviation="12" result="blur"/>
      <feOffset in="blur" dx="24" dy="20" result="offsetBlur"/>
      <feMerge>
        <feMergeNode in="offsetBlur"/>
        <feMergeNode in="SourceGraphic"/>
      </feMerge>
    </filter>
 </defs>

The effect definition refers to the id of the filter using the normal syntax for an internal URL – the name prefixed with ‘#’ as in:

ch.DefineEffect 97 '#MyShadow'

This points to the filter with id=MyFilter in the included content. Of course, you may have several filters defined in the same included file with different ids. You may also combine filters with other supported styles, using the syntax:

ch.DefineEffect 97 'filter:url(#MyShadow);opacity:0.75'

You may need to experiment to find out just which CSS styles the Adobe SVG viewer and the Microsoft VML renderer currently support.

Defining animations

Animations are much simpler to define, as they are simply run in-line as child tags of the animated object. For example:

ch.DefineEffect 42 '<animate attributeName="width" from="0" to="&width" dur="5s" fill="freeze" />'

This could be used with a horizontal barchart to make the bars grow over a period of 5sec. Note the use of “&property” to stand as a placeholder for the ‘static’ value of the property. This is a useful shorthand, as it allows you to apply a single animation to all the bars on your barchart, and have them grow from 0 to their natural width or height.

Applying effects to chart elements

To apply any effect (or collection of effects) to text elements, simply specify the effect id(s) in the element style:

ch.Set 'Hstyle' 'effect=98'

To apply multiple effects, chain them with the ‘+’ symbol, e.g. ‘effect=98+99’. This could be used to apply successive animations, for example a note which slides in from the right, then fades out after 10sec.

To apply the effects to data elements (lines, bars and so on) you set up an effects cycle in the same way as you define the cycle of colours, linestyles and so on. The data-elements will acquire the effects from the cycle in sequence, but note that you can only apply a single effect to each element here.

See also ...

ch.Include – add arbitrary content (SVG filters and symbols) | Effect – apply an SVG effect

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.DefineMarker – define markers

ch.DefineMarker – define markers

This allows you to set any standard icon, text character or vector drawing as your graphics marker.

Using image files

You can use small GIF files (typically 16 by 16) as graphic markers, but please note that these do not scale when you zoom in on the viewer, or on the printout. Also they are not supported by the direct PostScript or EPS output. They are very suitable for ‘PowerPoint’ style on-screen graphics where you need a strong visual effect.

ch.DefineMarker 23 'c:\data\icons\aplapple.gif'

Now you can use marker 23 as normal in line plots – the VML or SVG output will insert a suitable <image> tag to reference it. This will assume 16 pixels square by default as height and width. You can override this default by specifying the image size (in pixels) which you want to show in the graphic:

ch.DefineMarker 23 'c:\data\icons\aplapple.gif=32,32'

In this case, the marker will be sized assuming that the original image file is 32 pixels square.

For SVG output, you may refer to an external image in this way, but a better option is to include the image definition as a ‘symbol’ with a suitable id, and then refer to it from the marker definition:

ch.DefineMarker 24 '#mymark'

Again, you can force the scale of the marker by appending ‘=ht,width’ to the marker id here. Be careful to keep the aspect ratio of the viewBox of the included symbol consistent with the scaled height and width.

Using characters as markers

Characters from any scalable font (TrueType or PostScript type-1) can be used in charts as custom markers. A simple use of this would be in a scatter plot, say of two datasets for Male and Female subjects:

ch.Set 'xyplot,nolines'
ch.DefineMarker 20 'arb,12,M'
ch.DefineMarker 21 'arb,12,F'
ch.Set 'marker' 20 21
ch.Plot ?12 2⍴15
ch.Plot ?14 2⍴12
View PG←ch.Close

This uses 12-point bold Arial ‘M’ and ‘F’ for the series. The markers are centred horizontally and vertically at the data values, but obviously with alphabetic characters there is some scope for confusion here. A good source of centred markers is the WingDings font, for example you might use the ringed numbers, as in the following example:

ch.Set 'xyplot,nolines'
ch.DefineFont 'WING' 'Wingdings'
ch.DefineMarker 101 'wing,18,C'    ⍝ Wingdings 'C' is thumbs-up
ch.DefineMarker 102 'wing,12,#146' ⍝ Wingdings '7' in a circle
ch.Set 'marker' 101 102
ch.Plot ?12 2⍴15
ch.Plot ?14 2⍴12
View PG←ch.Close

Note that you can enter the hi-bit characters as the appropriate symbol (probably pasted from CharMap), or as the octal code, preceeded by a backslash, or (as shown here) as the decimal code preceeded by a hash symbol. Use the octal notation if you are using a PostScript font (such as ZapfDingbats) and wish to output your charts as PDF documents (via Acrobat Distiller) or as EPS files.

You can use short phrases as well as single symbols if you prefer:

ch.DefineMarker 99 'arb,10,Ph'

Again, these will be centred at the datapoints.

Using vector markers

You can use the syntax of ch.Draw/jump> to define arbitrarily complex vector graphics, which will be drawn or solid-filled in the current colour. The outline is drawn using the current nib setting; the values are xy pairs, with all distances in points.

ch.DefineMarker 67 (3 2⍴0 0 10 10 20 10)

The zero point for the marker is always drawn at the data point, so you will probably want to centre your markers around zero. If you pass a vector definition, it is automatically reshaped to 2 columns. The default is to stroke the entire outline as a single connected polyline; to draw several segments add an extra column at the front of the array to mark ‘pen-up’ or ‘pen-down’. The first element of this should always be 0 (pen-up), then you can insert 0 where you need to start a new polyline. If the final element in any segment is 2 instead of 1 the polyline willl be closed and filled rather than stroked.

Text and vector markers (and included SVG symbols) can be scaled using the marker-scale property.

See the Contour demo for an example of defining the standard molecular diagrams for Benzene and Phenol and using these as the markers on a scatter plot. See DefMark for a variety of custom text markers.

See also ...

MarkerScale – marker scale


Rain graphics: ch.DefineTile – define new fill patterns

ch.DefineTile – define new fill patterns

RainPro uses the first 8 ‘patterns’ to generate half-tones on low-colour devices (16- and 256-colour monitors and mono printers); patterns 9-15 are a simple set of hatchings, and numbers up to 39 are a selection of opacities and gradient fills. Any higher numbers may be defined using either the name of a bitmap file, a reference to an SVG gradient (see below) or a variation on one of the standard fills.

Note that there are some minor variations between output formats (PDF does not currently support the hatchings or bitmap fills, and SVG/VML do not support hatchings). The gradient fills look very similar on all output formats, but there are some inevitable small visual differences as the syntax for defining gradients is very different on the 3 formats.

Examples of Bitmap Fills

ch.DefineTile 32 'c:\windows\bubbles'
ch.DefineTile 67 (?8 8⍴15)

defines patterns 32 and 67. These can then be used anywhere a fill is required, for example:

ch.Set 'pattern' 3 14 32 67
ch.Pie 5 4 3 2
View ch.Close

will cycle these patterns around the pie sectors.

Note that the sector colour will be ignored for sectors with bitmap fills – the pattern is assumed to be fully coloured already.

Augmenting a standard gradient fill

The way all the built-in gradients work is to ‘lighten up’ the base colour by stirring in white to make the target colour for the highlight. If you want to grade to an arbitrary colour, you can override the colour with:

 ch.DefineTile 77 '34+Fuchsia'

This will use the gradient pattern numbered 34 (numeric pattern ids only are allowed here) but will grade towards ‘Fuchsia’. Of course hex values are also allowed here as a way of specifying arbitrary colours.

Alternatively, you can simply vary the amount of white ‘stirred in’ by changing the target pattern number (the default is always to grade towards pattern-3):

 ch.DefineTile 101 '36+1'

This example will use the ‘spotlight’ gradient, but with a much brighter central highlight.

Working with custom gradients and filters in SVG

SVG allows you to define a wide range of gradient fills as named resources within the output page. If you want to extend the set of inbuilt gradients, you can use this function to reference the URL of the fill pattern (included in the chart definition), prior to setting it as the pattern attribute for any of the chart, note or key boxes, or as an item in the Patterns cycle.

 ch.DefineTile 17 '#spotlight'
 ch.DefineTile 21 'filter:url(#MyFilter); fill:url(#fill1)'

In the second example, a filter is combined with a pre-defined fill. You can also set the opacity of the tile here:

ch.DefineTile 24 'fill:url(#fill2); opacity:0.25'

This will set up the defined fill pattern, but it will only be 25% opaque. Of course, any definitions you make here are completely platform-specific and will show as half-tone colour if the chart is rendered to PDF, VML or a raster format.

See also ...

ch.Include – add arbitrary content (SVG filters and symbols) | Patterns – pattern cycle

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Draw – add arbitrary polylines

ch.Draw – add arbitrary polylines

This allows you to draw arbitrary polylines over your charts, for example to add small diagrams, draw boxes around points, join points which are not normally in sequence, and so on.

ch.Plot 2 4 3
ch.Draw ch.MapCoords 2 2⍴1 2, 3 3
View ch.Close

This will join the first to the last data point with a solid line using the colour of the last chart plotted. The columns of the ‘draw’ matrix give the (x,y) values in the two-column case. Note the mapping from chart co-ordinates to absolute values in points.

Here is an example of a chart with the originator’s logo drawn in the corner:

If three or more columns or arrays are passed:

  • col-1 is the ‘0=penup; 1=pendown; 2=brushfill’ marker to split out polylines
  • col-2 is the x-value (points from left edge of current frame)
  • col-3 is the y-value (points from bottom of current frame)
  • col-4 (if given) is the over-ride colour (index to colourmap or RGB composite)
  • col-5 (if given) is the pattern fill (default half-tone) used if 2 appears in col-1
  • col-6 (if given) is the line-weight (black if filled, else in given colour)

Note that if you draw your diagrams before the plot, you should call ch.Set 'nowipe'to prevent Rain from clearing the plotting space and probably wiping part or all of your artwork.


Rain graphics: ch.DrawAxes – redraw chart axes

ch.DrawAxes – redraw chart axes

For some charts (e.g. surface plots with a middle Y-axis) it improves the final appearance of the plot to overdraw the axes at the end. This function simply repeats the main XY axis lines.

ch.DrawAxes

Note that it does not repeat the tickmarks, or any labels.


Rain graphics: ch.Fix – update property directly

ch.Fix – update property directly

This function provides a lower-level version of ch.Set to allow fast setting of multiple properties by an external application which already validated them. Called with 2-column matrix (or 2-element vector) giving property-id, and the new value as a string.

ch.Fix 'HE' 'This is the Heading'
ch.Fix 2 2⍴'CO' 'Red,blue,lime,Teal' 'LI' 'Solid'
ch.Fix'YR' '0,100'

The id must be upper-case and exactly 2 chars. The new value would normally be a string – numbers may be separated with comma or space. Negatives are accepted as standard hyphen characters.

See also ...

ch.Set – setting chart properties


Rain graphics: ch.GroupBy - add a grouping criterion

ch.GroupBy – add a grouping criterion

This command sets up a grouping criterion so that any charts which follow use summarised data. The default is to sum the data on the basis of the given groups, taken ‘cast in order of appearance’.

Properties

Examples

ch.GroupBy dept
ch.Bar salary
View ch.Close

You can choose the grouping method (e.g. average, min, max) using the GroupFunction setting and you can also set the order of the ‘bins’ by passing an array of bin identifiers as the GroupInto property.

See also ...

GroupFunction – grouping function | GroupInto – preset buckets for grouping

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Help – invoke help file

ch.Help – invoke help file

Invokes Windows help for the required function or property:

ch.Help 'LS'        ⍝ help on linestyle
ch.Help 'Help'      ⍝ Help on this function
ctx←0 ch.Help 'ST'  ⍝ Find context# only

The optional additional argument of 0 causes it to return the context number only. This is to allow you to build context-sensitive help into your own RainPro authoring tools.


Rain graphics: ch.Hint – add data hints

ch.Hint – add data hints

This function adds hints to a given set of data points, so that as you move the mouse over the data in the viewer, the hint can be shown in the status bar at the bottom of the screen. You can also call the PostScrp.FindHint function from your application code (typically on a mouse-move event) to detect these hints and display them in your own applications.

The argument may be a 3-element vector (the text for the hint and row,column index in the data series):

ch.Hint 'This one is exploded!' 5 1

You may also place a tip on any object with a standard id (like ‘Heading’) or something you have explicitly named. For example if you have a YZone called ‘TooHigh’, then a possible call would be:

ch.Hint 'Warning - above limit' 1 1 'TooHigh'

Hints are used to create ‘onMouseOver’ events in VML so that the user will see the hint in the status line when the mouse is waved over the hotspot in the chart. To create hints for every datapoint in a series, use the ‘Hints’ property and set this to an array of text, matching the structure of your data.

Setting up hints for multiple data series

If you want to plot several independent series on the same chart, and have different hints for each series, you must name the series explicitly with ch.Series so that the viewer can correctly identify the hints from the data points:

 ch.Series'One'
 ch.Hint 3 3⍴1 1 '1/1' 2 1 '1/2' 3 1 '1/3'
 ch.Plot(⍳10)
 ch.Series'Two'
 ch.Hint 3 3⍴1 1 'A/1' 2 1 'A/2' 4 1 'A/4'
 ch.Plot⌽⍳10
 PG←ch.Close

This is often good practice anyway, as the viewer will show the series name in addition to the row/column co-ordinates for all named series.

See also ...

ch.Tip – supply pop-up tips for data points | Hints – apply hints to data values

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Href – add HTML jumps

ch.Href – add HTML jumps

This function is used to make ‘active’ graphics work on your web site. It allows you to associate any URL (typically the address of another page on your site) with a data point on the chart. You define the jump with a 3-element vector, giving the row,col index (1-origin) of the data point in the series, and the target URL. For example:

ch.Href 2 1 'boring.htm'
ch.Pie 3 2 1

The second pie slice will show a ‘pointing hand’ in the web browser and when clicked it will route you to the page ‘boring.htm’. To jump to an anchor within the target page add ‘#anchor’ to the tag as usual. To route the jump to a specific frame, add the frame id to the URL, separated with a semi-colon:

ch.Href 1 12 'detail.htm;footnote'

This would be a good way to allow the user to click on the datapoints of a timeseries and see a summary of the numeric information for that datapoint in a second frame below the chart.

Setting up multiple jumps

If you have a target page for every datapoint, you can omit the row-col information entirely and simply supply an array of strings, shaped to match your data exactly, as the Hyperlink property of your chart. Again, you would probably add a target frame here, so that the additional data can appear in a separate frame and the original chart remains visible to be clicked again.

Calling a server

If you provide a simple text vector for the URL (no row/column details at all) RainPro assumes you want every datapoint as a hotspot, and it adds the required information automatically.

ch.Href 'http://127.0.0.1/Barinfo'

A typical line in the generated imagemap or VML attribute will now look like:

href="http://127.0.0.1/Barinfo?row=1&col=1"

Now what you get passed as the argument list to your server script Barinfois a set of property-value pairs such as:

   row  2
   col  3

... which makes it very easy to select the right data, format it and return a suitable result.

See also ...

ch.Hint – add data hints | Hyperlinks – HTML jumps from data points

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Include – add arbitrary content (SVG filters and symbols)

ch.Include – add arbitrary content (SVG filters and symbols)

Includes arbitrary text in the output stream. Ignored by PostScript and our own viewers – may be used to get customised gradient fills and 3D effects included in SVG output.

The argument is either an array of text items containing the SVG definitions to be included, or a list of text files.

ch.Include ∆grads,∆filters
ch.Include'grads.txt' 'filters.txt'

The included filters will be passed directly into the output stream, and may be referenced by ch.DefineTile to make custom fill patterns, ch.DefineEffect to enhance lines or text, or ch.DefineMark to make custom markers. Note that a reasonable selection of gradients are preset for you as patterns 24-39.

Defining custom filters

Filters must be wrapped inside a <defs> block and identified appropriately, for example:

<defs>
<desc>Background wash (light colour)</desc>
<linearGradient id="wash" gradientTransform="rotate(35)" >
<stop offset="15%" style="stop-color:#D7E1E3"/>
<stop offset="90%" style="stop-color:#9CDCEE"/>
</linearGradient>
</defs>

This filter would be referred to as “#wash” in a call to DefineTile.

Defining custom markers

Marker definitions are made using the <symbol> tag, and may specify the bounding box of the symbol:

<symbol id="duck" viewBox="0 0 3200 2400">
<path d=” M 424 1424
C 619 1589 790 1613 1105 1457
C 1417 1301 1474 1325 1564 1340
C 1654 1352 1681 1388 1723 1355
C 1867 1241 1684 836 1915 716
C 2032 656 2164 704 2263 794
C 2362 884 2446 1052 2647 1055
C 2587 1190 2563 1202 2248 1190
C 1933 1181 2014 1361 2185 1511
C 2266 1589 2425 1712 2377 1898
C 2329 2084 2119 2147 1888 2147
C 1657 2147 1060 2117 832 2015
C 622 1877 430 1547 424 1424 z”
style=”stroke:#000000; fill:Teal;
stroke-width:20;” />
</symbol>

You would refer to this symbol as “#duck” in the marker definition. In this example, the duck will probably not centre visually at the data point. When you design your symbols, be careful to make the (0,0) point the visual focus of the image.

See also ...

ch.DefineEffect – set up SVG effects | ch.DefineMarker – define markers | ch.DefineTile – define new fill patterns | Patterns – pattern cycle

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.InnerGap – inner gap on barcharts

ch.InnerGap – inner gap on barcharts

If you want to overlay a second chart on a grouped barchart, you will need to know the spacing which Rain has calculated for the inner bars:

hfs←ch.InnerGap

See Boxplot for an example.


Rain graphics: ch.JScript – define JavaScript prologue

ch.JScript – define JavaScript prologue

This includes the definition of any JavaScript functions or global variables in the chart, so that chart objects may define events for data items which can run your code in the web browser.

ch.JScript'// Globals' 'var total=0;'
ch.JScript addme

The script may be passed as a vector of strings, or a simple string delimited by carriage-return characters.

All scripts must be defined before you plot any data which may call them. This function may be called several times to set up global variables and a collection of functions if this is convenient.


Rain graphics: ch.JSet – set JavaScript properties

ch.JSet – set JavaScript properties

Every VML or SVG object is a namespace, so you can set arbitrary variables for each chart data item (typically you would set its value), or on headings, keys etc. You can set any of the standard JavaScript event handlers here, for example onMouseOver and onMouseOut to have data items highlight as you track the mouse over them. If you want to set the text of headings or other chart items, you can refer to them by the standard names listed as viewer hotspots, but be sure hotspots are turned on before you start to build the chart.

Setting properties on all data-points

⍝ Each object acts as a namespace, so we can set arbitrary variables
 ch.JSet'value'vv
⍝ This just highlights the bar the mouse is over
 ch.JSet'onMouseOver' 'this.strokecolor=''green'';'
 ch.JSet'onMouseOut' 'this.strokecolor=''black'';'
⍝ Note the use of 'this' to pass the value for the correct bar
 ch.JSet'onMouseDown' 'AddMe(this.value);'
 ch.Bar vv

To pass arrays of values, replace the second argument to the function with either a simple array or an array of arrays:

 ch.JSet 'value' (34 27 16 6)
 ch.JSet 'product_code' (3 4⍴⍳12)

The second example would be typical for a barchart, where a product identifier could be associated with each bar segment to assist with a subsequent database query.

Another possibility is to use ‘unnamed’ properties, in which case the entire property value is written into the output stream exactly as it appears. This could be used to set a collection of properties in a single call:

 ch.JSet '' 'onMouseOver="this.strokecolor=''green''; onMouseOut="this.strokecolor=''black'';"'

Setting properties on selected data-values

In all the examples above, the argument is passed as a 2-element set. An alternative syntax is to pass 4 arguments giving the (row,col) in the data series and the specific handler for just that data value:

 ch.JSet 'onMouseOver' 'this.strokecolor=''green''; ' 3 2

This would set the handler only on the data point from the 3rd row of the second series. A useful ‘special’ setting is that if you give a handler for row=0, this is interpreted as the ‘line’ in a chart with both lines and markers. You could use this to highlight the line the mouse is over, without affecting the markers. Here is an example (using the SVG style) which highlights any of 3 lines – note that the highlight is cancelled by a generic call as it is the same for all of them:

 ch.JSet 'onmouseover' 'evt.target.setAttribute('style','stroke:Red;');' 0 1
 ch.JSet 'onmouseover' 'evt.target.setAttribute('style','stroke:Lime;');' 0 2
 ch.JSet 'onmouseover' 'evt.target.setAttribute('style','stroke:Blue;');' 0 3
⍝ We can reset any of them with the same call (generic setting)
 ch.JSet'onmouseout' 'evt.target.setAttribute('style','');'

If you want to set a generic handler which is over-ridden for a selection of specific handlers, be careful to put the generic setting first and follow it with the selective settings.

Setting properties on chart boilerplate

You can use the ‘target’ element to attach handlers to any of the following standard items:

Heading ... The main chart heading
Subhead ... The subsidiary heading
Footnote ... The chart footer
Pagelabels ... The page-label array
XCaption ... The X-axis caption
YCaption ... The Y-axis caption
XLabels ... The set of all X-axis labels
YLabels ... The set of all Y-axis labels
Key ... The set of chart keys (series marker and text)

If you name a target with multiple elements (such as the Key) you may pass an array of handlers, which will be associated with individual elements of the given item. An option here would be to pass an array of values (one per key element) and also attach a single Javascript fragment to all the keys which used the value to process accordingly.

ch.JSet'ColorMe'('' 'Lime' 'Fuchsia')0 0 'Key'

Note that you must specify (0,0) as the row/col indices here, which are ignored in this case.

The sample function Jscripthas some simple ideas to show some of the possibilities. For more information on JavaScript, see any good textbook, such as the “Rhino” book from O’Reilly. Please note that scripting is possible on SVG charts, but requires considerably more JavaScript expertise.


Rain graphics: ch.MapCoords – map from chart space to frame

ch.MapCoords – map from chart space to frame

Maps chart axes to points, relative to the current frame.This is useful for positioning text output and drawing arbitrary polylines with ch.Draw e.g. to annotate data points or write your own text on Gantt charts.

It may also be used to offset notes by a fixed amount from a datapoint, for example:

ch.Note(⊂'Point 4;with offset'),4 ¯3 + ch.MapCoords mat[4;]

This will write the text 4 points to the right of the data and drop the baseline by 3 points. The sample function Annotations shows some possibilities here.


Rain graphics: ch.Metafile – add metafiles

ch.Metafile – add metafiles

This function can be used to place vector artwork anywhere on the plot, or to add a ‘PowerPoint’ style background to the entire chart area.

ch.Plot ⍳12
ch.Metafile'apltext' (6 4)
View ch.Close

This will add the ‘APL’ artwork with the lower left corner at x=6, y=4 reference the chart axes. If the metafile has been saved with a placeable header it will use this to make it at the correct size, however you can have it stretched to fit an arbitrary rectangle by passing the required width and height in addition:

ch.Metafile'apltext' (6 4 6 3)

Again, the width and height are expressed in the co-ordinate system of the chart.

If you call this function before you have plotted any charts, the entire chart area has notional axes of x=0⍎432, y=0⍎324. This is probably the most convenient point to add an element such as a shaded backdrop. However you will need to set the ‘nowipe’ style to prevent the first chart from clearing the plotting region:

ch.Metafile'shade' (0 0 432 324)
ch.Set 'nowipe,nohalo' ⋄ ch.Plot ⍳12

Note that the normal ‘halo’ effect around markers is also cancelled for better visual effect.

If you use -ve positions they are interpreted as the distance from the opposite corner of the chart area, so to place your logo in the top left corner (at its true size):

ch.Metafile 'mylogo' 10 ¯10

Note that you may omit the extra level of nesting in the function argument if you prefer.

See also ...

ch.Bitmap – add images to charts


Rain graphics: ch.Name – give a name to the chart

ch.Name – give a name to the chart

You can use this function to help you to recognise which chart a user clicked on if you intend to do drill-down or other chart-related processing in your application. The name you give will be included as an HTML anchor at the top of the block containing the chart. You could use this to make an HTML jump directly to a specific chart embedded in a long webpage.

ch.Name 'FirstPie'

If you do not name charts, they will be given a meaningless (unique) name such as ‘chart35321’ when they are generated. If you only have one chart (which may have multiple data series) at a time, you can ignore this function. See PostScrp.FindSeries for the code which you need to make use of these names.

See also ...

ch.Href – add HTML jumps


Rain graphics: ch.NewCell – advance to next cell in trellis

ch.NewCell – advance to next cell in trellis

When you have defined the chart area as a rectangular array of cells (trellis) with ch.Set 'Trellis'you move to the next cell with:

ch.NewCell

Most of the chart settings are left as they were by this call. For a full reset, call ch.Reset or set the trellis style to ‘reset’.

A typical use of this function would be to plot data from a series of planes of a high-dimensional array:

ch.Set 'trellis' (1↑⍴mat)
:for plane :in ⍳1↑⍴mat
  ch.NewCell
  ch.Plot mat[plane;;]
:endfor

You might like to set the Y-axis range outside the loop to ensure comparability between the plots as Rain will auto-range each plot individually by default. Note that for the simple case (as shown above) when you only plot one chart in each cell, you can set the trellis style to ‘skip’ to have RainPro move on to the next cell automatically. See the tutorial on trellis plots for more examples.

See also ...

TrellisStyle – trellis style


Rain graphics: ch.NextNote – y-position of next note

ch.NextNote – y-position of next note

Returns the correct position for the next note text in points (absolute style) or chart co-ords (relative style). You can use this to position a set of notes (for example a subheading followed by one or more wrapped paragraphs) correctly on the chart.

vpos←ch.NextNote 6  ⍝ add 6pt headspace

This spaces vertically down by <vspace> (in points always) from the calculated baseline for the next text output. Pass 0 here to have the text flow naturally, or 12 to add a line of space between paragraphs. The resulting <ypos> is returned in chart co-ordinates if you positioned your note this way, or in absolute (points) co-ordinates relative to the lower left corner of the current frame if you placed your note with style ‘absolute’.

See also ...

ch.Note – add chart notes | NoteStyle – note style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.PasteUp – include completed chart in page layout

ch.PasteUp – include completed chart in page layout

Simple utility to paste a completed chart on top of another chart, and so on. Intended for really complex layouts such as 1-page management reports where using ch.New gets really fussy. It just feels more intuitive to create all the charts in advance and then paste them up to make the final page layout. Syntax is:

 ch.PasteUp PG,x,y,[width]

All values are in points, measured from the origin of the current chart or the lower corner of the page (inside the gutter) if you just ran ch.New to clear things down. The xy-pos is the TOP left-hand corner of the pasted chart. The default is to place the chart at the size it was designed, but you can give a width to get it scaled to fit (for example within margins).


Rain graphics: ch.RangeAxes – set axis ranges

ch.RangeAxes – set axis ranges

Rainpro will always range the axes for you on the first plotting call, unless you have already set the ranges explicitly. If you have a matrix of data, and want to use different plotting styles for various columns, it can be a problem if the first subset you plot does not span the full range of the data. This command takes the entire matrix and does the automatic ranging for you, without actually plotting any values.

ch.RangeAxes mat
ch.Plot mat[;1]
ch.Vline mat[;2 3]

Properties

This will draw the Y-axis to accommodate all the data, even though the first chart plotted only uses the mean values of the daily range plotted by the line following. It is also useful in trellis plots where you typically want all the miniature charts ranged the same so you can compare them easily.

See also ...

Trellis – trellis of small charts | XRange – X-axis range | YRange – Y-axis range

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Reset – reset to defaults

ch.Reset – reset to defaults

To reset all the chart parameters to the current defaults:

ch.Reset

This may be used in conjunction with ch.NewCellas this leaves all options unchanged on the assumption that you are plotting a series of small multiples which should all have the same settings. An alternative would be to set the trellis-style as ‘reset’ here.

See also ...

ch.NewCell – advance to next cell in trellis | TrellisStyle – trellis style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.ResetKey – remove any key placeholders

ch.ResetKey – remove any key placeholders

To remove any accumulated key placeholders:

ch.ResetKey

This may be used to remove placeholders left behind by calls to plotting routines to add guidelines or any other artwork to the background of a composite plot..


Rain graphics: ch.Run – run with preset array and type

ch.Run – run with preset array and type

This function simply calls the appropriate plotting routine with the current value of the chart data array property as argument. For example:

ch.Set ('type' 'Bar')('array' (2 2⍴3 4 5 6))
ch.Run

... is exactly the same as:

ch.Bar 2 2⍴3 4 5 6

See also ...

Array – chart data array | TypeOfChart – chart type

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Series – name each data series

ch.Series – name each data series

Use this function if you have several data series plotted on the same chart, and you need to know which one the user clicked on, or some external code attempted to update. By default, series are un-named, so it is essential to name them uniquely if you want to drill-down from a data point on a chart with more than one series drawn against the same set of axes.

ch.Series'Budget'

This is also used in the chart viewer to identify the series as you move the mouse over the data points. See PostScrp.FindSeries for the code which you need to make use of these series names.


Rain graphics: ch.SetDefault – change shipped settings

ch.SetDefault – change shipped settings

Replaces default values with application preference; would normally be called at initialisation time. You must use numeric values here for line styles, colours, patterns etc.

ch.SetDefault 'LI'  (1⍴1)  ⍝ All lines will be solid
ch.SetDefault 'HO' 2  ⍝ all hotspots are now operative

You should either call this function after every update of RainPro, or run it on loading your application as part of your initialisation processing. Only one property can be set at each call.


Rain graphics: ch.SetNewline – change the default linebreak

ch.SetNewline – change the default linebreak

By default, the semi-colon is used as a line-break character in headings, notes and labels. You can ‘escape’ semi-colons by preceeding them with the backslash character, but it may be more convenient to set an alternative character which you know will not occur in your text.

ch.SetNewline '∧'
ch.Set 'Heading' 'Hello∧World

This must always be a single character, with the one exception that the character pair “\n” is accepted.

See also ...

ch.Note – add chart notes | Heading – main heading

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.SetSeparators – thousands and decimals

ch.SetSeparators – thousands and decimals

Overrides the Windows default settings for thousands and decimal separators. If only one char is given, it replaces the decimal separator only. The previous value is returned as a 2-character string.

 old←ch.SetSeparators '~∧'

This can be used in a webserver application to make correctly formatted numbers for the locale reported by the browser in the HTTP header, regardless of where the server is running. Function BaasChart tests it with German ‘56,7’ style decimals.


Rain graphics: ch.SplitBy - add a splitting criterion

ch.SplitBy – add a splitting criterion

This command sets up a splitting criterion so that any charts which follow use categorised data. The default is to split the data into the criteria taken ‘cast in order of appearance’. These are then used to generate a key for the resulting chart.

Properties

Examples

ch.SplitBy housetype
ch.Scatter price vs area
View ch.Close

You can set the order of the criteria by passing an array of identifiers as the SplitInto property. This will affect the ordering within each group of bars on a barchart, or of the lines drawn on a scatterplot. It will also be used to generate the chart key, although you may override this in the usual way.

See also ...

CategoriseInto – categorisation buckets


Rain graphics: ch.Text – low-level text output

ch.Text – low-level text output

This function is designed to complement ch.Note by providing a low-level call to output bulk text efficiently. Text is drawn in the currently set Note Font and style at absolute co-ordinates (in points) measured from the origin of the current frame.

Here a new frame (boxed and shadowed) has been used to make a suitable background for a table of figures.

It will normally help to set the margins and gutter to 0 so that all the text co-ordinates are measured from the lower left corner of the frame box you define.

ch.Text mat

where <mat> is a 3-column matrix [;text vector,x,y] or a 3-element array with (text vector)(x-vector)(y-vector) (either x or y may be scalar). This is most useful for adding tabular data to charts, and is illustrated by the examples TK and Scatter in the RainPro workspace.


Rain graphics: ch.TextWidth – measure text

ch.TextWidth – measure text

This is a simple utility to measure text (typically for notes). Accepts simple strings or text arrays, and uses the normal wrapping rules on strings. Returns the width of the longest line as a decimal value in points.

 note←'Hello in;left-justified, centred;text (at 15,12)'
 tw←ch.TextWidth note
 ch.Set'nnudge'(-0.5×tw)

This could be used (as in the example) to centre a block of left-aligned text. The left argument may be used to pass a font specification – this defaults to the current note font if not given.

See also ...

ch.Note – add chart notes | NoteNudge – Nudge note position

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Tip – supply pop-up tips for data points

ch.Tip – supply pop-up tips for data points

This function adds a pop-up to a given set of data points, so that as you move the mouse over the data in the viewer, the tip shows in a transient pop-up window.

The argument may be a 3-element vector (the text for the tip and row,column index in the data series ):

ch.Tip 'This one is exploded!' 5 1

To set multiple tips in one call, use the Tips property, passing the entire array of tips as the value.

You may also place a tip on any object with a standard id (like ‘Heading’) or something you have explicitly named. For example if you have a YZone called ‘TooHigh’, then a possible call would be:

ch.Tip 'Warning - above limit' 1 1 'TooHigh'

Tips are used as the ‘alt text’ on HTML image maps and as the jump ‘title’ attribute in VML and SVG. In the Microsoft browsers, the user will see the tip as a pop-up when the mouse is waved over the hotspot in the chart. In the built-in chart viewer, both hints and tips appear in the status-line.

See also ...

ch.Hint – add data hints | Tips – adding popup tips to data values

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Trellis – define a matrix of cells

ch.Trellis – define a matrix of cells

When plotting sections through high-dimensional datasets it is often convenient to make a series of small plots in a rectangular grid. To carve the chart area into a grid of 3 rows and 4 columns:

ch.Set 'Trellis' 3 4

If you simply have a set of charts to plot in a grid, you can leave RainPro to calculate the layout:

ch.Set 'Trellis' 13

... this will divide the available space as effectively as possible to lay out 13 small plots. The cells will be used in row-major order by default; use ch.Set 'tstyle' 'snaking'to work down the columns. See ch.NewCell/jump> for details on how to move from cell to cell.

To have RainPro skip to a new cell automatically for every plotting call, set the TrellisStyle to ‘skip’.

See also ...

TrellisStyle – trellis style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.UseTable – add a NewLeaf table to any chart

ch.UseTable – add a NewLeaf table to any chart

This is experimental!

 ch.Set'ns' 'noshadowed,transparent,absolute'
 ch.UseTable PGt 200 80 200 50 'table2'

Arguments are:

  • PG – any NewLeaf ‘page’ containing at least one table
  • xpos – in chart co-ords unless ‘ABS’ is set as the Note style
  • ypos – the same (this is where the top corner of the table goes – headings and captions go above here)
  • width – the top edge of the table will be fitted to this. Table is self-scaled if not given.
  • maxht – additional constraint on the vertical dimension
  • tablename – defaults to ‘table1’ if not given. See leaf.table.Name to set these explicitly.

Table may be ‘transparent’ or ‘shadowed’ – default is just to blank the rectangle behind it.

See also ...

NoteStyle – note style


Rain graphics: ch.Version – return current version

ch.Version – return current version

To get the current version of the chart ‘engine’, call:

ch.Version

This will return the target OS, APL interpreter and code release as a 3-element text vector.


Reference: Chart Properties

This section of the reference lists all the chart properties, with examples of their use.


Rain graphics: Altitude - colours for altitude shading

Altitude – colours for altitude shading

Both the Contour plot and Response surface (or Cloud chart with a fitted surface) can shade the Z-values according to value. This setting allows you set set a collection of ‘false colours’ to represent quantites such as temperature.

To set the altitude colour series:

ch.Set 'Altitude' 'Navy,Green,Red,Yellow'

Note that you can use the standard ‘internet’ colour names or the hex-style 24-bit specification here. You may also use the colour numbers directly – the values from 0-15 are the 16 basic colours (0=black ... 15=white) and higher numbers are an integer encoding of the RGB value in the form ((256×256×Red)+(256×Blue)+Green).

ch.Set 'colour'  1 3 5 7 14

An equal number of steps will be made between each colour in the list, so try to choose colours which grade reasonably evenly between each step (e.g. rainbow colours). You will probably want to add a scalebar to help the user interpret the colour gradients.


Rain graphics: Array – chart data array

Array – chart data array

This property may be used to store your data for repeated plotting by ch.Run, which generates your chosen chart:

ch.Set ('array' (2 2⍴3 4 5 6))('type' 'vline')
ch.Run

You can change the data array and run more charts with the same type. See also the chart type property.


Rain graphics: ArrowStyle – arrowhead style

ArrowStyle – arrowhead style

You can use the ‘ArrowStyle’ property to set the arrow head-size in points, the half-angle (use angles >90∘ to make inward-pointing heads) and fill pattern (you must give this as a number). The fill pattern is solid (=15) by default, and the default half-angle is 25∘.

ch.Set 'astyle'  6 30

These settings are ignored by arrows on axes, which are always solid filled and scaled relative to the axis line-weight. Examples include FrostFree and the wind-rose in the Polar examples.

See also ...

Style – chart style | XStyle – X-axis style | Shading Patterns

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Background – chart background

Background – chart background

You can fill the plotting region (the rectangle bounded by the chart axes) with a patterned colour using:

ch.Set 'bgcol' 'Lime,2'

You may also set an edge-weight in points here, but this would normally be left at the default value of 0. The background is drawn from the origin to the last tickmark in the X and Y directions, so you may wish to combine this with the Framed or Clipped styles.

For the Dial chart, this colours the arc portion only, and for the Polar chart it colours the circle edged by the X-axis. For Table charts, it simply sets the background fill for the entire table.


Rain graphics: Barchart style

Barchart style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'Horizontal,rela'

Keyword | Description
Relative | Treat data values as relative, so sum the series progressively to make stacked bars or shaded surfaces.
Forcezero | Force both axes to include the origin
Vertical | Draw bars vertically
Horizontal | Draw bars horizontally
Group | Grouped bars (multiple barchart)
Stack | Stacked bars
Float | Floating bars (stacked but first bar is not drawn)
Axes:NoAxes | Chart axes are drawn as normal
Grid | Gridlines are drawn on both axes
Values | Values are written on/inside the bars depending on the value style
Exploded | Axes are set back from the chart area
Frame | Axes are connected across the top and side of the chart to frame it

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Bar – barcharts


Rain graphics: BarEdge – edge weight for bars

BarEdge – edge weight for bars

By default, all bars are edged in black with a 0.4pt line. To change this (or remove the edge)

ch.Set 'bedge' 1.2
ch.Set 'be' 0

Unedged bars can be used to show horizontal or vertical bands:

This example uses an unedged Gantt chart to show the safe zone for the cumulative deviation from the norm. It can be found in the Thumbnails2 example.


Rain graphics: BarLimit – barchart limit

BarLimit – barchart limit

This parameter simply prevents ‘runaway’ barcharts if you accidentally plot a silly amount of data (for example you forgot a ‘where’ setting on a big database, or omitted a grouping command):

ch.Set 'bl' 5000

The default is set to 1000, which is the total number of data items above which barcharts will simply generate a blank page with an error message.

See also ...

TowerLimit – towerchart limit


Rain graphics: BarWidth – bar width for X-bar and Gantt

BarWidth – bar width for X-bar and Gantt

The default width for bars in an X-bar plot is approximately 3 digits written with the value-tag font. This can be over-ridden to set an exact width, in the scaling units of the X-axis, or the Y-axis for a Gantt chart.

ch.Set 'bw' 0.4

This allows precise control over bar placement, and could be used (for example) to produce a chart with multiple sets of stacked bars. The function BaasChart in the RainPro workspace illustrates the technique.

You may also pass an array of widths here, for example in a Gantt chart it might be desirable to show some of the bars fatter than others. Normally the array would match the shape of the data, but if necessary it will be reshaped (the elements will be reused cyclically) to match the numbers of items in the data.

ch.Set 'bw' 2 2 2 3 2

This could also be used in the XBar chart to create proportional bars where the width of the bar varies to show an extra variable.

See also ...

ch.Gantt – project plans | ch.Xbar – bar charts with a defined x-axis

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Boxplot Style

Boxplot Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'Forcezero,grid'

Keyword | Description
Forcezero | Both axes will include the origin
Horizontal | Bars and whiskers are drawn parallel to the X-axis
Deciles | Whiskers are dotted for the top and bottom deciles
Axes:NoAxes | Axes are drawn
Framed | Framed axes (completed across the top and down the side)
Exploded | Axes are set back from the chart area
Grid | Gridlines are drawn on both axes

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Boxplot – box and whisker charts


Rain graphics: Bubblechart Style

Bubblechart Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'Forcezero,radial'

Keyword | Description
Forcezero | Both axes will include the origin
Grid | Gridlines are drawn on both axes
Clipped | Data is clipped at axis extents
Values | Value tags are drawn at markers (z-values are used)
Radial | Scaling is proportional to data, rather than the Sqrt of the value
ScaleBar | A calibration bar is drawn in the right margin
Model | A weighted regression line is drawn
Axes | Axes are drawn
Framed | Framed axes (completed across the top and down the side)
Horizontal | Bars and whiskers are drawn parallel to the X-axis
Exploded | Axes are set back from the chart area

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.


Rain graphics: CaptionFormat – caption picture

CaptionFormat – caption picture

The X and Y-axis captions may be formatted with a simple picture format such as:

ch.Set 'cpic' 'XXXXXX;'

To force the captions to wrap at the length of the given string. If the string is simply ‘XXXXXXX’ then longer captions are truncated, and end with ‘...’ to indicate this.

This only applies to X-captions and Y-captions set with style ‘AtEnd’. Vertical Y-captions are not multiline.


Rain graphics: CaptionLineSpacing

CaptionLineSpacing

You may set the line-spacing for multi-line ‘atend’ captions:

ch.Set 'CW' 120

The pitch may be given as a percentage, a factor of the font size, or an absolute distance in points. The default value is 110% of the font size.

See also ...

CaptionStyle – caption style


Rain graphics: CaptionStyle – caption style

CaptionStyle – caption style

Captions on 3D charts are normally angled to match the slope of the axis. The text may be more readable at small sizes if written horizontally.

ch.Set 'Cstyle' 'flat'

will achieve this effect. You may also want to place the X and Y captions ‘atend’ with this style.

Caption alignment can be set with:

ch.Set 'Cstyle' 'left|centre|right'

The default is both left and right-hand axes to show centred text when this style is applied to the y-axis.

See also ...

CaptionLineSpacing | LabelStyle – label style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: CategoriseBy – category variable

CategoriseBy – category variable

Scatter plots can take a matrix of values, with the X-variable in column-1 and as many Y-variables as required in columns 2-n. It may be more convenient to specify the y-data as a simple vector and split it automatically with a category variable:

ch.Set 'xvar' farm
ch.Set 'cvar' year
ch.Scatter yield

This style is likely to be particularly useful if the data has come from a database table, where it can be quite tedious to separate the values on the basis of one or more category columns (say Sales in tonnes by region). If the category variable is text, it is sorted alphabetically and the unique values are used as the keys. This is also a convenient way to generate a grouped barchart or multiple piechart.

There are two simple cover functions vs and by in the RainPro workspace to allow expressions like:

ch.Scatter yield vs variety by year

You can experiment with the infamous barley data here!

See also ...

ch.Boxplot – box and whisker charts | CategoriseInto – categorisation buckets | Tease – separation of scatter plots | Versus – scatter versus this

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: CategoriseInto – categorisation buckets

CategoriseInto – categorisation buckets

When you specify a categorisation variable, the default is to create the split-out columns as the alphabetical list of the unique items in the category variable. You can over-ride this (to change the ordering or use only a subset of the available data) by setting an explicit list of values to be split into.

ch.Plot yield by farm into 'University Farm' 'Waseca' 'Morris'
View ch.Close

See also ...

CategoriseBy – category variable


Rain graphics: CellSize – cell size when using markers to make cells

CellSize – cell size when using markers to make cells

When plotting geographically-related data (see the PYGS example) it is often necessary to draw a set of small plots at the actual xy positions of various sample sites. You can do this by running a standard xy-plot with style ‘cells’ to define a plotting cell centred on each data point. Repeated calls to ch.NewCellwill then walk you around the cells in the same sequence as the xy datapoints which defined them.

The cell size defaults to 1” square (72 by 72 points). You can reset it to any size you like before running the xy plot to generate the cells:

ch.Set'nolines,nomark,cells'
ch.Set'Cellsize' 32

See example function PieMarkers which uses small piecharts as the markers in a timeseries plot.

See also ...

Positioning Small Plots on the Page | ch.NewCell – advance to next cell in trellis | Style – chart style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Cloudchart Style

Cloudchart Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'Forcezero,contour'

Keyword | Description
Markers | Draw markers at data points
Lines | Connect points with lines
Risers | Draw verticals from XY-plane
Surface | Surface shading from lines down to XY-plane
Trend | An exponentially weighted trend surface is drawn through the data
Model | A regression surface (default is linear in X and Y) is drawn through the data
Contour | Contour lines are drawn through the mesh surface at Z-ticks
Project | The contours are projected down onto the xy-plane
ForceZero | All axes include the origin
Walls | The backplanes are shaded to form walls
Grid | Gridlines are drawn on the XY-plane and the backplanes
Axes:NoAxes | Axes are drawn

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Cloud – 3D scatter plots


Rain graphics: Coefficients – parameters from modelfit

Coefficients – parameters from modelfit

This is a read-only property which is maintained for you by RainPro to allow you to use the ‘modelfit’ style and then do your own chart notes with the details of the fit chosen.

coeff←ch.Query 'fit'

The result will be a numeric vector with 1 more element than the order of fit used. The default (order-1) is intercept and slope.

Typically, the coefficients would be used to format a neat version of the equation of the line, as here. You could also use the values for further processing, e.g. to provide forecast Y-values for specific inputs of interesting X-values by the user.

See also ...

OrderOfFit – polynomial degree of modelfit


Rain graphics: Colours – set colour cycle

Colours – set colour cycle

When you plot several data series, or use a pie chart, RainPro will work through a standard sequence of colours, shading patterns, markers and so on. These series have been intentionally chosen to be of varying lengths to reduce the chance of any two data-series being plotted in the same combination.

To over-ride the colour series:

ch.Set 'colour' 'red,blue,#FFC0C0'

Note that you can use the standard ‘internet’ colour names or the hex-style 24-bit specification here. You may also use the colour numbers directly – the values from 0-15 are the 16 basic colours (0=black ... 15=white) and higher numbers are an integer encoding of the RGB value in the form ((256×256×Red)+(256×Blue)+Green). This may be more convenient if you are computing the colours with an algorithm, or you simply have very many lines to set.

ch.Set 'colour' (12 12 0 0 2)

The cycle will persist from the point where you set it, until you set this property again – this allows you to set it once only for a series of several plotting calls.

See also ...

Lines | Markers | Nibs | Patterns | Colour

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: DateFormat – picture specification

DateFormat – picture specification

When the X-axis is set to style ‘Date’, ‘Annual’ or ‘Monthly’, the date labels may be formatted with a simple picture format such as:

ch.Set 'dpic' 'MMM-yy'

To label the tickmarks ‘Jan-01’ ‘Feb-01’ .... ‘Dec 02’ as appropriate. The months will be shown in your local language.

The date specification in detail

The following table is taken from the Microsoft documentation for the GetDateFormat API call, and is common to all Windows applications which use it:

Picture | Meaning
d | Day of month as digits with no leading zero for single-digit days.
dd | Day of month as digits with leading zero for single-digit days.
ddd | Day of week as a three-letter abbreviation. The function uses the LOCALE_SABBREVDAYNAME value associated with the specified locale.
dddd | Day of week as its full name. The function uses the LOCALE_SDAYNAME value associated with the specified locale.
M | Month as digits with no leading zero for single-digit months.
MM | Month as digits with leading zero for single-digit months.
MMM | Month as a three-letter abbreviation. The function uses the LOCALE_SABBREVMONTHNAME value associated with the specified locale.
MMMM | Month as its full name. The function uses the LOCALE_SMONTHNAME value associated with the specified locale.
y | Year as last two digits, but with no leading zero for years less than 10.
yy | Year as last two digits, but with leading zero for years less than 10.
yyyy | Year represented by full four digits.

Any text that should remain in its exact form in the date string should be enclosed within single quotation marks in the date format picture. The single quotation mark may also be used as an escape character to allow the single quotation mark itself to be displayed in the date string. However, the escape sequence must be enclosed within two single quotation marks. For example, to display the date as “May ‘93”, the format string would be: “MMMM ‘’’’yy” The first and last single quotation marks are the enclosing quotation marks. The second and third single quotation marks are the escape sequence to allow the single quotation mark to be displayed before the century.

See also ...

Locale – for formatted dates or times


Rain graphics: ContourAttributes - for 3D surfaces

ContourAttributes – for 3D surfaces

To set the attributes for the contour lines drawn on trend-surfaces and scatterplots with data-values:

ch.Set 'CAttribs' 'red,solid,0.5'

The mnemonics may be given in any order, or you can use numbers strictly in the sequence shown above (colour, style, weight). The line weights are ‘hair, fine, medium, broad’ or you can give an exact line weight in points. The line styles are ‘solid, dot, dash, ddash, invisible’ or you can use numbers from 1 to 5.

See also ...

ch.Cloud – 3D scatter plots


Rain graphics: ContourPlot Style

ContourPlot Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'Forcezero,curves'

Keyword | Description
ForceZero | Both axes will include zero in range
GridLines | Both x and y grids will be drawn
Clipped | Data will be clipped to axis bounds
NoTags | Contour lines are not annotated
NoValues | Markers are not annotated
Curves | Countour lines are drawn as smooth curves
Altitude | Chart is shaded to represent the fitted height map
Fine | Colours are interpolated to provide a smooth gradient
ScaleBar | A calibration bar is drawn in the right margin
Framed | Framed axes (completed across the top and sides)
Exploded | Axes are set back from the chart area

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.


Rain graphics: ContourTagFont - font for contourline tags

ContourTagFont – font for contourline tags

To set the font and colour for the contour-line tags:

ch.Set 'CTfont' 'he,8,Green'

The short code for the font is a two-letter mnemonic followed by either or both of the letters ‘b’ and ‘i’ for the bold and italic variants. The font size is in points, and colours follow the normal internet naming rules.

If you leave the colour at its default value, the tag will automatically inherit the colour of the contour lines.


Rain graphics: Density – of fitted mesh surface

Density – of fitted mesh surface

When the ‘modelfit’ or ‘trend’ style is used with the Cloud chart, a mesh surface is drawn through the 3D scatter. The default is to draw the mesh with one line at each X and each Y major tickmark.

ch.Set 'Density' 2

This parameter may be set to any value (1 is the default) to add extra lines in between the ticks. Values less than 1 thin out the mesh as you would expect.

This example shows a trend surface drawn with a mesh density of 2.

See also ...

ch.Cloud – 3D scatter plots


Rain graphics: Dialchart Style

Dialchart Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style.

ch.Set 'style' 'wedge,arrow'

Keyword | Description
Annular | Annular zones (75% of the tickmark length)
Wedge | Wedge zones drawn from the dial centre
Arrow | Arrowed pointer

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Dial – dial and gauge charts


Rain graphics: Edge attributes – piecharts

Edge attributes – piecharts

Pie sectors default to a thin black line as the sector edge. You can use this property to remove the edges completely, or set a differently coloured (maybe thicker) line as required:

ch.Set 'edge' 'white,solid,2'

This works well with ‘inside’ value labels as shown in the example. Only solid edges are supported at present, although other edge-styles are accepted here. To remove the edges completely, use

ch.Set 'edge' 'none'

This sets the line-weight to 0, so no edge is drawn.


Rain graphics: Effect – apply an SVG effect

Effect – apply an SVG effect

This may be used to set a cycle of predefined filter or animation effects to be used by lines to be plotted.

ch.DefineEffect 97 '#MyFilter'
ch.Set 'Effect' 97 0 0

This will apply the list of filters (0 may be used for ‘normal’) to each line in turn. In contrast with dash patterns and markers, there are no preset effects, so you may use any number from 1 upwards here. For future compatibility, it is recommended that you use numbers above 64.

See also ...

ch.DefineEffect – set up SVG effects | ch.Include – add arbitrary content (SVG filters and symbols)

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Equation – formatted result of modelfit

Equation – formatted result of modelfit

This is a read-only property which is maintained for you by RainPro to allow you to use the ‘modelfit’ style and then make use of the formatted equation.

eqn←ch.Query 'equation'

The result will be a simple string, probably formatted using the supplied template. It could be used in a chart note to give the reader details of the equation used. This property is always maintained, even if the ‘annotate’ style has not been used.

See also ...

EquationFormat – template for modelfit equation | Modelfit

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: EquationFormat – template for modelfit equation

EquationFormat – template for modelfit equation

This property provides a template to allow RainPro to produce a readable equation from the results of a fitted line or curve.

ch.Set 'epic' 'Time = C0 + C1speed'

Simple Regression

The template is scanned for the strings C0,C1,C2 and so on, depending on the order of fit used. In the example, if the intercept was 2.3 and the slope was 0.42 the equation would read “Time = 2.3 + 0.42speed”. The “+” symbol in the template is a placeholder for the sign, so a negative slope would give a “-” sign here.

If a coefficient is zero, the matching term is omitted completely, so the above template could read “Time = 0.5speed” if the line went exactly through the origin.

The formatted equation may be written on the fitted line, positioned according to the equation style, or recovered after the line has been drawn by referencing the “Equation” property. This may then be used as part of a note, or placed in the key. To have it work correctly in the key, you should make an explicit call to ch.WriteKey (setting the key property) as this ensures the value of the key is set after the chart has been run.

Multiple Regression

Note that for multiple regressions (Cloud charts and Scatterplots with the ‘contour’ option) the coefficients are generated in the order Int,x1,x2,...,y1,y2,...,y4 depending on the order of fit chosen for x and y. Set the equationstyle to ‘forcezero’ to cut out the constant term and force the fit through the origin. In this case, the only way to display the equation is by referencing the ‘equation’ property and using this in a note or as part of the key.

See also ...

ch.WriteKey | Equation | EquationStyle | Annotate | Modelfit

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Equation Index - placement of equation

Equation Index – placement of equation

To set an exact placement of the fitted equation along the curve, use the ‘index’ property:

ch.Set 'Eindex' 23

The number may range from 1 to 100, and gives the distance to travel along the fitted curve from left to right. The annotation text will be aligned left or right, depending on the slope of the chart at the point you choose.


Rain graphics: EquationStyle – placement of modelfit results

EquationStyle – placement of modelfit results

When the equation of a curve is written on the line (style ‘model,annotate’) the default is to place it above the curve, at the right-hand end. The placement and appearance can be modified with this property.

ch.Set 'EStyle' 'left,below,opaque'

Keyword | Description
Left:Middle:Right:Index=nn | Position along the line
Above:Below:Straddle | vertical placement
Transparent:Opaque | Blank behind text
ForceZero | Set the y-intercept of the fitted line to zero

You can set the linespacing for multiple lines with the NoteLinespacing property.

See also ...

EquationFormat | NoteFont | NoteLinespacing | Annotate | Modelfit

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Flexibility – shape of trend line

Flexibility – shape of trend line

When you use the ‘Trend’ style to draw an approximate curve through a scatter of points, it uses a default ‘flex’ value of 10 which actually sets the rate of die-away of the gaussian weighting used to emphasise nearby points.

ch.Set 'flex' 4

A value of 0 will just draw an average (all points are weighted equally). A value of 100 will effectively force the line to visit every point. You will need to experiment with particular datasets to find the value that best hides the noise and reveals the underlying pattern in the data.

Technical data

For the statistically-minded, who want to know how this actually works!

It is a Gaussian-weighted moving average. The ‘Flexibility’ sets the exponent of the gaussian, so the way I calculate it is to divide the x-axis range arbitrarily into 100 parts and for each point compute a y-value by adding up all the y-values from the data, weighted by the x-distance expressed as a classic ‘bell-curve’ function.

I think the more traditional approach is to use an inverse exponential weighting based on the absolute distance, but this ‘peaks’ very sharply and also tends to ‘whiplash’ at the ends, whereas the gaussian is more flat-topped, so the trend is effectively an average of nearby points with far-away points included but heavily discounted.

Basically, it just looks better for most reasonable timeseries!


Rain graphics: Footnote – footnote

Footnote – footnote

To add a footnote (using the current footnote font) at the bottom of the chart area, use:

ch.Set 'Footer' 'My chart'

Typically, this would be used to note the file name used for the chart data, the date and time of preparation, and so on. By default, it is drawn in the lower left corner of the chart area, but you can also choose centred or right alignment by setting the footnote style.

Use semi-colons to split footnotes over multiple lines. To get a semi-colon into a footnote, preceed it with a backslash character.


Rain graphics: FootnoteFont – footnote font

FootnoteFont – footnote font

To set the font and colour for the chart footer:

ch.Set 'ffont' 'Ar,7,teal'

Fonts use a 2-letter short-code. Colours use the standard web colour names or hex-style “#FFF0C0” 24-bit values.

See also ...

Colour Cycle | Fonts – defining and using short codes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: FootnoteLinespacing

FootnoteLinespacing

You may set the line-spacing for multi-line footers:

ch.Set 'FVspace'  120

The pitch may be given as a percentage, a factor of the font size, or an absolute distance in points. The default value is 110% of the font size.

See also ...

FootnoteStyle – footnote style


Rain graphics: FootnoteStyle – footnote style

FootnoteStyle – footnote style

To move the footnote from the default (lower left corner) position:

ch.Set 'fstyle' 'right'   ⍝ right aligned
ch.Set 'fstyle' 'centre'  ⍝ centred

The footer is always written along the very bottom of the chart area. Either “Centre” or “Center” is recognised here. Use style ‘Ruled’ to rule across the entire chart area, just above the footer.

See also ...

FootnoteLinespacing


Rain graphics: Frame – chart frame

Frame – chart frame

As an alternative to calling ch.Newwith a plotting region, you can set the region as a property with:

ch.Set'frame' 0 0 500 200  ⍝ Letterbox

This is convenient if you want to set up everything in advance and then generate the plot with ch.Run. The best example in the chart workspace is Settings 7 which also shows the data window.


Rain graphics: FittedValues – computed values for all datapoints

FittedValues – computed values for all datapoints

This is a read-only property which is maintained for you by RainPro to allow you to use the ‘modelfit’ style and then plot the fitted values for each datapoint as an extra chart.

coeff←ch.Query 'FValues'

The result will be a numeric vector with one value for each value in the fitted data. Where missing values were marked in the input data, there will be corresponding missing values in the computed result, so that the original and fitted series always match exactly in length.

See also ...

OrderOfFit – polynomial degree of modelfit


Rain graphics: FrameStyle – style of chart frame

FrameStyle – style of chart frame

This may be used as an alternative to the general ‘style’ property to set attributes which are specific to the chart frame.

ch.Set 'BStyle' 'nowipe'
ch.Set 'BStyle' 'boxed'

The default style is ‘wipe, nobox’ which is the same setting as for the generic style.

Options

wiped:nowipe ... Blank area behind chart
boxed:nobox ... Draw box around entire chart
shadowed:noshadow ... Shadow chart box
rounded:square ... Corner style

The bolded values show the defaults. You would use ‘nowipe’ if you placed your charts on a fancy metafile graded fill, or if you want to have several overlapped graphs in the same chart area. The ‘boxed’ style simply draws a box around the entire chart area, with a small allowance (default 4 points) as gutter so that a trellis of boxed charts has some space between the cells. You can choose to shadow the box by adding ‘shadowed’ as well as ‘boxed’ to the style.

See also ...

FrameAttributes – frame & box attributes | Gutter – chart gutter

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Frequency and Histogram styles

Frequency and Histogram styles

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style.

ch.Set 'style' 'values,grid'

Keyword | Description
Values | Write value tags on the bars
Framed | Framed axes (completed across the top and sides)
Exploded | Axes are set back from the chart area
Gridlines | Both X and Y grids are drawn
Normal | Overlay a normal curve

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.


Rain graphics: GroupBy – group variable

GroupBy – group variable

When you set a grouping variable (for example you might Barchart Sales grouped by Region) the default is to sum the data into each category defined by the group code. This will give one bar for each unique value in Region, each bar being the total sales for that region.

ch.Bar yield GroupBy farm
View ch.Close

You can split the data with a category variable as well as grouping it, which effectively gives you 2-way accumulation as the category split is done first, then the split data is grouped:

ch.Tower yield GroupBy farm SplitBy year
View ch.Close

It is possible to group a variable on itself. This is very useful for occurrence data; for example a Barchart of Species grouped by Species, with group function ‘Count’ would give one bar per species, counting the number of records logged.

See also ...

CategoriseBy – category variable | GroupFunction – grouping function

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: GroupFunction – grouping function

GroupFunction – grouping function

When you set a grouping variable (for example you might Barchart Sales grouped by Region) the default is to sum the data into each category defined by the group code. This will give one bar for each unique value in Region, each bar being the total sales for that region. The functions which you can use here are:

  • Count – just report the number of occurrences of that group
  • Sum – add up the total value
  • Mean – add up the total and divide by the Count
  • Minimum – report the lowest value in the group
  • Maximum – report the largest value in the group

ch.Set 'head' 'Mean Barley Yield by Year'
ch.Set 'gfn' 'mean'
ch.Set 'gvar' year
ch.Bar yield

All these functions take account of the current Missing Value setting, so totals and averages will correctly omit missing data.

See also ...

GroupBy – group variable | MissingValue – missing value(s)

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: GroupInto – preset buckets for grouping

GroupInto – preset buckets for grouping

When you set a grouping variable (for example you might Barchart Sales grouped by Region) the default is to sum the data into each category defined by the group code. This will give one bar for each unique value in Region, each bar being the total sales for that region. The default is to make one ‘bucket’ for each Region, sorted alphabetically.

If you want to preset the buckets – maybe you don’t have data for all of them – use this property to set them. This will also set the ordering, which is essential for monthly data.

ch.Bar yield GroupBy year GroupInto 1930 1931 1932
View ch.Close

You can split the data with a category variable as well as grouping it, which effectively gives you 2-way accumulation as the category split is done first, then the split data is grouped.

See also ...

GroupBy – group variable


Rain graphics: Gutter – chart gutter

Gutter – chart gutter

When drawing chart borders, RainPro defaults to moving 4 points in from the edges to draw the boundary line. This is reduced in proportion to the chart size, but when it appears as a gap between tiles created with the ‘Trellis’ property, it may be excessive for a collection of very small plots. To over-ride this:

ch.Set ('trellis' 4 5)('gutter' 1)

To have all the small charts abutting, set the gutter to 0.


Rain graphics: HeadingLinespacing

HeadingLinespacing

You may set the line-spacing for multi-line chart titles:

ch.Set 'HVspace'  140

The pitch may be given as a percentage, a factor of the font size, or an absolute distance in points. The default value is 120% of the font size.


Rain graphics: HeadingNudge – adjust heading placement (pts)

HeadingNudge – adjust heading placement (pts)

This property may be used to provide a fine adjustment (in points, always) to the chart heading.

ch.Set 'HNudge' 0 12

This example will move both heading and subhead up 12pts from the default position. Negative numbers will move the heading set down and leftwards.


Rain graphics: Hints – apply hints to data values

Hints – apply hints to data values

You can use this to set a collection of hints to be shown in the browser status-bar when the mouse is over any data-point (for charts rendered as VML or mapped images).

ch.Set 'hints' 'One' 'Two' 'Three'

A typical use would be for a scatter-plot where extra information about each data point could be shown to the user. To show hints on multiple data series, pass an array of values which match exactly the structure of the data.

ch.Set 'Hints' (2 3⍴'One' 'Two' 'Three' 'Four' 'Five' 'Six')

You must set hints for all the data-points if you use this property – if you only want to hint a small selection of points consider calling ch.Hint instead, as this can be called repeatedly to set hints on individual points.

See also ...

ch.Hint – add data hints | Tips – adding popup tips to data values

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: HotspotSupport – viewer events

HotspotSupport – viewer events

This property determines whether RainPro inserts hot-spot information into the chart, so that the viewer can generate events when data is clicked.

When this is set to 2 you will also receive events when the user clicks on chart headings, axis labels and so on.


Rain graphics: Hyperlinks – HTML jumps from data points

Hyperlinks – HTML jumps from data points

You can use this property to set a list of HTML jumps to be active in the web-browser when the mouse is clicked in the corresponding data-point.

ch.Set 'href' 'page1#1' 'page1#2' 'page1#3'

A typical use would be for a pie-chart where the user might ‘drill-down’ to extra information by clicking on the sectors. To set links for multiple data series, pass an array of jump targets which match exactly the structure of the data.

ch.Set 'Href' (2 3⍴'One.htm' 'Two.htm' 'Three.htm' ....)

You must set jumps for all the data-points if you use this property – if you only want to jump from a small selection of points consider calling ch.Href instead, as this can be called repeatedly to set jumps from individual points.

See also ...

ch.Href – add HTML jumps


Rain graphics: IAllowance – inner-axis allowance

IAllowance – inner-axis allowance

This sets the ‘allowance’ (default 0.8) as a fraction of the space between adjacent trace lines (determined by the major Y-ticks).

ch.Set 'ia' 0.9

This may be set to a value >1 if you have a set of lines which move along very nearly parallel to one another. However this only works well with a plain inner axis as otherwise the ticks and labels collide.

See also ...

ch.Trace – trace charts | IStyle – inner-axis style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: IFont – inner-axis font

IFont – inner-axis font

This sets the font and colour for the inner-axis labels.

ch.Set 'ifont' 'ar,5'

Typically you would use a font sized around half the normal label font. Arial is a good choice here as it remains readable at very small sizes.

See also ...

ch.Trace – trace charts | Fonts – defining and using short codes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: IFormat – inner-axis format

IFormat – inner-axis format

You can format the inner-axis labels with a simple picture format, for example:

ch.Set ('if' 'he,4,green')('ipic' '#0∘')

This will show a degree symbol after each number, which would be appropriate for temperature data.

See also ...

Picture formatting


Rain graphics: IIntercept – inner-axis intercept

IIntercept – inner-axis intercept

This sets the inner data value where each inner axis is drawn.

ch.Set 'iintercept' 0

This would draw each inner-axis through the zero-point in the trace data. This would be a good setting if the data represented deviations about a norm, or temperatures where you had values both above and below freezing point.

See also ...

ch.Trace – trace charts


Rain graphics: ILabels – inner-axis labels

ILabels – inner-axis labels

Inner labels can be used to label each inner tickmark:

ch.Set 'ilabs' 'Jan,Feb,Mar'

Generally the default numeric labels would be adequate here. The ‘Picture’ format setting may used to format the numbers if the default formatting is insufficient.

See also ...

Picture formatting


Rain graphics: Index Origin

Index Origin

The ‘IO’ property allows you to set the ‘index origin’ of a generated x-scale. This is 1 by default, but could be 0 which is good for surface filled charts as the auto-ranging of the axis often forces it to include 0, and the surface looks ugly when it does not fill right back to the y-axis

 ch.Set ('style' 'surface')('io' 0)
 ch.Plot +\?37⍴12
 View ch.Close

Although 1 and 0 are the normal values, IO can take any integer (such as 36967 which is 17th March, 2001) for date labelled axes where the data is daily from a given start date.

 ch.Set('xt' 1)('io' 36967)('xs' 'date')
 ch.Plot ⍳23
 View ch.Close

This may be helpful when the data is known to have one value per day.


Rain graphics: IRange – inner-axis range

IRange – inner-axis range

This ranges the inner axis (all replicates will be ranged the same), over-riding the automatic ranging.

ch.Set 'irange' 0 100

A single number is also valid, and sets the range from 0 to the value you give. You can also use the ‘forcezero’ style here.

See also ...

ch.Trace – trace charts


Rain graphics: IStyle – inner-axis style

IStyle – inner-axis style

The inner style may be used to force the range to include zero. Style ‘exact’ will prevent it from rounding up to the next whole tick interval.

ch.Set 'istyle' 'forcezero,'

For qualitative data (common on Kite charts) style ‘Plain’ works best.

See also ...

ch.Trace – trace charts | ITickStyle – inner-axis tickstyle | Tick Mark Styles

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ITickMarks – inner-axis tickmarks

ITickMarks – inner-axis tickmarks

This sets the tick intervals (major ticks only here) for the inner axis.

ch.Set 'itick' 10

Use the appropriate IStyle to control how the tickmarks are drawn.

See also ...

ch.Trace – trace charts


Rain graphics: ITickStyle – inner-axis tickstyle

ITickStyle – inner-axis tickstyle

The inner tickstyle sets the tickmark type as for normal axes.

ch.Set 'ix' 'Inside'

The ‘Crossing’ style works well here when combined with the default ‘Outside’ on the outer Y-axis. You might also consider ‘Inside’ which will label the inner axis down the inside of the Y-axis, so keeping the outer and inner labels well separated. For qualitative data (common on Kite charts) style ‘Noticks’ works best.


Rain graphics: IZones – inner-axis zones

IZones – inner-axis zones

Used to set up warning regions on trace charts. Each region is defined by a colour (use colour names or the standard HTML syntax here) and the start and end values for the region. Use ‘/’ to separate each zone, and ‘,’ to separate the parameters within each zone.

ch.Set 'izones' 'Yellow,3,13,4/Green,7,9,5'

The coloured bands always span the full range of the X-axis and repeat as many times as necessary for each trace on the chart.

See also ...

ch.Trace – trace charts | YZones – warning bands for Y-axis | ZoneAttributes – for warning bands

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: JavaValue – preset argument for JSet

JavaValue – preset argument for JSet

This property provides a way of constructing the array of values to be passed to a set of JavaScript handlers.

ch.Set 'JV' ((1 2 3)(4 5 6))
ch.Jset 'values'

This may be simpler to code than the alternative of passing the entire argument to ch.JSet along with the property name.

See also ...

ch.JSet – set JavaScript properties


Rain graphics: JavaTarget – name element to be scripted

JavaTarget – name element to be scripted

This property allows you to target any of the standard ‘boilerplate’ items with script fragments.

   ch.Set('jvalue' 'Tuesday')('jtarget' 'head')
   ch.JSet'Weekday'

This would come through into VML or SVG output with the appropriate value set. The element names will be checked against the standard table, which is:

Heading ... The main chart heading
Subhead ... The subsidiary heading
Footnote ... The chart footer
Pagelabels ... The page-label array
XCaption ... The X-axis caption
YCaption ... The Y-axis caption
XLabels ... The set of all X-axis labels
YLabels ... The set of all Y-axis labels
Key ... The set of chart keys (series marker and text)
Keytext ... The key text only.

Currently, these are unique on the first two letters, so the minimum you need here would be ‘HE’ to specify the heading.

See also ...

ch.JScript – define JavaScript prologue


Rain graphics: KeyAttributes – key box attributes

KeyAttributes – key box attributes

To set the attributes for the box around the chart key:

ch.Set 'kattribs' 'White,Solid,2'

The attributes give (Fill Colour, Fill Pattern, Edge-weight). The default is solid white with a 1-point edge. The edge is always black.

See also ...

FrameAttributes – frame & box attributes


Rain graphics: KeyFrame – key frame override

KeyFrame – key frame override

This property allows you to place your key or legend anywhere in the chart area, and have the keys wrapped horizontally (the default) or in vertical snaking columns within the box. See the Keytest example for some possibilities.

Some reasonable key arrangements are:

   :Case 1  ⍝ Across the bottom
     ch.Set'hm' 64 12
     ch.Set('kbox' 4 0 380 48)('kstyle' 'boxed')
   :Case 2  ⍝ Right margin, vertical, 2-column
     ch.Set('vm' 48 120)('ks' 'boxed,vert')
     ch.Set('kbox' 310 80 424 300)('kf' 'ar,8')
   :Case 3  ⍝ Right margin, vertical, reversed, small text
     ch.Set('vm' 48 80)('ks' 'boxed,vert,reversed')
     ch.Set('kbox' 360 40 420 300)('kf' 'ar,7')
   :Case 4  ⍝ Columnar, across the bottom
     ch.Set'hm' 64 18
     ch.Set('kbox' 4 0 380 48)('kstyle' 'boxed,vertical')

Note that the key frame is specified in absolute (point) co-ordinates, measured from the lower left corner of the chart area. Any keys which cannot be fitted into the given box (using the font provided) will be trimmed. The vertical spacing is always set to 1.2 × font size – you might need to use this to calculate how deep to make the box to accommodate a varying number of series. Alternatively, use the ‘autofit’ key style to ensure your keys fit into the frame size you set.

See also ...

MarginBottom – chart margin (bottom) | MarginRight – chart margin (right)

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: KeyFormat – text picture format

KeyFormat – text picture format

The key text may be formatted with a simple picture format such as:

ch.Set 'kpic' 'XXXXXXXX;'

To force the text to wrap into the space allowed for 8 ‘X’ characters. If the picture does not end with a semi-colon, the text will be truncated if necessary and terminated with an ellipsis character (→) to indicate that it has been clipped. Insertion characters are allowed as for numeric formats, so a format such as ‘SKU:XX/XXXX’ might be appropriate for a set of product codes of the form ‘HL3287’.

See also ...

Picture formatting


Rain graphics: KeyLinespacing

KeyLinespacing

You may set the line-spacing for multi-line key entries:

ch.Set 'KVspace'  120

The pitch may be given as a percentage, a factor of the font size, or an absolute distance in points. The default value is 110% of the font size.

See also ...

KeyStyle – key style


Rain graphics: KeyNudge – adjust legend placement (pts)

KeyNudge – adjust legend placement (pts)

This property may be used to provide a fine adjustment (in points, always) to the chart legend.

ch.Set 'KNudge' 0 12

This example will move the entire legend box up 12pts from the default position. Negative numbers will move it down and leftwards.


Rain graphics: KeyType - key type override

KeyType – key type override

Normally, RainPro can generate the key automatically from the chart you have plotted, for example if you plot a bar chart and a line graph the key will be preset to a small shaded block and a line (and/or marker) of the appropriate type and colour. If for some reason you want to ‘hand craft’ a key you can use this property to set the type of placeholder:

ch.Set 'Ktype' 'Bar'
ch.Set 'Ktype' 'Line,marker'

This will pick up the current settings of the colour, marker and pattern cycle – to get a key in a particular colour sequence you must include a Colours setting just before you write the key.

See also ...

ch.WriteKey – output key at given location | Colours – set colour cycle

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: LabelLinespacing

LabelLinespacing

You may set the line-spacing for multi-line axis labels (X and Y axes):

ch.Set 'LVspace'  120

The pitch may be given as a percentage, a factor of the font size, or an absolute distance in points. The default value is 110% of the font size.


Rain graphics: LabelStyle – label style

LabelStyle – label style

This sets the general appearance of the labels which are used for the tickmarks on X,Y and Z axes.

Options

transparent:opaque | Create a blanked area behind labels
default:centre:middle | Placement on Y and X axes
3D:flat | Flatten all labels on 3D charts
effect=id | Attach a defined effeect to the label text

To blank behind axis labels (useful if you have intercept axes and grid lines) set the label style to ‘opaque’:

ch.Set 'Lstyle' 'opaque'

Labels are written by default to the left of the primary Y-axis and to the right of the secondary. Use style ‘centred’ to have them written (centre-aligned) on top of the axis. This would normally be used with the ‘opaque’ setting to make a white knockout over the axis line in which to write the text. Similarly, use style ‘middle’ to place the labels over the X-axis rather than below it.

ch.Set 'Lstyle' 'opaque,middle'

Labels on 3D charts are normally angled to match the slope of the axis. The text may be more readable at small sizes if written horizontally, right-aligned to the tickmarks.

ch.Set 'Lstyle' 'flat'

will achieve this effect.

To apply a defined effect (such as an opacity or SVG shadow filter) to the text, give the effect id here:

ch.AddEffect 'XLabels' 'opacity:0.5'

You can add multiple effects to apply several filters.

See also ...

CaptionStyle – caption style | LabelLinespacing

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Linegraph Style

Linegraph Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'XYPlot,lines,risers'

Keyword | Description
XYPlot | Treat the first column of data as X-values
Relative | Relative data (to be accumulated as it is plotted)
Index | Index to starting value=100 for all series
Forcezero | Both axes will include the origin
Trend | An exponentially weighted trend line is drawn through the data
Growth | An exponential growth curve is fitted to the data
Ontop | The trend or modelfit is drawn on top of the data values
Model | A regression line (default is linear) is drawn through the data
Annotate | Annotate modelfit with coefficients
Lines | Points are connected with lines
Curves | Connecting lines are drawn as smooth curves
Markers | Markers are drawn at points
Risers | Verticals are drawn up from the x-axis
Surface | Chart is shaded from the line down to the X-axis
Filled | Each line is completed back to its starting point, then shaded in
Segmented | Lines are broken wherever missing values are encountered
Clipped | Lines are broken and markers removed at axis limits
Clamped | Lines follow chart boundary when data is clipped
Cells | Cells are created for use by Newcell when plotting miniatures
Halo | Markers have a halo underlying them to make them stand out from axes and grids
Axes:NoAxes | Axes are drawn
Values | Values are written at all markers
Arrow | Arrowheads are drawn at the end of each line
Framed | Framed axes (completed across the top and down the side)
Exploded | Axes are set back from the chart area
Grid | Gridlines are drawn on both axes

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Plot – line graphs


Rain graphics: Lines – line-style cycle

Lines – line-style cycle

When you plot several data series, RainPro will work through a standard sequence of line-styles, colours, shading patterns, markers and so on. These series have been intentionally chosen to be of varying lengths to reduce the chance of any two data-series being plotted in the same combination.

To over-ride the line-style series:

ch.Set 'lines' 'dot,dash,solid'
ch.Set 'lines' 2 3 4 112

You can give style names or numeric values here. These should be in the range 0-6 to select from the standard styles, or numbers above 6 which are the ids of custom styles.

The cycle will persist from the point where you set it, until you set this property again – this allows you to set it once only for a series of several plotting calls.

See also ...

ch.DefineDash | Colours | Markers | Nibs | Patterns | Line

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Locale – for formatted dates or times

Locale – for formatted dates or times

When a date or time format is set, RainPro defaults to generating the formatted value in the style for your default locale. To have a server application use a different format (e.g. to create a date suitable for the locale passed in the HTTP header) you may set the locale as a simple decimal integer.

ch.Set 'locale' 1035

This example will format dates and times in Finnish, regardless of the setup of your machine.

Language table

Hex | Dec | Locale
0000 | 0 | Language Neutral
0400 | 1024 | Process or User Default Language
0800 | 2048 | System Default Language
0436 | 1078 | Afrikaans
041c | 1052 | Albanian
0401 | 1025 | Arabic (Saudi Arabia)
0801 | 2049 | Arabic (Iraq)
0c01 | 3073 | Arabic (Egypt)
1001 | 4097 | Arabic (Libya)
1401 | 5121 | Arabic (Algeria)
1801 | 6145 | Arabic (Morocco)
1c01 | 7169 | Arabic (Tunisia)
2001 | 8193 | Arabic (Oman)
2401 | 9217 | Arabic (Yemen)
2801 | 10241 | Arabic (Syria)
2c01 | 11265 | Arabic (Jordan)
3001 | 12289 | Arabic (Lebanon)
3401 | 13313 | Arabic (Kuwait)
3801 | 14337 | Arabic (U.A.E.)
3c01 | 15361 | Arabic (Bahrain)
4001 | 16385 | Arabic (Qatar)
042b | 1067 | Windows 2000/XP: Armenian. This is Unicode only.
042c | 1068 | Azeri (Latin)
082c | 2092 | Azeri (Cyrillic)
042d | 1069 | Basque
0423 | 1059 | Belarusian
0402 | 1026 | Bulgarian
0455 | 1109 | Burmese
0403 | 1027 | Catalan
0404 | 1028 | Chinese (Taiwan)
0804 | 2052 | Chinese (PRC)
0c04 | 3076 | Chinese (Hong Kong SAR, PRC)
1004 | 4100 | Chinese (Singapore)
1404 | 5124 | Windows 98/Me, Windows 2000/XP: Chinese (Macau SAR)
041a | 1050 | Croatian
0405 | 1029 | Czech
0406 | 1030 | Danish
0465 | 1125 | Windows XP: Divehi. This is Unicode only.
0413 | 1043 | Dutch (Netherlands)
0813 | 2067 | Dutch (Belgium)
0409 | 1033 | English (United States)
0809 | 2057 | English (United Kingdom)
0c09 | 3081 | English (Australian)
1009 | 4105 | English (Canadian)
1409 | 5129 | English (New Zealand)
1809 | 6153 | English (Ireland)
1c09 | 7177 | English (South Africa)
2009 | 8201 | English (Jamaica)
2409 | 9225 | English (Caribbean)
2809 | 10249 | English (Belize)
2c09 | 11273 | English (Trinidad)
3009 | 12297 | Windows 98/Me, Windows 2000/XP: English (Zimbabwe)
3409 | 13321 | Windows 98/Me, Windows 2000/XP: English (Philippines)
0425 | 1061 | Estonian
0438 | 1080 | Faeroese
0429 | 1065 | Farsi
040b | 1035 | Finnish
040c | 1036 | French (Standard)
080c | 2060 | French (Belgian)
0c0c | 3084 | French (Canadian)
100c | 4108 | French (Switzerland)
140c | 5132 | French (Luxembourg)
180c | 6156 | Windows 98/Me, Windows 2000/XP: French (Monaco)
0456 | 1110 | Windows XP: Galician
0437 | 1079 | Windows 2000/XP: Georgian. This is Unicode only.
0407 | 1031 | German (Standard)
0807 | 2055 | German (Switzerland)
0c07 | 3079 | German (Austria)
1007 | 4103 | German (Luxembourg)
1407 | 5127 | German (Liechtenstein)
0408 | 1032 | Greek
0447 | 1095 | Windows XP: Gujarati. This is Unicode only.
040d | 1037 | Hebrew
0439 | 1081 | Windows 2000/XP: Hindi. This is Unicode only.
040e | 1038 | Hungarian
040f | 1039 | Icelandic
0421 | 1057 | Indonesian
0410 | 1040 | Italian (Standard)
0810 | 2064 | Italian (Switzerland)
0411 | 1041 | Japanese
044b | 1099 | Windows XP: Kannada. This is Unicode only.
0457 | 1111 | Windows 2000/XP: Konkani. This is Unicode only.
0412 | 1042 | Korean
0812 | 2066 | Windows 95, Windows NT 4.0 only: Korean (Johab)
0440 | 1088 | Windows XP: Kyrgyz.
0426 | 1062 | Latvian
0427 | 1063 | Lithuanian
0827 | 2087 | Windows 98 only: Lithuanian (Classic)
042f | 1071 | FYRO Macedonian
043e | 1086 | Malay (Malaysian)
083e | 2110 | Malay (Brunei Darussalam)
044e | 1102 | Windows 2000/XP: Marathi. This is Unicode only.
0450 | 1104 | Windows XP: Mongolian
0414 | 1044 | Norwegian (Bokmal)
0814 | 2068 | Norwegian (Nynorsk)
0415 | 1045 | Polish
0416 | 1046 | Portuguese (Brazil)
0816 | 2070 | Portuguese (Portugal)
0446 | 1094 | Windows XP: Punjabi. This is Unicode only.
0418 | 1048 | Romanian
0419 | 1049 | Russian
044f | 1103 | Windows 2000/XP: Sanskrit. This is Unicode only.
0c1a | 3098 | Serbian (Cyrillic)
081a | 2074 | Serbian (Latin)
041b | 1051 | Slovak
0424 | 1060 | Slovenian
040a | 1034 | Spanish (Spain, Traditional Sort)
080a | 2058 | Spanish (Mexican)
0c0a | 3082 | Spanish (Spain, Modern Sort)
100a | 4106 | Spanish (Guatemala)
140a | 5130 | Spanish (Costa Rica)
180a | 6154 | Spanish (Panama)
1c0a | 7178 | Spanish (Dominican Republic)
200a | 8202 | Spanish (Venezuela)
240a | 9226 | Spanish (Colombia)
280a | 10250 | Spanish (Peru)
2c0a | 11274 | Spanish (Argentina)
300a | 12298 | Spanish (Ecuador)
340a | 13322 | Spanish (Chile)
380a | 14346 | Spanish (Uruguay)
3c0a | 15370 | Spanish (Paraguay)
400a | 16394 | Spanish (Bolivia)
440a | 17418 | Spanish (El Salvador)
480a | 18442 | Spanish (Honduras)
4c0a | 19466 | Spanish (Nicaragua)
500a | 20490 | Spanish (Puerto Rico)
0430 | 1072 | Sutu
0441 | 1089 | Swahili (Kenya)
041d | 1053 | Swedish
081d | 2077 | Swedish (Finland)
045a | 1114 | Windows XP: Syriac. This is Unicode only.
0449 | 1097 | Windows 2000/XP: Tamil. This is Unicode only.
0444 | 1092 | Tatar (Tatarstan)
044a | 1098 | Windows XP: Telugu. This is Unicode only.
041e | 1054 | Thai
041f | 1055 | Turkish
0422 | 1058 | Ukrainian
0420 | 1056 | Windows 98/Me, Windows 2000/XP: Urdu (Pakistan)
0820 | 2080 | Urdu (India)
0443 | 1091 | Uzbek (Latin)
0843 | 2115 | Uzbek (Cyrillic)
042a | 1066 | Windows 98/Me, Windows NT 4.0 and later: Vietnamese

See also ...

DateFormat – picture specification | TimeFormat – picture specification

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: MarginBottom – chart margin (bottom)

MarginBottom – chart margin (bottom)

To set the bottom margin:

ch.Set 'Mbottom'  36

This allows space (in points) for the X-axis caption, and the chart legend if you leave it in its default position.

See also ...

Glossary of Terms | Margins – chart margins (tblr)

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: MarginLeft – chart margin (left)

MarginLeft – chart margin (left)

To set the left margin:

ch.Set 'Mleft'  48

This allows space (in points) for the Y-axis labels and caption. If you have very large values to show here, you will almost certainly need to increase this value.

See also ...

Glossary of Terms | Margins – chart margins (tblr)

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: MarginRight – chart margin (right)

MarginRight – chart margin (right)

To set the right margin:

ch.Set 'MRight'  48

This allows space (in points) from the end of the X-axis to the edge of the chart region. It is set by default to a small value, so you will need to increase it (say to 48 points) if you have a duplicate or right-hand Y-axis.

See also ...

Glossary of Terms | Margins – chart margins (tblr)

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Margins – chart margins (tblr)

Margins – chart margins (tblr)

To set all four margins in a single call:

ch.Set 'Mgn' 48 24 36 12

The numbers give the top, bottom, left, right margin settings in points. This property sets the same internal values as the ‘hmar’ and ‘vmar’ properties.

You should leave room for the heading at the top and the X-axis labels and title at the bottom. You may want to increase the left margin if you have big numbers to accommodate in your Y-axis labels. If you only give one number, all four margins are set to this value. They measure from the edge of the chart area to the edge of the plotting region, i.e. the rectangle bounded by the axes.

See also ...

Glossary of Terms


Rain graphics: MarginTop – chart margins (top)

MarginTop – chart margins (top)

To set the top margin:

ch.Set 'Mtop'  36

This allows space (in points) for the chart heading and sub-heading. You will probably need to increase it if you have a heading that spans more than 2 lines. If you use left or right aligned headings for Pie or Polar charts, you can probably reduce this to zero as the headings will not clash with the chart in this case.

See also ...

Glossary of Terms | Margins – chart margins (tblr)

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: MarkerScale – marker scale

MarkerScale – marker scale

Allows markers to be scaled independently of the current line weight. Scaled markers are always drawn as vector graphics, rather than icons.

ch.Set 'mscale' 1.5

This may be a scalar or a vector matching the shape of the data, in which case each marker is individually scaled. Suitable for incidence plots where the xy is the location of the outbreak and the scale can show the number of cases; here you would probably scale with the square-root of the count so that the area of the marker was a good visual guide to the density of the data.

See function Ammonite for an example. In this case the markers are scaled roughly in proportion to the radius.

ch.Set('style' 'noline,grid')
ch.Set ('mark' 14)
ch.Set ('mscale'((⍳14)*.75))
ch.Polar⍳14
PG←ch.Close

The circular markers (9 to 13) can be used effectively here, and the 3D markers work particularly well in VML output, as the native ‘gradient fill’ capabilities of VML may be used to shade them.


Rain graphics: Markers – marker cycle

Markers – marker cycle

When you plot several data series RainPro will work through a standard sequence of colours, shading patterns, markers and so on. These series have been intentionally chosen to be of varying lengths to reduce the chance of any two data-series being plotted in the same combination.

To over-ride the marker series:

ch.Set 'marker' 2 3 4 112
ch.Set 'marker' 'Cross,Plus,Diamond'

Note that you can give names or numeric values here. These should be in the range 0-15 to select from the standard markers, or numbers above 15 which are the ids of user-defined markers.

See also ...

ch.DefineMarker – define markers | Chart Marker Cycle

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Min-Max Style

Min-Max Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'grid,errorbar'

Keyword | Description
XYPlot | The first column of data is taken as the X-values (or as Y-values for a horizontal plot)
Forcezero | Both axes must include the origin
Filled | The envelope made by the lines is filled as a band
Drift | Only the markers/arrows/errorbars at the ‘far’ end are drawn
Plain | No decorations are applied to the lines
Terminated | The current marker is appled to both ends of the line
Errorbars | The lines are decorated top and bottom with ‘T’ pieces to form errorbars.
Arrows | Arrowheads are drawn on the lines (at both ends unless the line starts from zero).
Axes:NoAxes | Axes are drawn
Framed | Framed axes (completed across the top and down the sides)
Exploded | Axes are set back from the chart area
Grid | Gridlines are drawn on both axes
Values | Value tags are added at both ends of the lines
Vertical | Lines are drawn parallel to the Y-axis
Horizontal | Lines are drawn parallel to the X-axis

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Vline – Hi-Lo plots


Rain graphics: Not Applicable – placeholder for missing value

Not Applicable – placeholder for missing value

By default, tables show missing values as “ – “ which may be reset with this property:

ch.Set 'NApp'  'n/a'

This will be shown in the case of a Cross-tab where no data is found for the particular combination of group and category which intersects at each cell.

See also ...

ch.Table – table charts | MissingValue – missing value(s)

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Nibs – nib weight cycle

Nibs – nib weight cycle

When you plot several data series RainPro will work through a standard sequence of colours, shading patterns, markers and so on. These series have been intentionally chosen to be of varying lengths to reduce the chance of any two data-series being plotted in the same combination. By default, all lines are drawn using the same line thickness (fine).

To over-ride the nib weight cycle:

ch.Set 'nibs' 'fine,medium'
ch.Set 'nibs' 2.1 3 2.2

You can give names or numeric values here. The numbers give the line-thickness in points.

The cycle will persist from the point where you set it, until you set this property again – this allows you to set it once only for a series of several plotting calls.

See also ...

Colours | Lines | Markers | Patterns | Nib

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: NoteLinespacing

NoteLinespacing

You may set the line-spacing for multi-line notes:

ch.Set 'NVspace'  110

The pitch may be given as a percentage, a factor of the font size, or an absolute distance in points. The default value is 120% of the font size.


Rain graphics: NoteNudge – Nudge note position

NoteNudge – Nudge note position

This property may be used to provide a fine adjustment (in points, always) to notes positioned using chart co-ordinates. This might be used to set an offset (in terms of font size) to notes used to label a subset of data-points. You could give the note position as the exact data value, and apply a ‘nudge’ of (6,6) for a note in 12-point text to get a better presentation.

ch.Set 'NNudge'  6 12

This property is also useful when labelling datum-lines, as by default the label would be written baselined exactly on the line, which looks untidy. A ‘nudge’ of (0,6) will adjust it upwards, leaving the letters clear of the line. If the y-value is omitted, zero is assumed.

See also ...

ch.Note – add chart notes | ch.TextWidth – measure text | XDatum – X-datum lines | YDatum – Y-datum lines

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: OrderOfFit – polynomial degree of modelfit

OrderOfFit – polynomial degree of modelfit

When you set the ‘Modelfit’ style on a scatterplot or line graph, the default is to draw a simple linear fit and determine the origin and slope of the line. Adding ‘Annotate’ to the style causes RainPro to append a note of these values to the line. To change the order of fit (e.g. to put a cubic curve through the points):

ch.Set 'Order' 3

The values may only be in the range 1-4 here.

Fitting models to 3D data

When the modelfit style is used with 3D data in a cloud chart, you may choose different values for the order of fit in the X and Y directions. For example if you think your data should be linear in X but possibly quadratic in Y, choose:

ch.Set 'Order'  1 2

Either value may be zero here, which effectively states that there is no relationship expected between the Z-values and the values on that axis. If both values are zero, a horizontal plane is plotted, showing the average Z-value.

See also ...

ch.Cloud – 3D scatter plots | Coefficients – parameters from modelfit

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: PageLabels – page labels

PageLabels – page labels

Intended for use in 2D slices of nD datasets, where the charts page through the dimensions. Page labels are given as a comma-separated list, or a vector of text vectors, with one element per dimension. They are drawn in the axis caption font in columns in the top left corner of the chart area.

ch.Set('mtop' 56)    ⍝ Space for 3 page labels
ch.Set('PLAB' 'France,Petfood,Budget,Junk')

See Barchart (in the RainPro workspace) for an example of use.

The page labels report a hotspot with id ‘Pagelabels’ and a hotspot counter giving the specific label you hit. Your software could use this (for example) to put up a popup menu allowing the user to pick from the items of that dimension.

Use the CaptionLineSpacing property to control the vertical spacing of page labels.


Rain graphics: Patterns – pattern cycle

Patterns – pattern cycle

When you plot several data series, or use a pie chart, RainPro will work through a standard sequence of colours, shading patterns, markers and so on. These series have been intentionally chosen to be of varying lengths to reduce the chance of any two data-series being plotted in the same combination.

To over-ride the pattern series:

ch.Set 'patterns' 3 2 34
ch.Set 'patterns' '10%,basket,solid'

Note that you can give names or numeric values here. These should be in the range 0-39 to select from the standard patterns, or numbers above 40 which are the ids of custom tiles or gradient fills. The simple plain half-tones are generally best for normal use. Linear gradients are effective tools in barcharts, and radial gradients can work well with polar and pie charts.

The cycle will persist from the point where you set it, until you set this property again – this allows you to set it once only for a series of several plotting calls.

See also ...

ch.DefineTile | Colours | Lines | Markers | Nibs | Shading

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Perspective – perspective distortion (3D charts)

Perspective – perspective distortion (3D charts)

To get a good feel for the depth of a 3D chart it is essential to have a small degree of perspective distortion in the projection. This is controlled by how far away from the plot the ‘camera’ is placed – in RainPro the default is 12, meaning 12 chart-widths back from the virtual 3D image. To reduce the distortion, make this a big number (above 50 you will find that all the verticals become vertical); to increase it, move the ‘camera’ towards the plot.

ch.Set 'Perspective' 20   ⍝ Move back

You will find that 7 is about as close as you can reasonably go without producing very exaggerated effects. Numbers less than this will start to give spurious ‘inside-out’ views and (eventually) strange errors.

Isometric Projections

To make an Excel-style 3D chart, you should set the perspective to 0 which generates an isometric view, rather than a true perspective image. This can be used with the Towerchart to make simple ‘column charts’ in Excel style.


Rain graphics: PieCentre – piechart centre

PieCentre – piechart centre

To place the piechart at a specific (x,y) position on the page:

ch.Set 'Piecentre' 50 60

The position is given in points on a co-ordinate system running from the bottom left-hand corner of the plotting region (the area inside the 4 margins).


Rain graphics: PieStartangle – angle of first sector

PieStartangle – angle of first sector

By default, piecharts are drawn clockwise from 12:00. This property may be used to start at any position:

ch.Set 'PStart' 90

The only commonly used alternative value is 90 to start the pie at the 3:00 position.


Rain graphics: Piechart Style

Piechart Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style.

ch.Set 'style' 'values'

Keyword | Description
Values | Data values are appended to spider tags
Spider | Keys are treated as spider tags in collections of small pies
Plain | The radial lines from the sectors to the tags are omitted
FarthestFirst | Sectors are drawn from the back to enable 3D extrusion

If you use Xlabels and Values here, you may set a Value format such as “#0% XL” to merge them together cleanly. The default is to append the value to the label, separated by a colon.

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Pie – piecharts


Rain graphics: Polarchart Style

Polarchart Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'lines,risers'

Keyword | Description
XYPlot | Treats first column of data as x-values (direction)
Time | X-values are taken as hours on a 24-hr clock
Compass | X-values are taken as degrees
Relative | Relative data (series are accumulated)
Forcezero | The radial axis is forced to include the origin
Centre | The centre of the chart is marked with a dot
Lines | The points are connected with lines
Markers | Markers are drawn at points
Risers | Radial lines are drawn from the centre to each point
Surface | Surface shading is drawn from each line to the centre
Grid | Radial and circular gridlines are drawn
Hollow centre | Radial gridlines stop at innermost tickmark
Arrows | Arrows are drawn from the centre to each data point

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Polar – polar charts


Rain graphics: QF – format specification

QF – format specification

By default, numeric axis labels are formatted with the normal APL format primitive. You can either format these yourself and pass them as text to ch.Set 'XLabs' or it may be more convenient to have RainPro format them for you. The easy way is to use the appropriate ‘picture’ format for the axis in question, but there may be the occasional need for more complex format strings. In this case you pass any valid ⎕FMT string here, and the numbers will be formatted appropriately. This applies across all axes and the value-tags for xy plots and piecharts.

ch.Set 'QFmt' 'F8.2'

Please note that no error trapping is done here, so invalid format strings will cause DOMAIN ERRORs in the RainPro function which attempts to apply them.

See also ...

XFormat – X-axis format-picture | YFormat – Y-axis format-picture | ZFormat – Z-axis format

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Range Style

Range Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style.

ch.Set 'style' 'relative'

Keyword | Description
Relative | Accumulate series values
Forcezero | Include zero in all axes

The checkboxes in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.


Rain graphics: ResetOptions – modify reset behaviour

ResetOptions – modify reset behaviour

Normally, a Reset sets all the chart properties (including keys and the various colour and pattern cycles) back to the initial state. You can use the ‘Reset options’ to have either keys or cycles persist through a Reset:

ch.Set 'RStyle'  'key'

Options

keys:nokeys | Keys persist through a chart reset
cycle:nocycle | Colour, line, marker, nib and pattern cycles persist

This can be useful when you have a series of independent miniature charts which share a common key.


Rain graphics: Residuals – differences between data and fit

Residuals – differences between data and fit

This is a read-only property which is maintained for you by RainPro to allow you to use the ‘modelfit’ style and then plot the residuals for each datapoint as an extra chart. You may like to overlay a frequency histogram to check that the residuals are normally distributed.

coeff←ch.Query 'Residuals'

The result will be a numeric vector with one value for each value in the fitted data. Where missing values were marked in the input data, there will be corresponding missing values in the computed result, so that the original and fitted series always match exactly in length.

See also ...

OrderOfFit – polynomial degree of modelfit


Rain graphics: Response Surface Style

Response Surface Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'walls,tiled'

Keyword | Description
Grid | Gridlines are drawn on the XY-plane and the backplanes
Walls | The backplanes are shaded to form walls
Forcezero | All axes must include the origin
Lines | Points are connected by lines to form a mesh
Markers | Markers are drawn at all points
Risers | Lines are drawn upward from the XY-plane
Contours | Contours are drawn at Z-tickmarks
Halo | Markers are drawn with a halo to improve visibility and 3D effect
Tile | Tile surface using the current pattern
Altitude | Altitude shading of tiles (pattern is automatically varied)
Axes:NoAxes | Axes are drawn

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Resp – response surface plots


Rain graphics: Scatterplot Style

Scatterplot Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'markers,trend'

Keyword | Description
Forcezero | Both axes must include the origin
Trend | An exponentially smoothed trend is drawn through the data
Model | A regression model is drawn through the data (linear by default)
Growth | An exponential growth curve is fitted to the data
Contour | Contours are drawn if numeric data-values are available
Annotate | The model coefficients are written next to the fitted line
Markers | Markers are drawn at the data points
Risers | Verticals are drawn from x-axis
Cells | Cells are created for use by Newcell
Halo | Halo markers to improve visibility
Axes:NoAxes | Axes drawn
Framed | Framed axes (completed across the top and down the sides)
Exploded | Axes are set back from the chart area
Values | Data values are written at the markers
Clipped | Markers are not drawn outside axis limits
Arrows | Arrows are drawn upwards from the x-axis to each point
Grid | Gridlines are drawn on both axes

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Scatter – x/y scatter plot


Rain graphics: SoftHyphen – optional line-breaks

SoftHyphen – optional line-breaks

By default, RainPro uses the tilde character ‘~’ as an optional word-break point in wrapped text, so that a word such as ‘Con~trib~ution’ could appear as:

Con-
tribution

or as

Contrib-
ution

or as

Contribution

... depending on the available width. If you require the ‘~’ character as normal text, you could do your own wrapping, or you could switch to a different soft hyphen with:

ch.Set 'SHyphen '@'

or any other suitable character or list of characters.

See also ...

ch.Note – add chart notes


Rain graphics: Stepchart style

Stepchart style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'values,floating'

Keyword | Description
Values | Write value tags on each horizontal section
Risers | Draw verticals from the X-axis at each value change
Floating | Do not shade from the line down to the X-axis
Forcezero | Both axes must include the origin
Axes:NoAxes | Axes are drawn
Frame | Framed axes (completed across the top and down the side)
Exploded | Axes are set back from the chart area
Grid | Gridlines are drawn on both axes

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Step – step charts


Rain graphics: Subhead – chart subheading

Subhead – chart subheading

You can make a second heading line by specifying a subhead:

ch.Set 'Sub' 'This is a subordinate heading'

The font and size are set by the SubheadFont property. The alignment and positioning are determined by the style of the main heading. Lines may be split with semi-colons as for the main heading.


Rain graphics: SubheadFont – subhead font

SubheadFont – subhead font

To set the font and colour for the secondary chart heading:

ch.Set 'Sfont' 'tib,14,green'

The remaining subhead attributes are shared with the main heading.

See also ...

Fonts – defining and using short codes


Rain graphics: Table Style

Table Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'spanned,grid,right'

Keyword | Description
Spanned | Span titles across empty cells
Gridlines | Rule horizontally and vertically between cells
Shadowed | Draw a drop-shadow under the table
Rounded | Round the table corners
Filled cells | Use current Colour and Pattern cycles to shade cell background
FitWidth | Scale the completed table to frame width (inside margins)
Relative:Absolute | Position table using points or chart co-ordinates
Left:Centre:Right | Automatic positioning when position not given
Rows:Columns | Table is transposed when data is presented row by row
Ascending | Groups are sorted upwards
Downward | Groups are sorted downward
AsIs | Groups take the unique values in order of first appearance in the data

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.


Rain graphics: Tower Aspect - shape of tower base

Tower Aspect – shape of tower base

Towers are always drawn by default on a square base. To override this:

ch.Set 'TAspect' 2

This will stretch the towers in the y-direction, making them abut in this plane.


Rain graphics: Tower patterns - shading for faces

Tower patterns – shading for faces

By default, the three faces of each tower are shaded in patterns (1,4,2) for (Top,Face,Edge) respectively. This gives an illusion of lighting from the usual upper-left corner. However it is possible to use your choice of pattern here, for example:

ch.Set 'Towers' 'Bricks,Basket,Solid'

Note that you can give pattern names or numeric values here:

ch.Set 'Towers' 2 24 12

Numbers should be in the range 0-39 to select from the standard patterns, or above 40 which are the ids of custom tiles or gradient fills. Linear gradients can be used to good effect here with SVG and VML output – patterns 2,24,15 give a nice effect when used together.

This could also be used (typically with VML) to apply a bitmap surface to the towers.

See also ...

Shading Patterns


Rain graphics: Table position – xpos,ypos,optional width

Table position – xpos,ypos,optional width

To place the table at a specific (x,y) position on the page and optionally set the maximum width:

ch.Set 'Txy' 50 60

For style ‘absolute’, the position is given in points on a co-ordinate system running from the bottom left-hand corner of the plotting region (the area inside the 4 margins). For style ‘relative’ (the default) the axes of the current chart are used to position the table. The (x,y) pair is the location of the top-left corner of the table, in either case.


Rain graphics: Tease – separation of scatter plots

Tease – separation of scatter plots

This property is designed to let you ‘tease out’ a 3rd dimension from a scatter-plot to show the effect of a category variable.

ch.Set'Head' 'Yield vs Farm, teased by Year'
ch.Set('style' 'boxed')('xs' 'grid')('ma' 'lozenge')('tease' 6)
ch.Scatter yield vs farm by year

This effectively adds a 3rd dimension to the normal 2-D scatter plot by pulling the categories apart in the X-direction. The ‘tease’ value is the distance in points to separate each category; the separated categories are teased symmetrically about each x-value. If you have a large number of categories, you will need to use a low value here to prevent adjacent groups merging into one another.

See also ...

ch.Boxplot – box and whisker charts | CategoriseBy – category variable

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: TimeFormat – picture specification

TimeFormat – picture specification

When the X-axis is set to style ‘Time’ or ‘Date,Time’ the time portion of the axis labels may be formatted with a simple picture format such as:

ch.Set 'tpic' 'HH:mm-ss'

To label the tickmarks ‘14:12-34’ and so on.

The time specification in detail

The following table is taken from the Microsoft documentation for the GetTimeFormat API call, and is common to all Windows applications which use it:

Picture | Meaning
h | Hours with no leading zero for single-digit hours; 12-hour clock
hh | Hours with leading zero for single-digit hours; 12-hour clock
H | Hours with no leading zero for single-digit hours; 24-hour clock
HH | Hours with leading zero for single-digit hours; 24-hour clock
m | Minutes with no leading zero for single-digit minutes
mm | Minutes with leading zero for single-digit minutes
s | Seconds with no leading zero for single-digit seconds
ss | Seconds with leading zero for single-digit seconds
t | One character time marker string, such as A or P
tt | Multicharacter time marker string, such as AM or PM

If you use spaces to separate the elements in the format string, these spaces will appear in the same location in the output string. The letters must be in uppercase or lowercase as shown (for example, “ss”, not “SS”). Characters in the format string that are enclosed in single quotation marks will appear in the same location and unchanged in the output string.

See also ...

DateFormat – picture specification | Locale – for formatted dates or times

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Tips – adding popup tips to data values

Tips – adding popup tips to data values

You can use this to set a list of tips to be shown as popups when the mouse is over any data-point. This is implemented for HTML pages output as VML or as mapped images.

ch.Set 'Tips' 'One' 'Two' 'Three'

A typical use would be for a scatter-plot where extra information about each data point could be shown to the user. To show tips on multiple data series, pass an array of tip values which match exactly the structure of the data.

ch.Set 'Tips' (2 3⍴'One' 'Two' 'Three' 'Four' 'Five' 'Six')

You must set tips for all the data-points if you use this property – if you only want to set tips on a small selection of points consider calling ch.Tip instead, as this can be called repeatedly to set tips on individual points.

See also ...

ch.Tip – supply pop-up tips for data points | Hints – apply hints to data values

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: TitleBar – document title

TitleBar – document title

By default, RainPro picks up the first heading in the document and uses this as the ‘title’ of the chart. To over-ride this:

ch.Set 'TBar' 'Custom title'

The title is used in the browser titlebar (for SVG output), as the document title in a saved PDF, and as the visible title in the placeholder box of an EPS when it is imported into MS Word or other publishing tool.


Rain graphics: Towerchart Style

Towerchart Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style.

ch.Set 'style' 'walls,forcezero'

Keyword | Description
Grid | Gridlines are drawn on the XY-plane and the walls
Walls | The backplanes are shaded to form walls
Forcezero | Zero is included in all axes
Ascending | Groups are sorted upwards
Downward | Groups are sorted downward
AsIs | Groups take the unique values in order of first appearance in the data
Flat | All labels are drawn with horizontal text

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Tower – tower charts


Rain graphics: TowerLimit – towerchart limit

TowerLimit – towerchart limit

This parameter simply prevents ‘runaway’ towercharts if you accidentally plot a silly amount of data (for example you forgot a ‘where’ setting on a big database, or omitted a grouping command):

ch.Set 'tl' 500

The default is set to 200, which is the total number of data items above which towercharts will simply generate a blank page with an error message.

See also ...

BarLimit – barchart limit


Rain graphics: Tracechart Style

Tracechart Style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'surface'

Keyword | Description
Lines | Lines only are drawn
Surface | Each line is shaded down to its own inner axis
Kite | Data is mirrored about each inner axis and shaded to make a kite diagram
Axes:NoAxes | Axes are drawn
Framed | Framed axes (the main X and Y axes are completed to form a frame)
Grid | Gridlines are drawn on X and Y axes

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.

See also ...

ch.Trace – trace charts


Rain graphics: Trellis – trellis of small charts

Trellis – trellis of small charts

When plotting sections through high-dimensional datasets it is often convenient to make a series of small plots in a rectangular grid. To carve the chart area into a grid of 3 rows and 4 columns:

ch.Set 'Trellis' 3 4

If you simply have a set of charts to plot in a grid, you can leave RainPro to calculate the layout:

ch.Set 'Trellis' 13

... this will divide the available space as effectively as possible to lay out 13 small plots. The cells will be used in row-major order by default; use ch.Set 'tstyle' 'snaking'to work down the columns. See ch.NewCell/jump> for details on how to move from cell to cell.

To have RainPro skip to a new cell automatically for every plotting call, set the TrellisStyle to ‘skip’.

See also ...

ch.RangeAxes – set axis ranges | TrellisStyle – trellis style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: TrellisStyle – trellis style

TrellisStyle – trellis style

When a series of miniature charts is arranged in a trellis layout, the default is to require an explicit call to ch.NewCellto move between cells. This is to allow you to draw several data-series on the same axis set in each cell. If you only require a single chart in each cell, you can set the trellis style ‘skip’ which skips on to the next cell after every chart.

ch.Set 'TStyle ' skip'
ch.Trellis 2 3
:for ct :in 1 2 3 4 5 6
  ch.Plot mat[ct;;]
:end

The normal ordering of the cells is to work across the columns, then down the rows. To switch this to work down the columns, you can set the ‘snake’ style:

ch.Set 'TStyle' 'snake'

The default is to have any properties set on the first chart (headings, axes etc.) apply to the entire set. This is what you would expect for a simple ‘small multiple’ layout. However if you are using the trellis simply as a way of arranging a collection of unrelated small charts, set the ‘reset’ style to have all properties (except ‘reset’!) put back to default between each chart. This saves an explicit call to ch.Resetwithin the plotting loop.

ch.Set 'ts' 'reset'

Finally, you can set the style to ‘Paged’ to have RainPro output one chart per page (rather than one per cell) when you use a Multiple plot.

See Thumbnails, SmallMultiple and MultiTrellis (in the RainPro workspace) for some sample code.

See also ...

ch.Multiple – small multiples | Gutter – chart gutter | Trellis – trellis of small charts

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: TypeOfChart – chart type

TypeOfChart – chart type

Chart types correspond to the standard plotting commands Plot, Bar and so on. This is used to preset the type of plot before running an automatic multiple plot:

ch.Set 'Type' 'Bar'
ch.Multiple sales by region

This will generate a trellis, or set of pages (depending on the trellis style) with one barchart for each sales region.

See also ...

Managing Multiple Plots | ch.Multiple – small multiples | TrellisStyle – trellis style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ValueNudge – Nudge value positions

ValueNudge – Nudge value positions

This property may be used to provide a fine adjustment (in points, always) to value tags.

ch.Set 'VNudge'  6 12

All tags will be adjusted by the same amount (value gives the offset in the horizontal and vertical directions). A single number will move all value tags diagonally by this amount.


Rain graphics: ValueLinespacing

ValueLinespacing

You may set the line-spacing for multi-line value tags:

ch.Set 'VVspace'  120

The pitch may be given as a percentage, a factor of the font size, or an absolute distance in points. The default value is 110% of the font size.


Rain graphics: ValueFormat – value-tag picture-format

ValueFormat – value-tag picture-format

Numeric value tags may be formatted with a simple picture format such as:

ch.Set 'vpic' '##0.00%'

To show the tags to 2 decimal places with a trailing % symbol. When contour lines are drawn on scatterplots, this format specification is used to create the labels on each line.

Piecharts

This format specification is also used for the numeric sector labels on piecharts if you set the ‘values’ style here. You can also use a simple format such as ‘XXXXXXX;’ to get text labels wrapped into a limited width, or ‘XXXXXX’ which will simply truncate them, suffixed with an ellipsis if necessary.

In addition, you may want to merge the sector labels with the sector values. You can do this with a format such as ‘The XL = ##0’ which will take each sector in turn and substitute the corresponding label into the value string at the XL marker.

See also ...

Picture formatting


Rain graphics: ValueAngle - rotation of value tags

ValueAngle – rotation of value tags

When you set the Value tags to be angled, the default angle is 34 degrees. You can set this to any value from 0-360 with ...

ch.Set ('VS' 'angled')( 'VX' 45)

Angled tags are always drawn to the right of the data points, and multi-line tags are centred about the normal to the rotated baseline.

See also ...

ValueStyle – value-tag style


Rain graphics: Vector plot style

Vector plot style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'arrows'

Keyword | Description
Columns | The data matrix has 4 rows with one column per vector
Arrows | Arrows are drawn at each line-end
Middle | The arrows are drawn centred on each line
Exploded | The lines are shortens at both ends to leave gaps
Terminated | The lines are ended with the current marker

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.


Rain graphics: Venn Diagram style

Venn Diagram style

Styles are defined with a list of keywords, separated by commas. At a minimum, you need the first 4 letters of each word to activate the style. If a style is turned on by default (bold) it can be cancelled by prefixing the word with ‘no’ as in ‘noaxes’.

ch.Set 'style' 'surface'

Keyword | Description
Values | Area values are written
Filled | Circles are filled with colour at 50% opacity (recommended for SVG and VML only)
Redraw | Circle outlines are redrawn to appear solid

The checkboxes and radio-buttons in the style editor in GraPL (desktop) simply add and remove the appropriate keywords for you.


Rain graphics: Versus – scatter versus this

Versus – scatter versus this

Scatter plots can take a matrix of values, with the X-variable in column-1 and as many Y-variables as required in columns 2-n. It may be more convenient to specify the y-data as a simple vector and set the x-variable as a property:

ch.Set 'xvar' farm
ch.Scatter yield

This makes it very easy to experiment with different permutations of x and y data to try to visualise the relationships in a multi-dimensional dataset.

There is a simple cover function vs in the RainPro workspace to allow expressions like ch.Scatter yield vs variety – you can experiment with the infamous barley data using vs and by here!

See also ...

CategoriseBy – category variable | Tease – separation of scatter plots | YVar – 3D scatter versus this

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Viewpoint – viewpoint (3D charts)

Viewpoint – viewpoint (3D charts)

All 3D charts are pivoted in 3 planes about the far corner (where the XYZ axes meet). You can set the viewpoint as a 3-vector of [Roll, Pitch,Yaw] values about this point, but the values (coupled with the perspective distortion) interact in quite a strange way and it takes a while to get comfortable with the settings.

      ch.Query 'VI'
22 15 50

... is a good starting point. Values from 0⍎90 are acceptable as rotations in degrees. You cannot turn charts completely around or upside-down!


Rain graphics: Patterns – pattern cycle

Patterns – pattern cycle

By default, the three ‘walls’ forming the axes of the 3D charts are shaded in patterns 3,2,1 for the left wall (yz-plane), back wall (xz-plane) and floor (xy-plane) respectively. This gives an illusion of lighting from the usual upper-left corner. However it is possible to use your choice of pattern here, for example:

ch.Set 'Walls' 24 30 28

ch.Set 'Walls' 'Bricks,Basket,Solid

Note that you can give pattern names or numeric values here. These should be in the range 0-39 to select from the standard patterns, or numbers above 40 which are the ids of custom tiles or gradient fills. Linear gradients can be used to good effect here with SVG and VML output – patterns 24,30,28 shade diagonally into the back corner when used together.

This could also be used (typically with VML) to apply a bitmap surface to the backplanes.

See also ...

Shading Patterns


Rain graphics: Weighting - for regression models

Weighting – for regression models

Weighted regression – this may be used to weight the points in a modelfit.

ch.Set 'Weighting' 1 1 1 1 0.1 1

This would be appropriate if the data was aggregated, but with differing numbers of measurements contributing to each point. Also it may be used to exclude selected points from a model by simply weighting them as zero.

For points with errorbars, you might consider a weight varying as the sqrt of the error to have more certain points counting higher in the model.

See also ...

OrderOfFit – polynomial degree of modelfit


Rain graphics: Where – data selection

Where – data selection

This property allows you to mask out arbitrary data values.

ch.Set 'where' 1 1 0 1 0 0
ch.Plot 3 2 12 4 9 8

This can be useful if your data has come from a database table, for example Sales = region,month,qty. It may be convenient to make one call to ch.Plotfor each region, generating a ‘where’ mask from the region-code each time. Alternatively you could set region as the ‘category’ variable to have RainPro make the split for you.

See also ...

ch.RangeAxes – set axis ranges | MissingValue – missing value(s) | Window – data window

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Window – data window

Window – data window

The ‘Window’ property allows for easy programming of ‘switchover’ points in timeseries. Any points outside the given data window (applies to X-axis only) are treated as missing values, so they are used in the auto-ranging of the axes but are not actually plotted. This allows you to change style easily (for example to use dashed lines for the part of the series which is beyond the current month) in the middle of a single timeseries.

⍝ NB - window is 'inclusive' so the boundary point gets hit twice.
 ch.Set('Window' 0 sw)('Line' 'solid')
 ch.Plot mat
 ch.Set('Window'sw 0)('Line' 'Dash')
 ch.Plot mat

You will probably also want to set the markers to a cycle of the same length as the number of columns in mat so that the same markers are used in each part of the chart.

Note that the ‘Window’ is inclusive, so that the points on the boundary get plotted twice. See Switch 7 in the RainPro workspace for an example.


Rain graphics: XAngle – angle of X-labels

XAngle – angle of X-labels

When you set the X-labels to be angled, the default angle is 34 degrees. You can set this to any value from 0-360 with ...

ch.Set 'XS' 'angled'
ch.Set 'XA' 45

Angled labels are normally right-aligned on the tick marks for a lower x-axis and left-aligned on a top axis. This will be switched around if you use angles above 270 (which you may give as negative angles, such as -90 which is the same as 270). They will not be automatically thinned if the ticks get too crowded.


Rain graphics: XCaptionFont – font for X caption

XCaptionFont – font for X caption

This property selectively overrides the current (generic) setting for the caption fonts for the X-axis only.

ch.Set 'CXfont' 'ti,10,Maroon'

If you use this to override the generic caption font, be sure to set the generic property first.

See also ...

CaptionFont – font for all axis captions


Rain graphics: XFormat – X-axis format-picture

XFormat – X-axis format-picture

The X-axis labels may be formatted with a simple picture format such as:

ch.Set 'xpic' 'Week #0'

To label the tickmarks ‘Week 1’ ‘Week 2’ .... ‘Week 52’ as appropriate.

Wrapping text labels

Text labels may be wrapped into a preset width with a format such as:

ch.Set 'xpic' 'XXXXXX;'

To force the labels to wrap at the length of the given string. If the string is simply ‘XXXXXXX’ then longer labels are truncated, and end with ‘...’ to indicate this.

See also ...

DateFormat – picture specification | TimeFormat – picture specification | Picture formatting

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: XLabelFont – font for X labels

XLabelFont – font for X labels

This property selectively overrides the current (generic) setting for the label fonts for the X-axis only.

ch.Set 'LXfont' 'arb,8,Maroon'

If you use this to override the generic caption font, be sure to set the generic property first.

See also ...

LabelFont – label font


Rain graphics: XTickStyle – X-axis tickstyle

XTickStyle – X-axis tickstyle

The X-axis tickstyle sets the tickmark type to one of:

  • Outside (the default)
  • Inside (ticks drawn inside axes)
  • Crossing (ticks are drawn across the axis)
  • NoTicks

You may also use ‘Minor’ here to generate default minor tickmarks for this axis.

ch.Set 'XX' 'Crossing'

Inside ticks work best with ‘framed’ chart axes to keep everything within the data area.

See also ...

XStyle – X-axis style


Rain graphics: XZones – warning regions for X-axis

XZones – warning regions for X-axis

Used to set up warning regions on xy and dial charts. Each region is defined by a colour (use colour names or the standard HTML syntax here), the start and end values for the region and an optional pattern number.You may set this as a single string (use ‘/’ to separate each zone, and ‘,’ to separate the parameters within each zone) or as an array of strings, one for each zone:

ch.Set 'xzones' 'Green,1,3,2/Blue,10,12,3'
ch.Set 'xzones' 'Green,1,3,2' 'Blue,10,12,3'

If you only give a start value, the end value defaults to the ‘full-scale deflection’ on a dial chart and the highest tickmark on a conventional chart.

 ch.Set('xr' 200 800)('xt' 100,1)('xzone' 'Green,200,350/Red,750')
 ch.Dial 345

The Zone string gives (at a minimum) the (from,to) x-values as Colour, Pattern and Edge-weight are inherited from the ZoneAttribs otherwise. If you need to override these attributes, then the order of parameters is:

colour,from,to,pattern,weight

and you must give the pattern as its id number (from 1-15 for built-in shadings, or a higher number for a custom pattern). The edge-weight is the required line weight in points, and defaults to zero as these regions are generally un-edged.

See also ...

ch.Dial – dial and gauge charts | ZoneAttributes – for warning bands | Colour Cycle | Shading Patterns

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: YCaptionFont – font for Y caption

YCaptionFont – font for Y caption

This property selectively overrides the current (generic) setting for the caption fonts for the Y-axis only.

ch.Set 'CYfont' 'ti,10,Maroon'

If you use this to override the generic caption font, be sure to set the generic property first.

See also ...

CaptionFont – font for all axis captions


Rain graphics: YFormat – Y-axis format-picture

YFormat – Y-axis format-picture

Y-axis labels may be formatted with a simple picture format such as:

ch.Set 'ypic' '##0.00%'

To show the numbers to 2 decimal places with a trailing % symbol. Note that this does not automatically multiply the values by 100 (unlike VB and many OCX controls such as the Flexgrid).

Wrapping text labels

Text labels may be wrapped into a preset width with a format such as:

ch.Set 'ypic' 'XXXXXX;'

To force the labels to wrap at the length of the given string. If the string is simply ‘XXXXXXX’ then longer labels are truncated, and end with ‘...’ to indicate this.

See also ...

Picture formatting


Rain graphics: YLabelFont – font for Y labels

YLabelFont – font for Y labels

This property selectively overrides the current (generic) setting for the label fonts for the Y-axis only.

ch.Set 'LYfont' 'arb,8,Maroon'

If you use this to override the generic caption font, be sure to set the generic property first.


Rain graphics: YTickStyle – Y-axis tickstyle

YTickStyle – Y-axis tickstyle

The Y-axis tickstyle sets the tickmark type to one of:

  • Outside (the default)
  • Inside (ticks drawn inside axes)
  • Crossing (ticks are drawn across the axis)
  • NoTicks

You may also use ‘Minor’ here to generate default minor tickmarks for this axis.

ch.Set 'yx' 'Crossing'

Inside ticks work best with ‘framed’ chart axes to keep everything within the data area.


Rain graphics: YVar – 3D scatter versus this

YVar – 3D scatter versus this

Cloud charts can take a matrix of values, with the X-variable in column-1, the Y-variable in column-2 and as many Z-values as required in columns 3-n. It may be more convenient to specify the z-data as simple vectors and set the x,y-variables as properties:

ch.Set 'xvar' farm
ch.Set 'yvar' variety
ch.Cloud yield

This makes it very easy to experiment with different permutations of x and y data to try to visualise the relationships in a multi-dimensional dataset.

There is a simple cover function vs in the RainPro workspace to allow expressions like: ch.Scatter yield vs farm variety – you can experiment with the infamous barley data here!

See also ...

Versus – scatter versus this


Rain graphics: YZones – warning bands for Y-axis

YZones – warning bands for Y-axis

Used to set up horizontal warning regions on xy plots. Each region is defined by a colour (use colour names or the standard HTML syntax here), the start and end values for the region and an optional pattern number. You may set this as a single string (use ‘/’ to separate each zone, and ‘,’ to separate the parameters within each zone) or as an array of strings, one for each zone:

 ch.Set'yzones' 'Yellow,5,11,4/Green,7.5,8.5,5'
 ch.Set'yzones' 'Yellow,5,11,4' 'Green,7.5,8.5,5'

If you only give a start value, the end value defaults to the highest tickmark. Of course, zones may overlap – this is a convenient way of creating a set of bands with a ‘safe’ zone in the middle.

The pattern defaults to ‘solid fill’ (pattern 15) which would be appropriate with fairly light pastel colours. For the normal named colours, patterns 2,3,4 are good choices to produce a lightweight ‘wash’ effect.

See also ...

Colours – set colour cycle | Patterns – pattern cycle | ZoneAttributes – for warning bands

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ZCaption – Z-axis caption

ZCaption – Z-axis caption

The Z-axis caption is written vertically alongside the axis. It will be automatically repositioned depending on the chart viewpoint.

ch.Set 'zcap' 'Yield'

You may also choose to place it at the end of the axis with the ‘atend’ Z-style.

See also ...

CaptionFont – font for all axis captions | CaptionStyle – caption style | ZCaptionFont – font for Z caption | ZStyle – Z-axis style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ZCaptionFont – font for Z caption

ZCaptionFont – font for Z caption

This property selectively overrides the current (generic) setting for the caption fonts for the Z-axis only.

ch.Set 'CZfont' 'ti,10,Maroon'

If you use this to override the generic caption font, be sure to set the generic property first.

See also ...

CaptionFont – font for all axis captions


Rain graphics: ZFactor – Z-axis scale factor

ZFactor – Z-axis scale factor

To scale your data labels in the Z-dimension by a given factor:

ch.Set 'Zfactor' 1000

This allows you to use default (numeric) labelling for scaled data.


Rain graphics: ZFormat – Z-axis format

ZFormat – Z-axis format

Z-axis labels may be formatted with a simple picture format such as:

ch.Set 'zpic' '##0%'

To show the numbers with a trailing % symbol and not more than 3 digits.

See also ...

Picture formatting


Rain graphics: ZLabels – Z-axis labels

ZLabels – Z-axis labels

Sets the labels for each tick mark on the vertical axis of 3D charts.

ch.Set 'Zlab' 'One,Two,Three'


Rain graphics: ZLabelFont – font for Z labels

ZLabelFont – font for Z labels

This property selectively overrides the current (generic) setting for the label fonts for the Z-axis only.

ch.Set 'LZfont' 'arb,8,Maroon'

If you use this to override the generic caption font, be sure to set the generic property first.

See also ...

LabelStyle – label style


Rain graphics: ZoneAttributes – for warning bands

ZoneAttributes – for warning bands

To set the default attributes for the warning zones:

ch.Set 'ZAttr' 'Green,10%,0'
ch.Set 'ZA' 3 2 0

You can use numbers strictly in the sequence shown above (Colour, Pattern, Weight). The patterns number from 1⍎15 and you can give an exact line weight in points for the edge. The default is Red, solid fill, with no edge.

See also ...

Colour Cycle | Shading Patterns | Nib Weights

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ZRange – Z-axis range

ZRange – Z-axis range

To force the range of the Z-axis to include the values you require:

ch.Set 'Zrange'  ¯2000 2000

If you only give one number, the range is forced from zero to this value.


Rain graphics: ZStyle – Z-axis style

ZStyle – Z-axis style

The chart axes can be set independently with a variety of custom effects. The options shown here apply to the vertical axis in 3D charts.

ch.Set 'zstyle' 'grid,forcezero'

Options

forcezero:noforce | Axis must include zero in range
exact:extend | Axis will not be rounded up to the next whole tick mark
atside:atend | Caption placement
plain:noaxis | Axis style (no axes/no tickmarks)
grid:nogrid | Draw gridlines from Z-ticks around backplanes
altitude:noaltitude | Shade tiles to indicate height
labels:nolabels | Omit labels if required
flat:noflat | Force flat captions and labels on 3D charts

All 3D charts have the tickmarks drawn outwards (style ‘ntick’), as either of the other normal styles can interfere with the grid when the chart is projected. Options shown in bold are the defaults.

See also ...

ZTickStyle – Z-axis tickstyle


Rain graphics: ZTickmarks – Z-tick intervals

ZTickmarks – Z-tick intervals

To set the major tick mark interval for the Z-axis:

ch.Set 'Ztick' 5

You can also set the tick mark positions exactly with:

ch.Set 'Ztick' VEC

A common use of this would be to generate a logarithmic Z-axis, which is not directly supported by RainPro. Note that if you use this facility, you will completely over-ride any previous settings on the axis range – the axis will be forced to span the gap from the first to the last tick mark you give.


Rain graphics: ZTickStyle – Z-axis tickstyle

ZTickStyle – Z-axis tickstyle

The Z-axis tickstyle sets the tickmark type to one of:

  • Outside (the default)
  • NoTicks
ch.Set 'zx' 'Noticks'


Reference: Chart Styles

Summarises the major style keywords which apply to the chart as a whole. Check the individual chart elements to see where these may be applied.

ALTI | Altitude shading
ANNO | Annotate model
ARRO | Arrows
ASIS | Unsorted groups
AUTO | Autofit keys
BOXE | Boxed chart
CELL | Cells created
CENT | Centre marked
CLAM | Clamp lines to chart range
CLIP | Clip data to axis range
COAR | Coarse shading
COLU | Columnar data
COMP | Compass
CONT | Contours on mesh surfaces
CROP | Crop data at axis range
CURV | Points joined with smooth curves
DURA | Durations formatted to base-60
DECI | Decile whiskers
DISS | Dissected arrows
DOWN | Downwards groups
DRIF | Directional Min-max
ERRO | Errorbars
EXPL | Exploded axes
FILL | Filled lines and cells
FINE | Fine shading
FLAT | Flat text
FLOA | Floating bars
FORC | Forcezero
FRAM | Framed axes
GRID | Gridlines
GROW | Growth curve
HALO | Halo markers
HOLL | Hollow centre
HORI | Horizontal
INDE | Indexed to 100
INVI | Invisible axes
KITE | Kite charts
LINE | Lines
MARK | Markers
MODE | Modelfit
NOAX | NoAxes
NOTI | No Tickmarks
NORM | Normal Curve
ONTO | Ontop model
OVER | Overlayed gridlines
PLAI | Plain axes
PROJ | Projected contours
PTIC | Positive ticks
RADI | Radial scaling
RELA | Relative data
RISE | Risers
ROOT | Rooted arrows
ROUN | Round corners
ROWS | Rows
SCAL | ScaleBar
SEGM | Segmented
SHAD | Shadowed
SPAN | Spanned labels
SPID | Spider tags
STAC | Stacked bars
SURF | Surface fill
TERM | Terminated Min-max
TILE | Tiled surfaces
TIME | Time – Clockface Polar
TREN | Trend lines
VALU | Value tags
WALL | Walls are shaded
WEDG | Wedge zones
XTIC | XTick – Crossing Ticks
XYPL | XYPlot


Rain graphics: Altitude shading

Altitude shading

Applies graded colour to tiled response surfaces.

ch.Set 'style' 'altitude'

This is best used with a computed (and therefore smooth) surface.


Rain graphics: Annotate model

Annotate model

Adds a note to each regression line giving the details of the model

ch.Set 'style' 'annot'

By default, intercept and slope are shown for a linear fit, coefficients for a higher-order curve. You may provide a template for the equation (as here) with the EquationFormat property.


Rain graphics: Arrows

Arrows

Ends each line with an arrowhead.

ch.Set 'style' 'arrow'

This style works well with a set of separated curves (e.g. pessimistic and optimistic forecasts) and also with in-line keys.


Rain graphics: Unsorted groups

Unsorted groups

If you set the ‘group by’ or ‘categorise by’ properties to have RainPro automatically cross-total (e.g. for Towercharts) it defaults to sorting the categories (ascending numbers or alphabetically).

ch.Set 'style' 'asis'

The ‘asis’ option simply takes the unique group ids ‘cast in order of appearance’ and is probably what you want if you already used an SQL query to order the data.


Rain graphics: Autofit keys

Autofit keys

This style may be used with chart keys to ensure that all the text fits into the available space.


Rain graphics: Boxed chart

Boxed chart

Draws a box around the entire chart, notes and keys, with optional background fill.

ch.Set 'style' 'boxed'

The box is edged and filled using the current Frame Attributes or Key Attributes.


Rain graphics: Cells created

Cells created

Creates a collection of rectangles (using the current cellsize) centred around each plotted point. These can then be used by ch.Newcell which will use each cell in turn as the chart frame.

ch.Set 'style' 'cells'

This allows you to make a scatter-plot of miniature charts, for example using geographical co-ordinates to show details of samples taken at various locations.


Rain graphics: Centre marked

Centre marked

Polar charts

Marks the centre of polar charts with a dot.

ch.Set 'style' 'centre'

Useful when the chart has a filled surface which can make it hard to read the values.

Table charts

The table is centred between the chart margins.


Rain graphics: Clamp lines to chart range

Clamp lines to chart range

This style may be used in conjunction with ‘clipped’ to remove points outside the span of the axes, and to force any out-of-range lines to follow the edge of the chart.

ch.Set 'style' 'clipped,clamped'

It may also be used independently on the x and y-axes if required. If surface-fill is selected, then this style is automatically applied if you choose ‘clipped’ as the surface cannot be completed otherwise.


Rain graphics: Clip data to axis range

Clip data to axis range

This style may be used on the Linegraph to remove points outside the span of the axes, and clip any lines at the edge of the chart.

ch.Set 'style' 'clipped'

It may also be used independently on the x and y-axes if required.


Rain graphics: Coarse shading

Coarse shading

No interpolation is done on the altitude colors, so a simple blocky chart is produced. This is much faster to render, and can be used to explore different model fits quickly.

The density setting is used to determine the accuracy of the grid-fit as normal.


Rain graphics: Columnar data

Columnar data

The data for the Vector plot is normally a 4-column matrix or vector of xyxy groups.

This style allows you to pass 4 arrays giving x1 y1 x2 y2 values respectively for each point.


Rain graphics: Compass

Compass

This style will force the polar chart to treat all x-values as degrees. This applies to data and to tickmark settings, so that the example can be drawn with an XTick setting of (45,0) here.

ch.Set 'style' 'compass'

Values above 360 are accepted, and simply wrap around.


Rain graphics: Crop data at axis range

Crop data at axis range

This style may be used on the Linegraph and scatter plot to crop lines and markers (and value tags) at the edge of the plotting space.

ch.Set 'style' 'cropped'

It is only implemented on the SVG and PDF viewers at present.


Rain graphics: Points joined with smooth curves

Points joined with smooth curves

Joins points using smooth curves, rather than straight lines.

ch.Set 'style' 'lines,curves'

Points are joined with computed (cubic) Bezier curves, where the smoothness is determined by the ‘flexibility’ parameter which may vary between zero (which joins the points with straight lines) to approx 12. The default value of 3 will normally give reasonable results. High values may start to draw loops and other artifacts on very noisy data series.

See also ...

Flexibility – shape of trend line | Trend lines

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Durations formatted to base-60

Durations formatted to base-60

Integer axis labels and value tags are formatted as elapsed times.

ch.Set 'ystyle' 'duration'

Typically this would be used to present elapsed times in hh:mm:ss format rather than in decimal seconds. Numbers larger than 59 hours are shown in decimal form, for example 123:12:23 would be a possible value.


Rain graphics: Decile whiskers

Decile whiskers

Boxplots are drawn with the outer deciles dotted.

ch.Set 'style' 'deciles'

This gives a better feel for the data if there are some very wild outliers.


Rain graphics: Dissected arrows

Dissected arrows

Vector plots may look better with the arrows set back slightly from the nodes, when the nodes are drawn with a separate scatter plot.

ch.Set 'style' 'dissected'

This would be a typical style for many types of network diagram.


Rain graphics: Downwards groups

Downwards groups

If you set the ‘group by’ or ‘categorise by’ properties to have RainPro automatically cross-total (e.g. for Towercharts) it defaults to sorting the categories (ascending numbers or alphabetically).

ch.Set 'style' 'downward'

This will sort the groups into downward (numeric) or reverse alphabetic order.


Rain graphics: Directional Min-max

Directional Min-max

The ‘Drift’ style applies only to the Min-Max chart and restricts any line terminators to the 2nd set of values. This is not necessarily the ‘high’ end of the line, so you can use this option to show movement either upwards or downwards.

ch.Set 'style' 'drift'

This style applies when the chart has either ‘terminators’, ‘arrowheads’ or ‘errorbars’ at the line ends.


Rain graphics: Errorbars

Errorbars

Adds ‘T-pieces’ to each end of Min-max charts to make traditional-style error-bars.

ch.Set 'style' 'errorbars'

The bars scale in proportion to the current nib weight.


Rain graphics: Exploded axes

Exploded axes

This style moves the axes back from the plotting area by one major tick-mark length. It is commonly used on scatterplots where many points fall close to the axis.

ch.Set 'style' 'grid,exploded'

The style applies to all the rectangular 2D charts, and may be used on Multiples to separate the axes on the individual charts within the trellis.


Rain graphics: Filled lines and cells

Filled lines and cells

Line charts and Min-Max charts

Completes each line back to its starting point and fills the area in between.

ch.Set 'style' 'filled'

This may be used very effectively to fill a band between two lines with the Max-Min chart type. It also works with simple lineplots, but you may need to construct the lines quite carefully to get the required effect.

Tables

This style enables cell-shading in table charts. The current cycles of colours and patterns are used to shade individual cells in the table.

This can be used to highlight certain data values, or just to apply background colour to table columns.


Rain graphics: Fine shading

Fine shading

Very detailed is done on the altitude colors, giving an illusion of smoothly graded color. This may be very slow to render in vector formats such as SVG.

The density setting is used to determine the accuracy of the grid-fit as normal, then each tile is divided assuming that the surface is locally linear.


Rain graphics: Flat text

Flat text

Forces all labels and captions on 3D charts to be drawn horizontally.

ch.Set 'style' 'flat'

This is recommended for VML charts which handle rotated text very badly.


Rain graphics: Floating bars

Floating bars

Stacked barcharts are drawn omitting the first bar to give a floating effect.

ch.Set 'style' 'floating'

For horizontal floating charts it may be easier to use the Gantt chart here.


Rain graphics: Forcezero

Forcezero

All axes are forced to include the origin.

ch.Set 'style' 'forcezero'

This style also can be applied individually to each axis.


Rain graphics: Framed axes

Framed axes

The axes are completed to form a frame around the chart.

ch.Set 'style' 'framed'

This also prevents the axes from extending beyond the final tickmarks.


Rain graphics: Gridlines

Gridlines

Gridlines are drawn from major tickmarks on all axes.

ch.Set 'style' 'grid'

This style can also be set individually by axis.

Table charts

Gridlines are drawn between cells, and the entire table is boxed.


Rain graphics: Growth curve

Growth curve

An exponential growth curve is fitted through the data.

ch.Set 'style' 'grow'

The line may be annotated with the computed growth rate.


Rain graphics: Halo markers

Halo markers

Markers have a halo drawn beneath them in the chart background colour.

ch.Set 'style' 'halo'

This generally improves visibility, but can result in obscured markers in a very crowded scatterplot.


Rain graphics: Hollow centre

Hollow centre

Polar charts are drawn with a hollow centre.

ch.Set 'style' 'hollow'

This may improve appearance if the radial grid is very dense.


Rain graphics: Horizontal

Horizontal

Barcharts, Boxplots and Min-max charts may be drawn horizontally.

ch.Set 'style' 'horizontal'

This does NOT change the meaning of the X and Y axes, so to label the bars, you must use Y-labels here.

For piecharts, the effect is to run the sectors clockwise from 3:00 rather than 12:00.


Rain graphics: Indexed to 100

Indexed to 100

All data series are scaled to make the initial value 100.

ch.Set 'style' 'indexed'

This is often a convenient way to compare differing timeseries, e.g. daily values of dollar and Yen.


Rain graphics: Invisible axes

Invisible axes

All axes are made invisible, but tickmarks, gridlines and labels are still drawn as usual.

ch.Set 'style' 'invisible'

This style may be applied to individual axes if required.


Rain graphics: Kite charts

Kite charts

Trace charts are mirrored and filled to make a ‘kite’ chart presentation.

ch.Set 'style' 'kite'

This is commonly used to plot vegetation coverage or the results of pollen analysis.


Rain graphics: Lines

Lines

Lines are drawn between data-points on linegraphs and scatterplots.

ch.Set 'style' 'lines'

Points are connected by straight lines unless you additionally set the ‘curved’ style. Use the ‘trend’ style to draw an approximate smooth curve through the data.


Rain graphics: Markers

Markers

Markers are drawn at datapoints on linegraphs and scatterplots.

ch.Set 'style' 'markers'

You can use the marker scale to add an extra ‘dimension’ to the data.


Rain graphics: Modelfit

Modelfit

A simple regression model is fitted to the data.

ch.Set 'style' 'model'

The default is a linear ‘straight-line’ fit but you can use the Order of Fit setting to fit models up to quartics. The line may be annotated with the regression coefficients. If the ‘risers’ style is also set, the risers are drawn from the fitted line:

Fitting 3D data

If the modelfit style is used with the cloud chart, the fit is made against both X and Y axes, and the order of fit may be set independently for either.

Here, the model is quadratic in both X and Y. Contour lines are shown, and risers have been used to show the residual values in the Z-direction.


Rain graphics: NoAxes

NoAxes

No axes are drawn. This is often appropriate on 3D plots, or if the chart is simply illustrating the shape of some function.

ch.Set 'style' 'noaxes'

This style may be applied to individual axes if required.


Rain graphics: No Tickmarks

No Tickmarks

No tickmarks are drawn, but labels and gridlines appear as normal at the major tick interval.

ch.Set 'style' 'notick'

This style may be applied to individual axes if required.


Rain graphics: Normal Curve

Normal Curve

Histogram is overlayed with a fitted normal distribution

ch.Set 'style' 'normal'

The fitted curve uses the next available colour and linestyle in the olour and linestyle cycles.


Rain graphics: Ontop model

Ontop model

Fitted models and trendlines are drawn after the data is plotted, and so appear on top.

ch.Set 'style' 'ontop'

The default is to drawn the fitted curve first so that it does not hide the datapoints.


Rain graphics: Overlayed gridlines

Overlayed gridlines

Draws the gridlines ontop of the data. May be set as ‘style’, ‘xstyle’ or ‘ystyle’ to control the axis grids independently.

ch.Set 'style' 'overlay'

The example shows a typical barchart from Tufte’s book, using white gridlines to achieve the ‘dissected’ effect he recommends.


Rain graphics: Plain axes

Plain axes

Axes are drawn without tickmarks or labels. Gridlines will be drawn if this style is set. It is often used with X/Y styles ‘Arrowed’ when illustrating a simple curve.

ch.Set 'style' 'plain'

This style may be applied to individual axes if required.


Rain graphics: Projected contours

Projected contours

Contour lines on fitted surfaces are drawn on the xy-plane, rather than around the ‘hills’.

ch.Set 'style' 'projected'

You can also use contour lines on the standard 2D scatter plot to get a more detailed surface map.


Rain graphics: Positive ticks

Positive ticks

All axes are drawn with positive (inward-pointing) ticks is the styles is ‘ptick’. This is typically used with duplicate X or Y axes.

ch.Set 'style' 'ptick'

This style may be applied to individual axes if required.


Rain graphics: Radial scaling

Radial scaling

Bubble charts are normally scaled to keep the area of the marker in proportion to the data values. This option changes to scaling the radii, which would be more suitable for unfilled markers such as the diamond or ring..

ch.Set 'style' 'radial'


Rain graphics: Relative data

Relative data

Data is assumed to be relative, so the series values are accumulated as each series is plotted.

ch.Set 'style' 'relative'

This is the default style for stacked barcharts but must be set explicitly for shaded surfaces.


Rain graphics: Risers

Risers

Risers are drawn from the X-axis (or XY-plane in 3D charts) to each datapoint. If a baseline is defined, this is used as the target for the risers, rather than the axis.

ch.Set 'style' 'risers'

For polar charts the risers are drawn as radial lines from the centre.

Using risers to show residuals

When a modelfit or trend surface has been used in a Cloud chart (3D scatter) the risers are drawn from the surface to each datapoint, rather than from the XY-plane.

This provides a quick visual check of the residuals, and may help to locate the datapoints relative to the fitted surface in the projection of the 3D chart.


Rain graphics: Rooted arrows

Rooted arrows

Vector plots may be drawn with the start-point of each vector clearly marked. This is common on Met charts (such as wind-speeds) where the location of the reading is important.

ch.Set 'style' 'rooted'

The current marker symbol is used to indicate the root point, and the current marker scale can be used to control the size of the marker.


Rain graphics: Round corners

Round corners

This style applies to the main chart frame, the chart key (if boxed) and chart notes.

ch.Set ('style' 'round')('ks' 'round')('ns' 'round')

It causes any of these to be drawn with rounded corners.


Rain graphics: Rows

Rows

The data series are in rows, rather than the default assumption of columns.

ch.Set 'style' 'rows'

For table charts, this has the effect of transposing the table.


Rain graphics: ScaleBar

ScaleBar

Contour plots and 3D fitted surfaces may be ‘altitude shaded’ with a smooth gradient between given colors. This style adds a calibration bar in the right margin to allow you to read the data value from the color.

ch.Set 'style' 'scalebar'

The labels on the bar are written with the current Key font setting, and the Z-axis caption is used to write the caption above it. Lines are drawn across the bar at the z-tickmark intervals, and the lines are drawn with the current contour style.


Rain graphics: Segmented

Segmented

Normally, lines are continued across missing values, joining the points on each side. This style forces the line to break either side of missing data.

ch.Set 'style' 'segmented'

Note that no line will be drawn unless there are at least 2 points between any run of missing values.


Rain graphics: Shadowed

Shadowed

Adds a drop shadow to the box around the chart frame, notes, and keys.

ch.Set 'style' 'shadowed'

The shadow offset will be increased in proportion to the line-weight of the box.


Rain graphics: Spanned labels

Spanned labels

Column headers on table charts are spanned across empty cells. Where a column is spanned, the vertical grid is omitted from between the merged cells.

ch.Set 'style' 'spanned'

This may also be used on the X-axis to form a hierarchy of labels.

ch.Set 'xstyle' 'spanned'

This is a convenient way to group periodic data in timeseries.

See also ...

Table Style


Rain graphics: Spider tags

Spider tags

Piechart keys are attached to spider labels rather than being drawn in a separate key box.

ch.Set 'style' 'spider'

This only applies when an array of pies is created with a single call.


Rain graphics: Stacked bars

Stacked bars

Barcharts will accumulate and stack multiple data series.

ch.Set 'style' 'stacked'

To have the first bar not drawn, use the ‘floating’ style here.


Rain graphics: Surface fill

Surface fill

Line and polar charts are shaded down to the X-axis or in to the centre.

ch.Set 'style' 'surface'

If a chart baseline is set, this is used as the target for the surface fill rather than the X-axis. Surface fills look good with markers turned off and maybe with risers (as here).

Cloud charts shade each series down to the XY-plane, or a Z-baseline if given.


Rain graphics: Terminated Min-max

Terminated Min-max

The ‘terminated’ style will apply the current markers to each end of the Min-Max chart as an alternative to ‘Errorbars’ or ‘Arrowheads’. Solid markers such as the lozenge or various sizes of circle work best here.

ch.Set 'style' 'terminated'

You can additionally use the ‘drift’ style to have the markers only placed at the ‘far’ end of each line.


Rain graphics: Tiled surfaces

Tiled surfaces

Response surfaces are tiled, rather than being drawn as an open mesh.

ch.Set 'style' 'tiled'

This works well when used to plot a computed function of 2 variables.


Rain graphics: Time - Clockface Polar

Time – Clockface Polar

The ‘time’ style forces the Polar chart to treat X-values as a 24-hour clock.

ch.Set 'style' 'time'

In this example, the x-ticks were set as (6,5) to get major ticks every 6 hours and minor ticks on the hour. Values >24 simply wrap around.


Rain graphics: Trend lines

Trend lines

An gaussian-weighted smooth is drawn through the data.

ch.Set 'style' 'trend'

The degree of smoothing may be adjusted with the Flexibility setting.

Trend surface with 3D data

You can use the same fitting process with 3D data to put a trend surface through a set of spot-height values.

This can be a useful way to visualise a landscape given a series of discrete altitude values. Contours are drawn at the Z-tickmarks if style ‘contour’ is set, and if style ‘riser’ is selected, the risers are drawn from the surface rather than from the XY-plane.


Rain graphics: Value tags

Value tags

Data values are written next to each marker, or on top (or inside) each bar.

ch.Set 'style' 'values'

The detailed placement may be adjusted with the Value style setting which also allows the tags to be drawn opaque (the default) or transparent.


Rain graphics: Walls are shaded

Walls are shaded

The XZ, YZ and XY planes of 3D charts are shaded to form walls and a floor.

ch.Set 'style' 'walls'

This usually improves the readability of 3D charts as it gives a better sense of perspective.


Rain graphics: Wedge zones

Wedge zones

Dialchart warning zones are drawn as a complete wedge from the centre, rather than an annular segment.

ch.Set 'style' 'wedge'

The example also shows the ‘arrowed’ style of pointer.


Rain graphics: XTick - Crossing Ticks

XTick – Crossing Ticks

All axes are drawn with crossing tickmarks if style is ‘xtick’.

ch.Set 'style' 'xtic'

This style may be applied to individual axes if required.


Rain graphics: XYPlot

XYPlot

Linegraphs

The first column of data is taken as the X-values. This has the same effect as passing one less column and setting the X-values with the Versus property. The default is to assume that all columns of data represent sets of Y-values to be plotted against (1..n) as timeseries.

ch.Set 'style' 'xyplot'

Cloud charts (3D scatter)

In this case, the first 2 columns are taken as the X and Y values. Columns from 3 onwards are taken as independent data series, giving Z values. This allows you to call Cloud charts passing a single 3-element array of arrays rather that using the Versus and YVar properties to set the values on the X and Y axes.


Technical Information

FontsNS | Using Non-standard Fonts
Dashlines | Changing the Dashline Repeat
NewPats | Setting the Shadings
NewMarks | Using your own Markers
Translation | Translating the Viewer Texts
Customising | Customising the Viewer
Causeway | Using Rain with User-Defined Classes
RawGui | Using RainPro from the Raw APL Gui
Vfns | Viewer Functions


Rain graphics: Using Non-standard Fonts

Using Non-standard Fonts

Rain is supplied with most of the standard Windows fonts already defined. When setting the font for any chart object, you use a short (two-character) abbreviation, such as ‘TI’ for Times-Roman, qualified by either or both of ‘B’ for Bold and ‘I’ for Italic.

ch.Set 'Hfont' 'tii,18,blue'  ⍝ 18-pt blue TimesItalic

These abbreviations are all defined in a text matrix called ∆fonttbl, which you may edit as required to add new fonts, or change the abbreviations of those already defined. Note that any changes you make in this way will be lost next time you install a Rain upgrade. An alternative is to make a temporary definition of the special font with:

ch.DefineFont 'uncl' 'Uncial'

... which will set up the association between the short code ‘uncl’ and the TrueType font ‘Uncial’. If you give a two-character short code, DefineFont will automatically define a full set of four fonts so that:

ch.DefineFont 'ga' 'Garamond MT'
ch.Set 'hfont' 'gai'

... will set the heading to Garamond Italic.

N.B. If you change the abbreviations of the standard Windows fonts, you will need to redo many of the examples in the workspace!


Rain graphics: Changing the Dashline Repeat

Changing the Dashline Repeat

Unfortunately, Windows makes a very poor attempt at dashed and dotted lines, so that Rain must draw these as polylines, composed of short segments of various lengths depending on the repeat required.

The patterns are defined in ch.∆dashline which is a 3-element array defining the length (in points) for the line and space for the dotted line, the dashed line and the dot-dash combination. You add to these definitions with ch.DefineDash, or modify them in place if you prefer. There is a sample function DashTest in the Rainpro workspace with some typical line definitions:

ch.DefineDash 12(12 4 24 4)          ⍝ Long, longer
ch.DefineDash 18(15 3 2 2 2 5)       ⍝ Long, short short
ch.DefineDash 123(3 2 3 2 3 2 12 3)  ⍝ 3xshort, then long
ch.DefineDash 200(2 2 4 2 9 2 16 2 25 2)  ⍝ Squared!

Please note that the VML standard supports user-defined dash repeats, but this is not supported by early versions of IE5.


Rain graphics: Setting the Shadings

Setting the Shadings

Rain defines 15 shading patterns for you, drawn for both screen and printer resolutions. These are illustrated by Patterns which draws all combinations of colours, markers, line styles and patterns for you to check.

If you want to change the defined patterns, you will need to edit ∆pdefs and ∆gdefs which are in the PostScrp namespace. Each row defines an 8 by 8 tile as a text vector of length 64 – you might like to write yourself a simple function to edit and display the tiles. Copy the changed arrays (remember to change and test both as patterns look very different on screen and printer) to your own global variable, as you will otherwise lose your changes the next time you update RainPro.

To add additional patterns, use ch.DefineTile to associate either a bitmap file name or an integer array with a pattern number above 15. For future compatibility, it is probably best to use numbers in the range 100-999 for your defined patterns.


Rain graphics: Using your own Markers

Using your own Markers

Rain draws all markers as icons (scaled as appropriate for the printer up to the allowed maximum of 32 by 32 pixels and then drawn as vectors) and you can easily add your own .ICO files to the list. However these are really only suitable for the screen as they will not be scaled for the printer, so they may print very small, particularly on a 600dpi device.

Markers 1⍎15 are the built-in set, and Rain assumes that any numbers above this refer to your own markers, which you define using ch.DefineMarker as vector graphics or icon files. You may give the full path to the icon file, or just the file name if it is in the working directory. The function Contour is the RainPro workspace illustrates some vector-drawn markers:

⍝ The simple case is just a vector or 2-col matrix of xy values
 benzene←(1 3,3 5,5 5,7 3,5 1,3 1,1 3)-3
 ch.DefineMarker 39 benzene
⍝ This has a filled centre and stroked tail
 phenol←10 3⍴0 1 3,1 3 5,1 5 5,1 7 3,1 5 1,1 3 1,2 1 3,0 5 5,1 7 7,1 9 7
 phenol←phenol-[2]0 3 3 ⍝ Centre it around point
 phenol←phenol×[2]1 0.8 0.8 ⍝ Scale any size you like
 ch.DefineMarker 42 phenol
 ch.Set('MARK' 39 42)

See APLApple for an example of a custom icon marker – this expects to find APLApple.ICO in the current working directory.


Rain graphics: Translating the Viewer Texts

Translating the Viewer Texts

Phrasebooks in most common European languages will be shipped by Causeway, but if you wish to create your own file, the format is very simple, and you may start simply by renaming the uk-en.phb file and modifying the phrases as appropriate.

Format of the phrasebook file

The format of the file is: {TAG=Phrase [# Purpose of phrase]} with one phrase per line. A special phrase is anything beginning ‘~’ which removes a tool button or menu item completely. You can force newlines in a phrase with the ASCII ‘pipe’ character (this only applies to error messages and tooltips).

Lines beginning with blank, and comment lines (which begin with the ‘#’ character) are ignored; all trailing space is removed from the phrase. Please notes that the short tags used to identify the phrase to the viewer are case-sensitive, and should not be altered.

Here is a small sample from the uk-en phrasebook file:

# Input request dialogues
WMFC=Metafile Copy                       # Copy dialogue title
WMFE=Invalid file name or directory ...  # Copy dialogue error
BMPS=Bitmap Scale                        # Bitmap scale title
GIFS=GIF Scale                           # GIF scale title

Where data is to be inserted into a phrase at run-time, the parameters are marked with the symbols %1 %2 and so on, for example Page %1 of %2.

You may use tabs in place of the ‘=’ and ‘#’ separator characters if you prefer. This allows you to maintain your phrases in (for example) Excel and export the table as a tab-separated file.

When new capabilities are added to the viewer, local Causeway distributors, users or other volunteers will be contacted to update the necessary texts before the product is shipped. If a phrase cannot be translated in time, the phrasebook will be shipped with the new phrase in English. Missing phrases show in the viewer with the identifying tag only.

See also ...

Loading Translated Phrasebooks


Rain graphics: Customising the Viewer

Customising the Viewer

Although you can use the viewer at a low level as part of your own Gui dialogue design, it may sometimes be convenient to call the standard viewer but with additional callbacks available as right-mouse menu items. This section explains how to set up these callbacks, and also the way your called functions may interact with the existing viewer form.

Adding entries to the right-mouse menu

You may edit the existing menu variable to add new calls to your own functions here, for example:

 )ed #.PostScrp.∆viewmenu
My stuff: fm #.UserFunction 1

If you want the caption (the piece to the left of the colon) to be translated, you will need to add a matching entry to the appropriate phrasebook file. Typically, the user function would change the chart in some way (or possibly draw a new chart altogether) in which case it must call #.PostScrp.Do to refresh the current viewer:

 fm UserFunction arg;newcht
⍝ Sample function called from View menu
⍝ This is ALWAYS passed the form-name as left argument, but may ignore it.
⍝ This will probably change the chart in some way and must redisplay it neatly
 ch.New 0 0 400 400
 ch.Set'head'('Replot with option = ',⍕arg)
 ch.Plot(⍳23)*arg
 newcht←ch.Close
⍝ Get the current chart replaced and redrawn
 fm #.PostScrp.Do'View'newcht

Normally, you would pass local variable fm down to the user code from the menu entry to give it the correct form name to be called here.

See also ...

Using RainPro from the Raw APL Gui


Rain graphics: Using Rain with User-Defined Classes

Using Rain with User-Defined Classes

CausewayPro has two object classes which are designed to help in the integration of graphs into your GUI application.

The ‘Chart’ Class

This is the simpler of the two to use, but does not give you the full flexibility of the Rain language. It takes a numeric vector or matrix as its data argument, and a ‘chart specification’ as the reference data. By default, you get a simple line graph, i.e. the same as ch.Plot 1 2 3. The chart specification is a text form of the argument list to ch.Set, for example:

  head=This is my Graph
  type=bar
  xlab=Jan,Feb,Mar, ... ,Dec

It will only plot a single set of data per graph, and you cannot add notes to the completed chart. However the chart is sized to fit nicely into the size you draw (it will redraw to fit the new size if the user resizes your form) and this is a very convenient way of getting simple numeric data presented graphically.

Note that it requires the ch namespace from Rain.

The ‘PostScript’ Class

Objects of this class expect a vector of PostScript as their data. One way to do this is to return it from a niladic function, which you specify as the data argument. Another possibility might be to run your graph as an action on some other object, have the result assigned into a suitable variable, and simply holler that name on execution of the action. Note that the graph will be drawn with the proportions you set, rather than being sized to fit the object. You may want your function to query the object size and call ch.New with the appropriate proportions.

Note that both these classes require the PostScrp namespace to be present.


Rain graphics: Using RainPro from the Raw APL Gui

Using RainPro from the Raw APL Gui

You can use the charting functions to build your graphs and the viewer from the PostScrp namespace to browse and print them. However you may want to display charts on forms which you have built with the standard Dyalog APL Gui functions. The notes which follow will guide you through the process.

You can draw charts on any object which allows other graphical objects as children. Typically this might be a SubForm, a MetaFile or a Bitmap. Of course it could also be a printer, but it would normally be easier to use the supplied print routines in the PostScrp namespace.

The important thing to understand is how the PostScript co-ordinate system used in RainPro maps to the pixel row-column layout used by Dyalog. In the example below, a form is created with a size of 200 pixels high by 400 wide. Because PostScript expects the origin at the lower left, the first thing we must do is to invert the Y-axis – hence the Xrange and Yrange settings.

It is also important to draw the graph on a region of the same shape as your target Gui object, so Rain is initialised by ch.New with the same size region, but this time you give (x,y) so the values are reversed!

      )clear
      )copy rain ch PostScrp ∆cmap
      ⎕lx←'''Rain in the raw'''
      'ff' ⎕wc 'Form' 'My Graph' (200 100)(200 400)('coord' 'pixel')
      'ff' ⎕ws ('Coord' 'User')('Yrange' 200 0)('Xrange' 0 400)

      ch.New 0 0 400 200
      ch.Set 'Head' 'Here is my Graph'
      ch.Bar ?12 2⍴100
      pp←ch.Close
      ⍴pp
1785
      PostScrp.PS pp '#.ff' 1 ∆cmap

The graph is then drawn as normal, and the output retained in a scratch variable pp. This can now be drawn onto the form (or any other suitable Dyalog object such as a Static or Bitmap) by a call to the PS function in the PostScrp namespace. The arguments to PS give:

  1. The PostScript definition of the chart
  2. The full (rooted) name of the Gui object to draw it on
  3. The scale factor (pixels per point) required – 1 in this case
  4. The colour map to be used.

You might like to give the user access to the supplied viewer (PostScrp.View); one possibility would be to put this call on the DoubleClick event on the form, or to trigger it from a right-mouse menu. If nothing appears on your form, check that you gave the fully rooted name of the Gui object, which is necessary to allow the PS function to locate it.


Technical Details: Viewer Functions

VFStd | Basic Viewer Functions
VFTran | Loading Translated Phrasebooks
VFIntro | Introducing ‘Active Rain’
VFEnum | PostScrp.EnumerateCharts – list all charts
VFInfo | PostScrp.FindInfo – bounding box of region
VFGuiId | PostScrp.GuiId – internal name of a series
VFD2L | PostScrp.D2L – device to logical co-ordinates
VFL2D | PostScrp.L2D – logical to device co-ordinates
VFHotspot | PostScrp.FindHotspot – chart headings etc.
VFSeries | PostScrp.FindSeries – detect data series
VFPoints | PostScrp.FindPoints – multiple data points
VFFindHint | PostScrp.FindHint – return data hints
VFSetObject | PostScrp.SetObject – redraw chart object
VFGetPage | PostScrp.GetPage – recover updated PostScript
VFReadHeader | PostScrp.ReadHeader – read header comments
VFWipe | PostScrp.Wipe – remove all graphics from Gui object


Rain graphics: Basic Viewer Functions

Basic Viewer Functions

The PostScrp namespace is designed to convert your RainPro chart to a wide variety of graphics formats. You can view the chart on screen, print it to your Windows printer, direct it to any PostScript device, clipboard it and so on. All the examples shown below assume you have saved the intermediate format of your chart in a character variable PG. The available functions are:

View the Chart

To see the chart on screen, zoom in on any selected region, read off data values from the mouse cursor etc. ...

PostScrp.View PG

The right-mouse menu in the viewer supports many of the facilities listed below. Any settings you change are saved in the Windows Registry, by default under the key ‘Software\Causeway\RainPro\Viewer’ within HKEY_CURRENT_USER. You can use PostScrp.SetRegPath to set your own registry path, so that the settings will be specific to your own application. If you set this path to null, no settings will be saved to or loaded from the registry.

All the text captions in the viewer may be loaded from a phrasebook file with PostScrp.GetPhraseBook phbfile. The workspace is shipped with a UK-English phrasebook (uk-en.phb) and phrasebooks for other languages will be shipped as they become available. You might choose to load your local phrasebook once and ship your product with a permanent phrase table, or you might have the application load it on startup depending on your user’s choice of language for the application.

Print the Chart

To have the chart printed on your standard Windows printer ...

PostScrp.Print PG

This will orient the paper automatically to match the orientation of the chart. You can preset the target printer with:

PostScrp.OpenPrinter 'Tektronix 840,\\SERVER\Tek840'

which will route all prints to this destination until you call PostScrp.ClosePrinter.

A null argument to OpenPrinter will open the Windows default printer.

Copy the Chart to the Clipboard

In general, the best format is ‘Windows Metafile’ which allows the chart to be pasted into standard applications such as Word, remaining fully scalable. To copy the chart to the clipboard in Windows metafile format ...

PostScrp.Clip PG

You can pass a left argument of a file name here, which will save the image to a file with extension ‘.WMF’ – you may then use the ‘Insert,Picture ...’ menu in Word to import your graphic.

'c:\data\doc\chart1' PostScrp.Clip PG

Two global variables may be used to control the metafile generation:

PostScrp.∆metascale←0.75  ⍝ Scales the metafile size
PostScrp.∆showpaper←1     ⍝ Add a double-line border

These are reset to default by PostScrp.Init.

To copy the chart in bitmap format:

1 PostScrp.ClipBits PG

The left argument gives the required scale factor – the function will prompt if you omit it. Large bitmaps require a lot of workspace, and can take a long time to create.

Output to PostScript Devices

Rain charts can be written directly to any PostScript printer, or saved on file in PostScript format.

'\\server\tek840' PostScrp.Write PG    ⍝ Direct to printer
'C:\temp\RAIN.PS' PostScrp.Write PG    ⍝ Write to PS file

If you omit the file name, the default is ‘prn’ which will output the chart to your default printer. If you have a colour printer (such as the Tektronix-840) set PostScrp.∆rgb←1 which allows full-colour output. Otherwise the results will be better if the chart is forced to use a black&white colour map with PostScrp.∆rgb←0.

file PostScrp.WritePDF PG    ⍝ for Distiller

The files saved in this format are ideal for use with Acrobat Distiller to generate PDF graphics; there is a sample function ToPDF in the RainPro workspace which you can change to route the PostScript data directly to Distiller’s inbound directory.

To save the chart in ‘Encapsulated PostScript’ (EPS) format:

'C:\data\doc\rain' PostScrp.WriteEPS PG  ⍝ Write out as .EPS file

You can import these files into Word, where you will be able to resize them as normal, but note that you will only see a placeholder (with the chart title and date) in the document. The chart will print correctly on any PostScript printer.

Saving Charts in Internet Format

The two graphics formats available are (uncompressed) GIF and PNG – use PNG if your browser supports it.

img←PostScrp.MakePNG PG

This returns a 3-element vector with the integer representation of the PNG file in the first element, the image map in the second, and the chart id in the third. If you are not using the capability to make hypertext jumps based on your data, you can simply save the first element directly to file:

'c:\temp\test.png'  PostScrp.rput 1⊃img

You can pass a scale factor as the optional left argument to MakePNG and MakeGIF if required. See the notes in the Introduction for suggestions on saving in the VML format for IE5. You can also use PostScrp.MakeApplet to generate applet tags and pass the chart as parameters to the Java viewer which is freely available from the Causeway web site.

Rendering to any Dyalog Object

You can draw your charts on nearly all the standard Dyalog objects, e.g. buttons, subforms etc. See Using the Raw Dyalog Gui for an example.

PostScrp.PS PG '#.ff.sub' 1 ∆cmap

The arguments give the vector of graphics data, the (fully qualified) name of the Gui object, the pixels per point conversion required (1 if the bounding box of the chart matches the size of the Gui object in pixels) and the colour map to be used.

Extracting header comments

You can use PostScrp.ReadHeader to read any of the header comments (such as the page bounding box) which you may find useful in your own event handlers.

See also ...

Loading Translated Phrasebooks


Rain graphics: Loading Translated Phrasebooks

Loading Translated Phrasebooks

It is possible that you will want to include the supplied chart viewer as a component in a shipped application, or maybe you would find it helpful during development to have all the viewer texts shown in your native language. To enable this, you require a text ‘phrasebook’ file which translates the English text to the language of your choice – phrasebooks are freely available from the Causeway web site ‘support’ pages in French, German and Finnish. More languages will be included as phrasebooks are completed by our users.

Using an existing phrasebook

This is managed with two service functions:

∆de←PostScrp.GetPhraseBook 'c:\deutsch.phb'

This reads the phrase table from file, and sets it as the active phrasebook for the viewer. You may ignore the result if you only run in a single language – just save the workspace with the phrase table in place. However if you regularly switch languages, you can keep the result in a variable (or on your own component file) and pass it as argument to:

PostScrp.UsePhraseBook ∆de

Note that this is the internal form of the phrase table, and may be changed in the future. It is always safest to maintain the plain text form as an external .PHB file.

See also ...

Translating the Viewer Texts


Rain graphics: Introducing 'Active Rain'

Introducing ‘Active Rain’

This section of the User Guide describes the interactive capabilities now available in RainPro. These allow you to change many of the chart elements dynamically (for example headings or titles), to implement drill-down capabilities, or to write truly interactive charts where the user can modify data values.

The RainPro workspace includes two examples for you to copy:

  • Drill – shows a simple data exploration tool where you can click on pie sectors to see the detail as a barchart
  • Edit – shows how to edit the data values on a simple linechart

You can also check out the callbacks in the RawGui function:

Sample
RawGui PG

These illustrate the techniques which you can use to detect the chart elements clicked by the user, modify headings, offer hints on mouse-move etc.

The functions which you may need to call are:

  • EnumerateCharts obj – List all charts drawn on this object
  • FindInfo – Locate hotspot info by tag (e.g. ‘Heading’)
  • GuiId – Return Guiname associated with this chart/tag
  • D2L – Convert Device to Logical co-ordinates
  • L2D – Convert Logical to Device co-ordinates
  • FindHotspot – Hotspot which is pointed to by (x,y) coordinates
  • FindSeries – Series data which is within tolerance of the coordinates
  • FindPoints – Data points which lie within bounding box
  • FindHint – Hint which matches this chart/series/data index
  • SetObject – Reset heading or axis captions in-place
  • GetPage – Recover updated PostScript source

These are all illustrated by the examples in the RainPro workspace.

N.B. RainPro is shipped with only the data hotspots enabled. FindSeries will work as described, but FindHotspot will not detect any captions, headings and so on. You can only change this setting at initialisation (before you call ch.Set for the first time after you last called ch.Close):

ch.SetDefault 'HO' 2  ⍝ all hotspots operative
ch.SetDefault 'HO' 0  ⍝ no hotspots at all

This is probably best run in an initialisation function in your workspace.


Rain graphics: PostScrp.EnumerateCharts – list all charts

PostScrp.EnumerateCharts – list all charts

Normally, you would use ch.Name to give your charts meaningful names, in which case you should not need this function. However if you allow RainPro to generate default names, you will need to find out what your chart is called before you can use any of the other PostScrp functions to check if you have located a chart element (such as a heading) or a point from a data series.

Assuming that you have drawn your chart(s) on a form called ‘#.pgi’:

      PostScrp.EnumerateCharts '#.pgi'
 XY Plot  chart42743  Sample Barchart

These are the three charts from the Sample function. The first and last have been explicitly named, the second has a generated chart name.

Note that this always returns a vector of names, so you must disclose it if you only have one chart.


Rain graphics: PostScrp.FindInfo – bounding box of region

PostScrp.FindInfo – bounding box of region

This function returns a 7-column matrix giving the name, position (bounding box = x1 y1 x2 y2), Gui object and counter of all objects of this type on a given Gui object. If you have drawn your charts on a Gui object '#.pgi':

'Info about headings is ...'
'#.pgi'PostScrp.FindInfo'Heading'

could display ...

Info about headings is ...
 chart197468       40    291.2  249.8  320     #.pgi.ps3   1
 XY Plot          256    247.22 356    268.82  #.pgi.ps5   1
 XY Plot           54.86 247.22 154.86 268.82  #.pgi.ps16  1
 Sample Barchart   54.86 118.82 154.86 140.42  #.pgi.ps36  1

The objects you can enquire about are:

  • PlotRegion – the overall area enclosed by the chart axes
  • OriginScale – the chart origin and scaling
  • Heading – the main chart heading
  • Subhead – the subsidiary heading
  • Footnote – the chart footer
  • XCaption – the X-axis title
  • YCaption – the Y-axis title
  • XLabels – the X-axis labels (counter runs from 1-n)
  • YLabels – the Y-axis labels, counting up from the origin 1-n
  • Key – the chart key, counting up in series order 1-n

Other objects may be added in later versions of RainPro.


Rain graphics: PostScrp.GuiId – internal name of a series

PostScrp.GuiId – internal name of a series

If you need to manipulate the data in a series directly (for example by resetting the ‘Points’ property of a Polyline generated by RainPro) you need to determine the internal Gui name of the APL object. To do this, it is best to name the chart and the series explicitly, for example:

ch.Name 'XY Plot'
ch.Series 'Ellipse'

before you plot the chart. See Sample for a typical example.

Now you can find the APL Gui name(s) by calling:

gui←'#.pgi'#.PostScrp.GuiId'XY Plot' 'Ellipse'

In this case two names will be returned, one for the line and one for the markers. You can see the effect of erasing one or both ...

 gui
#.pgi.ps12  #.pgi.ps13
⎕ex '#.pgi.ps12'

... this removes the line, leaving only the markers in place.


Rain graphics: PostScrp.D2L – device to logical co-ordinates

PostScrp.D2L – device to logical co-ordinates

This function converts from the co-ordinates returned by APL (for example in the mouse-move message) to the co-ordinate system used in the chart the mouse is currently over. It returns the result as PostScript-style XY co-ords, based at the chart origin.

xy←guiobj PostScrp.D2L rc

An example is included in the RainPro workspace as part of the Edit function set:

⍝ Follow the mouse (vertically)
 nm←'#.',⊃msg ⋄ pos←2↑2↓msg
......
⍝ show the user where we are (vertically)
 pos←⌊0.5+2⊃nm PostScrp.D2L pos
 '#.pgi.lbv'⎕WS'caption'(⍕pos)

This is set as the mouse-move handler when the user picks up a data point to move it vertically. It gets the (row,column) position from APL (in the current user-coordinate system) in the event message, and stores it as pos. In order to show the user the potential data value which will be set when the mouse is released, it must update a status field with the new Y-value in the chart co-ordinate system. It converts to (x,y) and shows the rounded value of the second element in the status field.


Rain graphics: PostScrp.L2D – logical to device co-ordinates

PostScrp.L2D – logical to device co-ordinates

This converts between the logical co-ordinate system used by Rain to the co-ordinates actually used to plot the APL Gui objects on the chart. You would use it if you wanted to overlay your own lines or markers on top of an existing chart, giving the data points in the same co-ordinate system as the original chart.

For example, you could try ...

ch.Name 'Test' ⋄ ch.Plot ⍳23
PG←ch.Close
RawGui PG

Then you could simply overlay the chart with a new line ...

'Test' RawGui_plot 2 2⍴0 0 23 12

     ∇ cnm RawGui_plot xy;rc
[1]   ⍝ Illustrates adding a new line to an existing plot
[2]   ⍝ <xy> is given in the user's co-ordinate system
[3]   ⍝ <cnm> names the chart we drew the plot on.
[4]    rc←('#.pgi'cnm)PostScrp.L2D xy
[5]   ⍝ Data is now in row-column format ready to draw
[6]    'pgi.poly'⎕WC'Poly'('Points'rc)
     ∇

This will draw your new line using the chart axes. You can call this repeatedly to get the line to move around, or you could easily modify it to add several lines one after the other.

Note that this takes the argument in (x,y) format and returns the result as (r,c) so that it can be used directly to create the APL Gui object.


Rain graphics: PostScrp.FindHotspot – chart headings etc.

PostScrp.FindHotspot – chart headings etc.

This function is intended to be used to allow users to modify ‘boilerplate’ elements such as headings and axis captions directly, probably by using a right-mouse menu. It takes the name of the APL Gui object on the left and the mouse position (x,y) on the right, and reports the hotspot (if any) which the (x,y) location falls within.

xy←⌽2↑2↓msg      ⍝ Mouse position
info←'#.pgi'#.PostScrp.FindHotspot xy

The result is a null vector if no hotspot is detected, otherwise it is an 8≡element vector giving:

  1. The chart name (set by ch.Name or generated by RainPro)
  2. The hotspot type (see the list below)
  3. The internal gui name of the APL object
  4. The hotspot counter (=1 except for pagelabels, labels and keys)
  5. The bounding box of the marked area

For example if you generate the Sample chart, view it with RawGui PG and double-click on the barchart heading:

Sample Barchart  Heading  gui-object-name  1 54.86 118.82 154.86 140.42

If hotspots overlap, only the last one is returned.

Hotspot types

Heading ... The main chart heading
Subhead ... The subsidiary heading
Footnote ... The chart footer
Pagelabels ... The page-label array
XCaption ... The X-axis caption
YCaption ... The Y-axis caption
XLabels ... The set of all X-axis labels
YLabels ... The set of all Y-axis labels
Key ... The set of chart keys (series marker and text)
Keytext ... The key text only.

Note that for labels and keys, the hotspot counter is incremented for each label, working out from the origin. For barcharts and piecharts, this may be used to identify the row in the data matrix corresponding to the label the user clicked on. The key text has a set of zero-size hotspots, so it cannot signal any events but it may be changed in-place under program control.

You might use the bounding area to show a dotted rectangle (indicating the selected object) when the user clicked on it, or to make a locator of the appropriate size for ‘drag-drop’ processing.

Note that RainPro is shipped with support for text hotspots disabled to save on processing time and workspace. To enable these, you must run:

ch.SetDefault 'HO' 2  ⍝ all hotspots operative

before your first call to ch.Set following a previous ch.Close.

More hotspots may be added in future releases.


Rain graphics: PostScrp.FindSeries – detect data series

PostScrp.FindSeries – detect data series

This function is designed to allow the user to interact directly with chart data, for example by clicking on data points to have them excluded from a regression analysis; clicking on pie sectors to drill-down to detailed figures and so on. The sample function Drill (in the RainPro workspace) illustrates several of the possibilities.

PostScrp.FindSeries takes the name of the APL Gui object on the left and the mouse position on the right, and reports the data point (if any) which the mouse location falls within or beside (within 4 pixels of a marker). Bars have a 4-pixel headspace so that you can drag a zero-length bar out of the x-axis.

xy←⌽2↑2↓msg     ⍝ mouse position (x,y)
info←'#.pgi'#.PostScrp.FindSeries xy

It returns null if there are no qualifying data points, otherwise an 11-element vector giving chart name, series name, row, column, type and 6 elements of extra information (see below). All data is treated as 2≡dimensional, so pie charts report (1 1), (1 2) and so on for the sectors, taken clockwise from midnight. Barcharts and linecharts report the (row,column) index in the original data matrix, with simple vectors treated as 1-column matrices. If there is more than one qualifying data point, the last one plotted is returned.

The extra details returned are for use by graphical editing tools and will vary by chart type:

  1. Line Chart – the x,y position of the target data point, and the x,y positions of its immediate neighbours in the series
  2. Barchart – the bounding box of the bar (x1,y1,x2,y2)
  3. Piechart – the x,y position of the sector origin, the radius, and start and end angles of the sector

These details are always padded with trailing zeros to 6 elements. All details are returned in device co-ordinate space.

Note that linecharts only hold this hotspot information if they have markers. If you want drill-down from a chart with no markers, use marker type=8 (invisible).

RainPro is shipped with support for series hotspots enabled by default. To save on processing time and workspace, you might like to disable these with:

ch.SetDefault 'HO' 0  ⍝ no hotspot support

This is only likely to make a significant economy for a heavy scatterplot, as the Chart Viewer will build an internal array with one row per data-point to allow the markers to be detected. Reset this to 1 (series tracking only) or 2 (series and text object tracking) as required.


Rain graphics: PostScrp.FindPoints – multiple data points

PostScrp.FindPoints – multiple data points

This function is designed to allow the user to select several data points which fall within a given rectangle on the chart. It would normally be used in conjunction with a Dyalog Locator object – the function RawGui_Locate in the RainPro workspace illustrates the technique.

 inf←⎕DQ lnm
⍝ Transform locator to (lower-left -> top right) ...
 inf←+⍀2 2⍴2↓inf
 inf←(>⌿inf)⊖inf
⍝ Pass as (x,y) bounding box to get enclosed points ...
 :If ~0∊⍴info←'#.pgi'#.PostScrp.FindPoints⌽inf
  'Got some (Chart name, series#, row, column) ...' ⋄ info
 :End

This selects chart markers only, with no tolerance (the marker must lie on or within the bounding rectangle). It returns a 0 by 4 matrix if no points are selected, otherwise one row per data point giving the chart name, series name and row/column index in the original data matrix. Vectors are treated as 1-column matrices.


Rain graphics: PostScrp.FindHint – return data hints

PostScrp.FindHint – return data hints

This is designed to allow a charting application to display any data hints applied when the chart was constructed using ch.Hint. It takes as argument the result from PostScrp.FindSeries (which uniquely identifies a data point) which gives the chart name, series name, row/column index of the data in the original data matrix.

hint←'#.pgi'#.PostScrp.FindHint info

It returns any hint which matches this chart/series/data index as a simple character vector (null if nothing is matched). Note that the CausewayPro Chart and PostScript Viewer classes both signal a ‘CHHINT’ event which can be used very simply to update a status field with the data hints as the mouse is moved over the chart.

You can easily check if hints are working correctly with the standard chart viewer – hints show in the second status field when you move the mouse over the hinted data. The function Sample has a hint on the exploded pie sector!


Rain graphics: PostScrp.SetObject – redraw chart object

PostScrp.SetObject – redraw chart object

This function allows you to re-make any of the standard ‘boilerplate’ objects without redrawing the entire chart. Currently it only supports the main heading, the subheading, and the X and Y captions.

obj #.PostScrp.SetObject ('chart1' 'Heading') 'Hello again'

N.B. work in progress – this does not currently remake the hotspot region, so that you may find that you can click ‘where the heading was before’ even though it has been replaced with different text.


Rain graphics: PostScrp.GetPage – recover updated PostScript

PostScrp.GetPage – recover updated PostScript

After you have modified various chart objects (headings etc.), you may want to recover the modified PostScript code to save on file, view in the standard RainPro viewer, export to the Acrobat Distiller, and so on. To access the updated page (assuming you drew the chart on gui object ‘pgi’):

PG←#.PostScrp.GetPage '#.pgi'

You might like to check this in the normal viewer during development to check that the modifications have been applied correctly.


Rain graphics: PostScrp.ReadHeader – read header comments

PostScrp.ReadHeader – read header comments

This is a simple utility to extract header information from the structured comments in the PostScript page. Typically it returns numeric data, such as the bounding-box of the entire chart. This is useful in writing a general-purpose viewer which will need to shape itself to fit around the chart.

bb←PostScrp.ReadHeader PG'%%BoundingBox:'

See RawGui for a simple example.


Rain graphics: PostScrp.Wipe – remove all graphics from Gui object

PostScrp.Wipe – remove all graphics from Gui object

This function cleans off all graphics which were drawn on the object:

PostScrp.Wipe obj


Rain graphics: Other Functions

Other Functions

This section lists all the functions (alphabetically by function name) which set up the charting environment, or add extra information such as JavaScript callbacks to your chart data.

chaddeffect | ch.AddEffect – use an animation or CSS style on text items
chbitmap | ch.Bitmap – add images to charts
chbookmark | ch.Bookmark – add outline entry for chart
chdefinedash | ch.DefineDash – generate custom dash repeats
chdefineeffect | ch.DefineEffect – set up SVG effects
chdefinemarker | ch.DefineMarker – define markers
chdefinetile | ch.DefineTile – define new fill patterns
chdraw | ch.Draw – add arbitrary polylines
chdrawaxes | ch.DrawAxes – redraw chart axes
chfix | ch.Fix – update property directly
chgroupby | ch.GroupBy – add a grouping criterion
chhelp | ch.Help – invoke help file
chhint | ch.Hint – add data hints
chhref | ch.Href – add HTML jumps
chinclude | ch.Include – add arbitrary content (SVG filters and symbols)
chinnergap | ch.InnerGap – inner gap on barcharts
chjscript | ch.JScript – define JavaScript prologue
chjset | ch.JSet – set JavaScript properties
chmapcoords | ch.MapCoords – map from chart space to frame
chmetafile | ch.Metafile – add metafiles
chname | ch.Name – give a name to the chart
chnewcell | ch.NewCell – advance to next cell in trellis
chnextnote | ch.NextNote – y-position of next note
chpasteup | ch.PasteUp – include completed chart in page layout
chrangeaxes | ch.RangeAxes – set axis ranges
chrendereps | ch.RenderEPS – render chart to an EPS file
chrenderpdf | ch.RenderPDF – render chart to PDF
chrenderpng | ch.RenderPNG – render chart to PNG image
chrendersvg | ch.RenderSVG – render chart as SVG
chrendervml | ch.RenderVML – render chart as VML text
chrenderemf | ch.RenderEMF – render chart as Windows metafile
chreset | ch.Reset – reset to defaults
chresetkey | ch.ResetKey – remove any key placeholders
chrun | ch.Run – run with preset array and type
chseries | ch.Series – name each data series
chsetdefault | ch.SetDefault – change shipped settings
chsetnewline | ch.SetNewline – change the default linebreak
chsetseparators | ch.SetSeparators – thousands and decimals
chsplitby | ch.SplitBy – add a splitting criterion
chtext | ch.Text – low-level text output
chtextwidth | ch.TextWidth – measure text
chtip | ch.Tip – supply pop-up tips for data points
chtrellis | ch.Trellis – define a matrix of cells
chusetable | ch.UseTable – add a NewLeaf table to any chart
chversion | ch.Version – return current version


Rain graphics: Chart Properties

Chart Properties

This section of the reference lists all the chart properties, with examples of their use.


Rain graphics: Chart Styles

Chart Styles

Summarises the major style keywords which apply to the chart as a whole. Check the individual chart elements to see where these may be applied.

ALTI | Altitude shading
ANNO | Annotate model
ARRO | Arrows
ASIS | Unsorted groups
AUTO | Autofit keys
BOXE | Boxed chart
CELL | Cells created
CENT | Centre marked
CLAM | Clamp lines to chart range
CLIP | Clip data to axis range
COAR | Coarse shading
COLU | Columnar data
COMP | Compass
CONT | Contours on mesh surfaces
CROP | Crop data at axis range
CURV | Points joined with smooth curves
DURA | Durations formatted to base-60
DECI | Decile whiskers
DISS | Dissected arrows
DOWN | Downwards groups
DRIF | Directional Min-max
ERRO | Errorbars
EXPL | Exploded axes
FILL | Filled lines and cells
FINE | Fine shading
FLAT | Flat text
FLOA | Floating bars
FORC | Forcezero
FRAM | Framed axes
GRID | Gridlines
GROW | Growth curve
HALO | Halo markers
HOLL | Hollow centre
HORI | Horizontal
INDE | Indexed to 100
INVI | Invisible axes
KITE | Kite charts
LINE | Lines
MARK | Markers
MODE | Modelfit
NOAX | NoAxes
NOTI | No Tickmarks
NORM | Normal Curve
ONTO | Ontop model
OVER | Overlayed gridlines
PLAI | Plain axes
PROJ | Projected contours
PTIC | Positive ticks
RADI | Radial scaling
RELA | Relative data
RISE | Risers
ROOT | Rooted arrows
ROUN | Round corners
ROWS | Rows
SCAL | ScaleBar
SEGM | Segmented
SHAD | Shadowed
SPAN | Spanned labels
SPID | Spider tags
STAC | Stacked bars
SURF | Surface fill
TERM | Terminated Min-max
TILE | Tiled surfaces
TIME | Time – Clockface Polar
TREN | Trend lines
VALU | Value tags
WALL | Walls are shaded
WEDG | Wedge zones
XTIC | XTick – Crossing Ticks
XYPL | XYPlot


Rain graphics: ch.Close – completing the chart

ch.Close – completing the chart

Completes any outstanding processing (e.g. adds the key information which can only be written when the chart is complete) and returns the PostScript vector which defines the completed chart:

     PG←ch.Close
     ⍴PG
1920
     View ch.Close

You can view a partially completed chart with ch.View if you need to:

wip←ch.View ⋄ View wip


Rain graphics: ch.DefineFont – define new TrueType fonts

ch.DefineFont – define new TrueType fonts

To make a short code for a non-standard TrueType font:

ch.DefineFont 'uncl' 'Uncial'
ch.Set 'hfont' 'uncl,14,forest'

... which will set up the association between the short code ‘uncl’ and the TrueType font ‘Uncial’. If you give a two-character short code, ch.DefineFontwill automatically define a full set of four fonts so that:

ch.DefineFont 'ga' 'Garamond MT'
ch.Set 'hfont' 'gai,14'

... will set the heading font to 14-point italic Garamond.

Adding CSS atributes, SVG filters or extra PostScript names

When defining fonts for use in SVG, you can append the URL to a filter (assuming that you have passed this through with ch.Include), for example:

ch.DefineFont 'AS' 'Arial' '#shadow'

You may now use all four variants of this font, sized as required, to obtain the drop-shadow effect defined by the SVG filter. Any other valid CSS2 attribute may also be given here:

ch.DefineFont 'AX' 'Arial' 'opacity:0.5'

This will set the opacity of the font wherever it is used in VML or SVG output (assuming that the opacity attribute is supported by the user’s browser). If you set several attributes here, separate them with semi-colons in the usual CSS2 syntax.

The same argument is used to enforce a particular font name when the output is saved in EPS format.

ch.DefineFont 'BANT' 'Book Antiqua' 'Palatino-Roman'

This will use Book Antiqua on screen, in SVG and VML, but will map to the “Palatino-Roman” font on your PostScript printer. It is often necessary to do this, as the PostScript names of the printer-resident fonts often differ from the windows equivalent. Probably you will have to define each of the 4 styles of font individually, as the ‘italic’ might be oddly named, as in “Helvetica-Oblique” so RainPro cannot reliably generate names for the variants.

Listing alternative fonts

For internet use (VML or SVG), you might like to give a list of alternative fonts for a short code, for example:

ch.DefineFont 'AX' 'Lithos,Arial,Helvetica'

... will ask the browser for each of these fonts in sequence, and will use the first one available on the user’s machine. If the font names have embedded spaces, you should enclose the list in quotes.


Rain graphics: ch.WriteKey – output key at given location

ch.WriteKey – output key at given location

By default, Rain completes the key when you end the chart with ch.Close so you normally do not need this function. You would use it:

  • to position the key at an exact x,y location:
    ch.WriteKey 10 10
  • to flush out the key after each plot in a multiple set:
    ch.WriteKey ⍬

The x,y location places the top left corner of the key box (or the baseline of the first legend if the key is unboxed) at the chart co-ordinate you give. There are two alternative key styles which allow other positioning strategies:

  • keystyle=’absolute’ will use points co-ordinates, with the origin at the origin of your graph
  • keystyle-’percentage’ will treat the chart area (bounded by the axes) as 0-100 in each direction

You may also use the keystyles ‘top|middle|bottom’ and ‘left|centre|right’ to determine which edge of the key box is positioned at the co-ordinates you provide, for example keystyle=’vertical,percent,top,right’ could be used with x=95%, y=95% to place the key neatly in the top right corner of the chart area. Negative percentages (or numbers above 100%) may be used to place the key all or partially in the chart margins.

Note that before you do any plotting, the entire chart region has notional axes of 0⍎100 in both directions, so that you can use ch.Newand ch.Nulto position a key anywhere in the plotting space. See the Intercepts example for the technique.

See also ...

KeyStyle – key style


Rain graphics: ch.New – define the chart area

ch.New – define the chart area

Please note that all dimensions are given in points, which is a unit equal to 1/72 of an inch. The default chart region is 6” by 4.5” which fits nicely into most published material. This is equivalent to:

ch.New 0 0 432 324  ⍝ or just
ch.New 432 324

as the default starting location is the lower left corner. To set the charting region to a different shape, or to restrict the chart to a partial area, use this function with (x1,y1,x2,y2) in points from the lower left corner.

It may be helpful to call this function to reset the chart area to a convenient co-ordinate range before you add bitmaps or metafiles as ‘artworks’ to your completed chart:

ch.New 1000 1000
ch.Bitmap 'logo' ¯10 ¯10

This will add your logo in the top right corner of the chart area.


Rain graphics: ch.NewPage – request a new page

ch.NewPage – request a new page

To prepare a series of graphs for viewing or printing as a set, you can ask RainPro to complete the current page and reset all defaults with the command:

ch.NewPage

Note that this has no effect if you run it before any plotting commands, as you are already on a clean page by default.


Rain graphics: ch.Note – add chart notes

ch.Note – add chart notes

Adds text notes to the completed chart.

ch.Note 'Here is;a 2-line note' 20 30
ch.Note 'This is angled at 45deg' 20 30 45
ch.Note 'This is wrapped into a column 10units wide' 20 30 0 10

Properties Styles

The data should be at least a three-element list of text and (x,y) position. Line-breaks are marked by semi-colons in the text or you may use the maxwidth parameter to force RainPro to wrap the text for you. The X≡position gives the starting point of the text in the co-ordinate system of the chart; the Y≡position specifies the baseline position of the top line, measured on the Y≡axis. To position notes on a piechart, assume an imaginary co-ordinate system of 0⍎100 in both dimensions. You may also set the NoteStyle to ‘absolute’ and give positions in points (relative to the lower left corner of the plotting region) if you prefer. The note text may be centred or right-aligned on the x-position you give. You can make minor adjustments to the note positioning with the NoteNudge property, which takes an (x,y) displacement in points.

To position notes on a barchart, note that the bars are placed at X-values 0.5, 1.5, 2.5 and so on, regardless of the numeric values written on the X-axis tick marks.

To write notes vertically add the required rotation (90 in this case) as the fourth element of the position. Vertical notes are base-aligned on the position you give unless you set the note-style to ‘right’ in which case they are top-aligned. The ‘boxed’ and ‘shadowed’ styles are ignored for rotated notes.

To set the maximum width (in chart co-ordinates unless you are using the ‘absolute’ style) of the text, add a 4th element giving the column width (you will need to specify 0 for the rotation). The text is then wrapped into this width, breaking at any occurrence of blank, hyphen or your chosen SoftHyphen character (the default is tilde~).

See also ...

ch.NextNote | NoteFont | NoteNudge | NoteStyle | SoftHyphen

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ch.Query – query chart properties

ch.Query – query chart properties

This is a specialist function to allow general-purpose routines to have access to current settings.

xx←ch.Query 'key' 'heading'

This will retrieve the current values of the chart key and chart heading. Only the first two characters are significant here, and case is ignored. It will accept an optional boolean flag which returns the setting as the ‘string’ value rather than the internal (usually numeric) codes, for example:

      ch.Query 'hf'
4 18 2
      1 ch.Query 'hf'
TII,18,Navy

Note that the ordering of the properties in the string may not be the same as the ordering of the integer codes.


Rain graphics: ch.Set – setting chart properties

ch.Set – setting chart properties

To set any of the chart properties, use ch.Set in the same way as ⎕WS, with a list of (property value) pairs.

ch.Set ('Head' 'A Heading')('Key' 'First,Second')

If no property is given, the ‘Style’ property is assumed:

ch.Set 'boxed,grid'

Only the first two letters of the property name are significant, and case is ignored.


Rain graphics: ch.YSec – add a secondary Y-axis

ch.YSec – add a secondary Y-axis

It is often useful to plot two sets of data on the same graph, but against independent Y-axes (e.g. Price Index and Dollar conversion). This function sets up a new axis at the right, and resets the scaling so that the next set of data plotted will auto-range the new axis.

Properties

ch.Plot ∆first
ch.Ysec
ch.Plot ∆second

See Dupaxfor a typical example.

It is possible to have more than two axes here. Use the XIntercept property as required to set a target point for each Y-axis and call ch.YSec as many times as you require, followed each time by an appropriate plot.


Rain graphics: Axes – axis attributes

Axes – axis attributes

To set the attributes for the chart axes:

ch.Set 'Axes' 'red,solid,fine'   ⍝ or
ch.Set 'Axes' 1 1 2.5

The mnemonics may be given in any order, or you can use numbers strictly in the sequence shown above (colour, style, weight). The line weights are ‘hair, fine, medium, broad’ or you can give an exact line weight in points. The line styles are ‘solid, dot, dash, ddash, invisible’ or you can use numbers from 1 to 5.

To draw a labelled but invisible axis, it is better to use the ‘invisible’ style as this repositions the labels rather than simply not drawing the axis line and tickmarks.

See also ...

XStyle – X-axis style | YStyle – Y-axis style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Baseline – baseline for bars and surfaces

Baseline – baseline for bars and surfaces

To set a baseline from which the bars on barcharts hang, or from which surface charts are shaded:

ch.Set 'baseline' 6

The baseline is drawn with the current setting of the axis attributes, typically a black, medium-weight line. A typical use is for variance plots, where the bars are expected to run up and down from a zero line.


Rain graphics: FrameAttributes – frame & box attributes

FrameAttributes – frame & box attributes

To set the attributes for the chart frame, the half-moon of Dial charts and the boxes around notes:

ch.Set 'Box' 'Green,10%,2'
ch.Set 'Box' 3 2 1.5

You can use numbers strictly in the sequence shown above (Colour, Pattern, Weight). The patterns number from 1⍎39 and you can give an exact line weight in points for the edge. The default is solid white with a 1.5-point edge. The edge is always black. The Mobiles example shows a typical use of a lightly shaded chart box, with the key in a white knock-out within it.

The last 4 radial gradients (35-39) are designed to make effective backdrops when used with a fairly dark base colour.

See also ...

Gutter | KeyAttributes | Colour | Shading | Nib

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: CaptionFont – font for all axis captions

CaptionFont – font for all axis captions

Setting the font for all captions

To set the font for all the axis captions and the pagelabels:

ch.Set 'Cfont' 'ti,12,teal'

The short code for the font is a two-letter mnemonic followed by either or both of the letters ‘b’ and ‘i’ for the bold and italic variants. The font size is in points, and colours are the usual set of internet names or ‘#FF’ style values.

Setting x,y,z captions independently

You may over-ride this setting for any of the x,y,z captions independently with the XCaptionFont, YCaptionFont and ZCaptionFont properties. These properties may be used in conjunction, for example:

ch.Set ('Cfont' 'arb,14,Navy')('CYFont' 'Maroon')

Note that the ordering is important here – the generic font must be set first.

See also ...

Colour Cycle | Fonts – defining and using short codes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ClassInterval – class interval

ClassInterval – class interval

To set the class interval for the frequency plot:

ch.Set 'Classint' 20

The default is 1, but RainPro will attempt to make an intelligent judgement depending on the data you pass to ch.Freq


Rain graphics: DatumStyle – datum-line attributes

DatumStyle – datum-line attributes

To set the attributes for any datum lines:

ch.Set 'Datum' 'red,dashed,fine'

The mnemonics may be given in any order. The line weights are ‘hair, fine, medium, broad’ or you can give an exact line weight in points. The line styles are ‘solid, dot, dash, ddash, invisible’ or you can use numbers from 1 to 5.

See also ...

Colour Cycle | Line Styles | Nib Weights

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Explode – pie explode

Explode – pie explode

To pull one or more pie segments out from the centre:

ch.Set 'Explode' 0 0 0 20 0 0

The vector will be extended to match the number of segments plotted. It gives the amount to explode as a percentage of the pie radius.


Rain graphics: Gap – inter-bar gap

Gap – inter-bar gap

To set the gap between bars in the same group (default 0.618 of the bar width):

ch.Set 'Gap' 1

The gap is given as the fraction of a bar width. If the barchart is stacked (i.e. there are no groups) this sets the gap between bars. Small negative values are acceptable here, say -0.1 to give slightly overlapping bars. For tower charts it sets the gap between towers, and 0 is the smallest reasonable value.


Rain graphics: GroupGap – inter-group gap

GroupGap – inter-group gap

To set the gap between groups of bars or towers (default 1.618 of the bar width):

ch.Set 'GGap' 1.5

The gap is given as the fraction of a bar width. If the barchart is stacked (i.e. there are no groups) this has no effect.


Rain graphics: GridlineAttribs – gridline attributes

GridlineAttribs – gridline attributes

To set the attributes for both X and Y grid lines:

ch.Set 'Grid' 'green,dotted,fine'

The mnemonics may be given in any order. The line styles are ‘solid, dot, dash, ddash, invisible’ or you can use numbers from 1 to 5 (or higher numbers to use a custom dash pattern).

See also ...

Colour Cycle | Line Styles | Nib Weights

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Heading – main heading

Heading – main heading

The main chart heading is set with:

ch.Set 'Heading' 'Here is;the Main Heading'

It is centred by default above the chart. New lines are forced with a semi-colon in the text (to get a semi-colon, preceed it with a backslash character). You can also make a second heading line in a different font by specifying a subhead:

ch.Set 'Sub' 'This is a subordinate heading'

Heading and subhead share the same placement, but you can set the subhead font independently.

See also ...

HeadingFont – heading font | HeadingStyle – heading placement

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: HeadingFont – heading font

HeadingFont – heading font

To set the font and colour for the main chart heading:

ch.Set 'Hfont' 'tii,18,blue'

The short code for the font is a two-letter mnemonic followed by either or both of the letters ‘b’ and ‘i’ for the bold and italic variants. The font size is in points.

Colours are set by name (red,green,blue etc.) or as a hex string, for example to get a nice slate grey:

ch.Set('hfont' 'tii,18,#3E306A')  ⍝ Slate

See also ...

Colour Cycle | Fonts – defining and using short codes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: HorizontalMargins – margins (bottom/top)

HorizontalMargins – margins (bottom/top)

To set the lower and upper margins:

ch.Set 'Hmar' 36 12

The margins are specified in points, and should leave room for the heading at the top and the X-axis labels and title at the bottom. If you only give one number, both margins are set to this value. They measure from the edge of the chart area to the edge of the plotting region, i.e. the rectangle bounded by the axes. Please refer to the diagram on the glossary page.

See also ...

Margins – chart margins (tblr)


Rain graphics: HeadingStyle – heading placement

HeadingStyle – heading placement

Sets the position and alignment of the chart heading:

ch.Set 'hstyle' 'right,bottom'

Options

centre:left:right ... Horizontal placement
top:bottom ... Vertical placement
transparent:opaque ... Blank behind text
ruled:norule ... Rule across chart
pitch=120% ... Set the inter-line spacing
effect=id ... Attach a defined effect to the text

Options in bold are the normal defaults. Use style ‘ruled’ to rule across the entire chart area, just below the heading. You can set the line-spacing as a percentage of the font-size, or as absolute points.

To include a defined effect (such as an SVG shadow filter or animation) to the text:

ch.AddEffect 'Heading' '<animate dur="0" />'

You can add multiple effects to apply several filters or animations.

See also ...

HeadingLinespacing


Rain graphics: Key – legends for key

Key – legends for key

Specifies the text key for each line or group of bars. May also be used to key a piechart if preferred to spider labels.

ch.Set 'Key' 'North,South,East,West'

Note: If you use a semi-colon as the first character of a key, this forces the key onto a new line, or a new column in keys with the ‘vertical’ style. (see Praxis for an example).

ch.Set 'Key' 'North,South,;East,West'

Semi-colons used in the body of the key text split the text onto multiple lines – preceed the semi-colon by a backslash to have the legend include a semi-colon character. If you give more text elements than will fit into the available space, the default behaviour is to discard the over-flowed text. Set the KeyStyle to ‘Autofit’ to have RainPro reduce the font-size of the key text until all the legend fits correctly.

See also ...

KeyFrame – key frame override | KeyStyle – key style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: KeyFont – key font

KeyFont – key font

To set the font and colour for the text in the chart key:

ch.Set 'Kfont' 'he,10,red'  ⍝ Helvetica or Arial

The short code for the font is a two-letter mnemonic followed by either or both of the letters ‘b’ and ‘i’ for the bold and italic variants. The font size is in points, and colours use the standard internet names.

See also ...

Colour Cycle | Fonts – defining and using short codes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: KeyStyle – key style

KeyStyle – key style

Set the key layout and optionally box the key.

ch.Set 'kstyle' 'boxed,vert'

Options

boxed:nobox ... Draw box around completed key
shadowed:noshadow ... Add drop-shadow to box
rounded:square ... Corner style
vertical:horizontal ... Alignment of key entries
reversed:normal ... Order of key entries
inline:legend ... Placement of key text
relative:percentage:absolute ... Key placement
top:middle:bottom ... Location of key box to be vertically placed
left:centre:right ... Location of key box to be horizontally placed
plain:markers ... Omit markers in key
manual:autofit ... Reduce font size until key fits frame
pitch=120% ... Set the line-spacing for multi-line key text
effect=id ... Attach a defined effect to the key text

Options in bold are the normal defaults. Markers are normally included in keys if they are shown on each line – they can be omitted with style ‘plain’. When you use ch.WriteKey to place the key explicitly, the keys are normally positioned relative to the current (x,y) axes (style ‘Relative’) but you can choose to use absolute coordinates here, in which case you give the position of the key in Points from the chart origin (where the Axes would normally cross).

Any of the key layouts may be used with the autofit style. This starts with the type-size you specify and progressively reduces the font until the entire key fits into the available space. This may be a useful option if you are generating the key text from descriptions on a database, and hence do not know in advance how much space to allow for the key.

You would often want the ‘reversed’ ordering for stacked barcharts or surface charts. In this case the ‘reversed,vertical’ style means that the boxes in the key match the ordering of the bars or surfaces.

The ‘inline’ style is only used for Lineplots. It writes the key text immediately to the right of the last point on the line, so is appropriate for timeseries data with well-separated lines. It may be necessary to increase the space in the right margin to make room for long series names.

See also ...

ch.WriteKey – output key at given location | Using Autofit with Keys

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: LabelFont – label font

LabelFont – label font

Setting the font for all axis labels

To set the font and colour for the labels against each major tick mark:

ch.Set 'Lfont' 'ti,10,neutral'

The short code for the font is a two-letter mnemonic followed by either or both of the letters ‘b’ and ‘i’ for the bold and italic variants. The font size is in points, and colours use the standard internet names.

Setting x,y,z labels independently

You may over-ride this setting for any of the x,y,z labels independently with the XLabelFont, YLabelFont and ZLabelFont properties. These properties may be used in conjunction, for example:

ch.Set ('Lfont' 'arb,12,Navy')('LYFont' 'Green')

Note that the ordering is important here – the generic font must be set first.

See also ...

Colour Cycle | Fonts – defining and using short codes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: MissingValue – missing value(s)

MissingValue – missing value(s)

To tell RainPro to ignore specific values:

ch.Set 'Missval' 0

The default setting is 32768. The effect of setting it to zero is to make line graphs skip over zero values, rather than drawing an annoying line down to the axis wherever zero is hit. When you plot an array of data with differing numbers of elements, RainPro automatically pads the shorter series with the current missing-value setting. If you pass an array of values, all of them will be automatically excluded:

ch.Set 'Missval' ¯1 ¯99

This might be appropriate for data from some logging device, where a variety of negative numbers indicate various error conditions.

By default, line-graphs simply ‘bridge’ the missing points by joining the points on either side. Use the segmented style to have the line broken wherever data is missing.

See also ...

Not Applicable – placeholder for missing value


Rain graphics: NoteFont – note font

NoteFont – note font

To set the font and colour for any chart notes:

ch.Set 'Nfont' 'ari,8,green' ⍝ Small italic helvetica

The short code for the font is a two-letter mnemonic followed by either or both of the letters ‘b’ and ‘i’ for the bold and italic variants. The font size is in points, and colours follow the normal internet conventions.

See also ...

Colour Cycle | Fonts – defining and using short codes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: NoteStyle – note style

NoteStyle – note style

Set the appearance of any chart notes.

ch.Set 'nstyle' 'boxed'

Options

opaque:transparent ... Blank area behind notes
boxed:nobox ... Draw box around note
shadowed:noshadow ... Shadow note box
rounded:square ... Corner style
left;centre;right ... Text alignment
relative;absolute ... Note placement

Options in bold are the normal defaults. Normally, notes are positioned relative to the current (x,y) axes (style ‘Relative’) but you can choose to use absolute coordinates here, in which case you give the position of the note in Points from the chart origin (the position where the axes would normally cross). For multi-line notes, the position gives the start of the baseline of the first line of the text.

To include a defined effect (such as an SVG shadow filter or animation) to the text, give the effect id here:

ch.AddEffect 'Notes' '<animate .... />'

You can add multiple effects to apply several filters or animations to the note. This could be used to have a note slide in from the side, then change colour or fade out.

See also ...

NoteLinespacing


Rain graphics: Radii – pie sector radii and Dial pointers

Radii – pie sector radii and Dial pointers

To alter the radius of one or more pie segments:

ch.Set 'Radii' 90 90 100 50 20 100

The vector will be extended (with 100) to match the number of segments plotted. It gives the radius of each segment as a percentage of the normal pie radius. You may use numbers above 100 here, but the pie segments may collide with headings, legends and so on!

This property would normally be used with pies of equal segment angle (probably 8 or 16 segments) to make something called a ‘Rose diagram’. Consider the Polar chart as a better alternative here.

It may also be used to create a short pointer on a ‘Dial’ chart, for example to simulate two hands on a dial face.

See also ...

ch.Dial – dial and gauge charts | ch.Polar – polar charts

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Style – chart style

Style – chart style

Accepts a wide range of keywords which set global options for the current chart. These can subsequently be reset by prefixing the option with ‘no’ as in ‘nolines’ to plot with markers only.

ch.Set 'boxed,forcezero'
ch.Set ('style' 'boxed,nolines')('xtick' 5 4)( ... etc)

The keyword ‘style’ can be omitted in this case, but only if you set the style option on its own, as in the first example.

Options in detail

lines:nolines | Draw lines
marker:nomarker | Add markers
fill:nofill | Fill area within each line
kite:nokite | Draw trace charts as kite diagrams
halo:nohalo | Add halo to markers
surface:nosurface | Shade below the lines
arrow:noarrow | Add arrowheads to risers
cells:nocells | Record xy co-ordinates as cells (see Cellsize)
grouped:stacked:floating:horiz | Barchart options
shaded:floating | Stepchart options
axes:noaxes | Draw Axis lines (both)
framed:noframed | Draw axes all around chart area
rows:columns | Data series presented across or down
spider:nospider | Use keys as spider tags in piecharts
XYplot:timeseries | 1st column gives x-values
relative:absolute | Accumulate data values
index:noindex | Re-base values to run from 100
forcezero:noforce | Origin must go through zero
risers:norisers | Draw risers on step chart
tile:notile | Tile response surfaces
errorbars:noerrorbars | Draw MinMax as error-bar plot
arrows:noarrows | Add arrowheads to MinMax, Dial and line plots
wedge:annular | Warning zones on dial plots drawn as complete sectors
values:novalues | Add values to bars or beside markers
trend:notrend | Draw a simple trendline through a scatter plot
model:nomodel | Fit a straight line or polynomial through the data
growth:nogrowth | Fit an exponential growth (or decay) curve
annotate:noannotate | Add a note to the line giving the fit coefficients

Options shown in bold are the normal default settings. You can over-ride any of these using ch.SetDefault at initialisation time. If you set an inappropriate style (for example you choose ‘tile’ for a barchart) it will be accepted but ignored.

See also ...

ch.SetDefault – change shipped settings | FrameStyle – style of chart frame

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ValueTags – value tags

ValueTags – value tags

Value tags to be written against each data point. By default, these will simply be the numeric value of the data and will only be shown if the chart style includes ‘values’. If you set values explicitly with this property, they will always be shown.

ch.Set 'Values' VEC

They may be written on top of bar charts and Gantt charts, at the end of the bar (on horizontal bar charts) or within the bar using 'vstyle' 'inside'

The tags are automatically cleared once they have been drawn on a chart – if you want the same tags applied to a secondary plot, you will need to reset the property.

See also ...

ValueFormat – value-tag picture-format | ValueStyle – value-tag style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: ValueFont – value-tag font

ValueFont – value-tag font

To set the font and colour for the data value labels:

ch.Set 'Vfont' 'he,8,Green'

The short code for the font is a two-letter mnemonic followed by either or both of the letters ‘b’ and ‘i’ for the bold and italic variants. The font size is in points, and colours follow the normal internet naming rules.

See also ...

Colour Cycle | Fonts – defining and using short codes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: VerticalMargins – margins (left/right)

VerticalMargins – margins (left/right)

To set the left and right margins:

ch.Set 'Vmar' 48 24

The margins are specified in points, and should leave room for the Y-axis labels and title at the left. If you only give one number, both margins are set to this value. They measure from the edge of the chart area to the edge of the plotting region, i.e. the rectangle bounded by the axes. Please refer to the diagram on the glossary page.

If you require the Y-axis at the right, or have very long Y-labels (such as for a Gantt chart) you will need to adjust these values.

See also ...

Margins – chart margins (tblr)


Rain graphics: ValueStyle – value-tag style

ValueStyle – value-tag style

Sets the appearance of chart value labels.

ch.Set 'vstyle' 'inside'

Options

opaque:transparent ... Blank behind text
invert ... Use bar colour if ‘inside’ tag has no space and is drawn ‘ontop’
inherit ... Always use data colour (ignore colour in Value Font)
ontop;inside;middle ... Placement on barcharts, piecharts and markers
vertical:horizontal ... Orientation
cumulative;sector ... Cumulative or sector values on stacked barcharts
left:centre:right ... Relative placement (to markers)
pitch=110% ... Set inter-line spacing for multi-line value tags
angled ... Labels are written at 34deg to the right of the data points
effect=id ... Attach a defined effect to the tag text
hints:tips:normal ... Set as hints or tips on the data points

Options in bold are the normal defaults.

Value tags are normally drawn on top of bars and centred above markers on scatterplots. Use the ‘inside’ style to get the values drawn inside the bars (possibly in conjunction with ‘vertical’ if the labels are long) or to have values written in the markers on a scatterplot. This works well with the large circular markers (marker-13), probably scaled up by about 3 to make room for the value digits.

Use the ‘middle’ style to centre the labels vertically in each bar segment of a stacked barchart. This style would probably go with ‘sector’ to get sector values rather than cumulative totals.

ch.Set 'vstyle' 'sector,middle'

For horizontal barcharts the values are always drawn at the end of the bar furthest from the axis or baseline.

To have the values shown as statusbar hints in the chart viewer (and also in the browser status field with VML output to web pages) set the valuestyle to ‘hints’. This will not write any text into the chart, but will instead add the appropriate hotspots to trigger mouseover actions. Similarly, you can set a ‘tips’ style to have the values show as pop-up tips in the web-browser. The hints/tips will be formatted using the value picture format as normal.

Note that if you use log or scaled axes, the values always show the true (unscaled) data values here, so if you set a format picture, make sure you allow sufficient space.

To apply a defined effect (such as an SVG shadow filter or animation) to the text, give the effect id here:

ch.AddEffect 'Values' 'opacity:0.5'

You can add multiple effects to apply several filters.

See also ...

ValueLinespacing | ValueFormat – value-tag picture-format | ValueAngle – rotation of value tags

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: XCaption – X-caption

XCaption – X-caption

The X-axis caption is written below the end of the axis, spaced to allow room for labels (if any):

ch.Set 'xcap' '1994'

You can control the positioning with the X-axis style to place the caption centred (below the axis) or at the right-hand end. The caption text will be split over more than one line of you include a semi-colon in the text, for example:

ch.Set 'xcap' 'Elapsed days;from start of project'

To get a semi-colon into a caption, preceed it with a backslash character.

See also ...

CaptionFont – font for all axis captions | CaptionStyle – caption style | XCaptionFont – font for X caption | XStyle – X-axis style

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: XDatum – X-datum lines

XDatum – X-datum lines

To set one or more vertical datum lines:

ch.Set 'Xdatum' VEC

... where this is any list of numbers within the chart range – the X-axis range will automatically be extended to include them.

The datum-line setting is automatically cleared once they have been drawn on a chart – if you want the same lines applied to a secondary plot, you will need to reset the property.


Rain graphics: XFactor – X-label scale factor

XFactor – X-label scale factor

To scale your data in the X-dimension by a given factor:

ch.Set 'Xfactor' 1000

This allows you to use default (numeric) labelling for scaled data. The values will be drawn normally, but will be divided by the given factor to generate the labels.


Rain graphics: XIntercept – X-intercept

XIntercept – X-intercept

To set the point where the Y-axis intercepts the X-axis:

ch.Set 'Xint' 0

This will move the Y-axis from its default position (at the left-hand side of the plotting region) to cross the X-axis at zero. You have the option of leaving the tickmarks and labels at the left edge, or having them stay with the axis using the Ystyle ‘stay’.


Rain graphics: XLabels – X-axis labels

XLabels – X-axis labels

Sets the labels at each X-axis tick mark or define one label for each data-point:

ch.Set 'xlab' 'Jan,Feb,Mar, ... ,Dec'

The label placement can be adjusted with the axis style:

ch.Set 'xstyle' 'labmid'

X-labels may be multi-line – use ‘;’ to split the lines or add a level of nesting:

ch.Set 'xlab' 'Jan;1997,Jan;1998'     ⍝ or ...
ch.Set 'xlab' ('Jan' '1997')('Jan' '1998')

To get a semi-colon into a label, preceed it with a backslash character.

You may specify one label per data-point as an alternative to one label per tickmark. This allows you to use RainPro’s automatic tick-spacing algorithm which will select the matching label for each generated tickmark. You can also angle the labels with ch.Set 'XS' 'angled'and control the angle with ch.Set 'XA' degrees

See also ...

LabelStyle – label style | XLabelFont – font for X labels

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: XRange – X-axis range

XRange – X-axis range

To force the range of the X-axis to include the values you require:

ch.Set 'Xrange' 0 100

If you only give one number, the range is forced from zero to this value.

See also ...

ch.RangeAxes – set axis ranges


Rain graphics: XStyle – X-axis style

XStyle – X-axis style

The chart axes can be set independently with a variety of custom effects. The options shown here apply to the horizontal axes.

ch.Set 'xstyle' 'grid,labmid'

Options

angled:noangle | Inclined labels (see XAngle)
between:nobetween | Place tickmarks between bars or groups
forcezero:noforce | Axis must include zero in range
axis:plain:invisible:noaxis | Axis style (normal, unlabelled, hidden but labelled, not drawn)
linear:log:longitude | Data transformation and label type
date:time:annual:monthly | Various date and time options
duration:nodur | Represent integer values to base-60, typically elapsed times as hh:mm:ss
bottom:top:duplicate | Axis placement
atside:atend;centre | Caption placement
labmid:labadj:nolab | Label placement
move:stay | Ticks and labels move with intercept axes
grid:nogrid | Draw grid lines at major ticks
labels:nolabels | Omit labels if required
mtick:nomtick | Add minor tick marks at default spacing
flat:noflat | Force flat captions and labels on 3D charts
arrow:noarrow | Add arrowheads at axis extremities
clip:noclip | Clip axis (and data) at first and last tick mark
exact:extend | Axis will not be rounded up to the next whole tick mark

Options in bold are the normal defaults. See Tick Marks for examples of the various styles.

See also ...

XTickmarks – X-tick marks | XTickStyle – X-axis tickstyle | Using Timescale Axes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: XTickmarks – X-tick marks

XTickmarks – X-tick marks

To set the major and minor tick marks for the X-axis:

ch.Set 'Xtick' 12 11

The first number is the major tick interval (12 would be suitable for monthly data); the second, which may be omitted, gives the number of minor ticks in each major interval (this is ignored on 3D charts). You can also set the tick mark positions exactly with:

ch.Set 'Xtick' VEC

This trick is used in the Rainfallchart to get exact positioning of the calendar months. Note that if you use this facility, you will completely over-ride any previous settings on the axis range – the axis will be forced to span the gap from the first to the last tick mark you give.

To control the lengths of the major tickmarks, you can pass an additional vector of percentages, for example:

ch.Set 'Xtick' VEC (120 60 60 60)

This will draw major ticks at intervals of 1 and every fourth tick will be drawn at 120% of normal.

Notes

The tick-mark interval is always a simple integer value, unless you set the axis style to ‘time’ in which case you should give a value in hours here. For axis style ‘longitude’ the tick interval is interpreted as integer degrees, for style ‘Annual’ it is years and for style ‘Monthly’ it is months.

Note that by default, barcharts place the ticks on the ends of the bars, or at the centre of each group of bars. To get the ticks placed between the bars or groups:

ch.Set 'XS'  'between'

You can place the ticks between every nth group by setting the tickmark interval:

ch.Set 'Xtick' 4  ⍝ Data in quarters

Only single integer values are allowed here.

See also ...

Using Timescale Axes


Rain graphics: YCaption – Y-caption

YCaption – Y-caption

The Y-axis caption is written by default vertically alongside the axis:

ch.Set 'ycap' 'Tonnes'

It may also be placed at the top of the axis (see y-style):

ch.Set 'ystyle' 'atend'

This is a better placement for short captions such as ‘mm’ or ‘kg’. Captions written at the top of the axis will be split into multiple lines if you include a semi-colon in the text, for example ‘Height;(cm)’ will give a two-line caption. To get a semi-colon into a caption, preceed it with a backslash character. The Caption style controls the alignment of the text for captions placed ‘atend’.

See also ...

CaptionFont – font for all axis captions | CaptionStyle – caption style | YCaptionFont – font for Y caption

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: YDatum – Y-datum lines

YDatum – Y-datum lines

To set one or more horizontal datum lines:

ch.Set 'Ydatum' VEC

... where this is any list of numbers within the vertical chart range – the Y≡range will automatically be extended to include them.

The datum-line setting is automatically cleared once they have been drawn on a chart – if you want the same lines applied to a secondary plot, you will need to reset the property.


Rain graphics: YFactor – Y-axis scale factor

YFactor – Y-axis scale factor

To scale your data in the Y-dimension by a given factor:

ch.Set 'Yfactor' 1000

This allows you to use default (numeric) labelling for scaled data. The values will be drawn normally, but will be divided by the given factor to generate the labels.


Rain graphics: YIntercept – Y-intercept

YIntercept – Y-intercept

To set the point where the X-axis intercepts the Y-axis:

ch.Set 'Yint' 0

This will move the X-axis from its default position (at the bottom of the plotting region) to cross the Y-axis at zero.


Rain graphics: YLabels – Y-axis labels

YLabels – Y-axis labels

Sets the labels for each tick mark on the vertical axis:

ch.Set 'Ylab' 'One,Two,Three'

This would commonly be used with a horizontal chart style, such as a barchart or Gantt chart.

To get multi-line labels, split the label text with semi-colons as in:

ch.Set 'Ylab' 'Oak,Ash,Small;leaved;Lime,Elder'

The lines will be vertically spread symmetrically around the position of each y-tickmark. To get a semi-colon into a label, preceed it with a backslash character.

See also ...

LabelStyle – label style | YLabelFont – font for Y labels

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: YRange – Y-axis range

YRange – Y-axis range

To force the range of the Y-axis to include the values you require:

ch.Set 'Yrange'  1200 2000

If you only give one number, the range is forced from zero to this value.

See also ...

ch.RangeAxes – set axis ranges


Rain graphics: YStyle – Y-axis style

YStyle – Y-axis style

The chart axes can be set independently with a variety of custom effects. The options shown here apply to the vertical axes.

ch.Set 'ystyle' 'grid,atend'

Options

forcezero:noforce | Axis must include zero in range
exact:extend | Axis will not be rounded up to the next whole tick mark
axis:plain:invisible:noaxis | Axis style (normal, unlabelled, hidden but labelled, not drawn)
left:right:duplicate | Axis placement
invert:noinvert | Scale increments downwards
atside:atend;centre | Caption placement (vertical)
move:stay | Ticks and labels move with intercept axes
linear:log:latitude | Data transformation and label type
date:nodate | Convert the integer part of numbers to date format
time:notime | Convert the fractional part of numbers to times (HH:MM)
duration:nodur | Represent integer values to base-60, typically elapsed times as hh:mm:ss
grid:nogrid | Draw grid lines at major ticks
labels:nolabels | Omit labels if required
flat:noflat | Force flat captions and labels on 3D charts
arrow:noarrow | Add arrowheads at axis extremities
clip:noclip | Clip axis and plotted data at first and last tick mark. Lines will be broken at the chart edge; markers outside the chart edge are not drawn

Options in bold are the normal defaults. See Tick Marks for examples of the various styles.

Note that you would normally use the ‘invert’ option in conjunction with xstyle 'top'

See also ...

YTickmarks – Y-tick marks | YTickStyle – Y-axis tickstyle | Using Timescale Axes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: YTickmarks – Y-tick marks

YTickmarks – Y-tick marks

To set the major and minor tick marks for the Y-axis:

ch.Set 'Ytick' 5 4

The first number is the major tick interval; the second (which may be omitted) gives the number of minor ticks in each major interval (this is ignored on 3D charts). You can also set the tick mark positions exactly with:

ch.Set 'Ytick' VEC

A common use of this would be to set your choice of tickmarks on a logarithmic Y-axis. Note that if you use this facility, you will completely over-ride any previous settings on the axis range – the axis will be forced to span the gap from the first to the last tick mark you give.

The tick-mark interval is always a simple integer value, unless you set the axis style to ‘time’ in which case you should give a value in hours here. For axis style ‘latitude’ the tick interval is interpreted as integer degrees.

See also ...

YStyle – Y-axis style | Using Timescale Axes

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Colour Cycle

Colour Cycle

RainPro has a pre-defined colour cycle, such that the colours are used in turn for each line or bar or pie-segment that you draw. The standard setting is ‘Navy,Maroon,Teal,Green,Purple,Gray’. To reset the cycle:

ch.Set 'Colours' 'maroon,green,teal'     ⍝ or
ch.Set 'Colours'  5 2 7 1 4           ⍝ by number

The standard colours are:

0. Black | 8. Silver
1. Maroon | 9. Red
2. Green | 10. Lime
3. Olive | 11. Yellow
4. Navy | 12. Blue
5. Purple | 13. Fuchsia
6. Teal | 14. Aqua
7. Gray | 15. White

If you are plotting a lot of lines on the same chart, ensure that the colour, marker and line-style cycles are of different lengths to give you the maximum number of permutations. The function Colours (in the RainPro workspace) illustrates all these for you.

Using 24-bit colour settings

RainPro extends colour support to 24-bit with the HTML convention of setting colours by RGB encoded as a hex string e.g. “#FCFCF0”. These hex strings can be used anywhere a colour name is allowed.

  ch.Set ('axis' 'med,#C86106')  ⍝ orange axis line
 ⍝ Slate heading
  ch.Set ('head' 'Sample Heading')('hfont' 'heb,24,#3E306A')
  ch.Set ('colour' '#9DC806,#78598D')('pattern' 15)
  ch.Bar 12 2⍴⍳12    ⍝ Lime and mauve bars

The assumption is that these hex strings will be computer-generated! Otherwise just paste the values from the Paintshop Pro 5 colour wheel. Note the last example – you will probably want to use solid fills for bars and pies, particularly as these reduce the file sizes on PNG output due to better compression. It will probably pay to check the appearance of your charts on a 256-colour system, as browsers can sometimes make a very unexpected mapping of 24-bit colour.


Rain graphics: Line Styles

Line Styles

RainPro has a pre-defined cycle of line-styles which are used in turn for each line that you draw. The default cycle is ‘Solid,Dashed,Dotted,DDash’. To reset the cycle:

ch.Set 'Lines' 'solid,dot,solid,dash'      ⍝ or
ch.Set 'Lines' 1 3 1 2                     ⍝ by number

If you are plotting a lot of lines on the same chart, ensure that the colour, marker and line-style cycles are of different lengths to give you the maximum number of permutations. You can easily make all lines solid (for example if you have a colour printer) by setting ‘Solid’ or ‘1’ as the line style.

The available line types are:

  1. Solid
  2. Dashed
  3. Dotted
  4. Dot-Dash
  5. Dash-Dot-Dot
  6. Invisible

You can change these (or add new types) if required. See Changing the Dashline Repeat for details.


Rain graphics: Chart Marker Cycle

Chart Marker Cycle

RainPro has a pre-defined cycle of up to 21 markers which are used in turn for each series that you draw. The default cycle is ‘Cross,Plus,Diamond,Triangle,Del,Lozenge’. To reset the cycle:

ch.Set 'Markers'  1 2 1 3          ⍝ by number

1. Cross ... 9. ... Dot – 1 pixel
2. Plus ... 10. ... SmallBullet – 5 pixel
3. Diamond ... 11. ... Bullet – 9 pixel
4. Triangle (point upwards) ... 12. ... Circle (open circle)
5. Del (point downwards) ... 13. ... Ring (thick open circle)
6. Lozenge (filled diamond) ... 14. ... Node
7. Block (solid square) ... 15. ... Ball
8. Invisible ... ...

Markers 9⍎11 are solid circles which increase in area in a constant ratio, so that they can be used (for example) for density maps where each marker might represent a population size at that point. Markers 14 and 15 are ‘3D≡effect’ spheres (small and large) intended for use in 3D plots.

Markers 16-21 are intended for use in ‘hi-lo-close’ charts and are simple ‘ticks’ which fall either side of horizontal or vertical lines.

16. ... LeftTick
17. ... RightTick
18. ... UpTick
19. ... DownTick
20. ... Hyphen
21. ... Bar

Numbers above 21 (it may be best to use numbers from 100-999) are free for your own markers. See User Defined Markers for more information – you can use characters or simple vector graphics as custom markers.


Rain graphics: Shading Patterns

Shading Patterns

RainPro has a pre-defined cycle of shading patterns which are used in turn for each filled area (bar, pie-segment, surface) that you draw. The default fills are ‘20%,80%,10%,60%’ to allow shaded bars or pie sectors to be easily distinguished on Black&White printers. To reset the cycle:

ch.Set 'Patterns' 7 4 3 4 5      ⍝ by number

Pattern-0 is ‘no fill’; the next 7 patterns are fills of gradually increasing saturation, and pattern-8 is ‘solid background’. If you intend to print in colour, you might like to set the pattern cycle to ‘Solid’ or a comfortable halftone (80% usually works well) so that all the bars or pie sectors get the same depth of colour. The remaining patterns cover 8 opacities (which work in VML and SVG only) and 16 gradient fills (VML, SVG, PDF).

0. Unfilled | 8. Background | 16. 6% opaque | 24. SE-NW gradient | 32. Pipe
1. 10% colour | 9. Left stripe | 17. 18% opaque | 25. E-W gradient | 33. Drum
2. 20% colour | 10. Right stripe | 18. 30% opaque | 26. NE-SW gradient | 34. Dome
3. 30% colour | 11. Hatched | 19. 42% opaque | 27. N-S gradient | 35. Sunrise
4. Half Tone | 12. Bricks | 20. 54% opaque | 28. NW-SE gradient | 36. TL spotlight
5. 60% colour | 13. Fishscale | 21. 66% opaque | 29. W-E gradient | 37. BL spotlight
6. 80% colour | 14. Basket | 22. 78% opaque | 30. SW-NE gradient | 38. BR spotlight
7. 90% colour | 15. Full colour | 23. 90% opaque | 31. S-N gradient | 39. TR spotlight

The illustration shows the SVG rendering of these – note that none of the hatchings are implemented in VML, SVG or PDF.

In general the lower-numbered patterns give a more restful effect; use the higher numbers with a dark colour for best results. Opacities are not supported by PDF, so these are emulated by mixing in some background colour as for patterns 1-7. The gradient fills work well in all formats, but there are some minor differences in appearance, as the way fills are specified varies greatly between the various rendering engines. The function Patternsillustrates these for you. Numbers above 40 are free for your own use as custom tiles but it may be better to use numbers above 100 as more preset patterns may be added in the future.


Rain graphics: Nib Weights

Nib Weights

By default, RainPro uses a pre-defined cycle of line-weights which are used in turn for each line that you draw. The default is to use ‘fine’ for every series. To reset the cycle:

ch.Set 'Nib' 'medium,broad'            ⍝ or
ch.Set 'Nib' 0.4 1.2                   ⍝ by points

You can set the weights to an exact line width in points, or use the pre-defined weights ‘hairline’, ‘fine’, ‘medium’, ‘broad’. Unless you want to make a really strong emphasis, it is probably best to set all the lines to the same nib weight.


Rain graphics: Fonts – defining and using short codes

Fonts – defining and using short codes

In general, charts can be designed very effectively using only variants of the standard fonts Times New Roman and Arial, so rather than asking you to enter these every time you need to set a font, RainPro uses a set of short codes like:

  • TI – means Times New Roman (TrueType) or Times-Roman (PostScript)
  • AR – means Arial (TrueType) or Helvetica (PostScript)

This approach also means that you can safely use EPS output (Encapsulated PostScript) to save your charts in a very high-quality format suitable for publishing tools like Quark Express, and also that your charts will be very reliably displayed on the internet when you render them in VML or SVG format.

To get the italic variant of any font, add ‘I’ to the end of the code, and similarly ‘B’ selects the bold style, so:

  • TIB – means Times New Roman, Bold
  • ARI – means Arial, Italic (Oblique)
  • TIBI – is Times New Roman, Bold, Italic

Fonts which only have a single variant (such as Symbol) can have a 4-letter short-code.

The default set of font codes which RainPro provides are:

TI | Times-Roman
TII | Times-Italic
TIB | Times-Bold
TIBI | Times-BoldItalic
AR | Arial
ARI | Arial-Oblique
ARB | Arial-Bold
ARBI | Arial-BoldOblique
CO | Courier
COI | Courier-Oblique
COB | Courier-Bold
COBI | Courier-BoldOblique
SYMB | Symbol
WING | Wingdings

Modifying the font table

If you need a font for a particular chart, you can add a code for it directly into the chart specification by including a Define font entry with the short code and TrueType name. You can now refer to the code as above. If you intend to export your charts in either of the PostScript formats (EPS or Distiller input for PDF generation) you should include the PostScript font name also. If you omit this, all extra fonts will appear as Times-Roman in the EPS file.

See also ...

ch.DefineFont – define new TrueType fonts


Rain graphics: Tick Mark Styles

Tick Mark Styles

RainPro always defaults to drawing tick-marks entirely outside the plotting region. However you can over-ride this by setting the appropriate tickmark style. See X-tick styles and Y-tick styles for details.

Note that minor ticks are not drawn on 3D plots.


Rain graphics: Using Timescale Axes

Using Timescale Axes

Timeseries data from Excel or from a database query is often held internally as floating-point numbers where the integer part represents the date (the number of days elapsed since 1900) and the decimal part the time of day. This scheme is accurate to around 2 sec with normal floating-point precision.

For example day number 35414 is actually 15/12/96 (in DD/MM/YY format) so 35414.5 would be 15/12/96 12:00, as times run from midnight to 23:59 spanning the range 0-1. RainPro can accept ‘date’ and ‘time’ styles (or both together) on either the X or Y axes, and will format the labels accordingly. The dates are shown by default in the format of your current Windows ‘short date’ setting and the times are normally shown as ‘HH:MM’ on a 24-hour clock.

Value ... Style ... Shown as
35414.25 ... (default) ... 35400
35414.25 ... date ... 15/12/96
35414.25 ... time ... 06:00
35414.25 ... date,time ... 15/12/96 06:00

For more detailed control over the presentation of the date/time combination, you can use the DateFormat and TimeFormat properties, for example to label tickmarks ‘Jan-01’ ‘Feb-01’ .... ‘Dec 02’ (in your local language) a suitable format would be “MMM-yy”.

The X-axis will also accept integers in the range 19000000 to 20991231 and (if the x-style is one of ‘date/annual/monthly’) treat these as if they are Excel-style date values. This may be convenient if you have imported your dates from an old-style time-series database, as this is a very common format in many database designs.

The tick-mark interval for both X and Y axes is normally a simple integer value, but for axes which include the ‘time’ style it is interpreted as a number of hours, so to get ticks every 6 hours you should set ‘Xtick’ to 6 rather than 0.25 (which would be the normal interpretation of this setting). Default tickmarks normally look for intervals which divide into 10; for time-based axes the choice is made between values which divide into 12 which gives a much better selection of intervals.

Calendar styles

In addition to ‘date’ you can set the x-axis (only) to style ‘annual’ which will put tickmarks at the year boundaries (so the tick spacing will be very slightly irregular). In this case the tick interval gives the number of years, so to mark decades you could use:

ch.Set ('xstyle' 'annual)('xtick' 10)

This style would very likely go along with ‘labmid’ to get the labels written between the tick marks. The style ‘Monthly’ works in a similar way – in this case the tickmark setting is the interval between months.

See also ...

DateFormat | TimeFormat | XStyle | XTickmarks | YStyle | YTickmarks

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Picture formatting

Picture formatting

You may apply a ‘picture’ format to numeric values, and also to text labels to enforce truncation or wrapping into a given width.

Formatting numeric values

Wherever you can use numeric value as labels (axes and data value tags) you may specify a suitable format string to have the numbers converted to appropriate text. Typical formats would be:

  • ‘##0.00’ allows space for 3 leading digits and always shows 2 decimal places
  • ‘#,###,##0’ inserts commas at the thousands and has no decimal places
  • ‘0000’ formats with leading zeros (always 4 digits)
  • ‘0.0E00’ uses scientific format, showing 2 significant figures
  • ‘##0%’ shows a trailing percent sign
  • ‘£##0.00’ floats a leading currency symbol
  • ‘---0.00’ floats a leading minus sign if the numbers are negative
  • ‘(#,##0.00’ shows negative values in parentheses
  • ‘Week #0’ shows ‘Week 1’ .... ‘Week 52’

More formally ...

The characters ‘#’, ‘-’ and ‘0’ are used to place the digits. The total number of ‘-#0’ characters in front of the decimal point determines the largest number you can display. Larger numbers are shown as ‘****’ to indicate overflow. Leading ‘0’ characters are zero-filled; leading ‘#’ characters are suppressed if not used. Digits after the decimal point are always shown, so ‘#’ and ‘0’ are equivalent here. Negative numbers are given a leading ‘-’ only if you use ‘-’ rather than ‘#’ as the placeholder.

The common currency symbols ‘$£’ and Euro will float to the front of the result if used as the first character in the format.

The character ‘~’ suppresses the digit in that position, so a vector of years could be formatted as ‘~~00’ to suppress the century part of the 4-digit number.

If the picture begins with an opening parenthesis, negative numbers will be parenthesised, rather than being shown with leading -ve symbols.

If any of the tokens ‘E-0’ ‘E+0’ ‘E0’ occur in the formatter, scientific notation will be used. A ‘+’ in the exponent part will always be shown, but a minus will only be shown when necessary. Floating currency symbols and other leading and trailing characters may be used as normal, for example ‘-##0.00E+00kg’ is a valid formatter here.

All other characters are simply treated as insertions, with the exception of ‘,’ which is only inserted if there were enough digits in the number to require it. The trailing % does not automatically scale the data.

Note that you always use the ‘American’ convention here for the decimal and thousands separators. These will be converted to your local currency symbols by the formatting function before the finished text is written to the chart.

Formatting text labels

A limited subset of the picture formatting capability may be used with text items, such as value tags and axis labels.

  • ‘XXXXXXXX’ simply limits the length of each label to a string of this size in the current font. If any of the labels is longer, it is clipped to one character less than the allowed length and the last character is set to an ellipsis. For very short patterns (less than 3 characters) the output is simply clipped to the pattern length.
  • ‘XXXXX;’ will force the text of each label to wrap into the allowed width.

Any other characters are treated as insertions, so a format like ‘SKU:XX/XXXX’ could be used for product codes, or a format such as ‘XXXX-XX-XX’ would be appropriate for text dates in the form 20020612. You may use your current line-break character as an insertion within the string, for example ‘SKU:;XXXXXX’ will make 2-line labels prefixed with ‘SKU:’.


Rain graphics: Using Autofit with Keys

Using Autofit with Keys

When you set up your chart frame and margins, RainPro defaults to using the available space in the bottom margin to write any key (or legend) text. You may override this by setting an explicit key frame, but sometimes it is hard to calculate exactly how much space you need, as the key text may be coming from a database system which is outside your control.

This key style allows you to set up a reasonable key font and frame, and have RainPro adjust the font (downwards only) to ensure all your legends fit in the allowed space. If you want to force an exact fit regardless (for example into a vertical frame) set a font size a little bigger than you really need so that RainPro sizes it down for you. The font is adjusted in 0.25 point decrements, so do not choose a very large size, as this will run the key-fitting code many times before the correct size is chosen.

Example of autofit

This example shows a vertical (reversed) key, which has been set to 10-point Arial.

As you can see, several of the texts are missing (having overflowed the allowed frame at the bottom) and also some words spill out of the right-hand side of the frame. If we enable the ‘autofit’ style on the key, the chart will look like:

As a final test, we can make the frame a little narrower, which constrains the text further and leaves some spare white space at the bottom of the key.

The text will not be reduced below 3pt in size – if the key does not fit at this size it will be truncated as before.

See also ...

Key – legends for key | KeyFont – key font | KeyFrame – key frame override

Send comments on this topic
© Dyalog Ltd 2007


Rain graphics: Caption

Caption

Caption is the term used for the text label on any axis.

It is also used to describe the label in the top left corner of a table, and the internal text in a dial chart.


Rain graphics: Attributes

Attributes

This is a generic term for the combination of Colour, Line-style (or pattern) and nib-width that characterise a line or filled shape.


Rain graphics: Property List

Property List

Barchart

  • Axes
  • Barchart style
  • Bar edge
  • Background
  • Bar limit
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Data style
  • Datumline attr
  • Datumline tags
  • DatumTag font
  • Date format
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gap
  • Group gap
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Subhead
  • Subhead font
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • Window
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-tick lengths
  • X-tick style
  • X-zones
  • X-grid threshold
  • X-datum threshold
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick lengths
  • Y-grid threshold
  • Y-datum threshold
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs


Rain graphics: Property List

Property List

BoxWhisker

  • Axes
  • Background
  • Baseline
  • Baseline attributes
  • Boxplot style
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Datumline attr
  • Date format
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gap
  • Group gap
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Heading nudge
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Subhead
  • Subhead font
  • Time format
  • Where
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-tick style
  • X-zones
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-tick style
  • Y-zones
  • Zone attribs


Rain graphics: Property List

Property List

Bubble

  • Arrow style
  • Axes
  • Background
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Cell size
  • Contour attributes
  • Bubble style
  • Data style
  • Datumline attr
  • Density
  • Date format
  • Equation format
  • Equation style
  • Equation position
  • Flexibility
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Locale
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Note font
  • Note nudge
  • Note style
  • Note linespacing
  • Order of fit
  • Page-labels
  • Subhead
  • Subhead font
  • Tease
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Weightings
  • Where
  • Window
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-data range
  • X-tick lengths
  • X-tick style
  • X-zones
  • X-grid threshold
  • X-datum threshold
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick lengths
  • Y-grid threshold
  • Y-datum threshold
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs
  • Z-caption
  • Z-factor
  • Z-format
  • Z-range
  • Z-tickmarks
  • Z-data range
  • Modelfit span


Rain graphics: Property List

Property List

Cloud

  • Axes
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Cloud style
  • Contour attributes
  • Data style
  • Datumline tags
  • DatumTag font
  • Density
  • Equation format
  • Equation style
  • Equation position
  • Flexibility
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Order of fit
  • Page-labels
  • Perspective
  • Subhead
  • Subhead font
  • Tips
  • Versus
  • Viewpoint
  • Wall patterns
  • Where
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-data range
  • X-tick style
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick style
  • Y-var
  • Z-caption
  • Z-datum
  • Z-caption font
  • Z-factor
  • Z-format
  • Z-labels
  • Z-label font
  • Z-range
  • Z-style
  • Z-tickmarks
  • Z-tick style
  • Z-data range


Rain graphics: Property List

Property List

Contour

  • Arrow style
  • Axes
  • Background
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Cell size
  • Contour attributes
  • ContourTag font
  • Contour style
  • Data style
  • Datumline attr
  • Datumline tags
  • DatumTag font
  • Density
  • Date format
  • Equation format
  • Equation style
  • Equation position
  • Flexibility
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Locale
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Note font
  • Note nudge
  • Note style
  • Note linespacing
  • Order of fit
  • Page-labels
  • Subhead
  • Subhead font
  • Tease
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Weightings
  • Where
  • Window
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-data range
  • X-tick lengths
  • X-tick style
  • X-zones
  • X-grid threshold
  • X-datum threshold
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick lengths
  • Y-grid threshold
  • Y-datum threshold
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs
  • Z-caption
  • Z-datum
  • Z-factor
  • Z-format
  • Z-range
  • Z-tickmarks
  • Z-zones
  • Z-data range
  • Modelfit span


Rain graphics: Property List

Property List

Dial

  • Arrow style
  • Axes
  • Background
  • Caption font
  • Caption linespacing
  • Dial style
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Frame attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Heading nudge
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Missing value
  • Page-labels
  • Radii
  • Subhead
  • Subhead font
  • X-caption
  • X-caption font
  • X-format
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-tick style
  • X-zones
  • Y-caption font
  • Y-label font
  • Zone attribs


Rain graphics: Property List

Property List

Group by

  • Group function
  • Group into


Rain graphics: Property List

Property List

Gantt

  • Axes
  • Bar edge
  • Background
  • Bar width
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Datumline attr
  • Date format
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • GanttChart style
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Locale
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Subhead
  • Subhead font
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-tick style
  • X-zones
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs


Rain graphics: Property List

Property List

Histogram

  • Axes
  • Bar edge
  • Background
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Class interval
  • Datumline attr
  • Datumline tags
  • DatumTag font
  • Date format
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Frequency style
  • Gap
  • Group gap
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Subhead
  • Subhead font
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • X-angle
  • X-caption
  • X-caption font
  • X-factor
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tick style
  • X-zones
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs


Rain graphics: Property List

Property List

Multiple

  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Heading nudge
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Page-labels
  • Subhead
  • Subhead font
  • Type of chart
  • Versus
  • X-caption
  • X-label font
  • X-style
  • X-tick style
  • Y-caption
  • Y-label font
  • Y-style
  • Style


Rain graphics: Property List

Property List

Null

  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Frame attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Heading nudge
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Marker scales
  • Page-labels
  • Subhead
  • Subhead font


Rain graphics: Property List

Property List

Pie

  • Axes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Contour style
  • Edge attributes
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Missing value
  • Page-labels
  • Piechart style
  • Pie explosion
  • Pie centre
  • Pie radius
  • Pie startangle
  • Subhead
  • Subhead font
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • X-caption
  • X-caption font
  • X-format
  • X-labels
  • X-label nudge
  • X-label font
  • Y-caption font
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-var


Rain graphics: Property List

Property List

Linegraph

  • Marker colours
  • Arrow style
  • Axes
  • Bar edge
  • Background
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Cell size
  • Data style
  • Datumline attr
  • Datumline tags
  • DatumTag font
  • Date format
  • Equation format
  • Equation style
  • Equation position
  • Flexibility
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • IndexOrigin
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Linegraph style
  • Marker scales
  • Marker colours
  • Missing value
  • Note font
  • Note nudge
  • Note style
  • Note linespacing
  • Order of fit
  • Page-labels
  • Subhead
  • Subhead font
  • Tease
  • Time format
  • Tips
  • Tick width
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • Window
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-data range
  • X-tick lengths
  • X-tick style
  • X-zones
  • X-grid threshold
  • X-datum threshold
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick lengths
  • Y-grid threshold
  • Y-datum threshold
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs
  • Series key
  • Trendline key
  • Modelfit key
  • X-Tracker format
  • Y-Tracker format


Rain graphics: Property List

Property List

Polar

  • Arrow style
  • Axes
  • Background
  • Caption format
  • Caption style
  • Caption linespacing
  • Data style
  • Flexibility
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Heading nudge
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Polar style
  • Subhead
  • Subhead font
  • Tick width
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • X-factor
  • X-format
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-tick style
  • Y-caption
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick style
  • Y-var


Rain graphics: Property List

Property List

Response

  • Axes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • ContourTag font
  • Data style
  • Datumline tags
  • DatumTag font
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Heading nudge
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Perspective
  • Response style
  • Subhead
  • Subhead font
  • Versus
  • Viewpoint
  • Wall patterns
  • Where
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-tick style
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-tick style
  • Y-var
  • Z-caption
  • Z-caption font
  • Z-factor
  • Z-format
  • Z-labels
  • Z-label font
  • Z-range
  • Z-style
  • Z-tickmarks
  • Z-tick style


Rain graphics: Property List

Property List

Scatter

  • Marker colours
  • Arrow style
  • Axes
  • Background
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Cell size
  • Contour attributes
  • Data style
  • Datumline attr
  • Datumline tags
  • DatumTag font
  • Density
  • Date format
  • Equation format
  • Equation style
  • Equation position
  • Flexibility
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Locale
  • Label style
  • Label linespacing
  • Marker scales
  • Marker colours
  • Missing value
  • Note font
  • Note nudge
  • Note style
  • Note linespacing
  • Order of fit
  • Page-labels
  • Parity tolerance
  • Parity line attributes
  • Parity limit attributes
  • Parity zone
  • Parity style
  • Scatter style
  • Subhead
  • Subhead font
  • Tease
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Weightings
  • Where
  • Window
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-data range
  • X-tick lengths
  • X-tick style
  • X-zones
  • X-grid threshold
  • X-datum threshold
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick lengths
  • Y-grid threshold
  • Y-datum threshold
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs
  • Z-tickmarks
  • Series key
  • Trendline key
  • Modelfit key
  • Modelfit span


Rain graphics: Property List

Property List

Split by

  • Split into


Rain graphics: Property List

Property List

Step

  • Axes
  • Bar edge
  • Background
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Data style
  • Datumline attr
  • Datumline tags
  • DatumTag font
  • Date format
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Stepchart style
  • Subhead
  • Subhead font
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-tick style
  • X-zones
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs


Rain graphics: Property List

Property List

Tower

  • Axes
  • Bar edge
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Data style
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gap
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Perspective
  • Subhead
  • Subhead font
  • Tips
  • Tower aspect
  • Tower limit
  • Tower patterns
  • Tower style
  • Versus
  • Viewpoint
  • Wall patterns
  • Where
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-tick style
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-tick style
  • Y-var
  • Z-caption
  • Z-caption font
  • Z-factor
  • Z-format
  • Z-labels
  • Z-label font
  • Z-range
  • Z-style
  • Z-tickmarks
  • Z-tick style


Rain graphics: Property List

Property List

Table

  • Background
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Split into
  • Data style
  • Edge attributes
  • Footnote
  • Footnote font
  • Footnote style
  • Frame attribs
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Hyperlinks
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Missing value
  • Not applicable
  • Subhead
  • Table position
  • Table style
  • Tips
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • X-caption font
  • X-format
  • X-labels
  • X-label nudge
  • X-label font
  • X-style
  • X-tick style
  • Y-caption
  • Y-caption font
  • Y-format
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-style
  • Y-tick style


Rain graphics: Property List

Property List

Triangle

  • Arrow style
  • Axes
  • Background
  • Caption format
  • Caption style
  • Caption linespacing
  • Data style
  • Flexibility
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Heading nudge
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Subhead
  • Subhead font
  • Tick width
  • Triangle style
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Where
  • X-caption
  • X-factor
  • X-label font
  • Y-caption
  • Y-label font
  • Z-caption


Rain graphics: Property List

Property List

VennDiagram

  • Edge attributes
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Venn style
  • Value tags
  • Value font
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • X-format
  • X-labels
  • X-label nudge
  • X-label font


Rain graphics: Property List

Property List

Vector

  • Arrow style
  • Axes
  • Background
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Datumline attr
  • Datumline tags
  • DatumTag font
  • Date format
  • Flexibility
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Min-Max style
  • Missing value
  • Page-labels
  • Subhead
  • Subhead font
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-data range
  • X-tick lengths
  • X-tick style
  • X-zones
  • X-grid threshold
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs


Rain graphics: Property List

Property List

Min-Max

  • Arrow style
  • Axes
  • Background
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Data style
  • Datumline attr
  • Datumline tags
  • DatumTag font
  • Date format
  • Flexibility
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Min-Max style
  • Missing value
  • Page-labels
  • Subhead
  • Subhead font
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-data range
  • X-tick lengths
  • X-tick style
  • X-zones
  • X-grid threshold
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs


Rain graphics: Property List

Property List

X-Bar

  • Axes
  • Barchart style
  • Bar edge
  • Background
  • Bar width
  • Baseline
  • Baseline attributes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Data style
  • Datumline attr
  • Datumline tags
  • DatumTag font
  • Date format
  • Footnote
  • Footnote font
  • Footnote style
  • Footnote linespacing
  • Gridline attribs
  • Gutter
  • Heading
  • Heading font
  • Heading style
  • Heading linespacing
  • Hints
  • Heading nudge
  • Hyperlinks
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label mask
  • Locale
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Page-labels
  • Subhead
  • Subhead font
  • Time format
  • Tips
  • Value tags
  • Value font
  • Value nudge
  • Value format
  • Value style
  • ValueTag linespacing
  • Value angle
  • Versus
  • Where
  • X-angle
  • X-caption
  • X-caption font
  • X-datum
  • X-factor
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-data range
  • X-tick lengths
  • X-tick style
  • X-zones
  • X-grid threshold
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick style
  • Y-var
  • Y-zones
  • Zone attribs


Rain graphics: Property List

Property List

Note

  • Background
  • Note font
  • Note nudge
  • Note style
  • Note linespacing
  • Soft hyphen


Rain graphics: Property List

Property List

Range Axes

  • Axes
  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Data style
  • Axes style
  • I-data range
  • Label font
  • Label mask
  • Label style
  • Label linespacing
  • Marker scales
  • Missing value
  • Versus
  • Where
  • X-caption
  • X-caption font
  • X-datum
  • X-grid
  • X-format
  • X-intercept
  • X-labels
  • X-label nudge
  • X-label font
  • X-range
  • X-style
  • X-tickmarks
  • X-data range
  • X-tick style
  • Y-caption font
  • Y-datum
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-data range
  • Y-tick style
  • Y-var
  • Z-data range


Rain graphics: Property List

Property List

Y-Sec

  • Caption font
  • Caption format
  • Caption style
  • Caption linespacing
  • Key
  • Key attribs
  • Key frame
  • Key font
  • Key indices
  • Key nudge
  • Key format
  • Key style
  • Key linespacing
  • Key gap
  • Label font
  • Label style
  • Label linespacing
  • Marker scales
  • X-intercept
  • Y-caption
  • Y-caption font
  • Y-datum
  • Y-factor
  • Y-grid
  • Y-format
  • Y-intercept
  • Y-labels
  • Y-label nudge
  • Y-label font
  • Y-range
  • Y-style
  • Y-tickmarks
  • Y-tick style


Rain graphics: Style Options

Style Options

Barchart

Summary of styles

  • ForceZero
  • Indexed
  • Horizontal
  • StackedBars
  • FloatingBars
  • NoAxes
  • ExplodeAxes
  • FrameAxes
  • CroppedAxes
  • TicksBetween
  • GridLines
  • OverlayGrid
  • ValueTags


Rain graphics: Style Options

Style Options

BoxWhisker

Summary of styles

  • ForceZero
  • NoAxes
  • ExplodeAxes
  • FrameAxes
  • CroppedAxes
  • TicksBetween
  • TabularData
  • Horizontal
  • GridLines
  • OverlayGrid
  • DecileWhiskers
  • ErrorBars


Rain graphics: Style Options

Style Options

Bubble

Summary of styles

  • ForceZero
  • GridLines
  • OverlayGrid
  • Clipped
  • Markers
  • HaloMarkers
  • ValueTags
  • AltitudeShading
  • RadialScaling
  • ScaleBar
  • Lines
  • Curves
  • ModelFit
  • AnnotateModel
  • Spanned
  • OnTopModel
  • NoAxes
  • ExplodeAxes
  • FrameAxes
  • CroppedAxes


Rain graphics: Style Options

Style Options

Cloud

Summary of styles

  • XYPlot
  • Indexed
  • WallShading
  • GridLines
  • Curves
  • NoMarkers
  • HaloMarkers
  • Lines
  • Risers
  • SurfaceShading
  • TrendSurface
  • ModelFit
  • Contours
  • ProjectContours
  • TiledSurface
  • AltitudeShading
  • Fine
  • ScaleBar
  • NoAxes
  • FlatText


Rain graphics: Style Options

Style Options

Contour

Summary of styles

  • ForceZero
  • GridLines
  • OverlayGrid
  • Clipped
  • NoTags
  • Markers
  • HaloMarkers
  • ValueTags
  • Lines
  • Curves
  • AltitudeShading
  • Coarse
  • Fine
  • ScaleBar
  • NoAxes
  • ExplodeAxes
  • FrameAxes
  • CroppedAxes


Rain graphics: Style Options

Style Options

Dial

Summary of styles

  • WedgeZones
  • Anticlockwise
  • ArrowLines


Rain graphics: Style Options

Style Options

Gantt

Summary of styles

  • GridLines
  • OverlayGrid
  • ValueTags
  • NoAxes
  • ExplodeAxes
  • FrameAxes
  • CroppedAxes


Rain graphics: Style Options

Style Options

Histogram

Summary of styles

  • GridLines
  • OverlayGrid
  • SurfaceShading
  • Risers
  • ValueTags
  • NormalCurve
  • FrameAxes
  • CroppedAxes
  • ExplodeAxes


Rain graphics: Style Options

Style Options

Pie

Summary of styles

  • ValueTags
  • Plain
  • FarthestFirst
  • RoseDiagram


Rain graphics: Style Options

Style Options

Linegraph

Summary of styles

  • XYPlot
  • Indexed
  • GridLines
  • OverlayGrid
  • Clipped
  • SkipRuns
  • SkipRepeats
  • TrendLine
  • ModelFit
  • GrowthCurve
  • AnnotateModel
  • OnTopModel
  • NoLines
  • Curves
  • Markers
  • Risers
  • SurfaceShading
  • Filled
  • SegmentLines
  • CellsCreated
  • HaloMarkers
  • CrispEdges
  • NoAxes
  • FrameAxes
  • CroppedAxes
  • ExplodeAxes
  • ValueTags
  • ArrowLines


Rain graphics: Style Options

Style Options

Polar

Summary of styles

  • XYPlot
  • Indexed
  • ClockFace
  • CompassPlot
  • SkipRuns
  • SkipRepeats
  • NoLines
  • Curves
  • Markers
  • Risers
  • SurfaceShading
  • NoAxes
  • GridLines
  • HollowCenter
  • OverlayGrid
  • ValueTags
  • HaloMarkers
  • ArrowLines
  • OriginMarker


Rain graphics: Style Options

Style Options

Response

Summary of styles

  • WallShading
  • GridLines
  • ForceZero
  • NoLines
  • Curves
  • Markers
  • Risers
  • Contours
  • TiledSurface
  • AltitudeShading
  • Fine
  • ScaleBar
  • NoAxes
  • FlatText
  • HaloMarkers


Rain graphics: Style Options

Style Options

Scatter

Summary of styles

  • ForceZero
  • LogAxes
  • GridLines
  • OverlayGrid
  • Clipped
  • TrendLine
  • ModelFit
  • GrowthCurve
  • AnnotateModel
  • OnTopModel
  • Parity
  • NoMarkers
  • Lines
  • Risers
  • ArrowLines
  • Contours
  • Curves
  • CellsCreated
  • HaloMarkers
  • NoAxes
  • ExplodeAxes
  • FrameAxes
  • CroppedAxes
  • ValueTags


Rain graphics: Style Options

Style Options

Step

Summary of styles

  • Horizontal
  • Indexed
  • ValueTags
  • SurfaceShading
  • Risers
  • SegmentLines
  • NoAxes
  • ExplodeAxes
  • FrameAxes
  • CroppedAxes
  • GridLines
  • OverlayGrid


Rain graphics: Style Options

Style Options

Table

Summary of styles

  • Spanned
  • Merged
  • FitWidth
  • Opaque
  • GridLines
  • UseHeaders
  • Boxed
  • Rounded
  • Shadowed
  • Absolute
  • Columns
  • Center
  • Right


Rain graphics: Style Options

Style Options

Tower

Summary of styles

  • WallShading
  • GridLines
  • ForceZero
  • Indexed
  • NoAxes
  • FlatText
  • Plain


Rain graphics: Style Options

Style Options

Triangle

Summary of styles

  • Markers
  • HaloMarkers
  • Lines
  • Curves
  • Filled
  • Labelled
  • ValueTags
  • SideCaptions
  • GridLines
  • RedrawOutline
  • Percentage


Rain graphics: Style Options

Style Options

VennDiagram

Summary of styles

  • ValueTags
  • Filled
  • RedrawOutline


Rain graphics: Style Options

Style Options

Vector

Summary of styles

  • ForceZero
  • GridLines
  • OverlayGrid
  • FrameAxes
  • CroppedAxes
  • ExplodeAxes
  • ValueTags
  • ArrowLines
  • Middle
  • Rooted
  • Terminated
  • Dissected
  • Columns
  • NoAxes


Rain graphics: Style Options

Style Options

Min-Max

Summary of styles

  • XYPlot
  • Indexed
  • NoLines
  • Envelope
  • Curves
  • ValueTags
  • DriftMarkers
  • Plain
  • Terminated
  • ErrorBars
  • ArrowLines
  • NoAxes
  • ExplodeAxes
  • FrameAxes
  • CroppedAxes
  • GridLines
  • OverlayGrid
  • Horizontal


Rain graphics: Style Options

Style Options

X-Bar

Summary of styles

  • ForceZero
  • Indexed
  • Horizontal
  • StackedBars
  • FloatingBars
  • NoAxes
  • ExplodeAxes
  • FrameAxes
  • CroppedAxes
  • TicksBetween
  • GridLines
  • OverlayGrid
  • ValueTags


Rain graphics: Note styles

Note styles

  • Boxed
  • Shadowed
  • Rounded


Rain graphics: Viewer Functions

Viewer Functions

VFStd | Basic Viewer Functions
VFTran | Loading Translated Phrasebooks
VFIntro | Introducing ‘Active Rain’
VFEnum | PostScrp.EnumerateCharts – list all charts
VFInfo | PostScrp.FindInfo – bounding box of region
VFGuiId | PostScrp.GuiId – internal name of a series
VFD2L | PostScrp.D2L – device to logical co-ordinates
VFL2D | PostScrp.L2D – logical to device co-ordinates
VFHotspot | PostScrp.FindHotspot – chart headings etc.
VFSeries | PostScrp.FindSeries – detect data series
VFPoints | PostScrp.FindPoints – multiple data points
VFFindHint | PostScrp.FindHint – return data hints
VFSetObject | PostScrp.SetObject – redraw chart object
VFGetPage | PostScrp.GetPage – recover updated PostScript
VFReadHeader | PostScrp.ReadHeader – read header comments
VFWipe | PostScrp.Wipe – remove all graphics from Gui object