MULTIPLOT
Name
MULTIPLOT
Purpose
Create multiple plots with simple control over the gaps between plots.
By default, the gap is zero but this can be set with the
gap= keyword, or xgap=, ygap= for individual control over different axes.
You can also place a single title along the x, y and top axes of the
matrix 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.
Calling Sequence
multiplot, pmulti,
gap=, xgap=, ygap=,
/square,
/doxaxis, /doyaxis,
mTitle=, mTitSize=, mTitOffset=,
mxTitle=, mxTitSize=, mxTitOffset=,
myTitle=, myTitSize=, myTitOffset=,
xtickformat=, 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
2001-03-20 Added /square keyword
Work in device coordinates so we can force aspect ratio to be square
if requested. Erin Scott Sheldon UMichigan
2007-06-18
Can now place titles on the overall x and y axes, as well as a
top title using these new keywords.
mTitle=, mTitSize=, mTitOffset=,
mxTitle=, mxTitSize=, mxTitOffset=,
myTitle=, myTitSize=, myTitOffset=,
Can also control overall tick formats. Useful because can just call
multiplot initially and set this, while calling on each call to
the plotting program will have unexpected results if the ticks
are not to be labelled for that place in the matrix.
xtickformat, ytickformat
Erin Sheldon, NYU
2007-08-28:
Can now add gaps between the plots with these keywords:
gap=, xgap=, ygap=
where the values are in normalized coordinates. Erin Sheldon, NYU
2009-11-23
Initialize common block if M[X/Y]TITLE set W. Landsman
2011-02-07
Use Coyote Graphics W. Landsman
2012-03-21
Use cgplot on initial call to get right background W.L.