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

Last modified: Fri Nov 7 18:17:52 2025.

# Directory Listing of Routines

# general/tools/tplot

- ADD_DATA
  Creates a tplot variable that is the sum of two tplot variables.
- ANG_DATA
  Creates a tplot variable that is the angle between two tplot variables.
- AVG_DATA
  Creates a new tplot variable that is the time average of original.
- DELTA_DATA
  Creates a tplot variable that is the derivative of a tplot variable.
- DERIV2_DATA
  Creates a tplot variable that is the derivative of a tplot variable.
- DERIV_DATA
  Creates a tplot variable that is the derivative of a tplot variable.
- DIF_DATA
  Creates a tplot variable that is the difference of two tplot variables.
- DIV_DATA
  Creates a tplot variable that is the ratio of two other tplot variables.
- INTERP_GAP
- LOAD_WI_ELPD5
  loads WIND 3D Plasma Experiment key parameter data for "tplot".
- LOAD_WI_PDFIT
  loads WIND 3D Plasma Experiment key parameter data for "tplot".
- MULT_DATA
  Creates a tplot variable that is the product of two other tplot variables.
- NUL_DATA
- SPECPLOT_GRAYNANS
  plot spectral data, any data set to NaN is plotted gray
- STORE_DATA_COLBAR
- TDEXISTS
- TPLOT_ASCII
- TPRINT_MULTIAXIS
  A PostScript wrapper for tplot_multiaxis, opens .ps file, calls
- TSAMPLE
  Returns a vector (or array) of tplot data values.
- TSAMPLE2
  Returns a vector (or array) of tplot data values.

# Routine Descriptions

## ADD_DATA

[Next Routine] [List of Routines]

    PROCEDURE: add_data, n1,n2
    PURPOSE:
       Creates a tplot variable that is the sum of two tplot variables.
    INPUT: n1,n2  tplot variable names (strings)
    KEWORDS:
      copy_dlimits: set to 1 to use the first variable's dlimits, 2 to use the second's

(See general/tools/tplot/add_data.pro)

## ANG_DATA

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

    PROCEDURE: ang_data, n1,n2
    PURPOSE:
       Creates a tplot variable that is the angle between two tplot variables.
    INPUT: n1,n2  tplot variable names (strings)
       These should each be 3 element vectors
    KEWORDS:
      copy_dlimits: set to 1 to use the first variable's dlimits, 2 to use the second's

(See general/tools/tplot/ang_data.pro)

## AVG_DATA

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

    PROCEDURE: avg_data, name, res
    PURPOSE:
       Creates a new tplot variable that is the time average of original.
    INPUT: name  tplot variable names (strings)
    KEYWORDS:
     newname = new name for the variable
     append = append this suffix to the variable
     trange = time range, can be used to alter start and end times, the
              default is minmax(data.x)
     day = return values /per day
     display_object = Object reference to be passed to dprint for output.
     do_stdev = if set create a variable for the standard deviation. with
                suffix "_stdev"
    Modified by O. Le Contel, LPP, Feb. 19, 2016
     in order to deal with L64 integer

     $LastChangedBy: jwl $
     $LastChangedDate: 2025-08-20 11:11:05 -0700 (Wed, 20 Aug 2025) $
     $LastChangedRevision: 33563 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tools/tplot/avg_data.pro $

(See general/tools/tplot/avg_data.pro)

## DELTA_DATA

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

    PROCEDURE: delta_data, n1,n2
    PURPOSE:
       Creates a tplot variable that is the derivative of a tplot variable.
    INPUT: n1  tplot variable names (strings)

    Keywords:
     newname = the name of the tplot variable in which output should be
        stored. This will produce an error if you use this option with globbing.
     nsmooth = If this keyword is set smoothing will be performed.  The
               number you set this keyword equal to is the width of the smoothing
               to be applied to the data.  It is the same as the
               width argument to the idl smooth procedure. To get an explanation of
               how this keyword works please see the idl documentation for the
               'width' keyword to the idl 'smooth' procedure.
     suffix = the suffix to be applied to the input data.  Use this if you
              want to call this procedure on multiple tplot variables
              simultaneously.
     replace = set this keyword if you want to replace the original
               variables with the new values
     display_object = Object reference to be passed to dprint for output.

     Examples:

     $LastChangedBy:  $
     $LastChangedDate: 2008-04-28 13:27:07 -0700 (Mon, 28 Apr 2008) $
     $LastChangedRevision: 2851 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/branches/tdas_4_00/idl/themis/common/thm_config.pro $

(See general/tools/tplot/delta_data.pro)

## DERIV2_DATA

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

    PROCEDURE: deriv_data, n1,n2
    PURPOSE:
       Creates a tplot variable that is the derivative of a tplot variable.
    INPUT: n1  tplot variable names (strings)

    Keywords:
     newname = the name of the tplot variable in which output should be
        stored. This will produce an error if you use this option with globbing.
     nsmooth = If this keyword is set smoothing will be performed.  The
               number you set this keyword equal to is the width of the smoothing
               to be applied to the data.  It is the same as the
               width argument to the idl smooth procedure. To get an explanation of
               how this keyword works please see the idl documentation for the
               'width' keyword to the idl 'smooth' procedure.
     suffix = the suffix to be applied to the input data.  Use this if you
              want to call this procedure on multiple tplot variables
              simultaneously.
     replace = set this keyword if you want to replace the original
               variables with the new values
     display_object = Object reference to be passed to dprint for output.

     Examples:
          deriv_data,'thb_fgs_dsl'
          deriv_data,'th?_fgs_dsl',suffix='_fgsderiv'
          deriv_data,'thb_fgs_dsl thb_state_pos',nsmth=2
          deriv_data,'thb_fgs_dsl',newname='fgs_derivd'
          deriv_data,'the_*',/replace

     $LastChangedBy: jwl $
     $LastChangedDate: 2025-08-20 11:11:05 -0700 (Wed, 20 Aug 2025) $
     $LastChangedRevision: 33563 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tools/tplot/deriv2_data.pro $

(See general/tools/tplot/deriv2_data.pro)

## DERIV_DATA

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

    PROCEDURE: deriv_data, n1,n2
    PURPOSE:
       Creates a tplot variable that is the derivative of a tplot variable.
    INPUT: n1  tplot variable names (strings)

    Keywords:
     newname = the name of the tplot variable in which output should be
        stored. This will produce an error if you use this option with globbing.
     nsmooth = If this keyword is set smoothing will be performed.  The
               number you set this keyword equal to is the width of the smoothing
               to be applied to the data.  It is the same as the
               width argument to the idl smooth procedure. To get an explanation of
               how this keyword works please see the idl documentation for the
               'width' keyword to the idl 'smooth' procedure.
     suffix = the suffix to be applied to the input data.  Use this if you
              want to call this procedure on multiple tplot variables
              simultaneously.
     replace = set this keyword if you want to replace the original
               variables with the new values
     display_object = Object reference to be passed to dprint for output.

     Examples:
          deriv_data,'thb_fgs_dsl'
          deriv_data,'th?_fgs_dsl',suffix='_fgsderiv'
          deriv_data,'thb_fgs_dsl thb_state_pos',nsmth=2
          deriv_data,'thb_fgs_dsl',newname='fgs_derivd'
          deriv_data,'the_*',/replace

     $LastChangedBy: jimm $
     $LastChangedDate: 2008-04-28 13:27:07 -0700 (Mon, 28 Apr 2008) $
     $LastChangedRevision: 2851 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/branches/tdas_4_00/idl/themis/common/thm_config.pro $

(See general/tools/tplot/deriv_data.pro)

## DIF_DATA

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

    PROCEDURE: dif_data, n1,n2
    PURPOSE:
       Creates a tplot variable that is the difference of two tplot variables.
    INPUT: n1,n2  tplot variable names (strings)
    KEWORDS:
      copy_dlimits: set to 1 to use the first variable's dlimits, 2 to use the second's

(See general/tools/tplot/dif_data.pro)

## DIV_DATA

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

    PROCEDURE: div_data, n1,n2
    PURPOSE:
       Creates a tplot variable that is the ratio of two other tplot variables.
    INPUT: n1,n2  tplot variable names (strings)

(See general/tools/tplot/div_data.pro)

## INTERP_GAP

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

    Procedure interp_gap,x,y,index=wb,count=c
    replaces NANs with interpolated values.

(See general/tools/tplot/interp_gap.pro)

## LOAD_WI_ELPD5

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

    PROCEDURE:	load_wi_elpd5
    PURPOSE:
       loads WIND 3D Plasma Experiment key parameter data for "tplot".

    INPUTS:
      none, but will call "timespan" if time_range is not already set.
    KEYWORDS:
      DATA:        Raw data can be returned through this named variable.
      TIME_RANGE:  2 element vector specifying the time range
    RESTRICTIONS:
      This routine expects to find the master file: 'wi_elsp_3dp_files'
      In the directory specified by the environment variable: 'CDF_INDEX_DIR'
      See "make_cdf_index" for more info.
    SEE ALSO:
      "make_cdf_index","loadcdf","loadcdfstr","loadallcdf"

    CREATED BY:	Davin Larson
    FILE:  load_wi_elpd4.pro
    LAST MODIFICATION: 99/05/27

(See general/tools/tplot/load_wi_elpd5.pro)

## LOAD_WI_PDFIT

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

    PROCEDURE:	load_wi_pdfit
    PURPOSE:
       loads WIND 3D Plasma Experiment key parameter data for "tplot".

    INPUTS:
      none, but will call "timespan" if time_range is not already set.
    KEYWORDS:
      DATA:        Raw data can be returned through this named variable.
      TIME_RANGE:  2 element vector specifying the time range
    RESTRICTIONS:
      This routine expects to find the master file: 'wi_elsp_3dp_files'
      In the directory specified by the environment variable: 'CDF_INDEX_DIR'
      See "make_cdf_index" for more info.
    SEE ALSO:
      "make_cdf_index","loadcdf","loadcdfstr","loadallcdf"

    CREATED BY:	Davin Larson
    FILE:  load_wi_elpd4.pro
    LAST MODIFICATION: 99/05/27

(See general/tools/tplot/load_wi_pdfit.pro)

## MULT_DATA

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

    PROCEDURE: mult_data, n1,n2
    PURPOSE:
       Creates a tplot variable that is the product of two other tplot variables.
    INPUT: n1,n2  tplot variable names (strings)
    KEWORDS:
      copy_dlimits: set to 1 to use the first variable's dlimits, 2 to use the second's

(See general/tools/tplot/mult_data.pro)

## NUL_DATA

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

    $LastChangedBy: jwl $
    $LastChangedDate: 2025-08-20 11:11:05 -0700 (Wed, 20 Aug 2025) $
    $LastChangedRevision: 33563 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tools/tplot/nul_data.pro $

    PROCEDURE: nul_data
    PURPOSE: Null out a range of tplot data.

(See general/tools/tplot/nul_data.pro)

## SPECPLOT_GRAYNANS

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

     PROCEDURE:
             specplot_grayNaNs, tvar

     PURPOSE:
             plot spectral data, any data set to NaN is plotted gray

     INPUT:
             tvar:  tplot variable name, string

     EXAMPLE:
             mms_load_eis, probes='1', trange=['2015-07-31', '2015-08-1'], datatype='electronenergy'
             mms_eis_pad, probe='1', species='electron', datatype='electronenergy', data_units='flux'
             specplot_grayNaNs, 'mms1_epd_eis_electronenergy_0-1000keV_electron_flux_omni_pad_spin'

     NOTES:
         This is an initial release demonstrating the capability of plotting tplot spectral data that contains Nans.
         Originally developed for MMS data, however, subsequent fixes to the data may no longer have need for this
         type of plot.
         Currently the routine locates any existing Nan values and sets them to a sentinel value for display. An index
         in the color table corresponding to the new Nan value is changed to gray

(See general/tools/tplot/specplot_graynans.pro)

## STORE_DATA_COLBAR

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

    PROCEDURE:       STORE_DATA_COLBAR

    PURPOSE:         Wrapper of 'store_data' to create a tplot variable
                     of color bar as a function of time.

    INPUTS:          Time and bar data array. They must be same elements.
                     Basic usage is the same as 'store_data'.

    KEYWORDS:        See, 'store_data', and 'draw_color_scale'.

          DATA:      Variable that contains the data structure.

        LIMITS:      Variable that contains the limit structure.

         RANGE:      Array of two giving the range in data values the
                     scale corresponding to.

        BRANGE:      INTARR(2) giving the range in color map values the
                     scale spans.

        BOTTOM:      Sets the bottom color for byte-scaling.

           TOP:      Sets the top color for byte-scaling.

           LOG:      If set, make scale logarithmic.

    CREATED BY:      Takuya Hara on 2015-05-01.

    LAST MODIFICATION:
     $LastChangedBy: hara $
     $LastChangedDate: 2015-05-06 16:30:16 -0700 (Wed, 06 May 2015) $
     $LastChangedRevision: 17491 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tools/tplot/store_data_colbar.pro $

(See general/tools/tplot/store_data_colbar.pro)

## TDEXISTS

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

    function: tdexists

     purpose: Checks to see if a tplot variable exists and if its data
     exists. Exists means that there is data on the specified interval
     and that the data is not all NaNs

     Inputs:

     tvarname: A name or names to be checked(accepts type globs)
     start_time: a start datetime for the interval
     end_time: an end datetime for the interval

     Keywords:

      dims: set this keyword to a number if you want the function also to verify that
        the data has that number of elements in its second dimension.  For
        example, if you set dims = 3, it will verify that the y component
        of the tplot variable is Nx3.

     NOTES:
        If you pass in a list of variables, this routine will return 0 if
        any of them do not exist or they do not have data on the
        interval.
        If you use globbing, it will return 0 if no variables match the
        glob and 0 if any of the variables that match the glob do not
        have data on the interval.
        On the other hand, if, for example,
        you expect that 2 variables should match the glob, but only one is
        present or only one matches and that has data, it will return
        true, because it cannot predict how many variables you expect to
        exist if you do not explictly specify them.

        For data types with the number of y dimensions > 6, false positives may result
        if the Y array has some finite values, but all of them are outside the time range of interest.

     $LastChangedBy: jwl $
     $LastChangedDate: 2021-03-18 16:49:04 -0700 (Thu, 18 Mar 2021) $
     $LastChangedRevision: 29776 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tools/tplot/tdexists.pro $

(See general/tools/tplot/tdexists.pro)

## TPLOT_ASCII

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

    Procedure:  tplot_ascii
    Purpose:
      Creates an ascii file for selected tplot variables.
    Input:
      Names names of tplot variables. May use glob patterns  to specify
            a set of variables.
    Keywords:
      fname: file name, by default 'tplot_name' where name is set to
    		  tvar[n] (variable name)
      Ext:  by default, a separate file will be created in the
            current directory with name tplot_name.txt.  Use this
            keyword to set the .txt extension to a different extension.
      dir:  Put output  in dir as opposed to current working directory.
      precise: increases precision to maximum (microseconds)
      trange: array[2] of double  or string. Specify time range for output.
      header: optional keyword, if set ascii file will contain header information
    History:
      08-Jul-2008, cg, added formating to handle 3 d data sets
      09-may-2008, cg, added format statement to print so that the values didn't
                   run together
      09-may-2008, cg, added use of precision keyword, set default value = 3
      29-apr-2008, cg, fixed bug with dlimits
      28-mar-2008, cg, added keyword fname to allow user to specify a file
                   name (thm_ui_dproc procedure determines and passes the
                   filename)
      28-mar-2008, cg, added file header
      27-aug-2008, cg, added another time precision keyword /msec to print format
      09-jul-2009, cg, added code to write the v component to a file, also added
                       print statements indicating success or failure.
      30-nov-2010, jmm, removed /msec from time_string call

(See general/tools/tplot/tplot_ascii.pro)

## TPRINT_MULTIAXIS

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

    NAME:
     tprint_multiaxis
    PURPOSE:
     A PostScript wrapper for tplot_multiaxis, opens .ps file, calls
     tplot_multiaxis, closes file and prints or calls "xv". The printer
     or view options are only applied on Unix-based systems, but the file
     will be created for any OS.
    CALLING SEQUENCE:
     tprint_multiaxis, left_names, right_names [,positions], filename=filename, $
                       printer=printer,times=times,ct=ct,landscape=landscape, $
                       xsize=xsize,ysize=ysize,_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 right-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.
    KEYWORDS:
      no_zoffset: If set, then the color scale is Not moved off the
                  screen. (See tplot_multiaxis_kludge.pro for details)
      filename:  An output filename, the default is 'tplot_multiaxis'
      printer: A printer name (example 'chp360'), If not set, then output
               is displayed via "xv", if it is a valid command.
      times: if set, will apply timebars at certain times. Note that
             tplot_apply_timebar and tplot_apply_databar are also called
             by default, so if these timbars are aplied for all panels in
             addition to any variable-specific timebars.
      ct: Color table; the default is to use whatever is already
          loaded. Note that the color table is not reset post-plot
      landscape, xsize, ysize: passed through to popen
      _extra:  Keywords to tplot can also be used here.
    HISTORY: Hacked from 'tprint.pro', 2022-08-22, jmm,
             jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2022-08-22 14:21:36 -0700 (Mon, 22 Aug 2022) $
     $LastChangedRevision: 31031 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tools/tplot/tprint_multiaxis.pro $

(See general/tools/tplot/tprint_multiaxis.pro)

## TSAMPLE

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

     $LastChangedBy: ali $
     $LastChangedDate: 2025-10-14 18:20:42 -0700 (Tue, 14 Oct 2025) $
     $LastChangedRevision: 33757 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/tools/tplot/tsample.pro $

    FUNCTION:
      dat = tsample([var,trange],[times=t])
    PURPOSE:
      Returns a vector (or array) of tplot data values.
    USAGE:
      dat = tsample()               ;Use cursor to select a subset of data.
      dat = tsample('Np',[t0,t1])   ;extract all 'Np' data in the given time range
    KEYWORDS:
      AVERAGE:  if set the time average of the variable is returned
      STDEV:  named value to return the standard deviation (only works if AVERAGE is set)
      TIMES:  time values returned through this (named) variable keyword.
      VALUES: values returned through this named variable keyword.
      DY :  dy values returned through this named variable keyword.

(See general/tools/tplot/tsample.pro)

## TSAMPLE2

[Previous Routine] [List of Routines]

    FUNCTION:
      dat = tsample([var,trange],[times=t])
    PURPOSE:
      Returns a vector (or array) of tplot data values.
    USAGE:
      dat = tsample()               ;Use cursor to select a subset of data.
      dat = tsample('Np',[t0,t1])   ;extract all 'Np' data in the given time range
    KEYWORDS:
      times:  time values returned through this keyword.
      values: values returned through this keyword.
      dy :  dy values

(See general/tools/tplot/tsample2.pro)