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

Last modified: Thu Jul 31 18:17:17 2025.

# Directory Listing of Routines

# general/misc

- APPEND_ARRAY
  Append an array to another array. Can also copy an array into a
- ARRAY_CONCAT
  Performs array concatenation in a way that handles an empty list.
- ARRAY_CONCAT_WRAPPER
  Wrapper for the array_concat function -- correctly handles
- ARRAY_CONTAINS
  Boolean check for a value inside an array; returns 1
- ARRAY_CROSS
- AVERAGE_STR
  Average data in res second time segments.
- BIN1D
- BIN2D
- BOX_MEAN
  Calculates the mean, median, and standard deviation of a 1-D array
- BSHOCK_2
  This subroutine calculates the bow shock (X,Y) locations based on
- BYTESCALE
- CART_TO_SPHERE
- CDF_FILE_NAMES
  Returns an array of filenames within a timerange.
- COLORS_COM
- CROSSP2
  performs cross product on arrays
- CSVECTOR
- CUSTOMTICKFORMATEXP
- DIMEN
  Returns the dimensions of an array as an array of integers.
- DIMEN1
- DIMEN2
- DIMEN_SHIFT
  Rotate dimensions of a multidimensional array.
- DIVIDE_DATA
- DPWRSPC
  Called with times time and data quantity, dpwrspc returns a dps
- DYDT_SPIKE_TEST
  This function checks an array for spikes based on its time
- ESCAPE_STRING
- EULER_ANG_ROT_MATRIX
  returns rotation matrix given the euler angles
- EXTRACT_TAGS
- [4]
  Decimates polylines in an aesthetically pleasing fashion.
- FILE_ARCHIVE
  Archives files by renaming them and optionally moving them to another directory.
- FILE_CHGRP
- FILE_COPY2
- FILE_DAILYNAMES
- FILE_OPEN
- FILE_RETRIEVE
- FILE_RETRIEVE_V
- FILE_SOURCE_DIRNAME
- FILE_TOUCH
- FIND_CONST_INTERVALS
- FIND_NEAREST_NEIGHBOR
- FIND_NEAREST_NEIGHBOR2
- FIND_STR_ELEMENT
- FNAME_TO_TIME
  To translate the name of a standard WIND data file into the starting
- GENERIC_APDAT__DEFINE
- GENERIC_OBJECT__DEFINE
- GET_COLOR_INDX
- GET_COLORS
- GET_FILE_NAMES
  Gets an array of filenames within a time range
- GET_FILE_NAMES_IND
  Gets an array of filenames within a masterfile within a time range
- GET_RT_PATH
  gets the directory of the calling routine. Used for reliably looking
- GRAD
- HEXPRINT
- HIGH_PASS_FILTER
  subtracts running average from a data array
- HISTBINS
- HISTBINS2D
- INTERP
  Linearly Interpolates vectors with an irregular grid.
- IS_NUMERIC
- [5]
- MAKEGIF[2]
  Creates a GIF file from the currently displayed image.
- MAKEJPG
  Creates a jpg file from the currently displayed image.
- MAKEPNG
  Creates a PNG file from the currently displayed image.
- MAKEPS.PRO
- MERGE_STRUCT[1]
  Renames structure element with name "old_tag_name" or index "index",
- MERGE_STRUCT[2]
  Find (or add) an element of a structure.
- MINMAX
- MK_HTML_HELP2
  Creates a html document from a list of IDL procedures.
- MPAUSE_2
  This subroutine calculates the magnetopause (X,Y) locations based on
- MPAUSE_FLAG
  determine spacecraft is inside or outside the magnetopause, according to the Fairfield model (JGR, 1971)
- NDIMEN
  Returns the number of dimensions in an array.
- NEAREST_NEIGHBOR
- SM_NS_MODEL
  This routine calculates the NS position along the zaxis at a specific x and y location.
- THEMIS_NS_MODEL
  This routine calculates the position along the zaxis at a specific
- AEN_NS_MODEL
- DEN_NS_MODEL
  This program finds the DEN(Displaced Equatorial Neutral) sheet inside
- FAIRFIELD_NS_MODEL
  This routine calculates the position along the zaxis at a specific
- DEN_FAIRFIELD_NS_MODEL
  This routine calculates the position along the zaxis at a specific
- LOPEZ_NS_MODEL
  This routine calculates the position along the zaxis at a specific
- NN
- NN2
  Returns the indices of the nearest neighbors in one time array to the
- OPLOT_ERR
  Plot error bars over a previously drawn plot.
- PCLOSE
- PLOT_POSITIONS
  Procedure that will compute plot positions for multiple plots per page.
- PLOT_THE_EARTH
- POPEN
  Change plot device to postscript.
- POPEN_COM
- PRINT_OPTIONS
- PRINT_TINFO
- PRINTDAT
  Displays information and contents of a data variable. (Very similar to HELP procedure but much more verbose.)
- PTR_EXTRACT
- PTRACE
- PUTWIN
  'Putwin' has been renamed to 'win'. Putwin is now a simple pass-through
- PUTWIN_COMMON
  Common block for win.
- PWRSPC
  Called with times time and data quantity, PWRSPC returns a power
- READ_ASCII_CMDLINE
  Read data from an ASCII file into IDL.
- REPLACE_TAG
  Replaces a tag in a structure by another
- REVVID
  Swaps !p.color and !p.background to switch between a light and
- ROOT_DATA_DIR
- SCPOT_OVERLAY
  Overlays a spacecraft potential (or similar line function) over a
- SETBP
- SHARE_COLORS
  Procedure that allows multiple IDL sessions to share the same color table.
- SIMPLE_DESPIKE_1D
- SMOOTH_IN_TIME
  Runs smooth for irregular grids, after regularising grid
- SPACE_BAR
- SPD_DEFAULT_LOCAL_DATA_DIR
  Returns the default data directory for file downloads for varius projects.
- SSL_CHECK_VALID_NAME
  Checks a string or array input against another array to find matches.
- SSL_CORRELATE_TPLOT
  Identified the amount of shift required to correlate two
- SSL_CORRELATION_SHIFT
  Calculates the shift required to correlate two tme series of
- SSL_SET_COMPLEMENT
- SSL_SET_INTERSECTION
- SSL_SET_SYMBOL
- SSL_SET_UNION
- SSL_TIME_CHECK
- STR_ELEMENT
  Find (or add) an element of a structure.
- STRFILTER
- STRIPPATH
- STRUCT_VALUE
- TAG_NAMES_R
- TCLIP
  Wrapper for xclip.pro allowing input of tplot variable
- TCS_IS_ARRAY
  Helper function: tests if argument is array, 1L on success 0L on failure
- TDEFLAG
  wapper for xdeflag.pro allowing input of tplot variable names
- TDEGAP
  wrapper for xdegap.pro allowing input of tplot variable names
- TDESPIKE_AE
- TDPWRSPC
  wapper for dpwrspc.pro allowing input of a tplot variable name
- THIGH_PASS_FILTER
  Uses high_pass_filter to calculate a running average of the input data and
- TIME_AVERAGE
- TIME_CLIP
- TIME_INTERVALS
- TIME_STAMP
  Prints a time stamp along the lower right edge of the current plot box
- TIME_TICKS
  Returns a structure that can be used to create time ticks for a plot.
- TIMEBOX_MEAN
  Calculates the mean, median, and standard deviation of a 1-D array
- TINTERPOL
- TKM2RE
- TPLOT_NOISE_VARS
  generate Nvars tplot variables, with random noise for testing
- TPWRSPC[2]
  wrapper for pwrspc.pro allowing input of a tplot variable name.
- TRANGE_STR
- TRES
  returns the time resolution of a tplot variable, defined as the
- TSMOOTH_IN_TIME
  Calls smooth_in_time function on a plot variable
- TSNAP
  Tplot variables with two independent variables (time and some other
- AVSIG
  Average and dispersion of an array, zeros can be not included,
- TSUB_AVERAGE
  Subtracts average or median values from the data in a tplot
- STRING_PARSER
  Parse strings into components
- CODE_FRAGMENT
  takes a string, where input variables are defined as array_elements
- TVECTOT
- UNDEFINED
  Tests whether a variable is undefined
- WI
- WIN
  When there are multiple monitors, IDL defines a rectangular "super
- XCLIP
  Replaces with FLAGs the values of the array that are BEYOND
- XDEFLAG
  Replaces FLAGs in arrays with interpolated or other values
- XDEGAP
  Locates gaps in data, and fills in with NaN

# Routine Descriptions

## AEN_NS_MODEL

[Next Routine] [List of Routines]

    NAME:
     aen_ns_model

    PURPOSE:  This program is to find the AEN(Analytical Equatorial Neutral) sheet in the
              magnetopause in different time and position

    INPUT:
     time - string or double format
            double(s)  seconds since 1970
            string(s)  format:  YYYY-MM-DD/hh:mm:ss
     gsm_pos - position vector in GSM coordinates in re (pos[*,3])

    OUTPUT: returns Z displacement of the neutral sheet above or below the XY plane in Re (zgsm of the NS)
            Value is positive if NS is above z=0 gsm plane, negative if below

    KEYWORDS
        sc2NS - if set returns Z displacement from the spacecraft to the neutral sheet
                Value is positive if the NS is northward of the SC location, and negative if below

    NOTES:

     References:
    (1) AEN(Analytical Equatorial Neutral):
        Zhu, M. and R.-L. Xu, 1994, A continuous neutral sheet model and a normal
        curved coordinate system in the magnetotail,  Chinese J. Space Science,  14,
        (4)269, (in Chinese).
        Wang, Z.-D. and R.-L. Xu, Neutral Sheet Observed on ISEE Satellite,
        Geophysical Research Letter, 21, (19)2087, 1994.
    (2) Magnetopause model:
        Sibeck, D. G., R. E. Lopez, and E. C. Roelof, Solar wind control of the
        magnetopause shape, location, and motion, J. Grophys. Res., 96, 5489, 1991

    HISTORY:

(See general/misc/neutral_sheet.pro)

## APPEND_ARRAY

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

    PROCEDURE: append_array, a0, a1
    PURPOSE:
       Append an array to another array.  Can also copy an array into a
       subset of another. It is equivalent to :    a0 = [a0,a1];  but it doesn't fail if a0 is undefined (or 0)
    INPUT:
       a0:   Array to be enlarged.
       a1:   Array (or single value) to be appended to a0.
    KEYWORDS:
       INDEX:  an input variable that will VASTLY improve performance when repeatedly appending a small array onto the end of a large array.
            When using this keyword, the array a0 is enlarged a little bit more than needed so that subsequent appends of a1 will be
            written into a0 instead of creating a new array each time.  The INDEX value represents the number of valid elements.
            If INDEX is a named variable then it will be auto incremented.
            If INDEX is not a named variable then the calling routine should set it using the NEW_INDEX output,
            After all appending is completed, make the call:
                append_array,a0,index=index
            to truncate to the proper size.
       NEW_INDEX:  Output, size of new array.  This can be used if index is NOT a named variable.  Don't use if INDEX is a NAMED variable
       FILLNAN:  Set this keyword to fill padded values with NANs.
       DONE: Equivalent to calling without the a1 argument.
    CREATED BY:    Davin Larson
     $LastChangedBy: davin-mac $
     $LastChangedDate: 2020-04-04 00:09:13 -0700 (Sat, 04 Apr 2020) $
     $LastChangedRevision: 28501 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/append_array.pro $

    LAST MODIFIED: @(#)append_array.pro    1.6 98/08/13

(See general/misc/append_array.pro)

## ARRAY_CONCAT

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

    FUNCTION:
      array_concat

    PURPOSE:
      Performs array concatenation in a way that handles an empty list.
      Simple code that gets duplicated everywhere.

    Inputs:
      arg: The argument to be concatenated
      array: The array to which it should be concatenated, or nothing
      no_copy: Flag to effectively call array_concat( x, temporary(y) ), which
               throws an exception in IDL versions without the null variable.

    Output:
      [ array , arg ]

    $LastChangedBy: aaflores $
    $LastChangedDate: 2015-09-10 18:58:16 -0700 (Thu, 10 Sep 2015) $
    $LastChangedRevision: 18766 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/array_concat.pro $

(See general/misc/array_concat.pro)

## ARRAY_CONCAT_WRAPPER

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

    FUNCTION:
        array_concat_wrapper

    PURPOSE:
         Wrapper for the array_concat function -- correctly handles
         the case when the input array is an empty string

    Inputs:
      arg: The argument to be concatenated
      array: The array to which it should be concatenated, or nothing

    Output:
      array + arg

    $LastChangedBy: egrimes $
    $LastChangedDate: 2013-10-22 12:49:25 -0700 (Tue, 22 Oct 2013) $
    $LastChangedRevision: 13372 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/array_concat_wrapper.pro $

(See general/misc/array_concat_wrapper.pro)

## ARRAY_CONTAINS

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

     PROCEDURE:
             array_contains

     PURPOSE:
             Boolean check for a value inside an array; returns 1
               if str_to_check exists inside array_input

     INPUT:
             array_input: the array to be searched
             str_to_check: value to search for

     KEYWORDS:
             allow_wildcards: allow wild cards ([], *, ?) to be used in the input string

     EXAMPLE:
         IDL> print, array_contains(['hello', 'world'], 'hello')
             1

       Note that this also works on other types:

         IDL> print, array_contains([1, 4, 66], 66)
             1
         IDL> print, array_contains([1, 4, 66], 65)
             0
     HISTORY:
       created by egrimes@igpp

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-11-20 16:04:09 -0800 (Mon, 20 Nov 2017) $
    $LastChangedRevision: 24327 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/array_contains.pro $

(See general/misc/array_contains.pro)

## ARRAY_CROSS

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

     FUNCTION array_cross(l1,l2)
     Purpose:
        returns a 2*n array, where n = n_elements(l1)*n_elements(l2)
        each pair is a combination of l1 and l2
        the total list represents all possible pairings of l1 and l2

     Written by Patrick Cruce

     $LastChangedBy: adrozdov $
     $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
     $LastChangedRevision: 24506 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/array_cross.pro $

(See general/misc/array_cross.pro)

## AVERAGE_STR

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

    FUNCTION:	average_str(data, res)
    PURPOSE:
    	Average data in res second time segments.
    INPUTS:
    	DATA:	array of structures.  One element of structure must be TIME.
    	RES:	resolution in seconds.
    KEYWORDS:
    	NAN:	If set, treat the IEEE NAN value as missing data.
    CREATED BY:	Davin Larson
    LAST MODIFIED:	%W% %E%

(See general/misc/average_str.pro)

## AVSIG

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

     NAME:
         avsig
     PURPOSE:
         Average and dispersion of an array, zeros can be not included,
         handles NaN values correctly
     CALLING SEQUENCE:
         xbar = Avsig(x, sigma = sigma, no_zeros = no_zeros, $
                    sig_mean = sig_mean, dimension = dimension, $
                    fractional = fractional, median = median, $
                    _extra = _extra)
     INPUT:
         x = an array
     OUTPUT:
         xbar = mean, total(x)/n_elements(x)
     KEYWORDS:
         no_zeros= if set, strip out zeros
         get_sigma = if set, calculate the standard deviation
         sigma = standard deviation, sqrt(total((x-xbar)^2/(nx-1)))
         sig_mean = if set return sigma/sqrt(nx), the standard deviation of the
                    mean of the array,
         dimension = the dimension of the array to find the mean in,
                     passed into the total command, it must be a scalar.
         fractional = if set, the fractional error is passed out as sigma,
                      don't use this if zero is a valid value of xbar...
         median = if set, use the median instead of the mean for xbar, it
                  is not recommended fo sigma calculations
     HISTORY:
         12-9-94, jmm, jimm@ssl.berkeley.edu
         2-13-95, jmm, added dimension keyword, switched from ok_zeros to no_zeros
         5-sep-1996, jmm, switched to double precision
         7-oct-2008, jmm, ignores NaN values, added median keyword

(See general/misc/tsub_average.pro)

## BIN1D

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

     Procedure: bin1d

     Purpose:
    Uses histogram to bin data according to array binarr. The elements in binarr
     that are in a specific bin correspond to elements in other arrays (like
     density, temperature etc) and the averages of those are computed within
     each bin. The arrays to be averaged within each bin are passed in
     arrs2bin(NXM) where N is the number of elements of the binarr and M is the
     number of quantities.

     Output: kinbin is K-array of elements (K=number of bins) containing
             number of points within each bin, bincenters a K-array with center
             of bins, averages is KXM array with averages (zero if no points)
             stdevs an KXM array with stdevs about the mean and medians is
             KXM array of medians within each bin

     If any of the keywords maxvarvec or minvarvec is set to a name
     then it is assumed that the first two
     elements of the array "arrs2bin" correspond to the X,Y coordinates of
     a "flow" field. The corresponding data in each cell will be rotated
     in a max/min variance direction. The maxvariance direction will
     be in 2D vector maxvarvec for each cell. The minvariance direction
     will be in 2D vector minvarvec for each cell. The vector norm is the
     variance in the max/min direction, i.e.,
     lambda_i=sqrt(maxvarvec(*,0)^2+maxvarvec(*,1)^2).

     if keyword flag4nodata is set, then points with no data are flags set equal
     to the value passed in, not zeros.

     Usage:
    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
     bin1D,Ygse,[[Ni],[Ti],[Vx],[fx],[Qx],[Eylep]],-15.,15.,1.,kinbin,Ycntrs,avrg,std,med
     Niavg=avrg(*,0)&Tiavg=avrg(*,1)&Vxavg=avrg(*,2)&fxavg=avrg(*,3)&Qxavg=avrg(*,4)&Eylepavg=avrg(*,5)
    ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
     $LastChangedBy: adrozdov $
     $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
     $LastChangedRevision: 24506 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/bin1d.pro $

(See general/misc/bin1d.pro)

## BIN2D

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

     Procedure: bin2d

     Purpose:
     A slightly simpler wrapper for vassilis's routine for 2-d binning
     NOTE: despite the fact that they are keywords either binsize or
     binnum must be set for the proceedure to function

     Inputs:
         x: the x components for the bins. Should be
               an N length array.
         y:  the y components for the bins. Should be an
               N length array.
         arrs2bin: the arrays to be binned should be an NxM
                   sized array or an N sized array
                   (Note: Interpolation to match the N component
                    of input arrays is the responsibility of the
                    user.)

     Keywords:

         binsize: a number or a 2 element array.  If a single number
                  it will be treated as size of the bins for the x dimension
                  and the y dimension.  If it is a two element array, the
                  first element will be the size of the bins on the x
                  axis and the second element will be the size of the
                  bins on the y axis.
                  Warning: Either Binsize or binum must always be set.

         binum: a number of 2 element array.  If a single number it
                 will be treated as the number of bins on for both
                 axes.  If a 2 element array, the first element is
                 number of bins on the x-axis and the second element is
                 the number of bins on the y-axis. (Note: The number of
                 bins actually produced may vary by +- 1) Bins will be
                 evenly spaced over xrange and yrange if provided, and
                 over the range of the data if not.

                 Warning: Either Binsize or binum must always be set.

         xrange,yrange(optional): a 2 element array specifying the min
                 and the max over which binning will occur for the
                 respective axis(default: all data)

         flagnodata(optional): set this keyword to a flag to replace
                 output values with if there is no data. (default: 0)

         averages(output): outputs 2-d array in which the bin averages
                       are stored

         medians(output): outputs 2-d array in which the bin medians are stored

         stdevs(output): outputs 2-d array in which the bin stdevs are stored.

         binhistogram(output): a 2-d histogram of the number of elements
                 used for constructing each cell

         xcenters,ycenters(output): 1-d array of the centers for the bins
                 on each axis.

         minvarvec,maxvarvec(output): Either of these are set arrs2bin
                 will must have dimension M >= 2. The first 2 arrays
                 of the M dimension(ie arrs2bin[*,0] and arrs2bin[*,1]
                 will be treated as corresponding elements of an X,Y flow
                 field. The maxvariance direction will be a 2D vector in
                 maxvarvec for each cell. The minvariance direction
                 will be a 2D vector in minvarvec for each cell. The
                 vector norm is the variance in the max/min direction, i.e.,
                 lambda_i=sqrt(maxvarvec(*,0)^2+maxvarvec(*,1)^2).

     Notes and Warnings:
       1.  Interpolation to match the N component of input arrays is the
           responsibility of the user.

       2.  The number of bins actually produced may vary by +- 1 from the
           number requested by binum

       3.  Either binsize or binum must always be set.

       4.  If both binsize and binum, binsize will take precedent.

      SEE ALSO: bin1d.pro,plotxyz.pro,crib_plotxyz.pro

     $LastChangedBy: egrimes $
     $LastChangedDate: 2019-08-26 16:12:31 -0700 (Mon, 26 Aug 2019) $
     $LastChangedRevision: 27654 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/bin2d.pro $

(See general/misc/bin2d.pro)

## BOX_MEAN

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

    PROCEDURE:   box_mean
    PURPOSE:
      Calculates the mean, median, and standard deviation of a 1-D array
      in a running boxcar.

    USAGE:
      box_mean, var, result=dat

    INPUTS:
           var:     Tplot structure or variable name/number.  Can also
                    simply be an array of numbers.

    OUTPUT:         If var is a tplot variable name/number, then the result
                    is stored as a new tplot variable.  Otherwise, the
                    result is returned via keyword (see below).

    KEYWORDS:
           WIDTH:   Boxcar half-width for calculating mean and sdev.
                    Default = 20 points.  The boxcar is truncated at
                    the beginning and end of the array.

           OUTLIER: Discard points more than this many standard deviations
                    from the mean.  Default = 10.

           RESULT:  Named variable to hold the result.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2020-09-07 12:20:50 -0700 (Mon, 07 Sep 2020) $
     $LastChangedRevision: 29119 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/box_mean.pro $

    CREATED BY:    David L. Mitchell

(See general/misc/box_mean.pro)

## BSHOCK_2

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

     PROCEDURE:
         bowshock_2

     PURPOSE:
         This subroutine calculates the bow shock (X,Y) locations based on
         the Fairfield model (JGR, 1971 Vol 76 Oct-Dec p.6700).
         Aberation of 4 degrees is assumed

     INPUT:
         xmp:   spacecraft position, x component
         ymp:   spacecraft position, y component
                gse or gsm does not matter because mpause assumed
                rotationally symmetric

     OUTPUT:
         It outputs the location of the bow shock down to a very large distance (xmp_max=-300 Re)

     AUTHOR:
         S. Frey

     MODIFICATION:
         Calculates ysh for given xsh and returns only abs(ysh)

     NOTE:
         This provides flexibility with xsh_max

(See general/misc/bshock_2.pro)

## BYTESCALE

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

    FUNCTION:  bytescale(array)
    PURPOSE:   Takes an array or image and scales it to bytes
    INPUT:     array of numeric values.
    KEYWORDS:
       RANGE:  Two element vector specifying the range of array to be used.
            Defaults to the min and max values in the array.
       ZERO:   Forces range(0) to zero
       TOP:    Maximum byte value  (default is !d.table_size-2)
       BOTTOM: Minimum byte value  (default is 1)
       MIN_VALUE: autoranging ignores all numbers below this value
       MAX_VALUE: autoranging ignores all numbers above this value
       MISSING:  Byte value for missing data. (values outside of MIN_VALUE,
         MAX_VALUE range)  If the value is less than 0 then !p.background is used.
       LOG:    sets logrithmic scaling

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

(See general/misc/bytescale.pro)

## CART_TO_SPHERE

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

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

      FUNCTION :   cart_to_sphere.pro
      PURPOSE  :   Transforms from cartesian to spherical coordinates.

      CALLED BY:
                   xyz_to_polar.pro
                   add_df2dp.pro
                   add_df2d_to_ph.pro

      CALLS:       NA

      REQUIRES:    NA

      INPUT:
                   X            :  N-Element array of cartesian X-component data points
                   Y            :  N-Element array of cartesian Y-component data points
                   Z            :  N-Element array of cartesian Z-component data points
                   R            :  Named variable to return the radial magnitudes in
                                     spherical coordinates
                   THETA        :  Named variable to return the poloidal angles (deg)
                   PHI          :  Named variable to return the azimuthal angles (deg)

      EXAMPLES:

      KEYWORDS:
                   PH_0_360     :  IF > 0, 0 <= PHI <= 360
                                   IF = 0, -180 <= PHI <= 180
                                   IF < 0, ***if negative, best guess phi range returned***
                   PH_HIST      :  2-Element array of max and min values for PHI
                                     [e.g. IF PH_0_360 NOT set and PH_HIST=[-220,220] THEN
                                       if d(PHI)/dt is positive near 180, then
                                       PHI => PHI+360 when PHI passes the 180/-180
                                       discontinuity until phi reaches 220.]
                   CO_LATITUDE  :  If set, THETA returned between 0.0 and 180.0 degrees

                   MIN_VALUE    :  Deprecated keyword, maintained for backwards compatibility
                   MAX_VALUE    :  Deprecated keyword, maintained for backwards compatibility

       CREATED BY:  Davin Larson
        LAST MODIFIED:  06/21/2009   v1.1.0
        MODIFIED BY: Lynn B. Wilson III

     $LastChangedBy: adrozdov $
     $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
     $LastChangedRevision: 24506 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/cart_to_sphere.pro $

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

(See general/misc/cart_to_sphere.pro)

## CDF_FILE_NAMES

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

    FUNCTION: cdf_file_names
    PURPOSE:
       Returns an array of filenames within a timerange.
    USAGE:
       files=cdf_file_names(FORMAT,trange=trange,/verbose)
    INPUT:
       FORMAT is a string that will be interpreted as one of two things:
         CASE 1:
            e.g.    FORMAT = '/home/wind/dat/wi/3dp/k0/????/wi_k0_3dp*.cdf'
            if FORMAT contains * or ? then filenames are returned that match that
            pattern and for which YYYYMMDD falls within the specified timerange.
            for example:
            (UNIX only)
         CASE 2:
            e.g.    FORMAT = 'fa_k0_ees_files'
            The name of an indexfile that associates filenames with start and
            end times. If his file is not found, then the environment variable
            getenv('CDF_INDEX_DIR') is prepended and searched for.
            See "make_cdf_index" for information on producing this file.
         SPECIAL NOTE:
            If strupcase(FORMAT) is the name of an environment varible. Then
            the value of that environment variable is used instead.
    KEYWORDS:
         TRANGE:
            Two element array specifying the time range for which data files should
            be returned.  If not provided then "timerange" is called to provide
            the time range.  See also "timespan".
         NFILES:
            Named variable that returns the number of files found.
         VERBOSE:
            Set to print some useful info.
         FILEINFO:  OBSOLETE!
            Set to a named variable that will return a table of file info.
    NOTES:
         UNIX only!

(See general/misc/cdf_file_names.pro)

## CODE_FRAGMENT

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

    NAME:
     code_fragment
    PURPOSE:
     takes a string, where input variables are defined as array_elements
     'qq' and creates a set of tplot commands using those data
    CALLING SEQUENCE:
     code_fragment,  inp_string,  otp_string
    HISTORY:
     13-jun-2007, jmm, jimm@ssl.berkeley.edu

(See general/misc/tuserdef.pro)

## COLORS_COM

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

    COMMON BLOCK  colors_com
    WARNING!  Don't rely on this file to remain stable!
    USE "get_colors" to get color information.
    SEE ALSO:
      "get_colors","bytescale","loadct2"
    CREATED BY: Davin Larson
    File:      96/08/30
    Version:   1.2
    Last Mod:  colors_com.pro

(See general/misc/colors_com.pro)

## CROSSP2

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

    FUNCTION:	crossp2(a,b)
    INPUT:
    	a,b:	real(n,3)	vector arrays dimension (n,3) or (3)
    PURPOSE:
    	performs cross product on arrays
    CREATED BY:
    	J.McFadden	97-3-14
    Modifications
    	J.McFadden	05-2-7 changed first if to "if ndimen(a) eq 1 and ndimen(b) eq 1"

(See general/misc/crossp2.pro)

## CSVECTOR

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

     Function: csvector

     Purpose:  This procedure implements the create,add, and read
               methods for a traditional computer science
               data structure: the vector.The vector
               list of elements of any type and of any length.

               Advantages over array:
               1. store heterogenous elements of any type in a list.
               2. Lists can grow as large as memory and you don't
               need to know how big it will be in advance
               3. You don't need to worry about how the data is stored

               Disadvantages over array:
               1. You can't directly apply operations to the data
               structure
               2. You are forced to use abstraction

               Inputs: arg1:the meaning of the argument varies with syntax
                       arg2:the meaning of the argument varies with syntax

               Keywords: read(optional): set this if you want
                                         to read an element
                         length(optional): set this if you want
                                           to read the length
                         free(optional): set this if you want to free the
                                         vector's memory without
                                         creating a leak, it will return
                                         the number of elements free'd

               Outputs: a vector, the internal representation is
               abstracted, use the methods to access this data structure

               Syntax(each method is followed by examples):

                       create:
                         v = csvector(some_element)
                         v = csvector(1)
                         v = csvector([1,2])
                         v = csvector({a:1,b:2})
                       add:
                         vector = csvector(some_element,vector)
                         v = csvector(1,v)
                         v = csvector('a',v)
                         v = csvector([1,2],v)
                       read:
                         element = csvector(element_index,vector,/read)
                         e = csvector(0,v,/read) ;first element
                         e = csvector(csvector(v,/L)-1,v,/r) ;last element
                       length:
                         length = csvector(vector,/length)
                         l = csvector(v,/l)
                         l = csvector(v,/length)
                       free:
                         num = csvector(vector,/free)
                         temp = csvector(v,/free)

           NOTES: in the event of overflow during add the vector.a
           component will double in size

           Add/Create stores a copy of the element not the element itself

           If you want to do manual lengths and reads you can look
           at the code, but I would recommend against cause you are
           violating abstraction which means the internal representation
           could change and invalidate your code.

           This might be worth writing in O.O. idl as well

           To get type flexibility it uses a pointer for every object
           Thus if you aren't careful this function will eat your
           system memory for breakfast.  Use heap_gc to clean up if you
           are running out of memory.

(See general/misc/csvector.pro)

## CUSTOMTICKFORMATEXP

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

     Procedure: customtickformatexp

     Purpose:
       Forces the format of the numbers on the y-axis to be powers of ten.
       It can be used to set the IDL YTICKFORMAT option of tplot.

     Keywords:
       The three keywords for this function should not be set or used.
       They are required internally for the IDL plot procedure.

     Examples:
       This is how it can be used in SPEDAS:
         options, /def, varname, 'ytickformat', 'customtickformatexp'

       This is how it can be used with the original IDL plot procedure:
         plot, [1, 1e3], YTickFormat='customtickformatexp'
         plot, [1,1e3], YTickFormat='customtickformatexp', YLog=1

     Notes:
       Normally, IDL shows the numbers on the plot axis either as decimals or as powers of ten.
       This is decided by an IDL internal algorithm, but this function can force it
       to be powers of ten.

       This function is a modification of the following function from idlcoyote.com.
       It was originally written by Stein Vidar Hagfors Haugan.
       http://www.idlcoyote.com/tips/exponents.html

     $LastChangedBy: nikos $
     $LastChangedDate: 2024-05-10 13:10:49 -0700 (Fri, 10 May 2024) $
     $LastChangedRevision: 32571 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/customtickformatexp.pro $

(See general/misc/customtickformatexp.pro)

## DEN_FAIRFIELD_NS_MODEL

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

    NAME:
     den_fairfield_ns_model

    PURPOSE:
     This routine calculates the position along the zaxis at a specific
     x and y location.

    INPUT:
     time - string or double format
            double(s)  seconds since 1970
            string(s)  format:  YYYY-MM-DD/hh:mm:ss
     gsm_pos - position vector in GSM coordinates in re (pos[*,3])

    OUTPUT: returns Z displacement of the neutral sheet above or below the XY plane in Re (zgsm of the NS)
            Value is positive if NS is above z=0 gsm plane, negative if below

    KEYWORDS
        sc2NS - if set returns Z displacement from the spacecraft to the neutral sheet
                Value is positive if the NS is northward of the SC location, and negative if below

    HISTORY:

(See general/misc/neutral_sheet.pro)

## DEN_NS_MODEL

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

    NAME:
     den_ns_model

    PURPOSE:
     This program finds the DEN(Displaced Equatorial Neutral) sheet inside
      the magnetopause in different tine and positions. The routine calculates
      the position along the zaxis at a specific location.

    INPUT:
     time - string or double format
            double(s)  seconds since 1970
            string(s)  format:  YYYY-MM-DD/hh:mm:ss
     gsm_pos - position vector in GSM coordinates in re (pos[*,3])

    OUTPUT: returns Z displacement of the neutral sheet above or below the XY plane in Re (zgsm of the NS)
            Value is positive if NS is above z=0 gsm plane, negative if below

    KEYWORDS
        sc2NS - if set returns Z displacement from the spacecraft to the neutral sheet
                Value is positive if the NS is northward of the SC location, and negative if below

    NOTES:
    References:
    (1) DEN(Displaced Equatorial Neutral):
        Xu, R.-L., A Displaced Equatorial Neutral Sheet Surface Observed on ISEE-2
        Satellite,  J. Atmospheric and Terrestrial Phys., 58, 1085, 1991
    (2) Magnetopause model:
        Sibeck, D. G., R. E. Lopez, and R. C. Roelof, Solar wind control of the
        magnetopause shape, location, and motion, J. Grophys. Res., 96, 5489, 1991
    Original Authors of the FORTRAN source code:
    Ronglan XU and Lei LI, Center for Space Sci. and Applied Res.,
    Chinese Academy of Sciences, PO Box 8701, Beijing 100080, China
    E-mail: XURL@SUN.IHEP.AC.CN, XURL@SUN20.CSSAR.AC.CN

    This source code was ported from the original FORTRAN source code into IDL
    The original source code only calculated to 10.05 RE. In this IDL version
    that restriction was increased to 25.

    HISTORY:

(See general/misc/neutral_sheet.pro)

## DIMEN

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

    FUNCTION:   dimen(x)
    PURPOSE:
      Returns the dimensions of an array as an array of integers.
    INPUT:  matrix
    RETURNS:  vector of dimensions of matrix.
       If the input is undefined then 0 is returned.
       if the input is a scaler then 1 is returned.

    SEE ALSO:  "dimen", "data_type", "dimen1", "dimen2"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)dimen.pro	1.6 96/12/16

(See general/misc/dimen.pro)

## DIMEN1

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

    FUNCTION:   dimen1
    INPUT:  matrix
    RETURNS:  scaler int:  size of first dimension  (1 if dimension doesn't exist)

    CREATED BY:	Davin Larson
    LAST MODIFICATION;	@(#)dimen1.pro	1.3 95/08/24

(See general/misc/dimen1.pro)

## DIMEN2

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

    FUNCTION:   dimen2
    INPUT:  matrix
    RETURNS:  scaler int:  size of second dimension  (1 if dimension doesn't exist)

    CREATED BY:	Davin Larson
    LAST MODIFICATION;	@(#)dimen2.pro	1.3 95/08/24

(See general/misc/dimen2.pro)

## DIMEN_SHIFT

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

    FUNCTION:  dimen_shift(x,shift)
    NAME:
      dimen_shift
    PURPOSE:
      Rotate dimensions of a multidimensional array.
      This function is very similar to transpose but works on multi-dimensional
      arrays to shift the dimensions around.
      It has no effect on scalars and one dimensional arrays.
    INPUT:
      x   multi-dimensional array of any type
      shift:  1 or -1  direction of shift.
    CREATED BY: Davin Larson
    LAST MODIFICATION:	@(#)dimen_shift.pro	1.4 98/07/09

(See general/misc/dimen_shift.pro)

## DIVIDE_DATA

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

    PROCEDURE:	divide_data

    PURPOSE:

      Divides successive channels of SST data by powers of 'factor', to

      separate the traces. Also, optionally, multiplies data by an overall factor,

      'conv_factor', to convert units.

    INPUT:		in_name (string), the name of the input TPLOT variable
    			structure.
                   out_name (string), the name of the output TPLOT variable
    			structure.

    KEYWORDS:      factor (float), by which fluxes in successive channels are

                   	divided.
    		conv_factor (optional float), by which fluxes in all channels
    			are multiplied.

    CREATED BY:	Ted Freeman

    FILE:  divide_data.pro

    LAST MODIFIED:  @(#)divide_data.pro	1.2 99/09/01

    NOTES:	  "LOAD_3DP_DATA" and "GET_SPEC" must be called first.

(See general/misc/divide_data.pro)

## DPWRSPC

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

    NAME:
     dpwrspc
    PURPOSE:
        Called with times time and data quantity, dpwrspc returns a dps
        spectrum at frequencies fdps. A Hanning window is applied to the
        input data, and its power is divided out of the returned
        spectrum. A straight line is subtracted from the data to reduce
        spurious power due to sawtooth behavior of a background. UNITS
        ARE (UNITS)^2 WHERE UNITS ARE THE UNITS OF time. fdps is in
        Hz. THUS THE OUTPUT REPRESENTS THE MEAN SQUARED AMPLITUDE OF THE
        SIGNAL AT EACH SPECIFIC FREQUENCY. THE TOTAL (SUM) POWER UNDER
        THE CURVE IS EQUAL TO THE MEAN (OVER TIME) POWER OF THE
        OSCILLATION IN TIME DOMAIN. NOTE: IF KEYWORD notperhz IS SET,
        THEN POWER IS IN UNITS OF NT^2 ELSE IT IS IN UNITS OF NT^2/HZ.
    CALLING SEQUENCE:
     dpwrspc, time, quantity, tdps, fdps, dps, nboxpoints = nboxpoints, $
              nshiftpoints = nshiftpoints, bin = bin, tbegin = tbegin,$
              tend = tend, noline = noline, nohanning = nohanning, $
              notperhz = notperhz
    INPUT:
     time = the time array
     quantity = the function for which you want to obtain a power
                spectrum
    OUTPUT:
     tps = the time array for the dynamic power spectrum, the center time
           of the interval used for the spectrum
     fdps = the frequency array (units =1/time units)
     dps = the power spectrum, (units of quantity)^2/frequency_units
    KEYWORDS:
     nboxpoints = the number of points to use for the hanning window, the
                  default is 256
     nshiftpoints = this is the number of points to shift for each
                    spectrum, the first spectrum will cover the range
                    from 0 to nboxpoints, then next will cover the range
                    from nshiftpoints to nshiftpoints+nboxpoints, etc..
                    the default is 128.
     bin = a binsize for binning of the data along the frequency domain,
           the default is 3
     tbegin = a start time, the default is time[0]
     tend = an end time, the default is time[n_elements(time)-1]
     noline = if set, no straight line is subtracted
     nohanning = if set, then no hanning window is applied to the input
     notperhz = if set, the output units are simply the square of the
                input units
     noTmVariance = if set replaces output spectrum for any windows that
                    have variable cadence with NaNs
     tm_sensitivity = If noTmVariance is set, this number controls
                             how much of a dt anomaly is accepted. The
                             program will flag a time resolution
                             discontinuity if the time resolution dt
                             changes by a value greater than
                             dt/dt_sensitivity; the default
                             is 100.0; i.e. If, for a given spectrum, if
                             there are points with abs(dt[i]-median(dt)
                             Gt median(dt)/100.0, then this will
                             be set to NaN. A larger value means
                             more sensitivity. If you want to flag round-off
                             errors then try a value of 1.0e8.
     fail = if set to a named variable, returns 1 if an error occurs, 0 otherwise

    $LastChangedBy: jimm $
    $LastChangedDate: 2018-06-20 11:26:03 -0700 (Wed, 20 Jun 2018) $
    $LastChangedRevision: 25373 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/dpwrspc.pro $

(See general/misc/dpwrspc.pro)

## DYDT_SPIKE_TEST

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

    NAME:
     dydt_spike_test
    PURPOSE:
     This function checks an array for spikes based on its time
     derivative. This is designed mostly for THEMIS GMAG spikes that
     persist over multiple data points, but should work on single data
     point spikes too.
    CALLING SEQUENCE:
     flag = dydt_spike_test(t0, y0, dydt_lim = dydt_lim, $
                            sigma_y = sigma_y, nsig = nsig, $
                            no_degap = no_degap, pad=pad, $
                            degap_margin = degap_margin, $
                            degap_dt = degap_dt, _extra = _extra)
    INPUT:
     t0 = a time array
     y0 = a data aray, same number of elements as t0
    OUTPUT:
     flag = a bytarr(n_elements(t0)), set to 1 for spikes, 0 for ok data,
            note that NaN values are automatically set to 1
    KEYWORDS:
     dydt_lim =  a value for the max. allowed derivative, the default is
                 to calculate a limiting value from the uncertainty in
                 the data.
     sigma_y = if known, an estimate of the standard deviation in y0
               values. The default is to use sqrt(y), as if you have a
               photon count for data. If you do not know
               this uncertainty in Y, it might be a good idea to use
               dydt_lim.
     nsig = the number of uncertainties in dydt that will be used to
            obtain the limit value at each data point.
     pad = pad the spike flag on either side by this many data points.
     no_degap = By default, the program calls xdegap and xdeflag routines
                to deal with gaps in the data. Set this keyword to avoid
                this.
    DEGAP KEYWORDS:
     nowarning = if set, suppresses warnings
     maxgap = the maximum gap size filled, in seconds
     degap_dt = a time_interval for the degap process, the default is to
                use the minimum of the time resolutions in the data,
                i.e., min(t0[1:*]-t0)
     degap_margin = a margin value for the degap call, the default is to
                    use the minimum of the time resolutions in the data,
                    i.e., min(t0[1:*]-t0)

    HISTORY:
     7-apr-2008, jmm, jimm@ssl.berkeley.edu

    $LastChangedBy: jimm $
    $LastChangedDate: 2013-03-13 12:57:13 -0700 (Wed, 13 Mar 2013) $
    $LastChangedRevision: 11796 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/dydt_spike_test.pro $

(See general/misc/dydt_spike_test.pro)

## ESCAPE_STRING

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

    function: escape_string

    purpose: adds \ to escape a list of characters

    inputs:
      s: The string to be escaped
      list=list: an array of characters to be escaped.  If not set, defaults to the regex set  ['[',']','{','}','\','^','$','.','|','?','*','+','(',')']

     $LastChangedBy: pcruce $
     $LastChangedDate: 2013-06-11 21:39:46 -0700 (Tue, 11 Jun 2013) $
     $LastChangedRevision: 12513 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/escape_string.pro $

(See general/misc/escape_string.pro)

## EULER_ANG_ROT_MATRIX

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

    FUNCTION:  euler_ang_rot_matrix,eulerang  [parameters=par]
    PURPOSE:
      returns rotation matrix given the euler angles
      (This function may be used with the "fit" curve fitting procedure.)

    KEYWORDS:
      PARAMETERS: a structure that contain the parameters that define the rotation
         If this parameter is not a structure then it will be created.

    Written by: Davin Larson

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2020-12-16 13:37:02 -0800 (Wed, 16 Dec 2020) $
     $LastChangedRevision: 29518 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/euler_ang_rot_matrix.pro $

(See general/misc/euler_ang_rot_matrix.pro)

## EXTRACT_TAGS

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

    PROCEDURE:  extract_tags, newstruct, oldstruct
    PURPOSE: takes the named tag elements from oldstruct and puts them into
       newstruct.  This procedure is very useful for creating a structure that
       can be passed onto the PLOT or OPLOT subroutines using the _EXTRA keyword.
       If no tag keywords are included then all tag elements of oldstruct are
       added to newstruct.  The mode keyword PRESERVE is used to prevent the
       overwritting of an existing keyword.
    INPUTS:
      newstruct:  new structure to be created or added to.
      oldstruct:  old structure from which elements are extracted.
    KEYWORDS:  Only one of the following should be given:;
     (TAG KEYWORDS)
      TAGS:  array of strings.  (tag names) to be taken from oldstruct and put in
          newstruct
      EXCEPT: array of strings.  Tag names not to be copied from old to new.
      OPLOT:  (flag)  If set, then TAGS is set to an array of valid keywords
         for the OPLOT subroutine.
      PLOT:   (flag)  If set, then TAGS is set to an array of valid keywords
         for the PLOT subroutine.
      CONTOUR: (flag) If set, then TAGS is set to an array of valid keywords
         for the CONTOUR procedure.   (might not be complete)
    If no KEYWORDS are set then all elements of oldstruct are put into newstruct
      (MODE KEYWORDS)
      PRESERVE: (flag) Prevents the overwritting of an existing, non-null keyword.
         Adds tags to newstruct that were not already there, or if they were there
         and their values were either "" or 0.
    CREATED BY:	Davin Larson
    FILE:  extract_tags.pro
    VERSION  1.21
    LAST MODIFICATION: 02/04/17

(See general/misc/extract_tags.pro)

## FAIRFIELD_NS_MODEL

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

    NAME:
     fairfield_NS_model

    PURPOSE:
     This routine calculates the position along the zaxis at a specific
     x and y location. The Fairfield model is used to this calculation.

    INPUT:
     time - string or double format
            double(s)  seconds since 1970
            string(s)  format:  YYYY-MM-DD/hh:mm:ss
     gsm_pos - position vector in GSM coordinates in re (pos[*,3])

    OUTPUT: returns Z displacement of the neutral sheet above or below the XY plane in Re (zgsm of the NS)
            Value is positive if NS is above z=0 gsm plane, negative if below

    KEYWORDS
        sc2NS - if set returns Z displacement from the spacecraft to the neutral sheet
                Value is positive if the NS is northward of the SC location, and negative if below

    NOTES:
    Reference:
     A statistical determination of the shape and position of the
     geomagnetic neutral sheet,  Journal of Geophysical Research,
     Vol. 85, No A2, pages 775-780, February 1, 1980
     Author - D. Fairfield

    HISTORY:

(See general/misc/neutral_sheet.pro)

## FILE_ARCHIVE

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

     NAME:
       FILE_ARCHIVE
     PURPOSE:
       Archives files by renaming them and optionally moving them to another directory.
       No action is taken if neither ARCHIVE_EXT or ARCHIVE_DIR is set.
     CALLING SEQUENCE:
       FILE_ARCHIVE,'old_file',archive_ext = '.arc'
     KEYWORDS:
       ARCHIVE_EXT = '.arc'
       ARCHIVE_DIR = 'archive_dir/'  ; name of subdirectory to move files into.
       VERBOSE
       DLEVEL
       MAX_ARCS = n  ; max number of archives to produce
     Author:
       Davin Larson  June 2013
     $LastChangedBy: ali $
     $LastChangedDate: 2021-09-24 13:31:21 -0700 (Fri, 24 Sep 2021) $
     $LastChangedRevision: 30317 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/file_archive.pro $

(See general/misc/file_archive.pro)

## FILE_CHGRP

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

    PROCEDURE  file_chgrp

    PURPOSE:  Changes the group ownership of a directory or file.  Caller must own the
              file and be a group member.  Works only in UNIX-like environments.

              This routine is intended for one or a small number of files.  Changing
              the group ownership of a large number of files, or descending though a
              directory structure is much better done in a unix shell.  See the manual
              page for chgrp.

    USAGE:
       file_chgrp, files, group

    INPUTS:
       files:      One or more file names.  Caller must own these files.

       group:      Desired group ownership for files.  Caller must be a member
                   of this group.

    KEYWORDS:
       SUCCESS:    An integer array containing a success flag for each file.

       ERRCODE:    An integer or integer array containing error code(s):

                     0 = normal completion, no errors
                     1 = OS family is not UNIX
                     2 = file name not specified
                     3 = target group not specified
                     4 = caller is not a member of the target group
                     5 = caller does not own file
                     6 = file does not exist

                   For errors that affect the entire operation (1-4), a single
                   code is returned.  Otherwise, an array of codes, one for
                   each file, is returned.

       SILENT:     Suppress messages.  Exit status is returned via ERRCODE.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-04-05 14:33:09 -0700 (Sat, 05 Apr 2025) $
     $LastChangedRevision: 33229 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/file_chgrp.pro $

(See general/misc/file_chgrp.pro)

## FILE_COPY2

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

     Procedure: file_copy2

(See general/misc/file_copy2.pro)

## FILE_DAILYNAMES

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

      Procedure:  FILE_DAILYNAMES
      Author: Davin Larson

(See general/misc/file_dailynames.pro)

## FILE_OPEN

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

    Procedure  FILE_OPEN,type,name
    Purpose:  wrapper for  OPENW, OPENU, OPENR,  FILE_MKDIR
    type must be one of:  'w', 'u', 'r',  'd'  (write, update, read, directory)
       This procedure performs the functions of creating/opening files and creating directories.
       It has several useful features which the regular procedures do not have:
      1)  Non-existant directories are created automatically (with optional mode setting)
      2)  If a non-existant file is opened for update, it is created with OPENW instead of producing an error.
      3)  Files (or directories) can be tested to see if they can be created before actually opening (or creating)
               them (use the TEST keyword). (The returned structure INFO will have the WRITE element set)

    Example 1:   Creating a file for write access:
       FILE_OPEN,'w','/dir1/dir2/dir3/file.tmp',unit=u  ; Will create the director tree if it does not already exist.
    Example 2:   Creating new directories with defined modes:
       FILE_OPEN,'d','/dir1/dir2/dir3', dir_mode="777 ,
         All newly created directories will have the given permissions  (Octal 777)
    Example 3:
       FILE_OPEN,'w','/dir1/dir2/dir3/file.tmp',/test,info=info  ;This will test if the file
              can be created (with given file system permissions) without actually creating the file.
              The returned info stucture can potentially have info.exists eq to 0 and info.write eq 1
    Example 4:
     $LastChangedBy: ali $
     $LastChangedDate: 2023-03-14 18:56:49 -0700 (Tue, 14 Mar 2023) $
     $LastChangedRevision: 31635 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/file_open.pro $

(See general/misc/file_open.pro)

## FILE_RETRIEVE

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

     FUNCTION: FILE_RETRIEVE
     Purpose:
      FILE_RETRIEVE provides a simple, transportable interface to retrieve data files.
      It will download files from a remote web server and copy them into a local (cache) directory
      maintaining the original directory structure. It returns the list of local file names.
      By default files are only downloaded if the remote file is more recent.
      This routine is specifically designed to be used with the same file system that the web server is using to serve files.
      It can look for a MASTER_FILE that indicates the master files system is in use and it then bypasses the download process.
      The file system can be a mix of directories that hold the original files being served as well as a copy of files from external servers.
      The routine correctly handles multiple users sharing (and writing to) the same directories.

      Works on LINUX, MAC, and Windows

    Usage:
     files = file_retrieve(pathnames, [keyword options])

    Suggested usage:

    First get a default structure that specifies where the files come from and where they will be stored locally
      source = file_retrieve(/default_structure,REMOTE_DATA_DIR='http://sprg.ssl.berkeley.edu/data/',master_file='maven/.master')

       ; Retrieve a MAVEN mag 1 sec resolution file for 2014-11-18
      files = file_retrieve( 'maven/data/sci/mag/l2/sav/1sec/2014/11/mvn_mag_l2_pl_1sec_20141118.sav' ,_extra=source)

        ; Retrieve an array of filenames within a time range:
      files = file_retrieve( 'maven/data/sci/mag/l2/sav/1sec/YYYY/MM/mvn_mag_l2_pl_1sec_YYYYMMDD.sav',trange=['2014-12-30','2015-1-3'] ,_extra=source)

        ; Retrieve "globbed files from the SPDF:
        ; A typical URL at SPDF is:  'http://spdf.sci.gsfc.nasa.gov/pub/data/wind/mfi/mfi_h0/2015/wi_h0_mfi_20151008_v03.cdf
            The source of these files is given by:
      source = file_retrieve(/default,  REMOTE_DATA_DIR='http://spdf.sci.gsfc.nasa.gov/pub/data/'  , LOCAL_DATA_DIR = root_data_dir()+'istp/'  )
        ; The path specifiation is given by:
      pathname =      'wind/mfi/mfi_h0/YYYY/wi_h0_mfi_YYYYMMDD_v??.cdf'
      files = file_retrieve(pathname, trange=['2014-12-25','2015-1-4'],_extra=source,/last_version)

      Subsequent calls will be much faster since the files will have been downloaded.

    Arguments:
        pathnames: String or string array with partial path to the remote file.
                   (will be appended to remote_data_dir)
        [newpathnames]: (optional) String or string array with partial path to file destination.
                       (Will be appended to local_data_dir)  (NOT RECOMMENDED TO USE THIS OPTION.

    Keywords:
        REMOTE_DATA_DIR:  String defining remote data directory
                          Pathnames will be appended to this variable.
        LOCAL_DATA_DIR:  String or string array w/ local data directory(s)
                         If newpathnames is set it will be appended to this variable; if not,
                         pathnames will be appended.
        MASTER_FILE:     (file pathname)   if the file: LOCAL_DATA_DIR+MASTER_FILE exists then no download or contact with the server is made. (same effect as NO_SERVER - but evaluated at run time)
        NO_SERVER:       Set this keyword to prevent any contact with a remote server.

        TRANGE:       One or two element array indicating the time range of interest.  If set, then PATHNAMES will be expanded into an array of pathnames using the special character sequences to translate:
             YYYY, yy, MM, DD,  hh,  mm, ss, .f, DOY, DOW, TDIFF are special characters that will be substituted with the appropriate date/time field
             Be especially careful of extensions that begin with '.f' since these will be translated into a fractional second.
             See "time_string"  TFORMAT keyword for more info.

        LAST_VERSION:  If set, then only the last of multiple file versions is downloaded and returned. (used in conjuction with "globbed" pathnames and version numbers.)

        USER_PASS:   Username and password for secured systems;    USER_PASS='username:password'
        ARCHIVE_EXT:  string;   Set archiving extension. (i.e.:  ARCHIVE_EXT= '.arc'). to rename old files instead of deleting them. Prevents accidental file deletion.
        ARCHIVE_DIR:  string;   Set archiving subdirectory. (i.e.:  ARCHIVE_DIR = '.archive/')

        VALID_ONLY:  Set this keyword to return only existing files.

        PRESERVE_MTIME: if set, the local file will be given a modification time that is the same as the modification time of the remote server's file modification time.
           This keyword is ignored on (windows) machines that don't have touch installed. (No cygwin or GNU utils)  Default is 1

        VERBOSE:  Set Verbosity - 0 print almost nothing ,  2 is typical,  4 and above is for debugging.

        if_modified_since:    Set to 0 to force download
      user_agent:   String - User agent text to be sent to web server.
      file_mode:   permissions for new files.   Default is '666'o  ;
      dir_mode:     permissions for newly created directories.  Default is '777'o  ;
      progobj:     Experimental option for a progress bar widget.  (please ignore for now)
      min_age_limit:   Files younger than this age (in seconds) are assumed current (avoids the need to recheck server)  Default is 300
      no_download:0   ,      $    ; similar to NO_SERVER keyword. Should still allow remote directory retrieval - but not files.
      no_update:0     ,      $    ; Set to 1 to prevent contact to server if local file already exists. (this is similar to no_clobber)

    History:
        2012-6-25:  local_data_dir and remote_data_dir accept array inputs
                    with the same # of elements as pathnames/newpathnames   -DO NOT USE this option!

    $LastChangedBy: davin-mac $
    $LastChangedDate: 2019-02-13 17:49:40 -0800 (Wed, 13 Feb 2019) $
    $LastChangedRevision: 26627 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/file_retrieve.pro $

(See general/misc/file_retrieve.pro)

## FILE_RETRIEVE_V

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

    Procedure: file_retrieve_v

    Purpose:  Wrapper for file_retrieve that searches for highest
    available version first, with no need to retrieve remote-index.

    Keywords:

       relpathnames:  the list of relative pathnames that are being
       searched

       version_list(optional): if the user wants to override the default
       version priority list so this function prioritizes versions
       differently, a different version list can be passed in

     $LastChangedBy: kenb-mac $
     $LastChangedDate: 2007-08-21 08:33:59 -0700 (Tue, 21 Aug 2007) $
     $LastChangedRevision: 1463 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/file_retrieve_v.pro $

(See general/misc/file_retrieve_v.pro)

## FILE_SOURCE_DIRNAME

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

    Function: file_source_dirname
    Purpose:  Returns the directory path of the source file which calls this function.
       This is useful for determining the directory of associated data files.
    Warning:  May not work for a precompile version of code.
    Author:  D Larson  2008

(See general/misc/file_source_dirname.pro)

## FILE_TOUCH

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

     FILE_TOUCH
     Purpose:  Wrapper routine for the "touch" program that sets file modification and access times
     USAGE:
        file_touch,'foo',systime(1)-300,/mtime   ; sets mod time to 5 minutes ago
     keywords:
        MTIME    set only modification time(UTC)
        ATIME    set only access time(UTC)
        VERBOSE  sets VERBOSITY of messages (0: error messages only,  6: lots)
     Restrictions:
       #1
       Shell executable "touch" must be in path on local operating system.  This is common on unix systems.
       Windows executable available from: http://sourceforge.net/projects/unxutils/
       If the touch executable is not found then no action is taken.
       Test for executable occurs only once.

       #2 Behavior on Windows is currently untested, and may not be
       consistent with Linux.

       #3 This routine will not work with home directories(~/file_name will not work) on linux variants.  The /noshell option to spawn means that it won't expand home directories into full paths

       #4 Routine will not work for modification date 1970-01-01/00:00:00

       #5 Time should be a UTC time in seconds since 1970.
       Example:  file_touch,'foo',systime(1),/mtime

       #6 This routine primarily for file_http_copy routine.  It
       is not considered stable for general purpose use and the interface
       may change.

    $LastChangedBy: jimmpc1 $
    $LastChangedDate: 2019-02-22 12:24:10 -0800 (Fri, 22 Feb 2019) $
    $LastChangedRevision: 26686 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/file_touch.pro $

(See general/misc/file_touch.pro)

## FIND_CONST_INTERVALS

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

    	Procedure: FIND_CONST_INTERVALS

    	Purpose:  Find intervals within the input array where the data are constant to some tolerance,
    		and return the begin and end indices into the original array for those intervals.

    	Calling Sequence:
    		x = [ 1, 1, 3, 3, 4, 1, 1, 1, 1]
    		ctol = 0.01
    		find_const_intervals, x, nint=nint, ibeg=ibeg, iend=iend, ctol=ctol

    	Arguements:
    		X, ARRAY or any type; will be cast to FLOAT for comparison.
    		NINT, LONG, number of intervals of constantcy found in X.
    		IBEG, IEND, LONG[ nint], arrays of array indices to the begin and end of each constant interval.
    		CTOL, FLOAT, tollerance for constancy of data; ABS(dX) lt CTOL for data to be "constant".

    	Notes:
    		None.

     $LastChangedBy: egrimes $
     $LastChangedDate: 2016-11-14 13:46:58 -0800 (Mon, 14 Nov 2016) $
     $LastChangedRevision: 22356 $
     $URL $

(See general/misc/find_const_intervals.pro)

## FIND_NEAREST_NEIGHBOR

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

     Name:
         find_nearest_neighbor

     Purpose:
         Uses binary search on a time series to find the array element closest to the target time

         Please consider using find_nearest neighbors 2 function as the faster version.
         Also, please consider nn function which provides the nearest index of the time.

     Input:
         time_series: monotonically increasing time series array (stored as doubles)
         target_time: time to search for in the time series (double)

     Keywords:
         quiet: suppress output of errors
         sort: sort the input array prior to searching
         allow_outside: if target_time is outside of target_series, this keyword
             causes this routine to return the last/first element in the array
             (whichever is closer)

     Output:
         Returns the value in time_series nearest to the target_time (as a double)
         Returns -1 if there's an error

     Examples:
         >> print, find_nearest_neighbor([1,2,3,4,5,6,7,8,9], 4.6)
               5

         >> print, find_nearest_neighbor([5,4,3,7,8,2,4,6,7], 7.6, /sort)
               8

     See also:
         find_nearest_neighbor2, nn

     $LastChangedBy: adrozdov $
     $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
     $LastChangedRevision: 24506 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/find_nearest_neighbor.pro $

(See general/misc/find_nearest_neighbor.pro)

## FIND_NEAREST_NEIGHBOR2

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

     Name:
         find_nearest_neighbor2

     Purpose:
         Faster versin of find_nearest_neighbor. Use minimum to search in a time series to find the array element closest to the target time.
         nn function uses similar algorithm providing nearest index in time.

     Input:
         time_series: monotonically increasing time series array (stored as doubles)
         target_time: time to search for in the time series (double)

     Keywords:
         quiet: suppress output of errors
         sort: sort the input array prior to searching
         allow_outside: if target_time is outside of target_series, this keyword
             causes this routine to return the last/first element in the array
             (whichever is closer)

     Output:
         Returns the value in time_series nearest to the target_time (as a double)
         Returns -1 if there's an error

     Examples:
         >> print, find_nearest_neighbor2([1,2,3,4,5,6,7,8,9], 4.6)
               5

         >> print, find_nearest_neighbor2([5,4,3,7,8,2,4,6,7], 7.6, /sort)
               8
     See also:
       find_nearest_neighbor, nn

     $LastChangedBy: adrozdov $
     $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
     $LastChangedRevision: 24506 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/find_nearest_neighbor2.pro $

(See general/misc/find_nearest_neighbor2.pro)

## FIND_STR_ELEMENT

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

     **** OBSOLETE!!! Please use "str_element"instead! ***

    FUNCTION:  find_str_element
    PURPOSE:  find an element within a structure
     Input:
       struct,  generic structure
       name,    string  (tag name)
     Purpose:
       Returns index of structure tag.
       Returns -1 if not found
       Returns -2 if struct is not a structure
    KEYWORDS:
      If VALUE is set to a named variable then  the value of that element is
       returned in it.

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)find_str_element.pro	1.6 95/10/06

(See general/misc/find_str_element.pro)

## FNAME_TO_TIME

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

    PROCEDURE:	fname_to_time, fname, time
    PURPOSE:
    	To translate the name of a standard WIND data file into the starting
    	time of the data.
    INPUT:
    	fname: filename (string) to be translated
    	time: variable in which to return time (double)

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

(See general/misc/fname_to_time.pro)

## GENERIC_APDAT__DEFINE

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

      generic_apdat
      This basic object is the entry point for defining and obtaining all data for all apids
     $LastChangedBy: ali $
     $LastChangedDate: 2024-10-07 17:44:01 -0700 (Mon, 07 Oct 2024) $
     $LastChangedRevision: 32880 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu:36867/repos/spdsoft/trunk/projects/SPP/COMMON/generic_apdat__define.pro $

(See general/misc/generic_apdat__define.pro)

## GENERIC_OBJECT__DEFINE

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

      generic_object
      This basic object can be inherited by other objects and defines some basic functions and operations
     $LastChangedBy: davin-mac $
     $LastChangedDate: 2024-10-15 08:12:13 -0700 (Tue, 15 Oct 2024) $
     $LastChangedRevision: 32887 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/generic_object__define.pro $

     Written by Davin Larson October 2018

(See general/misc/generic_object__define.pro)

## GET_COLORS

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

    FUNCTION:    get_colors
    PURPOSE:   returns a structure containing color pixel values
    INPUT:    none
    KEYWORDS:
       NOCOLOR:  forces all colors to !d.table_size-1.

    Written by: Davin Larson    96-01-31

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-02-03 13:32:18 -0800 (Mon, 03 Feb 2025) $
     $LastChangedRevision: 33109 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/get_colors.pro $

(See general/misc/get_colors.pro)

## GET_COLOR_INDX

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

    FUNCTION:    get_color_indx
    PURPOSE:   returns the color index value closest to the input rgb value.
    INPUT:    color:  3 x N array of rgb values:
                 [[r,g,b],[r,g,b],...]
    KEYWORDS:

     This stand-alone version split off from get_colors so that it can be
     called by other routines before compiling get_colors.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-07-29 17:32:53 -0700 (Fri, 29 Jul 2022) $
     $LastChangedRevision: 30977 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/get_color_indx.pro $

    Written by: Davin Larson    96-01-31

(See general/misc/get_color_indx.pro)

## GET_FILE_NAMES

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

    PROCEDURE:  get_file_names,  fnames
    PURPOSE:
       Gets an array of filenames within a time range
    INPUT:
       fnames:  named variable in which the output array of filenames is placed.
    KEYWORDS:
       TIME_RANGE: Two element vector (double or string) specifying the time range.
         If time range is not set, then "GET_TIMESPAN" will be called
         to get a time range.
       MASTERFILE: Use this keyword to pass in one of the following:
    	1) Name of a masterfile that contains times and associated
    	     	filenames.  The file should have the format:
    yyyy-mm-dd/hh:mm:ss   yyyy-mm-dd/hh:mm:ss   fullpathfilename
         		with one line for each file.
    	     (Hint: for CDF files, the masterfile can be created using the
    	     UNIX program 'kpdfile' or the IDL procedure "MAKE_CDF_INDEX".)
    	2) Full path/file names with wildcard characters to search for
    		relevant files.  Input should be in the form:
    		/path/xxx* for files of form /path/xxx_date.
    	3) The name of a previously defined environment variable containing
    		data in the form of 1 or 2 above.
       ROOT_DIR:   Optional root_directory of the masterfile.  This will properly
          manage operating system dependancies.

    CREATED BY:	Davin Larson
    MODIFIED BY:	Peter Schroeder
    VERSION:	1.26 00/10/04 get_file_names.pro

(See general/misc/get_file_names.pro)

## GET_FILE_NAMES_IND

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

    PROCEDURE:  get_file_names_ind,  fnames
    PURPOSE:
       Gets an array of filenames within a masterfile within a time range
    INPUT:
       fnames:  named variable in which the output array of filenames is placed.
    KEYWORDS:
       TIME_RANGE: Two element vector (double or string) specifying the time range.
         If time range is not set, then "GET_TIMESPAN" will be called
         to get a time range.
       MASTERFILE: Name of a masterfile that contains times and associated
         filenames.  The file should have the format:
    yyyy-mm-dd/hh:mm:ss   yyyy-mm-dd/hh:mm:ss   fullpathfilename
         with one line for each file.
         (Hint: for CDF files, the masterfile can be created using the
         UNIX program 'kpdfile' or the IDL procedure "MAKE_CDF_INDEX".)
       ROOT_DIR:   Optional root_directory of the masterfile.  This will properly
          manage operating system dependancies.
       NO_DUPLICATES:  (N;  integer)
          when set the first N characters of file names are compared and only
          the highest version is returned.

    CREATED BY:	Davin Larson
    VERSION:	@(#)get_file_names_ind.pro	1.1 97/06/23

(See general/misc/get_file_names_ind.pro)

## GET_RT_PATH

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

    NAME:
     get_rt_path
    PURPOSE:
      gets the directory of the calling routine.  Used for reliably looking
      up resource paths across platform
    CALLING SEQUENCE:
      get_rt_path,path
    OUTPUT:
      path: the path of the routine that called get_rt_path

    NOTES:
      This is a general version of specific routines like getctpath.
      Eventually those routines should be replaced with this one.

    $LastChangedBy: pcruce $
    $LastChangedDate: 2009-07-16 16:38:39 -0700 (Thu, 16 Jul 2009) $
    $LastChangedRevision: 6439 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/get_rt_path.pro $

(See general/misc/get_rt_path.pro)

## GRAD

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

    Procedure: Grad

    Purpose:  Calculates the gradient of a 2d or 3d grid in one of two ways.

      In 2d:
      Method1(default):
      gradientX = (grid[x+1,y] - grid[x,y] + grid[x+1,y+1] - grid[x,y+1]) / (2*dx)
      gradientY = (grid[x,y+1] - grid[x,y] + grid[x+1,y+1] - grid[x+1,y]) / (2*dy)

      Method2(leftright):
      gradientX = (grid[x+1,y] - grid[x,y] + grid[x,y] - grid[x-1,y]) / (2*dx)
      gradientY = (grid[x,y+1] - grid[x,y] + grid[x,y] - grid[x,y-1]) / (2*dy)
      This method is actually equivalent to:
      gradientX = (grid[x+1,y] - grid[x-1,y]) / (2*dx)
      gradientY = (grid[x,y+1] - grid[x,y-1]) / (2*dy)

      In 3d:
      Method1(default):
      gradientX = (grid[x+1,y,z] - grid[x,y,z] + grid[x+1,y+1,z] - grid[x,y+1,z] +
                   grid[x+1,y,z+1] - grid[x,y,z+1] + grid[x+1,y+1,z+1] - grid[x,y+1,z+1])
                   / (4*dx)
      gradientY = (grid[x,y+1,z] - grid[x,y,z] + grid[x+1,y+1,z] - grid[x+1,y,z] +
                   grid[x,y+1,z+1] - grid[x,y,z+1] + grid[x+1,y+1,z+1] - grid[x+1,y,z+1])
                   / (4*dy)
      gradientZ = (grid[x,y,z+1] - grid[x,y,z] + grid[x+1,y,z+1] - grid[x+1,y,z] +
                   grid[x,y+1,z+1] - grid[x,y+1,z] + grid[x+1,y+1,z+1] - grid[x+1,y+1,z])
                   / (4*dz)

      Method2(leftright):
      gradientX = grid[x+1,y,z] - grid[x-1,y,z] / (2*dx)
      gradientY = grid[x,y+1,z] - grid[x,y-1,z] / (2*dy)
      gradientZ = grid[x,y,z+1] - grid[x,y,z-1] / (2*dz)

      Method1 will produce an output that is one element smaller in each dimension
      and whose element centers are offset by half the nominal spacing of the grid.

      Method2 will have the same centers and same number of elements as the original
      grid(if the original grid had regular spacing).

    Example:

    Inputs: grid: an NxM grid of points, if it contains NaNs the output may be
                 unpredictable.(or an NxMxP)
            x(optional):  An N length array specifying the positions of the grid points on the x-axis
                 xc should be monotonic and should contain no NaNs.  If unset this routine will
                 assume dx = 1.0
            y(optional):  An M length array specifying the positions of the grid points on the y-axis
                 yc should be monotonic and should contain no NaNs. If unset this routine will
                 assume dy = 1.0
            z:(optional) a P length array specifying the positions of the grid points on
                 the z-axis.  zc should be monotonic and should contain no NaNs. If unset this routine will
                 assume dz = 1.0

    Keywords:
            grad:  The gradient is output through this keyword as an NxMx2 array
            of points.  grad[*,*,0] is the x gradient & grad[*,*,1] is the y gradient

            xout: The positions of the gradient outputs on the x axis are output through this
            keyword as an N length array

            yout: The positions of the gradient outputs on the y axis are output through this
            keyword as an M length array

            xy:  The positions for each output point are passed out as pairs through this
            keyword. The output array will have dimensions N*Mx2,(N times M by 2)

            dxy: The gradient for each point is passed out as pairs through this
            keyword. The output array will have dimensions N*Mx2,(N times M by 2)

            leftright:  Set this keyword if you want to use the second method
            of gradient calculation.

     Notes:
     1. This procedure is not particularly tolerant of NaNs in the input, so
     you should remove them before passing them into this routine.

     2. The output may have slightly different centers/ dimensions as the input.
     This is will definitely be the case if the input array had irregular dimensions.

     3. xy,dxy are useful output format keywords for the plotxyvec routine
     While grad,xout, & yout may be easier for other tasks.

(See general/misc/grad.pro)

## HEXPRINT

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

    hexprint
     :Description:
        Routine that will display hex values of an array of bytes, ints or longs.

     :Params:
        buffer - Either an array of (bytes, ints or longs) or a filename to open

     :Keywords:
        unit
        filename: Set this keyword to filename to dump the results
        decimal:  display in decimal instead of hex.
        start
        nbytes: Set to number of bytes to display. Default is one kilobyte.
        dlevel
        ncolumns

     :Author: davin  Jan 19, 2015

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2024-10-26 11:30:45 -0700 (Sat, 26 Oct 2024) $
     $LastChangedRevision: 32904 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/hexprint.pro $

(See general/misc/hexprint.pro)

## HIGH_PASS_FILTER

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

    NAME:
     high_pass_filter
    PURPOSE:
     subtracts running average from a data array
    CALLING SEQUENCE:
     y = high_pass_filter(array, time_array, no_time_interp=no_time_interp)
    INPUT:
     array = a data array
     time_array = a time array (in units of seconds)
     dt = the averaging time (in seconds)
     no_time_interp = if set, do *not* interpolate the data to the
                      minimum time resolution. The default procedure is
                      to interpolate the data to a regularly spaced grid,
                      and then use ts_smooth to get the running
                      average. This alternative can be slow, but it may
                      save a lot of memory.
     double = if set, do calculation in double precision
                      regardless of input type. (If input data is double
                      calculation is always done in double precision)
     interp_resolution = If time interpolation is being used, set this
                         option to control the number of seconds between
                         interpolated samples.  The default is to use
                         the value of the smallest separation between
                         samples.  Any number higher than this will sacrifice
                         output resolution to save memory. (NOTE: This option
                         will not be applied if no interpolation is being
                         performed because either (1) no_time_interp is set or
                         (2) the sample rate of the data is constant)

     interactive_warning = if keyword is set pops up a message box if there are memory problems and asks
                         the user if they would like to continue
     interactive_varname = set this to a string indicating the name of the quantity to be used in the warning message.

     warning_result = assign a named variable to this keyword to determine the result of the computation
    OUTPUT:
     y = the data array where at each point an average of the data for
     the previous dt has been subtracted.
    HISTORY:
     14-jan-2008, jmm, jimm@ssl.berkeley.edu
     06-feb-2008, teq, teq@ssl.berkeley.edu
     13-mar-2008, jmm, added the default behavior using interpolation
     17-mar-2008, jmm, Gutted and rewritten to use smooth_in_time program
     23-apr-2008, pcruce, Added padding for no_time_interp option, added _extra keyword
     28-apr-2008, pcruce, Added interp_resolution option, added memory warning,
                            mod to guarantee that precision of output is at least as
                            large as precision of input
    $LastChangedBy: adrozdov $
    $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
    $LastChangedRevision: 24506 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/high_pass_filter.pro $

(See general/misc/high_pass_filter.pro)

## HISTBINS

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

    FUNCTION:
       H=histbins(R,XBINS)
    Purpose:
       Returns the histogram (H) and bin locations (XBINS) for an array of numbers.
    Examples:
       r = randomn(seed,10000)
       plot,psym=10, xbins, histbins(r,xbins)             ;Use all defaults.
       plot,psym=10, xbins, histbins(r,xbins ,/shift)     ;shift bin edges.
       plot,psym=10, xbins, histbins(r,xbins, binsize=.2)
       plot,psym=10, xbins, histbins(r,xbins, binsize=.2 ,/shift)
       plot,psym=10, xbins, histbins(r,xbins, range=[-10,10])
    NOTE:
       XBINS is an output, not an input!
    Keywords:  (All optional)  Defaults are based on the size and range of input.
       BINSIZE:  Size of bins.  (recommend double precision!)
       NBINS: force the output array to have this number of elements. (Use with RANGE)
       RANGE: Limits of histogram
       SHIFT :  Keyword that controls the location of bin edges.
          This has no effect if RANGE is defined.
       NORMALIZE: Set keyword to return a normalized histogram (probability distribution).
       REVERSE:  See REVERSE keyword for histogram
       RETBINS:  If set then an array of bins (same size as r) is returned instead.
       EXTEND_RANGE:   if set then the range is extended on either end,  (no effect if range is set)
    See also: "average_hist", "histbins2d"

(See general/misc/histbins.pro)

## HISTBINS2D

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

    Function:
     h = histbins2d(x,y,xval,yval)
    Input:
       x, y, random variables to bin.
    Output:
       h  number of events within bin
       xval, yval,  center locations of the bins.

       Written by Davin larson

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2021-11-16 14:13:26 -0800 (Tue, 16 Nov 2021) $
     $LastChangedRevision: 30425 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/histbins2d.pro $
     $ID: $

(See general/misc/histbins2d.pro)

## INTERP

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

    FUNCTION:   interp(y,x,u)
    PURPOSE:
      Linearly Interpolates vectors with an irregular grid.
      INTERP is functionally the same as INTERPOL, however it is typically
      much faster for most applications.
    USAGE:
      result = interp(y,x,u)
    INPUTS:
           Y:      The input vector can be any type except string.

           X:      The absicissae values for Y.  This vector must have same # of
                   elements as Y.  The values MUST be monotonically ascending
                   or descending.

           U:      The absicissae values for the result.  The result will have
                   the same number of elements as U.  U does not need to be
                   monotonic.
    KEYWORDS:
      NO_CHECK_MONOTONIC:   set this keyword to skip the check for monotonic data.
      INDEX:  Set to named variable to return the index of the closest x less than u.
          (same dimensons as u)
      NO_EXTRAPOLATE:  Set this keyword to prevent extrapolation.
      LAST_VALUE:  Set this keyword to return the last value of y array:  y[index]    (no interpolation performed)
      INTERP_THRESHOLD:  Set to minimum allowed gap size.

    CREATED BY:	Davin Larson  4-30-96
    FILE:  interp.pro
     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-06-04 16:43:03 -0700 (Tue, 04 Jun 2024) $
     $LastChangedRevision: 32686 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/interp.pro $
     $Id: interp.pro 32686 2024-06-04 23:43:03Z dmitchell $

(See general/misc/interp.pro)

## IS_NUMERIC

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

    Name: is_numeric

    Purpose: determines if input string is a validly formatted number.  Does

    Inputs: s:  the string to be checked

    Outputs: 1: if it is validly formatted
             0: if it is not

    Keywords:
        sci_notation: add support for scientific notation (3*10^6)
        decimal: when set, only return 1 for decimal numeric values, such as 1.0, 0.000004,
                 returns 0 for scientific, exponential, engineering, etc. notations

    Notes:  Does not consider numbers in complex notation or numbers with trailing type codes to be valid.

    Examples:
       print,is_numeric('1')
       1
       print,is_numeric('1.23e45')
       1
       print,is_numeric('1.2c34')
       0
       print,is_numeric('1B')
       0
       print,is_numeric('-1.23d-3')
       1
       print,is_numeric('5e+4')
       1
       print,is_numeric('5.e2')
       1
       print,is_numeric('5.e3.2')
       0

       Examples using scientific notation:
       print,is_numeric('4*10^2', /sci)
       1
       print,is_numeric('4*10^-6', /sci)
       1
       print,is_numeric('4*10^(-12)', /sci)
       1
       print,is_numeric('12.3*10^2', /sci)
       1
       print,is_numeric('10^-2.2', /sci)
       1
       print,is_numeric('10.^-2.2', /sci)
       1
       print,is_numeric('12.3*10^', /sci)
       0
       print,is_numeric('12.3*', /sci)
       0

     $LastChangedBy: nikos $
     $LastChangedDate: 2014-05-13 09:46:59 -0700 (Tue, 13 May 2014) $
     $LastChangedRevision: 15109 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/is_numeric.pro $

(See general/misc/is_numeric.pro)

## LOPEZ_NS_MODEL

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

    NAME:
     lopez_NS_model

    PURPOSE:
     This routine calculates the position along the zaxis at a specific
     x and y location. The Lopez model is used for this calculation.

    INPUT:
     time - string or double format
            double(s)  seconds since 1970
            string(s)  format:  YYYY-MM-DD/hh:mm:ss
     gsm_pos - position vector in GSM coordinates in re (pos[*,3])
     kp - kp index value
     mlt - magnetic local time in degrees (0=midnight)

    OUTPUT: returns Z displacement of the neutral sheet above or below the XY plane in Re (zgsm of the NS)
            Value is positive if NS is above z=0 gsm plane, negative if below

    KEYWORDS
        sc2NS - if set returns Z displacement from the spacecraft to the neutral sheet
                Value is positive if the NS is northward of the SC location, and negative if below

    NOTES:
    Reference:
     The position of the magnetotail neutral sheet in the near-Earth Region,
     Geophysical Research Letters, Vol. 17, No 10, pages 1617-1620, 1990
     Author - Ramon E. Lopez

     The lopez model is best used for distances <8.8 RE

    HISTORY:

(See general/misc/neutral_sheet.pro)

## MAKEGIF[2]

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

    PROCEDURE:  makegif, filename
    NAME:
      makegif
    PURPOSE:
      Creates a GIF file from the currently displayed image.
    PARAMETERS:
      filename   filename of gif file to create.  Defaults to 'plot'. Note:
                 extension '.gif' is added automatically
    KEYWORDS:
      ct         Index of color table to load.  Note: will have global
                 consequences!
      multiple   Write multiple gifs to a single file. Subsequent calls to
                 makegif with same filename argument will append to the file.
                 Use /close to close.
      close      close the gif file.  Useful when writing multiple gifs to
                 a single file.  Does not write any image to the file.
      no_expose  Don't print index of current window.

    Restrictions:
      Current device should have readable pixels (ie. 'x' or 'z')

    Created by:  Davin Larson
    FILE:  makegif.pro
    VERSION:  1.11
    LAST MODIFICATION:  02/11/06

(See general/misc/makegif.pro)

## MAKEJPG

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

    PROCEDURE:  makejpg, filename
    NAME:
      makejpg
    PURPOSE:
      Creates a jpg file from the currently displayed image.
    PARAMETERS:
      filename   filename of jpg file to create.  Defaults to 'plot'. Note:
                 extension '.jpg' is added automatically
    KEYWORDS:
      ct         Index of color table to load.  Note: will have global
                 consequences!
      multiple   Does nothing.
      close      Does nothing.
      no_expose  Don't print index of current window.
      mkdir      If set, make the parent directory/directories of the
                 file specified by filename.

    Restrictions:
      Current device should have readable pixels (ie. 'x' or 'z')

    Based almost entirely on makepng by davin larson

    $LastChangedBy: pcruce $
    $LastChangedDate: 2009-11-18 14:36:51 -0800 (Wed, 18 Nov 2009) $
    $LastChangedRevision: 6941 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/makejpg.pro $

(See general/misc/makejpg.pro)

## MAKEPNG

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

    PROCEDURE:  makepng, filename
    NAME:
      makepng
    PURPOSE:
      Creates a PNG file from the currently displayed image.
    PARAMETERS:
      filename   filename of png file to create.  Defaults to 'plot'. Note:
                 extension '.png' is added automatically
    KEYWORDS:
      ct         Index of color table to load.  Note: will have global
                 consequences!
      multiple   Does nothing.
      close      Does nothing.
      no_expose  Don't print index of current window.
      mkdir      If set, make the parent directory/directories of the
                 file specified by filename.
      TIMETAG :  1 - Use current local time
              :  2 - Use current GMT
              :  >2  Use unix time
      WINDOW  :  window number

    Restrictions:
      Current device should have readable pixels (ie. 'x' or 'z')

    Created by:  Davin Larson
     $LastChangedBy: jimm $
     $LastChangedDate: 2023-04-12 11:07:59 -0700 (Wed, 12 Apr 2023) $
     $LastChangedRevision: 31736 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/makepng.pro $

(See general/misc/makepng.pro)

## MAKEPS.PRO

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

    NAME:
     makeps.pro
    PURPOSE:

    OBSOLETE: please use tprint or popen and pclose
     A simple function to reliably and consistently do postscript export
     Right now it will export whatever your last tplot command was(ie
     current plot)
    CALLING SEQUENCE:
     makeps
     -or-
     makeps,'filename'
    INPUT:
     a filename or nothing
    OUTPUT:
     a postscript file to the specified location
     errors, grays out all buttons while processing

    NOTES: Will append a .ps to your filename whether you like it or not
           TODO: add an argument to accept a list of variables

    $LastChangedBy: pcruce $
    $LastChangedDate: 2008-04-14 15:50:24 -0700 (Mon, 14 Apr 2008) $
    $LastChangedRevision: 2719 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/makeps.pro $

(See general/misc/makeps.pro)

## MERGE_STRUCT[1]

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

    PROCEDURE:  rename_struct_tag, struct_i, new_tag_name, index=index, old_tag_name=old_tag_name, remove=remove
    PURPOSE:
     Renames structure element with name "old_tag_name" or index "index",
     to "new_tag_name" in structure "struct_i".

     This is equivalent to replace_tag.pro, but uses str_element and extract_tags.
     It runs slower in merge_struct (0.13 sec) than replace_tag.pro (0.03 sec).

     Input:
       struct_i - structure with tags
       index or old_tag_name - reference to structure tag to rename
     Output:
       struct_i - structure with renamed tag
     Purpose:
       Relabels a tag in the structure.
    KEYWORDS:
      remove: removes the old tag name

    LAST MODIFICATION:
     $LastChangedBy: rjolitz $
     $LastChangedDate: 2025-03-23 18:07:39 -0700 (Sun, 23 Mar 2025) $
     $LastChangedRevision: 33198 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/merge_struct.pro $

(See general/misc/merge_struct.pro)

## MERGE_STRUCT[2]

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

    FUNCTION:  merge_struct(structs, struct_names)
    PURPOSE:
     Find (or add) an element of a structure.

     Input:
       structs, array of structures
       struct_names, array of strings containing names
     Output:
       merged, a structure with all the tag:values
           in supplied structs
     Purpose:
       Merges multiple structures EVEN IF identical tag names
       in multiple structures. will prepend all var names by default.
    KEYWORDS:
      PREPEND_ONLY_IDENTICAL: prepend the identical substructure tags

    CREATED BY:    Rebecca Jolitz
    FILE:  merge_struct.pro
    LAST MODIFICATION:
     $LastChangedBy: rjolitz $
     $LastChangedDate: 2025-03-23 18:07:39 -0700 (Sun, 23 Mar 2025) $
     $LastChangedRevision: 33198 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/merge_struct.pro $

(See general/misc/merge_struct.pro)

## MINMAX

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

    FUNCTION:   minmax,array
    PURPOSE:  returns a two element array of min, max values
    INPUT:  array
    KEYWORDS:
      MAX_VALUE:  ignore all numbers greater than this value
      MIN_VALUE:  ignore all numbers less than this value
      POSITIVE:   forces MINVALUE to 0

    CREATED BY:    Davin Larson
    LAST MODIFICATION:     @(#)minmax.pro	1.2 02/04/17
     $LastChangedBy: orlando $
     $LastChangedDate: 2022-11-28 12:25:39 -0800 (Mon, 28 Nov 2022) $
     $LastChangedRevision: 31300 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/minmax.pro $

(See general/misc/minmax.pro)

## MK_HTML_HELP2

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

     NAME:
    	MK_HTML_HELP2

     PURPOSE:
           Creates a html document from a list of IDL procedures.
    	Given a list of IDL procedure files (.PRO), VMS text library
           files (.TLB), or directories that contain such files, this procedure
           generates a file in the HTML format that contains the documentation
           for those routines that contain a DOC_LIBRARY style documentation
           template.  The output file is compatible with World Wide Web browsers.
           This version is enhanced over the routine supplied by IDL, It will
           also cross reference, print the purpose, and add links to the source
           code.

     CATEGORY:
    	Help, documentation.

     CALLING SEQUENCE:
    	MK_HTML_HELP, Sources, Outfile

     INPUTS:
         Sources:  A string or string array containing the name(s) of the
    		.pro or .tlb files (or the names of directories containing
                   such files) for which help is desired.  If a source file is
                   a VMS text library, it must include the .TLB file extension.
                   If a source file is an IDL procedure, it must include the .PRO
                   file extension.  All other source files are assumed to be
                   directories.  If not provided, searches down directory tree
    		from current directory for files.

         Outfile:	The name of the output file which will be generated without
    		HTML extension.

         If no inputs are given: All directories in the current directory tree
                   are used with the exception of: directories named: 'obsolete'
                   or 'SCCS.'  (UNIX only)

     KEYWORDS:
         TITLE:	If present, a string which supplies the name that
    		should appear as the Document Title for the help.
         FILENAME: Alternative method of specifying Outfile (see above)
         VERBOSE:	Normally, MK_HTML_HELP does its work silently.
    		Setting this keyword to a non-zero value causes the procedure
    		to issue informational messages that indicate what it
    		is currently doing. !QUIET must be 0 for these messages
                   to appear.
         STRICT:   If this keyword is set to a non-zero value, MK_HTML_HELP will
                   adhere strictly to the HTML format by scanning the
                   the document headers for characters that are reserved in
                   HTML (",&,").  These are then converted to the appropriate
                   HTML syntax in the output file. By default, this keyword
                   is set to zero (to allow for faster processing).
         CROSSLINK:If this keyword is set MK_HTML_HELP will create a cross
                   reference between library files.
         CLTURBO:  If this keyword is set to a single character string, then the
                   cross reference procedure will only cross reference lines that
                   contain the character given in CLTURBO.  This greatly increases
                   the speed of the routine.  By default the double quote (") is
                   used
         PRINT_PURPOSE:  If this keyword is set then the first line after PURPOSE:
                   is printed in the output file.
         MASTLIST:	If set, create master list only.  Do not create subdirectory
    		file listings.

     COMMON BLOCKS:
    	None.

     SIDE EFFECTS:
    	A help file with the name given by the Outfile argument is
    	created.

     RESTRICTIONS:
    	The following rules must be followed in formatting the .pro
    	files that are to be searched.
    		(a) The first line of the documentation block contains
    		    only the characters ";+", starting in column 1.
                   (b) There must be a line which contains the string "NAME:",
                       which is immediately followed by a line containing the
                       name of the procedure or function being described in
                       that documentation block.  If this NAME field is not
                       present, the name of the source file will be used.
    		(c) The last line of the documentation block contains
    		    only the characters ";-", starting in column 1.
    		(d) Every other line in the documentation block contains
    		    a ";" in column 1.

           Note that a single .pro file can contain multiple procedures and/or
           functions, each with their own documentation blocks. If it is desired
           to have "invisible" routines in a file, i.e. routines which are only
           for internal use and should not appear in the help file, simply leave
           out the ";+" and ";-" lines in the documentation block for those
           routines.

    	No reformatting of the documentation is done.

     MODIFICATION HISTORY:
           July 5, 1995, DD, RSI. Original version.
           July 13, 1995, Mark Rivers, University of Chicago. Added support for
                   multiple source directories and multiple documentation
                   headers per .pro file.
           July 17, 1995, DD, RSI. Added code to alphabetize the subjects;
                   At the end of each description block in the HTML file,
                   added a reference to the source .pro file.
           July 18, 1995, DD, RSI. Added STRICT keyword to handle angle brackets.
           July 19, 1995, DD, RSI. Updated STRICT to handle & and ".
                   Changed calling sequence to accept .pro filenames, .tlb
                   text librarie names, and/or directory names.
                   Added code to set default subject to name of file if NAME
                   field is not present in the doc header.
           September, 1995, D. Larson. SSL Berkeley. Added crosslink, print_purpose
                   clturbo.
           October 4, 1995, D. Larson. SSL Berkeley. Added link to source file.
           October 3, 1996, F. Marcoline. SSL Berkeley.  Added Alphabet Jumpline.
           October 10, 1996, D. Larson. Added Listing by Directory.
           October 1, 2007, J. McTiernan, allow to work with more than 28
                   directories, dropped obsolete /stream keywords from
                   openw calls.

    FILE:  mk_html_help2.pro
    VERSION 1.26
    LAST MODIFICATION: 99/04/22

(See general/misc/mk_html_help2.pro)

## MPAUSE_2

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

     PROCEDURE:
         mpause_2

     PURPOSE:
         This subroutine calculates the magnetopause (X,Y) locations based on
         the Fairfield model (JGR, 1971).
         Aberation of 4 degrees is assumed

     INPUT:
         xmp:   spacecraft position, x component
         ymp:   spacecraft position, y component
                gse or gsm does not matter because mpause assumed
                rotationally symmetric

     OUTPUT:
        It outputs the location of the magnetopause down to a very large distance (xmp_max=-300 Re)

    sfrey copy mpause.pro but for given xmp
    03-19-09  corrected calculation of ymp_east[west](ilt15) using proper index for xmp~-15
    04-01-09  calculation of ymp_east[west](ilt15) to work for case in15 eq  n_ige15-1

(See general/misc/mpause_2.pro)

## MPAUSE_FLAG

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

     PURPOSE:
     determine spacecraft is inside or outside the magnetopause, according to the Fairfield model (JGR, 1971)
     assume magnetopause is symmetrical around x axis, in other words, magnetopause is a circle in yz plane

     INPUT:
       SC x: spacecraft position (RE)
       SC y: spacecraft position (RE)
       SC z: spacecraft position (RE)
       xmp: magnetopasue position (RE)
       ymp: magnetopasue position (RE)

     OUTPUT:
       mpauseflag: 1 spacecraft inside magnetopause
                   0 spacecraft outside magnetopause

     NOTES:
       To be used with mpause_2

     AUTHOR:
          Jiashu Wu, 2021-08-10

(See general/misc/mpause_flag.pro)

## NDIMEN

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

    FUNCTION: ndimen
    PURPOSE:
      Returns the number of dimensions in an array.
    INPUT:  array
    RETURNS number of dimensions  (0 for scalers,-1 for undefined)

    SEE ALSO:  "dimen", "data_type"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)ndimen.pro	1.6 97/03/10

(See general/misc/ndimen.pro)

## NEAREST_NEIGHBOR

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

    Name:
       nearest_neighbor

    Purpose:
       Finding the nearest neighbors by interpolating the indices for two arrays.
       NANs can be returned when gap/no_extrapolate are used.

    Input:
       time_series: monotonically increasing time series array
       target_time: monotonically increasing time to search for in the time series

    Keywords:
       gap: return NANs if time gap > gap (in seconds), see keyword 'interp_threshold' in "interp"
       no_extrapolate: Set this keyword to prevent extrapolation. See keyword 'no_extrapolate' in "interp"
       silent: No printing
     $LastChangedBy: xussui $
     $LastChangedDate: 2018-12-05 17:23:32 -0800 (Wed, 05 Dec 2018) $
     $LastChangedRevision: 26256 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/nearest_neighbor.pro $

    CREATED BY:    Shaosui Xu  2018-08-15
    FILE: nearest_neighbor.pro

(See general/misc/nearest_neighbor.pro)

## NN

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

    NAME:                  nn
    PURPOSE:               Find the index of the data point(s) nearest to the specified time(s)
                           You can use find_nearest_neighbor2 function to find the nearest time.

                           This routine can be inefficient when operating on large arrays.  In
                           such cases it is better, if possible, to divide the time arrays into
                           smaller segments and work on one segment at a time.

    CALLING SEQUENCE:      ind=nn(data,time)
    INPUTS:                data:  a data structure, a tplot variable name/index,
                              or a time array
                           time:  (double) seconds from 1970-01-01, scalar or array
                                  if not present, "ctime" is called to get time(s)
    OPTIONAL INPUTS:       none
    KEYWORD PARAMETERS:    x, y, & v:  set to named keywords to return the values
    			of the x, y, & v arrays, if applicable

                           progress: If set, then report progress in increments of 1%.
                                     No effect when n_elements(time) lt 100.

    OUTPUTS:               a long scalar index or long array of indicies
                           on failure, returns: -2 if bad inputs,
                                                -1 if nearest neighbor not found
    EXAMPLE:               ctime,times,npoints=2
                           inds=nn('Np',times)
                           get_data,'Np',data=dens & get_data,'Tp',data=temp
                           plot,dens.y(inds(0):inds(1)),temp(inds(0):inds(1))
    LAST MODIFICATION:     @(#)nn.pro	1.8 02/04/17
    CREATED BY:            Frank Marcoline

     See also:
       find_nearest_neighbor2, find_nearest_neighbor

     $LastChangedBy: hara $
     $LastChangedDate: 2018-05-17 14:33:19 -0700 (Thu, 17 May 2018) $
     $LastChangedRevision: 25233 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/nn.pro $

(See general/misc/nn.pro)

## NN2

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

    FUNCTION:   nn2
    PURPOSE:
      Returns the indices of the nearest neighbors in one time array to the
      times in a second array.  This routine is MUCH faster than nn.pro.
      Based on an idea by Shaosui Xu.

      If times outside the range of the first time array are present,
      the index of the first or last element of the first time array
      will be taken as the nearest neighbor.  Use keyword MAXDT to ensure
      reasonable output.

    USAGE:
      i = nn2(time1, time2)

    INPUTS:
       time1:      Input time array, in any format accepted by time double.
                   Must be monotonically increasing or decreasing.

       time2:      Another time array, in any format accepted by time_double,
                   for which you want the indices of the nearest neighbors in
                   time1.

    OUTPUTS:
       i:          Indices of the nearest neighbors in time1 to the elements of
                   time2.  Note that i indexes time1 and has the same number of
                   elements as time2:

                       time1[i] <--> time2

    KEYWORDS:

       MAXDT:      Maximum time difference in seconds between an element of
                   time2 and its nearest neighbor in time1.  If exceeded, the
                   corresponding index will be set to -1.

                   Note: Later versions of IDL allow -1 as a valid array index,
                   so you must filter the output of this routine before using
                   it to index an array.

       VALID:      Remove all occurrences of -1 from array before returning.

       VINDEX:     Indicies of time2 with valid neighbors in time1.

                       time1[i] <--> time2[VINDEX]

                   Only works when VALID is set.

       BADINDEX:   Indices of time2 with no valid neighbor in time1.  This is
                   the complement of VINDEX.  Only works when VALID is set.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2024-08-06 08:29:17 -0700 (Tue, 06 Aug 2024) $
     $LastChangedRevision: 32779 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/nn2.pro $

    CREATED BY:	David L. Mitchell  2018-08-23
    FILE:  nn2.pro

(See general/misc/nn2.pro)

## OPLOT_ERR

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

     PROCEDURE:
    	oplot_err, x, low, high
     PURPOSE:
    	Plot error bars over a previously drawn plot.

(See general/misc/oplot_err.pro)

## PCLOSE

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

    PROCEDURE:   pclose
    INPUT:  none
    PURPOSE: Close postscript file opened with popen, and change device back to
      default.
      If common block string 'printer_name' is set, then file is sent to that
      printer.
    SEE ALSO: 	"print_options"
    		"popen"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)pclose.pro	1.10 99/02/18

(See general/misc/pclose.pro)

## PLOT_POSITIONS

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

    FUNCTION:   plot_positions
    PURPOSE:
      Procedure that will compute plot positions for multiple plots per page.
    Created by Davin Larson

(See general/misc/plot_positions.pro)

## PLOT_THE_EARTH

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

     :PURPOSE:
        Create an Earth graphic.

     :INPUT:
        X - position x
        Y - position y
        R - radius
        Direction - direction of the sun in RAD
        LineColor - color of the line
        FillColor - color of the background
        RenderNum - number of defined vertex in earth half view

        Example: default plot the earth
          PLOT_THE_EARTH, 0, 0, 1, 0, 'k', 'black', 16

     AUTHOR:
       Alexander Drozdov

     VERSION:
      $LastChangedBy: adrozdov $
      $LastChangedDate: 2017-10-25 12:57:57 -0700 (Wed, 25 Oct 2017) $
      $LastChangedRevision: 24214 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/plot_the_earth.pro $

(See general/misc/plot_the_earth.pro)

## POPEN

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

    PROCEDURE: popen, filename
    PURPOSE:
      Change plot device to postscript.
    INPUT:    optional;  if:
      string   :  string used as filename,  '.ps' extension is added automatically
      integer X:  filename set to 'plotX.ps'.  value of x is incremented by 1.
      none:       filename set to 'plot.ps'
    KEYWORDS: See print_options for info.
      COPY:    pass COPY keyword to set_plot
      INTERP:  pass INTERP keyword to set_plot  (default is to have interp off)
      XSIZE:   postscript plot size in the x direction
      YSIZE:   postscript plot size in the y direction
      UNITS:   plot size units (inches or cm)
    SEE ALSO:	"pclose",
    		"print_options",
    		"popen_com"
    HISOTRY:
     4-apr-2008   cg, added optional keywords for postscript plot size
                      units for plot size variables
    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)popen.pro	1.21 98/06/23

(See general/misc/popen.pro)

## POPEN_COM

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

    COMMON BLOCK:	popen_com
    PURPOSE:	Common block for print routines

    SEE ALSO:	"popen","pclose",
    		"print_options"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)popen_com.pro	1.10 97/12/05

(See general/misc/popen_com.pro)

## PRINTDAT

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

    PROCEDURE: printdat,[x]
    PURPOSE:
       Displays information and contents of a data variable. (Very similar to HELP procedure but much more verbose.)
       This routine is most useful for displaying contents of complex
       data structures.
       If printdat is called without arguments then information on all variables
       within the calling routine are displayed.
       POINTER occurences are recursively displayed as well. (only non-null pointers are listed)

    Keywords:
       FULL     Set this keyword to display full variable output.
       NAMES = string:  Optional list of variables to display (Same as for HELP)
       WIDTH:   Width of screen (Default is 120).
       MAX:     Maximum number of array elements to print.  (default is 30)
       NSTRMAX  Maximum number of structure elements to print. (default is 3)
       NPTRMAX  Maximum number of pointer elements to print. (default is 5)
       OUTPUT=string :  named variable in which the output is dumped.
       VARNAME=string : [optional] name of variable to be displayed. (useful if input is an expression instead of a variable)
       RECURSEMAX = integer :  Maximum number of levels to dive into. (Useful for limiting the output for heavily nested structures or pointers)

    Written by Davin Larson, May 1997.

     $LastChangedBy: davin-mac $
     $LastChangedDate: 2018-11-01 15:30:14 -0700 (Thu, 01 Nov 2018) $
     $LastChangedRevision: 26039 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/printdat.pro $

(See general/misc/printdat.pro)

## PRINT_OPTIONS

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

    PROCEDURE: print_options

    PURPOSE:  controls postscript printing options

    KEYWORDS:

      PORT:   print pages in portrait format (default)

      LAND:   print pages in landscape format

      BW:     Use black and white mode  (untested)

      COLOR:  Use Color postscript (default)

      XSIZE:  plot size dimension in the x direction

      YSIZE:  plot size dimension in the y direction

      UNITS:  plot size units (inches or cm)

    FUTURE OPTIONS:

      Ecapsulated postscript format

      changing plotting area

    HISOTRY:

     4-apr-2008   cg, added optional keywords for postscript

                      file size and file size units

    SEE ALSO:	"popen","pclose"

    CREATED BY:	Davin Larson

    LAST MODIFICATION:	@(#)print_options.pro	1.16 97/05/30

(See general/misc/print_options.pro)

## PRINT_TINFO

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

     Procedure:  print_tinfo

     Purpose:
                 prints info on a tplot variable, including dimensions
                 and what each dimension represents

     Input:
                 tplot_name: name of the tplot variable to print info on; also
                 accepts tplot variable #

     Keywords:
                 time:   show the first and last times in the variable
                 help:   show the output of help, /structure, data
                         and help, /structure, dlimits for the variable
     Note:
                 This procedure assumes that there haven't been any modifications
                 to the structure of the tplot variable; i.e., if you transpose the order
                 of the indices in d.Y manually using get_data, store_data,
                 this routine will not know that (and will incorrectly report
                 the 'data format')

     Example:
                 MMS> print_tinfo, 'mms1_hpca_hplus_phase_space_density'
                     *** Variable: mms1_hpca_hplus_phase_space_density
                     ** Structure <221f3690>, 4 tags, length=165121216, data length=165121212, refs=1:
                     X               DOUBLE    Array[20456]
                     Y               DOUBLE    Array[20456, 63, 16]
                     V1              DOUBLE    Array[16]
                     V2              FLOAT     Array[63]
                     Data format: [Epoch, mms1_hpca_ion_energy, mms1_hpca_polar_anode_number]
                     v1: mms1_hpca_polar_anode_number
                     v2: mms1_hpca_ion_energy

     $LastChangedBy: egrimes $
     $LastChangedDate: 2018-02-20 09:49:14 -0800 (Tue, 20 Feb 2018) $
     $LastChangedRevision: 24751 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/print_tinfo.pro $

(See general/misc/print_tinfo.pro)

## PTRACE

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

    FUNCTION: PTRACE()
    PURPOSE: Returns a string that provides the current program location.
    KEYWORDS:
        OPTION:  The value of the option is retained in a common block
               OPTION=0  : returns null string
               OPTION=1  : returns highest level routine name.
               OPTION=2  : returns highest level routine name (indented).
               OPTION=3  : returns all levels

    Usage: Generally useful for debugging code and following code execution.
    Example:
      if keyword_set(verbose) then  print,ptrace(),'X=',x

    Written:  Jan 2007,  D. Larson

(See general/misc/ptrace.pro)

## PTR_EXTRACT

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

    NAME: ptr_extract
    Function: ptrs = ptr_extract(p,EXCEPT=EXCEPT)
    Purpose:
       Recursively searches the input (of any type) and returns an array of all
       pointers found.
       This is useful for freeing pointers contained within some complicated
       structure heirachy or pointer list.
       if no pointers are found then a scaler null pointer is returned.
       This routine ignores object pointers!
    Keywords:
       EXCEPTPTRS = an array of pointers that should not be included in the output.
    Created by Davin Larson. May 2002.

(See general/misc/ptr_extract.pro)

## PUTWIN

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

    PROCEDURE:   putwin
    PURPOSE:
      'Putwin' has been renamed to 'win'.  Putwin is now a simple pass-through
      to win.  The functionality is identical.  Please use the new name.

    USAGE:
      win, num, [mon, ] options=options

    INPUTS:
           See win.pro

    KEYWORDS:
           See win.pro

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-08-04 15:17:20 -0700 (Thu, 04 Aug 2022) $
     $LastChangedRevision: 30996 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/putwin.pro $

    CREATED BY:	David L. Mitchell  2020-06-03

(See general/misc/putwin.pro)

## PUTWIN_COMMON

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

    PROCEDURE:   putwin_common
    PURPOSE:
      Common block for win.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2022-08-04 11:55:06 -0700 (Thu, 04 Aug 2022) $
     $LastChangedRevision: 30993 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/putwin_common.pro $

    CREATED BY:    David L. Mitchell

(See general/misc/putwin_common.pro)

## PWRSPC

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

    NAME:
     pwrspc
    PURPOSE:
        Called with times time and data quantity, PWRSPC returns a power
        spectrum power at frequencies freq. A Hanning window is applied to
        the input data, and its power is divided out of the returned
        spectrum. A straight line is subtracted from the data to
        reduce spurious power due to sawtooth behavior of a background.
        UNITS ARE (UNITS)^2 WHERE UNITS ARE THE UNITS OF quantity. freq
        is in 1/timeunits.
        THUS THE OUTPUT REPRESENTS THE MEAN SQUARED AMPLITUDE OF THE SIGNAL
           AT EACH SPECIFIC FREQUENCY. THE TOTAL (SUM) POWER UNDER THE CURVE IS
           EQUAL TO THE MEAN (OVER TIME) POWER OF THE OSCILLATION IN TIME DOMAIN.
        NOTE: IF KEYWORD notperhz IS SET, THEN POWER IS IN UNITS^2. If notset
               power is (as normal) in UNITS^2/Hz.
    CALLING SEQUENCE:
     pwrspc, time, quantity, freq, power, noline = noline, $
             nohanning = nohanning, bin = bin, notperhz = notperhz
    INPUT:
     time = the time array
     quantity = the function for which you want to obtain a power
                spectrum
    OUTPUT:
     freq = the frequency array (units =1/time units)
     power = the power spectrum, (units of quantity)^2/frequency_units
    KEYWORDS:
     noline = if set, no straight line is subtracted
     nohanning = if set, then no hanning window is applied to the input
     bin = a binsize for binning of the data, the default is 3
     notperhz = if set, the output units are simply the square of the
                input units
     err_msg = named variable that contains any error message that might occur

    $LastChangedBy: jimm $
    $LastChangedDate: 2018-06-20 11:48:31 -0700 (Wed, 20 Jun 2018) $
    $LastChangedRevision: 25376 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/pwrspc.pro $

(See general/misc/pwrspc.pro)

## READ_ASCII_CMDLINE

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

     NAME:
       READ_ASCII_CMDLINE

     PURPOSE:
       Read data from an ASCII file into IDL.

     CATEGORY:
       Input/Output.

     CALLING SEQUENCE:
       data = READ_ASCII(file)

     INPUTS:
       file          - Name of file to read.

     INPUT KEYWORD PARAMETERS:
       record_start      - 1st sequential "record" (see DESCRIPTION) to read.
                   Default = 0 (the first record of the file).
       num_records   - Number of records to read.
                   Default = 0 = Read up to and including the last record.

       template      - ASCII file template (e.g., generated by function
                   ASCII_TEMPLATE) describing attributes of the file
                   to read.  Specific attributes contained in the
                   template may be overridden by keywords below.
                   Default = (see the keywords below).

       start_line    - Number of lines of header to skip.
                   Default (if no template) = 0L. (NOTE: this keyword name
                   has been changed from the IDL read_ascii routine. It was data_start.)
       delimiter     - Character that delimits fields.
                   Default (if no template) = '' = use fields(*).loc.
       missing_value     - Value to replace any missing/invalid data.
                   Default (if no template) = !VALUES.F_NAN.
       comment_symbol    - String identifying comments
                   (from comment_symbol to the next end-of-line).
                   Default (if no template) = '' = no comments.

        field_types  - An array of the field (column) IDL data type. This array can be
                       either a string array or a long array.  Example: ['string', 'double', 'double']
                       or [7,5,5].  Valid types are ['int', 'long', 'float', 'double', 'string',
                       'structure'] or [2, 3, 4, 5, 7, 8]
        field_names  - An array of the names for each field or column. Default values are
                       Field01, Field02, Field03, ..... Fieldnn.
        field_locations - An array of the start positions of each column. Default values are
                       zero and the procedure will try to figure it out.
        field_groups   - An array of fields that are common to a group.

        [Note:  The 'fields' keyword has not been implemented yet.]
       fields        - Descriptions of the data fields, formatted as
                               an array of structures containing the tags:
                                  name  = name of the field (string)
                                  type  = type of field as returned by SIZE (long)
                                  loc   = offset from the beginning of line to
                                          the start of the field (long)
                                  group = sequential group the field is in (int)
                   Default (if no template) =
                                  {name:'field', type:4L, loc:0L, group:0}.

       verbose       - If set, print runtime messages.
                   Default = Do not print them.

     OUTPUT KEYWORD PARAMETERS:
       header        - The header read (string array of length
                   data_start).  If no header, empty string returned.

       count         - The number of records read.

     OUTPUTS:
       The function returns an anonymous structure, where each field in
       the structure is a "field" of the data read (see DESCRIPTION).
       If no records are read, 0 is returned.

     COMMON BLOCKS:
       None.

     SIDE EFFECTS:
       None.

     RESTRICTIONS:
       See DESCRIPTION.

     DESCRIPTION:
       ASCII files handled by this routine consist of an optional header
       of a fixed number of lines, followed by columnar data.  Files may
       also contain comments, which exist between a user-specified comment
       string and the corresponding end-of-line.

       One or more rows of data constitute a "record."  Each data element
       within a record is considered to be in a different column, or "field."
       Adjacent fields may be "grouped" into multi-column fields.
       The data in one field must be of, or promotable to, a single
       type (e.g., FLOAT).

     EXAMPLES:
       ; Using default file attributes.
       data = READ_ASCII(file)

       ; Setting specific file attributes.
       data = READ_ASCII(file, START_LINE=10)

       ; Using a template to define file attributes.
       data = READ_ASCII(file, TEMPLATE=template)

       ; Using a template to define file attributes,
       ; and overriding some of those attributes.
       data = READ_ASCII(file, TEMPLATE=template, START_LINE=10)

       ; Using the ASCII_TEMPLATE GUI to generate a template in place.
       data = READ_ASCII(file, TEMPLATE=ASCII_TEMPLATE(file))

        [Note:  The 'fields' keyword has not been implemented yet.]
       ; An example defining fields by hand.
       fields = REPLICATE({name:'', type:0L, loc:0L, group:0}, 2, 3)
       num = N_ELEMENTS(fields)
       fields(*).name  = 'field' + STRTRIM(STRING(INDGEN(num) + 1), 2)
       fields(*).type  = REPLICATE(4L, num)
       fields(*).loc   = [0L,10L, 0L,15L, 0L,12L]
       fields(*).group = INDGEN(num)
       data = READ_ASCII(file, FIELDS=fields)

        [Note:  The 'fields' keyword has not been implemented yet.]
       ; Another example defining fields by hand.
       void = {sMyStructName, name:'', type:0L, loc:0L, group:0}
       fields = [ [ {sMyStructName, 'frog', (SIZE(''))(1),  0L, 0},   $
                    {sMyStructName, 'bird', (SIZE(0 ))(1), 15L, 1} ], $
                  [ {sMyStructName, 'fish', (SIZE(0.))(1),  0L, 2},   $
                    {sMyStructName, 'bear', (SIZE(0D))(1), 15L, 3} ], $
                  [ {sMyStructName, 'boar', (SIZE(0B))(1),  0L, 4},   $
                    {sMyStructName, 'nerd', (SIZE(OL))(1), 15L, 5} ]  ]
       data = READ_ASCII(file, FIELDS=fields)

     DEVELOPMENT NOTES:

       - See ???,xxx in the code.

       - Error check input 'delimiter' to be a string (not a byte).

       - Implement the 'fields' keyword.

     MODIFICATION HISTORY:
       AL & RPM, 8/96 - Written.
       PCS, 3/99 - Deploy STRTOK and other new commands.  Gain some speed.
       CT, Aug 2003: Free up temp pointers if an error occurs.
       clrussell 10-01-12 - Added five keywords field_count, field_types, field_names,
                            field_locations, field_groups. These keywords were added so
                            the user could specify these mixed data types without having to
                            use a template.

(See general/misc/read_ascii_cmdline.pro)

## REPLACE_TAG

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

     NAME:
           REPLACE_TAG

     PURPOSE:
           Replaces a tag in a structure by another

     CALLING:
           replace_tag, struct, old_tag, new_tag, value

     INPUTS:
    	struct		- the structure to be changed
    	old_tag		- name of the tag to be changed
    	new_tag		- name of the new tag
    			  If set to '', old_tag is deleted from the structure
    	value		- value of the new tag

     RESTRICTIONS:
    	Does not work with named structures

     MODIFICATION HISTORY:
           Alex Schuster, MPIfnF, 8/97 - Written

(See general/misc/replace_tag.pro)

## REVVID

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

    PROCEDURE:   revvid
    PURPOSE:
      Swaps !p.color and !p.background to switch between a light and
      dark background.

    USAGE:
      revvid [, KEYWORD=value]

    INPUTS:
       none:    A simple toggle.

    KEYWORDS:
       WHITE:   Make !p.background the lighter color (often white) and
                !p.color the darker color (often black).

       BLACK:   Make !p.background the darker color (often black) and
                !p.color the lighter color (often white).

    SEE ALSO:
       line_colors to set custom line, background and foreground colors.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2023-03-05 09:49:26 -0800 (Sun, 05 Mar 2023) $
     $LastChangedRevision: 31585 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/revvid.pro $

    CREATED BY:    David L. Mitchell

(See general/misc/revvid.pro)

## ROOT_DATA_DIR

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

    FUNCTION:  root_data_dir
    PURPOSE:  Returns the root data directory used by numerous file retrieval procedures.
         By default it returns either:
              for unix:    '/disks/data/' if it exists,  '~/data/' otherwise
              for Windows: 'c:/data/' if it exists; else 'e:/data/' if it exists,  else 'c:/data/' regardless.

         These data sets can grow to very large size. These defaults are intended to allow multiple
         users to share a common data directory system.

         It is recommended that PC users create a separate partition (e:/data/) to store files so that
         disk backups do not have to include these large (easily replaced) files.

         On unix systems, it is recommended to create a common directory with global write permission
         that multiple users can share. This will reduce internet traffic and disk storage requirements for users
         that use common data files.

    CHANGING THE DEFAULT:
         The default directory can be changed by creating an environment variable: 'ROOT_DATA_DIR'
         Example 1:
              setenv,'ROOT_DATA_DIR=/mydata/'
         Example 2:  A temporary directory:
              setenv,'ROOT_DATA_DIR=' + getenv('IDL_TMPDIR') + 'data/'     ;  trailing '/' IS required.
         If the value of the environment variable ROOT_DATA_DIR is a list of directories, then the first
         existing directory is returned.

         Notes:
         1)  The environment variable should be set prior to running initialization routines (put it in your IDL_STARTUP file)
         2)  The trailing '/' is required!    PC users should also use '/'   (not backslash: '\')
         3)  The total size of all files can grow immense and there is no need to back them up.
                We suggest placing them on a partition that is not backed up
         4)  File storage space can be shared with other users if a commonly accessible data directory is chosen.
         5)  Use a temporary directory if you do not want to permanently store these cached files.
         6)  The root data directory should be writable by all.

    This routine is called by:
        wind_init
        istp_init
        stereo_init
        lanl_spa_load
        thm_config (through thm_init)

    $LastChangedBy: adrozdov $
    $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
    $LastChangedRevision: 24506 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/root_data_dir.pro $

(See general/misc/root_data_dir.pro)

## SCPOT_OVERLAY

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

    NAME:
     scpot_overlay
    PURPOSE:
     Overlays a spacecraft potential (or similar line function) over a
     spectrogram
    CALLING SEQUENCE:
      cvar = scpot_overlay(pvar, svar)
    INPUT:
     pvar = a tplot variable containing the spacecraft potential
     svar = a tplot variable containing a spectrogram
    OUTPUT:
     cvar = a compound tplot variable name containing the combined spectrum
            variable with the SC pot overlaid.
    KEYWORDS:
     sc_line_color = if set, use this color for SCPOT
     sc_line_thick = if set, use this line thickness for SCPOT
     sc_line_style = if set, use this line_style for SCPOT
     scale_scpot = if set, then scale the scpot to the max and min of the
                  spectrogram y-range
     use_yrange = if set, scale using the yrange range for the
                  spectrogram, if not set, use min and max of data.v.
     zero_line = if set, add a line for zero potential
     suffix = suffix for output variable
    HISTORY:
     3-sep-2013, jmm, jimm@ssl.berkeley.edu
     29-jan-2016, jmm, must have lost the suffix keyword, replaced it.
    $LastChangedBy: jimm $
    $LastChangedDate: 2016-01-29 11:44:34 -0800 (Fri, 29 Jan 2016) $
    $LastChangedRevision: 19841 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/scpot_overlay.pro $

(See general/misc/scpot_overlay.pro)

## SETBP

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

    PROCEDURE:  setbp, module
        This procedure will set BREAKPOINTS at all lines within a program module
        file that contain the string:  ";bp"
        A conditional break point is set with  ;bpif  condition statement

    Input:  module (string)
    Purpose:   This is a DEBUGGING tool that is used to set breakpoints.
    Keywords:
        /FUNCTION  Set this keyword if module is a function.

     Author:  Davin Larson 2007

(See general/misc/setbp.pro)

## SHARE_COLORS

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

    PROCEDURE:
      share_colors
    PURPOSE:
      Procedure that allows multiple IDL sessions to share the same color table.
      The procedure should be called in each session before any
      windows are created.
    USAGE:
      Typically this procedure will be put in a startup routine. such as:
      share_colors,first=f
      if f then loadct,39

    KEYWORDS:
      FIRST Named variable that will be set to 1 if this is the
          first session, and set to 0 otherwise.
    SIDE EFFECTS:
      Creates a temporary file with the name 'idl_cmap:NAME' on the users home
      directory where NAME is the name of the display machine.
      This file is deleted upon exiting IDL.
      The procedure is only useful on UNIX for users with a common home directory.

(See general/misc/share_colors.pro)

## SIMPLE_DESPIKE_1D

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

     Simple 1d despike, hacked from SXI_despike
     CALLING SEQUENCE:
     result=simple_despike_1d(image)
     INPUTS:
     image	= 1-D image array (float or integer) to be cleaned
     OUTPUTS:
     result = Cleaned 1-D image array (float)
     KEYWORDS:
     spike_threshold = Median filter threshold for	good pixel map
     width = width of median filter in each direction, default is 3
             points
     use_nan = if set, instead of using the median value as a replacement
               for a spike, insert a NaN value
     jmm, 2013-02-12, testing SVN messaging
     jmm, 2013-02-12, testing SVN messaging, yet again
    $LastChangedBy: jimm $
    $LastChangedDate: 2014-02-12 13:21:15 -0800 (Wed, 12 Feb 2014) $
    $LastChangedRevision: 14361 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/simple_despike_1d.pro $

(See general/misc/simple_despike_1d.pro)

## SMOOTH_IN_TIME

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

    NAME:
     smooth_in_time
    PURPOSE:
     Runs smooth for irregular grids, after regularising grid
    CALLING SEQUENCE:
     ts = smooth_in_time(array, time_array, dt, /backward, /forward,
                      /double, /no_time_interp)
    INPUT:
     array = a data array, can be 2-d (ntimes, n_something_else), the
             first index is smoothed or averaged.
     time_array = a time array (in units of seconds)
     dt = the averaging time (in seconds)
    KEYWORDS:
     backward = if set, perform an average over the previous dt, the
                default is to average from t-dt/2 to t+dt/2
     forward = if set, perform an average over the next dt
     double = if set, do calculation in double precision
                      regardless of input type. (If input data is double
                      calculation is always done in double precision)
     no_time_interp = if set, do *not* interpolate the data to the
                      minimum time resolution. The default procedure is
                      to interpolate the data to a regularly spaced grid,
                      and then use ts_smooth to get the running
                      average. This alternative can be slow.
     smooth_nans = if set, replace Nan values in the input array with the
                   average values calculated using the ts_smooth
                   process. This has not been implemented for the
                   no_time_interp option.
     true_t_integration = if set, subtract 1/2 of the end points of the
                          integration from each value, to obtain the
                          value for an integration over time of the
                          appropriate interval. This has not been
                          implemented for the no_time_interp option.
                          Ths is created for the high_pass_filter.
     interp_resolution = If time interpolation is being used, set this
                         option to control the number of seconds between
                         interpolated samples.  The default is to use
                         the value of the smallest separation between
                         samples.  Any number higher than this will sacrifice
                         output resolution to save memory. (NOTE: This option
                         will not be applied if no interpolation is being
                         performed because either (1) no_time_interp is set or
                         (2) the sample rate of the data is constant)
     dtx_min_fraction = When interp_resolution is not set, the default is to use
                        the value of the smallest separation between
                        samples, with the caveat that this value of smallest
                        separation has to occur relatively
                        frequently. Dtx_min_fraction is used to get an
                        effective value for the minimum of the input time
                        resolution. If a suspected minimum value occurs
                        less than dtx_min_fraction times the peak of a
                        histogram of time resolutions, it is
                        discarded. The default value is 0.10
     interactive_warning = if keyword is set pops up a message box if there are memory problems and asks
                         the user if they would like to continue
     interactive_varname = set this to a string indicating the name of the quantity to be used in the warning message.
     warning_result = assign a named variable to this keyword to determine the result of the computation
     display_object = Object reference to be passed to dprint for output.

    OUTPUT:
     ts = the data array smoothed or averaged

    HISTORY:
     13-mar-2008, jmm, jimm@ssl.berkeley.edu, hacked from
     high_pass_filter.pro and added ts_smooth as the default
     13-mar-2008, ts_smooth is way too slow, just uses smooth.pro now
     6-may-2008, jmm, added sort for input data for cases with
                      non-monotonic time_arrays
     23-apr-2008, pcruce, Added padding for no_time_interp option, added _extra keyword
     28-apr-2008, pcruce, Added interp_resolution option, added memory warning,
                            mod to guarantee that precision of output is at least as
                            large as precision of input
    $LastChangedBy: ghanley $
    $LastChangedDate: 2024-07-03 11:10:37 -0700 (Wed, 03 Jul 2024) $
    $LastChangedRevision: 32716 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/smooth_in_time.pro $

(See general/misc/smooth_in_time.pro)

## SM_NS_MODEL

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

    NAME:
     sm_ns_model

    PURPOSE:
     This routine calculates the NS position along the zaxis at a specific x and y location.

    CALLING SEQUENCE:
     zNS=sm_ns_model(time, position)
     or
     dz2NS=sm_ns_model(time, position, /sc2ns)

    INPUT:
     time - string or double format
            double(s)  seconds since 1970
            string(s)  format:  YYYY-MM-DD/hh:mm:ss
     gsm_pos - position vector in GSM coordinates in re (pos[*,3])

    OUTPUT: returns Z displacement of the neutral sheet above or below the XY plane in Re (zgsm of the NS)
            Value is positive if NS is above z=0 gsm plane, negative if below

    KEYWORDS
        sc2NS - if set returns Z displacement from the spacecraft to the neutral sheet
                Value is positive if the NS is northward of the SC location, and negative if below

    NOTES:
        For the nominal mission, THEMIS used this model for the inner probes

    HISTORY:

(See general/misc/neutral_sheet.pro)

## SPACE_BAR

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

      Procedure: space_bar

      Purpose: generates a horizontal bar stored in a tplot variable
               that is used to adjust the spacing between tplot variables
               in plots

      Arguments:
                 n(positional,required): a double representing the height
                 of the space bar

                 newname(keyword,optional): the name you want the bar to
                 have(default: 'space_bar')

     $LastChangedBy: adrozdov $
     $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
     $LastChangedRevision: 24506 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/space_bar.pro $

(See general/misc/space_bar.pro)

## SPD_DEFAULT_LOCAL_DATA_DIR

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

    NAME:
     spd_default_local_data_dir

    PURPOSE:
     Returns the default data directory for file downloads for varius projects.
     It is used for the GUI configuration settings.
     Simplified replacement for root_data_dir

    CALLING SEQUENCE:
     spd_default_local_data_dir

    INPUT:
     none

    OUTPUT:
     (string) Directory in user's home path

    HISTORY:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2016-11-16 08:19:37 -0800 (Wed, 16 Nov 2016) $
    $LastChangedRevision: 22362 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/spd_default_local_data_dir.pro $

(See general/misc/spd_default_local_data_dir.pro)

## SSL_CHECK_VALID_NAME

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

    NAME:
     ssl_check_valid_name

    PURPOSE:
     Checks a string or array input against another array to find matches.

    CALLING SEQUENCE:
     ok_names = ssl_check_valid_name(names, valid_names)

    INPUT:
     names:  String or string array to be checked
     valid_names:  String array specifying valid values

    OUTPUT:
     return value: String array containing the subset set of input names determined
                   to be valid.  A null string is returned if no matches are found.

    KEYWORDS:
     include_all:  if set, include 'all' in the possible datanames
     ignore_case: if set converts all inputs
     loose_interpretation:  if set, adds wild card '*'s to each end of
                            the input names
     no_warning:  if set, do not issue a warning if the input is invalid
     invalid: returns string array containing non-valid names or a
               null string returned if all match, if the TYPE keyword
               is set then a full error message will be returned
     type:  input string denoting what type of input is being check,
            will be used for error reporting
            (e.g. 'data type', 'probe', ...)

    HISTORY:
     22-jan-2007, jmm, jimm@ssl.berkeley.edu
     11-feb-2007, jmm, Added loose_interpretation keyword
     30-apr-2015,  af, Moved to general branch

     $LastChangedBy: aaflores $
     $LastChangedDate: 2015-04-30 15:31:31 -0700 (Thu, 30 Apr 2015) $
     $LastChangedRevision: 17459 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/ssl_check_valid_name.pro $

(See general/misc/ssl_check_valid_name.pro)

## SSL_CORRELATE_TPLOT

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

     NAME:
          ssl_correlate_tplot

     PURPOSE:
            Identified the amount of shift required to correlate two
            time series tplot variables and stores the result in a tplot
            variable. Only compares 1-d to 1-d data at a time So for example you
            can, compare the fge x and the fgl_x but can't do all three
            at a time.

          Works by binning the timeseries data, then calculating the
          time shift required to maximally correlate each bin.
          When too few points overlap bins are rejected.

     CATEGORY:
           THEMIS-SOC

     CALLING SEQUENCE:
          pro thm_correlate_tplot,var1_name, var1_y_dim, var2_name, var2_y_dim, store_name, correlation_floor = correlation_floor, point_number =  point_number, lag_step_number = lag_step_number, time_step_size = time_step_size, bin_size = bin_size

     INPUTS:

           var1_name: the tplot name of the first variable to be compared

           var1_y_dim: the numerical dimension of the first tplot y_var to look
           at(from 0 to n-1)

           var2_name: the tplot name of the second variable to be
           compared

           var2_y_dim: the numerical dimension of the second tplot y_var
           to look at(from 0 to n-1)

           store_name: the name of a tplot variable in which to store the result

           correlation_floor: optional, if set filters all results where
           the correlation between functions is too poor(default:.9)

           point_number: optional, the minimum number of points of
           overlap necessary to try correlating a bin(default:200)

           lag_step_number: optional, checks plus or minus lag_steps * time steps
           to correlate the vectors (default:64)

           time_step_size: optional, the size of the time step to use when
           interpolating and correlating the vectors, in
           seconds(default:1/128 seconds)

           bin_size: optional, the size of each bin in seconds
           (default:60 seconds)

     OUTPUTS:

           stores the time and the shift values in the select tplot_var

     KEYWORDS:

     COMMENTS: This function will probably die horribly if time
      values are not monotonic.

     PROCEDURE:

     EXAMPLE:

     MODIFICATION HISTORY:
           Written by: Patrick Cruce(pcruce@gmail.com)
           2007-05-24        V1.0

    ;$LastChangedBy: lphilpott $
    $LastChangedDate: 2012-06-25 15:20:30 -0700 (Mon, 25 Jun 2012) $
    $LastChangedRevision: 10638 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/ssl_correlate_tplot.pro $

     KNOWN BUGS:

(See general/misc/ssl_correlate_tplot.pro)

## SSL_CORRELATION_SHIFT

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

     NAME:
          ssl_correlation_shift

     PURPOSE:
          Calculates the shift required to correlate two tme series of
          data.  Does this by binning the timeseries data, then
          calculating the time shift required to maximally correlate each
          bin.  When too few points overlap bins are rejected.

     CATEGORY:
           THEMIS-SOC

     CALLING SEQUENCE:
           lag_time_series = thm_correlation_shift(var1_time_series,var2_time_series)

     INPUTS:

           var1_time_series: a 2xn matrix(column major) of n time/value pairs for var1

           var2_time_series: a 2xn matrix(column major) of n time/value pairs for var2

           n_pts: optional, the minimum number of points of overlap necessary to
           try correlating a bin

           lag_steps: optional, checks plus or minus lag_steps * time steps
           to correlate the vectors

           time_step: optional, the size of the time step to use when
           interpolating and correlating the vectors

           bin_size: optional, the size of each bin in seconds

     OUTPUTS:

           an 3xn matrix(column major) of time/shift/correlation triplets
           or -1L on failure,
           the output n is the number of bins constructed

     KEYWORDS:

     COMMENTS: This function will probably die horribly if time
      values are not monotonic.

     PROCEDURE:

     EXAMPLE:

     MODIFICATION HISTORY:
           Written by:       Jim Lewis
           2007-04-19        Initial version
           Updated by: Patrick Cruce(pcruce@gmail.com)
           2007-05-22        V2.0

    $LastChangedBy: lphilpott $
    $LastChangedDate: 2012-06-25 15:20:30 -0700 (Mon, 25 Jun 2012) $
    $LastChangedRevision: 10638 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/ssl_correlation_shift.pro $

(See general/misc/ssl_correlation_shift.pro)

## SSL_SET_COMPLEMENT

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

    Purpose: Calculates the complement of l2 - l1
              (ie set difference)

    Arguments: l1 subset,l2 superset

    Notes: empty set is -1L
           all inputs must be empty set or arrays
           all outputs will be empty set or arrays
           Arrays must be of homogenous type

(See general/misc/ssl_set_complement.pro)

## SSL_SET_INTERSECTION

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

    Purpose: Performs an intersection of two sets
    Parameters: l1,l2 sets(arrays) for which the intersection is
    calculated

    Returns: -1L on empty set, otherwise intersection of the two sets

    Notes: empty set is -1L
           Input arrays cannot contain repeated values
           all inputs must be empty set or arrays
           all outputs will be empty set or arrays
           Arrays must be of homogenous type

(See general/misc/ssl_set_intersection.pro)

## SSL_SET_SYMBOL

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

    Procedure: ssl_set_symbol

    Purpose:
       1) Set the user defined plotting symbol to be used with psym=8,
                  or
       2) Return a graphics object of the specified symbol

    Calling Sequence:
        ssl_set_symbol, index [,fill=fill] [,size=size] [,fail=fail]
                           [,object=object, [,obj_size=obj_size] [,color=color]]

    Arguments:
      INDEX: Number of the symbol that is desired:
             1: Plus sign
             2: Star
             3: Circle
             4: Diamond
             5: Triangle
             6: Square
             7: X
            42: Lemniscate
      FILL: Flag to fill the symbol (solid)
      SIZE: Number specifying the size of the symbol (default=1.0)
            (not valid if used with OBJECT)
      OBJECT: If called this keyword will return an IDLgrSymbol object
              of the requested type
      OBJ_SIZE: Two element array specifying the returned graphics
                object's x and y size respecively.
      COLOR: The color of the returned graphics object; may be specified as an
             index or as a three-element vector [red, green, blue].
      FAIL: This keword will contain a message if any errors are encountered

    Examples:
      Set to a filled circle:

        ssl_set_symbol, 3, /fill

      Set to an large, unfilled triangle:

        ssl_set_symbol, 5, size = 5

      Get IDLgrSymbol for a filled diamond:

        ssl_set_symbol, 4, obj=obj, /fill

    Caveats:
     Non-fillable symbols such as Asterisks and Plus Signs will not
     return graphics objects if /fill is set.

    Other:
     This routine was primarily developed as a method of drawing
     filled symbols; however, any number of custom symbols may be added
     by specifying the x and y variables in the main case statment.

(See general/misc/ssl_set_symbol.pro)

## SSL_SET_UNION

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

    FUNCTION ssl_set_union(set1,set2)

    Purpose: returns the union of two sets

    Notes: empty set is -1L
           all inputs must be empty set or arrays
           all outputs will be empty set or arrays
           Arrays must be of homogenous type

(See general/misc/ssl_set_union.pro)

## SSL_TIME_CHECK

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

    PROCEDURE:     ssl_time_check.pro
    PURPOSE:   prints information about gaps between timestamps in cdf files
    INPUT:
       dir: The directory in which to search for cdfs
       out: the output directory for the limit files
       LIM: reassign the limit if you want it is a 2 element array
       MNEM: optional regex to filter timestamp mnems
    KEYWORDS:
       none

    COMMENTS: Will check all timestamps for all cdfs in the directory and
    output a seperate file for each type of timestamp.
    File format is:
    timestamp1 timestamp2 gap_size record_number

    currently it signals a gap if a gap is over 180 seconds or negative

    EXAMPLE: ssl_time_check,'/','/dev/null'

    CREATED BY:    Patrick Cruce (pcruce@gmail.com)

    $LastChangedBy: crussell $
    $LastChangedDate: 2012-05-15 14:43:24 -0700 (Tue, 15 May 2012) $
    $LastChangedRevision: 10431 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/ssl_time_check.pro $

(See general/misc/ssl_time_check.pro)

## STRFILTER

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

     $LastChangedBy: nikos $
     $LastChangedDate: 2025-01-06 11:01:53 -0800 (Mon, 06 Jan 2025) $
     $LastChangedRevision: 33045 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/strfilter.pro $

(See general/misc/strfilter.pro)

## STRING_PARSER

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

    NAME:
           string_parser
    PURPOSE:
           Parse strings into components
    CALLING SEQUENCE:
           string_parser, inpx, parse_by, out, output_count
    INPUT:
           inpx     strings to parse
           parse_by        character to parse by
    OUTPUT:
           out     array of substrings
           output_count    number of substrings
    HISTORY:
           Updated 22-April-1993 by Terry Slocum
           Fixed output_count bug, 28-mar-94, JMM
           Gave the ability to use a parse_by string of more than one
           character, jmm 13-jun-2007

(See general/misc/tuserdef.pro)

## STRIPPATH

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

     FUNCTION:
            STRIPPATH

     DESCRIPTION:

           Function that strips off any directory components from a full
           file path, and returns the file name and directory components
           seperately in the structure:
                   {file_cmp_str,file_name:'file',dir_name:'dir'}
           This is only implemented for UNIX at this time.

     USAGE (SAMPLE CODE FRAGMENT):

       ; find file component of /usr/lib/sendmail.cf
           stripped_file = STRIPPATH('/usr/lib/sendmail.cf')

      The variable stripped_file would contain:

           stripped_file.file_name = 'sendmail.cf'
           stripped_file.dir_name  = '/usr/lib/'

     REVISION HISTORY:

       $LastChangedBy: adrozdov $
       $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
       $LastChangedRevision: 24506 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/strippath.pro $
           Originally written by Jonathan M. Loran,  University of
           California at Berkeley, Space Sciences Lab.   Oct. '92
       Updated to use IDL 6.0 features for cross-platform usability.

(See general/misc/strippath.pro)

## STRUCT_VALUE

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

    FUNCTION: struct_value(struc,name,default=default,index=index)
    PURPOSE:  Returns the value of a structure element.
       Function equivalent to the procedure: "STR_ELEMENT"
       if "name" is an array then a new structure is returned with only the named values.
       works with dictionary or hash just like str_element
    Author:  Davin Larson, 2006

(See general/misc/struct_value.pro)

## STR_ELEMENT

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

    PROCEDURE:  str_element, struct,  tagname, value
    PURPOSE:
     Find (or add) an element of a structure.

     Input:
       struct,  generic structure
       tagname,    string  (tag name)
     Output:
       value,  Named variable in which value of the structure element is returned.
     Purpose:
       Retrieves the value of a structure element.  This function will not produce
       an error if the tag and/or structure does not exist.
    KEYWORDS:
      SUCCESS:  Named variable that will contain a 1 if the element was found
         or a 0 if not found.
      INDEX: a named variable in which the element index is returned.  The index
         will be -2 if struct is not a structure,  -1 if the tag is not found,
         and >= 0 if successful.
      ADD_REPLACE:  Set this keyword to add or replace a structure element.
      DELETE:   Set this keyword to delete the tagname.
      CLOSEST:  Set this keyword to allow near matchs (useful with _extra)
      VALUE: (obsolete) alternate method of returning value. (Will not work with recursion)
    Notes:
      1. Value remains unchanged if the structure element does not exist.
      2. If tagname contains a '.' then the structure is recursively searched and
           index will be an array of indices.
      3. If struct is an array then results may be unpredictable.
      4. Elements may be inserted into embedded structures, by including the
           embedded structure name in the tagname string.(example below)

    Examples:
        Does an element exist?
        str_element,my_str,'my_tag_name',SUCCESS=s
        What is an element's value?
        str_element,my_str,'my_tag_name',v
        Add an element
        str_element,my_str,'my_tag_name','value',/add
        Add an element to embedded structure:
        str_element,my_str,'my_substr_name.my_tag_name','value',/add

    Modifications:
      5/7/97: Added recursive searching of structure hierarchy.  D. Larson
      2014-1-20 : Added mulidimensional elements for arrays of structures

    CREATED BY:    Davin Larson
    FILE:  str_element.pro
    VERSION  1.10
    LAST MODIFICATION: 01/10/08
     CREATED BY: Davin Larson
     $LastChangedBy: davin-mac $
     $LastChangedDate: 2023-03-06 23:40:49 -0800 (Mon, 06 Mar 2023) $
     $LastChangedRevision: 31593 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/str_element.pro $

(See general/misc/str_element.pro)

## TAG_NAMES_R

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

     FUNCTION:  TAG_NAMES_R(STRUCTURE, [TYPE=dt] )
     PURPOSE:  Very similar to the TAG_NAMES function but recursively
               obtains all structure names within imbedded structures as well.
     INPUT: STRUCTURE: A structure typically.
                  If input is not a structure then a null string is returned
     KEYWORDS:
           TYPE=var; Named variable in which to return and array of data types.
     RETURNS:  Returns an array of strings

(See general/misc/tag_names_r.pro)

## TCLIP

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

    NAME:
     tclip
    PURPOSE:
     Wrapper for xclip.pro allowing input of tplot variable
     names. IMPORTANT NOTE: The Y values of the tplot variable are
     cliped using tclip, Not Time. TO clip the time range of a tplot
     variable, use the program TIME_CLIP.PRO.
    CALLING SEQUENCE:
     tclip, varnames, amin, amax, _extra=_extra
    INPUT:
     varnames = an array (or scalar) of tplot variable names
     amin, amax = the minumum and maximum values
    KEYWORDS:
     flag = the value that clipped data are  set to, the default is
            -0.0/0.0 (NaN)
     newname = if set,give these names to the clipped data, the
                    default is to append '_clip' to the input names and
                    pass out the names in the newname variables,
                    Unless /overwrite is set. This will not work for wild
                    card input.
     overwrite = if set, write the new data back to the old tplot
                 variables, do not set this with newname
     display_object = Object reference to be passed to dprint for output.
     interior_clip (optional): removes data inside the selected region instead of outside the selected region

    HISTORY:
     2-feb-2007, jmm, jimm.ssl.berkeley.edu

    $LastChangedBy: nikos $
    $LastChangedDate: 2018-11-30 12:04:47 -0800 (Fri, 30 Nov 2018) $
    $LastChangedRevision: 26204 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tclip.pro $

(See general/misc/tclip.pro)

## TCS_IS_ARRAY

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

     NAME:
          tcs_is_array

     PURPOSE:
      Helper function: tests if argument is array, 1L on success 0L on failure

    ;$LastChangedBy: lphilpott $
    $LastChangedDate: 2012-06-25 15:20:30 -0700 (Mon, 25 Jun 2012) $
    $LastChangedRevision: 10638 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tcs_is_array.pro $

(See general/misc/tcs_is_array.pro)

## TDEFLAG

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

    NAME:
     tdeflag
    PURPOSE:
     wapper for xdeflag.pro allowing input of tplot variable names
    CALLING SEQUENCE:
     tdeflag, varnames, method, newname = newname, $
              overwrite = overwrite, _extra = _extra
    INPUT:
     varnames = an array (or scalar) of tplot variable names
     method = set to "remove_nan", this will remove any NaN (or infinite) values
                 from the data (potentially returning shortened or empty arrays)
              set to "repeat", this will repeat the last good value.
              set to "linear", then linear interpolation is used, but for
              the edges, the closest value is used, there is no
              extrapolation
              set to "replace", this will replace the gap values with an
              input variable, input via the keyword, "fillval"
    KEYWORDS:
     flag = all values greater than 0.98 times this value will be deflagged,
            the default is 6.8792e28, Nan's, Inf's are also deflagged
     maxgap = the maximum number of rows that can be filled? the default
               is n_elements(t)
     newname = if set, give these names to the deflagged data, the
                    default is to append '_deflag' to the input names and
                    pass out the names in the newname variables,
                    Unless /overwrite is set
     overwrite = if set, write the new data back to the old tplot
                 variables, do not set this with newname
     display_object = Object reference to be passed to dprint for output.
     fillval = a fill value for the "replace" option. THe default is zero.

    HISTORY:
     2-feb-2007, jmm, jimm.ssl.berkeley.edu

    $LastChangedBy: jimm $
    $LastChangedDate: 2020-09-23 15:50:05 -0700 (Wed, 23 Sep 2020) $
    $LastChangedRevision: 29179 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tdeflag.pro $

(See general/misc/tdeflag.pro)

## TDEGAP

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

    NAME:
     tdegap
    PURPOSE:
     wrapper for xdegap.pro allowing input of tplot variable names
    CALLING SEQUENCE:
     tdegap, varnames, dt=dt, margin=margin, maxgap=maxgap,$
             newname=newname, overwrite=overwrite
    INPUT:
     varnames = an array (or scalar) of tplot variable names
    KEYWORDS:
     dt = the nominal time resolution of the data that will be inserted,
          the default is to choose the median of the input time array
     margin = the margin used to determine if a gap is big enough, the
              default is 0.25 seconds
     maxgap = the maximum gap size that will be allowed to be filled, in
              units of dt. the default is to set this to the max number
              of data points
              (TDEGAP degaps anything that is greater than dt+margin
              and less than maxgap*dt)
     newname = if set,give these names to the degapped data, the
                    default is to append '_degap' to the input names and
                    pass out the names in the newname variables,
                    Unless /overwrite is set
     overwrite = if set, write the new data back to the old tplot
                 variables, do not set this with newname
     (Keywords passed to XDEGAP:)
     nowarning = if set, suppresses warnings
     flag = A numeric user-specified value to use for flagging gaps.
       Defaults to a floating NaN.  If an array is entered, only the
       first element is considered.If a non-numeric datatype is entered,
       its value is ignored.
     onenanpergap = Fill gaps with only one NaN -> useful for conserving memory.
       Also, for reference concerning post-processing, the INTERPOL function
       propagates a single NaN just as it would many NaNs.
     display_object = An object reference to be passed to dprint for output.
     output_message = Passes any messages generated up to the calling procedure as an array of strings

    HISTORY:
     9-apr-2007, jmm, jimm.ssl.berkeley.edu
     10-oct-2008, jmm, Degaps v tags if necessary
     Added output_message keyword Feb-02-2011 prc
    $LastChangedBy: adrozdov $
    $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
    $LastChangedRevision: 24506 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tdegap.pro $

(See general/misc/tdegap.pro)

## TDESPIKE_AE

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

           Name: TDESPIKE_AE

           Purpose:  This routine removes artificial spikes. Note that it is
                     ONLY meant to be used for the calculation of the
                     'THEMIS AE index' in the overview plots.

           Variable:  lower = lower cutoff of spikes to be removed
                      upper = upper cutoff of spikes to be removed

           Keywords:  none

           Example:   tdespike_AE, -2000.0, 1500.0

           Notes:     Written by Andreas Keiling, 29 August 2007

     $LastChangedBy: aaflores $
     $LastChangedDate: 2009-08-03 10:43:14 -0700 (Mon, 03 Aug 2009) $
     $LastChangedRevision: 6516 $
     $URL $

(See general/misc/tdespike_ae.pro)

## TDPWRSPC

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

    NAME:
     tdpwrspc
    PURPOSE:
     wapper for dpwrspc.pro allowing input of a tplot variable name
    CALLING SEQUENCE:
     tdpwrspc, varname, newname=newname,_extra=_extra
    INPUT:
     varname = one tplot variable name
    KEYWORDS:
     newname = if set,give this name to the new data, the
               default is to append '_dpwrspc' to the input name and
               pass out the name in the newname variable,
               Unless /overwrite is set. Note that if a multi-dimensional
               variable is passed in, the newname keyword is not used.
     overwrite = if set, write the new data back to the old tplot
                 variable, do not set this with newname

     nboxpoints = the number of points to use for the hanning window, the
                  default is the closest power of 2 less than the number of points divided by 32
     nshiftpoints = the number of points to shift the hanning window per-step, the default in nboxpoints/2

     bin = a binsize for binning of the data along the frequency domain, the default is 3
     tbegin = a start time, the default is time[0]
     tend = an end time, the default is time[n_elements(time)-1]
     noline = if set, no straight line is subtracted
     nohanning = if set, then no hanning window is applied to the input
     notperhz = if set, the output units are simply the square of the
                input units
    HISTORY:
     27-mar-2007, jmm, jimm.ssl.berkeley.edu
     10-apr-2007, jmm, fixed 2 bugs wrt structure definition

     $LastChangedBy: egrimes $
     $LastChangedDate: 2023-04-25 12:00:09 -0700 (Tue, 25 Apr 2023) $
     $LastChangedRevision: 31797 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tdpwrspc.pro $

(See general/misc/tdpwrspc.pro)

## THEMIS_NS_MODEL

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

    NAME:
     themis_NS_model

    PURPOSE:
     This routine calculates the position along the zaxis at a specific
     x and y location. The themis model is used for this calculation.
     The themis model uses z-sm (converted from z-gsm) for the inner probes
     and the Hammond model for the outer probes.

    INPUT:
     time - string or double format
            double(s)  seconds since 1970
            string(s)  format:  YYYY-MM-DD/hh:mm:ss
     gsm_pos - position vector in GSM coordinates in re (pos[*,3])

    OUTPUT: returns Z displacement of the neutral sheet above or below the XY plane in Re (zgsm of the NS)
            Value is positive if NS is above z=0 gsm plane, negative if below

    KEYWORDS
        sc2NS - if set returns Z displacement from the spacecraft to the neutral sheet
                Value is positive if the NS is northward of the SC location, and negative if below

    NOTES;
     Reference:
     The themis model uses z-sm (converted from z-gsm) for the inner probes
     and the Hammond model (default) for the outer probes. The algorithm can be found
     in ssllib neutralsheet.pro.

    HISTORY:

(See general/misc/neutral_sheet.pro)

## THIGH_PASS_FILTER

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

    PROCEDURE: thigh_pass_filter, varname, dt, newname = newname
    PURPOSE:
     Uses high_pass_filter to calculate a running average of the input data and
       store the data with the running average subtracted in an output tplot variable.

    INPUT:
     varname = variable passed to get_data, example - thg_mag_ccnv
     dt = the averaging time (in seconds)
    KEYWORDS:
     newname: set output variable name
     no_time_interp:  Set to save memory by preventing interpolation of time
                      array when smoothing data before subtraction.
                      This option will probably be significantly slower.
     double:  Set so operation is performed at double precision
                      regardless of input type. (If input data is double
                      calculation is always done in double precision)
     interp_resolution = If time interpolation is being used, set this
                         option to control the number of seconds between
                         interpolated samples.  The default is to use
                         the value of the smallest separation between
                         samples.  Any number higher than this will sacrifice
                         output resolution to save memory. (NOTE: This option
                         will not be applied if no interpolation is being
                         performed because either (1) no_time_interp is set or
                         (2) the sample rate of the data is constant)

     interactive_warning = pops up a message box if there are memory problems and asks
                         the user if they would like to continue
     warning_result = assign a named variable to this keyword to determine the result of the computation
     display_object = Object reference to be passed to dprint for output.

    HISTORY:
     14-jan-2008, jmm, jimm@ssl.berkeley.edu
     06-feb-2008, teq, teq@ssl.berkeley.edu
     23-Apr-2009, pcruce, pcruce@igpp.ucla.edu, Added extra keyword support
     28-apr-2008, pcruce, Added interp_resolution option, added memory warning,
                            mod to guarantee that precision of output is at least as
                            large as precision of input
    $LastChangedBy: adrozdov $
    $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
    $LastChangedRevision: 24506 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/thigh_pass_filter.pro $

(See general/misc/thigh_pass_filter.pro)

## TIMEBOX_MEAN

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

    PROCEDURE:   timebox_mean
    PURPOSE:
      Calculates the mean, median, and standard deviation of a 1-D array
      for the input time resolution.

    USAGE:
      timebox_mean, var, resolution = resolution, result=dat

    INPUTS:
           var:     Tplot-like data structure {x:unix time, y:data}
                    or variable name/number.

    OUTPUT:         If var is a tplot variable name/number, then the result
                    is stored as a new tplot variable.  Otherwise, the
                    result is returned via keyword (see below).

    KEYWORDS:
           RESOLUTON: time resolution of average in seconds, the default
                      is one day. 86400.0 seconds

           OUTLIER: Discard points more than this many standard deviations
                    from the mean.  Default = 10.

           RESULT:  Named variable to hold the result.
           TIME_RANGE: the input time range, the default is
                       to obtain the time range from the data
           TIME_BINS_IN: Use these bins for input, either a 2Xnbins array
                         or 1D array of Nbins+1, The 2Xnbins array option
                         allows for discontinuous binning.
    HISTORY:
           Hacked from box_mean.pro, jmm, jimm@ssl.berkeley.eud

     $LastChangedBy: jimm $
     $LastChangedDate: 2019-10-16 14:04:32 -0700 (Wed, 16 Oct 2019) $
     $LastChangedRevision: 27880 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/timebox_mean.pro $

(See general/misc/timebox_mean.pro)

## TIME_AVERAGE

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

     Function: time_average

     Calculates a bin based average over time series data
     Uses a histogram internally so it should be pretty quick

     Arguments:
           time: the time array for the input timeseries
           data: the data array for the input timeseries
           newtime(optional): named variable in which to return the times
                  for each bin upon which an average is calculated
           trange(optional): a time range over which the average is
           performed
           resolution(optional): the size of each bin in seconds
           ret_total(optional): named variable in which totals for each
           bin are returned
           ret_min(optional): named variable in which mins for each bin
           are returned
           ret_med(optional): named variable in which medians for each
           bin are returned

     $LastChangedBy: aaflores $
     $LastChangedDate: 2012-01-24 09:39:41 -0800 (Tue, 24 Jan 2012) $
     $LastChangedRevision: 9596 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/time_average.pro $

(See general/misc/time_average.pro)

## TIME_CLIP

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

    Procedure: time_clip

    Purpose: clips a tplot variable between a start time and an end time

    Inputs:   tplot_var_name: the name of the variable to be clipped

              start_time: the start time for the clipping(double or string)

              end_time: the end time for the clipping(double or string)

    Keywords:
              newname(optional): the name of the output tplot variable
                       otherwise it will be tplot_var_name+'_tclip'

              tvar(optional): set this keyword and start_time and
              end_time will be interpreted as the names of tplot variables
              The start and end times will then be taken from the first
              and last component of the tplot variables listed

              replace(optional): set this to replace the tplot variable,  rather than create
              a new one

              error(optional): set this to a named variable to return the
              error status of the function, it will return 0 for no error
              and 1 to signal an error.  This may be set to true even if
              the error was non fatal.  Also if you are using globbing
              to modify many tplot variables it will signal an error if
              any of the variables failed

              interior_clip(optional): removes data inside the selected region instead of outside the selected region

              nan_replace(optional): instead of clipping replaces data with NaNs

              examples:
                     time_clip,'thb_fgs_gsm','2007-03-23/10:00:00','2007-03-23/12:00:00',newname='thb_fgs_gsm_10t12clip'
                     time_clip,'thb_peem_velocity','thb_fgs_gsm',thb_fgs_gsm',/tvar

     $LastChangedBy: adrozdov $
     $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
     $LastChangedRevision: 24506 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/time_clip.pro $

(See general/misc/time_clip.pro)

## TIME_INTERVALS

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

     FUNCTION: TIME_INTERVALS
     Purpose:
      TIME_INTERVALS will generate regular time intervals given a time range
         This routine was specifically designed to aid in producing file names based on time ranges
      KEYWORDS:
        TRANGE:  Time range - scaler or two element array. double, string or structure  (see time_double(), time_string, time_struct)

         Generated times will be LESS than or equal to TRANGE[0]  and less than TRANGE[1]   (may be scaler)

        RESOLUTION:    resolution in seconds
        MINUTE_RES:    Forces RESOLUTION to 60
        HOURLY_RES:    Forces RESOLUTION to 3600
        DAILY_RES:     Forces RESOLUTION to 3600*24L
        MONTHLY_RES:   resolution in months.
        YEARLY_RES:    resolution in years

        PHASE_SHIFT:   scaler between 0. and 1. - shifts the starting phase.

        TIMES:  named variable that will return the double precision array of values (same as output if tformat is not specified))

         array of times used to generate the output strings. (output if any of above resolutions and TRANGE is set)
           TIMES is an output if TRANGE is set and any of the resolutions are set.
           Otherwise is can be used as an input.

        TFORMAT:  (string) format the output and return as a string  (See TIME_STRING(t,TFORMAT=tformat))

      Examples:

      times = time_intervals(trange=['2014-12-28','2015-1-3'],/daily_res)

      filenames = time_intervals(tformat='data/YYYY/MM/example_yyMMDD_v??.dat',trange=['2015','2016'] ,daily_res=7,phase_shift=4/7.,times=t)

      Generate weekly filenames that start on Mondays:
      tr =['2014-12-1','2015-1-31']
      filenames = time_intervals(trange=tr,daily=7,phase_shift=4/7.,times=t,tformat='file_yyMMDD')+time_intervals(tformat='_yyMMDD_v??.dat',times=t+3600d*24*7)

    $LastChangedBy: adrozdov $
    $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
    $LastChangedRevision: 24506 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/time_intervals.pro $

(See general/misc/time_intervals.pro)

## TIME_STAMP

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

    PROCEDURE:   time_stamp,charsize=charsize
    PURPOSE:
         Prints a time stamp along the lower right edge of the current plot box
    KEYWORDS:
         CHARSIZE:  The character size to be used.  Default is !p.charsize/2.
         ON:        if set, then timestamping is turned on. (No other action taken)
         OFF:       if set, then timestamping is turned off. (Until turned ON)

(See general/misc/time_stamp.pro)

## TIME_TICKS

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

    FUNCTION:  time_tk_str = time_ticks(timerange,offset)
    NAME:
      time_ticks
    PURPOSE:
      Returns a structure that can be used to create time ticks for a plot.
      See "timetick" for more info
    INPUT:
      timerange: Two element vector specifying the time range of the plot
          this input can be obtained from: "time_double", "time_struct"
          or "time_string"
      offset: named variable in which offset time is placed.
    KEYWORDS:
      NUM_LAB_MIN:   minimum number of labels for bottom axis.

    OUTPUT:
      a structure that can be used with the _EXTRA keyword of the PLOT routine

    See Also: "box", "tplot"

     NOTES:

         The returned time_tk_str has tags named so that it can be used
         with the special _EXTRA keyword in the call to PLOT or OPLOT.

         The offset value that is returned from timetick must be
         subtracted from the time-axis data values before plotting.
         This is to maintain resolution in the PLOT routines, which use
         single precision floating point internally.  Remember that if
         the CURSOR routine is used to read a cursor position from the
         plot, this offset will need to be added back to the time-axis
         value to get seconds since  1970-01-01/00:00:00.

    NOTE:
      This routine is an enhanced version of the routine "timetick"
      See this routine for more info on usage

    WARNING!:
      This routine does not yet work on very small time scales.

    CREATED BY:	Davin Larson  Oct 1996
    FILE:  time_ticks.pro
    VERSION:  1.16
    LAST MODIFICATION:  02/04/17

(See general/misc/time_ticks.pro)

## TINTERPOL

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

    Function: tinterpol

    Purpose:
    Wrapper for tinterpol_mxn.  Performs interpolation on tplot variables.
    Interpolates xv_tvar to match uz_tvar.  Can also interpolate with non-tvar types
    and return non-tvar types. (Helpful for interpolating matrices and time-series vectors)

    This function works on any n or nxm dimensional vectors. Interpolation always occurs along first dimension(time)

    Arguments:
                xv_tvar = tplot variable to be interpolated, the y component
                can have any dimesions, can use globbing to interpolate
                many values at once
                uses x component for x abcissa values
                Can also pass in a struct with the same format as the
                data component for a tplot variable:
                {x:time_array,y:data_array,v:optional_y_axis_abcissas}

                uz_tvar = tplot variable that V will be fit to
                uses x component for u abcissa values.  Can also
                pass in an array of time values rather than a tplot
                variable.

                newname = output tplot variable name(optional) defaults to
                xv_tvar+'_interp'.  If you want vector output, use the keyword "out"

                suffix = a suffix other than interp you can use,
                particularily useful when using globbing

                overwrite=set this variable if you just want
                the original variable overwritten instead of using
                newname or suffix

                Use only newname or suffix or overwrite. If you combine
                them the naming behavior may be erratic

                /LINEAR = pass this argument to specify linear
                interpolation(this is the default behavior)

                /QUADRATIC = pass this argument to specify quadratic
                interpolation

                /SPLINE = pass this argument to specify spline
                interpolation

                /NEAREST_NEIGHBOR = pass this argument to specify repeat
                nearest neighbor 'interpolation'

                /NO_EXTRAPOLATE = pass this argument to prevent
                extrapolation of data values in V passed it's start and
                end points

                /NAN_EXTRAPOLATE = pass this argument to extrapolate past
                the endpoints using NaNs as a fill value

                /REPEAT_EXTRAPOLATE = pass this argument to repeat nearest value past the endpoints

                ERROR(optional): named variable in which to return the error state
                of the computation.  1 = success 0 = failure

    Outputs(optional):
       out:
         Returns output as a data struct. If this argument is present, no tplot variable will be created.
         Note that only one result can be returned through this keyword.(ie You can't use this keyword with tplot name-globbing)

    CALLING SEQUENCE;
               tinterpol,'tplot_var1','tplot_var2',newname='tplot_var_out'
               tinterpol,'tplot_var1','tplot_var2',/NO_EXTRAPOLATE
               tinterpol,'tplot_var1','tplot_var2',/SPLINE
               tinterpol,'tplot_var1','tplot_var2',out=out_data_struct ;doesn't create tplot variable, instead returns struct
               tinterpol,'tplot_var1',time_array ;This calling method doesn't require second tplot variable
               tinterpol,{x:time_array,y:data_array},'tplot_var2' ;This calling method doesn't require first tplot variable
               tinterpol,{x:time_array,y:data_array,v:y_scale_vals},time_array,out=out_data_struct ; You can mix and match calling types. This calling method doesn't use any tplot variables

    Output: an N by D1 by D2 by ... array stored in an output tplot variabel

    Notes:
    Uses a for loop over D1*D2*..., but I'm operating under the assumption that
    D1*D2... << M (D1 * D2 *... is waaaay less than M)

    It uses a little bit of modular arithmatic so this function is
    generalized to any array dimensionality(IDL limits at 8)

    Examples:
     if the input is an array of 3-d vectors(say 1,1,1 and 2,2,2) and we
     want 3 vectors out the output is 1,1,1 1.5 1.5 1.5 2,2,2
     if the input is an array of 3x3 matrices(say all ones and all twos)
     and we want three matrices then output is all 1s all 1.5s all 2s

     $LastChangedBy: egrimes $
     $LastChangedDate: 2016-10-17 08:33:58 -0700 (Mon, 17 Oct 2016) $
     $LastChangedRevision: 22105 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tinterpol.pro $

(See general/misc/tinterpol.pro)

## TKM2RE

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

    Procedure: tKm2Re

    Purpose: Converts a variable to RE or KM

    Inputs: name: a string naming the tplot variable to be modified
                  globbing may be used

    Keywords:
              newname: set this keyword to a string to store the
                       output in(only works when globbing is not used)
              suffix:  set this keyword to a string indicating the
                       suffix to be appended to the input variable(s)
              /replace: set this option to replace the variable being modified
              /KM : converts to KM from RE rather than to RE from KM

      examples:
            tKm2Re,'thb_state_pos'
            tKm2Re,'thb_state_pos',/replace
            tKm2Re,'thb_state_pos',/KM
            tKm2Re,'thb_state_pos',newname='pos_in_re'
            tKm2Re,'th?_state_pos',suffix='_converted'

      NOTES: Uses conversion of 6371.2 KM/RE ;mean radius
             By default output will be called: input_name+'_RE'

    $LastChangedBy: adrozdov $
    $LastChangedDate: 2019-03-26 12:08:00 -0700 (Tue, 26 Mar 2019) $
    $LastChangedRevision: 26907 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tkm2re.pro $

(See general/misc/tkm2re.pro)

## TPLOT_NOISE_VARS

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

    NAME:
     tplot_noise_vars
    PURPOSE:
     generate Nvars tplot variables, with random noise for testing
    CALLING SEQUENCE:
     tplot_names = tplot_noise_vars(nvars = nvars, time = time, $
                   nchan = nchan, ncounts = ncounts)
    INPUT:
     none explicit
    OUTPUT:
     tplot_names = an array of tplot names: 'test_var_nnnnnn', starting
     just after the highest value i.e., if you just created variable 99,
     then the first new variable will be variable 100. use del_data if
     you want to recreate variables
    KEYWORDS:
     nvars = number of variables, the default is 100, max is 999999L
     time = a time array, the default is systime()+indgen(60), one minute
            starting now.
     nchan = number of channels in data, the default is 16
     ncounts = number of counts per channel, the output data is poisson
               distributed given the number of counts. The default is 1
               count per channel.
     nostore =  if set, don't create the variables, for testing
    HISTORY:
     2017-08-24, jmm, jimm@ssl.berkeley.edu
    $LastChangedBy: jimmpc1 $
    $LastChangedDate: 2017-10-13 10:50:56 -0700 (Fri, 13 Oct 2017) $
    $LastChangedRevision: 24155 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tplot_noise_vars.pro $

(See general/misc/tplot_noise_vars.pro)

## TPWRSPC[2]

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

    NAME:
     tpwrspc
    PURPOSE:
     wrapper for pwrspc.pro allowing input of a tplot variable name.
        A Hanning window is applied to
        the input data, and its power is divided out of the returned
        spectrum. A straight line is subtracted from the data to
        reduce spurius power due to sawtooth behavior of a background.
        UNITS ARE (UNITS)^2 WHERE UNITS ARE THE UNITS OF quantity. freq
        is in 1/timeunits.
        THUS THE OUTPUT REPRESENTS THE MEAN SQUARED AMPLITUDE OF THE SIGNAL
           AT EACH SPECIFIC FREQUENCY. THE TOTAL (SUM) POWER UNDER THE CURVE IS
           EQUAL TO THE MEAN (OVER TIME) POWER OF THE OSCILLATION IN TIME DOMAIN.

    CALLING SEQUENCE:

    CALLING SEQUENCE:
     tpwrspc, varnames, newname=newname,_extra=_extra
    INPUT:
     varname = one tplot variable name
    OUTPUTS:
     freq_out=freq_out(optional): output frequency abcissas, in a 1-d array
     power_out = power_out(optional) : output powers at frequency abcissas, in a 1-d array

    KEYWORDS:
     newname = if set,give this name to the new data, the
               default is to append '_pwrspc' to the input name and
               pass out the name in the newname variable,
               Unless /overwrite is set
     overwrite = if set, write the new data back to the old tplot
                 variable, do not set this with newname
     noline = if set, no straight line is subtracted
     nohanning = if set, then no hanning window is applied to the input
     bin = a binsize for binning of the frequency data, the default is 3
     notperhz = if set, the output units are simply the square of the
                input units
     err_msg = named variable that contains any error message that might occur

     NOTES: 1. IF KEYWORD notperhz IS SET, THEN POWER IS IN UNITS^2. If notset
               power is (as normal) in UNITS^2/Hz.
            2. Inputs must be 1-dimensional.   For example, if you try to
                call this on a 3-d vector like fgs data, it will not work.
                call 'split_vec' first, to split the quantity into its components.

     27-mar-2007, jmm, jimm.ssl.berkeley.edu

    HISTORY:

    $LastChangedBy: nikos $
    $LastChangedDate: 2023-12-15 14:11:08 -0800 (Fri, 15 Dec 2023) $
    $LastChangedRevision: 32290 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tpwrspc.pro $

(See general/misc/tpwrspc.pro)

## TRANGE_STR

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

    FUNCTION:   trange_str,t1,t2
    INPUT:  t1,t2   doubles,   seconds since 1970
    OUTPUT:  string  with the format:  'YYYY-MM-DD/HH:MM:SS - HH:MM:SS'

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)trange_str.pro	1.10 97/12/22

(See general/misc/trange_str.pro)

## TRES

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

    NAME:
    tres
    PURPOSE:
    returns the time resolution of a tplot variable, defined as the
    median value of the differences between time values from the data
    points, e.g. median(d.x[1:*]-d.x). Also will return a measure of how
    useful this value is, e.g. what fraction of the points are within 10%
    of the median value. Can be used for multiple variables.
    CALLING SEQUENCE:
     tres, tplot_var, delta_t, confidence = confidence, $
                               closeto_fraction = closeto_fraction
    INPUT:
     tplot_var = a tplot variable name or number
    OUTPUT:
     delta_t = the time resolution, a median value. If the data variable
               does not exist, or does not return a median, then the
               result is -1
    KEYWORDS:
     confidence = the fraction of dt values that are close to (within
                  a certain percentage) of the returned value. A bad
                  value of this would make this not a good measure of the
                  time resolution of the full sample, and you may want
                  to work in batches.
     close_fraction = the fractional value that the values of time
                        interval sizes need to be close to the median
                        value to be called 'close'. E.g., values are
                        considered close to the median if the value is
                        greater than 1-close_fraction and less than
                        1+close_fraction times the median. The default
                        is 0.01.
     tplot_var_out = A set of tplot variable names, that correspond to
                     the values of delta_t and confidence level if there
                     are multiple tplot variables input as a globbed
                     string or array.
    EXAMPLE:
     For THEMIS ESA data:

     timespan, '2010-11-26'
     thm_load_esa,probe='a',level='l2',datatype='*velocity*gsm'
     tres, 'tha_pe??_velocity_gsm', delta_t, confidence = c, $
           tplot_var_out = tplot_var_out
     For k = 0, n_elements(delta_t)-1 Do print, delta_t[k], c[k], '  ', tplot_var_out[k]
           97.020038     0.765714  tha_peif_velocity_gsm
           3.0318751     0.990622  tha_peef_velocity_gsm
           3.0318747     0.999575  tha_peir_velocity_gsm
           3.0318747     0.999647  tha_peer_velocity_gsm
           3.0318732     0.991525  tha_peib_velocity_gsm
           3.0318732     0.988764  tha_peeb_velocity_gsm

     For most of the datatypes the median value is ok, but the time
     resolution of the PEIF data varies for different modes, so this
     is not a good resolution for that variable.

    HISTORY:
     2018-11-26, jmm, jimm@ssl.berkeley.edu
     $LastChangedBy: jimm $
     $LastChangedDate: 2018-11-26 14:59:03 -0800 (Mon, 26 Nov 2018) $
     $LastChangedRevision: 26176 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tres.pro $

(See general/misc/tres.pro)

## TSMOOTH_IN_TIME

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

    PROCEDURE: tsmooth_in_time, varname, dt, newname = newname
    PURPOSE:
     Calls smooth_in_time function on a plot variable
    INPUT:
     varname = variable passed to get_data, example - thg_mag_ccnv
     dt = the averaging time (in seconds)
    KEYWORDS:
     newname = set output variable name
     display_object = Object reference to be passed to dprint for output.

    HISTORY:
     11-apr-2008, jmm, jimm@ssl.berkeley.edu

    $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/misc/tsmooth_in_time.pro $

(See general/misc/tsmooth_in_time.pro)

## TSNAP

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

    PROCEDURE:   tsnap
    PURPOSE:
      Tplot variables with two independent variables (time and some other
      parameter) are often displayed as color spectrograms, where the Y
      axis is the second independent variable and color represents the
      dependent variable (Z).  Sometimes, the color scale does not
      accurately portray the variation in Z, or it is difficult to tell
      whether a color gradient is significant.

      This routine plots cuts of color spectrograms across the second
      independent variable at time(s) selected by the mouse.  You can plot
      error bars if DY is provided as a tag in the tplot variable structure.
      This procedure can average in time (and propagate errors) to improve
      statistics.

      Unless keyword SUM is set, you can hold down the left mouse button
      and drag for a movie effect.  Click the right mouse button at any time
      to exit.

    USAGE:
      tsnap, var

    INPUTS:
           var:    Tplot variable name or number.  If not specified, determine
                   based on which panel the mouse is in when clicked.

                   The selected variable must have two independent variables
                   X and Y (time and some other parameter) and one dependent
                   variable Z (represented as color in the spectrogram).  This
                   cannot be a compound variable (list of variables to be plotted
                   in the same panel).  You must specify which variable within
                   the list.

    KEYWORDS:
           NAVG:   Number of times to average centered on the selected time.
                   This is forced to be an odd number.  Default = 1.

           SUM:    Average all times between two selected times.

           XSMO:   Number of points to smooth in the second independent variable
                   (which is the snapshot X axis).  Default = 1 (no smoothing).

           KEEP:   Do not close the snapshot window on exit.

           DERIV:  Plot the first (DERIV=1) or second (DERIV=2) derivative.
                   Default = 0 (just plot Y).

           ERR:    If the tplot variable has a DY tag, then plot error bars for
                   each point.  Propagate uncertainties when NAVG or SUM is set.

           Passes many keywords to WIN (e.g. MONITOR, DX, DY, etc.).  If WIN is
           enabled (win, /config), then by default the snapshot window will be
           placed in the secondary monitor.

           Passes many keywords to PLOT (e.g., XSIZE, YTITLE, etc.).  If not set,
           TITLE becomes the time or time range of the snapshot.

           KEY:    Alternate method for setting keywords.  Structure containing
                   keyword(s) for this routine, plus many keywords for WIN and
                   PLOT.  Unrecognized or ambiguous keywords are ignored, but
                   they will generate error messages.

                          {KEYWORD: value, KEYWORD: value, ...}

                   This allows you to gather keywords into a single structure and
                   use them multiple times without a lot of typing.  In case of
                   conflict, keywords set explicitly take precedence over KEY.

           LASTCUT:  Named variable to hold data for the last plot.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-05-25 09:50:47 -0700 (Sun, 25 May 2025) $
     $LastChangedRevision: 33334 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tsnap.pro $

    CREATED BY:    David L. Mitchell

(See general/misc/tsnap.pro)

## TSUB_AVERAGE

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

    NAME:
     tsub_average
    PURPOSE:
     Subtracts average or median values from the data in a tplot
     variable, returns a new variable, only one at a time for now
    CALLING SEQUENCE:
     tsub_average, varname, out_name, new_name=new_name,median=median
    INPUT:
     varname =  a tplot variable name
    OUTPUT:
     out_name = variable name of the output tplot variable
    KEYWORDS:
     new_name = can be used to input the new variable name, if not input
                the default is to add a '-d' to the input name (or '-m' for median
                subtraction) and the name is passed out in this variable
     display_object = Object reference to be passed to dprint for output.

    HISTORY:
     18-jul-2007, jmm, jimm@ssl.berkeley.edu
     02-nov-2007, jmm, Fixed bug for variables with no data.
     06-may-2008, jmm, Fixed problem, by changing non-float and
                       non-double datatypes to floats
    $LastChangedBy: adrozdov $
    $LastChangedDate: 2018-01-10 17:03:26 -0800 (Wed, 10 Jan 2018) $
    $LastChangedRevision: 24506 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tsub_average.pro $

(See general/misc/tsub_average.pro)

## TVECTOT

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

    Procedure: tvectot(tplot vector total)

    Purpose: Add or remove the magnitude of a vector to a tplot quantity

    Inputs: name: a string naming the tplot variable to be modified,  may
    use regex

    Keywords: /remove: set this keyword to remove the magnitude from
                       vector
              newname: set this keyword to a string to store the(this
              option will not work properly if regex is used)
              output in a different variable instead of overwriting
              tot: set this keyword to a named variable to store
                 the magnitude as an array or set it to a string to store
                 the magnitude as a tplot variable(this option will not
                 work properly if regex is used)

      examples:
            tvectot,'tha_fgs_dsl'
            tvectot,'tha_fgs_dsl',/remove
            tvectot,'tha_fg*_dsl'
            tvectot,'tha_fgs_dsl',newname='tha_fgs_dsl_mag'
            tvectot,'tha_fgs_dsl',tot=var
            tvectot,'tha_fgs_dsl',tot='mag_t_var'

    $LastChangedBy: pcruce $
    $LastChangedDate: 2012-01-27 11:23:20 -0800 (Fri, 27 Jan 2012) $
    $LastChangedRevision: 9637 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/tvectot.pro $

(See general/misc/tvectot.pro)

## UNDEFINED

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

    NAME:
     undefined
    PURPOSE:
     Tests whether a variable is undefined
    CALLING SEQUENCE:
     if ~undefined(var) then print,'Hooray!'

     INPUT:
      var:  A variable to be tested

    OUTPUT:
     1 on success, 0 on fail

     $LastChangedBy: pcruce $
     $LastChangedDate: 2008-07-28 11:53:49 -0700 (Mon, 28 Jul 2008) $
     $LastChangedRevision: 3311 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/undefined.pro $

(See general/misc/undefined.pro)

## WI

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

    PROCEDURE:     wi, wnum

    PURPOSE:   Switch or open windows.

    INPUT:
       wnum - the window number.

    CREATED BY:    REE, 95-10-23
    completely rewritten by DEL 2006
    FILE: wi.pro
    VERSION: 1.6
    LAST MODIFICATION: 97/06/03

(See general/misc/wi.pro)

## WIN

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

    PROCEDURE:   win
    PURPOSE:
      When there are multiple monitors, IDL defines a rectangular "super
      monitor" that encompasses all physical monitors.  One of the physical
      monitors is designated the "primary monitor" and the lower left corner
      of that monitor is the origin of the coordinate system for the super
      monitor.  XPOS and YPOS are used to position windows within the super
      monitor; however, the coordinate system is not known in advance, and
      when you attempt to place a window entirely or partially out of bounds,
      it can appear in an unexpected location, depending on your window
      server.  (IDL can only make a request.  The window server will try to
      to honor that request, but if there's a problem the server may do
      something different and unexpected.)

      This procedure divides the super monitor back into physical monitors
      and allows you to choose a monitor and place a window relative to the
      edges of that monitor (or in the center, or full screen).  You can
      also place a new window next to and aligned with an existing window.
      It is also possible to clone an existing window and place it as above.
      In short, this is a user-friendly version of WINDOW designed for a
      multiple monitor setup.  It allows you to create new windows within a
      routine and arrange them accurately in specified monitors or next to
      other windows without the need for resizing and moving them with the
      mouse.

      On first call, this routine queries the OS to get the number, sizes,
      and arrangement of the physical monitors.  This works well on Mac
      systems but has not been thoroughly tested on other platforms.  See
      keywords SETPRIME, TBAR, and TCALIB for more information.

      If CONFIG=0 (default), win behaves exactly like window.  This allows
      the routine to be used in public code, where the user may not know about
      or does not want to use its functionality.

    USAGE:
      win [, wnum [, monitor]] [, KEYWORD=value, ...]  ; normal usage

      win, CONFIG={0|1} [, TBAR=value]  ; 0=disable, 1=enable

      win, SHOW=N  ; identify the monitor(s) and corners for N seconds.

    EXAMPLES:
      win, 0, /full
        --> put a full-screen window in the primary monitor

      win, 1, xsize=800, aspect=4./3., /secondary, dx=10, dy=10
        --> put a 4:3 aspect window in the secondary monitor, offset by 10 pixels
            from the top left corner

      win, 2, clone=1, relative=1, dx=10, /top
        --> put a clone of window 1 to the right of window 1 offset by 10 pixels
            with the top edges aligned

      win, 3, 0, clone=1, scale=0.6, /center
        --> put a clone of window 1 scaled by 60% in the center of monitor 0

      win, wnum, /free, key={sec:1, yf:1, xs:500, dx:10}
        --> put a window with an index > 31 in the secondary monitor, full-screen in Y,
            500 pixels in X; the assigned window number is returned in wnum

    INPUTS:
           wnum:      Window number.  Can be an integer from 0 to 31.
                      Default: next free widow number > 31.

                      This can also be set to a variable name, which will
                      return the window number chosen.

           monitor:   Monitor number.  Can also be set by keyword (see
                      below), but this method takes precedence.  Only the
                      second input will be interpreted as a monitor number.
                      If there's only one input, it's interpreted as the
                      window number.

                      If there is more than one monitor, this routine
                      defines a "primary monitor", where graphics windows
                      appear if no monitor is specified.  See keyword
                      SETPRIME for details.

    KEYWORDS:
           Accepts all keywords for WINDOW.  In addition, the following
           are defined:

           CONFIG:    An integer that controls the behavior of win.
                      The first time win is called, it queries the OS
                      to get the number, dimensions, and arrangement of
                      the monitors.  This information is stored in a
                      common block.

                         0 = disabled: win acts like window (default)
                         1 = enabled: win has full functionality

           SETPRIME:  Set the primary (and secondary) monitors manually.
                      The first element is the primary monitor number, and
                      the second element, if present, is the secondary
                      monitor number.  These values are persistent.

                      Default:
                        primary monitor = left-most external monitor
                        secondary monitor = highest numbered non-primary

           TBAR:      Title bar width in pixels.

                      The standard WINDOW procedure does not account for the
                      window title bar, but this procedure does, so windows
                      can be positioned precisely.  IDL does not have access
                      to the title bar width, so this routine provides two
                      defaults, depending on the operating system:

                        MacOS    : TBAR = 22
                        RedHat 8 : TBAR = 37

                      For other X servers and Windows, use TCALIB (below) to
                      calibrate the title bar width.  You can then set the
                      configuration in your IDL startup file, so you won't
                      need to rerun the calibration:

                        win, /config, tbar=N, /silent

                      This value is persistent.

           TCALIB:    Calibrate the title bar width by briefly creating two
                      windows with the same dimensions and location but
                      different (bogus) title bar widths.  The vertical offset
                      between these two windows is used to calculate the actual
                      title bar width.  This value is persistent.

           STAT:      Output the current monitor configuration.  When this
                      keyword is set, CONFIG will return the current monitor
                      array, the primary and secondary monitor indices, and
                      the title bar width.

           SHOW:      Place a small window in each monitor for 5 sec to
                      identify the monitor numbers and which are primary and
                      secondary.  In addition, place four small windows in the
                      corners of the primary monitor to identify the corner
                      numbers (keyword CORNER).

                      Set this keyword to a number N > 5 to display the small
                      windows for N seconds.

           LIST:      List the existing windows and their dimensions.

           MONITOR:   Put window in this monitor.  If no monitor is set by
                      input or keyword, then the new window is placed in
                      the primary monitor.

           SECONDARY: Put window in the secondary monitor.

           DX:        Horizontal offset from left or right edge (pixels).
                        If DX is positive, offset is from left.
                        If DX is negative, offset is from right.
                      Replaces XPOS.  Default = 0.

           DY:        Vertical offset from top or bottom edge (pixels).
                        If DY is positive, offset is from top.
                        If DY is negative, offset is from bottom.
                      Replaces YPOS.  Default = 0.

                      XPOS and YPOS are ignored while win is enabled.

           RELATIVE:  Set this keyword to an existing window number.  Then
                      DX and DY specify offsets of the new window location
                      from the perimeter of the existing window.
                        If DX (DY) is positive, place window right (above).
                        If DX (DY) is negative, place window left (below).
                      Usually, DX and/or DY are non-zero, in which case the
                      new window is placed around the perimeter of the
                      existing window.  However, when DX and DY are both
                      zero, the new window is placed on top of the existing
                      window, with the top left corners aligned.

                      If RELATIVE is set, NORM=0 and NOFIT=1 are enforced.

           TOP:       If RELATIVE is set and DY=0, align the top edges of
                      the windows.  Default.

           LEFT:      If RELATIVE is set and DX=0, align the left edges of
                      the windows.  Default.

           BOTTOM:    If RELATIVE is set and DY=0, align the bottom edges of
                      the windows.

           RIGHT:     If RELATIVE is set and DX=0, align the right edges of
                      the windows.

           MIDDLE:    If RELATIVE is set and DX=0 (DY=0), center the two
                      windows vertically (horizontally).

           CLONE:     Create a new window with the same dimensions as the
                      (existing) window specified by this keyword.  SCALE
                      can then be used to shrink/expand the window while
                      maintaining the aspect ratio.  Unless NOFIT is set,
                      the clone is allowed to move around and shrink/expand
                      so that it fits entirely on the monitor.

           CORNER:    Alternate method for determining which corner to
                      place window.  If this keyword is set, then only the
                      absolute values of DX and DY are used and specify
                      offsets from the selected corner.  Corners are
                      numbered like reading a book:

                        0 = top left (default)
                        1 = top right
                        2 = bottom left
                        3 = bottom right

           NORM:      Measure DX and DY in normalized coordinates (0-1)
                      instead of pixels.

           XCENTER:   Center the window horizontally in the monitor.

           YCENTER:   Center the window vertically in the monitor.

           CENTER:    Center the window in both X and Y.

           SCALE:     Scale factor for setting the window size.  If no
                      window size is specified, then SCALE is relative
                      to the default size: 1/4 of the monitor size.
                      Default = 1.

           NOFIT:     If the combination of XSIZE, YSIZE, SCALE, DX and
                      DY cause the window to extend beyond the monitor,
                      first DX and DY, then XSIZE and YSIZE are reduced
                      until the window does fit.  If ASPECT is set, then
                      the window is further reduced, if necessary, to
                      maintain the aspect ratio.  Set NOFIT to disable
                      this behavior and create the window as requested.

           XFULL:     Make the window full-screen in X.
                      (Ignore XSIZE, DX.)

           YFULL:     Make the window full-screen in Y.
                      (Ignore YSIZE, DY.)

           FULL:      If set, make a full-screen window in MONITOR.
                      (Ignore XSIZE, YSIZE, DX, DY, SCALE, ASPECT.)

           ASPECT:    Aspect ratio: XSIZE/YSIZE.  If one dimension is
                      set with XSIZE, YSIZE, XFULL, or YFULL, this
                      keyword sets the other dimension.

           SILENT:    Shhh.

           KEY:       A structure containing any of the above keywords
                      plus XSIZE and YSIZE:

                        {KEYWORD:value, KEYWORD:value, ...}

                      Case folded minimum matching is used to match tag
                      names in this structure to valid keywords.  For
                      example:

                        {f:1, mon:2} is interpreted as FULL=1, MONITOR=2.

                      Unrecognized or ambiguous tag names generate an
                      error message, and no window is created.

                      Keywords set using this mechanism take precedence.
                      All other keywords for WINDOW must be passed
                      separately in the usual way.

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2025-02-03 13:32:18 -0800 (Mon, 03 Feb 2025) $
     $LastChangedRevision: 33109 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/win.pro $

    CREATED BY:	David L. Mitchell  2020-06-03

(See general/misc/win.pro)

## XCLIP

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

     xclip
    PURPOSE:
     Replaces with FLAGs the values of the array that are BEYOND
     the limits specified.
    CALLING SEQUENCE:
     xclip, amin, amax, y, flag=flag, _extra=_extra
    INPUT:
     amin, amax = the minumum and maximum values
     y = the input array
    OUTPUT:
     y = set to flag for points less than amin or greater than amax
    KEYWORDS:
     flag = the value that clipped data will be set to, the default is
               -0.0/0.0 (NaN)
     clip_adjacent = if set, then clip the vales adjacent to the bad
                     ones, as in tdespike_ae.pro
     interior_clip (optional): removes data inside the selected region instead of outside the selected region

    HISTORY:
     2-feb-2007, jmm, jimm.ssl.berkeley.edu from Vassilis'
     clip_deflag.pro
     9-feb-2007, change big value to Nan
     9-oct-2007, added option to clip the points adjacent to the bad
                 ones, as in tdespike_ae.pro
     20-Oct-2007, Jmm, Added this comment to test commit comand
    $LastChangedBy: nikos $
    $LastChangedDate: 2018-11-30 12:03:45 -0800 (Fri, 30 Nov 2018) $
    $LastChangedRevision: 26203 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/xclip.pro $

(See general/misc/xclip.pro)

## XDEFLAG

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

     xdeflag
    PURPOSE:
     Replaces FLAGs in arrays with interpolated or other values
    CALLING SEQUENCE:
     xdeflag, method, t, y, flag=flag, _extra=_extra
    INPUT:
     method = set to "repeat", this will repeat the last good value.
              set to "linear", then linear interpolation is used, but for
              the edges, the closest value is used, there is no
              extrapolation.
              set to "replace", this will replace the gap values with an
              input variable, input via the keyword, "fillval"
     t = time array, in any useable tplot format
     y = the input array, n_elements(t) by n
    OUTPUT:
     y = either interpolated or repated, where the value is > 0.98*flag,
         or NaN
    KEYWORDS:
     flag = all values greater than 0.98 times this value will be removed;
            default is 6.879e28, NaNs and +/-Infinity are always removed
     maxgap = the maximum number of rows that can be filled? the default
               is n_elements(t)
     display_object = Object reference to be passed to dprint for output.
     fillval = a fill value for the "replace" option. The default is zero
    HISTORY:
     2-feb-2007, jmm, jimm.ssl.berkeley.edu from Vassilis' clip_deflag.pro

    $LastChangedBy: jimm $
    $LastChangedDate: 2020-09-23 15:50:05 -0700 (Wed, 23 Sep 2020) $
    $LastChangedRevision: 29179 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/xdeflag.pro $

(See general/misc/xdeflag.pro)

## XDEGAP

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

    NAME:
     xdegap
    PURPOSE:
     Locates gaps in data, and fills in with NaN
     This subroutine accepts the time array (can be cline time) t and the
     multi-dimensional array yarr that matches with the time array.
     It outputs the same arrays but with a different number of rows
     depending on how many rows were added. It then figures out where to
     add rows by checking which time differences are greater than or equal to
     deltat plus a margin and adds an array of rows of equispaced times of
     size tstep=gap/(number_of_points_that_fit_with_minimum_cumulative_error).
     The same number of rows is added to yarr with values equal to
     FLAGs.
     NOTE: ARRAYS AND STRUCTURES THAT NEED DEGAPPING ARE REDEFINED TO BE
     LARGER THAN BEFORE. THUS THE TIME COLUMN THAT HAS BEEN DEGAPPED
     WILL NOT CORRESPOND TO THE ELEMENTS OF AN ARRAY THAT HAS NOT BEEN
     DEGAPPED. CAUTION: DEGAP ALL ARRAYS OR STRUCTURES YOU ARE GOING TO USE
     TOGETHER, I.E., WITH ONE DEGAP CALL.
     ADDITIONAL NOTE: To conserve memory, see the ONENANPERGAP keyword.
    CALLING SEQUENCE:
     xdegap, dt, margin, ct, y, ct_out, y_out [,/nowarning] [,maxgap =
     <value>] [,iindices=<variable>] [,/onenanpergap] [,/twonanpergap]
    INPUT:
     dt = the time interval for tests
     margin = the margin
     ct = the input time array
     y = the input array, can be 1 or 2d (n_elements(ct), m)
    OUTPUT:
     ct_out = the output time array,
     y_out = the input time array
    KEYWORDS:
     nowarning = if set, suppresses warnings
     maxgap = the maximum gap size filled, in seconds
     iindicies = the indices in the output arrays that contain the original data
     flag = A numeric user-specified value to use for flagging gaps.
       Defaults to a floating NaN.  If an array is entered, only the
       first element is considered.If a non-numeric datatype is entered,
       its value is ignored.
     onenanpergap = Fill gaps with only one NaN -> useful for conserving memory.
       Also, for reference concerning post-processing, the INTERPOL function
       propagates a single NaN just as it would many NaNs.
     twonanpergap = Fill gaps with only two NaNs, it turns out that
                    onenanpergap does not work well with
                    spectrograms. The exeption is if only one NAN fits in
                    the gap given the input parameters, then only one is
                    used.
     n_gaps = the number of gaps found
     gap_begin = the double-precision start times of the detected gaps.
     gap_end = the double-precision end times of the detected gaps.
     display_object = Object reference to be passed to dprint for output.
     output_message = Passes any messages generated up to the calling procedure as an array of strings

    HISTORY:
     From Vassilis' degap.pro, 2-apr-2007, jmm, jimm@ssl.berkeley.edu
     bug fix for undefined variable, jmm, 24-jun-2007
     Switched maxgap to seconds, jmm, 26-oct-2007
     Added comment to test svn version 4_00, jmm, 28-apr-2008
     Added ONENANPERGAP kw, W.M.F., 5 May, 2009.
     Added GAP_BEGIN, GAP_END kwd's, 12 June, 2009.
     Added _extra keyword, 20-oct-2009, jmm
     Added output_message keyword Feb-02-2011 prc
     Added twonanpergap, jmm, 14-aug-2012
     Return inputs instead of -1 if no gaps found, added n_gaps keyword, af 2016-05-03

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-05-03 13:28:56 -0700 (Tue, 03 May 2016) $
    $LastChangedRevision: 21010 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/xdegap.pro $

(See general/misc/xdegap.pro)

## [4]

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

    NAME:

      fancompress

    PURPOSE:
      Decimates polylines in an aesthetically pleasing fashion.

    CALLING SEQUENCE:
      outidx = fancompress(inpts,err)

    INPUT:
      inpts: N x 2 dimension array, where inpts[*,0] are the x components of the polyline and inpts[*,1] are the y components of the polyline
      err: The amount of error allowed before including a point

    Keywords:
      vector:  Will enable the vectorized fan compression algorithm.
      step:  Controls the number of steps to perform per loop, during vectorized implementation.
             At the limit, where step = N, the vectorized version works like the iterative
             version.
    OUTPUT:
      An array of indexes into inpts.  Indices will range from 0 to N-1.  First and Last points are always included.

    NOTES:
      1. Based almost entirely on the paper:
      Fowell, Richard A. and McNeil, David D. , “Faster Plots by Fan Data-Compression,”
      IEEE Computer Graphics & Applications, Vol. 9, No. 2,Mar. 1989, pp. 58-66.

      2. One modification from published algorithm, handles NaNs by always including the point
      before a group of NaNs, 1 NaN and the point after the NaNs.  This ensures that gaps will
      be drawn accurately.

      3. Algorithm is fairly slow, because it requires 1 pass over all data points.
      Optimizing this algorithm by divide and conquer, vectorization, or dlm may be
      a worthwhile use of time in the future.

      4. Vectorized version is essentially a divide and conquer version of the Fowell & McNeil algorithm.
      The idea being to split the array into sub-problems that can be addressed in parallel using IDL vector-ops.
      The fan-comparison operation at the core of the fan-compression algorithm takes 3-sequential points to work.
      So if step = 1, the algorithm will split the input array of length N in floor(N/3) segments; Making an independent
      decision on whether to keep the middle point of each segment, based upon the start and end points of each segment.
      If a point is removed, the 5-element fan vector at the start point is updated, and this will be applied in the subsequent test.

      5. If step is higher an internal loop will perform the operation iteratively within-segments, but in parallel across segments.
      For example, If step is 3, N will be split into floor(N/5) segments(5-point segments). Operating on points 1-2-3 of the segment
      in the first iteration of the internal loop, points 1-3-4 or 2-3-4 on the second iteration and points 1-4-5,2-4-5,or 3-4-5 on the
      third iteration. Which sequence ends up being operated on depends on whether the point was accepted or rejected in the previous iteration.

      6. Vectorized(step=1) version generally achieves a speed up of 1000% at decrease in compression by ~10%.
         For example, if the iterative version creates a 1 Mb of output in 1 sec, this will create
         1.1 Mb of output in .1 sec.  Higher values of step, tend to decrease compression rates until step becomes large,
         then compression approaches the iterative solution

    $LastChangedBy: pcruce $
    $LastChangedDate: 2009-07-27 17:44:33 -0700 (Mon, 27 Jul 2009) $
    $LastChangedRevision: 6496 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/misc/fancompress.pro $

(See general/misc/fancompress.pro)

## [5]

[Previous Routine] [List of Routines]

     NAME:

       LOAD_MAT

     PURPOSE:

       Read MATLAB MAT-files in IDL (see README for more information).

     CATEGORY:

     CALLING SEQUENCE:

     INPUTS:

     OPTIONAL INPUTS:

     KEYWORD PARAMETERS:

     OUTPUTS:

     OPTIONAL OUTPUTS:

     COMMON BLOCKS:

     SIDE EFFECTS:

     RESTRICTIONS:

     PROCEDURE:

     EXAMPLE:

       PRO load_mat, <filename>, <path>, STORE_LEVEL=store_level, $
                     VERBOSE=verbose, DEBUG=debug

     MODIFICATION HISTORY:

       See changelog.

     COPYRIGHT:

       Copyright (C) 2009 Gordon Farquharson <gordonfarquharson@gmail.com>

       This program is free software: you can redistribute it and/or modify
       it under the terms of the GNU General Public License as published by
       the Free Software Foundation, either version 3 of the License, or
       (at your option) any later version.

       This program is distributed in the hope that it will be useful,
       but WITHOUT ANY WARRANTY; without even the implied warranty of
       MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
       GNU General Public License for more details.

       You should have received a copy of the GNU General Public License
       along with this program.  If not, see <http://www.gnu.org/licenses/>.

(See general/misc/load_mat.pro)