## Institut für Astronomie und Astrophysik

### Abteilung Astronomie

Sand 1, D-72076 Tübingen, Germany

plot Source code in cafe_plot.pro

### plot

Name
           plot

Purpose
           plots data/model of fit

Category
           cafe

SYNTAX:
           plot [,top][,bottom|panelnum][,/quiet][,/noerase]

Input Parameters
           top      - (optional) Defines the plot type to draw in the upper
part of the plot window.
bottom   - (optional) Defines the plot type to draw in the lower
part of the plot window.
panelnum - If instead of bottom a integer number is given
the panel with this number is set (starting
from 0).

PLOT TYPES:
           The plots to be inserted in the top/bottom
panels are defined with plot types defining
what to plot. There are some plot types
available (and could be extended just as in
case of fit models).
Syntax:
> [+|-]<plot type>["[parameter]"][:group]...
> ...[+<plot type>["[parameter]"][:group]]
With:
- add/remove:If the plot type is prepended
with "+" the new plot types
ones.
If the plot type is prepended
with "-" this plot type is
removed. For this case
wildcards are allowed to
remove more than one plot
type.

Example
                                        > plot,data+model
> plot,-mod*
-> remove the model plot type.
- plot type: defining what to plot (refer below)
- parameter: defining special options to
be passed to the plot type
driver. These are usually
those accepted by the IDL
oplot command, e.g. linestyle.
The format is:
keyword=value. It is possible
to define several such
parameters which must be
separated by ";".
If the assignment "=value" is
not given the value =1 will
be used (setting flags).

Example
                                          plot, data[linestyle=3;psym=-4;noerror]
Remark: Options set with
setplot override these parameters.
- group:    Defines for the plot type
which data group to use. This
allows to plot several groups
in a single plot window.

Example
                               > plot, data+model...
-> Draw data and model in the same
panel.
> plot, data:2+data:3
-> Draw data from group 2,3 to panel.
> plot, data[linestyle=3;psym=-3]+model
-> Draw data plus underlying model,
which is formated with different symbol/linestyle.

Description
                      The "+" adds several plot types in the same
panel. In this case each will be drawn in a
different color (refer also to the plot types
itself).
The optional ":<group>" defines the group for
the specific plot type to look data/model for.
Common plot types are
"data" - draw the data as is
"model"- draw the computed model with
current parameters
"res" - Residuum between data/model
"delchi" - Same but in units of 1 sigma
Available plot types can be listed with the
command
help,plot,all
while a specific plot type can be shown with
the command
help,plot,<plot type>.

OPTIONS:
           /quiet    - Do not print plot informations.
/noeraase - Do not delete window (useful for plotting as
a client procedure)

SETUP:
           All options may be set with the "set" command. The
command prefix is "plot".

SETPLOT KEYWORDS:
                      Plotting may be influenced by some general plot
parameters set with the setplot command. For all
plot styles following setplot identifier will be
applicable (and must be defined for plot panel 0):
weight  - A integer number which defines how  the
height should be distributed among different
panels. For this all weights are summed up;
and each panel gets a share according its
weight from the total sum. For example with
top panel of weight 2 and bottom panel of
weight 1 will set 2/3 of the available height
at top panel and 1/3 at bottom panel (this is
the default).
topsep  - Floating number between 0..1 defining margin
of plot to top (either frame or plot above).
This must include sufficient place for
title/subtitle text.
Default is 0.05.
bottomsep  - Floating number between 0..1 defining margin
of plot to bottom (either frame or plot below).
This must include sufficient space for x-axis
text/sub-text.
Default is 0.1.
rmargin  - Floating number between 0..1 defining margin
of plot to right side.
This must include sufficient space for right y-axis
text (if any).
Default is 0.05.
lmargin  - Floating number between 0..1 defining margin
of plot to left side.
This must include sufficient space for left y-axis
text/tick labels.
Default is 0.1.
xfree    - Flag (0/1). If set the x-range is computed
independent for each panel (not recommended for
interactive plot tools, e.g. iplot/wplot).
Default is off (0).
position - 4-vector containing edge coordinates
of panel to plot. Coordinates are values
between 0..1.
Setting this option overrides the default
algorith using the top/bottomsep/r/lmargin and
weigth keywords described above.
background - The background color for all plots. This is
common for all panels and can not be set
separately :-<
startcolor - First color number used to plot
frame/data. Must be adapted to currently used
color table. Default: 255.
deltacolor - Decrease of color to apply for distinct plot
types/data sets. Default: 23.
startlinestyle - First line style used to plot frame/data. Default: 0.
Must not exceed 5.
deltalinestyle - Increase of line styles for distinct plot
types/data sets. May be positive or negative
integer number. Default: 0 (no change).
startpsym - First point symbol used to plot frame/data. Default: -4.
Should not exceed -7..7. If psym is negative
lines are drawn, if positive, not (refer IDL
PLOT command).
Userdefined symbols (8) are not supported.
deltapsym - Increase of point symbols for distinct plot
types/data sets. May be positive or negative
integer number. Default: 0 (no change).
If psym exceeds -7..7 during plot different
plot types it will be set at 0 (no symbol). Therefore
plotting all data sets with lines it is
recomended to set deltapsym at a negative
value (to decrease and restart from 0).
zbuff      - Use the Z Buffer device for plot
production. The practical use is for 3-dim
plots. The Z Buffer device essentially is able
to check which object (even axis lines, text
or data) is behind another object and must not
be drawn. This is especially usefull when:
- Combining several shaded objects, possibly
with surface or contour.
- Generating high quality plot 3-dim plot
images.
The drawback is that the generated
(postscript) images are pixelated, i.e. the
quality depends on the resolution/image size.
Also fonts are not always drawn properly.
This means: If one prints zbuffer generated
plots into a file she has to look
- reasonable resolution (s.b.)
- A proper line thickness (setplot keywords
thick, xthick,ythick,zthick).
- A scaleable font. System fonts usually look
poor. It is recomended to use the setplot
keyword font=1.
maxres    - Using the Z Buffer device with this keyword defines
the maximal number of pixels in X
direction. Default are 5000. The pixel in Y
direction are set according the plot aspect
ratio.
tex       - Use TexToIDL to convert the parameter text
from TeX syntax into IDL strings. This allows
to access mathematical symbols like \chi=Chi,
\Delta,\pi etc.
It is recomended to use this parameter
instead of calling textoidl() manually. The
latter causes problems when printing into
postscript files because the IDL codes for
plot fonts (!p.font = -1) and hardware fonts
(!p.font = 0) are different.
enhanced  - Switch on enhanced plot facilities (see
ENHANCED PLOTTING).

ENHANCED PLOTTING:
           Enhanced plotting is intended for 2-D plotting only
images).
The plot may be a combination of different separate plot
images. This feature is enabled using the "enhanced"
keyword. After this some plot operators are available
which take each plot type as a separate unit which can be
combined to create complex images. In standard mode only
the "+" operator is available which simply overlays
several plot images. In enhanced mode following operators
are implemented:
+ - standard case: execute plot type on current plot
device. This is the only operator which acknowledges
the z buffer device.
^ - add two images in respect of their colors. May be used
to simulate transparency by adding image parts which
were hidden.
* - multiply colors of image. May be used to
enhance/diminish colors. It is possible to multiply an
image with a number to change the color space.
& - mask parts of image. This means that for a & b the
image b is shown where image b is not background
color, otherwise a is shown. Usefull to replace parts
of image with other parts.
There are some additional keyword parameters which can be
used to influence the plot result:
ctable  - Defines the color table to use. Therefore a plot
may consist of plot images created with
different color tables ;-)
background - Defines the background color for which the plot
is considered to be transparent. This is
important for the "&" - Operator to mask certain
parts of the image.

Example
           The enhanced mode may be used to circumvent problems
arising from Z Buffer use. A detailed tutorial is
described at: http://www.sljus.lu.se/stm/IDL/Surf_Tips/ by
Struan Gray.
Here some basic examples:
> setplot,enhanced
> setplot,zbuff
-> avoid submarining of surface lines in shade
plot. Actually the surface *replaces* the shade.
-> plot data sets of group 0 and 1 in a transparent manner
-> plot data set 0 in blue color and data set 1 in red
Remarks:
The enhanced mode has some drawbacks. One is that is
significant slower than the standard mode (because each
image must be read and processed separately).
The other problem arises from the fact that the image
always is pixellated; plotting out to a postscript device
results in the same problems as the use of the Z-Buffer
device (which should be used in enhanced mode anyway).

Side Effects
           Last plot ranges/plot type will be stored if no new is
given.

Example
           > plot, data,delchi
-> plot data and chi difference in different panels.

Revision History
           $Id: cafe_plot.pro,v 1.34 2004/07/30 15:52:36 goehler Exp$