This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
PROCEDURE: dat2angsplit HELPER function take the dat component of a structure and splits it into an array ordered in terms of theta = energy*angle->energy*theta*phi dimensions 16*64->16*4*16, phi is guaranteed to be contiguous but not necessarily ascending(some phi may be out of phase by 180 degrees) returns indices to perform this transformation $LastChangedBy: lphilpott $ $LastChangedDate: 2012-06-14 10:44:44 -0700 (Thu, 14 Jun 2012) $ $LastChangedRevision: 10559 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/dat2angsplit.pro $
(See projects/themis/spacecraft/particles/SST/dat2angsplit.pro)
$Id: $
(See projects/themis/spacecraft/particles/SST/thm_pdist.pro)
Procedure: THM_SST_ADD_SPINDATA.PRO
Purpose: Adds appropriate spin model data to SST common block structure.
Arguments:
cashe: structure from common block
Keywords:
trange: Two-element time range of requested data (double)
use_eclipse_corrections: Flag to specify which spin model will be used:
0 - No corrections (default)
1 - Use partial corrections
2 - Use full eclipse corrections
Notes: To be called within thm_load_sst.
(See projects/themis/spacecraft/particles/SST/thm_sst_add_spindata.pro)
NAME:
thm_sst_atten_scale
PURPOSE:
This routine determines the appropriate attenuator scale factor array based on the SST angle mode and
the attenuator flags
Inputs:
atten_flags: 4-bit flag indicating which attenuators are engaged
data_dims: The return value of dimen(data.data)
Keywords:
scale_factors(optional): 4-element array with the scaling factors for each attenuator pinhole.
Defaults to 1./64.
Returns:
Scaling factor array
SEE ALSO:
thm_sst_convert_units
NOTES:
atten_flags are a 4-bit value for the attenuator flags
Defined as MSB,Open Equatorial Attenuator,Closed Equatorial Attenuator,Open Polar Attenuator,Closed Polar Attenuator, LSB
With MSB/LSB not representing actual bits, but as labels to clarify bit order.
Some examples:
0x5: both attenuators closed
0xA: both attenuators open
0x6: equatorial closed, polar open (Occurs during stuck atten error on themis D)
0xf: Error state. Invalid data.
0x9: equatorial open, polar closed (This should never actually happen)
Under normal circumstances both attenuators are in the same state and the open/closed flags are mutually exclusive.
$LastChangedBy: pcruce $
$LastChangedDate: 2014-01-03 12:10:47 -0800 (Fri, 03 Jan 2014) $
$LastChangedRevision: 13737 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/thm_sst_atten_scale.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_atten_scale.pro)
pro thm_sst_crib This is an example crib sheet that will load Solid State Telescope data. Open this file in a text editor and then use copy and paste to copy selected lines into an idl window. Or alternatively compile and run using the command: .RUN THM_SST_CRIB Author: Davin Larson $Id:$
(See projects/themis/spacecraft/particles/SST/thm_sst_crib.pro)
PROCEDURE: thm_sst_dat2angsplit HELPER function take the dat component of a structure and splits it into an array ordered in terms of theta = energy*angle->energy*theta*phi dimensions 16*64->16*4*16, phi is guaranteed to be contiguous but not necessarily ascending(some phi may be out of phase by 180 degrees) returns indices to perform this transformation $LastChangedBy: lphilpott $ $LastChangedDate: 2012-06-15 12:11:29 -0700 (Fri, 15 Jun 2012) $ $LastChangedRevision: 10569 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/thm_sst_dat2angsplit.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_dat2angsplit.pro)
PROCEDURE: thm_sst_energy_extrapolate
PURPOSE: Performs linear extrapolation of sst data to a new set of lower energies
INPUTS:
dist_data:
The sst 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='psef',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=[5000,7000,10000]
NOTES:
$LastChangedBy: pcruce $
$LastChangedDate: 2012-12-13 16:23:14 -0800 (Thu, 13 Dec 2012) $
$LastChangedRevision: 11355 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/thm_sst_energy_extrapolate.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_energy_extrapolate.pro)
PROCEDURE: THM_SST_ERANGE_BIN_VAL
Purpose:
This routine generates the values that will be subtracted to remove electronic noise. The actual subtraction is done by thm_sst_remove_sunpulse.pro
A separate value will be calculated for each combination of bin and energy, but a single value will be calculated for all times(at a particular bin/energy).
This value will be generated using one of several different functions of the values across time. The functions can be specified by the user.
The user should never call this routine directly, but should instead provide the appropriate arguments to thm_part_moments,thm_part_moments2, & thm_part_getspec
These routines will guarantee that this routine is called correctly.
Arguments(note these arguments are generated correctly in thm_part_moments & thm_part_moments2)
thx: a string representing a probe prefix(ie 'tha')
instrument: a string representing the instrument(ie 'psif') Note that this routine will only perform an operation if
it is passed a string representing sst full distribution data. (ie 'psif', 'psef')
times: a list of times for the sst measurements, this list is generated by thm_part_dist
Keywords:
method_clean: If set to 'manual', this keyword disables the enoise code, as another method will be used by thm_sst_remove_sunpulse.pro
enoise_bins: A 0-1 array that indicates which bins should be used to calculate electronic noise. A 0 indicates that the
bin should be used for electronic noise calculations. This is basically the output from the bins argument of edit3dbins.
It should have dimensions 16x4.
enoise_bgnd_times: This should be either a 2 element array or a 2xN element array(where n is the number of elements in enoise_bins).
The arguments represents the start and end times over which the electronic background will be calculated for each
bin. If you pass a 2 element array the same start and end times can be used for each bin. If you pass a 2xN element
array, then the Ith bin in enoise_bins will use the time enoise_bgnd_time[0,I] as the start time and enoise_bgnd_time[1,I] as
the end time for the calculation of the background for that bin. If this keyword is not set then electronic noise will not
be subtracted.
enoise_remove_method(default: 'fit_median') set the keyword to a string specifying the method you want to use to calculate the electronic noise that will be subtracted
This function combines values across time. The allowable options are:
'min': Use the minimum value in the time interval for each bin/energy combination.
'average': Use the average value in the time interval for each bin/energy combination.
'median': Use the median value in the time interval for each bin/energy combination.
'fit_average': Fill in selected bins with a value that is interpolated across phi then subtracts the average of the difference
between the interpolated value and the actual value from each selected bin/energy combination.
'fit_median' :Fill in selected bins with a value that is interpolated across phi then subtracts the median of the difference
between the interpolated value and the actual value from each selected bin/energy combination.
'fill': Fill the selected bins using the technique specified by enoise_remove_method_fit, or interpolation by default. (note that if this method is used, enoise_bgnd_time is not required)
enoise_remove_fit_method(default:'interpolation'): Set this keyword to control the method used in 'fit_average' & 'fit_median' to
fit across phi. Options are 'interpolation' & 'spin_fit' By default, missing bins are interpolated across phi. Setting
enoise_remove_fit_method='spin_fit' will instead try to fill by fitting to a curve of the form A+B*sin(phi)+C*cos(phi).
SEE ALSO:
thm_part_moments.pro, thm_part_moments2.pro, thm_part_getspec.pro
thm_part_dist.pro, thm_sst_psif.pro, thm_sst_psef.pro,thm_crib_sst_contamination.pro
thm_sst_find_masking.pro, thm_sst_remove_sunpulse.pro
$LastChangedBy: pcruce $
$LastChangedDate: 2014-01-03 12:10:47 -0800 (Fri, 03 Jan 2014) $
$LastChangedRevision: 13737 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/thm_sst_erange_bin_val.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_erange_bin_val.pro)
PROCEDURE: THM_SST_FIND_MASKING
Purpose:
This routine is designed to find the indices of the masking in the SST Full distribution data.
It directly checks the common block and then returns it for use by the remove_sunpulse routine
While it is the function that actually takes the mask_fill argument, it should not ever be
directly called by a user. It was written so that it can identify the mask locations
efficiently using a total, prior to the point at which thm_part_moments and thm_part_moments2
begin to iterate over time.
The majority of the documentation can be found in thm_remove_sunpulse.pro and thm_crib_sst_contamination.pro
Arguments:
thx: a string storing the satellite prefix(ie 'tha')
instrument: a string identifying the instrument(ie 'psif')
index: a list of indices which specify the times that were requested
Keywords:
mask_remove: Set this keyword to the proportion of values that must be 0 at all energies to determine that a mask is present.
Generally .99 or 1.0 is a good value. The mask is a set of points that are set to 0 on-board the spacecraft. By default they will
be filled by linear interpolation across phi. This keyword should be passed down via _extra from the parent
routine. If this keyword is not set, this routine will always return -1.
SEE ALSO:
thm_part_moments.pro, thm_part_moments2.pro, thm_part_getspec.pro
thm_part_dist.pro, thm_sst_psif.pro, thm_sst_psef.pro, thm_crib_sst_contamination.pro
thm_sst_remove_sunpulse.pro
$LastChangedBy: pcruce $
$LastChangedDate: 2013-01-10 16:45:16 -0800 (Thu, 10 Jan 2013) $
$LastChangedRevision: 11423 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/thm_sst_find_masking.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_find_masking.pro)
Procedure: THM_SST_PSEB VERSION: $LastChangedBy: $ $LastChangedDate: $ $LastChangedRevision: $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/SST/thm_sst_psef.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_pseb.pro)
Procedure: THM_SST_PSEF For documentation on sun contamination correction keywords that may be passed in through the _extra keyword please see: thm_sst_remove_sunpulse.pro or thm_crib_sst_contamination.pro VERSION: $LastChangedBy: aaflores $ $LastChangedDate: 2016-02-05 14:02:49 -0800 (Fri, 05 Feb 2016) $ $LastChangedRevision: 19904 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/thm_sst_psef.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_psef.pro)
$Id: thm_sst_pser.pro 19904 2016-02-05 22:02:49Z aaflores $
(See projects/themis/spacecraft/particles/SST/thm_sst_pser.pro)
Procedure: THM_SST_PSIF For documentation on sun contamination correction keywords that may be passed in through the _extra keyword please see: thm_sst_remove_sunpulse.pro or thm_crib_sst_contamination.pro VERSION: $LastChangedBy: aaflores $ $LastChangedDate: 2016-02-05 14:02:49 -0800 (Fri, 05 Feb 2016) $ $LastChangedRevision: 19904 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/thm_sst_psif.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_psif.pro)
$Id: thm_sst_psir.pro 19904 2016-02-05 22:02:49Z aaflores $
(See projects/themis/spacecraft/particles/SST/thm_sst_psir.pro)
Procedure: thm_sst_quality_flags Description: makes a bitpacked tplot variable containing quality flags for SST Bit 0: saturated. (psef_count_rate > 10k) Bit 1: attenuator error (stuck attenuator or incorrect indicator) Bit 2: too low(<2.5 s) or too high(>5s) spin period Bit 3: earth shadow Bit 4: lunar shadow Set timespan by calling timespan outside of this routine.(e.g. time/duration is not an argument) $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/SST/thm_sst_quality_flags.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_quality_flags.pro)
PROCEDURE: THM_SST_REMOVE_SUNPULSE
Purpose:
Routine to perform a variety of calibrations on full distribution sst data.
These can remove sun contamination and on-board masking. They can also scale
the data to account for the loss of solid angle from the inability of the sst
to measure directly along the probe geometric Z axis and the inability to measure
directly along the probe geometric xy plane.(ie X=0,Y=0,Z = n or X=n,Y=m,Z=0, are SST 'blind spots')
THM_REMOVE_SUNPULSE routine should not generally be called directly.
Keywords to it will be passed down from higher level routines such as, thm_part_moments,
thm_part_moments2, thm_part_dist,thm_part_getspec, thm_sst_psif, and thm_sst_psef
Arguments:
dat: the dat structure used in thm_part_dist, etc...
Keywords:
method_clean: Simplified sun cleaning methods:
Allowed options are:
'manual': To use this option you need to specify the contaminated bins using the sun_bins keyword. Specified bins are removed and interpolated over phi.
'automatic': This method attempts to find contaminated bins using a statistical outlier test(modified z-score)
then fills the bins by interpolation over phi.
sun_bins: method_clean manual removal bin selection. Must be either a 64 element or a 16x64 element 0-1 array. Bins set to 1 will be used, bins set to 0
will be removed and filled.
The 64 element input is the same format as the output from edit3dbins, it removes and fills all energies at a particular angle of measure.
The 16x64 element input allows the user to remove some bins at some of the 16 energies but to keep others.
all_angle_median: set this option to replace the angular distribution with the median
of the data calculated over the all angles(thetas & phis) for each energy.
This will generally eliminate contamination in some of the moments, but will make
analysis of angular plots impossible. It will also eliminate the velocity
moment.
scale_sphere: set this option to increase the value of all counts by 16%. This accounts
for the loss of phase space mentioned above.
method_sunpulse_clean: set this to a string: Either 'median' or 'spin_fit' or 'z_score_mod'
'median': This will remove all points that are greater
than 2.0 standard deviations from the median.By default they will be filled by a
linear interpolation across the phi angle by default.
'spin_fit': This will remove all points that are greater
than 2.0 standard deviations from a spin fit across phi angle. The equation used to
fit is A+B*sin(phi)+C*cos(phi). By default these points will be filled by a linear
interpolation across the phi angle. The fitting is done using the svdfit routine
from the idl distribution.
'z_score_mod': This will remove all points that have a modified z-score(calculated across phi) greater than 3.5
The modified z-score is a normalized outlier detection test defined as follows:
#1 X_Bar = median(X+1)
#2 Sigma = MAD = Median Absolute Deviation = median(abs(X-X_Bar))
#3 Z_Score_Mod = .6745*(X - X_Bar)/Sigma
This test can often get excellent results because it is insensitive to variation in standard deviation
and skew in the distributions.
limit_sunpulse_clean: set this equal to a floating point number that will override the default of 2.0 standard
deviation tolerance or 3.5 z_score_tolerance, used by the sunpulse cleaning methods by default.
This keyword will only have an effect if the method_sunpulse_clean keyword is set.
fillin_method: Set this keyword to a string that specifies the method used to fill the points that are
removed via the method_sunpulse_clean or the mask_remove keywords, and bins removed when enoise_remove_method='fill'.
'interpolation': this routine will interpolate across the phi angle. This is the
default behavior. Interpolation is done using the interp_gap routine.
'spin_fit': this routine will perform a spin fit to the data after the points
have been removed using the equation A+B*sin(phi)+C*cos(phi). It will then generate
expected values for each removed phi using the equation of fit. The fitting is done using
the svdfit routine from the idl distribution. Note that if 'spin_fit' is selected for
the clean method and the fill method, this routine will perform two spin fits.
'blank' : Just removes the data but doesn't fill with anything
mask_remove: Set this keyword to the proportion of values that must be 0 at all energies to determine that a mask is present.
Generally .99 or 1.0 is a good value. The mask is a set of points that are set to 0 on-board the spacecraft.
By default they will be filled by linear interpolation across phi. NOTE: This argument is not actually accepted by
this routine, it is only documented here. If you provide this argument to thm_part_moments,
thm_part_moments2, or thm_part_getspec, those routines will appropriately set the value for the
mask_tot keyword to this routine.
enoise_bins: A 0-1 array that indicates which bins should be used to calculate electronic noise. A 0 indicates that the
bin should be used for electronic noise calculations. This is basically the output from the bins argument of edit3dbins.
It should have dimensions 16x4. NOTE: This argument is not actually accepted by
this routine, it is only documented here. If you provide this argument to thm_part_moments,
thm_part_moments2, or thm_part_getspec, those routines will appropriately set the value for the
enoise_tot keyword to this routine.
enoise_bgnd_time: This should be either a 2 element array or a 2xN element array(where n is the number of elements in enoise_bins).
The arguments represents the start and end times over which the electronic background will be calculated for each
bin. If you pass a 2 element array the same start and end times can be used for each bin. If you pass a 2xN element
array, then the Ith bin in enoise_bins will use the time enoise_bgnd_time[0,I] as the start time and enoise_bgnd_time[1,I] as
the end time for the calculation of the background for that bin. If this keyword is not set then electronic noise will not
be subtracted.NOTE: This argument is not actually accepted by
this routine, it is only documented here. If you provide this argument to thm_part_moments,
thm_part_moments2, or thm_part_getspec, those routines will appropriately set the value for the
enoise_tot keyword to this routine.
enoise_remove_method(default: 'fit_median') set the keyword to a string specifying the method you want to use to calculate the electronic noise that will be subtracted
This function combines values across time. The allowable options are:
'min': Use the minimum value in the time interval for each bin/energy combination.
'average': Use the average value in the time interval for each bin/energy combination.
'median': Use the median value in the time interval for each bin/energy combination.
'fit_average': Fill in selected bins with a value that is interpolated across phi, then use
the average of these values across the time interval for each bin/energy combination.
'fit_median' : Fill in selected bins with a value that is interpolated across phi, then use
the mean of these values across the time interval for each bin/energy combination.
'fill': Fill in selected bins across phi, do not perform any subtraction. This will
provide the cleanest looking plot, but the signal in that bin will be entirely removed.
NOTE: This argument is not actually accepted by
this routine, it is only documented here. If you provide this argument to thm_part_moments,
thm_part_moments2, or thm_part_getspec, those routines will appropriately set the value for the
enoise_tot keyword to this routine.
enoise_remove_fit_method(default:'interpolation'): Set this keyword to control the method used in 'fit_average' & 'fit_median' to
fit across phi.
Options are:
'interpolation'
'spin_fit'
By default, missing bins are interpolated across phi. Setting
enoise_remove_fit_method='spin_fit' will instead try to fill by fitting to a curve of the form A+B*sin(phi)+C*cos(phi).
mask_tot: The user should never manually set this keyword. thm_part_moments,thm_part_moments2, & thm_part_getspec
will properly set this keyword, if the mask_remove keyword is set when they are called.
enoise_tot: The user should never manually set this keyword. thm_part_moments,thm_part_moments2, & thm_part_getspec
will properly set this keyword, if enoise keywords are set when called.
Examples:
thm_part_moments,probe='a',inst='ps?f',method_clean='automatic'
sun_bins=dblarr(64)+1
sun_bins[[30,39,40,46,55,56,61,62]] = 0 ;these are the bin numbers that will be removed
thm_part_moments,probe='a',inst='ps?f',sun_method='manual',sun_bins=sun_bins
thm_part_moments,probe='a',instrum=['ps?f'],mag_suffix='_peif_magf',scpot_suffix='_peif_sc_pot',moments='*', $
,fillin_method='spin_fit',method_sunpulse_clean='spin_fit',limit_sunpulse_clean=1.8, $
trange=['2008-05-19','2008-05-20'],tplotsuffix='_fit_mask_fit'
thm_part_getspec, probe='a', trange=['2007-03-23','2007-03-23'],theta=[0,45], data_type='ps?f', angle='phi', $
erange=[50000,100000], /mask_remove,method_sunpulse_clean='median',limit_sunpulse_clean=1.5, $
suffix='_fit_mask_med_t2'
edit3dbins,thm_sst_psef(probe='a', time_double('2008-03-01'),method_sunpulse_clean='spin_fit', $
limit_sunpulse_clean=1.2),ebins=4,sum_ebins=1
SEE ALSO:
thm_part_moments.pro, thm_part_moments2.pro, thm_part_getspec.pro
thm_part_dist.pro, thm_sst_psif.pro, thm_sst_psef.pro,thm_crib_sst_contamination.pro
thm_sst_find_masking.pro, thm_sst_erange_bin_val.pro
$LastChangedBy: pcruce $
$LastChangedDate: 2012-08-10 09:42:49 -0700 (Fri, 10 Aug 2012) $
$LastChangedRevision: 10800 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/thm_sst_remove_sunpulse.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_remove_sunpulse.pro)
Procedure: thm_sst_set_trange Purpose: Helper function for thm_load_sst. Sets the common block time ranges for applicable data types. Input: cache: SST data pointer structure from thm_load_sst trange: two element time range Output: none Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2014-05-05 18:12:35 -0700 (Mon, 05 May 2014) $ $LastChangedRevision: 15053 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/SST/thm_sst_set_trange.pro $
(See projects/themis/spacecraft/particles/SST/thm_sst_set_trange.pro)