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

Last modified: Wed Apr 7 16:22:55 1999.

[back to main]

# Directory Listing of Routines

# /disks/aeolus/disk1/wind/source/idl/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.
- COPY_DATA
- CROSSHAIRS
  Display crosshairs on the plot window, display the data coordinates of the
- CTIME[1]
- CTIME[2]
  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.
- PMPLOT
- SCAT_PLOT
  Produces a scatter plot of selected tplot variables.
- SPECPLOT
  Creates a spectrogram plot.
- 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 lines on tplots at specified times
- 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.
- 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_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).
- 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/3dp_ref_man.html#_TPLOT_EXAMPLE">_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 1.
        LIMITS: TPLOT limits structure corresponding to the variable plotted.
        DATA: TPLOT data structure corresponding to the variable plotted.

(See /disks/aeolus/disk1/wind/source/idl/general/tplot/bitplot.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:	"TPLOT/3dp_ref_man.html#GET_DATA">GET_DATA",
    		"TPLOT/3dp_ref_man.html#STORE_DATA">STORE_DATA"

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

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/general/tplot/crosshairs.pro)

## CTIME[1]

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

    PROCEDURE:     ctime_get_exact_data
    PURPOSE:       Get a data structure for ctime.  if var is a string or a strarr,
                   create a structure of data structures.
                   Get the new values for hx and hy, the crosshairs position.
                   Also check the spec option.
                   ctime need never see the actual data structures.
    		All work is done with pointers to reduce data duplication
                   and increase speed.
    COMMON BLOCKS: CTIME_COMMON
    HISTORY:       First appeared in ctime version 1.29

(See /disks/aeolus/disk1/wind/source/idl/general/tplot/ctime.pro)

## CTIME[2]

[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:  "TPLOT/3dp_ref_man.html#CROSSHAIRS">CROSSHAIRS"

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

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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 "TPLOT/3dp_ref_man.html#GET_DATA">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.17 99/02/18
                    Added the four keywords. (fvm 9/27/95)

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/general/tplot/data_to_normal.pro)

## DEL_DATA

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

    NAME:                  del_data
    PURPOSE:
    			obsolete procedure!  use "TPLOT/3dp_ref_man.html#STORE_DATA">STORE_DATA" instead
                           delete tplot variables
                           del_data calls "TPLOT/3dp_ref_man.html#STORE_DATA">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.3 98/08/02
    CREATED BY:            Frank Marcoline

(See /disks/aeolus/disk1/wind/source/idl/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:	@(#)draw_color_scale.pro	1.14 98/08/03

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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:	"TPLOT/3dp_ref_man.html#STORE_DATA">STORE_DATA", "TPLOT_NAMES", "TPLOT"

    CREATED BY:	Davin Larson
    MODIFICATION BY: 	Peter Schroeder
    LAST MODIFICATION:	@(#)get_data.pro	1.27 98/08/02

(See /disks/aeolus/disk1/wind/source/idl/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:	"TPLOT/3dp_ref_man.html#TIMESPAN">TIMESPAN"

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

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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.39
    LAST MODIFICATION: 99/04/07

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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:
      DEF:  If set, modify the default limits structure rather than the
    	    regular limits structure (tplot variables only).
    SEE ALSO:
      "TPLOT/3dp_ref_man.html#GET_DATA">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 /disks/aeolus/disk1/wind/source/idl/general/tplot/options.pro)

## PMPLOT

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

     PROCECURE:	pmplot

     PURPOSE:	Used for making log y-axis plots.  Preformats data for
    		use with "TPLOT/3dp_ref_man.html#MPLOT">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.2 98/08/03

(See /disks/aeolus/disk1/wind/source/idl/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.12 98/08/03

(See /disks/aeolus/disk1/wind/source/idl/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_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)
       DATA:  A structure that provides an alternate means of supplying
           the data and TPLOT/3dp_ref_man.html#OPTIONS">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 60.
       NO_INTERP:	   If set, do no x or y interpolation.
       IGNORE_NAN:    If nonzero, ignore data points that are not finite.

    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",  "TPLOT/3dp_ref_man.html#OPTIONS">OPTIONS",  "TPLOT", "DRAW_COLOR_SCALE"

(See /disks/aeolus/disk1/wind/source/idl/general/tplot/specplot.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.
        MAX: if set, data values greater than this value will be made NaN.
        NOSTRSW: if set, do not transpose multidimensional data arrays in
    	      structures.  The default is to transpose.

    SEE ALSO:    "TPLOT/3dp_ref_man.html#GET_DATA">GET_DATA", "TPLOT_NAMES",  "TPLOT", "OPTIONS"

    CREATED BY:	Davin Larson
    MODIFIED BY:   Peter Schroeder
    VERSION: 	@(#)store_data.pro	1.37 99/04/07

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/general/tplot/strplot.pro)

## TIMEBAR

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

    NAME:                  timebar
    PURPOSE:
                           plot vertical lines on tplots at specified times
    CALLING SEQUENCE:      timebar,t
    INPUTS:                t: dblarr of times at which to draw vertical lines,
    				seconds since Jan, 1, 1970.
    KEYWORD PARAMETERS:
    			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 indicating panel in which
    				 to plot timebar
    			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:     99/01/21
    FILE:                  1.9
    VERSION:               timebar.pro

(See /disks/aeolus/disk1/wind/source/idl/general/tplot/timebar.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 /disks/aeolus/disk1/wind/source/idl/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.
    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 /disks/aeolus/disk1/wind/source/idl/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:    the indices
    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,iton('*wi*')
    VERSION: 	@(#)tnames.pro	1.4 99/04/07
    copied from iton.pro
    CREATED BY:            Davin Larson   Feb 1999

(See /disks/aeolus/disk1/wind/source/idl/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:  Array of handles. (string names)   Each string should be a
           handle associated with a data quantity.  (see the "STORE_DATA" and
           "GET_DATA" routines.)   Alternatively, datanames can be an array of
           integers, 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 or 3 (3 is default)  Uses a different labeling scheme.
       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.
       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
    FILE:  tplot.pro
    VERSION:  1.88
    LAST MODIFICATION:  99/04/07

(See /disks/aeolus/disk1/wind/source/idl/general/tplot/tplot.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: 97/05/30
    VERSION: @(#)tplot_com.pro	1.20

(See /disks/aeolus/disk1/wind/source/idl/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:      "TPLOT/3dp_ref_man.html#STORE_DATA">STORE_DATA", "GET_DATA", "TPLOT"

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

(See /disks/aeolus/disk1/wind/source/idl/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.2 99/04/07

(See /disks/aeolus/disk1/wind/source/idl/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 "TPLOT/3dp_ref_man.html#STORE_DATA">STORE_DATA" and "GET_DATA" routines)
    KEYWORDS:
      TIME_RANGE: set this keyword to print out the time range for each quantity.
      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.
      SORT:       set this keyword to sort by name
    EXAMPLE
       tplot_names,'*3dp*'   ; display all names with '3dp' in the name
    CREATED BY:	Davin Larson
    SEE ALSO:   "TPLOT/3dp_ref_man.html#TNAMES">TNAMES"  "TPLOT"
    MODS:     Accepts wildcards
    LAST MODIFICATION:	@(#)tplot_names.pro	1.18 99/02/26

(See /disks/aeolus/disk1/wind/source/idl/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 TPLOT/3dp_ref_man.html#OPTIONS">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.
       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.

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

(See /disks/aeolus/disk1/wind/source/idl/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.8 98/08/06

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/general/tplot/tplot_positions.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.
    SEE ALSO:      "TPLOT_SAVE","STORE_DATA", "GET_DATA", "TPLOT"

    CREATED BY:    Peter Schroeder
    LAST MODIFICATION:     @(#)tplot_restore.pro	1.16 98/12/09

(See /disks/aeolus/disk1/wind/source/idl/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:      "TPLOT/3dp_ref_man.html#STORE_DATA">STORE_DATA", "GET_DATA", "TPLOT", "TPLOT_RESTORE"

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

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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:  "TPLOT/3dp_ref_man.html#OPTIONS">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.8 97/06/05

(See /disks/aeolus/disk1/wind/source/idl/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 "TPLOT/3dp_ref_man.html#GET_DATA">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:  "TPLOT/3dp_ref_man.html#OPTIONS">OPTIONS", "TLIMIT", "XLIM", "ZLIM"
    CREATED BY:	Davin Larson
    VERSION: ylim.pro
    LAST MODIFICATION: 98/08/06

(See /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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:  "TPLOT/3dp_ref_man.html#OPTIONS">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.1 96/02/19

(See /disks/aeolus/disk1/wind/source/idl/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/3dp_ref_man.html#_TPLOT_EXAMPLE">_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 /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/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 /disks/aeolus/disk1/wind/source/idl/general/tplot/_tplot_example.pro)