This page was created by the IDL library routine `mk_html_help2`.

Last modified: Thu Feb 18 01:15:16 2010.

# Directory Listing of Routines

# ssl_general/tplot

- _GET_EXAMPLE_DAT
  A procedure that generates sample data for "TPLOT".
- _TPLOT_DEMO
  A sample crib sheet that explains how to use the "TPLOT" procedure.
- _TPLOT_EXAMPLE
  A sample crib sheet that explains how to use the "TPLOT" procedure.
- BITPLOT
  Plots 'ON' bits for housekeeping type data.
- CLEAN_SPIKES
- COPY_DATA
- CROSSHAIRS
  Display crosshairs on the plot window, display the data coordinates of the
- CTIME
  Interactively uses the cursor to select a time (or times)
- CUTS
- DATA_CUT
- DATA_TO_NORMAL
- DEL_DATA
  obsolete procedure! use "STORE_DATA" instead
- DRAW_COLOR_SCALE
  Procedure to draw a color scale.
- FIND_HANDLE
  Returns the index associated with a string name.
- GET_DATA
  Retrieves the data and or limit structure associated with a name handle.
- GET_TIMESPAN
- GET_YLIMITS
  Calculates appropriate ylimits for a string array of "TPLOT" variables
- GETTIME
- ITON
  Convert an index or array of indicies to data names.
- MAKEGAP
  Creates data gaps (by inserting NaN) when the time between data points is
- MPLOT
  General purpose procedure used to make multi-line plots.
- NORMAL_TO_DATA
- OPTIONS
  Add (or change) an element of a structure.
- PLOTXY
- PLOTXYLIB
- PLOTXYVEC
- PLOTXYZ
- PMPLOT
- SCAT_PLOT
  Produces a scatter plot of selected tplot variables.
- SPECPLOT
  Creates a spectrogram plot.
- SPLIT_VEC
  take a stored vector like 'Vp' and create stored vectors 'Vp_x','Vp_y','Vp_z'
- STORE_DATA
  Store time series structures in static memory for later retrieval
- STRPLOT
  Procedure used to print strings in a "TPLOT" style plot.
- TIMEBAR
  plot vertical (or horizontal) lines on TPLOTs at specified times (or values)
- TIMERANGE
- TIMESPAN
  Define a time span for the "tplot" routine.
- TLIMIT
- TNAMES
  Returns an array of "TPLOT" names
- TPLOT
  Creates a time series plot of user defined quantities.
- TPLOT3D
- TPLOT_COM
- TPLOT_FILE
  OBSOLETE PROCEDURE! Use "TPLOT_SAVE" and "TPLOT_RESTORE" instead.
- TPLOT_KEYS
  Sets up function keys on user keyboard to perform frequent "tplot"
- TPLOT_NAMES
  Lists current stored data names that can be plotted with the TPLOT routines.
- TPLOT_OPTIONS
  Sets global options for the "tplot" routine.
- TPLOT_PANEL
  Sets the graphics parameters to the specified tplot panel.
- TPLOT_POSITIONS
  Return a set of plot positions for tplot.
- TPLOT_QUANT__DEFINE
- TPLOT_RESTORE
  Restores tplot data, limits, name handles, options, and settings.
- TPLOT_SAVE
  Store tplot data in a file.
- TPLOT_SORT
  Sorts tplot data by time (or x).
- TPLOTXY
- XLIM
  To set plotting limits for plotting routines.
- YLIM
  Sets y-axis limits for plotting routines.
- YLIMIT
- ZLIM
  To set plotting limits for plotting routines.

# Routine Descriptions

## BITPLOT

[Next Routine] [List of Routines]

    NAME:
      bitplot

    INPUT: (optional if DATA keyword is set)
        x: array of x values
        y: array of y values

    PURPOSE:
      Plots 'ON' bits for housekeeping type data.
      Can be used by "tplot".
      See "_tplot_example" and "_get_example_dat" for an example.

    KEYWORDS:
        PSYMS: array of IDL plot psym values corresponding to each bit.
              OVERPLOT: create plot without erasing previous plot.
        DI: value to be given to first bit in plot.  Default is 0.
        LIMITS: TPLOT limits structure corresponding to the variable plotted.
        DATA: TPLOT data structure corresponding to the variable plotted.
        NUMBITS: the number of bits that will be plot
        SYMSIZE: set the size of the symbol

     $LastChangedBy: pcruce $
     $LastChangedDate: 2008-02-28 19:13:34 -0800 (Thu, 28 Feb 2008) $
     $LastChangedRevision: 2428 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/bitplot.pro $

(See ssl_general/tplot/bitplot.pro)

## CLEAN_SPIKES

[Previous Routine] [Next Routine] [List of Routines]

     Procedure:   CLEAN_SPIKES, 'name'
     Purpose:  Simple routine to remove spikes from tplot data.
     Author: unknown, Probably Frank Marcoline
     jmm, 4-jul-2007, made to work for negative data, by adding absolute
     values
     jmm, 30-jul-2007, Added more error checking
     jmm, 15-sep-2009, documentation test
    $LastChangedBy: $
    $LastChangedDate: $
    $LastChangedRevision: $
    $URL: $

(See ssl_general/tplot/clean_spikes.pro)

## COPY_DATA

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  	copy_data,  oldname, newname
    PURPOSE:	to copy a data structure
    INPUT:
    	oldname:	name associated with old data structure
    	newname:	name associated with new data structure
    KEYWORDS:
           LINK:   if set, then the data is not copied but is linked to the old
                       name.

    SEE ALSO:	"get_data",
    		"store_data"

    CREATED BY:	Davin Larson
    LAST MODIFICATION: copy_data.pro  1.10   97/05/20

(See ssl_general/tplot/copy_data.pro)

## CROSSHAIRS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:                  crosshairs
    PURPOSE:
    Display crosshairs on the plot window, display the data coordinates of the
    cursor position on the plot, and return the coordinates of clicked points.
    			Use the mouse buttons to control operation:
    			1: Record and print a point
    			2: Delete the previously recorded point
    			3: Quit.
    CALLING SEQUENCE:      crosshairs,x,y
    INPUTS:                x,y:  set to named variables to return the data
                                 coordinates of the cursor position where mouse
                                 button 1 was pressed.

    KEYWORD PARAMETERS:
    	COLOR:  set to a scalar byte to change the color of the crosshairs.
    		note:  you will not get the color you ask for.  it's the nature
    		of XOR graphics.  could be useful to change colors though.
    	LEGEND: set a position for the legend, in data coords.
    	DOT_CURSOR:  change the cursor to a dot.  it's smaller and makes seeing
    		the data easier.  warning:  will reset the cursor to crosshairs
    		after quitting.  if you had set your own cursor (changed from
    		the default) it'll be replaced.
    	FIX:	if crosshairs crashes  (if you Control-C out of it) then
    		you probabaly want to call crosshairs,/fix
    		all it does is calls:  device,set_graphics=3,/cursor_cross
    		but do you want to remember that line?
    		FIX repairs the changes to the X device that crosshairs made.
    	SILENT: don't print clicked points
           NOLEGEND:  don't display the legend
    OUTPUTS:       prints clicked data points to the terminal, prints the current
    		cursor position on the graphics window (or last position before
    		leaving the window)
    SIDE EFFECTS:          can mess up your display.  use crosshairs,/fix to fix.
    			can leave junk on your plot.  not recommended for use
    			if you intend to call tvrd() before reploting.
    LAST MODIFICATION:     @(#)crosshairs.pro	1.5 98/07/31
    CREATED BY:            Frank V. Marcoline
    NOTES:			Inspired by IDL's box_cursor.pro

(See ssl_general/tplot/crosshairs.pro)

## CTIME

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   ctime,time,y,z
    INPUT:
        time: Named variable in which to return the selected time (seconds
              since 1970)
        y:    Named variable in which to return the y value
        z:    Named variable in which to return the z value
    KEYWORDS:
        PROMPT:  Optional prompt string
        NPOINTS: Max number of points to return
        PSYM:    If set to a psym number, the cooresponding psym is plotted at
                 selected points
        SILENT:  Do not print data point information
        PANEL:   Set to a named variable to return an array of tplot panel numbers
                 coresponding to the variables points were chosen from.
        APPEND:  If set, points are appended to the input arrays,
                 instead of overwriting the old values.
        VNAME:   Set to a named variable to return an array of tplot variable names,
                 cooresponding to the variables points were chosen from.
        COLOR:   An alternative color for the crosshairs.  0<=color<=!d.n_colors-1
        SLEEP:   Sleep time (seconds) between polling the cursor for events.
                 Defaults to 0.1 seconds.  Increasing SLEEP will slow ctime down,
                 but will prevent ctime from monopolizing cpu time.
        INDS:    Return the indices into the data arrays for the points nearest the
                 recorded times to this named variable.
        VINDS:   Return the second dimension of the v or y array.
                 Thus  TIME(i) is  data.x(INDS(i))           and
                       Y(i)    is  data.y(INDS(i),VINDS(i))  and
                       V(i)    is  data.v(VINDS(i)) or data.v(INDS(i),VINDS(i))
                 for get_data,VNAME(i),data=data,INDS=INDS,VINDS=VINDS
        EXACT:   Get the time,y, and (if applicable) z values from the data
                 arrays.  If on a multi-line plot, get the value from the line
                 closest to the cursor along y.
        NOSHOW:  Do not show the plot window.
        DEBUG:   Avoids default error handling.  Useful for debugging.
        DAYS, HOURS, MINUTES, SECONDS: Sets time granularity.  For example
                 with MINUTES=1, CTIME will find nearest minute to cursor
                 position.
    PURPOSE:
       Interactively uses the cursor to select a time (or times)
    NOTES:       If you use the keyword EXACT, ctime may run noticeablly slower.
             Reduce the number of time you cross panels, especially with
             tplots of large data sets.
    SEE ALSO:  "crosshairs"

    CREATED BY:    Davin Larson & Frank Marcoline
    LAST MODIFICATION:     @(#)ctime.pro   1.44 02/11/01
    WARNING!
      If ctime crashes, you may need to call:
      IDL> device,set_graph=3,/cursor_crosshair

(See ssl_general/tplot/ctime.pro)

## CUTS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:	cuts
    PURPOSE:	to show x cuts or y cuts of a
    		"tplot" spectrogram
    INPUT:		none
    KEYWORDS:	name:	name of the variable you want cuts for

    CREATED BY:	Peter Schroeder
    LAST MODIFICATION:	@(#)cuts.pro	1.6 98/01/29

(See ssl_general/tplot/cuts.pro)

## DATA_CUT

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION: A = data_cut(name, t)
    PURPOSE:  Interpolates data from a data structure.
    INPUT:
      name:  Either a data structure or a string that can be associated with
          a data structure.  (see "get_data" routine)
          the data structure must contain the element tags:  "x" and "y"
          the y array may be multi dimensional.
      t:   (scalar or array)  x-values for interpolated quantities.
    RETURN VALUE:
      a data array: the first dimension is the dimension of t
                    the second dimension is the dimension of name

     NOTE!!  keyword options have been temporarily removed!!!!

    KEYWORDS:
      EXTRAPOLATE:  Controls interpolation of the ends of the data. Effects:
                    0:  Default action.  Set new y data to NAN or to MISSING.
                    1:  Extend the endpoints horizontally.
                    2:  Extrapolate the ends.  If the range of 't' is
                        significantly larger than the old time range, the ends
                        are likely to blow up.
      INTERP_GAP:   Determines if points should be interpolated between data gaps,
                    together with the GAP_DIST.  IF the data gap > GAP_DIST,
                    follow the action of INTERP_GAP
                    0:  Default action.  Set y data to MISSING.
                    1:  Interpolate gaps
      GAP_DIST:     Determines the size of a data gap above which interpolation
                    is regulated by INTERP_GAP.
                    Default value is 5, in units of the average time interval:
                    delta_t = (t(end)-t(start)/number of data points)
      MISSING:      Value to set the new y data to for data gaps.  Default is NAN.

    CREATED BY:	 Davin Larson
    LAST MODIFICATION:     @(#)data_cut.pro	1.19 02/04/17
                    Added the four keywords. (fvm 9/27/95)

(See ssl_general/tplot/data_cut.pro)

## DATA_TO_NORMAL

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:	data_to_normal
    PURPOSE:	convert data coordinates to normal coordinates
    INPUT:
    	datav:	data coordinates
    	s:	!AXIS structure
    KEYWORDS:
    	none

    CREATED BY: 	Frank Marcoline.  Hiested from Davin's normal_to_data.
    LAST MODIFICATION: 	@(#)data_to_normal.pro	1.2 97/01/09

    NOTE:	I think this procedure is superceded by convert_coord.

(See ssl_general/tplot/data_to_normal.pro)

## DEL_DATA

[Previous Routine] [Next Routine] [List of Routines]

    NAME:                  del_data
    PURPOSE:
    			obsolete procedure!  use "STORE_DATA" instead
                           delete tplot variables
                           del_data calls "store_data" with the DELETE keyword set
                           let: input=['a','b','c','d','e','f']
                           then, del_data,input is the same as
                           store_data,delete=input
    CALLING SEQUENCE:      del_data,input
    INPUTS:                input:  strarr() or intarr() of tplot variables
    LAST MODIFICATION:     @(#)del_data.pro	1.4 01/10/08
    CREATED BY:            Frank Marcoline

(See ssl_general/tplot/del_data.pro)

## DRAW_COLOR_SCALE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   draw_color_scale
    NAME:
      draw_color_scale
    PURPOSE:
      Procedure to draw a color scale.
    INPUTS: (none)
    KEYWORDS:
    	RANGE:		Array of two giving the range in data values the scale
    	        	corresponds to.
           BRANGE: 	intarr(2) giving the range in color map values the
    			scale spans.
           LOG:		If set, make scale logarithmic.
    	CHARSIZE:	Character size to be used for scale.
    	YTICKS:		Functions like IDL plot yticks keyword.  Used to set
    			number of scale annotations.
    	POSITION:	fltarr(4) giving the position of the color scale in the
    			window in the form (x0,y0,x1,y1).
    	OFFSET:		fltarr(2) giving the offsets from the right side of the
    			current plot for calculating the x0 and x1 positions
    			of the color scale. In device units. Ignored if
    			POSITION keyword is set.
    	TITLE:		String title for color scale.
    CREATED BY:	Davin Larson
    LAST MODIFIED:	1.17 05/29/07
    MODIFIED BY: Patrick Cruce

(See ssl_general/tplot/draw_color_scale.pro)

## FIND_HANDLE

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:  find_handle(name)

    PURPOSE:
       Returns the index associated with a string name.
       This function is used by the "TPLOT" routines.

    INPUT:     name  (scalar string)
        name can also be the corresponding integer index to a TPLOT quantity,
        in which case name will be converted to the string handle.

    RETURN VALUE:   tplot index. (0 if not found)

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)find_handle.pro	1.14 99/02/26

(See ssl_general/tplot/find_handle.pro)

## GETTIME

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:  gettime(x)
    INPUTS:   x: Null or double or string or integer
    OUTPUT:   double,  seconds since Jan 1, 1970
    Examples:
      t = gettime('95-7-4/12:34')
      t = gettime('12:34:56')     (get time on reference date)
      t = gettime(t+300.)         (assumes t is a double)
      t = gettime(10)             (t = 10 am on reference date)
      t = gettime(/key)           (prompts user for time on reference date)
      t = gettime(key='Enter time: ')
      t = gettime(/curs)          (select time using cursor in tplot routine)
    KEYWORDS:
       KEYBOARD:  If non-zero then user is prompted to enter a time.  If KEYBOARD
          is a string then that string is used as a prompt.
       CURSOR:  if non-zero then user can select a time with the cursor.
       VALUES:  if cursor keyword set, returns data values for time chosen.
       REFDATE:  Sets the reference date if REFDATE is a string with
           format: "yyyy-mm-dd".

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)gettime.pro	1.17 98/08/02

(See ssl_general/tplot/gettime.pro)

## GET_DATA

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  get_data , name, time, data, values
    PURPOSE:
       Retrieves the data and or limit structure associated with a name handle.
       This procedure is used by the "TPLOT" routines.
    INPUT:  name    scalar string or index of TPLOT variable
            time	 named variable to return time values.
            data    named variable to return data (y) values.
            values  named variable to return additional (v) values.
    KEYWORDS:
       DATA:   named variable to hold the data structure.
       LIMITS: named variable to hold the limits structure.
       DLIMITS: named variable to hold the default limits structure.
       ALIMITS: named variable to hold the combined limits and default limits
                structures.
       DTYPE: named variable to hold the data type value.  These values are:
    		0: undefined data type
    		1: normal data in x,y format
    		2: structure-type data in time,y1,y2,etc. format
    		3: an array of tplot variable names
       PTR:   named variable to hold pointers to data structure.
       INDEX:  named variable to hold the name index.  This value will be 0
         if the request was unsuccessful.

    SEE ALSO:	"STORE_DATA", "TPLOT_NAMES", "TPLOT"

    CREATED BY:	Davin Larson
    MODIFICATION BY: 	Peter Schroeder
    LAST MODIFICATION:	@(#)get_data.pro	1.28 02/04/17

(See ssl_general/tplot/get_data.pro)

## GET_TIMESPAN

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:	get_timespan
    PURPOSE:	To get timespan from tplot_com or by using timespan, if
    		tplot time range not set.
    INPUT:
    	t, actually returned to you
    KEYWORDS:
    	none

    SEE ALSO:	"timespan"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)get_timespan.pro	1.9 97/06/02

(See ssl_general/tplot/get_timespan.pro)

## GET_YLIMITS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  get_ylimits, datastr, limits, trg
    PURPOSE:
       Calculates appropriate ylimits for a string array of "TPLOT" variables
       to be plotted in the same panel.
    INPUT:  datastr	string array of TPLOT variables
    	 limits		limits structure to be modified (usually the limits
    			structure of the TPLOT variable whose data
    			field is a string array of TPLOT variables)
    	 trg		time range over which to calculate the limits;
    			double[2]
    CREATED BY:	Peter Schroeder
    LAST MODIFIED:	%W% %E%

(See ssl_general/tplot/get_ylimits.pro)

## ITON

[Previous Routine] [Next Routine] [List of Routines]

    NAME:                  iton
    PURPOSE:
                           Convert an index or array of indicies to data names.
                           This exits because it is not always reasonable to make
                           a program tell the difference between a data array
                           and an index array, and because not all programs
                           accept indicies as inputs instead of data names.
    CALLING SEQUENCE:      names=iton(ind)
    INPUTS:                ind:  an index or array of indicies
    OPTIONAL INPUTS:       none
    KEYWORD PARAMETERS:    none
    OUTPUTS:               a data name or array of data names
    OPTIONAL OUTPUTS:      none
    COMMON BLOCKS:         tplot_com
    SIDE EFFECTS:          none
    EXAMPLE:               for i=6,13 do store_data,iton(6),/delete
    LAST MODIFICATION:     @(#)iton.pro	1.5 97/06/11
    CREATED BY:            Frank Marcoline

(See ssl_general/tplot/iton.pro)

## MAKEGAP

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE makegap,dg,x,y
    PURPOSE:
       Creates data gaps (by inserting NaN) when the time between data points is
       larger than a value either passed in by the user or calculated to a
       default.
    INPUT:
       dg: If dg is positive, it is the maximum allowed time gap.  Any time gaps
    	greater than dg will be treated as data gaps.  If dg is negative,
    	the procedure will calculate a default value for dg of 20 times the
    	the smallest time gap in the time series.
        x: The time array.
        y: The data array.
    KEYWORDS:
        v: Optional third dimension array.
        dy: Optional uncertainty in y.
    CREATED BY: Peter Schroeder
    LAST MODIFIED:	@(#)makegap.pro	1.2 98/02/18

(See ssl_general/tplot/makegap.pro)

## MPLOT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  mplot, x, y, [,dy]
    INPUT:
                x:  1 or 2 dimensional array of x values.
                y:  1 or 2 dimensional array of y values.
               dy;  error bars for y;  same dimensions as y. (optional)
    PURPOSE:
        General purpose procedure used to make multi-line plots.

    KEYWORDS:
        DATA:     A structure that contains the elements 'x', 'y' ['dy'].  This
           is an alternative way of inputing the data  (used by "TPLOT").
        LIMITS:   Structure containing any combination of the following elements:
              ALL PLOT/OPLOT keywords  (ie. PSYM,SYMSIZE,LINESTYLE,COLOR,etc.)
              ALL MPLOT keywords
              NSUMS:   array of NSUM keywords.
              LINESTYLES:  array of linestyles.
        LABELS:  array of text labels.
        LABPOS:  array of positions for LABELS.
        LABFLAG: integer, flag that controls label positioning.
                 -1: labels placed in reverse order.
                  0: No labels.
                  1: labels spaced equally.
                  2: labels placed according to data.
                  3: labels placed according to LABPOS.
        BINS:    flag array specifying which channels to plot.
        OVERPLOT: If non-zero then data is plotted over last plot.
        NOXLAB:   if non-zero then xlabel tick marks are supressed.
        COLORS:   array of colors used for each curve.
        NOCOLOR:  do not use color when creating plot.
    NOTES:
        The values of all the keywords can also be put in the limits structure or
        in the data structure using the full keyword as the tag name.
        The structure value will overide the keyword value.

    CREATED BY:	Davin Larson
    FILE:  mplot.pro
    VERSION  1.43
    LAST MODIFICATION: 02/11/01

(See ssl_general/tplot/mplot.pro)

## NORMAL_TO_DATA

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:	normal_to_data
    PURPOSE:	convert normal coordinates to data coordinates
    INPUT:
    	normv:	normal coordinates
    	s:	!AXIS structure
    KEYWORDS:
    	none

    CREATED BY: 	Davin Larson
    LAST MODIFICATION: 	@(#)normal_to_data.pro	1.5 98/08/02

    NOTE:	I think this procedure is superceded by convert_coord.

(See ssl_general/tplot/normal_to_data.pro)

## OPTIONS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   options, str, tag_name, value
    PURPOSE:
      Add (or change) an element of a structure.
      This routine is useful for changing plotting options for tplot, but can also
      be used for creating limit structures for other routines such as "SPEC3D"
      or "CONT2D"

    INPUT:
      str:
        Case 1:  String (or array of strings)
           The limit structure associated with the "TPLOT" handle name is altered.
           Warning!  wildcards accepted!  "*" will change ALL tplot quantities!
        Case 2:  Number (or array of numbers)
           The limit structure for the given "TPLOT" quantity is altered.  The
           number/name association is given by "TPLOT_NAMES"
        Case 3:  Structure or not set (undefined or zero)
           Structure to be created, added to, or changed.
      tag_name:     string,  tag name for value.
      value:    (any type or dimension) value of new element.
    NOTES:
      if VALUE is undefined then it will be DELETED from the structure.
      if TAG_NAME is undefined, then the entire limit structure is deleted.

    KEYWORDS:
      DEFAULT:  If set, modify the default limits structure rather than the
    	    regular limits structure (tplot variables only).
    SEE ALSO:
      "GET_DATA","STORE_DATA", "TPLOT", "XLIM", "YLIM", "ZLIM", "STR_ELEMENT"

    CREATED BY:	Jasper Halekas
    Modified by:   Davin Larson
    LAST MODIFICATION:	@(#)options.pro	1.19 99/04/07

(See ssl_general/tplot/options.pro)

## PLOTXY

[Previous Routine] [Next Routine] [List of Routines]

     Procedure: plotxy

     Purpose: Takes an array of 3-d(Nx3) vectors or tplot variable
              and plots them using 2-d plots to help visualize them.
              It can also take an MxNx3 array tplot variable storing
              an MxNx3 array which represents a set of M lines with N
              points

             Can also accept an Nx2 or an MxNx2 element array...if this
             is done the versus argument should not use a custom
             designation or the z-axis, as it assumes 2-d vectors are in
             the x-y plane, and thus will distort the vectors upon projection.

             plotxy/tplotxy plots can be interleaved on the same window
             with plotxyz & plotxyvec plots

             Calling tplotxy with no arguments to redraw the entire
             window(including plotxyz,plotxyvec plots)

             ***************************************************

             Using custom axes:  If you use two vectors to define custom
             axes, the procedure will generate a plot of the data vectors
             projected into a plane defined by the span of the two custom
             vectors.  The x-axis will be the first vector, the y axis
             will be the second vector.  This means that if the custom
             vectors are not orthogonal the plot will show a distortion.
             You can think of this as plotting along a plane that slices
             though the 3-d space.

             ********************************
             Plot windows and panels:
             using, /overplot,/addpanel,/noisotropic and multi=

             To put multiple panels in a window first call
             plotxy with the multi keyword.  It will either
             plot in which ever window is your current one, or
             create a new one if no window exists or if you
             request the use of a nonexistent window.

             During this first call you may want to specify things
             like wtitle,xsize,ysize,window...in addition to your normal
             plotting options. However,Calling window options will interfere with
             the creation of postscripts.

             multi specifies the plot window panel layout.
             So if you set multi='3,2' you will get 6 plots
             in your window with a layout like:
               -------
               |x x x|
               |x x x|
               -------

             Each panel will have dimensions x number of pixels = 1/3 *
             xsize of window and y number of pixels = 1/2 * ysize of window.

             Your first call should also specify the layout of your
             first panel. To add to that panel use the /overplot keyword.

             When you use the /add keyword the program will move on to
             the next panel within the plot window and you should add
             options to specify the layout of that panel.

             If you set the xmargin or ymargin keyword the margin will be
             relative to the overall size of that panel. When using the
             not using the noisotropic keyword the procedure will make
             each axis vary over the same range AND make the
             largest possible square window given the size of the panel
             and the sizes of the margins you have provided, if possible.
             In some cases when ranges are set explictly the plot must
             be rectangular.

             An entire plot window must be filled in sequence, if you move
             on to a new window you will not be able to go back to the
             previous window without restarting.

             If you call plotxy with no arguments it will redraw the
             entire window including all panels and overplots.  If you
             resize the window before calling with new arguments it
             will redraw the isotropic panels as the largest possible
             squares.  This comes at a cost of storing copies of the
             commands and data you made in memory.  If you need to save
             memory you can call the function with the /memsave argument,
             but then redraws will be done using hardware and window resizes
             can distort isotropic plots.

             NOTE TO PROGRAMMERS:
               Information about plotting for plotxy is stored in
               the global variable !TPLOTXY, this includes
               information about the layout of the plot window
               which panel it is currently working on, and the
               sequence of commands used to generate current plot window
               so that it can regenerate the plotwindow when called
               with no arguments. This variable also stores information
               used by the plotxyz function so spectrographic xyz plots
               can be interleaved with xy line plots.

    Example: a = [[dindgen(10)],[dindgen(10)],[dindgen(10)]]
             get_data,'thb_state_pos',data=d
             dat=d.y
             plotxy
             plotxy,a
             plotxy,a,versus='yzr'
             plotxy,dat,versus='cc',custom=transpose([[1,1,0],[0,0,1]])
             plotxy,dat,versus='xryz',xrange=[0,10],yrange=[0,10]

     Inputs: vectors(optional): an Nx3,MxNx3,Nx2, or MxNx2 list

     Keywords:

             versus(optional): specify the projection to be used, can be
             'xx','xy','xz','yx','yy','yz','zx','zy','zz','cc' you can also
             follow a letter with an 'r' to reverse the axis(goes from
             positive to negative instead of from negative to positive)
             if you specify 'cc','crc'...that indicate you want to use a
             custom projection
             example: 'xry' will be an xy plot with the maximum x value
             listed on the left and the minimum on the right
             (default:'xy')

             custom(optional): set this variable to a
             2x3 matrix whose columns define a plane in 3-d space, to define a
             custom projection. In other words the 2-d plot will be a
             plot of the vectors passed into plotxy when they are
             projected into a plane defined by
             span(custom[0,*],custom[1,*]). (span is defined as the set
             of all the linear combinations of two vectors, or
             span(x,y) = {mx+ny:m = element of the reals, n = element of
             the reals} The vectors used to define this plane will be
             relative to whatever 3-d coordinate system the input vector
             data is in.
             So if the call:
             tplotxy,'somedata',versus='cc',custom=transpose([[1,1,0],[0,0,1])
             is made, the plot generated will be of the vectors closest
             to the data vectors that are inside a vertical plane whose
             intersection with the x-y plane forms a line y=x.
             tplotxy,'somedata',versus='cc',custom=transpose([[1,0,0],[0,1,0])
             is effectively the same as:
             tplotxy,'somedata',versus='xy'

             overplot(optional): set this keyword if you want to plot
             on the last plot and panel that you plotted on

             addpanel(optional): set this keyword if you want to plot on a new
             panel within the same plot window as where you last
             plotted. This will go to the next column first and if it is
             at the end of a row, to the next row.

             multi(optional): set this keyword to a string that
             specifies the layout of panels within a plotwindow.  Set
             this keyword only the first time you call tplotxy for a
             given plotwindow.  Each time you set it, the previous
             contents of the window will be erased. You can separate
             the two elements with a variety of different delimiters
             The first element is columns left to right, the second rows
             top to bottom. Append an 'r' to the elements to have it
             reverse the direction of panel application
             Examples:  multi= '2 3'
                        multi= '5r,7'
                        multi=' 1:6r'
                         .....

             noisotropic(optional): set this keyword if you don't want the
             scaling of both axes to be the same and the space to
             be perspective corrected so that a cm of y unit takes
             up the same space on the screen as a cm of x unit

             memsave(optional): set this keyword to request command
             copies not be saved and redraws be done without maintaining
             square isotropic plots.  Setting this option can potentially
             save quite a lot of memory.

             linestyle(optional):set this to change the linestyle used
             0 = default,1=dotted=,2=dashed,3=dash dot,4=dash dot
             dot,5=long dashes

             xrange(optional): set this to a 2 element array to specify
             the min and max for the first axis(x) of the 2-d plot

             yrange(optional): set this to a 2 element array to specify
             the min and max for the second axis(y) of the 2-d plot

             pstart(optional): set this keyword to a number representing
             the symbol you would like to start lines with. (This works
             like the idl psym keyword, but only for the first symbol
             in a line being plotted)

             pstop(optional): set this keyword to a number representing
             the symbol you would like to end lines with. (This works
             like the idl psym keyword, but only for the last symbol
             in a line being plotted)

             psym(optional): use this to plot the line using a symbol
             rather than a line.

             symsize(optional): specify the size of the start and end
             symbol or psym. (default:1.0)

             WARNING: setting any of the 4 windowing options below
             will interfere with postscripts

             window(optional):specify the window for
             output, if overplot is not specified, it will
             always recreate the window so it can attempt to make
             the window square (default:current)

             xsize(optional):specify the xsize of the window in
             pixels(default: current)

             ysize(optional):specify the ysize of the window in pixels
             (default: current)

             wtitle(optional):the title you would like the window to have

             colors(optional): if vectors in Nx3 colors should contain a
             single element(name like 'r' or index like 2), if vectors is
             an MxNx3 then it can contain a single element or M elements

             xmargin(optional): set this option to a two element array
             specifing the size of the margin of the current panel
             relative to the size of overall panel on the x dimension.
             Values range from 0.0(no margin) to 1.0(all margin)
             The first element of the array is the left margin
             The second element is the right margin

             ymargin(optional): set this option to a two element array
             specifing the size of the margin of the current panel
             relative to the size of overall panel on the y dimension.
             Values range from 0.0(no margin) to 1.0(all margin)
             The first element of the array is the bottom margin and
             The second element of the array is the top margin

             xlog(optional): set the x scale to be logarithmic

             ylog(optional): set the y scale to be logarithmic

             xtitle(optional): set the xtitle for the plot

             ytitle(optional): set the ytitle for the plot

             grid(optional): set this to 1 to have the procedure
             generate a grid rather than normal tickmarks

             units(optional): set this if you want this unit label
             appended to both axis titles.(This will be ignored if
             you set the xtitle or ytitle explictly)

             labels(optional): set this if you want to use the axis
             labels array from limits/dlimits of a tvar.(This will be
             ignored if you set the xtitle or ytitle explictly)

    ;        markends: This keyword is deprecated.  You can use
             all the normal options for plot to manipulate the
             position of the ticks on the axes.

             xtick_get,ytick_get: These behave exactly as the plot
             command versions, but they had to be identified explictly
             to ensure they would be passed through correctly.

             replot(internal): this option is used in recursive calls
             by the routine to itself and should never be set by the
             user

             This function also takes normal idl keywords that effect
             plotting style(things like xtitle,ytitle....etc..)

      SEE ALSO:
        plotxyz,tplotxy,thm_crib_tplotxy,thm_crib_plotxy,thm_crib_plotxyz
        plotxylib,plotxyvec

     $LastChangedBy: pcruce $
     $LastChangedDate: 2008-01-16 16:54:40 -0800 (Wed, 16 Jan 2008) $
     $LastChangedRevision: 2283 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplotxy.pro $

(See ssl_general/tplot/plotxy.pro)

## PLOTXYLIB

[Previous Routine] [Next Routine] [List of Routines]

    Procedure: plotxylib

    Purpose:  A library of helper functions for plotxy, plotxyz, and plotxyvec.
              To make the library available for a routine just call: plotxylib
              That will force all the routines to be compiled.

              pxy_set_state sets the state of !TPLOTXY which keeps track
              of windowing information for the plotxy* routines.  pxy_push_state
              pushes arguments to these routines onto a data structure that allows
              them to be replot without retyping the arguments.  pxy_replot will
              replot a series of calls from memory.  pxy_get_pos will calculate
              the position and shape of a window from the windowing information
              in !TPLOTXY and the requested data ranges and margins for a window.
              pxy_set_window is a routine that houses some redundant
              initialization code.

              SEE ALSO: plotxy,plotxyz,plotxyvec

     $LastChangedBy: pcruce $
     $LastChangedDate: 2009-12-15 14:49:37 -0800 (Tue, 15 Dec 2009) $
     $LastChangedRevision: 7011 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/plotxylib.pro $

(See ssl_general/tplot/plotxylib.pro)

## PLOTXYVEC

[Previous Routine] [Next Routine] [List of Routines]

     Procedure:  plotxyvec

     Purpose:  Plots a set of arrows on an image generated with
             plotxy,tplotxy or, plotxyz this is a pretty simple wrapper
             for the idl arrow routine.  The major difference is that
             this routine stores a history so that you can autoreplot it
             This routine will take any of the options that the normal
             arrows routine takes, with one exception.  plotxyvec must
             always use data coordinates.

     Examples:

        plotxyvec,xy,dxy
        plotxyvec,xy,dxy,/grid,multi='2,1'
        plotxyvec,xy,dxy,/grid,/addpanel,xticks=5

     Arguments: xy: an Nx2 array that contains the starting coordinates of the arrows
                dxy: an Nx2 array that contains the offset from each
                     starting coordinate to the end of the arrow
                (They argument can be MxNx2 or JxMxNx2 ... the main requirement is that the last
                dimension be 2)

     Keywords:

          noisotropic:Set this keyword if you want the plot to not be isotropic

          overplot: set this keyword if you want to plot
            on the last plot and panel that you plotted on

          addpanel: set this keyword if you want to plot on a new
             panel within the same plot window as where you last
             plotted. This will go to the next column first and if it is
             at the end of a row, to the next row.

          multi: set this keyword to a string that
             specifies the layout of panels within a plotwindow.  Set
             this keyword only the first time you call tplotxy for a
             given plotwindow.  Each time you set it, the previous
             contents of the window will be erased. You can separate
             the two elements with a variety of different delimiters
             The first element is columns left to right, the second rows
             top to bottom. Append an 'r' to the elements to have it
             reverse the direction of panel application
             Examples:  multi= '2 3'
                        multi= '5r,7'
                        multi=' 1:6r'
                         .....
           [xy]range: The desired range of your plot on a particular axis. By default
           this routine will not display any arrows that start or end outside this range.
           Use noclip, nostartclip, nostopclip, or clip. To display clipped arrows.

           [xy]margin: The desired margin for the plot on the left/right(x) axis
               or the top/bottom(y) axis.  This is specified as a proportion of
               the overall plot window.(ie from 0.0 to 1.0)

            grid:  Set this option to draw a grid on the output

            window: Set a specific window number to plot in.

            [xy]size: The size in pixels of the window you want to plot

            wtitle:  The title of the window

            uarrowside:  A string storing the side on which the unit arrow should be drawn.
            Can be: 'left','right','top','bottom','none'

            uarrowoffset: The distance of the arrow from the edge of the plot.  This is
            specified as a proportion of the size of the plot. (By default it is .2 for left/right
            arrows and .05 for top/bottom arrows

            uarrowtext:  Any text to be drawn after the number of data units the arrow represents.
            This is usually used to indicate the units.

            uarrowdatasize: The number of data units that the unit arrow should represent.

            arrowscale: The ratio between the coordinate system of the
            start points(xy) and the coordinate system of the offsets.(dxy)
            (default:1.0)

            xtick_get,ytick_get: These behave exactly as the plot
            command versions, but they had to be identified explictly
            to ensure they would be passed through correctly.

            hsize: This scales the head size of the arrow.  This is basically like the hsize argument
            to arrow, except it is a normalized value instead of a fraction of !D.x_size.

            clip: allows the user to set clipping to a particular bounding box.
                  either set /clip to clip to the current x,y range or set clip equal to q
                  a 4 element array with elements [x0,y0,x1,x2] specifying the corners of
                  the bounding box

            startclip: clip xy, but not dxy

            stopclip: clip dxy, but not xy

            color:  Set the color of the arrows.  Can use color indexes or letters('b','g'...)
                 This does not currently allow you to set separate colors for separate arrows in
                 a single call.
            Replot:  For internal use only
            All Other Keywords:  See IDL documentation for arrow.pro,plot.pro, this routine
            accepts most of the arguments to these routines through _extra

     Notes: If the arrows are overplotted, the routine will use the
            x,y range of the previous plot, by default.

            The unit arrow will only be drawn automatically when using isotropic plots.
            If you'd like the routine to draw two unit arrows when using nonisotropic plots,
            to indicate the scaling in each direction, please request the feature.

            Arrows that start or end outside of the user defined xrange,yrange will be clipped
            by default.  Use noclip, nostartclip, nostopclip, or clip. Clipping clips the apparent
            range.  So if the arrows are enlarged by uarrowscale, they may be clipped; even if the
            data values they represent are in range.

              ********************************
             Plot windows and panels:
             using, /overplot,/addpanel,/noisotropic and multi=

             To put multiple panels in a window first call
             plotxy with the multi keyword.  It will either
             plot in which ever window is your current one, or
             create a new one if no window exists or if you
             request the use of a nonexistent window.

             During this first call you may want to specify things
             like wtitle,xsize,ysize,window...in addition to your normal
             plotting options. However,Calling window options will interfere with
             the creation of postscripts.

             multi specifies the plot window panel layout.
             So if you set multi='3,2' you will get 6 plots
             in your window with a layout like:
               -------
               |x x x|
               |x x x|
               -------

             Each panel will have dimensions x number of pixels = 1/3 *
             xsize of window and y number of pixels = 1/2 * ysize of window.

             Your first call should also specify the layout of your
             first panel. To add to that panel use the /overplot keyword.

             When you use the /add keyword the program will move on to
             the next panel within the plot window and you should add
             options to specify the layout of that panel.

             If you set the xmargin or ymargin keyword the margin will be
             relative to the overall size of that panel. When using the
             not using the noisotropic keyword the procedure will make
             each axis vary over the same range AND make the
             largest possible square window given the size of the panel
             and the sizes of the margins you have provided, if possible.
             In some cases when ranges are set explictly the plot must
             be rectangular.

             An entire plot window must be filled in sequence, if you move
             on to a new window you will not be able to go back to the
             previous window without restarting.

             If you call plotxy with no arguments it will redraw the
             entire window including all panels and overplots.  If you
             resize the window before calling with new arguments it
             will redraw the isotropic panels as the largest possible
             squares.  This comes at a cost of storing copies of the
             commands and data you made in memory.  If you need to save
             memory you can call the function with the /memsave argument,
             but then redraws will be done using hardware and window resizes
             can distort isotropic plots.

             NOTE TO PROGRAMMERS:
               Information about plotting for plotxy is stored in
               the global variable !TPLOTXY, this includes
               information about the layout of the plot window
               which panel it is currently working on, and the
               sequence of commands used to generate current plot window
               so that it can regenerate the plotwindow when called
               with no arguments. This variable also stores information
               used by the plotxyz function so spectrographic xyz plots
               can be interleaved with xy line plots.

     See Also:
       plotxy.pro,tplotxy.pro,plotxyz.pro,plotxylib.pro

     $LastChangedBy: pcruce $
     $LastChangedDate: 2008-08-15 14:15:37 -0700 (Fri, 15 Aug 2008) $
     $LastChangedRevision: 3406 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/plotxyvec.pro $

(See ssl_general/tplot/plotxyvec.pro)

## PLOTXYZ

[Previous Routine] [Next Routine] [List of Routines]

     Procedure: plotxyz

     Purpose: Generates an isotropic spectrographic plot.  It takes one
     2-d array(Z) and plots it using the values in 2 1-d arrays(X,Y) to
     scale the data in Z.  The X and Y axes can be any kind of data,
     most specifically the X axis need not be time.  By default the
     plots, are scaled isotropically.  Meaning that a unit on the x axis
     will have the same length on the screen as a unit on the z axis.

     The plots can be interleaved with plotxy/tplotxy plots in the same
     panel/window. Calling plotxyz with no arguments will redraw the
     entire window(including plotxy/tplotxy plots)

     The most significant restiction to this function is that it will
     clip any negative(or 0) data(in X,Y or Z) if you select a
     logarithmic axis.

     If one scaling axis is set to logarithmic and the other is not,
     but the plot is set to isotropic, 1 power unit on the logarithmic
     axis will take up the same space on screen as one normal unit on
     the normal axis.  Despite the capability to perform these mixed
     x,y log plots, this is not recommended...but feel free to experiment.

    ************************************
           Detailed explanation of Plot windows and panels:
             /addpanel,/noisotropic and multi=

             To put multiple panels in a window first call
             plotxyz with the multi keyword.  It will either
             plot in which ever window is your current one, or
             create a new one if no window exists or if you
             request the use of a nonexistent window.

             During this first call you may want to specify things
             like wtitle,xsize,ysize,window...in addition to your normal
             plotting options, setting these windowing options will
             interfere with the creation of postscript

             multi specifies the plot window panel layout.
             So if you set multi='3,2' you will get 6 plots
             in your window with a layout like:
               -------
               |x x x|
               |x x x|
               -------

             Each panel will have dimensions x number of pixels = 1/3 *
             xsize of window and y number of pixels = 1/2 * ysize of window.

             Your first call should also specify the layout of your
             first panel. To add to that panel use the /overplot keyword.

             When you use the /add keyword the program will move on to
             the next panel within the plot window and you should add
             options to specify the layout of that panel.

             If you set the xmargin or ymargin keyword the margin will be
             relative to the overall size of that panel. When using the
             not using the noisotropic keyword the procedure will make
             each axis vary over the same range AND make the
             largest possible square window given the size of the panel
             and the sizes of the margins you have provided, if possible.
             In some cases when ranges are set explictly the plot must
             be rectangular.

             An entire plot window must be filled in sequence, if you move
             on to a new window you will not be able to go back to the
             previous window without restarting.

             If you call plotxyz with no arguments it will redraw the
             entire window including all panels and overplots.  If you
             resize the window before calling with new arguments it
             will redraw the isotropic panels as the largest possible
             squares.  This comes at a cost of storing copies of the
             commands and data you made in memory.  If you need to save
             memory you can call the function with the /memsave argument,
             but then redraws will be done using hardware and window resizes
             can distort isotropic plots.

             NOTE TO PROGRAMMERS:
               Information about plotting for plotxyz is stored in
               the global variable !TPLOTXY, this includes
               information about the layout of the plot window
               which panel it is currently working on, and the
               sequence of commands used to generate current plot window
               so that it can regenerate the plotwindow when called
               with no arguments. This variable also stores information
               used by the plotxy function so line plots
               can be interleaved with xyz spectrographic plots.

     Required Inputs:
           x: 1-d array specifying the scaling/spacing of the x axis
              This array must have the same number of elements as the
              1st dimension of Z. One can think of the x coordinates of
              the centers of the Z array data

           y: 1-d array specifying the scaling/spacing of the y axis
              This array must have the same number of elements as the
              2nd dimension of Z. One can think of the y coordinates of
              the centers of the Z array data

           z: 2-d array specifying the intensity of each element, or the
              height of the z-axis.  This will be represented by color
              in the 2-d plot this procedure generates.

     Optional keywords:
                 interpolate: set this argument if you want the data to
                 be interpolated between z data.  This will give the
                 appearance of smooth gradations, although this may not
                 exist in the data.  If your Z data has blanks(NaNs),
                 interpolation can give inaccurate results near the blanks.

                 noisotropic: set this argument if you don't want
                 the plot to be isotropic. If this is set the plot
                 will fill the entire space available to it,
                 regardless of data scaling.

                 xlog,ylog,zlog: set any of these to create logarithmic
                 scaling on the appropriate axis.  It is recommended,
                 but not required that if you set xlog on an isotropic
                 plot you also set ylog.

                 multi: as explained above set this to a string
                 indicating the desired number of columns and rows
                 in your window. This string can must contain 2 numbers
                 delimited by any common delimiter character or space.
                 the numbers may optionally be followed by an r to
                 indicate a reversal in the direction that the plots
                 will be added to the window.

                 addpanel: set this keyword to make the procedure
                 move on to the next plot in window, if you have
                 previously set multi. If this is not set, it will
                 generate a new plot in a clear window, if this is
                 set and there are no more available spaces for
                 plots an error will be generated.

                 memsave: To allow replotting of the data when the
                 procedure is called with no arguments, the copies of
                 the data are stored in memory.  If memsave is set
                 these copies will not be saved and you will be unable
                 to replot with a 0 argument call.

                 xmargin,ymargin:  Set these keyword to a 2 element
                 array to set extra space around the plot.  Margins are
                 measured proportionally(from 0.0 to 1.0) and are
                 separate for each plot(not global to the entire window).
                 The arrays store the [left,right] xmargin or
                 [bottom,top] ymargin. Default xmargin for xyz plots is
                 [.15,.15] and ymargin is [.1,.075].

                 xrange,yrange,zrange: Set these keywords to a 2 element
                 array to control the range of values to be displayed
                 for each axis.

                 title: set this to a string indicating the title at
                 the top of the plot

                 xtitle,ytitle,ztitle: set this to a string indicating
                 the title of the appropriate axis.

                 charsize: set this to a number to scale the character
                 size of writing on the plot.  1.0 is the default,
                 less than 1.0 decreases charsize, greater increases.

                 WARNING setting window, xsize, ysize or wtitle will
                 interfere with the creation of postscript

                 window: specify the window in which the plots should be
                 made. The default is the current window. If the window
                 number does not exist one will be made

                 xsize,ysize: Specify the number of pixels of the window you are
                 plotting in. This can be done ahead by the user if they
                 like, or just by stretching the window.

                 wtitle: Specify the title for the bar at the top of the
                 window as a string.

                 noticks: set this if you do not want ticks on the plot
                          (mutually exclusive with grid)

                 grid: set this if you want a grid on your plot
                           (mutually exclusive with noticks)
                           Use xticks and yticks to manipulate the
                           spacing of your grid

                 markends: This keyword is deprecated.  You can use
                 all the normal options for plot to manipulate the
                 position of the ticks on the axes.

                 xtick_get,ytick_get: These behave exactly as the plot
                 command versions, but they had to be identified explictly
                 to ensure they would be passed through correctly.

                 zticks: this acts like the normal x,y ticks option in
                 idl plots.  Set it to some number greater than 1 to set
                 the number of tick marks of the z axis. It is available
                 because draw color scale will sometimes supress all the
                 tick marks on the z axis.

                 ps_resolution: set the resolution, if you are using
                 postscript (default is 150 pts/cm)

                 You can also use many normal plot options.

     NOTES:
       All NaN's & INFs in the x and y axes will be removed from the data. All
       NaN's in the z data will be replaced by the minimum value.

       bin2d is VERY useful for preparing data for use in this routine

       Be very careful when manually setting the ticks.  While some options like [xy]ticks
       are quite safe, others can inadvertently produce inaccurate labels as idl will sometimes
       make assumptions about positioning of axes, by rounding off.  If you plan on using [xy]tickv,
       or [xy]style be careful to verify that the axis labeling is working correctly.  This can best be done by
       testing on a data set where the axes are irregularly spaced and where some of the values at the axes are
       irrational.

     SEE ALSO:
        plotxy,tplotxy,thm_crib_tplotxy,thm_crib_plotxy,thm_crib_plotxyz,bin2d,
        plotxylib,plotxyvec

     $LastChangedBy: pcruce $
     $LastChangedDate: 2008-01-16 16:54:40 -0800 (Wed, 16 Jan 2008) $
     $LastChangedRevision: 2283 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplotxy.pro $

(See ssl_general/tplot/plotxyz.pro)

## PMPLOT

[Previous Routine] [Next Routine] [List of Routines]

     PROCECURE:	pmplot

     PURPOSE:	Used for making log y-axis plots.  Preformats data for
    		use with "mplot".  Plots negative data in red and positive
    		data in green.

     KEYWORDS:
        DATA:     A structure that contains the elements 'x', 'y' ['dy'].  This
           is an alternative way of inputing the data  (used by "TPLOT").
        LIMITS:   Structure containing any combination of the following elements:
              ALL PLOT/OPLOT keywords  (ie. PSYM,SYMSIZE,LINESTYLE,COLOR,etc.)
              ALL PMPLOT keywords
              NSUMS:   array of NSUM keywords.
              LINESTYLES:  array of linestyles.
        LABELS:  array of text labels.
        LABPOS:  array of positions for LABELS.
        LABFLAG: integer, flag that controls label positioning.
                 -1: labels placed in reverse order.
                  0: No labels.
                  1: labels spaced equally.
                  2: labels placed according to data.
                  3: labels placed according to LABPOS.
        BINS:    flag array specifying which channels to plot.
        OVERPLOT: If non-zero then data is plotted over last plot.
        NOXLAB:   if non-zero then xlabel tick marks are supressed.
        COLORS:   array of colors used for each curve.
        NOCOLOR:  do not use color when creating plot.
    NOTES:
        The values of all the keywords can also be put in the limits structure or
        in the data structure using the full keyword as the tag name.
        The structure value will overide the keyword value.

    LAST MODIFIED: @(#)pmplot.pro	1.4 02/04/17

(See ssl_general/tplot/pmplot.pro)

## SCAT_PLOT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: scat_plot, xname, yname
    PURPOSE:
       Produces a scatter plot of selected tplot variables.
       Colors are scaled according to zname, if present
    INPUTS:
       xname:    xvariable name
       yname:    yvariable name
       zname:    if present, color variable name
    KEYWORDS:
           TRANGE:  two element vector giving start and end time.
       limits:     a structure with plotting keywords
       begin_time:   time at which to start plot
       end_time: time at which to end plot

    CREATED BY:    Davin Larson
    LAST MODIFICATION: @(#)scat_plot.pro   1.13 02/04/17

(See ssl_general/tplot/scat_plot.pro)

## SPECPLOT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE specplot,x,y,z
    NAME:
       specplot
    PURPOSE:
       Creates a spectrogram plot.
       All plot limits and plot positions are handled by the keyword LIMITS.
    INPUT:
       x:  xaxis values:  dimension N.
       y:  yaxis values:  dimension M.  (Future update will allow (N,M))
       Z:  color axis values:  dimension (N,M).

       All options are passed in through a single structure.
    KEYWORDS:
       LIMITS:  A structure that may contain any combination of the following
           elements:
           X_NO_INTERP:   Prevents interpolation along the x-axis.
           Y_NO_INTERP:   Prevents interpolation along the y-axis.
           NO_INTERP:     Prevents interpolation along either axis
           NO_COLOR_SCALE: Prevents drawing of color bar scale.
           BOTTOM, TOP:   Sets the bottom and top colors for byte-scaling
           ALL plot keywords such as:
           XLOG,   YLOG,   ZLOG,
           XRANGE, YRANGE, ZRANGE,
           XTITLE, YTITLE,
           TITLE, POSITION, REGION  etc. (see IDL documentation for a description)
             The following elements can be included in LIMITS to effect DRAW_COLOR_SCALE:
           ZTICKS, ZRANGE, ZTITLE, ZPOSITION, ZOFFSET
       DATA:  A structure that provides an alternate means of supplying
           the data and options.  This is the method used by "TPLOT".
       X_NO_INTERP:   Prevents interpolation along the x-axis.
       Y_NO_INTERP:   Prevents interpolation along the y-axis.
       OVERPLOT:      If non-zero then data is plotted over last plot.
       OVERLAY:       If non-zero then data is plotted on top of data from last
            last plot.
       PS_RESOLUTION: Post Script resolution.  Default is 150.
       NO_INTERP:     If set, do no x or y interpolation.
       IGNORE_NAN:    If nonzero, ignore data points that are not finite.
       DX_GAP_SIZE = Maximum time gap over which to interpolate the plot. Use this
         keyword when overlaying spectra plots, allowing the underlying spectra to
         be shown in the data gaps of the overlying spectra.  Overrides value set
         by DATAGAP in dlimits.  Note: if either DX_GAP_SIZE or DATAGAP is set to
         less than zero, then the 20 times the smallest delta x is used.

    Notes:
      - The arrays x and y MUST be monotonic!  (increasing or decreasing)
      - The default is to interpolate in both the x and y dimensions.
      - Data gaps can be included by setting the z values to NAN  (!values.f_nan).
      - If ZLOG is set then non-positive zvalues are treated as missing data.

    See Also:  "XLIM", "YLIM", "ZLIM",  "OPTIONS",  "TPLOT", "DRAW_COLOR_SCALE"
    Author:  Davin Larson,  Space Sciences Lab
     $LastChangedBy: bckerr $
     $LastChangedDate: 2009-06-16 16:46:31 -0700 (Tue, 16 Jun 2009) $
     $LastChangedRevision: 6230 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/specplot.pro $

(See ssl_general/tplot/specplot.pro)

## SPLIT_VEC

[Previous Routine] [Next Routine] [List of Routines]

    NAME:                  split_vec
    PURPOSE:
                           take a stored vector like 'Vp' and create stored vectors 'Vp_x','Vp_y','Vp_z'
    CALLING SEQUENCE:      split_vec,names
    INPUTS:                names: string or strarr, elements are data handle names
    OPTIONAL INPUTS:
    KEYWORD PARAMETERS:    polar: Use '_mag', '_th', and '_phi'
    			titles: an array of titles to use instead of
    			the default or polar sufficies (NOT USED)
                           names_out: The variable names of the new variables
    OUTPUTS:
    OPTIONAL OUTPUTS:
    COMMON BLOCKS:
    SIDE EFFECTS:
    RESTRICTIONS:
    EXAMPLE:
    LAST MODIFICATION:     12-mar-2007, jmm
    CREATED BY:            Frank V. Marcoline
    $LastChangedBy: pcruce $
    $LastChangedDate: 2009-10-01 10:12:20 -0700 (Thu, 01 Oct 2009) $
    $LastChangedRevision: 6793 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/split_vec.pro $

(See ssl_general/tplot/split_vec.pro)

## STORE_DATA

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  store_data,name,DATA=data,LIMITS=limits,DLIMITS=dlimits,
         NEWNAME=newname,DELETE=delete
    PURPOSE:
       Store time series structures in static memory for later retrieval
       by the tplot routine.  Three structures can be associated with the
       string 'name':  a data structure (DATA) that typically contains the x and
       y data. A default limits structure (DLIMITS) and a user limits structure
       (LIMITS) that will typically contain user defined limits and options
       (typically plot and oplot keywords).  The data structure and the default
       limits structure will be
       over written each time a new data set is loaded.  The limit structure
       is not over-written.
    INPUT:
       name:   string name to be associated with the data structure and/or
         the limits structure.  Also, can enter tplot index as name.
         The name should not contain spaces or the characters '*' and '?'
    KEYWORDS:
        DATA:  variable that contains the data structure.
        LIMITS; variable that contains the limit structure.
        DLIMITS; variable that contains the default limits structure.
        NEWNAME: new tplot handle.  Use to rename tplot names.
        DELETE: array of tplot handles or indices to delete from common block.
        MIN: if set, data values less than this value will be made NaN.               (obsolete)
        MAX: if set, data values greater than this value will be made NaN.            (obsolete)
        NOSTRSW: if set, do not transpose multidimensional data arrays in
             structures.  The default is to transpose.
        ERROR: if set returns error code for store_data, values are:
        0=NO ERROR
        1=INVALID HANDLE ERROR
        2=OTHER ERROR

    SEE ALSO:    "GET_DATA", "TPLOT_NAMES",  "TPLOT", "OPTIONS"

    CREATED BY:    Davin Larson
    MODIFIED BY:   Peter Schroeder
    VERSION:   @(#)store_data.pro   1.44 02/04/17

(See ssl_general/tplot/store_data.pro)

## STRPLOT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  strplot, x, y
    INPUT:
                x:  array of x values.
                y:  array of y strings.
    PURPOSE:
        Procedure used to print strings in a "TPLOT" style plot.

    KEYWORDS:
        DATA:     A structure that contains the elements 'x', 'y.'  This
           is an alternative way of inputing the data.
        LIMITS:   The limits structure including PLOT and XYOUTS keywords.
        OVERPLOT: If set, then data is plotted over last plot.
        DI:       Not used. Exists for backward compatibility.

    LAST MODIFIED: @(#)strplot.pro	1.2 98/08/03

(See ssl_general/tplot/strplot.pro)

## TIMEBAR

[Previous Routine] [Next Routine] [List of Routines]

    NAME:                  timebar
    PURPOSE:
                           plot vertical (or horizontal) lines on TPLOTs at specified times (or values)
    CALLING SEQUENCE:      timebar,t
    INPUTS:                t: dblarr of times at which to draw vertical lines,
                           seconds since Jan, 1, 1970.  (Or a single datavalue at which to draw a horizontal
                           line in units of the TPLOT variable named in VARNAME).
    KEYWORD PARAMETERS:
          DATABAR:    Set to plot horizontal lines.  *** Must set VARNAME also (for the time being) ***.
          COLOR:      byte or bytarr of color values
          LINESTYLE:  int or intarr of linestyles
          THICK:      int or intarr of line thicknesses
       for any of the above keywords, a scalar input will apply to all times
          VERBOSE: print more error messages; useful for debugging
          VARNAME: TPLOT variable name or index indicating panel in which to plot bar
          BETWEEN: array of two TPLOT variable names indicating
               between which two panels to plot timebar
                           TRANSIENT:  timebar,t,/transient called once plots a
               timebar. Called twice, it deletes the timebar.
                                    Note:  1) all other keywords except VERBOSE
                                    be the same for both calls. 2) COLOR will most
                                    likely not come out what you ask for, but
                                    since it's transient anyway, shouldn't matter.
    OUTPUTS:
    OPTIONAL OUTPUTS:
    COMMON BLOCKS:         tplot_com
    EXAMPLE:
          load_3dp_data,'95-01-01',2 & get_pmom
          tplot,['Np','Tp','Vp']
          t=time_double('95-01-01/1:12')
          timebar,t             ;put a white line at 1:12 am, Jan, 1, 1995
          ctime,t1,t2           ;select two times from the plot
          timebar,[t1,t2],color=!d.n_colors-2 ;plot them in red
    SEE ALSO:
      "CTIME","TPLOT"
    CREATED BY:            Frank V. Marcoline
    LAST MODIFICATION:     2009/05/14, W.M.Feuerstein
    FILE:                  timebar.pro
    VERSION:               1.91

(See ssl_general/tplot/timebar.pro)

## TIMERANGE

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:  timerange
    PURPOSE:	To get timespan from tplot_com or by using timespan, if
    		tplot time range not set.
    INPUT:
    	tr (optional)
    KEYWORDS:
    	CURRENT  Set to 1 to get the current time range as set by tlimit.
    RETURNS:
        two element time range vector.  (double)

    SEE ALSO:	"timespan"
    REPLACES:  "get_timespan"

    CREATED BY:	Davin Larson
     $LastChangedBy: kenb-mac $
     $LastChangedDate: 2007-06-05 08:30:27 -0700 (Tue, 05 Jun 2007) $
     $LastChangedRevision: 731 $
     $URL: svn+ssh:$

(See ssl_general/tplot/timerange.pro)

## TIMESPAN

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  timespan, t1, dt
    PURPOSE:
      Define a time span for the "tplot" routine.
    INPUTS:
        t1:  starting time (seconds since 1970 or string)
        dt:  duration of time span  (DAYS is default)
    KEYWORDS:   set one of the following:
      SECONDS
      MINUTES
      HOURS
      DAYS     (default)

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)timespan.pro	1.14 97/06/04

(See ssl_general/tplot/timespan.pro)

## TLIMIT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   tlimit,t1,t2
    PURPOSE:  defines time range for "tplot"
    	   (tplot must be called first)
    INPUTS:  Starting and Ending times.  These can be string, double (seconds
       since 1970), or hours since refdate.  If no Input is given then the cursor
       is used to select times from the most recent time plot.
    KEYWORD:
    	REFDATE:   new TPLOT reference data in seconds (double).
    	FULL:	   use full limits.
    	LAST:	   use the last plot's limits.
    	ZOOM:	   set to a value between 0 (no range in times) and 1 (full
    		   time range) to zoom in on the center of the time range.
    	WINDOW:    window in which to plot new time range.
    	OLD_TVARS: use this to pass an existing tplot_vars structure and
    		   override the one in the tplot_com common block.  This
    		   can be used to select which window and set of data to
    		   define a time range in.
    	NEW_TVARS: returns the tplot_vars structure created when plotting
    		   the newly defined time range.
    	DAYS, HOURS, MINUTES, SECONDS: passed to "ctime" for cursor input of
    		   time range.
           SILENT     If true, don't print output with x/y values under cursor.
                      Default value for Windows is silent=1, default for others is
                      silent = 0.
    EXAMPLES:
       tlimit                     ; Use the cursor
       tlimit,'12:30','14:30'
       tlimit, 12.5, 14.5
       tlimit,t,t+3600            ; t must be set previously
       tlimit,/FULL               ; full limits
       tlimit,/LAST               ; previous limits

    CREATED BY:	Davin Larson
    FILE:  tlimit.pro
    VERSION:  1.26
    LAST MODIFICATION:  98/08/06

(See ssl_general/tplot/tlimit.pro)

## TNAMES

[Previous Routine] [Next Routine] [List of Routines]

    FUNCTION:              names=tnames(s [,n])
    PURPOSE:
                           Returns an array of "TPLOT" names
                           This routine accepts wildcard characters.
    CALLING SEQUENCE:      nam=tnames('wi*') ; match tplot variables that start with 'wi'
    INPUTS:                s: a match string (ie.  '*B3*' )
    OPTIONAL INPUTS:       s: an array of indices for tplot variables
    KEYWORD PARAMETERS:
     INDEX:          named variable in which the  the indices are returned.
     TRANGE:         named variable in which the  start / end times are returned
     CREATE_TIME     named variable in which the  creation time is stored.
     TPLOT:          if set then returns only the variables plotted in the most recent call to TPLOT
     DATAQUANTS:     if set then it returns the entire array of current stored TPLOT data quantities.

    OUTPUTS:               a data name or array of data names
    OTHER OUTPUTS:         n: the number of matched strings
    COMMON BLOCKS:         tplot_com
    SIDE EFFECTS:          none
    EXAMPLE:               print,tnames('*wi*')
    VERSION:   1.8  @(#)tnames.pro  1.8 02/11/01
    copied from iton.pro
    CREATED BY:            Davin Larson   Feb 1999

(See ssl_general/tplot/tnames.pro)

## TPLOT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:   tplot  [,datanames]
    PURPOSE:
       Creates a time series plot of user defined quantities.
    INPUT:
       datanames: A string of space separated datanames.
                 wildcard expansion is supported.
                 if datanames is not supplied then the last values are used.
                 Each name should be associated with a data quantity.
                 (see the "STORE_DATA" and "GET_DATA" routines.)
                 Alternatively datanames can be an array of integers or strings.
                 run "TPLOT_NAMES" to show the current numbering.

    KEYWORDS:
       TITLE:    A string to be used for the title. Remembered for future plots.
       ADD_VAR:  Set this variable to add datanames to the previous plot.  If set
             to 1, the new panels will appear at the top (position 1) of the
             plot.  If set to 2, they will be inserted directly after the
             first panel and so on.  Set this to a value greater than the
             existing number of panels in your tplot window to add panels to
                 the bottom of the plot.
       LASTVAR:  Set this variable to plot the previous variables plotted in a
             TPLOT window.
       PICK:     Set this keyword to choose new order of plot panels
                 using the mouse.
       WINDOW:   Window to be used for all time plots.  If set to -1, then the
                 current window is used.
       VAR_LABEL:  String [array]; Variable(s) used for putting labels along
         the bottom. This allows quantities such as altitude to be labeled.
       VERSION:  Must be 1,2,3, or 4 (3 is default)  Uses a different labeling
       scheme.  Version 4 is for rocket-type time scales.
       OVERPLOT: Will not erase the previous screen if set.
       NAMES:    The names of the tplot variables that are plotted.
       NOCOLOR:  Set this to produce plot without color.
       TRANGE:   Time range for tplot.
       NEW_TVARS:  Returns the tplot_vars structure for the plot created. Set
             aside the structure so that it may be restored using the
                 OLD_TVARS keyword later. This structure includes information
                 about various TPLOT options and settings and can be used to
                 recreates a plot.
       OLD_TVARS:  Use this to pass an existing tplot_vars structure to
         override the one in the tplot_com common block.
       HELP:     Set this to print the contents of the tplot_vars.options
             (user-defined options) structure.

    RESTRICTIONS:
       Some data must be loaded prior to trying to plot it.  Try running
       "_GET_EXAMPLE_DAT" for a test.

    EXAMPLES:  (assumes "_GET_EXAMPLE_DAT" has been run)
       tplot,'amp slp flx2' ;Plots the named quantities
       tplot,'flx1',/ADD          ;Add the quantity 'flx1'.
       tplot                      ;Re-plot the last variables.
       tplot,var_label=['alt']   ;Put Distance labels at the bottom.
           For a long list of examples see "_TPLOT_EXAMPLE"

    OTHER RELATED ROUTINES:
       Examples of most usages of TPLOT and related routines are in
          the crib sheet: "_TPLOT_EXAMPLE"
       Use "TNAMES" function to return an array of current names.
       Use "TPLOT_NAMES" to print a list of acceptable names to plot.
       Use "TPLOT_OPTIONS" for setting various global options.
       Plot limits can be set with the "YLIM" procedure.
       Spectrogram limits can be set with the "ZLIM" procedure.
       Time limits can be set with the "TLIMIT" procedure.
       The "OPTIONS" procedure can be used to set all IDL
          plotting keyword parameters (i.e. psym, color, linestyle, etc) as well
          as some keywords that are specific to tplot (i.e. panel_size, labels,
          etc.)  For example, to change the relative panel width for the quantity
          'slp', run the following:
                OPTIONS,'slp','panel_size',1.5
       TPLOT calls the routine "SPECPLOT" to make spectrograms and
          calls "MPLOT" to make the line plots. See these routines to determine
          what other options are available.
       Use "GET_DATA" to retrieve the data structure (or
          limit structure) associated with a TPLOT quantity.
       Use "STORE_DATA" to create new TPLOT quantities to plot.
       The routine "DATA_CUT" can be used to extract interpolated data.
       The routine "TSAMPLE" can also be used to extract data.
       Time stamping is performed with the routine "TIME_STAMP".
       Use "CTIME" or "GETTIME" to obtain time values.
       tplot variables can be stored in files using "TPLOT_SAVE" and loaded
          again using "TPLOT_RESTORE"

    CREATED BY:    Davin Larson  June 1995

    QUESTIONS?
       See the archives at:  http://lists.ssl.berkeley.edu/mailman/listinfo/tplot
    Still have questions:
       Send e-mail to:  tplot@ssl.berkeley.edu    someone might answer!

    FILE:  tplot.pro
    VERSION:  1.97
    LAST MODIFICATION:  02/11/01
     $LastChangedBy: davin-win $
     $LastChangedDate: 2009-09-03 16:28:21 -0700 (Thu, 03 Sep 2009) $
     $LastChangedRevision: 6683 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplot.pro $

(See ssl_general/tplot/tplot.pro)

## TPLOT3D

[Previous Routine] [Next Routine] [List of Routines]

     Procedure: tplot3d

     Purpose: Takes an array of 3-d(Nx3 or MxNx3) vectors or tplot variable
              holding these vectors and generates a 3d plot of them

    Example: tplotxy,'thb_state_pos'
             tplotxy,'thb_state_pos',/overplot

     Inputs: vectors: an Nx3 or MxNx3 list of vectors or the name of a tplot
             variable that stores an Nx3 or MxNx3 list of vectors

     Keywords:
             overplot(optional): overplot on an already existing 3d plot

             noreset(optional): iplot changes some internal settings,
             this procedure resets them to themis defaults, if you do not
             want this done then set this option.

             also takes all the other options that iplot takes

     $LastChangedBy: pcruce $
     $LastChangedDate: 2008-02-06 14:24:05 -0800 (Wed, 06 Feb 2008) $
     $LastChangedRevision: 2355 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplot3d.pro $

(See ssl_general/tplot/tplot3d.pro)

## TPLOTXY

[Previous Routine] [Next Routine] [List of Routines]

     Procedure: tplotxy

     Purpose: Takes a tplot variable containing an array of 3-d(Nx3)
              vectors or and plots them using 2-d plots to help visualize
              them. It can also take a tplot variable storing an
              MxNx3 array.  This represents N times and M different
              sets of 3-d vectors. (For example M different magnetic
              field lines during some interval)

             This routine will check the current timespan and only
             display values within the specified range(this entails
             clipping on the N dimension).  If no range is specified
             by argument or timespan it will use the entire interval.

             If the noisotropic keyword is not used the plot will be made
             so that one unit of x is the same length on the screen as
             one unit of y

             Can also accept an Nx2 or an MxNx2 element array(in a tvar)...if this
             is done the versus argument should not use a custom
             designation or the z-axis, as it assumes 2-d vectors are in
             the x-y plane, and thus will distort the vectors upon projection.

             plotxy/tplotxy plots can be interleaved on the same window
             with plotxyz plots

             Calling tplotxy with no arguments to redraw the entire
             window(including plotxyz plots)

             ***************************************************

             Using custom axes:  If you use two vectors to define custom
             axes, the procedure will generate a plot of the data vectors
             projected into a plane defined by the span of the two custom
             vectors.  The x-axis will be the first vector, the y axis
             will be the second vector.  This means that if the custom
             vectors are not orthogonal the plot will show a distortion.
             You can think of this as plotting along a plane that slices
             though the 3-d space.

             ********************************
             Plot windows and panels:
             using, /overplot,/addpanel,/noisotropic and multi=

             To put multiple panels in a window first call
             plotxy with the multi keyword.  It will either
             plot in which ever window is your current one, or
             create a new one if no window exists or if you
             request the use of a nonexistent window.

             During this first call you may want to specify things
             like wtitle,xsize,ysize,window...in addition to your normal
             plotting options.

             multi specifies the plot window panel layout.
             So if you set multi='3,2' you will get 6 plots
             in your window with a layout like:
               -------
               |x x x|
               |x x x|
               -------

             Each panel will have dimensions x number of pixels = 1/3 *
             xsize of window and y number of pixels = 1/2 * ysize of window.

             Your first call should also specify the layout of your
             first panel. To add to that panel use the /overplot keyword.

             When you use the /add keyword the program will move on to
             the next panel within the plot window and you should add
             options to specify the layout of that panel.

             An entire plot window must be filled in sequence, if you move
             on to a new window you will not be able to go back to the
             previous window without restarting.

             If you set the xmargin or ymargin keyword the margin will be
             relative to the overall size of that panel. When using the
             not using the noisotropic keyword the procedure will make
             each axis vary over the same range AND make the
             largest possible square window given the size of the panel
             and the sizes of the margins you have provided, if possible.
             In some cases when ranges are set explictly the plot must
             be rectangular.

             This program will also set some options using the dlimits
             and limits of the tplot variable, if they have not already
             been explicitly set by the user.

             If the tag 'colorsxy' is set to a color index in either
             the limits or dlimits of a tplot variable, it will be read
             to set a default line color.

             The 'ytitle' tag from a dlimits or limits structure will
             be used as the plot title

             If the 'ysubtitle' tag is set, it will be used as the units
             for the xtitle and ytitle of the tplotxy panel

             If the 'labels' tag is set, then the appropriate dimension
             lable will be used. For example 'Bx','By','Bz' labels for
             FGM will be used if plotted

             NOTE TO PROGRAMMERS:
               Information about plotting for plotxy is stored in
               the global variable !TPLOTXY, this includes
               information about the layout of the plot window
               which panel it is currently working on, and the
               sequence of commands used to generate current plot window
               so that it can regenerate the plotwindow when called
               with no arguments. This variable also stores information
               used by the plotxyz function so spectrographic xyz plots
               can be interleaved with xy line plots.

    Example: tplotxy,'thb_state_pos'
             tplotxy,'thb_state_pos',versus='yzr'
             tplotxy,'thb_state_pos',versus='cc',custom=transpose([[1,1,0],[0,0,1]])
             tplotxy,'thb_state_pos',versus='xryz',xrange=[0,10],yrange=[0,10]

     NOTE: This procedure can accept arguments that are documented only
     in plotxy.  It will pass them through when it calls that routine
     using keyword inheritance.  So if you can't find a useful option
     here, I would recommend looking there.

     Inputs: vectors: The name of a tplot variable that stores the list of vectors

             versus(optional): specify the projection to be used, can be
             'xx','xy','xz','yx','yy','yz','zx','zy','zz','cc' you can also
             follow a letter with an 'r' to reverse the axis(goes from
             positive to negative instead of from negative to positive)
             if you specify 'cc','crc'...that indicate you want to use a
             custom projection
             example: 'xry' will be an xy plot with the maximum x value
             listed on the left and the minimum on the right
             (default:'xy')

             custom(optional): set this variable to a
             2x3 matrix whose columns define a plane in 3-d space, to define a
             custom projection. In other words the 2-d plot will be a
             plot of the vectors passed into tplotxy when they are
             projected into a plane defined by
             span(custom[0,*],custom[1,*]). (span is defined as the set
             of all the linear combinations of two vectors, or
             span(x,y) = {mx+ny:m = element of the reals, n = element of
             the reals} The vectors used to define this plane will be
             relative to whatever 3-d coordinate system the input vector
             data is in.
             So if the call:
             tplotxy,'somedata',versus='cc',custom=transpose([[1,1,0],[0,0,1])
             is made, the plot generated will be of the vectors closest
             to the data vectors that are inside a vertical plane whose
             intersection with the x-y plane forms a line y=x.
             tplotxy,'somedata',versus='cc',custom=transpose([[1,0,0],[0,1,0])
             is effectively the same as:
             tplotxy,'somedata',versus='xy'

             overplot(optional): set this keyword if you want to plot
             on the last plot and panel that you plotted on

             addpanel(optional): set this keyword if you want to plot on a new
             panel within the same plot window as where you last
             plotted. This will go to the next column first and if it is
             at the end of a row, to the next row.

             multi(optional): set this keyword to a string that
             specifies the layout of panels within a plotwindow.  Set
             this keyword only the first time you call tplotxy for a
             given plotwindow.  Each time you set it, the previous
             contents of the window will be erased. You can separate
             the two elements with a variety of different delimiters
             The first element is cols left to right, the second rows
             top to bottom. Append an 'r' to the elements to have it
             reverse the direction of panel application
             Examples:  multi= '2 3'
                        multi= '5r,7'
                        multi=' 1:6r'
                         .....
             noisotropic(optional): set this keyword if you don't want the
             scaling of both axes to be the same and the space to
             be perspective corrected so that a cm of y unit takes
             up the same space on the screen as a cm of x unit

             memsave(optional): set this keyword to request command
             copies not be saved and redraws be done without maintaining
             square isotropic plots.  Setting this option can potentially
             save quite a lot of memory.

             linestyle(optional):set this to change the linestyle used
             0 = default,1=dotted=,2=dashed,3=dash dot,4=dash dot
             dot,5=long dashes

             xrange(optional): set this to a 2 element array to specify
             the min and max for the first axis(x) of the 2-d plot

             yrange(optional): set this to a 2 element array to specify
             the min and max for the second axis(y) of the 2-d plot

             xmargin(optional):set this to a 2 element array to specify
             the left and right margin for the plot
             unlike tplot & plot this is specified in terms of the
             proportion of available space given the plot layout not
             number of characters.  This also specified for each plot
             in a panel individually, no for the whole panel to allow
             the user more control over layout.

             ymargin(optional):set this to a 2 element array to specify
             the bottom and top margin for the plot
             unlike tplot & plot this is specified in terms of the
             proportion of available space given the plot layout not
             number of characters.  This also specified for each plot
             in a panel individually, no for the whole panel to allow
             the user more control over layout.

             pstart(optional): set this keyword to a number representing
             the symbol you would like to start lines with. (This works
             like the idl psym keyword, but only for the first symbol
             in a line being plotted)

             pstop(optional): set this keyword to a number representing
             the symbol you would like to end lines with. (This works
             like the idl psym keyword, but only for the last symbol
             in a line being plotted)

             psym(optional): use this to plot using a symbol
             rather than a line.

             symsize(optional): specify the size of the start and end
             symbol, or psym (default:1.0)

             WARNING!!! Using any of the 4 windowing options
             below will interfere with the creation of postscript
             graphics

             window(optional):specify the window for
             output.  (default:current)

             xsize(optional):specify the xsize of the window in
             pixels(default: current)

             ysize(optional):specify the ysize of the window in pixels
             (default: current)

             wtitle(optional):the title you would like the window to have

             usetrange(optional):set this keyword(ie /usetrange) if you want it
             to prompt for a timerange if one is not provided by timespan

             notrange(optional):set this keyword(ie /notrange) if you
             want it to ignore the time range and use the entire sequence
             of values regardless.

             sort(optional): set this keyword(ie /sort) if you want it
             to sort points on time

             colors(optional): set this keyword to override the color
             information stored in the limits or dlimits of the tplot
             variable, if the tplot variable contains an Nx3 array
             it should contain a single element, if it contains an
             MxNx3 array it should contain one or M colors. If the
             tplot variable contains wildcards or is composite
             it will be ignored.

             xlog(optional): set the x scale to be logarithmic

             ylog(optional): set the y scale to be logarithmic

             xtitle(optional): set the xtitle for the plot

             ytitle(optional): set the ytitle for the plot

             grid(optional): set this to 1 to have the procedure
             generate a grid rather than normal tickmarks

             markends(optional): set this if you want to mark the very
             edges of your plot axis with data labels. This means the
             numerical values of the maximum x tick,minimum x tick,
             maximum y tick, and minimum y tick will be marked.Note that
             an extra blank page may be created in any postscripts you
             generate when using this option.

             reverse_time(optional): set to have the function reverse
             the data according to the time axis,this will only
             really change which end is marked as stop and which as start

             units(optional): set this if you want this unit label
             appended to both axis titles.(This will be ignored if
             you set the xtitle or ytitle explictly)

             xtick_get,ytick_get: These behave exactly as the plot
             command versions, but they had to be identified explictly
             to ensure they would be passed through correctly.

             This procedure also takes normal idl keywords that effect
             plotting style

      SEE ALSO:
        plotxyz,plotxy,thm_crib_tplotxy,thm_crib_plotxy,thm_crib_plotxyz,
        plotxylib,plotxyvec

     $LastChangedBy: pcruce $
     $LastChangedDate: 2008-07-28 11:52:58 -0700 (Mon, 28 Jul 2008) $
     $LastChangedRevision: 3310 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/ssl_general/trunk/tplot/tplotxy.pro $

(See ssl_general/tplot/tplotxy.pro)

## TPLOT_COM

[Previous Routine] [Next Routine] [List of Routines]

    COMMON BLOCK:  tplot_com

    WARNING!  THIS COMMON BLOCK IS SUBJECT TO CHANGE!  DON'T BE TOO SURPRISED
       IF VARIABLES ARE ADDED, CHANGED, OR DISAPPEAR!

       data_quants:  structure array,  handle to location of ALL data.
       tplot_vars:   structure containing all tplot window and plotting
    			 information.
    SEE ALSO:   "tplot_options" and "tplot"
    MODIFIED BY:	Peter Schroeder
    CREATED BY:	Davin Larson
    LAST MODIFICATION: 01/10/08
    VERSION: @(#)tplot_com.pro	1.21

(See ssl_general/tplot/tplot_com.pro)

## TPLOT_FILE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  tplot_file , name [,filename]
    PURPOSE:
       OBSOLETE PROCEDURE!  Use "TPLOT_SAVE" and "TPLOT_RESTORE" instead.
       Store tplot data in a file.
      gets the data, limits and name handle associated with a name string
       This procedure is used by the tplot routines.
    INPUT:
       name    (string, tplot handle)
       filename:  file name
    KEYWORDS:
       SAVE:   set to save files.
       RESTORE:set to restore files.
    SEE ALSO:      "STORE_DATA", "GET_DATA", "TPLOT"

    CREATED BY:    Davin Larson
    LAST MODIFICATION:     tplot_file.pro   98/08/06

(See ssl_general/tplot/tplot_file.pro)

## TPLOT_KEYS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:	tplot_keys
    PURPOSE:
    	Sets up function keys on user keyboard to perform frequent "tplot"
    	functions and procedures.  Definitions will be explained when run.
    INPUT:	(none)
    OUTPUT: (none)
    CREATED BY:	Davin Larson
    LAST MODIFIED:	@(#)tplot_keys.pro	1.5 02/11/22

(See ssl_general/tplot/tplot_keys.pro)

## TPLOT_NAMES

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  tplot_names [, datanames ]
    PURPOSE:
       Lists current stored data names that can be plotted with the TPLOT routines.
    INPUT:   (Optional)  An string (or array of strings) to be displayed
             The strings may contain wildcard characters.
    Optional array of strings.  Each string should be associated with a data
           quantity.  (see the "store_data" and "get_data" routines)
    KEYWORDS:
      TIME_RANGE:  Set this keyword to print out the time range for each quantity.
      CREATE_TIME: Set to print creation time.
      VERBOSE:     Set this keyword to print out more info on the data structures
      NAMES:       Named variable in which the array of valid data names is returned.
      ASORT:       Set to sort by name.
      TSORT:       Set to sort by creation time.
      CURRENT:     Set to display only names in last call to tplot.
    EXAMPLE
       tplot_names,'*3dp*'   ; display all names with '3dp' in the name
    CREATED BY:	Davin Larson
    SEE ALSO:   "TNAMES"  "TPLOT"
    MODS:     Accepts wildcards
    LAST MODIFICATION:	@(#)tplot_names.pro	1.19 01/10/08

(See ssl_general/tplot/tplot_names.pro)

## TPLOT_OPTIONS

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  tplot_options [,string,value]
    NAME:
      tplot_options
    PURPOSE:
      Sets global options for the "tplot" routine.
    INPUTS:
       string: 	option to be set.
       value:	value to be given the option.
    KEYWORDS:
       HELP:      Display current options structure.
       VAR_LABEL:   String [array], variable[s] to be used for plot labels.
       FULL_TRANGE: 2 element double array specifying the full time range.
       TRANGE:      2 element double array specifying the current time range.
       DATANAMES:  String containing names of variable to plot
       REFDATE:    Reference date.  String with format: 'YYYY-MM-DD'.
             This reference date is used with the gettime subroutine.
       WINDOW:     Window to be used for all time plots. (-1 specifies current
           window.
       VERSION:    plot label version. (1 or 2 or 3)
       TITLE:	string used for the tplot title
       OPTIONS:	tplot options structure to be passed to replace the current
    		structure.
       GET_OPTIONS:returns the new tplot options structure.
    EXAMPLES:
       tplot_options,'ynozero',1          ; set all panels to YNOZERO=1
       tplot_options,'title','My Data'    ; Set title
       tplot_options,'xmargin',[10,10]    ; Set left/right margins to 10 characters
       tplot_options,'ymargin',[4,2]      ; Set top/bottom margins to 4/2 lines
       tplot_options,'position',[.25,.25,.75,.75]  ; Set plot position (normal coord)
       tplot_options,'wshow',1             ; de-iconify window with each tplot
       tplot_options,'version',3          ; Sets the best time ticks possible
       tplot_options,'window',0           ; Makes tplot always use window 0
       tplot_options,/help                ; Display current options
       tplot_options,get_options=opt      ; get option structure in the variable opt.
       tplot_options,'ygap',0.0   ;eliminate the vertical spacing between panels

    SEE ALSO:  "TPLOT", "OPTIONS", "TPLOT_COM"
    CREATED BY:  Davin Larson   95/08/29
    LAST MODIFICATION: 01/10/08
    VERSION: @(#)tplot_options.pro	1.16

(See ssl_general/tplot/tplot_options.pro)

## TPLOT_PANEL

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: tplot_panel [,time,y]
    INPUTS: (optional)
       time:      dblarr of time values associated with a variable to overplot
    	       in a designated "tplot" panel.
       y:	       array of variable values to be plotted.
    KEYWORDS:
       VARIABLE:  (string) name of previously plotted tplot variable.
       OPLOTVAR:  Data that will be plotted on top of the selected panel
       DELTATIME: Named variable in which time offset is returned.
       PANEL:     Returns panel number of designated tplot variable.
       PSYM:      Sets the IDL plot PSYM value for overplot data.
    PURPOSE:
      Sets the graphics parameters to the specified tplot panel.
      The time offset is returned through the optional keyword DELTATIME.

    LAST MODIFICATION:	@(#)tplot_panel.pro	1.9 02/04/17

(See ssl_general/tplot/tplot_panel.pro)

## TPLOT_POSITIONS

[Previous Routine] [Next Routine] [List of Routines]

    NAME:               tplot_positions
    PURPOSE:
                        Return a set of plot positions for tplot.
                        Given the number of plots, the margins, and the relative
                        sizes of the plot panels, determine the plot coordinates.
                        The positions are the device coordinates of the plot, not
                        of the plot region. (See IDL User's Guide Chapter 14.10)

                        If the margins are not specifically set, first the limit
                        structures are checked, then ![x,y].margin are checked,
                        then some defaults are used.

    CALLING SEQUENCE:   positions = tplot_positions(panels)

    INPUTS:             panels: the number of plots, an integer

    KEYWORD PARAMETERS: xm,xom,ym,yom: the x and y inner and outer margins
                               these are two element arrays. ![x,y].margin
     			    and ![x,y].omargin are used if left off
                        sizes: fltarr(panels) containing the relative plot sizes

    OUTPUTS:            positions = fltarr(4,n_elements(panels))
                               positions(*,i) is the ith plot position
                               (x0,y0,x1,y1)
    EXAMPLE:

    LAST MODIFICATION:  @(#)tplot_positions.pro	1.2 97/05/30

(See ssl_general/tplot/tplot_positions.pro)

## TPLOT_QUANT__DEFINE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: tplot_quant__define

     This procedure defines the tplot_quant structure.

(See ssl_general/tplot/tplot_quant__define.pro)

## TPLOT_RESTORE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  tplot_restore ,filenames=filenames, all=all, sort=sort
    PURPOSE:
       Restores tplot data, limits, name handles, options, and settings.
    INPUT:
    KEYWORDS:
       filenames:  file name or array of filenames to restore.  If
                   no file name is chosen and the all keyword is not set,
    		tplot_restore will look for and restore a file called
    		saved.tplot.
       all: restore all *.tplot files in current directory
       append: append saved data to existing tplot variables
       sort: sort data by time after loading in
       get_tvars: load tplot_vars structure (the structure containing tplot
    		options and settings even if such a structure already exists
    		in the current session.  The default is to only load these
    		if no such structure currently exists in the session.
       restored_varnames=the tplot variable names for the restored data
    SEE ALSO:      "TPLOT_SAVE","STORE_DATA", "GET_DATA", "TPLOT"

    CREATED BY:    Peter Schroeder
    LAST MODIFICATION:     Added restore_varnames, 19-jun-2007, jmm
                           Changed the obsolete IDL routine str_sep to
                             strsplit. Also added additional output
    						  text.                   21-may-2008, cg
                           Removed additional output text - Use dprint,debug=3  to restore text.   Nov 2008

(See ssl_general/tplot/tplot_restore.pro)

## TPLOT_SAVE

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  tplot_save , name ,filename=filename, limits=limits
    PURPOSE:
       Store tplot data in a file.
    INPUT:
       name:   (optional) tplot handle or array of tplot handles to save.  If
    	    no name is supplied, tplot_save will save all defined tplot
    	    handles.
    KEYWORDS:
       filename:  file name in which to save data.  A default suffix of .tplot or
    	       .lim will be added to this depending on whether the limits
                  keyword has been set.  If not given, the default file name is
    	       saved.tplot or saved.lim.
       limits:    will save only limits structures.  No data will be saved.
    SEE ALSO:      "STORE_DATA", "GET_DATA", "TPLOT", "TPLOT_RESTORE"

    CREATED BY:    Peter Schroeder
    LAST MODIFICATION:     tplot_save.pro   97/05/14

(See ssl_general/tplot/tplot_save.pro)

## TPLOT_SORT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  tplot_sort,name
    PURPOSE:
       Sorts tplot data by time (or x).
    INPUT:
       name: name of tplot variable to be sorted.
    KEYWORDS:

    CREATED BY:    Peter Schroeder
    LAST MODIFICATION:     %W% %E%

(See ssl_general/tplot/tplot_sort.pro)

## XLIM

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  xlim,lim, [min,max, [log]]
    PURPOSE:
       To set plotting limits for plotting routines.
       This procedure will add the tags 'xrange', 'xstyle' and 'xlog' to the
       structure lim.  This structure can be used in other plotting routines such
       as "SPEC3D".
    INPUTS:
       lim:     structure to be added to.  (Created if non-existent)
       min:     min value of range
       max:     max value of range
    KEYWORDS:
       LOG:  (optional)  0: linear,   1: log
    See also:  "OPTIONS", "YLIM", "ZLIM"
    Typical usage:
       xlim,lim,-20,100      ; create a variable called lim that can be passed to
                             ; a plotting routine such as "SPEC3D".

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)xlim.pro	1.9 02/04/17

(See ssl_general/tplot/xlim.pro)

## YLIM

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  ylim [, str [ , min, max, [ LOG=log ] ] ]
    PURPOSE:
      Sets y-axis limits for plotting routines.
      Adds the tags 'yrange', 'ystyle' and 'ylog' to the structure str, or to the
      limit structure associated with the string str.
    INPUTS:
       str is a:
          CASE 1: structure (or zero or non-existent)
             Structure to be added to.  (Created if non-existent)
          CASE 2: string  (handle associated with a "TPLOT" variable)
             The limits structure associated with this string is used.  This
             structure can be retrieved with the "GET_DATA" procedure.
       min:     min value of yrange
       max:     max value of yrange
    KEYWORDS:
       LOG:   (optional)  0: linear,   1: log
       DEFAULT:   Sets default tplot limits.
       STYLE:  value to set the IDL plot YSTYLE keyword
    Typical usage:
       ylim,lim,-20,100   ; create (or add to) the structure lim

       ylim,'Ne',.01,100,1  ; Change limits of the "TPLOT" variable 'Ne'.

    NO INPUTS:
       ylim                 ; Set "TPLOT" limits using the cursor.

    SEE ALSO:  "OPTIONS", "TLIMIT", "XLIM", "ZLIM"
    CREATED BY:	Davin Larson
    VERSION: ylim.pro
    LAST MODIFICATION: 01/06/25

(See ssl_general/tplot/ylim.pro)

## YLIMIT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: ylimit
    PURPOSE:  Interactive setting of y-limits for the "TPLOT" procedure.

    SEE ALSO:	"YLIM", a noninteractive version which calls this routine.

    NOTES:  This procedure will probably be made obsolete by embedding it in.
        "YLIM".
            Run "TPLOT" prior to using this procedure.

    CREATED BY:	Davin Larson
    FILE: ylimit.pro
    VERSION:  1.11
    LAST MODIFICATION: 98/08/06

(See ssl_general/tplot/ylimit.pro)

## ZLIM

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE:  zlim,lim, [min,max, [log]]
    PURPOSE:
       To set plotting limits for plotting routines.
       This procedure will add the tags 'zrange', 'zstyle' and 'xlog' to the
       structure lim.  This structure can be used in other plotting routines.
    INPUTS:
       lim:     structure to be added to.  (Created if non-existent)
       min:     min value of range
       max:     max value of range
       log:  (optional)  0: linear,   1: log
    If lim is a string then the limit structure associated with that "TPLOT"
       variable is modified.
    See also:  "OPTIONS", "YLIM", "XLIM", "SPEC"
    Typical usage:
       zlim,'ehspec',1e-2,1e6,1   ; Change color limits of the "TPLOT" variable
                                  ; 'ehspec'.

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)zlim.pro	1.2 02/11/01

(See ssl_general/tplot/zlim.pro)

## _GET_EXAMPLE_DAT

[Previous Routine] [Next Routine] [List of Routines]

    PROCEDURE: _get_example_dat
    NAME:
      _get_example_dat
    PURPOSE:
      A procedure that generates sample data for "TPLOT".
      See the crib sheet: "_tplot_example" for instructions on using this routine.

    CREATED BY:	Davin Larson  96-2-19
    FILE:  _get_example_dat.pro
    VERSION:  1.4
    LAST MODIFICATION:  96/10/14

(See ssl_general/tplot/_get_example_dat.pro)

## _TPLOT_DEMO

[Previous Routine] [Next Routine] [List of Routines]

    DEMONSTRATION OF TPLOT AND RELATED ROUTINES
    PURPOSE:
      A sample crib sheet that explains how to use the "TPLOT" procedure.

    Written by Peter Schroeder 97-9-17

(See ssl_general/tplot/_tplot_demo.pro)

## _TPLOT_EXAMPLE

[Previous Routine] [List of Routines]

    CRIB SHEET EXAMPLE
    PURPOSE:
      A sample crib sheet that explains how to use the "TPLOT" procedure.

    Written by Davin Larson 96-2-19

(See ssl_general/tplot/_tplot_example.pro)