idlastro / Math and Statistics: MULTIPLOT

[Source code]

Name
MULTIPLOT
Purpose
Create multiple plots with simple control over the gaps between plots.
fault, the gap is zero but this can be set with the
keyword, or xgap=, ygap= for individual control over different axes.
an also place a single title along the x, y and top axes of the
x of plots using the mtitle, mxtitle and mytitle keywords.
It is good for data with one or two shared axes and retains all the
versatility of the plot commands (e.g. all keywords and log scaling).
The plots are connected with the shared axes, which saves space by
omitting redundant ticklabels and titles.  Multiplot does this by
setting !p.position, !x.tickname and !y.tickname automatically.
A call (multiplot,/reset) restores original values.
e graphics users might want to look at CGLAYOUT
http://www.idlcoyote.com/idldoc/cg/cglayout.html
 has similar functionality. 
CALLING SEQUENCE
multiplot, pmulti, 
ap=, xgap=, ygap=, 
square, 
doxaxis, /doyaxis, 
Title=, mTitSize=, mTitOffset=, 
xTitle=, mxTitSize=, mxTitOffset=, 
yTitle=, myTitSize=, myTitOffset=, 
tickformat=, ytickformat=
default, /reset, /rowmajor, /initialize
INPUTS
pmulti: Optional input. [Nx,Ny] array describing the shape of the
    matrix of plots.  This is equivalent to the 2nd and 3rd elements
    of !p.multi.  Or you can send all 5 elements of the !p.multi.
KEYWORD INPUTS
gap=: Set the gap between plots in normalized units.  Default is 0.
    This input overrides the xgap and ygap inputs.
xgap=: Gap between plots in the x direction. Default 0. To set both
    x and y gap to the same value just use the gap keyword.
ygap=: Gap between plots in the y direction. Default 0. To set both
    x and y gap to the same value just use the gap keyword.
mTitle: A single title to go across the top of the matrix of plots,
    as opposed to the plot over single plots you generate with the
    plot command for example. 
mTitSize: The font size of the top title. Default is 1.25*!p.charsize
mTitOffset: Offset of the title in the y-direction.
mxTitle, mxTitSize, mxTitOffset: same as above but for the x-axis title
myTitle, myTitSize, myTitOffset: same as above but for the y-axis title
xtickformat, ytickformat: Set the default tick formats when the ticks
    are plotted. This allows the user to avoid sending this to each
    plotting command which can have unexpected results if that axis
    was not to get tick labels in a given point in the matrix.
KEYWORDS SWITCHES
/square: Force the axis ratio of each plot to be square. Note if
    xgap and ygap are set to different values, this axis ratio will
    not be preserved.  It will be preserved if gap= is used.
/doxaxis: Put axis labels, etc on the axis. Default is to place labels
    only on the left side and bottom sides of the plot matrix, but may
    be useful when some cells are empty; for example the x-axis of
    a 2x2 grid when only 3 total plots will be created.
/doyaxis: Put axis labels, etc on the yxis.  Default is to place labels
    only on the left side and bottom sides of the plot matrix, but may
    be useful when some cells are empty; for example the x-axis of
    a 2x2 grid when only 3 total plots will be created.
/rowmajor: Like setting 5th element of !p.multi to 1. 
/reset: Set plotting parameters to their saved values from before
    multiplot was initially called.
/default: Set plotting parameters to IDL defaults.  This is useful
    when the saved parameters get in a whacky state.
/initialize: Just do the initialization. This is what happends when
    you first call multiplot anyway.
EXAMPLES
; Make an array of plots [4,3] with a gap of 0.1 (in norm. coords.)
; and overall titles along the x and y axes as given.  Force the
; plots to be square.
    cgerase & multiplot, [4,3], /square, gap=0.1, mXtitle='R', mYtitle='F(R)'
    for i=0,4*3-1 do begin
        cgplot, struct[i].x, struct[i].y, psym=4
        multiplot
    endfor
    multiplot,/reset
Side Effects
Multiplot sets a number of system variables: !p.position, !p.multi,
     !x.tickname, !y.tickname, !P.noerase---but all can be reset with
     the call: multiplot,/reset  
Things can get out of wack if your program crashes in the middle of 
making a matrix of plots, and often /reset will not fix it.  In those 
cases, calling multiplot,/default will often fix the problem.
Restrictions
1. If you use !p.multi as the method of telling how many plots
are present, you have to set !p.multi at the beginning each time you
use multiplot or call multiplot with the /reset keyword.
2. There is no way to make plots of different sizes; each plot
covers the same area on the screen or paper.
Modification history
write, 21-23 Mar 94, Fred Knight (knight@ll.mit.edu)
alter plot command that sets !x.window, etc. per suggestion of
  Mark Hadfield (hadfield@storm.greta.cri.nz), 7 Apr 94, FKK
add a /default keyword restore IDL's default values of system vars,
  7 Apr 94, FKK
modify two more sys vars !x(y).tickformat to suppress user-formatted
  ticknames, per suggestion of Mark Hadfield (qv), 8 Apr 94, FKK
03-20    Added /square keyword
ork in device coordinates so we can force aspect ratio to be square 
f requested. Erin Scott Sheldon UMichigan
06-18
an now place titles on the overall x and y axes, as well as a 
op title using these new keywords. 
   mTitle=, mTitSize=, mTitOffset=, 
   mxTitle=, mxTitSize=, mxTitOffset=, 
   myTitle=, myTitSize=, myTitOffset=, 
an also control overall tick formats. Useful because can just call
ultiplot initially and set this, while calling on each call to
he plotting program will have unexpected results if the ticks
re not to be labelled for that place in the matrix.
   xtickformat, ytickformat
rin Sheldon, NYU
08-28:
an now add gaps between the plots with these keywords:
   gap=, xgap=, ygap=
here the values are in normalized coordinates. Erin Sheldon, NYU
11-23
nitialize common block if M[X/Y]TITLE set W. Landsman 
02-07
Use Coyote Graphics  W. Landsman    
03-21
Use cgplot on initial call to get right background  W.L.
02-04
Handle  [X/Y].OMargin   A. Negri, Bologna