HELP SHOWDISPLAY                       Chris Thornton, September 1988
                                       updated Dec 16  1994

   showdisplay(instructions);
   showdisplay(instructions, output_type);

SHOWDISPLAY generates graphical displays in various formats. It takes a
list of drawing instructions such as

   [  {line 2 3 4 5}
      {string 4 5 'foo'}
      {circle 8 7 13 14} ]

and turns them into a graphical display. It can also be provided with an
`output_type' argument. Possible values for this include "X", "ved",
"fig", "latex", "troff" and "screen". If the output_type is "X" then the
display will be shown in an X window. If the output_type is "ved" then a
ved buffer called ~/temp.out will be constructed containing the display
(compare LIB SHOWTREE). Otherwise the display will be written in the
given format into ~/temp.out. If the output_type is not specified it
defaults to the value of "sd_default_output_type". Setting
"sd_output_type" to "screen" will ensure that the display is drawn on
screen using an X window if possible and a ved buffer otherwise.

Try the following.

   showdisplay([{line 2 2 10 10} {string 4 3 'hello'}{box 4 4 6 6}]);

(Note that it is easy to get postscript output from fig output using
f2ps).

-- Drawing instructions -------------------------

The following instructions are currently implemented.

   {string  x1 y1 sssss}
   {line    x1 y1 x2 y2}
   {box     x1 y1 x2 y2}
   {circle  x1 y1 x2 y2}
   {arc     x1 y1 x2 y2 start inc}
   {space   x1 y1 x2 y2}

x1, y1 are always relevant starting/top-left coordinates and x2, y2 (if
needed) are ending/bottom-right coordinates. sssss is an arbitrary
POP-11 string. The arc instruction is currently only implemented for "X"
and "fig" output. `start' is the starting angle of the arc (measured in
degrees) and `inc' is the amount the angle is incremented in the arc.

Instructions can include extra values which specify things like colour
(yellow, red etc.), shade, font/line-size and rotation. For example, in

   showdisplay([{box 1 1 2 2 blue -0.2 45.0 [] '-' 4}]);

we have six extra arguments. The word "blue" ensures that the box is
shown in blue. The -0.2 ensures that the blue is of a light shade. (The
shade value can be any number between 0 (for pure white) and -1 (for
pure black) but it will only work with primary colours such as red,
green, blue, yellow etc.) The 45.0 ensures that the box is rotated
anti-clockwise 45 degrees. (The  rotation value MUST be a decimal
number.) The empty list ensures that the box is not filled in. The '-'
ensures that the border of the box is shown in a dashed line style and
the 4 ensures that the width of the lines is 4. (The line size value
MUST be an integer.) Compare

   showdisplay([{line 0 0 3 3}
      {string 1 1 'A silly string' red 0.3 18}]);

   showdisplay([
      {line 2 28 20 28}
      {line 2 29 20 29}
      {line 2 30 20 30}
      {line 2 31 20 31}
      {circle 3 3 7 7}
      {circle 20 6 24 10}
      {box 5 5 25 25 []}
      {box 20 20 22 22 []}
      {string 29 4 'this is a box'}
      {line 8 6  20 15}
      {arrow 36 5 30 15}
      {string 10 19 'there'}
      {string 10 16 'hello'}
      {box 0 0 45 45 []}
      ]);

   showdisplay([
      {line 2 28 20 28 red}
      {line 2 29 20 29 green}
      {line 2 30 20 30 blue}
      {line 2 31 20 31 yellow}
      {circle 3 3 7 7 cyan 0.2}
      {circle 20 6 24 10 yellow -0.4}
      {box 5 5 25 25 magenta []}
      {box 20 20 22 22 orange}
      {string 29 4 'this is a box' 8 brown}
      {line 8 6 20 15 24 LimeGreen}
      {arrow 36 5 24 15}
      {string 10 19 'there' red 24}
      {string 10 16 'hello' blue 12}
      {box 0 0 45 45 [] white}
      ]);

Note that optional arguments do not have to go in any particular order.

-- Optional arguments ---------------------------

Showdisplay can be called with optional arguments, e.g.,

   showdisplay(commands, name, type, file, incremental);

Here `commands' is the compulsory list of drawing commands. `name' is a
word giving the name of the display. (Naming displays is essential if
you want to work with several screen displays at once.) `type' is an
output type label such as "X" or "fig". `file' is a string giving the
filename to be used when writing a display to a file and `incremental'
is a boolean flag which specifies whether the display is to be updated
incrementally or not.

-- Display sizes and drawing areas --------------

The absolute sizes for the displays are stored in a property table
called sd_display_size. It is possible to make the program use a
particular drawing area by specifying marginal offsets via the property
table sd_drawing_area. For example, if you want an X display which
measures 350 by 350 with a drawing area that leaves a margin of 20
pixels on all sides you would do

   [0 0 350 350] -> sd_display_size("X");
   [20 20 -20 -20] -> sd_drawing_area("X");


-- Variables ----------------------------------------------------------

   sd_output_file - string specifying output file
   sd_incremental - boolean: set true to incrementally update display
   sd_hard_frame - boolean: stops dimensions scaling independently
   sd_background - colour of display background (assignable)
   sd_allow_colour - boolean: set false to get monochrome
   sd_default_font_size - integer: self-explanatory

-- Special displays -----------------------------

There are serveral libraries that use showdisplay. These all provide a
single procedure which takes a data structure and constructs a
particular type of display. Each procedure can take the same optional
extra argument as showdisplay. Most have configuration variables and
these appear at the top of the relevant source file.

Examples:

Graphs...

   showgraph([[[2 3][3.5 5][3.5 5 'label'][4 3][5 7][5 8 ^false]]]);

   showgraph([[[2 3][3.5 5][3.5 5 'label'][4 3][5 7]]
      [[2 5][4 6][5 3]]
      [[2 1][3 7][3.5 2][4 2.5][5 5]]
      [[2 1][3 2][3.5 2.7][4 2.9][5 2.5]]],
      ['x axis' 'y axis']);

Histograms...

   showhistogram([[[1 4][2 3][3 5][4 3] [5 7][6 2]
      [0 0 ^false][7 7 ^false] ]]);

Dendrograms

   showdendro([0.85 [0.7 [0.65 ding [one hello]]
      [0.6 bang] [0.8 zonk zank] [0.82 tink]]]);

3d surfaces

   showsurface(newanyarray([1 12 1 12], {0.487336 0.467523 0.438052
             0.458673 0.483175 0.497975 0.484976
             0.467325 0.469933 0.448748 0.461089 0.51624 0.428925
             0.391302 0.413076 0.431703 0.46686 0.490313 0.484111
             0.495754 0.481258 0.459152 0.476999 0.496957 0.425835
             0.401539 0.414037 0.466274 0.504831 0.480004 0.489406
             0.515275 0.537309 0.54458 0.499069 0.478901 0.498075
             0.473247 0.497281 0.556284 0.522141 0.473935 0.473917
             0.516433 0.571149 0.574787 0.527286 0.48531 0.531115
             0.538776 0.578098 0.587934 0.532881 0.456766 0.445357
             0.476235 0.506482 0.537838 0.519813 0.474236 0.493953
             0.524041 0.563292 0.5506 0.505744 0.458001 0.413974
             0.386995 0.405241 0.452199 0.466368 0.455166 0.455664
             0.459979 0.492698 0.506168 0.454122 0.44201 0.406688
             0.362849 0.352875 0.391919 0.428211 0.457643 0.453048
             0.406947 0.437812 0.457802 0.475532 0.449925 0.462307
             0.409683 0.363071 0.365345 0.427979 0.491559 0.409758
             0.40516 0.440088 0.518796 0.529587 0.525195 0.527755
             0.504456 0.416527 0.369878 0.3996 0.466675 0.416882
             0.413948 0.522577 0.58898 0.613689 0.60488 0.579094
             0.55799 0.509249 0.406335 0.368328 0.41389 0.44857
             0.491967 0.54817 0.615134 0.624002 0.592702 0.574334
             0.566084 0.52891 0.464781 0.396902 0.403804 0.494129
             0.515417 0.543952 0.55694 0.562334 0.540569 0.529303
             0.520592 0.500117 0.48473 0.466149 0.440356}));

Activation sequences...

   showactivations({{0.1 0.2 0.3 0.4 0.4 foo}
      {0.5 0.3 0.1 0.2 0.25 bang}{0.8 0.9 1 0.9 1 ding}});

Hinton diagrams...

   showfields(newarray([1 9 1 10],
      procedure(i,j); 1 - random(2.0) endprocedure));

Here, the final element of each array row is taken to be the name of the
corresponding unit. It is also possible to pass a file name to
showfields, provided that the file contains a weight matrix with one
weight vector per line with the unit's name at the end.

Neural-net displays of various sorts... (only accessible after
compilation of `shownet').

   shownet(
      newarray([1 5 1 5],
         procedure(i,j); oneof([0 0.75]) endprocedure),
      [  [[ _  5  _ ]]
         [[ 3  _  4 ]]
         [[ 1  _  2 ]]]);

   showstruc(newanyarray([1 3 1 3], {0 0 0 0 0 0 1 1 0 0}),
      [[[_ 3 _]][[1 _ 2]]], {0.2 0.3 -0.9});

   showweights(newarray([1 5 1 5], procedure(i,j); random(1.0)
      endprocedure));


   showgrid(newanyarray([1 3 1 3], {0 0 0 0 0 0 1 1 0 0}),
      [[[_ 3 _]][[1 _ 2]]], {0.2 0.3 -0.9});

   showlinks(newanyarray([1 3 1 3], {0 0 0 0 0 0 1 1 0 0}),
      [[[3 _ _]][[1 _ 2]]], {0.2 0.3 -0.9});


-- Reading in weight-files created by `pdp' package

The Rumelhart and McClelland `pdp' package dumps weights in files with a
special format. You can use the showdisplay programs to display these by
using LIB PBP_BACKPROP. First do

   lib learners;
   lib pdp_backprop;

Then set up the network structure by defining a procedure that assigns a
vector to `l_network_description' and executing the `setproblem -'
command. For example, to set up a strictly-layered network with 14 input
units, two layers of ten hidden units and three output units you would
do

   define learner_problem;
      {14 10 10 3} -> l_network_description;
   enddefine;

Then give the command `l setproblem -'.

Finally do

   loadpdpweights <filename>

where <filename> is the name of the relevant weights file.

Following this, you can show Hinton diagrams by giving the command
`showfields' (or `showtop' if you just want to see the non-input units).
You can also display the structure of the network with `showstruc' or
`shownet'. You can also do `showtop -' to browse through the fields
one by one.


--- ________________$poplocal/local/learners/help////////___________showdisplay
--- _________Copyright __________University __of ______Sussex _____1997. ___All ______rights _________reserved.