;+
; NAME:
;   SUBCELLARRAY
;
; AUTHOR:
;   Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
;   craigm@lheamail.gsfc.nasa.gov
;
; PURPOSE:
;   Returns a set of subcells, suitable for creating a matrix of plots.
;
; CALLING SEQUENCE:
;   subcellarray, xdivs, ydivs, newpanels, newsubpanels
;
; DESCRIPTION: 
;
;   SUBCELLARRAY generates a group of subcells.  The subcells are
;   useful for plotting a matrix of windows.
;
;   This procedure takes a list of subdivisions in X and Y,
;   designating the subdivision of the plot into num(X) X panels and
;   num(Y) Y panels, and creates a new batch of panels and subpanels,
;   which can be used in the individual plot commands of the array.
;
; INPUTS:
;
;   XDIVS - list of subdivisions in the X-direction.  Example: [1,1,2]
;           will create three panels in the X-direction such that
;           their sizes are in the ratio of 1:1:2 (1 being on the
;           left, 2 being on the right).  These are the subdivisions
;           of the SUBPANEL, the inner plot box boundary, not
;           divisions of the PANEL, which is the boundary that
;           includes axis labels.
;
;   YDIVS - same, for Y direction
;
; OPTIONAL INPUTS:
;   NONE
;
; INPUT KEYWORD PARAMETERS:
;
;   PANEL - Original panel (outer margin) of plot. Default is to fill
;           screen.
;
;   SUBPANEL - Original subpanel (inner margin) of plot.  Default is
;              to use defsubcell().
;
; OUTPUTS:
;
;   NEWPANELS - output array of panels.  The output is 4 x M x N where
;               M is the number of X divisions and N is the number of
;               Y divisions.
;
;   NEWSUBPANELS - output array of subpanels, with correct adjustment
;                  for margins, same format as NEWPANELS.
;
; PROCEDURE:
;
; EXAMPLE:
;
;   See PLOTCUBE for an example usage.
;
; SEE ALSO:
;
;   DEFSUBCELL, SUBCELLARRAY, PLOTCUBE
;
; EXTERNAL SUBROUTINES:
;
;   DEFSUBCELL, SUBCELL
;
; MODIFICATION HISTORY:
;   Written, CM, 1997
;   Added copyright notice, 25 Mar 2001, CM
;   Add usage message, 19 May 2009, CM
;
;  $Id: subcellarray.pro,v 1.4 2009/07/01 15:58:41 craigm Exp $
;
;-
; Copyright (C) 1997,2001,2009, Craig Markwardt
; This software is provided as is without any warranty whatsoever.
; Permission to use, copy, modify, and distribute modified or
; unmodified copies is granted, provided this copyright and disclaimer
; are included unchanged.
;-