This page was created by the IDL library routine mk_html_help2.

Last modified: Thu Aug 6 12:53:14 2020.

Directory Listing of Routines

projects/themis/spacecraft/particles/ESA

CLEAR_ESA_COMMON_BLOCKS
THM_CRIB_ESA_DIST2SCPOT
THM_ESA_DIST2SCPOT
Estimates the SC potential from an electron sepctrum, by comparing
THM_ESA_DUMP
THM_ESA_ENERGY_EXTRAPOLATE
THM_ESA_EST_DIST2SCPOT
For a given probe and date, estimates the SC potential from PEER
THM_ESA_EST_DIST2SCPOT2
For a given probe and date, estimates the SC potential from PEER
THM_ESA_QUALITY_FLAGS[1]
THM_ESA_QUALITY_FLAGS[2]
THM_ESA_TEST_SPEC3D2
Wrapper for spec3d2, plots PEEF, PEER, PEEB data; the user clicks on
THM_LOAD_PXXM_POT4ESA
loads the pxxm_pot variable for ESA processing, performs a time

Routine Descriptions

CLEAR_ESA_COMMON_BLOCKS


Procedure:	clear_esa_common_blocks

Purpose:	Clears common blocks used in esa_pkt routines, to
               avoid using old data to create plots or L2 files
 jmm, jimm@ssl.berkeley.edu, 12-dec-2007
 $LastChangedBy: pcruce $
 $LastChangedDate: 2012-02-07 13:47:46 -0800 (Tue, 07 Feb 2012) $
 $LastChangedRevision: 9692 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/ESA/clear_esa_common_blocks.pro $

(See projects/themis/spacecraft/particles/ESA/clear_esa_common_blocks.pro)

THM_CRIB_ESA_DIST2SCPOT

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

THM_ESA_DIST2SCPOT

The program THM_ESA_DIST2SCPOT estimates the spacecraft potential
from the electron distribution by lookng for photoelectrons at low
energies. It estimates potential by comparing the slope of the low
energy electron distribution to the expected slope of secondary
electrons. (The slope of the secondary electron distribution is
approximately -2.0, see McFadden etal. 2008SSRv..141..477M)

For a given time interval, the procedure is as follows:

1) Calculate the slope of the electron distribution. The slope of the
distribution between the energies E0, and E1 is given by:

M = (log(F1)-log(F0))/(log(E1)-log(E0),

where F is the differential electron energy flux in eV/sec/cm^2/eV.

2) Next we Compare the low-energy slope with the expected slope of
secondary electrons, which is estimated to be between -2.0 at 8 eV
and -4.0 at 50 eV. (These numbers are empirical, except for the lower
limit). The upper limit of the photoelectron part of the distribution
is estimated to be the highest energy for which the slope is steeper
than the secondary electron slope.

3) Also, the electron distribution has to exhibit at least two
distinct peaks, a low-energy peak must be present with electron flux
greater than 3.0e7 eV/sec/cm^2/eV, and a higher energy peak with
electron flux greater than 1.0e-3 times the value of the overall peak
of the distribution. (These parameters are the default values, and
can be changed via the photoelectron_threshold and noise_threshold.)

4) Since slopes are calculated between energy values, the estimate
for M is at the midpoint between E0 and E1. We 'unquantize' by an
amount that depends on the difference between the actual slope and
the secondary electron slope, so that the final value of the
estimated potential is: ;

SC_POT = E0+(E1-E0)*(1-M/2)/(1-M)

For M=2, the lowest possible value, SC_POT = E0. For an infinite
slope, SC_POT is the midpoint between E0 and E1.

5) If the test for low energy photoelectrons fails, i,e, the
distribution does not show two peaks, OR the low energy, possible
photoelectron peak is below 3.0e7, OR the low energy slope is not
steeper that the secondary electron slope, OR if there is a high
energy peak, but one that is too small. Then the value for the SC_POT
estimate is set to the lowest energy in the electron distribution.

Batch File: THM_CRIB_ESA_DIST2SCPOT

Purpose: Demonstrates the use of THM_ESA_EST_DIST2SCPOT.
The program THM_ESA_EST_DIST2SCPOT estimates the spacecraft
potential using the ESA electron distribution. The SC
potential is estimated by comparison of the slope of the low
energy electron flux with the expected slope of secondary electrons

Calling Sequence:
.run thm_crib_esa_dist2scpot, or using cut-and-paste.

Arguements: None.

Notes: None.

$LastChangedBy: jimm $
$LastChangedDate: 2015-07-24 15:57:59 -0700 (Fri, 24 Jul 2015) $
$LastChangedRevision: 18252 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/ESA/thm_crib_esa_dist2scpot.pro $

(See projects/themis/spacecraft/particles/ESA/thm_crib_esa_dist2scpot.pro)

THM_ESA_DIST2SCPOT

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

NAME:
 thm_esa_dist2scpot
CALLING SEQUENCE:
 scpot = thm_esa_dist2scpot(data)
PURPOSE:
 Estimates the SC potential from an electron sepctrum, by comparing
 the slope of the electron energy distribution with the slope that
 would be expected from secondary electrons.
INPUT:
 data = 3d data structure filled by themis routines get_th?_p???
KEYWORDS:
 pr_slope = if set, show some diagnostics prints of the slope of the
            distribution
 noise_threshold = values below Noise_threshold*max(flux) are
                   considered to be in noise, if there is a positive 
                   slope, it is ignored. The default is 1.0e-3
 photoelectron_threshold = Only test for photoelctrons if the flux
                           is above this value, The default is 1.0e7
HISTORY:
 Hacked from spec3d.pro, jmm, jimm@ssl.berkeley.edu
 $LastChangedBy: jimm $
 $LastChangedDate: 2017-10-02 11:19:09 -0700 (Mon, 02 Oct 2017) $
 $LastChangedRevision: 24078 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/ESA/thm_esa_dist2scpot.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_dist2scpot.pro)

THM_ESA_DUMP

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

Purpose:
  Helper function to store single array from specified
  structure tag as tplot variable(s)

Arguments:
  ptr:  pointer to array of data structures
  name:  string of structure tag to use
  prefix:  string prefix of tplot var(s) to be created

(See projects/themis/spacecraft/particles/ESA/thm_esa_dump.pro)

THM_ESA_ENERGY_EXTRAPOLATE

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

PROCEDURE: thm_esa_energy_extrapolate
PURPOSE:  Performs linear extrapolation of esa data to a new set of higher energies

INPUTS:
  dist_data:
    The esa data structure on which the extrapolation should be performed.  (loaded by thm_part_dist_array)
KEYWORDS:

  add_energy=add_energy : Adds these energies to the current set of energies for the particle data when extrapolating.  
  lin_energy=lin_energy : Set this keyword to perform extrapolation on energy, not logarithmic.
  lin_counts=lin_counts: Set this keyword to perform extrapolation on counts, not logarithmic
  lsquadratic=lsquadratic: Set this keyword to perform least square quadratic extrapolation of count data(see interpol documentation in IDL help.)
  quadratic=quadratic: Set this keyword to perform quadratic extrapolation of count data.(see interpol documentation in IDL help.)
  lsquares=lsquares: Set this keyword to the number of bins that you want to use for least squares extrapolation of the count data(Uses poly_fit)
  spline=spline: Set this keyword to perform spline extrapolation of count data.(see interpol documentation in IDL help.)
  trange=trange: Set this keyword to a two element array specifying a subset of the data that the operation should be performed on.(Don't need to modify the whole thing with the same parameters)
  error=error:  Returns 1 if an error occurred.  Returns 0 if operation completed successfully.
  
  
  bin_select: set the bin numbers that you want to use in the extrapolation
EXAMPLES:
 dist_data = thm_part_dist_array(probe='a',type='peef',trange=time_double(['2012-02-08/09','2012-02-08/12']))
 thm_part_conv_units,dist_data,error=e
 thm_esa_energy_extrapolate,dist_data,add_energy=[100000,70000,50000]

NOTES:
  Removes the retrace bin from ESA modes that include retrace.

  $LastChangedBy: pcruce $
  $LastChangedDate: 2013-01-10 18:10:18 -0800 (Thu, 10 Jan 2013) $
  $LastChangedRevision: 11424 $
  $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/ESA/thm_esa_energy_extrapolate.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_energy_extrapolate.pro)

THM_ESA_EST_DIST2SCPOT

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

NAME:
 thm_esa_est_dist2scpot
PURPOSE:
 For a given probe and date, estimates the SC potential from PEER
 data, and plots it.
CALLING SEQUENCE:
 thm_esa_est_dist2scpot, date, probe, no_init = no_init, $
                          random_dp = random_dp, plot = plot
INPUT:
 date = a date, e.g., '2008-01-05'
 probe = a probe, e.g., 'c'
OUTPUT:
 a tplot variable 'th'+probe+'_est_scpot' is created
 If /random_dp is set, then date and probe are output 
KEYWORDS:
 trange = a time range
 no_init = if set, do not read in a new set of data
 random_dp = if set, the input date and probe are randomized, note
             that this keyword is unused if no_init is set.
 plot = if set, plot a comparison of the estimated sc_pot wht the
        value obtained from the esa L2 cdf (originally from
        thm_load_esa_pot)
 esa_datatype = 'peef', 'peer', or 'peeb'; the default is 'peer'

HISTORY:
 31-may-2015, jmm, jimm@ssl.berkeley.edu
 $LastChangedBy: jimm $
 $LastChangedDate: 2017-10-02 11:19:09 -0700 (Mon, 02 Oct 2017) $
 $LastChangedRevision: 24078 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/ESA/thm_esa_est_dist2scpot.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_est_dist2scpot.pro)

THM_ESA_EST_DIST2SCPOT2

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

NAME:
 thm_esa_est_dist2scpot2
PURPOSE:
 For a given probe and date, estimates the SC potential from PEER
 data, and plots it. This differs from the original
 thm_esa_est_dist2scpot.pro in that it uses the "eyeball test"; it
 only checks byte-scaled eflux variables.
CALLING SEQUENCE:
 thm_esa_est_dist2scpot2, date, probe, no_init = no_init, $
                          random_dp = random_dp, plot = plot
INPUT:
 date = a date, e.g., '2008-01-05'
 probe = a probe, e.g., 'c'
OUTPUT:
 a tplot variable 'th'+probe+'_est_scpot' is created
 If /random_dp is set, then date and probe are output 
KEYWORDS:
 trange = a time range
 no_init = if set, do not read in a new set of data
 random_dp = if set, the input date and probe are randomized, note
             that this keyword is unused if no_init is set.
 plot = if set, plot a comparison of the estimated sc_pot wht the
        value obtained from the esa L2 cdf (originally from
        thm_load_esa_pot)
 esa_datatype = 'peef', 'peer', or 'peeb'; the default is 'peer'
 yellow = the limit (0-255) where above this value, we assume that
          there are photo electrons in the scaled eflux
          spectrogram. This will give the potential; the default is 170.
HISTORY:
 3-mar-2016, jmm, jimm@ssl.berkeley.edu
 $LastChangedBy: jimm $
 $LastChangedDate: 2017-01-23 15:09:39 -0800 (Mon, 23 Jan 2017) $
 $LastChangedRevision: 22649 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/ESA/thm_esa_est_dist2scpot2.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_est_dist2scpot2.pro)

THM_ESA_QUALITY_FLAGS[1]

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

Procedure:
  thm_esa_quality_flags
  
Description:
  makes a bitpacked tplot variable containing quality flags for ESA
  bit0 = pre-efi boom deployment (using zeroed spacecraft potential)
  bit1 = counter overflow flag
  bit2 = solar wind mode flag(disabled)
  bit3 = flow flag, flow less than threshold is flagged
  bit4 = earth shadow
  bit5 = lunar shadow
  bit6 = manuever flag
  
  Set timespan by calling timespan outside of this routine.(e.g. time/duration is not an argument)
  
Keywords:
  probe(required): probe letter ('a','b','c','d','e')
  datatype(required): type string  ('peef','peib', etc...)
  noload(optional): set this if calling from thm_l2gen_esa
  flow_threshold(optional): flow threshold for flow flag(default = 1.0, units undocumented)
  
  
 $LastChangedBy: jimm $
 $LastChangedDate: 2018-03-12 14:57:15 -0700 (Mon, 12 Mar 2018) $
 $LastChangedRevision: 24875 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/ESA/thm_esa_quality_flags.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_quality_flags.pro)

THM_ESA_QUALITY_FLAGS[2]

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

HELPER FUNCTION (main function below)
 Returns the start and end indices of intervals where a condition
 applies

(See projects/themis/spacecraft/particles/ESA/thm_esa_quality_flags.pro)

THM_ESA_TEST_SPEC3D2

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

NAME:
 thm_esa_test_spec3d2
PURPOSE:
 Wrapper for spec3d2, plots PEEF, PEER, PEEB data; the user clicks on
 a time, and spec3d2 estimates the sc potential for each mode, and
 plots the distribution with the potential overplotted. A black line
 for the measured potential, and a red line for the
 estimated potential
INPUT:
 date = a date, e.g., '2008-01-05'
 probe = a probe, e.g., 'c'
OUTPUT:
 plots of the 3d distribution for each mode, with SC_POT plotted on
 the graph.
 init = if set, read in a new set of data
 random_dp = if set, the input date and probe are randomized, note
             that this keyword is unused if init is not set.
HISTORY:
 31-may-2015, jmm, jimm@ssl.berkeley.edu
 $LastChangedBy: jimm $
 $LastChangedDate: 2015-07-24 15:57:59 -0700 (Fri, 24 Jul 2015) $
 $LastChangedRevision: 18252 $
 $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/ESA/thm_esa_test_spec3d2.pro $

(See projects/themis/spacecraft/particles/ESA/thm_esa_test_spec3d2.pro)

THM_LOAD_PXXM_POT4ESA

[Previous Routine] [List of Routines]

NAME:
 thm_load_pxxm_pot4esa
PURPOSE:
 loads the pxxm_pot variable for ESA processing, performs a time
 offset, and also loads the efs_Potl variable fro FIT files, if it
 exists.
CALLING SEQUENCE:
 thm_load_esa_pxx_pot4esa, probe=probe, trange=trange,suffix=suffix
INPUT;
 All via keyword
OUTPUT:
 For each probe, a tplot variable 'thx_pxxm_pot', which is the SC
 potential that comes directly from the MOM L1 files, a variable,
 'thm_pxxm_pot_0', that includes a time correction, 
KEYWORDS:
 probe - ['a','b','c','d','e']
 trange -  the time range, otherwise just use whatever's there
HISTORY:
 11-May-2010, jmm, jimm@ssl.berkeley.edu
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-10 10:56:14 -0800 (Tue, 10 Jan 2012) $
$LastChangedRevision: 9526 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/ESA/thm_load_pxxm_pot4esa.pro $

(See projects/themis/spacecraft/particles/ESA/thm_load_pxxm_pot4esa.pro)