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

Last modified: Fri Oct 3 03:17:47 2025.

# Directory Listing of Routines

# 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.
- AUTO_DOWNSAMPLE
  Downsamples spectral data to fit a given array and interpolates back
- 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
- DANGLE
  Determines the angle between two vectors in tplot. Operates on
- 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
- HIGHLIGHT_TIME_INTERVAL
  for a given tplot variable, click on a time interval to highlight
- ITON
  Convert an index or array of indicies to data names.
- JOIN_VEC
- MAKEGAP
  Creates data gaps (by inserting NaN) when the time between data points is
- MPLOT
  General purpose procedure used to make multi-line plots.
- MPLOT_DOWNSAMPLE_DATA
- MPLOT_SYMLOG
- NORMAL_TO_DATA
- OPTIONS
  Add (or change) an element of a structure.
- PLOTXY
- PLOTXYLIB
- PLOTXYVEC
- PLOTXYZ
- PMPLOT
- SKIP
  Shifts the tplot plotting window forward/backward by a number of
- 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_APPLY_DATABAR
  Plots horizontal lines (databars) for plotted tplot variables, if
- TPLOT_APPLY_PANEL_LABEL
  Applies a label to a panel, given an input structure from
- TPLOT_APPLY_TIMEBAR
  Plots vertical lines (timebars) for plotted tplot variables, if
- TPLOT_COM
- TPLOT_FILE
  OBSOLETE PROCEDURE! Use "TPLOT_SAVE" and "TPLOT_RESTORE" instead.
- TPLOT_FILL_COLOR
  Fills the area under a line in a tplot panel
- TPLOT_FILL_TIME_INTV
  Allow different background color, or other polyfill options for time
- TPLOT_FORCE_MONOTONIC
- TPLOT_KEYS
  Sets up function keys on user keyboard to perform frequent "tplot"
- TPLOT_MULTIAXIS
- TPLOT_MULTIAXIS_KLUDGE
- 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_PANEL_LABEL
  For an input tplot variable, add an attribute, 'panel_label', that will be
- TPLOT_PLOTTER__DEFINE
- TPLOT_POSITIONS
  Return a set of plot positions for tplot.
- TPLOT_QUANT__DEFINE
- TPLOT_QUATERNION_ROTATE
  Rotates a tplot vector using the tplot quaternion. Will create a new tplot variable.
- TPLOT_REMOVE_PANEL
  Remove panel(s) from the current tplot window
- TPLOT_RENAME
  Simple procedure to perform a rename of tplot variable without copy.
- 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).
- TPLOT_VAR_LABELS
  Helper routine for tplot. Formats var_labels
- 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

## AUTO_DOWNSAMPLE

[Next Routine] [List of Routines]

    NAME:
     auto_downsample
    PURPOSE:
     Downsamples spectral data to fit a given array and interpolates back
     to the original. For specplot.pro in cases where there is a time
     variation faster than the time resolution of device pixels. Not
     done if n_elements(x_out) > n_elements(x_in)/2, or if dx_out/dx_in
     is less than 2.0.
    CALLING SEQUENCE:
     spec_out = auto_downsample(spec_in, x_in, x_out)
    INPUT:
     spec_in = a spectrogram, ntimesXnchannels, or nxXny
     x_in = x coordinate for input
     x_out = x coordinate for output, the default is to use this for
             scaling, an interpolate the result back to x_in, the x_out
             coordinates are not overwritten
    KEYWORDS:
     downsample_interp2out = if set, then do not interpolate back to the
                                input coordinates, but to the output coordinates
    HISTORY:
     31-aug-2018, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2019-03-18 11:26:36 -0700 (Mon, 18 Mar 2019) $
     $LastChangedRevision: 26846 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/auto_downsample.pro $

(See general/tplot/auto_downsample.pro)

## BITPLOT

[Previous Routine] [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: ali $
     $LastChangedDate: 2025-06-02 12:18:19 -0700 (Mon, 02 Jun 2025) $
     $LastChangedRevision: 33356 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/bitplot.pro $

(See 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.
     Clean_spikes smooths the data, then compares each data point
     with its smoothed value. Given a threshold value of FT (default of
     10) and a number of smoothing points (default of 3) if the data
     value at any point is greater than FT*nsmooth/(nsmooth-1+FT) times
     the smoothed data point, then the data is reset to NaN. Note that
     the coefficient FT*nsmooth/(nsmooth-1+FT) is between a value of 1.0
     (for FT = 1) and nsmooth (ft -> INF). For the default input the
     coefficient is 2.5.

     AUTHOR: unknown, Probably Frank Marcoline

     KEYWORDS:
      display_object = Object reference to be passed to dprint for output.
      new_name = a new name for the despiked variable, the default is to
      append '_cln' to the input variable name
      nsmooth = the number of data points for smoothing. The default is
      3, will be reset to an odd number prior to smoothing if an even
      number is passed in.
      thresh = a threshold value, the default is 10.0
      use_nn_median = if set, then do not compare the value of the data
      point to a smoothed version of itself, instead compare the value
      data[i] with the median value of the data[i-ns:i+ns], not including the
      value at data[i]
      subtract_average = if set, subtract the average value of the data
      prior to checking for spikes. **This is not recommended for data that
      is defined to be greater than zero, such as a density or particle
      count rate.
      mdeian = passed into the average subtraction. if set, use the
      median for the subtract_average option.
     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
     jmm, 9-mar-2020, Added documentation, fixed absolute value
     calculation so that mixed positive-negative values are handled
     correctly. Also added use_nn_median, subtract_average keywords.
    $LastChangedBy: $
    $LastChangedDate: $
    $LastChangedRevision: $
    $URL: $

(See general/tplot/clean_spikes.pro)

## COPY_DATA

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

    PROCEDURE:  	copy_data,  oldnames, newnames
    PURPOSE:	to copy a data structure
    INPUT:
    	oldnames:	names associated with old data structure
    	newnames:	names 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
    $LastChangedBy: ali $
    $LastChangedDate: 2020-11-05 22:46:13 -0800 (Thu, 05 Nov 2020) $
    $LastChangedRevision: 29332 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/copy_data.pro $

(See 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 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:  0 = print instructions and data point information
                 1 = print instructions but not data point information
                 2 = print nothing
        PANEL:   Set to a named variable to return an array of tplot panel numbers
                 coresponding to the variables points were chosen from.
        XNORM:   Set to a named variable to return an array of normalized x
                 coordinates of each button-click.
        YNORM:   Set to a named variable to return an array of normalized y
                 coordinates of each button-click.
        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.
    Mac Os users:
             You might need to set preferences on your X11 display:
             Within X11 program go to X11 -> preferences -> Windows: check box labeled "Click=through Inactive Windows"
             also:                    X11 -> preferences -> Input:  check box labeled "Emulate three button mouse"
    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 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 general/tplot/cuts.pro)

## DANGLE

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

    PROCEDURE:   dangle
    PURPOSE:
      Determines the angle between two vectors in tplot.  Operates on
      variables in Cartesian coordinates, where X is an N-element time
      array, and Y is an N x 3 array of vectors.  Two time ranges are
      input by the cursor, and the mean vector [<x>, <y>, <z>] is
      determined in each range.  The angle between these two vectors is
      the result.  Only makes sense when the vectors are steady in both
      ranges.

      This routine continues in a loop.  Press the right mouse button
      at any time to exit.

    USAGE:
       dangle, var

    INPUTS:
       var    :     Tplot variable name or number.  The X tag is an
                    N-element time array, and the Y tag is an N x 3
                    array of Cartesian vectors.  Required.

    KEYWORDS:
       RESULT :     Named variable to hold the results (units = deg).

       TBAR:        Plot time bars for the two time ranges.  These are
                    transient and disappear whenever a new set of time
                    ranges is selected or when the routine exits.
                    Default = 1.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-10-09 10:17:00 -0700 (Mon, 09 Oct 2023) $
     $LastChangedRevision: 32177 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/dangle.pro $

    CREATED BY:    David L. Mitchell

(See general/tplot/dangle.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.
      LAST_VALUE:  Set this keyword to return the last value of y array:  y[index]    (no interpolation performed)

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

(See 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 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 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.

    	_EXTRA: Passes the _EXTRA to the AXIS routine when called.  Most options that AXIS accepts may be passed to DRAW_COLOR_SCALE
    	e.g. ytickformat,ytitle,yminor,yticklen,...

    CREATED BY:	Davin Larson
    LAST MODIFIED:	1.17 05/29/07
    MODIFIED BY: Patrick Cruce

(See 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 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 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.
       TRANGE: named variable to hold the time range (output variable only,
               does not affect data returned).

    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
     $LastChangedBy: davin-mac $
     $LastChangedDate: 2023-11-19 11:39:45 -0800 (Sun, 19 Nov 2023) $
     $LastChangedRevision: 32251 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/get_data.pro $

(See 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 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 general/tplot/get_ylimits.pro)

## HIGHLIGHT_TIME_INTERVAL

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

    NAME:
    highlight_time_interval
    PURPOSE:
    for a given tplot variable, click on a time interval to highlight
    using the fill_time_intv option
    CALLING SEQUENCE:
    highlight_time_interval, tplot_variable, time_interval=time_interval,
                             color = color, polyfill_options =
                             polyfill_options, delete=delete
    INPUT:
    tplot_variable - one or more tplot variables, No input will apply to
                     all tplot variables.
    KEYWORDS:
    time_interval - a 2 or 2Xntimes array of time intervals. The default
                    is to use interactive ctime calls. If interactive,
                    then n_intervals is used to calculate the number of
                    time_intervals.
    color - a color value or ntimes color values, the default is color
            zero, string input is ok, e.g., 'rgb' for three intervals
    line_fill - sets polyfill line_fill option, that uses parallel lines
                instead of solid color
    orientation - angle in degrees for orientation of lines for line_fill
                  option
    linestyle - linestyle for line_fill option
    thick - line thickness for line_fill option
    n_intervals - used for cases with no time inputs, for number of
                  intervals to choose interactively.
    delete - delete highlights.
    refresh - call tplot to show the intervals
    NOTES:
     The same intervals are applied to each of the input tplot variables
     $LastChangedBy: jimm $
     $LastChangedDate: 2019-11-15 11:20:05 -0800 (Fri, 15 Nov 2019) $
     $LastChangedRevision: 28023 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/highlight_time_interval.pro $

(See general/tplot/highlight_time_interval.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 general/tplot/iton.pro)

## JOIN_VEC

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

    NAME: join_vec.pro

    PURPOSE: Take a series of similar variables and store as a single vector;
             e.g. one dimensional variables Vp_x, Vp_y, vp_z can be combined to
             form a three dimensional variable Vp.

    CALLING SEQUENCE:
      join_vec, 'thm_state_pos'+['_x','_y','_z'], 'thm_state_pos_new'

    ARGUMENTS:
      NAMES: Array of tplot variable names to be joined into single variable
      NEW_NAME: Single string containing the name of the tplot variable to be created
      IGNORE_DLIMITS: Set this flag to ignore warnings about dlimits (meta data)

    KEYWORDS
      display_object = Object reference to be passed to dprint for output.

    NOTES: Meant to compliment split_vec.pro

(See general/tplot/join_vec.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 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.
        median_filter:  N : applies an median filter of size N prior to plotting.
        NEG_COLORS  array of colors (or string)  If defined then data is plotted twice - once with
          positive values and second time with negative values. This is useful on log plots
        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
     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-25 12:05:21 -0700 (Sun, 25 May 2025) $
     $LastChangedRevision: 33339 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/mplot.pro $

(See general/tplot/mplot.pro)

## MPLOT_DOWNSAMPLE_DATA

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

     PROCEDURE mplot_downsample_data, max_points, x, y

     PURPOSE:

       Enables fast plotting of time series plots with many elements.

       This function is intended for use when plotting time series plots using
       MPLOT.  When n_elements >> number of pixels on the screen, the large number
       of points slows down plotting considerably without adding any visual
       information to the final plot.

       This procedure groups the data into regularly spaced time intervals.  If
       MAX_POINTS is set correctly (see below), each interval is less than a pixel
       in the plot.  The procedure finds the minimum and maximum value of the
       time series in that interval, and constructs a new time series from the
       minima and maxima.  The new series has many fewer points than the original
       (and therefore the plotting runs much faster), but the resulting plot is
       nearly visually identical to the full time series plot.

       If the number of input points is smaller than MAX_POINTS, the function does
       nothing.

       This should not be used as a 'real' downsampling procedure to make a new
       time series that can be used for calculations at a reduced cadence--use
       only for plotting.

       Works best with regularly spaced data that is plotted without a plot
       symbol set.

     INPUT:

        MAX_POINTS: The maximum number of points in the downsampled array.
         Set to a number that is several times larger than the maximum pixel
         width of the plot window (something like 10000 gives more than enough
         points for nearly any display, and plots nearly instantly).  If the
         number of input points is smaller than max_points, the function does
         nothing.
         For TPLOT variables, set 'max_points' using the OPTIONS procedure.
        X: The time array.
        Y: The data array.

     KEYWORDS:

        DY: Optional uncertainty in y.

     CREATED BY:

       pulupa

     $LastChangedBy: pulupalap $
     $LastChangedDate: 2021-07-06 16:49:05 -0700 (Tue, 06 Jul 2021) $
     $LastChangedRevision: 30102 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/mplot_downsample_data.pro $

(See general/tplot/mplot_downsample_data.pro)

## MPLOT_SYMLOG

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

    PROCEDURE:       MPLOT_SYMLOG

    PURPOSE:         Draws a tplot variable with a bi-symmetric log y-axis
                     that allows to display both positive and negative
                     values in log scale.

                     In general, it is assumed to be only used as follows:

                     IDL> options, 'tplot name', tplot_routine='mplot_symlog'

                     In the current version, it can only draw multi-line plots.

    INPUTS:          Tplot data and settings same to 'mplot'.

    KEYWORDS:

          DATA:      A structure that contains the elements 'x', 'y', and ['dy'].
                     (used by 'tplot').

        LIMITS:      A structure that contains any combination of the following elements:
                     All PLOT/OPLOT keywords (i.e., psym, symsize, linestyle, colors, etc.)

    CREATED BY:      Takuya Hara on 2016-09-27.

    LAST MODIFICATION:
     $LastChangedBy: egrimes $
     $LastChangedDate: 2019-10-08 11:11:53 -0700 (Tue, 08 Oct 2019) $
     $LastChangedRevision: 27831 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/mplot_symlog.pro $

(See general/tplot/mplot_symlog.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 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
     $LastChangedBy: davin-mac $
     $LastChangedDate: 2023-03-06 23:44:21 -0800 (Mon, 06 Mar 2023) $
     $LastChangedRevision: 31594 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/options.pro $

(See 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.

             If you wish to add an overall title and/or margins to your multi panel
             window your first call should also specify mtitle and/or mmargin.

             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 not using the
             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 is filled in sequence, if you move
             on to a new window you will not be able to go back to the
             previous panel without restarting.
             It is possible use a panel out of sequence by setting mpanel.
             mpanel also allows you to create non symmetric layouts by
             creating plots that take up more than one panel.

             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]

    Note: Recommend using the keyword /noiso if you're wondering why your plot has a weird aspect ratio.

     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'
                         .....

             mmargin(optional, can only be used if multi is also specified):
             set this keyword to a 4 element array specifying margins to be left
             around a multipanel plot. Element order is bottom, left, top, right.
             Margins are specified relative to the overall size of the window:
             0.0 is no margin, 1.0 is all margin.
                 e.g. mmargin=[0.1,0.1,0.15.0.1]

             mtitle(optional, can only be used if multi is also specified):
             set this keyword to a string to display as a title for a multi panel
             plot window. This is displayed in addition to any titles specified for
             individual panels.
             If the top mmargin = 0, or has not been set then it will be set at 0.05
             to allow room for the title.
             It is not possible to set your own font size for the mtitle. The size is
             chosen so that as much as possible the title fits in the top margin and
             is not too long for the window. Setting a larger top mmargin will
             increase the font size. NB: Size is fixed you are saving your plot
             to a postscript. If you require more control over the title format
             try leaving space using mmargin and adding your own text with idl
             procedure XYOUTS.

             mpanel(optional, can only be used if multi is also specified):
             set this keyword to a string to specify which panels in a multipanel window
             to plot to. This allows you to create non symmetric plot layouts in a multi
             panel window.
             mpanel must contain two numbers separated by a comma (col, row) or two ranges
             indicated with a colon, separated by a comma.
             Panels are numbered starting at 0, from top to bottom and from
             left to right.
                 e.g. mpanel = '0,1' will plot to panel in the first column,
                           second row;
                      mpanel = '0:1,0' will create a plot that takes up both the first
                           and second columns in the first row.
             You cannot plot to a panel if that panel has already been used.
             Panels in a window are normally filled from left to right, top to bottom. You
             can use mpanel to place a plot out of this standard sequence.

             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

             xistime(optional): set this keyword if you want to treat the x-axis
             as a time axis and use tplot-style time labels

             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)

             startsymcolor(optional): Set this keyword to a color table number
             or letter(e.g. 'm') to control the color of the pstart symbol separately
             from the color= keyword

             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)

    ;        stopsymcolor(optional): Set this keyword to a color table number
             or letter(e.g. 'm') to control the color of the pstop symbol separately
             from the color= keyword

             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..)

             get_plot_pos=get_plot_pos: Return the normalized position of your plot.
                 Output will be a 4-element array [x1,y1,,x2,y2]
                 Where (x1,y1) is the lower-left corner of your plot and
                 (x2,y2) is the top right corner of your plot.

      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 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: lphilpott $
     $LastChangedDate: 2011-05-26 11:53:59 -0700 (Thu, 26 May 2011) $
     $LastChangedRevision: 8701 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/plotxylib.pro $

(See 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'
                         .....

           mmargin(optional, can only be used if multi is also specified):
             set this keyword to a 4 element array specifying margins to be left
             around a multipanel plot. Element order is bottom, left, top, right.
             Margins are specified relative to the overall size of the window:
             0.0 is no margin, 1.0 is all margin.
                 e.g. mmargin=[0.1,0.1,0.15.0.1]

           mtitle(optional, can only be used if multi is also specified):
             set this keyword to a string to display as a title for a multi panel
             plot window. This is displayed in addition to any titles specified for
             individual panels.
             If the top mmargin = 0, or has not been set then it will be set at 0.05
             to allow room for the title.
             It is not possible to set your own font size for the mtitle. The size is
             chosen so that as much as possible the title fits in the top margin and
             is not too long for the window. Setting a larger top mmargin will
             increase the font size. NB: Size is fixed you are saving your plot
             to a postscript. If you require more control over the title format
             try leaving space using mmargin and adding your own text with idl
             procedure XYOUTS.

           mpanel(optional, can only be used if multi is also specified):
             set this keyword to a string to specify which panels in a multipanel window
             to plot to. This allows you to create non symmetric plot layouts in a multi
             panel window.
             mpanel must contain two numbers separated by a comma (col, row) or two ranges
             indicated with a colon, separated by a comma.
             Panels are numbered starting at 0, from top to bottom and from
             left to right.
                 e.g. mpanel = '0,1' will plot to panel in the first column,
                           second row;
                      mpanel = '0:1,0' will create a plot that takes up both the first
                           and second columns in the first row.
             You cannot plot to a panel if that panel has already been used.
             Panels in a window are normally filled from left to right, top to bottom. You
             can use mpanel to place a plot out of this standard sequence.

             xistime(optional): set this keyword if you want to treat the x-axis
             as a time axis and use tplot-style time labels

           [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

            get_plot_pos=get_plot_pos: Return the normalized position of your plot.
                 Output will be a 4-element array [x1,y1,,x2,y2]
                 Where (x1,y1) is the lower-left corner of your plot and
                 (x2,y2) is the top right corner of your plot.

     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: 2013-08-23 17:25:01 -0700 (Fri, 23 Aug 2013) $
     $LastChangedRevision: 12887 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/plotxyvec.pro $

(See 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.

             If you wish to add an overall title and/or margins to your multi panel
             window your first call should also specify mtitle and/or mmargin.

             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 panel without restarting.
             It is possible use a panel out of sequence by setting mpanel.
             mpanel also allows you to create non symmetric layouts by
             creating plots that take up more than one panel.

             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.

                 xistime: Set this argument to use tplot-style time formatting
                 for x-axis labels.

                 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.

                 mmargin(can only be used if multi is also specified):
                 set this keyword to a 4 element array specifying margins to be left
                 around a multipanel plot. Element order is bottom, left, top, right.
                 Margins are specified relative to the overall size of the window:
                 0.0 is no margin, 1.0 is all margin.
                 e.g. mmargin=[0.1,0.1,0.15.0.1]

                 mtitle(can only be used if multi is also specified):
                 set this keyword to a string to display as a title for a multi panel
                 plot window. This is displayed in addition to any titles specified for
                 individual panels.
                 If the top mmargin = 0, or has not been set then it will be set at 0.05
                 to allow room for the title.
                 It is not possible to set your own font size for the mtitle. The size is
                 chosen so that as much as possible the title fits in the top margin and
                 is not too long for the window. Setting a larger top mmargin will
                 increase the font size. NB: Size is fixed you are saving your plot
                 to a postscript. ] If you require more control over the title format
                 try leaving space using mmargin and adding your own text with idl
                 procedure XYOUTS.

                 mpanel(can only be used if multi is also specified):
                 set this keyword to a string to specify which panels in a multipanel window
                 to plot to. This allows you to create non symmetric plot layouts in a multi
                 panel window.
                 mpanel must contain two numbers separated by a comma (col, row) or two ranges
                 indicated with a colon, separated by a comma.
                 Panels are numbered starting at 0, from top to bottom and from
                 left to right.
                     e.g. mpanel = '0,1' will plot to panel in the first column,
                           second row;
                          mpanel = '0:1,0' will create a plot that takes up both the first
                           and second columns in the first row.
                 You cannot plot to a panel if that panel has already been used.
                 Panels in a window are normally filled from left to right, top to bottom. You
                 can use mpanel to place a plot out of this standard sequence.

                 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)

                 no_color_scale: Set to not draw the z-axis color scale

                 get_plot_pos=get_plot_pos: Return the normalized position of your plot.
                 Output will be a 4-element array [x1,y1,,x2,y2]
                 Where (x1,y1) is the lower-left corner of your plot and
                 (x2,y2) is the top right corner of your plot.

                 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 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 general/tplot/pmplot.pro)

## SKIP

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

    PROCEDURE:   skip
    PURPOSE:
      Shifts the tplot plotting window forward/backward by a number of
      orbits, days, hours, minutes, seconds, or "pages".  A page is
      defined as the currently displayed time range.

      For maximum convenience, map this procedure to function keys:

        define_key,'F7','skip,-1',/terminate
        define_key,'F9','skip,1',/terminate

    USAGE:
      skip, n

    INPUTS:
           n:        Number of orbits, days, hours, minutes, seconds, or pages
                     (positive or negative) to shift.  Default = +1.  Normally,
                     this would be an integer, but it can also be a float.

    KEYWORDS:
           PAGE:     (Default) Shift in units of the time range currently displayed.
                     This keyword and the next 5 define the shift units.  Once you
                     set the units, it remains in effect until you explicitly select
                     different units.  The units are all minimum matching, so you only
                     need to specify the first 1 or 2 letters.

           DAY:      Shift in days.

           HOUR:     Shift in hours.

           MINUTE:   Shift in minutes.

           SEC:      Shift in seconds.

           ORB:      Shift in orbits.  Currently only works for MAVEN.

           FIRST:    Go to the beginning of the loaded time range and
                     plot the requested interval from there.  Do not
                     collect $200.

           LAST:     Go to end of loaded time range and plot the requested
                     interval from there.

           PERI:     If keyword FIRST or LAST is set, then go to first or last
                     periapsis and plot the requested interval from there.
                     Shift units are assumed to be orbits.

           APO:      If keyword FIRST or LAST is set, then go to first or last
                     apoapsis and plot the requested interval from there.
                     Shift units are assumed to be orbits.

           TREF:     Reference time to start (instead of the beginning of the
                     loaded time range).

           UNITS:    Skip units to use after the first call.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-08-07 08:03:17 -0700 (Wed, 07 Aug 2024) $
     $LastChangedRevision: 32783 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/skip.pro $

    CREATED BY:    David L. Mitchell

(See general/tplot/skip.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: jimm $
     $LastChangedDate: 2025-02-18 14:05:52 -0800 (Tue, 18 Feb 2025) $
     $LastChangedRevision: 33138 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/specplot.pro $

(See 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:
         inset: a string to be inserted in the new variable names before the suffix
    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
         display_object = Object reference to be passed to dprint for output.

    OUTPUTS:
    OPTIONAL OUTPUTS:
    COMMON BLOCKS:
    SIDE EFFECTS:
    RESTRICTIONS:
    EXAMPLE:
    LAST MODIFICATION:     12-mar-2007, jmm
    CREATED BY:            Frank V. Marcoline
    $LastChangedBy: aaflores $
    $LastChangedDate: 2012-01-26 15:01:41 -0800 (Thu, 26 Jan 2012) $
    $LastChangedRevision: 9619 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/split_vec.pro $

(See 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.
        CLEAR:  Set this keyword to erase the data structure but not the LIMITS or DLIMITS structures
        TAGNAMES: Set this keyword to a string containing tagnames that are to be extracted from an array of
           structures passed in through the DATA structure.  Use TAGNAMES='*' to extract all tagnames.
        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             (obsolete)
             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
     $LastChangedBy: jwl $
     $LastChangedDate: 2025-09-22 11:18:38 -0700 (Mon, 22 Sep 2025) $
     $LastChangedRevision: 33642 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/store_data.pro $

(See 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 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 names or indices indicating panel in which
          to plot bar, can be an array or glob string, color, linestyle
          thick should either be scalar or n_elements(varname) for
          multiple varables
          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 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:
     CURSOR   set to 1 to use the cursor to set the timerange
    	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: jwl $
     $LastChangedDate: 2016-02-03 17:03:41 -0800 (Wed, 03 Feb 2016) $
     $LastChangedRevision: 19898 $
     $URL: svn+ssh:$

(See 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 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

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2025-03-14 14:42:21 -0700 (Fri, 14 Mar 2025) $
     $LastChangedRevision: 33183 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tlimit.pro $

(See 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 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.
             Set this variable to a negative integer to count up from the last
             panel.  If set to -1, the new panels will be placed above the last
             panel.  If set to -2, they will be placed above the second to last
             panel, and so on.
       SUB_VAR:  Set this variable to remove datanames from 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.
       TOSS:     Set this keyword to remove 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,4,5 or 6 (3 is default)  Uses a different labeling
       scheme.  Version 4 is for rocket-type time scales.
         valid inputs for "version" (date annotation | tick annotations)
         1: UTC date boundaries | # of hours or days
         2: month:day | UTC time (fewer ticks)
         3: year(left margin) month:day | UTC time (default)
         4: seconds after launch
         5: supress time labels
         6: time displayed directly below last panel
         7: time displayed directly below last panel (1 line date text only)
         this option can also be set when calling tplot_options (
         e.g. tplot, [variable], version=2 )
       NO_VTITLE_SHIFT: If the var_label keyword is set, then if the full
         time range is less than 10 minutes, then the titles for the
         var_labels are shifted downwards a small amount. (Added on
         2022-02-07). Set /no_vtitle_shift via keyword in the tplot
         call, or via "tplot_options,'no_vtitle_shift',1" to turn this off.
       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.
       GET_PLOT_POSITION: Returns an array containing the corners of each panel in the plot, to make it easier to overplot and annotate plots
       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!

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-12-31 18:33:10 -0800 (Tue, 31 Dec 2024) $
     $LastChangedRevision: 33025 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot.pro $

(See 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: aaflores $
     $LastChangedDate: 2012-01-26 17:01:34 -0800 (Thu, 26 Jan 2012) $
     $LastChangedRevision: 9630 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot3d.pro $

(See 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.

             If you wish to add an overall title and/or margins to your multi panel
             window your first call should also specify mtitle and/or mmargin.

             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 panel without restarting.
             It is possible use a panel out of sequence by setting mpanel.
             mpanel also allows you to create non symmetric layouts by
             creating plots that take up more than one 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.

             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'
                         .....

             mmargin(optional, can only be used if multi is also specified):
             set this keyword to a 4 element array specifying margins to be left
             around a multipanel plot. Element order is bottom, left, top, right.
             Margins are specified relative to the overall size of the window:
             0.0 is no margin, 1.0 is all margin.
                 e.g. mmargin=[0.1,0.1,0.15.0.1]

             mtitle(optional, can only be used if multi is also specified):
             set this keyword to a string to display as a title for a multi panel
             plot window. This is displayed in addition to any titles specified for
             individual panels.
             If the top mmargin = 0, or has not been set then it will be set at 0.05
             to allow room for the title.
             It is not possible to set your own font size for the mtitle. The size is
             chosen so that as much as possible the title fits in the top margin and
             is not too long for the window. Setting a larger top mmargin will
             increase the font size. NB: Size is fixed you are saving your plot
             to a postscript. If you require more control over the title format
             try leaving space using mmargin and adding your own text with idl
             procedure XYOUTS.

             mpanel(optional, can only be used if multi is also specified):
             set this keyword to a string to specify which panels in a multipanel window
             to plot to. This allows you to create non symmetric plot layouts in a multi
             panel window.
             mpanel must contain two numbers separated by a comma (col, row) or two ranges
             indicated with a colon, separated by a comma.
             Panels are numbered starting at 0, from top to bottom and from
             left to right.
                 e.g. mpanel = '0,1' will plot to panel in the first column,
                           second row;
                      mpanel = '0:1,0' will create a plot that takes up both the first
                           and second columns in the first row.
             You cannot plot to a panel if that panel has already been used.
             Panels in a window are normally filled from left to right, top to bottom. You
             can use mpanel to place a plot out of this standard sequence.

             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.

             get_plot_pos=get_plot_pos: Return the normalized position of your plot.
               Output will be a 4-element array [x1,y1,,x2,y2]
               Where (x1,y1) is the lower-left corner of your plot and
               (x2,y2) is the top right corner of your plot.

             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: egrimes $
     $LastChangedDate: 2016-10-27 14:27:21 -0700 (Thu, 27 Oct 2016) $
     $LastChangedRevision: 22223 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplotxy.pro $

(See general/tplot/tplotxy.pro)

## TPLOT_APPLY_DATABAR

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

    NAME:
     tplot_apply_databar
    PURPOSE:
     Plots horizontal lines (databars) for plotted tplot variables, if
     there is a databar tag in the limits structure for those
     variables. To set values, use the 'options' programs: e.g.,

      options, 'tha_efs', 'databar', {yval:[-5., 0, 5.0]}

     Then call

      tplot_apply_databar

     sets three vertical lines for the 'tha_efs' variable..
     Color, linestyle and thick can be included, for each value, or one
     scalar for all:

     options, 'tha_efs', 'databar', {yval:[-5., 0, 5.0], color:[2,4,6], linestyle:2, thick:[2.0, 1.0, 2.0]}

     The databar value only needs to be a structure if other options are set
     options, 'tha_efs', 'databar', [6, 7, 8]
     will work

     Note that tplot needs to have been called previously
    CALLING SEQUENCE:
     tplot_apply_databar
    INPUT:
     none
    OUTPUT:
     none
    KEYWORDS:
     varname = if set, only do the databars for the named variable(s)
     clear = if set, clear out the databar options for the affected variables
    HISTORY:
     2016-07-29, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2019-08-19 12:50:00 -0700 (Mon, 19 Aug 2019) $
     $LastChangedRevision: 27620 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_apply_databar.pro $

(See general/tplot/tplot_apply_databar.pro)

## TPLOT_APPLY_PANEL_LABEL

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

    NAME:
    tplot_apply_panel_label
    PURPOSE:
    Applies a label to a panel, given an input structure from
    tplot_panel_label.pro,
      opt_struct = {label:label, xpos:x, ypos:y, $
                    dq_set:dq_set, charsize:char}
    'dq_set' is set to 1 if xpos and ypos are in data coordinates,
     otherwise xpos and ypos are relative values
     Call this from MPLOT, SPECPLOT, BITPLOT, etc...
    HISTORY:
    2025-02-18, jmm. jimm@ssl.berkeley.edu
     $LastChangedBy: $
     $LastChangedDate: $
     $LastChangedRevision: $
     $URL: $

(See general/tplot/tplot_apply_panel_label.pro)

## TPLOT_APPLY_TIMEBAR

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

    NAME:
     tplot_apply_timebar
    PURPOSE:
     Plots vertical lines (timebars) for plotted tplot variables, if
     there is a timebar tag in the limits structure for those
     variables. To set values, use the 'options' programs: e.g.,

      options, 'tha_efs', 'timebar', {time:'2016-07-01 '+['06:22', '07:00']}

     sets two vertical lines for the 'tha_efs' variable..

     Then call

      tplot_apply_timebar

      options, 'tha_efs', 'timebar', {time:'2016-07-01/'+['06:22','07:00'], color:[3, 6], linestyle:2, thick:2.0}

     Adds color for each of the lines. Linestyle and thick are also
     options for the timebar; color, linestyle and thick can be arrays or scalars

     The timebar value only needs to be a structure if other options are set
     options, 'tha_efs', 'timebar', '2016-07-07/06:12'
     will work

     Note that tplot needs to have been called previously
    CALLING SEQUENCE:
     tplot_apply_timebar
    INPUT:
     none
    OUTPUT:
     none
    KEYWORDS:
     varname = if set, only do the timebars for the named variable(s)
     clear = if set, clear the options for the affected variable
    HISTORY:
     2016-07-29, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2016-10-10 12:29:12 -0700 (Mon, 10 Oct 2016) $
     $LastChangedRevision: 22074 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_apply_timebar.pro $

(See general/tplot/tplot_apply_timebar.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 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 general/tplot/tplot_file.pro)

## TPLOT_FILL_COLOR

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

     NAME:
         tplot_fill_color

     PURPOSE:
         Fills the area under a line in a tplot panel

     INPUT:
         vars: string or array of strings specifying which tplot variables to fill
         colors: int or array of ints specifying the fill colors; must match the number
               of elements in 'vars'

     EXAMPLE:
         >> tplot, 'kyoto_dst'
         >> tplot_fill_color, 'kyoto_dst', spd_get_color('blue')

     WARNING:
         if you see strange results with a variable containing NaNs, run 'tdegap'
         on the variable prior to creating the figure to remove the NaNs

    $LastChangedBy: egrimes $
    $LastChangedDate: 2020-02-12 12:40:17 -0800 (Wed, 12 Feb 2020) $
    $LastChangedRevision: 28296 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_fill_color.pro $

(See general/tplot/tplot_fill_color.pro)

## TPLOT_FILL_TIME_INTV

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

    NAME:
    tplot_fill_time_intv
    PURPOSE:
    Allow different background color, or other polyfill options for time
    intervals for a tplot variable. Called only from tplot.pro, Do not
    use this in any other environment
    CALLING SEQUENCE:
    tplot_fill_time_intv, routine, data, newlim
    INPUT:
    routine - thie is the plot routine for a given tplot variable,
              typically 'mplot' or 'specplot' or 'bitplot'
    data - the data structure for the input variable
    newlim - the limits structure, this must contain a tag
             'fill_time_intv' = {time:interval_times, color:color values}
             The time intervals can be an array of 2, or 2Xntimes, color
             values can be scalar, or an array of ntimes. Other polyfill
             options, such as line_fill, orientation, thick, can be input
             in the fill_time_intv structure,
    time_offset - the plot start time needed for the correct position
    EXAMPLES:
     (see also crib_fill_time_intv.pro in spdsw/general/examples)

    a solid background color, using options, for the variable 'sta_SWEA_mom_flux'
    options, 'sta_SWEA_mom_flux', 'fill_time_intv', $
             {time:['2008-03-23/02:00','2008-03-23/04:00'], color:2}

    different intervals with different colors, using options, for the flux variable
    2Xn_times intervals
    t1 = '2008-03-23/'+[['02:00','04:00'],['07:00','09:00'],['16:24','22:00']]
    c1 = 'rgb' ;you can use string color values in addition to absolute numbers

    options, 'sta_SWEA_mom_flux', 'fill_time_intv', {time:t1, color:c1}

    set line_fill:1,orientation:45 to use angled
    parallel lines and not solid colors
    2Xn_times intervals
    t1 = '2008-03-23/'+[['02:00','04:00'],['07:00','09:00'],['16:24','22:00']]
    c1 = [4,6,2]

    options, 'sta_SWEA_mom_flux', 'fill_time_intv',
              {time:t1, color:c1, line_fill:1, orientation:45.0}
    See crib sheet for more options

    HISTORY:
     2019-11-04, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2023-03-23 13:23:01 -0700 (Thu, 23 Mar 2023) $
     $LastChangedRevision: 31653 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_fill_time_intv.pro $

(See general/tplot/tplot_fill_time_intv.pro)

## TPLOT_FORCE_MONOTONIC

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

     Procedure: tplot_force_monotonic

     Purpose:
        This routine checks tplot variables for sample time (abscissa: data.x) monotonicity
         and forces them so through removal or replacement of non-monotonic segments, if requested;
         the corresponding elements of data.y and data.v are also repaired.
        Indices of consecutively repeated header times and piece-wise monotonic segment "negative jumps"
         are identified and used to determine monotonicity of tplot variables. If checking,
         the routine will report cause of failures (i.e. negative jumps, repeats).
        Three repair methods are available: /forward, /reverse and /sort (see Keywords)

     Inputs:   [optional] tplot variable name(s) string/array or wild-card name string or tplot variable number(s); same as input for tnames()

     Keywords:
               forward:      the recommended repair method, which keeps the older time elements of over-lapping time segments
               reverse:      repair method which keeps the newer time elements over-lapping time segments
               sort:         repair method which sorts time-lines chronologically, using bsort()

               keep_repeats: [optional] do not remove consecutively repeated header times
               replace_NaN:  [optional] instead of removing 'bad' elements, replace them with NaN (only applied to data.y and data.v elements, data.x is not modified)

     Outputs:
               If checking, PASS/FAIL console message per tplot variable, including cause of failures
               If repairing, PASS/FAIL console message per tplot variable and repaired tplot variable(s) (via store_data)

     Examples:
               tplot_force_monotonic                           ; check all tplot variables
               tplot_force_monotonic,'*'                       ; check all tplot variables
               tplot_force_monotonic,'var1'                    ; check tplot variable named var1
               tplot_force_monotonic,['var1','var2']           ; check tplot variables named var1 and var2
               tplot_force_monotonic,[6,7,9]                   ; check tplot variables 6, 7 and 9
               tplot_force_monotonic,/forward                  ; repair all tplot variables using 'forward' method, discarding repeated sample times (recommended repair method)
               tplot_force_monotonic,/reverse,/keep_repeats    ; repair all tplot variables using 'reverse' method, keeping repeated sample times
               tplot_force_monotonic,/sort                     ; repair all tplot variables using 'sort' method, discarding consecutively repeated sample times
               tplot_force_monotonic,'var?',/forward,/replace_nan  ; repair tplot variable(s) in var? using 'forward' method and replace bad elements with NaNs

     Notes:
         1. tplot variables repaired with the /replace_nan keyword will not pass a monotonicity check.
         2. tplot variables repaired with the /keep_repeats keyword may not pass a monotonicity check.
         3. A warning is issued if more than 10% of tplot variable elements are removed or replaced.

     ToDo: nothing yet

     $LastChangedBy: egrimes $
     $LastChangedDate: 2016-04-25 12:07:51 -0700 (Mon, 25 Apr 2016) $
     $LastChangedRevision: 20911 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_force_monotonic.pro $

(See general/tplot/tplot_force_monotonic.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 general/tplot/tplot_keys.pro)

## TPLOT_MULTIAXIS

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

    Procedure:
      tplot_multiaxis

    Purpose:
      This procedure functions as a workaround to allow
      two y axes when creating line plots with tplot.

    Calling Sequence:
      tplot_multiaxis, left_names, right_names [,positions] [,_extra=extra]

    Input:
      left_names:  String array or space separated list of tplot variables.
                   Each variable will be plotted in a separate panel with a
                   left-aligned y axis.
      right_names:  String array or space separate list of tplot variables.
                    Each variable will be added to the appropriate panel
                    with a righ-aligned y axis.  If positions are not
                    specified then this must be the same size as left_names.
      positions:  Integer array specifying the vertical position [1,N] of
                  the correspond entry in right_names.  This keyword must
                  be used if left_names has more entries than right_names.

      _extra:  Keywords to tplot can also be used here.

    Output:
      None, calls tplot with current settings.

    Notes:
      -Y axis graphical keywords set with "options, 'tvar', ..." should be applied.
      -Existing "ystyle" and "axis" elements will be clobbered (from limits structure).

    $LastChangedBy: egrimes $
    $LastChangedDate: 2019-02-07 12:15:26 -0800 (Thu, 07 Feb 2019) $
    $LastChangedRevision: 26569 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_multiaxis.pro $

(See general/tplot/tplot_multiaxis.pro)

## TPLOT_MULTIAXIS_KLUDGE

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

    Procedure:
      tplot_multiaxis_kludge

    Purpose:
      Apply workaround for simultaneous left/right y axes to
      list of tplot variables.

    Calling Sequence:
      tplot_multiaxis_kludge, names, [,/left] [,/right] [,/reset]

    Input:
      names:  string array of tplot variables
      left:  flag denoting left handed y axes
      right:  flag denoting right handed y axes
      reset:  flag to remove previous changes

    Output:
      None, alters limits structure of tplot variables

    Notes:
      -See tplot_multiaxis.pro
      -Existing "ystyle" and "axis" elements of limits struct will be clobbered.

    $LastChangedBy: egrimes $
    $LastChangedDate: 2019-02-07 12:15:26 -0800 (Thu, 07 Feb 2019) $
    $LastChangedRevision: 26569 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_multiaxis_kludge.pro $

(See general/tplot/tplot_multiaxis_kludge.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
     $LastChangedBy: ali $
     $LastChangedDate: 2020-03-05 13:17:11 -0800 (Thu, 05 Mar 2020) $
     $LastChangedRevision: 28378 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_names.pro $

(See 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,2,3,4,5,6)
         valid inputs for "version" (date annotation | tick annotations)
         1: UTC date boundaries | # of hours or days
         2: month:day | UTC time (fewer ticks)
         3: year(left margin) month:day | UTC time (default)
         4: seconds after launch
         5: supress time labels
         6: time displayed directly below last panel
         this option can also be set when calling tplot ( e.g. tplot, [variable], version=2 )
       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,verbose = 2          ; Set verbose level to 2
       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 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 general/tplot/tplot_panel.pro)

## TPLOT_PANEL_LABEL

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

    NAME:
    tplot_panel_label
    PURPOSE:
    For an input tplot variable, add an attribute, 'panel_label', that will be
    printed on the tplot panel for that variable.
    CALLING SEQUENCE:
    tplot_panel_label, tvar, panel_label, x, y, data_coordinates =
    data_coordinates, upper_right=upper_right, lower_right=lower_right, $
    upper_left=upper_left, lower_left=lower_left, charsize=charsize
    INPUT:
    tvar = the tplot variable name
    panel_label = the string input
    x, y = the plot position for the panel_label; the default is relative to
    the plot panel, e.g., x, y = [0.9, 0.9] will put the panel_label in the
    upper right hand corner 9/10 od the way from the lower left.
    data_coordinates = if, set, then use data values instead of relative
    values. The x position can be any time format.
    upper_right = if set, then set [x,y] = [.9, .9]
    lower_right = if set, then set [x, y] = [.9, .1]
    Upper_left = if set, then set [x,y]=[0.05, 0.9]
    lower_left = if set, then set[x,y]=[0.05, 0.1]
    Upper_middle = if set, then set [x,y]=[0.45, 0.9]
    lower_middle = if set, then set[x,y]=[0.45, 0.1]
    charsize = default is 1
    color = default is 0
    remove_label = if set, then remove the panel_label
    OUTPUT:
    No explicit output, instead, an attribute 'panel_label' is added to the
    limits structure for the given variable, containing:
      opt_struct = {label:label, xpos:x, ypos:y, $
                    dq_set:dq_set, charsize:char}
    'dq_set' is set to 1 if xpos and ypos are in data coordinates,
     otherwise xpos and ypos are relative values. Xpos is interpreted as
     seconds from the start of the plot, which makes the use of tlimit difficult

    HISTORY:
    2025-02-04, jmm. jimm@ssl.berkeley.edu
     $LastChangedBy: $
     $LastChangedDate: $
     $LastChangedRevision: $
     $URL: $

(See general/tplot/tplot_panel_label.pro)

## TPLOT_PLOTTER__DEFINE

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

    OBJECT:   tplot_plotter()
    KEYWORDS:

(See general/tplot/tplot_plotter__define.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 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 general/tplot/tplot_quant__define.pro)

## TPLOT_QUATERNION_ROTATE

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

    Procedure: tplot_quaternion_rotate, vectorname, quatname, name=name

    PURPOSE:
      Rotates a tplot vector using the tplot quaternion. Will create a new tplot variable.
      This function may be used with the "fit" curve fitting procedure.

    Written by: Davin Larson

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2020-12-16 13:28:30 -0800 (Wed, 16 Dec 2020) $
     $LastChangedRevision: 29513 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_quaternion_rotate.pro $

(See general/tplot/tplot_quaternion_rotate.pro)

## TPLOT_REMOVE_PANEL

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

     PROCEDURE:
             tplot_remove_panel

     PURPOSE:
             Remove panel(s) from the current tplot window

     INPUT:
             panel: int or array of ints containing panel #s
                    to remove from the current tplot window
                    (starts at 0 at the top)

                    also accepts string or array of strings
                    containing variable names to be removed

     EXAMPLES:
       IDL> tplot, ['var1', 'var2', 'var3']

       to remove 'var2' from the figure:

       IDL> tplot_remove_panel, 'var2'

       or:

       IDL> tplot_remove_panel, 1

    $LastChangedBy: egrimes $
    $LastChangedDate: 2019-07-10 13:21:07 -0700 (Wed, 10 Jul 2019) $
    $LastChangedRevision: 27433 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_remove_panel.pro $

(See general/tplot/tplot_remove_panel.pro)

## TPLOT_RENAME

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

    PROCEDURE: tplot_rename
    PURPOSE:
      Simple procedure to perform a rename of tplot variable without copy.
      Uses the store_data,newname= keyword to implement, but performs some
      checks to make it more user friendly.

    Inputs(required):

     old_name: current name of the variable or index.(string or integer)
     new_name: name the variable will have after procedure call.(string)

    $LastChangedBy: pcruce $
    $LastChangedDate: 2013-09-06 14:36:07 -0700 (Fri, 06 Sep 2013) $
    $LastChangedRevision: 12962 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_rename.pro $

(See general/tplot/tplot_rename.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 (or directory specified by directory keyword)
       directory: specify a directory other than the current working dir for loading ALL tplot files
       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
                           Fixed bug on macOS when saving figures of restored data using makepng/makegif/makejpg, 24-jan-2019, egrimes

     $LastChangedBy: jimmpc1 $
     $LastChangedDate: 2021-11-19 11:02:24 -0800 (Fri, 19 Nov 2021) $
     $LastChangedRevision: 30432 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_restore.pro $

(See 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.
       NO_ADD_EXTENSION:  Set this to prevent the addition of the extension

    SEE ALSO:      "STORE_DATA", "GET_DATA", "TPLOT", "TPLOT_RESTORE"

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

     $LastChangedBy: ali $
     $LastChangedDate: 2021-05-30 19:45:35 -0700 (Sun, 30 May 2021) $
     $LastChangedRevision: 30010 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_save.pro $

(See 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%
     $LastChangedBy: lbwilsoniii_desk $
     $LastChangedDate: 2018-01-31 11:56:42 -0800 (Wed, 31 Jan 2018) $
     $LastChangedRevision: 24612 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_sort.pro $

(See general/tplot/tplot_sort.pro)

## TPLOT_VAR_LABELS

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

    PROCEDURE:   tplot_var_labels
    PURPOSE:
       Helper routine for tplot.  Formats var_labels
       The var_label code in the body of tplot.pro was occupying 25% of the file. It needed to be abstracted.
    Inputs:
      def_opts: all the options need for variables labels, labels are
                added to the xtickname values in the def_opts structure
      trg: time range for plotting
      var_label: var_label setting from user
      local_time: local time keyword from user
      pos: plot position
      chsize: desired character size

    Outputs:
      vtitle=vtitle: title for var labels, for first variable
      vlab=vlab: formatted var labels, for first variable
      time_offset=time_offset: Used by tplot, as the start time of the
                               plot in unix time
      time_scale=time_scale: Used by tplot to scale the time variable,
                             typically 1.0, but larger for longer time
                             ranges
     2021-06-07, jmm, Added option option to allow two variables on a
     line when labeling tplots. To be invoked, the var_label keyword must
     be set up with a valid tplot variable name in square brackets [] after a
     valid tplot variable. Note that even single labels must be passed in as arrays.
     e.g.,
     tplot, 'tha_fag_dsl', var_label = ['tha_state_pos_gse_x[tha_state_pos_gei_x]']
     2022-03-09, jmm, Swapped square brackets for parentheses in
                      two-variable option declaration
     $LastChangedBy: ali $
     $LastChangedDate: 2022-07-06 12:47:09 -0700 (Wed, 06 Jul 2022) $
     $LastChangedRevision: 30907 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/tplot_var_labels.pro $

(See general/tplot/tplot_var_labels.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 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
     $LastChangedBy: ali $
     $LastChangedDate: 2019-05-14 14:18:26 -0700 (Tue, 14 May 2019) $
     $LastChangedRevision: 27232 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/ylim.pro $

(See 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 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
     $LastChangedBy: ali $
     $LastChangedDate: 2020-02-20 12:13:34 -0800 (Thu, 20 Feb 2020) $
     $LastChangedRevision: 28324 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tplot/zlim.pro $

(See 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 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 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 general/tplot/_tplot_example.pro)