multiplot.pro

basic median filter simulation

;+
; 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.
;
;       erase & multiplot, [4,3], /square, gap=0.1, mXtitle='R', mYtitle='F(R)'
;       for i=0,4*3-1 do begin
;           plot, 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 ([e-mail])
;	alter plot command that sets !x.window, etc. per suggestion of
;	  Mark Hadfield ([e-mail]), 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
;	Converted to IDL V5.0   W. Landsman   September 1997
;       
;   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
;      
;
;-

PRO multiplot, pmulti, help=help, $
        initialize=initialize, reset=reset, default=default, $
        rowmajor=rowmajor,verbose=verbose, square=square, $
        gap=gap_in, xgap=xgap_in, ygap=ygap_in, $
        doxaxis=doxaxis, doyaxis=doyaxis, $
        $
        xtickformat=xtickformat_in, ytickformat=ytickformat_in, $
        mtitle=mtitle, mTitSize=mTitSize, mTitOffset=mTitOffset, $
        mxTitle=mxTitle, mxTitSize=mxTitSize, mxTitOffset=mxTitOffset, $
        myTitle=myTitle, myTitSize=myTitSize, myTitOffset=myTitOffset




    common multiplot $
        ,nplots $                   ; [# of plots along x, # of plots along y]
        ,nleft $                    ; # of plots remaining---like the first element of !p.multi
        ,pdotmulti $                ; saved value of !p.multi
        ,margins $                  ; calculated margins based on !p.multi or pmulti
        ,pposition $                ; saved value of !p.position
        ,colmajor $                 ; flag for column major order
        ,noerase $                  ; saved value of !p.noerase
        ,sqplot $                   ; should be make it square?
        ,xtickname $                ; Original value
        ,ytickname $                ; Original value
        ,xtickformat_orig $         ; Original value
        ,ytickformat_orig $        
        ,xtickformat $              ; Value we will use
        ,ytickformat $
        ,gap  $
        ,xgap $
        ,ygap

    ; help message
    if keyword_set(help) then begin
        doc_library,'multiplot' 
        return 
    endif
   
    
    ; restore idl's default values (kill multiplot's influence)
    if keyword_set(default) then begin
        !p.position = 0
        !x.tickname = ''
        !y.tickname = ''
        !x.tickformat = ''
        !y.tickformat = ''
        !p.multi = 0
        !p.noerase = 0
        nleft = 0
        nplots = [1,1]
        pdotmulti = !p.multi
        margins = 0
        sqplot=0
        pposition = !p.position
        noerase = !p.noerase
        xtickname = !x.tickname
        ytickname = !y.tickname
        xtickformat = !x.tickformat
        ytickformat = !y.tickformat

        gap=0.0
        xgap=0.0
        ygap=0.0
        if keyword_set(verbose) then begin
            message,/inform,$
                'Restore IDL''s defaults for affected system variables.'
            message,/inform,$
                'Reset multiplot''s common to IDL''s defaults.'
        endif
        return
    endif

    ; restore saved system variables
    if keyword_set(reset) then begin
         if n_elements(pposition) gt 0 then begin
             !p.position = pposition
             !x.tickname = xtickname
             !y.tickname = ytickname
             !x.tickformat = xtickformat_orig
             !y.tickformat = ytickformat_orig
             !p.multi = pdotmulti
             !p.noerase = noerase
             sqplot=0
        endif
        nleft = 0
        if keyword_set(verbose) then begin
            coords = '['+string(!p.position,form='(3(f4.2,","),f4.2)')+']'
            multi = '['+string(!p.multi,form='(4(i2,","),i2)')+']'
            message,/inform,'Reset.  !p.position='+coords+', !p.multi='+multi
        endif
        gap=0.0
        xgap=0.0
        ygap=0.0
        return
    endif

    ;
    ;  Now the user inputs
    ;

    ; How big are the gaps between the plots?
    if n_elements(gap) eq 0 then begin
        ; initial set up of common block values
        xgap=0.0
        ygap=0.0
        gap=0.0
    endif

    if n_elements(xgap_in) ne 0 then xgap=xgap_in
    if n_elements(ygap_in) ne 0 then ygap=ygap_in

    ; gap will override any previously set values
    if n_elements(gap_in) ne 0 then begin
        gap=gap_in
        xgap=gap
        ygap=gap
    endif


    ;
    ; Set up the plot layout
    ;

    ; Shall we force the individual plots to be square?
    if keyword_set(square) then sqplot=1 else begin
        if n_elements(sqplot) eq 0 then sqplot=0
    endelse