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

Last modified: Sun Oct 5 03:17:42 2025.

# Directory Listing of Routines

# projects/themis/spacecraft/fields/LASP

- [3]
- REE_SET_GSM
- THM_EFI_CLEAN_EFP
  FIXES AXIAL, REMOVES SPIKES, SPINTONE, SC POTENTIAL, AND OTHER EFP ERRORS.
- THM_EFI_CLEAN_EFW
  FIXES HF, REMOVES SPIKES, AND LOW FREQUENCY.
- THM_EFI_DERIVE_EZ
- THM_EFI_EXB
- THM_EFI_FIX_FREQ_AND_PHASE
- THM_EFI_GET_POTENTIAL
  Remove SC potential from axial signal.
- THM_EFI_SIN_FIT
- THM_JBT_GET_BTRANGE (FUNCTION)
  This routine is to find the starting time and ending time of each
- THM_LSP_DERIVE_EZ
- THM_LSP_FILTER
- THM_LSP_FILTER_HIGHPASS (FUNCTION)
  CAUTION: THIS ROUTINE ONLY WORKS FOR DATA SAMPLED AT EITHER 8192 HZ OR
- THM_LSP_FIND_BURST
  Isolate an indivitual burst for analysis.
- THM_LSP_FIND_SPIKES
  Remove the non-physical spiky signals in the efw data.
- THM_LSP_GET_SPEC (PROCEDURE)
  Get the power spectrum density (PSD) of a given tplot variable.
- THM_LSP_MEDIAN_SMOOTH
  Smooth data with median rather than average - removes spikes.
- THM_LSP_NOTCH_SPIKES
  Remove the non-physical spiky signals in the efw data.
- THM_LSP_REMOVE_SPIKES
  Remove the non-physical spiky signals in the efw data.
- THM_LSP_REMOVE_SPIN_EPOCH
  Remove the non-physical spiky signals in the efw data.
- THM_LSP_REMOVE_SPINTONE
- THM_QFIT
- TRANGE_CLIP (PROCEDURE)
  Utility to trim the time range of a tplot variable and remove
- VH (SHORT FOR VIEWHELP)
  Make a shortcut to the IDL procedure DOC_LIBRARY

# Routine Descriptions

## REE_SET_GSM

[Next Routine] [List of Routines]

     PRO: REE_SET_GSM, sc

     PURPOSE: LOADS STATE AD SETS UP PLOTS FOR GSM

     INPUT:
           SC    -       REQUIRED. STRING. Spacecraft

     EXAMPLE: ree_set_gsm, 'a'

     OUTPUT: GSM Coordinates are laoded into tplot.

     WARNING: BE SURE TO SET TIMESPAN FIRST!

     INITIAL VERSION: REE 08-10-31
     MODIFICATION HISTORY:
     LASP, CU

(See projects/themis/spacecraft/fields/LASP/ree_set_gsm.pro)

## THM_EFI_CLEAN_EFP

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

     PRO: THM_EFI_CLEAN_EFP

     PURPOSE:
        FIXES AXIAL, REMOVES SPIKES, SPINTONE, SC POTENTIAL, AND OTHER EFP ERRORS.

       This routine is designed for general use. It will take EFP data in DSL as
       input, clean up the data, and transform the data into FAC and GSM, and
       return the cleaned EFP data in DSL, FAC, and GSM. If the data is gathered in
       the dayside, set keyword /SUBSOLAR to use keyword defaults specifically for
       dayside data.

       The routine can work on one-day long data, but if only a single particle
       burst data is interesting, use the keyword TRANGE to specify the time range
       of that burst can greatly reduce run time.

       CAUTION: The input keyword ENAME is optional. When it is not specified,
           ENAME is defaulted to 'thx_efp', where 'x' is probe name and should be
           one of these: 'a', 'b', 'c', 'd', and 'e'. In this case, if the existed
           'thx_efp' is not in DSL, the output will be wrong. So, make sure the
           existed 'thx_efp' is in DSL, or specify ENAME to another tplot variable
           which is EFP data in DSL.

       NOTE: 1) Spike removal does not always work, so don't be surprised if there
             still are spikes left on the data. Hopefully the spike issue can be
             resolved in the future.
             2) Merge can exhibit pathological behavior if B is near the spin plane.
             spike removal does not always work.
             3) Make sure thx_state_spinper is available! Best to set up for gsm.
             Make sure timespan is set!!!!

     EXAMPLES:
         For typical use, see thm_crib_cleanefp.pro and thm_crib_cleanefi.pro which
         are typically located under TDAS_DIR/idl/themis/examples.

     INPUT:

     KEYWORDS (general):
        probe      NEEDED: Program does only one sc at a time!
        Ename      OPTIONAL: Valid TPLOT name for E, DEFAULT = 'thX_efp' (will
                   fetch)
        Vname      OPTIONAL: Valid TPLOT name for E, DEFAULT = 'thX_vap' (will
                   fetch)
        Bdslname   OPTIONAL, Valid TPLOT name for B, DEFAULT = 'thX_fgh_dsl'
                   (will fetch)
        trange     OPTIONAL. Time range.
                   USE TRANGE TO ISOLATE SINGLE PARTICLE BURST AND GREATLY
                   REDUCE RUN TIME!!!!
        subsolar   OPTIONAL. If set, defaults for subsolar region are used.
                   DEFAULT = TAIL
        talk       OPTIONAL. Plots diagnostics. Can be fun. Slow. DEFAULT = 0
        duration_threshold:  OPTIONAL. If the duration of a burst is less than
                   duration_threshold, it is skipped. DEFAULT = 15.
                   In units of seconds.

     KEYWORDS (for output tplot variables):
        Edslname   OPTIONAL: Name for the cleaned efp in DSL.
                   DEFAULT = Ename + '_clean_dsl'
        Egsmname   OPTIONAL: Name for the cleaned efp in DSL.
                   DEFAULT = Ename + '_clean_gsm'
        Efacname   OPTIONAL: Name for the cleaned efp in DSL.
                   DEFAULT = Ename + '_clean_fac'

     KEYWORDS (Remove_SpinTone):
        SpinRemove     If entered as 0, suppresses spintone removal. DEFAULT = 4
                       (Spintone removed). The following are the behaviors for
                       different values of SpinRemove.
                       1: Only spintone, 2: Spintone and 2nd harm. 3: Spintone and
                       4th harm.  4: Spintone, 2nd, and 4th harm.
        SpinNsmooth    Activates median smoothing. # of half periods. Must be odd.
                       DEFAULT = 19 for subsolar and 39 otherwise.
        SpinPoly       Activates polyfit smoothing. Can be unstable if >9. DEFAULT
                       = 0

     KEYWORDS (Remove_Potential):
        VscRemove      If entered as 0, suppresses potential removal. DEFAULT = 1
                       (Potential removed.)
        VscPole        Frequency to median smooth Vsc before applying to Ez.
                       DEFAULT = 5.0 Hz
        Vpoly          Actives polyfit of Ez to Vsc.  DEFAULT = 2 (5 /Subsolar)
        Use_Electrons  (OBSOLETE) Kept for backward compatibility.
        TeName         (OBSOLETE) Kept for backward compatibility.

     KEYWORDS (Remove_Spikes):
        SpikeRemove    If entered as 0, suppresses spike removal. DEFAULT = 1
                       (Spikes are removed.)
        SpikeNwin      Number of points in spike search window. DFLT = 16
        SpikeSig       Sigma of spikes. DFLT = 5 (Sometimes Sig = 6 works better)
        SpikeSigmin    Minimun of sigma. DFLT = 0.01 mV/m. (Sometimes Sigmin = 0
                       works better)
        SpikeNfit      Number of points in the fit window. DFLT = 16
        SpikeFit       If set, will do a Gaussian fit to Spikes. DFLT = 0

     KEYWORDS (Remove_Spin_Epoch):
        EpochRemove    If set, removes all spin-epoch signals. DEFAULT = 0 (Not
                       used.) Only useful for short stretches or if plasma
                       condtitions are constant.

     KEYWORDS (Fix_Axial)
        FixAxial       If entered as 0, suppresses axial fix. DEFAULT=1 (Axial is
                       fixed.)
        AxPoly         Forces polynomial fit of Ez-Eder of order AxPoly. DEFAULT=2
                       (9 /SubSolar)
        Merge          Merges Ederived with Eaxial.  DEFAULT = 0 No merging
                       (1 /Subsolar)
                       1 - Abrupt merging. If Eder is avaliable Eder is used
                       (0 - Fmerge). Else Ez.
                       2 - Soft merging. Bz/|B| is considered when merging.
                       WARNING: MERGE=1 OR 2 CAN EXHIBIT PATHOLOGICAL BEHAVIOR IF
                           MAGNETIC FIELD IS NEAR THE SPIN PLANE. PLEASE DOUBLE
                           CHECK RESULTS IF USED.
        Fmerge         Frequency of crossover for merging Ederived with Eaxial.
                       DEFAULT = 5.0 Hz (/Subsolar).
        MergeRatio     Mimimum value of Bz/|B| to start merge (USED IF MERGE=2).
                       DEFAULT = 0.05
        MinBz          Needed to avoid divide by zero in Ederive. DEFAULT = 0.01 nT
        MinRatio       Mimimum value of Bz/|B| to calculate Ederive. DEFAULT = 0.1
                       (0.05 /Subsolar)

     KEYWORDS (B_Smooth)
        BspinPoly      Activates polyfit smoothing. Can be unstable if >9. DEFAULT
                       = 2. -1 suppresses.
        Bsmooth        Activates B smoothing for fac rotation. DEFAULT = 11. 1 or
                       less suppresses.

     HISTORY:
       2013-06-20: JBT. Added deconvolution of sheath response.
       2011-05-21: JBT. Added keyword DURATION_THRESHOLD.
       2011-05-20: JBT. Fixed a bug that happens when the spin-tone removing fails.
       2010-09-13: JBT. The default of FixAxial was changed to 0 (not to fix
                   axial E-field component).
                   Updated documents.
       2010-04-08: JBT. Fixed some bugs.
       2009-06-04: REE/JBT. Second Release.
       2009-06-04: Jianbao Tao (JBT). The metadata (dlim.data_att) was improved.
       2009-05-05: REE. First Release.

(See projects/themis/spacecraft/fields/LASP/thm_efi_clean_efp.pro)

## THM_EFI_CLEAN_EFW

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

     PRO: THM_EFI_CLEAN_EFW

     PURPOSE:
        FIXES HF, REMOVES SPIKES, AND LOW FREQUENCY.

       This routine is designed for general use. It will take EFW data in
       DSL as input, clean up the data, and transform the data into FAC, and return
       the cleaned EFP data in DSL/FAC.

       The routine can work on one-day long data, but if only a single particle
       burst data is interesting, use the keyword TRANGE to specify the time range
       of that burst can greatly reduce run time.

       NOTE: 1) Spike removal does not always work, so don't be surprised if there
             still are spikes left on the data. Hopefully the spike issue can be
             resolved in the future.
             2) Make sure thx_state_spinper is available! Best to set up for gsm.
             Make sure timespan is set!!!!

     EXAMPLES:
         For typical use, see thm_crib_cleanefw.pro and thm_crib_cleanefi.pro which
         are typically located under TDAS_DIR/idl/themis/examples.

     INPUT:

     KEYWORDS (general):
        probe          NEEDED: Program does only one sc at a time!
        Ename          OPTIONAL: Valid TPLOT name for E WAVE, DEFAULT = 'thX_efw'
                       (will fetch)
        Bdslname       OPTIONAL, Valid TPLOT name for B, DEFAULT = 'thX_fgh_dsl'
                       (will fetch)
        trange         OPTIONAL. Time range.
                       USE TRANGE TO ISOLATE SINGLE PARTICLE BURST AND GREATLY
                       REDUCE RUN TIME!!!!
        talk           OPTIONAL. Plots diagnostics. Can be fun. Slow. DEFAULT = 0
        EfpName        OPTIONAL: Valid TPLOT name for EFP, DEFAULT = 'thX_efp'
                       (will fetch)
                       EFP is used to find spike positions.
        status         OPTIONAL: A named variable to return the exiting status. If
                        exit successfully, status = 0, otherwise status = 1
        EFWHEDACNAME   OPTIONAL: Valid TPLOT name for the AC-coupled E-field header info
                       DEFAULT = 'thX_efw_hed_ac'

     KEYWORDS (Filter):
        FPole          (OBSOLETE) Kept for backward compatibility.

     KEYWORDS (for output tplot variables):
        Edslname   OPTIONAL: Name for the cleaned efp in DSL.
                   DEFAULT = Ename + '_clean_dsl'
        Efacname   OPTIONAL: Name for the cleaned efp in DSL.
                   DEFAULT = Ename + '_clean_fac'

     KEYWORDS (Remove_Spikes):
        SpikeRemove    If entered as 0, suppresses spike removal.
                       DEFAULT = 1 (Spikes are removed.)
        SpikeNwin      Number of points in spike search window. DFLT = 16
        SpikeSig       Sigma of spikes. DFLT = 5
                       (Sometimes Sig = 6 works better)
        SpikeSigmin    Minimun of sigma. DFLT = 0.01 mV/m.
                       (Sometimes Sigmin = 0 works better)
        SpikeNfit      Number of points in the fit window. DFLT = 16
        SpikeFit       If set, will do a Gaussian fit to Spikes. DFLT = 0

     HISTORY:
       2009-05-06: REE. First Release.
       2009-06-04: Jianbao Tao (JBT), CU/LASP.
                   The metadata (dlim.data_att) is modified properly.
       2009-06-17: JBT, CU/LASP.
                   Keyword STATUS added.
       2010-04-08: JBT, CU/LASP.
                   The high-pass filter is changed from an FFT filter to an
                   FIR filter. Some modification is made to be compatible with
                   two different sample rates 8192 Hz and 16384 Hz.
       2010-09-13: JBT, CU/LASP.
                   Cleaned up documents.
                   Added keyword dt in calling thm_efi_fix_freq_and_phase.
       2012-07-26: JBT, SSL, UC Berkeley.
                   1. Incorporated C. Cully's calibration for
                         1) Plasma-probe coupling
                         2) Anti-aliasing Bessel filter
                         3) ADC response
                         4) DFB response
       2012-08-30: CMC, University of Calgary.
                   Fixed problems with AC-coupled data sampled at < 16 ksps

     VERSION:

     $LastChangedBy $
     $LastChangedDate $
     $LastChangedRevision $
     $URL $

(See projects/themis/spacecraft/fields/LASP/thm_efi_clean_efw.pro)

## THM_EFI_DERIVE_EZ

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

     PRO: THM_EFI_DERIVE_EZ, Edsl, Bdsl, new_name=new_name

     PURPOSE: DERIVES EZ ASSUMING EdotB = 0

     INPUT:
           Edsl -       REQUIRED. STRING Efield data name (tplot).
           Bdsl -       REQUIRED. STRING Bfield data (tplot)

     CALLING: thm_efi_derive_Ez, Edsl, Bdsl

     OUTPUT: Tplot

     INITIAL VERSION: REE 08-11-04
     MODIFICATION HISTORY:
     LASP, CU

(See projects/themis/spacecraft/fields/LASP/thm_efi_derive_ez.pro)

## THM_EFI_EXB

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

     PRO: THM_EFI_ExB, Ename, Bname, Sname=Sname, Vname=Vname, $
                       EdotB=EdotB, Btot=Btot

     PURPOSE: Calculate Poynting Flux and Flow Velocity

     INPUT:
           Eanme -       REQUIRED. STRING Efield data name (tplot).
           Bname -       REQUIRED. STRING Bfield data (tplot)
           Sname -       OPTIONAL. Poynting Flux name (tplot)
           Vname -       OPTIONAL. Velocity Flow name (tplot)

     CALLING: thm_efi_exb, Ename, Bname, Sname

     OUTPUT: Poynting Flux is Calculated

     INITIAL VERSION: REE 08-10-31
     LASP, CU
     MODIFICATION HISTORY:
           2010-02-21: Added a check of the coordinate systems of Ename and Bname.
                       -JBT, CU/LASP.

(See projects/themis/spacecraft/fields/LASP/thm_efi_exb.pro)

## THM_EFI_FIX_FREQ_AND_PHASE

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

     FUNCTION: THM_EFI_FIX_FREQ_AND_PAHSE, E, freq=freq, ghf=ghf, dt=dt, axial=axial

     PURPOSE: A routine which integrates data to fix the gain and remove the
              phase shift due to resistive to capacitive crossover of the
              THEMIS preamps. ONLY USEFUL FOR BURST DATA.

     INPUT:
           data -        REQUIRED. Data to be fixed. DEFAULT = SPIN PLANE

     KEYWORDS:
           axial -       OPTIONAL. Changes freq and gh to AXIAL default values.
           freq -        OPTIONAL. Crossover frequency in HZ. DEFAULT = SPIN PLANE
                         Careful! Derived from Rsheath(Csheath+Cin)
           ghf -         OPTIONAL. Gain at high frequency. DEFAULT = SPIN PLANE
                         Csheath/(Csheath+Cin)
           dt -          OPTIONAL. Time between samples (s). DEFAULT = 1/8192

     CALLING: Esp = thm_efi_fix_freq_and_phase(Esp) or
              Eax = thm_efi_fix_freq_and_phase(Ex, /ax)

     OUTPUT: Data is integrated to remove gain/phase error from preamp RC
             crossover.

     NOTE ON DEFAULTS: Spin Plane: The front-end network, R=100k, C = 10pF is
        ignored. Instead, I fudge Csh = 14 pF  and Cin = 11.5 pF to realize a close
        approximation of measured gain/phase (see Bonnell et al. paper).
        Axial: Same system. I use Csh = 4 pf, Cin = 13 pF to approximate.
        One could improve the calculation with 2 poles, but the location of Cin
        (before or after the input network) would need to be questioned.
        Rsh is assumed to be 20 MOhm

     BEHAVIOR:
        (1) USE /AX for AXIAL SIGNALS!!!
        (2) DATA AT BEGINNING OF AN ARRAY MAY NOT BE CORRECTED.
        Use large arrays if possible. The program relaxes by one
        e-fold every 3 ms.
        (3) Electric field is improved for all plasma conditions. However,
        PHASE/GAIN CORRECTION MAY NOT BE ENOUGH FOR ALL PLASMA CONDITIONS.
        (4) PROBES MUST BE IN SUNLIGHT!
        (5) ONLY USEFUL FOR BURST DATA!
        (6) BE SURE TO SET DT = 1/16384 FOR AC BURST!!!

     INITIAL VERSION: REE 08-08-26
     MODIFICATION HISTORY:
     LASP, CU

(See projects/themis/spacecraft/fields/LASP/thm_efi_fix_freq_and_phase.pro)

## THM_EFI_GET_POTENTIAL

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

    FUNCTION: THM_EFI_GET_POTENTIAL, Vname

               NOT FOR GENERAL USE. CALLED BY THM_EFI...
               ONLY FOR ISOLATED PARTICLE OR WAVE BURSTS
               NOT FOR ENTIRE ORBIT.

    PURPOSE:
        Remove SC potential from axial signal.

    INPUT:
        Vname           TPLOT name of voltages.

    KEYWORDS:

    HISTORY:
       2009-03-30: REE.

(See projects/themis/spacecraft/fields/LASP/thm_efi_get_potential.pro)

## THM_EFI_SIN_FIT

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

     PROCEEDURE: THM_EFI_SIN_FIT, e, t, es=es, ec=ec, per=per

     Called by THM_EFI_REMOVE_OFFSET_AND_SPIN, name, ask=ask

     PURPOSE: DOES A QUICK SIN AND COS FIT

     INPUT:
        E -         REQUIRED (Electric Field)
        T -         REQUIRED

     WARNING: USE SHORT SEGMENTS

     OUTPUT:

        AMP  -         AMPLITUDE
        PHS  -         PHASE
        Per  -         PERIOD (Sypply and save a lot of time!)

     INITIAL VERSION: REE 08-10-31
     University of Colorado
     MODIFICATION HISTORY:

(See projects/themis/spacecraft/fields/LASP/thm_efi_sin_fit.pro)

## THM_JBT_GET_BTRANGE (FUNCTION)

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

     NAME:
         THM_JBT_GET_BTRANGE (FUNCTION)

     PURPOSE:
         This routine is to find the starting time and ending time of each
         continuous section of a give tplot variable which essentially is specified
         by a tplot name such as 'tha_efp'.
         If the routine exit unsuccessfully, it will return -1. Otherwise, it will
         return a 2D array as [2,number_of_total_bursts] which stores the
         the starting time and the ending time of each continuous section.

     CALLING SEQUENCE:
         btrange = thm_jbt_get_btrange(tvar, nbursts=nbursts, tind=tind)

     ARGUMENTS:
        tvar: (INPUT, REQUIRED). The name of a tplot variable.

     KEYWORDS:
        nbursts: (OUTPUT, OPTIONAL) A named variable to return the number of
               sections.
        tind: (OUTPUT, OPTIONAL) A named variable to return a 2D array of the index
               of starting and ending time points with structure
               [[starting],[ending]]

     EXAMPLES:
         tvar = 'tha_efp'
         btrange = thm_jbt_get_btrange(tvar, nb = nb, tind = tind)

    HISTORY:
        2009-05-04, written by Jianbao Tao, in CU/LASP.
        2010-04-08: Updated the help information. JBT, CU/LASP.

(See projects/themis/spacecraft/fields/LASP/thm_jbt_get_btrange.pro)

## THM_LSP_DERIVE_EZ

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

     FUNCTION: THM_EFI_DERIVE_EZ, E, B, minBz=minBz, minRat=minRat, ratio=ratio

     PURPOSE: DERIVES EZ ASSUMING EdotB = 0

     INPUT:
           E -       REQUIRED. Data structure in DSL
           B -       REQUIRED. Data structure in DSL

     KEYWORDS:
           minBz -       OPTIONAL. Keeps from divide by zero. DEFAULT = 0.01 nT
           minRat -      OPTIONAL. Minimum value of Bz/|B|.  DEFAULT = 0.1
           ratio -       OUTPUT. = Bz/|B|

     CALLING: thm_efi_derive_Ez, Edsl, Bdsl

     OUTPUT: Tplot

     INITIAL VERSION: REE 08-11-04
     MODIFICATION HISTORY:
     REE 09_05_01
     LASP, CU

(See projects/themis/spacecraft/fields/LASP/thm_lsp_derive_ez.pro)

## THM_LSP_FILTER

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

    FUNCTION:  THM_LSP_FILTER, x, dt, flow, fhigh, db=db

    PURPOSE:   Filters the data COMP*.

    INPUT:
    	x         - NEEDED. Just the data. Not a structure or name.
    	dt        - NEEDED. Time between points.
           freq      - NEEDED. Pole of filter. If band_pass: [f1,f2] f1<f2
                     - If low-pass: [0,f]. If high-pass [f,0]

     KEYWORDS:
           db        - OPTIONAL. If convol option is taken, default = 120.

    CREATED BY:	REE, 97-03-17 - modified 97-10-03 REE added buf_dt
    FILE:  fa_fields_filter.pro
    VERSION:  0.0
    LAST MODIFICATION:
    REE 08-11-02, rewrite for THEMIS - no call external so much slower.
    REE 09-04-30, made it a simple function.
    REE 09-05-05, Added Gaussian option. Changed passband to match digital_fliter

(See projects/themis/spacecraft/fields/LASP/thm_lsp_filter.pro)

## THM_LSP_FILTER_HIGHPASS (FUNCTION)

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

     NAME:
         THM_LSP_FILTER_HIGHPASS (FUNCTION)

     PURPOSE:
         CAUTION: THIS ROUTINE ONLY WORKS FOR DATA SAMPLED AT EITHER 8192 HZ OR
                  16384 HZ.
         In general, this routine works as a high-pass filter on the input data.
         The data to be filtered must be a continuously sampled 1D array. The basic
         process of this routine is the following. First, the input data will be
         low-pass filtered with two Finite Impulse Response filters and 2:1
         decimations. The details of this procedure is described in the paper
            Cully, Space Sci Rev, 2008, V141, 343-355.
         Second, the output from the first step is extracted from the input data to
         generate the final output. This whole process is equivalent to a high-pass
         filter.
         If the routine exit unsuccessfully, -1 will be retured.

     CALLING SEQUENCE:
         output = thm_lsp_filter_highpass(datain, dt, [keywords])

     ARGUMENTS:
         datain: (INPUT, REQUIRED) The data to be filtered. It must be a 1D array.
         dt: (INPUT, REQUIRED) The sample interval of DATAIN in seconds;
               1/dt = sample_rate.

     KEYWORDS:
         freqlow: (OUTPUT, OPTIONAL) The approximate lower bound of the frequency
                  range of the output of the routine.

    HISTORY:
        2009-05-03: Created by Jianbao Tao, CU/LASP.
        2009-05-17: Fixed the edge effect due to sectioning original data.
                    Jianbao Tao, CU/LASP
        2010-01-22: Fixed the issue of dealing with a too-short input array.
                    Jianbao Tao, CU/LASP

     VERSION:
     $LastChangedBy: jimm $
     $LastChangedDate: 2025-09-22 14:38:29 -0700 (Mon, 22 Sep 2025) $
     $LastChangedRevision: 33649 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/fields/LASP/thm_lsp_filter_highpass.pro $

(See projects/themis/spacecraft/fields/LASP/thm_lsp_filter_highpass.pro)

## THM_LSP_FIND_BURST

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

    PRO: THM_LSP_FIND_BURST

               NOT FOR GENERAL USE.

    PURPOSE:
        Isolate an indivitual burst for analysis.

    INPUT:
        Data          -NEEDED. A data structure
        tfind         -OPTIONAL. Time of interest.

    KEYWORD:

    HISTORY:
       2009-05-30: REE. Broke out to run with wave burst.

(See projects/themis/spacecraft/fields/LASP/thm_lsp_find_burst.pro)

## THM_LSP_FIND_SPIKES

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

    FUNCTION: THM_LSP_FIND_SPIKES

               NOT FOR GENERAL USE. CALLED BY THM_EFI_REMOVE_SPIKES
               ONLY FOR ISOLATED PARTICLE OR WAVE BURSTS
               NOT FOR ENTIRE ORBIT.

    PURPOSE:
        Remove the non-physical spiky signals in the efw data.

    INPUT:
        t             -NEEDED. Time array
        xx            -NEEDED. EFP data, DO NOT GIVE EFW DATA. Won't work.
        per           -NEEDED. Spin period.

    KEYWORD:
        nwin          -OPTIONAL. Number of points in spike search window. DFLT = 16
        spikesig      -OPTIONAL. Sigma of spikes. DFLT = 5
        sigmin        -OPTIONAL. Minimun of sigma. DFLT = 0 mV/m.

    OUTPUT:
        tpks          RETURN VALUE. Time of peaks (mod spin per) + t0
        Amp           Estimated amplitude of spikes. Helps remove_spikes.

    HISTORY:
       2009-05-30: REE. Broke out to run with wave burst.

(See projects/themis/spacecraft/fields/LASP/thm_lsp_find_spikes.pro)

## THM_LSP_GET_SPEC (PROCEDURE)

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

     NAME:
         THM_LSP_GET_SPEC (PROCEDURE)

     PURPOSE:
         Get the power spectrum density (PSD) of a given tplot variable.

     CALLING SEQUENCE:
         thm_lsp_get_spec, tvar, units = units, prefix = prefix, fftlen = fftlen, $
            yrange = yrange

     ARGUMENTS:
         tvar: (INPUT, REQUIRED) The name of a tplot variable to calculate the
               PSD from.

     KEYWORDS:
         units: (INPUT, OPTIONAL) A string of the units of the data in the tvar. By
               default, it is obtained from dlim.data_att.units, or 'unknown' if
               dlim.data_att.units is not available.
         prefix: (INPUT, OPTIONAL) The prefix for tplot variables that contain the
               resulting PSD. By default, prefix = tvar.
         fftlen: (INPUT, OPTIONAL) The number of data points to FFT. By default,
               fftlen = 512.
         yrange: (INPUT, OPTIONAL) The yrange for the spectra. By default, yrange =
               [1, Nyquist] in units of Hz.
         ufactor: (INPUT, OPTIONAL) A factor to convert units from one to another.
         instr_resp: (INPUT, OPTIONAL) The instrument response as a function of
               frequency. The number of elements of instr_resp should be the same
               as (fftlen/2 + 1). By default, instr_resp = 1.
         /checkenergy: (INPUT, OPTIONAL) If set, the ratios of time-domain energy to
               freq-domain energy are stored into tplot variables. By default, no
               such output is generated.
         /phase: If set, phase will be calculated and saved into tplots.
         /ft   : If set, the FFT of the input data will be saved.

     EXAMPLES:
         See thm_crib_lsp_get_spec.pro which is typically located under
         TDAS_DIR/idl/themis/examples.

     HISTORY:
       2010-03-07: Created by Jianbao Tao (JBT), CU/LASP.
       2012-07-26: JBT, SSL, UC Berkeley.
                   1. Removed the spectral averaging.
                   2. Added keywords *phase* and *ft* to output phase and FFT data.

     VERSION:
     $LastChangedBy: jianbao_tao $
     $LastChangedDate: 2012-07-27 12:29:50 -0700 (Fri, 27 Jul 2012) $
     $LastChangedRevision: 10753 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/fields/LASP/thm_lsp_get_spec.pro $

(See projects/themis/spacecraft/fields/LASP/thm_lsp_get_spec.pro)

## THM_LSP_MEDIAN_SMOOTH

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

    FUNCTION: THM_LSP_MEDIAN_SMOOTH, x, nsmooth

               NOT FOR GENERAL USE. CALLED BY THM_EFI...
               ONLY FOR ISOLATED PARTICLE OR WAVE BURSTS
               NOT FOR ENTIRE ORBIT.
    PURPOSE:
        Smooth data with median rather than average - removes spikes.

    INPUT:
        x             -NEEDED. Array
        nsmooth       -OPTIONAL. Number of points in smoothing. DEFAULT = 11
                      -MUST BE ODD.

    KEYWORDS:

    HISTORY:
       2009-04-28: REE.

(See projects/themis/spacecraft/fields/LASP/thm_lsp_median_smooth.pro)

## THM_LSP_NOTCH_SPIKES

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

    FUNCTION: THM_LSP_NOTCH_SPIKES

               NOT FOR GENERAL USE.
               ONLY FOR ISOLATED PARTICLE OR WAVE BURSTS
               NOT FOR ENTIRE ORBIT.

    PURPOSE:
        Remove the non-physical spiky signals in the efw data.

    INPUT:
        t             -NEEDED. Time array
        x             -NEEDED. Data
        per           -NEEDED. Spin period.
        tpks          -NEEDED. Phase of spikes.

    KEYWORD:
        nfit          -OPTIONAL. Number of points in the fit window. DFLT = 16 (256 for wave)
        fit           -OPTIONAL. If set, will perform a Gauss fit.
        Amp           -OPTIONAL. Estimated amplitudes. Same number of elements as tpks.
        Diagnose      -OPTIONAL. Plots fits and notchs.
        Talk          -OPTIONAL. Indicates number of fits and notchs.

    HISTORY:
       2009-05-30: REE. Broke out to run with wave burst.

(See projects/themis/spacecraft/fields/LASP/thm_lsp_notch_spikes.pro)

## THM_LSP_REMOVE_SPIKES

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

    PRO: THM_LSP_REMOVE_SPIKES

               NOT FOR GENERAL USE.
               ONLY FOR ISOLATED PARTICLE OR WAVE BURSTS
               NOT FOR ENTIRE ORBIT.

    PURPOSE:
        Remove the non-physical spiky signals in the efw data.

    INPUT:
        t             -NEEDED. Time array
        Ex, Ey, Ez    -NEEDED. Data. Leave blank or set to zero to skip.
        per           -NEEDED. Spin period.
        Efp           -NEEDED for wave burst. Not needed for particle burst.

    KEYWORD:
        nwin          -OPTIONAL. Number of points in spike search window. DFLT = 16
        spikesig      -OPTIONAL. Sigma of spikes. DFLT = 5
        sigmin        -OPTIONAL. Minimun of sigma. DFLT = 0 mV/m.
        nfit          -OPTIONAL. Number of points in the fit window. DFLT = 16
        fit           -OPTIONAL. If set, will fit spikes to Gaussian. DFLT = 0

    HISTORY:
       2009-05-12: REE. Complete rewrite for wave burst.

     VERSION:
     $LastChangedBy$
     $LastChangedDate$
     $LastChangedRevision$
     $URL$

(See projects/themis/spacecraft/fields/LASP/thm_lsp_remove_spikes.pro)

## THM_LSP_REMOVE_SPINTONE

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

     FUNCTION: THM_LSP_REMOVE_SPINTONE, t, x, per, SpinPoly=SpinPoly, $
                                        nsmooth=nsmooth, talk=talk

               NOT FOR GENERAL USE. CALLED BY THM_EFI...
               ONLY FOR ISOLATED PARTICLE OR WAVE BURSTS
               NOT FOR ENTIRE ORBIT.

     PURPOSE: GETS RID OF SPIN TONE AND OFFSET ON MEDIUM SIZE STRETCHES

     INPUT:
        t             -NEEDED. Time array.
        x             -NEEDED. Data array.
        per           -NEEDED. Spin period. NOTE: input per/2 for 2nd harmonic, etc.

     KEYWORDS:
                      -DEFAULT ACTION. If neither nsmooth or SpinPoly are set, sin
                                       and cos fits over entire period are used.
        nsmooth       -OPTIONAL. If set, it takes precedence. It uses qfit
                                 and "median smooth" sin and cos over
                                 nsmooth points.
        SpinPoly      -OPTIONAL. If set (and nsmooth not set), it uses qfit
                                 and polyfits sin and cos over nsmooth points.

        talk          -OPTIONAL. Plots diagnostics.
        fail          -OPTIONAL. If the removing fails, fail = 1.
                                   Otherwise fail = 0.

     OUTPUT: TPLOT STORE

     HISTORY:
       INITIAL VERSION: REE 99-03-25 (ff_remove_spintone)
       Space Scienes Lab, UCBerkeley
       MODIFICATION HISTORY:
       08-10-31 Modified for THEMIS by REE
       University of Colorado

       2011-05-20: Added the keyword FAIL.
             Jianbao Tao (JBT), CU/LASP.

(See projects/themis/spacecraft/fields/LASP/thm_lsp_remove_spintone.pro)

## THM_LSP_REMOVE_SPIN_EPOCH

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

    FUNCTION: THM_LSP_REMOVE_SPIN_EPOCH, t, x, per, talk=talk

               NOT FOR GENERAL USE. CALLED BY THM_EFI_REMOVE_SPIKES
               ONLY FOR ISOLATED PARTICLE OR WAVE BURSTS
               NOT FOR ENTIRE ORBIT.

    PURPOSE:
        Remove the non-physical spiky signals in the efw data.

    INPUT:
        t             -NEEDED. Time array
        x             -NEEDED. Data
        per           -NEEDED. Spin period.

    KEYWORDS:
        talk          -OPTIONAL. Provides diagnostic plots.

    HISTORY:
       2008-11-08: Created by Jianbao Tao at LASP@CU-Boulder.
       2008-11-10: The head comment was added.
       2009-03-30: REE. Rewrite to test epoch analysis.

(See projects/themis/spacecraft/fields/LASP/thm_lsp_remove_spin_epoch.pro)

## THM_QFIT

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

     FUNCTION: THM_QFIT,  data, phs, phsf=phsf, es=es, ec=ec, zero=zero,
                      do_sigma=do_sigma, sigma=sigma,
                      period=period, slide=slide, n_fitpts=n_fitpts,
                      out=out, max_err=max_err, bad_pts=bad_pts

     PURPOSE: User unfriendly fit routine.
              NOTE: REQUIRES CONTINUOUS BUFFERS!
              NOT FOR GENERAL USE.

     INPUT:
           data -        REQUIRED. A DATA ARRAY -  NOT A STRUCTURE!
                         RECOMMEND: dat_in does not have NANS. One nan
                                    may destroy entire period.
           phs -         REQUIRED. An array of phases.
                         IMPORTANT! All phases must be valid! No NANs!

     KEYWORDS:
           period   -    INPUT. Fit period. DEFAULT = 4pi
           slide    -    NO LONGER AN OPTION!
                         NOTE: Slide will be forced to be pi/2.
           n_fitpts -    INPUT. Number of points per fit. DEFAULT = 64.
           do_sigma -    OPTION. /do_sigma fills sigma.
           out      -    OPTION. /out fills bad_pts.
                         NOTE: FOR OUTLYER REJECTION, SEE BELOW!
           max_err  -    INPUT. Maximum allowable error of bad_pts. DEFAULT=25 nT

     OUTPUT:
           phsf    -     OUTPUT. Phase of fit -> Time of fit.
           es      -     OUTPUT. Sin phase of fit.
           ec      -     OUTPUT. Cos phase of fit.
           zero    -     OUTPUT. Zero level of fit.
           sigma   -     OUTPUT. Deviation in nT. Only filled if /do_sigma
           bad_pts -     OUTPUT. Deviation in nT. Only filled if /out

     CALLING:
           SEE ff_magdc for an example. MUST USE fa_fields_bufs, and
           ff_zero_crossing first.

     OUT-LYING POINTS REJECTION:
           The program must be iterated. For example, below shows one interation:

           ff_qfit,data,phs,phsf=phsf,es=es,ec=ec,zero=zero,/out, bad_pts=bad_pts
           data(bad_pts) = !values.f_nan
           index = where(finite(data), n_index)
           IF n_index GT 0 then BEGIN
               data = data(index)
               phs  = phs(index)
               ff_qfit,data,phs,phsf=phsf,es=es,ec=ec,zero=zero
           ENDIF ELSE print, "Big trouble! No valid points."

     HISTORY:
       INITIAL VERSION: REE 97-10-05
       Space Sciences Lab, UCBerkeley
       2011-05-20: Added the keyword FAIL.
             Jianbao Tao (JBT), CU/LASP.

(See projects/themis/spacecraft/fields/LASP/thm_qfit.pro)

## TRANGE_CLIP (PROCEDURE)

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

     NAME:
         TRANGE_CLIP (PROCEDURE)

     PURPOSE:
         Utility to trim the time range of a tplot variable and remove
         excess data.

     CALLING SEQUENCE:
         trange_clip,name, t1, t2, newname=newname, data_in=data_in,$
                   remove_match=remove_match, BadClip=BadClip

     ARGUMENTS:
         name: (INPUT, REQUIRED) Either tplot variable name
                    or data structure (if data_in keyword specified)
         t1: (INPUT, REQUIRED) Start time (double, time since 1970)
         t2: (INPUT, REQUIRED) Stop time (double, time since 1970)

     KEYWORDS:
         data_in: (INPUT, OPTIONAL) Set to specify that the input is a data
               structure, not a tplot name.
         remove_match: (INPUT, OPTIONAL) Removes data between t1 and t2
                         (default is keep only data between t1 and t2)
         BadClip: (OUTPUT, OPTIONAL) A named variable of the status of the clip. If
               the clip is valid, BadClip = 0, otherwise 1.
         newname: (INPUT, OPTIONAL) A new name for storing the clip into a tplot
               variable if the name is also a tplot variable name.

     Outputs:
        Modifies the specified tplot name or data structure.

     Examples:
         tvar = 'thd_fgh_dsl'
         newname = tvar + '_clip'
         trange_clip, tvar, t1, t2, newname = newname

     HISTORY:
        REE. 09-05-11. Changed to work with CLEAN EFP. Added BadClip=BadClip

     VERSION:
     $LastChangedBy$
     $LastChangedDate$
     $LastChangedRevision$
     $URL$

(See projects/themis/spacecraft/fields/LASP/trange_clip.pro)

## VH (SHORT FOR VIEWHELP)

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

     NAME:
        VH (short for ViewHelp)

     PURPOSE:
         Make a shortcut to the IDL procedure DOC_LIBRARY

     CALLING SEQUENCE
         vh, pro_name

     ARGUMENTS:
         pro_name: (INPUT, REQUIRED) The name of the routine whose help document is
             to be shown. It could be a string. For example, the following IDL
             command shows the help info of the routine TPLOT.
                       vh, 'tplot'
             It could also simply be the name of the routine (without the quotes),
             if no variable with the same name as the routine is defined. For
             example, if no variable is named TPLOT, the following command command
             does the same thing as the one above.
                       vh, tplot

     HISTORY:
       2008-05-23: Created by Jianbao Tao (JBT), CU/LASP
       2010-12-12: JBT, CU/LASP.
           1. The help document was improved.
       2012-07-20: JBT, SSL, UC Berkeley.
           1. Added the VERSION to the documentation comment.

     VERSION:
       $LastChangedBy: jianbao_tao $
       $LastChangedDate: 2012-07-23 17:44:33 -0700 (Mon, 23 Jul 2012) $
       $LastChangedRevision: 10737 $
       $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/fields/LASP/vh.pro $

(See projects/themis/spacecraft/fields/LASP/vh.pro)

## [3]

[Previous Routine] [List of Routines]

     NAME:

           FFT_CONVOLUTION

     PURPOSE:

    		Computes the convolution of two or many 1D to 3D arrays by using the FFT.

     DESCRIPTION:

    		This function computes in one time the convolution of an array with
    		one or more convolution kernels, e.g. F*K1*K2*...Kn.
    		1 dimensional to 3 dimensional arrays are supported.

     CATEGORY:

           Mathematics.

     CALLING SEQUENCE:

    		Result = FFT_CONVOLUTION(array, kernel, /DOUBLE)

     INPUTS:

    		Array: 1-D to 3-D array to be convolved.

    		Kernel: 1-D to 3-D array to be used as convolution kernel.
    				Kernel Must have the SAME SIZE as Array.
    				For multiple convolutions Kernel must have the dimension of Array + 1 and
    				must have one convolution kernel for each element of the Last dimension:
    				e.g.: for F(x,y)*K1(x,y)*K2(x,y) where F is of LX*LY size the kernel is
    				an array of [LX, LY, 2] in size.
    				The Kernel is always centered on the Array points to make convolution.

     KEYWORD PARAMETERS:

    		DOUBLE: if set uses the double precision for the FFT.

     MODIFICATION HISTORY:

           Feb 2004 - 	Gianluca Li Causi & Massimo De Luca, INAF - Rome Astronomical Observatory
    					licausi@mporzio.astro.it
    					http://www.mporzio.astro.it/~licausi/

(See projects/themis/spacecraft/fields/LASP/fft_convolution.pro)