This page was created by the IDL library routine
mk_html_help2.
Last modified: Fri Nov 2 11:01:31 2012.
function butterworth_filter_resp(f, fc, N)
purpose: Calculates the transfer function of an N-pole Butterworth filter
with a given cutoff frequency Fc.
Inputs: f freqency in Hz
fc Cutoff frequency in Hz
N Number of poles (must be 1, 2 or 4)
Output: complex transfer function at given frequencies
(See themis/spacecraft/fields/butterworth_filter_resp.pro)
FUNCTION: SCM_CLEANUP_CCC
PURPOSE: cleans 8 hertz and harmonic instrument noise from scm data using
superposed epoch analysis.
The raw data is high pass filtered above 4 Hz and then averaging on
this filtered data is performed to determine the noise.
Returns de-noised data and stores tplot quantity of this data
INPUTS:requires 3-component single spacecraft data structure from thm_load_scm
OUTPUT: data structure of 3 component cleaned data
KEYWORDS:
probe: use this keyword to specify spacecraft if other than 'a'
clock: set keyword clock to base epoch on the 1 sec clock pulse closest to
the start of the interval otherwise epoch is from the beginning of
each interval
ave_window: set keyword ave_window to define window length in seconds for
averaging, Default 3 seconds in length
note for technique to work the window length should be an integer
multiple of the period of the noise
that is being removed.
min_num_windows: set keyword min_num_windows to define the minimum length
of continuous data in terms of window lengths
default is 10. The greater this number the more reliable the result.
diagnostic: set keyword diagnostic to plot spectral data and to store the
average noise, filtered (>4Hz) corrected signal,
and corrected signal for the last continuous interval anlaysed
SIDE EFFECTS: in current version data preceding the epoch for each interval
is discarded
HISTORY
Chris Chaston 9-May-2007
Modified by Olivier Le Contel 5th-July-2007
in order to include it in thm_cal_scm_ccc.pro routine
thm_cal_scm_ccc being a modified version of
thm_cal_scm routine written by Ken Bromund and Patrcik Robert
Modified by Ken Bromund 27-Sept-2007
for inclusion in TDAS (use time routines available in TDAS)
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-09 15:50:20 -0800 (Mon, 09 Jan 2012) $
$LastChangedRevision: 9520 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/scm_cleanup_ccc.pro $
(See themis/spacecraft/fields/scm_cleanup_ccc.pro)
Name:
spinfit
Purpose:
performs a spinfit on B or E field data, results should be
equivalent to FGS or EFS datatypes
Calling Sqeuence:
spinfit,arr_in_t,arr_in_data,arr_in_sunpulse_t,arr_in_sunpulse_data, $
A,B,C, avg_axis, median_axis,Sigma,Npoints,sun_data, $
min_points=min_points,alpha=alpha,beta=beta, $
plane_dim=plane_dim,axis_dim=axis_dim,phase_mask_starts=phase_mask_starts, $
phase_mask_ends=phase_mask_ends,sun2sensor=sun2sensor
Input:
arr_in_t = time array for the data
arr_in_data = the data to be spin fit
arr_in_sunpulse_t = time array for sunpulse data
arr_in_sunpulse_data = sunpulse data
Output:
A,B,C = fit parameters for spinfit
avg_axis = the average over the spin_axis direction
median_axis = the median over the spin_axis direction
sigma = sigma for each spin period
npoints = number of points in fit for each spin period
sun_data = midpoint times of spitfit data
keywords:
plane_dim = Tells program which dimension to treat as the plane. 0=x, 1=y, 2=z. Default 0.
axis_dim = Tells program which dimension contains axis to average over. Default 0. Will not
create a tplot variable unless used with /spinaxis.
min_points = Minimum number of points to fit. Default = 5.
alpha = A parameter for finding fits. Points outside of sigma*(alpha + beta*i)
will be thrown out. Default 1.4.
beta = A parameter for finding fits. See above. Default = 0.4
phase_mask_starts = Time to start masking data. Default = 0
phase_mask_ends = Time to stop masking data. Default = -1
sun2sensor = Tells how much to rotate data to align with sun sensor.
Example:
thm_spinfit,'th?_fg?',/sigma
20-sep-2010, changed sign of sun2sensor to insure agressment between
spinfit EFF and on-board EFS spinfit data, and between
spinfit FGL and on-board FGS spinfit data.
Written by Katherine Ramer
$LastChangedBy: $
$LastChangedDate: $
$LastChangedRevision: $
$URL: $
(See themis/spacecraft/fields/spinfit.pro)
Procedure: spin_tones_cleaning_vec_v5
Purpose: compute an averaged signal with a specified averaging window duration
and substract this averaged signal to raw signal
keywords: none
input :t_vec,VEC,wind_dur,samp_per
t_vec is a time array
VEC is a time vector
wind_dur is the duration of the averaging,
samp_per is the sample period of t_vec and VEC
output :VEC_AV has the duration of VEC but is obtained by
duplicating the average signal over one averaging window
along the whole time period
the average signal is obtained by summing all averaging
windows within the whole time period
VEC_CLEANED is equal to VEC-VEC_AV,
nbwind is the number of averaging window within the whole time period,
nbpts_cl is the number of points within the whole time period
i.e. also the dimension of t_vec_cleaned and VEC_CLEANED
Example:
spin_tones_cleaning_vector, t_vec,VEC,wind_dur,samp_per,$
t_vec_cleaned,VEC_AV,VEC_CLEANED,nbwind,nbpts_cl
Notes:
This routine is (should be) platform independent.
History:
12 june 2007, written by Olivier Le Contel
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-26 16:43:03 -0800 (Thu, 26 Jan 2012) $
$LastChangedRevision: 9624 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/spin_tones_cleaning_vector_v5.pro $
(See themis/spacecraft/fields/spin_tones_cleaning_vector_v5.pro)
Procedure THM_PUT_ELEMENT() Purpose: Put data into a substructure (1 level down) given the structure, the substructure tag name, and the data tag name. Syntax: thm_put_element , struct, sstruct_tag, data_tag, data where STRUCT: The structure to receive the data. SSTRUCT_TAG: The substructure tag name to receive the data (need not exist). DATA_TAG: The data tag name. DATA: The data. Keywords: None. Code: W. Michael Feuerstein, 16 June, 2009.
(See themis/spacecraft/fields/thm_cal_efi.pro)
function THM_GET_EFI_EDC_OFFSET() Purpose: Estimate the EDC offset by low-pass filtering the ADC data with a moving estimation window. Returns all NaNs, if the data interval is shorter than the minimum number of spins (see MIN_N_SPINS kw). Syntax: result = thm_get_efi_edc_offset(Y, Sample_Rate, N_Spins, Spin_Period [, Offset_Estimation_Window_Truncated] [, NEW_N_SPINS] [, MIN_N_SPINS = <long>]) where Y (n-element array) Input The ADC data needing the EDC offset calculation. Sample_Rate Input The data rate. N_Spins Input The width of the estimation window in # of spins Spin_Period Input The period of a spin [s]. Edge_Truncate Input Passed to SMOOTH, if SMOOTH is the estimation function. Offset_Estimation_Window_Truncated Output Indicates that the data interval is shorter than the estimation window requested, so the estimation window has been truncated to the greatest integral number of spins that fit into the data interval. New_N_Spins Output If OFFSET_ESTIMATION_WINDOW_TRUNCATED is set, then this will contain the adjusted number of spins. Keywords: MIN_N_SPINS I/O, long. 1 <= MIN_N_SPINS <= NOMINAL_N_SPINS. Specify the lower limit for NOMINAL_N_SPINS. Defaults to 1.
(See themis/spacecraft/fields/thm_cal_efi.pro)
THM_UPDATE_EFI_LABELS.PRO PURPOSE: To be used on THEMIS EFI 3-vectors. Labels x-axis as "E12 (<coordinate system in DLIMITS.LABLES>)" for spinning coordinate systems and "Ex (<coord. sys. in DLIMITS.LABELS>)" for despun coordinate systems. Y and Z axes are upadated correspondingly. Call after coordinate transformations. SYNTAX: thm_update_efi_labels ,<String> Arguments: <String>: A TPLOT variable name referring to a 3-vector TPLOT variable. Code: W. Michael Feuerstein, 7/2008.
(See themis/spacecraft/fields/thm_cal_efi.pro)
Procedure: THM_CAL_EFI
Purpose: Converts raw EFI (V, EDC, and EAC waveform) data into physical quantities.
Syntax: THM_CAL_EFI [, <optional keywords below>]
keywords:
VERBOSE: Input, >= 1. Set to enable diagnostic message output. Higher values of produce more and lower-level diagnostic messages.
DATATYPE: Input, string. Default setting is to calibrate all raw quantites and also produce all _0 and _dot0 quantities. Use DATATYPE
kw to narrow the data products. Wildcards and glob-style patterns accepted (e.g., ef?, *_dot0).
PROBE: Input, string. Specify space-separated probe letters, or string array (e.g., 'a c', ['a', 'c']). Defaults to all probes.
VALID_NAMES: Output, string. Return valid datatypes, print them, and return.
COORD: I/O, string. Set to coordinate system of output (e.g., 'gse', 'spg', etc,... see THEMIS Sci. Data Anal. Software
Users Guide). Defaults to 'dsl'.
IN_SUFFIX: Input, scalar or array string. Suffix to expect when parsing input TPLOT variable names.
OUT_SUFFIX: I/O, scalar or array string. Suffix to append to output TPLOT variable names in place of IN_SUFFIX (usally = IN_SUFFIX).
TEST: 1 or 0. Disables selected /CONTINUE to MESSAGE. For QA testing only.
STORED_TNAMES: OUTPUT, string array. Returns each TPLOT variable name invoked in a STORE_DATA operation (chron. order). (Not sorted or uniqued.)
ONTHEFLY_EDC_OFFSET:OUTPUT, float. Return the EDC offset array calculated on-the-fly in a structure (tag name = probe letter, subtagname =
datatype). *** WARNING: This kw can use a lot
of memory, if processing many datatypes, or
long time periods. ***
NO_EDC_OFFSET: I/O, 0 or 1. If set, do not preform an EDC offset calculation. Will also avoid dot0 and_0 calculations, and not perform coordinate transforms
GAP_TRIGGER_VALUE: I/O, float, > 0. For on-the-fly EDC offset calculation, consider anything greater than or equal to GAP_TRIGGER_VALUE to be
a gap in the data. Default: 0.5 s.
NOMINAL_N_SPINS: I/O, long, >= 1. Specify the number of spins for the on-the-fly EDC offset calculation estimation window, or
read out the default (20 spins).
MIN_N_SPINS: I/O, long, 1 <= MIN_N_SPINS <= NOMINAL_N_SPINS. Specify the lower limit for NOMINAL_N_SPINS.
OFFSET_ESTIMATION_FUNC: OUTPUT, scalar string. The name of the function used to estimate the EDC offset for the on-the-fly window.
/EDGE_TRUNCATE: I/O, numeric, 0 or 1. Set to 0 to disable edge truncation in SMOOTH (for the on-the-fly offset calculation). Assign
to a variable to read the default (= 1). Undefined, if on-the-fly offset not done.
GAP_BEGIN, GAP_END: OUTPUT, double, >= 0. Return (if they exist), the double-precision start and end times of all
gaps detected in preparation for on-the-fly offset calculation. See kw ONTHEFLY_EDC_OFFSET for structure format and warnings.
keyword parameters for _dot0 computation:
MAX_ANGLE: Input, float. Maximum angle of B field to spin axis to calculate _dot0. Typical = 80 degrees. No default.
MIN_BZ: I/O, float. Minimum value of Bz. Typical value is 2.0 nT. Default= 1.0 nT. If argument not defined, returns default. Not
compatible with MAX_ANGLE keyword.
MAX_BXY_BZ: Input, float. Maximum value of abs(bx/bz) or abs(by/bz). Typical value is 5. ~= tan(79 degrees) (think of Bx/Bz). Default is
not to use this method (no default value).
BZ_OFFSET: I/O, float. Offset in nT that will be added to Z axis measurement of B. Defaults to 0.0. If argument not defined, returns default.
FGM_DATATYPE: Input, string. 'fgl', 'fgh', 'fgs' or 'fge'.
FGM_LEVEL: Input, 'l1' or 'l2', default is 'l1'
Example:
thm_cal_efi, probe='c'
Modifications:
Added boom_shorting_factor_e12, boom_shorting_factor_e34,
offset_e12, offset_e34, offset_dsc_x, offset_dsc_y
fields to data_att structure in the default limits structure.
Also, added mechanism to fill new field from
THM_GET_EFI_CAL_PARS.PRO, W.M.Feuerstein, 2/26-27/2008.
Changed "History" to "Modifications" in header, made "1000" a float ("."),
switched all internal calibration parameters over to those read through
THM_GET_EFI_CAL_PARS.PRO, WMF, 3/12/2008.
Updated DATA_ATT fields to match revised cal. files, WMF, 3/12/2008.
Updated error handling, updated doc'n, WMF, 3/12/2008.
Updated doc'n, made datatypes more consistent (speed), WMF, 3/14/2008.
Changed "no default" for MIN_BZ kw to default=1.0 nT, fixed MAX_ANGLE
and MIN_BZ kwd's "both set" handling, WMF, 3/14/2008.
Changed an NaN multiplication to an assignment (speed), simplified MIN_BZ
default assignment, turned on good practice compile options,
reorganized opening statements (flow), turned off ARG_PRESENT(MAX_BXY_BZ)
bug (no default for this kw), updated doc'n, WMF, 3/17/2008.
Now calculates Ez (_dot0 section) AFTER implementing MAX_BXY_BZ kw as per
J. Bonnell's request (it also happens to be faster), updated doc'n,
WMF, 3/18/2008.
Removed redundant datatype conversions, WMF, 3/20/2008.
Using BOOM_SHORTING_FACTOR in field calibration, WMF, 3/20/2008 (Th).
Fixed potential logical vs. bitwise conditional bug, WMF, 3/21/2008 (F).
Updated doc'n, WMF, 3/27/2008.
Removed "TWEAK_GAINS" kw to THM_EFI_DESPIN.PRO per J.Bonnell's req.,
WMF, 4/4/2008 (F).
Added TEST kw to disable certain /CONTINUE to MESSAGE, and passed TEST
through to THM_GET_EFI_CAL_PARS.PRO, WMF, 4/7/2008 (M).
Implemented time-dependent EAD/EDC gain conditional, WMF, 4/22/2008 (Tu).
Implemented time-dependent calibration parameters for v?? and
e?? datatypes, WMF, 5/21 - 6/5/2008.
Reconciled last three changes from non-time-dependent version: COORD kw is now not case
sensitive, made sure 'E12','E34','E56' labels go with SSL and SPG coordinates and
'Ex','Ey','Ez' go with all other coordinate systems (THM_UPDATE_EFI_LABELS.PRO),
fixed COORD='gse' crash, WMF, 8/21/2008.
Added error message for hed_ac = 255, WMF, 8/26/2008.
Renamed from "thm_cal_efi_td.pro" to "thm_cal_efi.pro", WMF, 9/9/2008.
Put in cases for 2 and 4 spin-dependent offsets in the boom plane, WMF, 3/4/2009.
Insert on NaN on FGM degap, memory management, WMF, 5/5/2009.
added no_edc_offset and _extra keywords, 19-aug-2010, jmm
Notes:
-- fixed, nominal calibration pars used (gains and
frequency responses), rather than proper time-dependent parameters.
$LastChangedBy: michf $
$LastChangedDate: 2008-04-22 17:50:30 -0700 (Tue, 22 Apr 2008) $
$LastChangedRevision: 2804 $
$URL $
(See themis/spacecraft/fields/thm_cal_efi.pro)
THM_UPDATE_EFI_LABELS.PRO PURPOSE: To be used on THEMIS EFI 3-vectors. Labels x-axis as "E12 (<coordinate system in DLIMITS.LABLES>)" for spinning coordinate systems and "Ex (<coord. sys. in DLIMITS.LABELS>)" for despun coordinate systmes. Y and Z axes are upadated correspondingly. Call after coordinate transformations. SYNTAX: thm_update_efi_labels ,<String> Arguments: <String>: A TPLOT variable name referring to a 3-vector TPLOT variable. Code: W. Michael Feuerstein, 7/2008.
(See themis/spacecraft/fields/thm_cal_efi_nonTD.pro)
Procedure: THM_CAL_EFI
Purpose: Converts raw EFI (V, EDC, and EAC waveform) data into
physical quantities.
keywords:
/VERBOSE or VERBOSE=n ; set to enable diagnostic message output.
higher values of n produce more and lower-level diagnostic
messages.
datatype - Default setting is to calibrate all raw quantites and also
produce all _0 and _dot0 quantities that are passed in
DATATYPE kw.
probe - Defaults to all probes.
valid_names - Return valid datatypes, print them, and return.
coord - Coordinate system of output.
TEST: Disables selected /CONTINUE to MESSAGE. For QA testing only.
keyword parameters for _dot0 computation:
max_angle - Maximum angle of B field to spin axis to calculate _dot0.
Typical = 80 degrees. No default.
min_bz - Minimum value of Bz. Typical value is 2.0 nT.
Default= 1.0 nT. Not compatible with max_angle keyword.
max_bxy_bz- Maximum value of abs(bx/bz) or abs(by/bz). Typical value is
5. ~= tan(79 degrees) (think of Bx/Bz).
Default is not to use this method (no default value).
bz_offset - Offset in nT that will be added to Z axis measurement of B.
Defaults to 0.0.
fgm_datatype - 'fgl', 'fgh', 'fgs' or 'fge'
Example:
thm_cal_efi, probe='c'
Modifications:
Added boom_shorting_factor_e12, boom_shorting_factor_e34,
offset_e12, offset_e34, offset_dsc_x, offset_dsc_y
fields to data_att structure in the default limits structure.
Also, added mechanism to fill new field from
THM_GET_EFI_CAL_PARS.PRO, W.M.Feuerstein, 2/26-27/2008.
Changed "History" to "Modifications" in header, made "1000" a float ("."),
switched all internal calibration parameters over to those read through
THM_GET_EFI_CAL_PARS.PRO, WMF, 3/12/2008.
Updated DATA_ATT fields to match revised cal. files, WMF, 3/12/2008.
Updated error handling, updated doc'n, WMF, 3/12/2008.
Updated doc'n, made datatypes more consistent (speed), WMF, 3/14/2008.
Changed "no default" for MIN_BZ kw to default=1.0 nT, fixed MAX_ANGLE
and MIN_BZ kwd's "both set" handling, WMF, 3/14/2008.
Changed an NaN multiplication to an assignment (speed), simplified MIN_BZ
default assignment, turned on good practice compile options,
reorganized opening statements (flow), turned off ARG_PRESENT(MAX_BXY_BZ)
bug (no default for this kw), updated doc'n, WMF, 3/17/2008.
Now calculates Ez (_dot0 section) AFTER implementing MAX_BXY_BZ kw as per
J. Bonnell's request (it also happens to be faster), updated doc'n,
WMF, 3/18/2008.
Removed redundant datatype conversions, WMF, 3/20/2008.
Using BOOM_SHORTING_FACTOR in field calibration, WMF, 3/20/2008 (Th).
Fixed potential logical vs. bitwise conditional bug, WMF, 3/21/2008 (F).
Updated doc'n, WMF, 3/27/2008.
Removed "TWEAK_GAINS" kw to THM_EFI_DESPIN.PRO per J.Bonnell's req.,
WMF, 4/4/2008 (F).
Added TEST kw to disable certain /CONTINUE to MESSAGE, and passed TEST
through to THM_GET_EFI_CAL_PARS.PRO, WMF, 4/7/2008 (M).
Implemented time-dependent EAC/EDC gain conditional, WMF, 4/22/2008 (Tu).
Made sure input to COORD kw is case-insensitive, WMF, 6/26/2008.
Made sure 'E12','E34','E56' labels go with SSL and SPG coordinates, and
'Ex','Ey','Ez' go with all other coordinate systems, WMF, 7/8/2008.
Fixed "COORD='gse'" crash, wrote THM_UPDATE_EFI_LABELS.PRO to handle labelling, WMF, 7/15/2008.
Renamed from "thm_cal_efi.pro" to "thm_cal_efi_nonTD.pro", WMF, 9/9/2008.
Notes:
-- fixed, nominal calibration pars used (gains and
frequency responses), rather than proper time-dependent parameters.
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-26 16:43:03 -0800 (Thu, 26 Jan 2012) $
$LastChangedRevision: 9624 $
$URL $
(See themis/spacecraft/fields/thm_cal_efi_nonTD.pro)
Procedure: THM_CAL_FBK
Purpose: Converts raw FBK (Filter Bank) data into physical quantities.
keywords:
probe = Probe name. The default is 'all', i.e., calibrate data for all
available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be loaded, 'fbh', 'fb1', 'fb2'. default is
'all', to calibrate all variables.
due to some last minute changes it is required that you include
both the raw and the calibrated datatype you want for this function
to perform properly
in_suffix = optional suffix to add to name of input data quantity, which
is generated from probe and datatype keywords.
out_suffix = optional suffix to add to name for output tplot quantity,
which is generated from probe and datatype keywords.
/VALID_NAMES; returns the allowable input names in the probe and
datatype variables
/VERBOSE or VERBOSE=n ; set to enable diagnostic message output.
higher values of n produce more and lower-level diagnostic messages.
Example:
thm_cal_fbk
Notes:
-- Changes between signal sources are handled;
source info from HED data should be used to get actual units of a given spectrum.
-- fixed, nominal calibration pars used (gains and frequency responses), rather than proper time-dependent parameters.
(See themis/spacecraft/fields/thm_cal_fbk.pro)
Procedure: THM_CAL_FFT
Purpose: Converts raw FFT (on-board FFT spectra) data into physical quantities.
keywords:
probe = Probe name. The default is 'all', i.e., calibrate data for all
available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be loaded, 'ffp_16', 'ffp_32',
'ffp_64', 'ffw_16', 'ffw_32', or 'ffw_64'. default is
'all', to calibrate all variables.
due to some last minute changes it is required that you include
both the raw and the calibrated datatype you want for this function
to perform properly
in_suffix = optional suffix to add to name of input data quantity, which
is generated from probe and datatype keywords.
out_suffix = optional suffix to add to name for output tplot quantity,
which is generated from probe and datatype keywords.
/VALID_NAMES; returns the allowable input names in the probe and
datatype variables
/VERBOSE or VERBOSE=n ; set to enable diagnostic message output.
higher values of n produce more and lower-level diagnostic messages.
Example:
thm_cal_fft
Notes:
-- Changes between signal sources are handled;
source info from HED data should be used to get actual units of a given spectrum.
-- fixed, nominal calibration pars used (gains and frequency
responses), rather than proper time-dependent parameters.
(See themis/spacecraft/fields/thm_cal_fft.pro)
procedure: thm_cal_fgm
Purpose: applies calibration to THEMIS fluxgate magnetometer data
searches for the current calibration in ASCII file
takes calibration that has time stamp before or at the start of the data
converts data to nano Tessla
applies the calibration
corrects for phase shift from averaging before despinning
keywords:
probe = Probe name. The default is 'all', i.e., calibrate data for all
available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be loaded, 'fge', 'fgh', or 'fgl'. default is
'all', to calibrate all variables.
in_suffix = optional suffix to add to name of input data quantity, which
is generated from probe and datatype keywords.
out_suffix = optional suffix to add to name for output tplot quantity,
which is generated from probe and datatype keywords.
coord = apply thm_cotrans if output other
than spinning spacecraft (SSL) is desired.
cal_dac_offset = apply calibrations that remove digital analog
converter nonlinearity by addition of offset.
Algorithm generated by Dragos Constantine
<d.constantinescu@tu-bs.de>. This is the default
process as of 7-Jan-2010, to disable, explicitly
set this keyword to 0.
cal_spin_harmonics = apply calibrations from a file that remove
spin harmonics by applying spin-dependent
offsets generated by David Fischer
<david.fischer@oeaw.ac.at>. This is the default
process as of 7-Jan-2010, to disable, explicitly
set this keyword to 0.
cal_tone_removal = fitting algorithm removes orbit dependent
spintone without removing scientifically salient
features. Algorithm generated by Ferdinand Plaschke
<f.plaschke@tu-bs.de>. This is the default
process as of 7-Jan-2010, to disable, explicitly
set this keyword to 0.
cal_get_fulloffset = returns the offset used for spintone removal.(this keyword used for valididation)
Because there may be a different offset for each combination of probe and datatype,
This is returned as a struct of structs, with each element in the child structs being an N by 3 array.
For example, if offset_struct is the name of a struct with the return value from the cal_get_fulloffset keyword,
print,offset_struct.tha.fgl
Will print the fulloffset for probe a and datatype fgl.
cal_get_dac_dat = Returns the raw data from directly after the DAC(non-linearity offset) calibration is applied. For verification.
cal_get_spin_dat = Returns the raw data from directly after the spin harmonic(solar array current) calibration is applied. For verification.
optional parameters:
name_thx_fgx_in --> input data (t-plot variable name)
name_thx_fgx_hed --> header information for input data (t-plot variable name)
name_thx_fgx_out --> name for output (t-plot variable name)
pathfile --> path and filename of the calibration file
keywords:
Example:
tha_cal_fgm, probe = 'a', datatype= 'fgl'
Notes: under construction!!
Written by Hannes Schwarzl.
$LastChangedBy: aaflores $
$LastChangedDate: 2012-02-22 11:30:33 -0800 (Wed, 22 Feb 2012) $
$LastChangedRevision: 9811 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_cal_fgm.pro $
Changes by Edita Georgescu
eg 6/3/2007 - matrix multiplication
eg 30/3/2007 - keyword deleted, fgmtype determined from: name_thx_fgx_in
- calibrates fgl,fgh,fge
- calibrate only mode=0 data
2007-03-30 Modified by Hannnes S to use multiple calibrations for a selected interval
and use spinperiod from the statefile
Search this string to see changes ;Hannes 30/3/2007
2007-03-30 Modified by Hannnes S correction for filter delay removed
Search this string to see changes: Hannes 05/21/2007
(See themis/spacecraft/fields/thm_cal_fgm.pro)
procedure: thm_cal_fgm_dac_ffset Purpose: Uses routine provided by Dragos Constanine to correct FGM offset from non-linearity of DAC(Digital Analog Converter) Specific routine from Dragos: thm_fgm_find_shift_1p1c.pro Calibration values from Dragos: thm_fgm_dac_corrections.dat Inputs: fgmdata: An Nx3 length array of fgm data in digital units. fgmdata[*,0] = x,fgmdata[*,1] = y,fgmdata[*,2] = z probe: The probe letter, as a string. datatype: fgm data type can be (fgl,fge,fgh) Outputs: Mutates fgmdata in place. error: Set to 1 if error occurs, 0 otherwise Notes: This routine based largely upon routine fgm_correct_shift by Dragos Constantinescu $LastChangedBy: aaflores $ $LastChangedDate: 2012-02-22 11:30:33 -0800 (Wed, 22 Feb 2012) $ $LastChangedRevision: 9811 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_cal_fgm_dac_offset.pro $
(See themis/spacecraft/fields/thm_cal_fgm_dac_offset.pro)
Procedure: thm_cal_fgm_spintone_removal
Purpose:
Tool to remove spintone from spinplane component FGM high resolution data
by dynamical adaption and subtraction of bias field offsets
Inputs:
Time: vector of time values
Data_in: corresponding spinplane component data, SSL x or y component
Datatype: string 'fgl', 'fge' or 'fgh'
Outputs:
data_out: corrected data vector
offset: removed offset data vector
fulloffset: vector of all offset determinations (for validation)
Author: Ferdinand Plaschke (2009-10-15)
Replace AMOEBA with DFPMIN, Ferdinand Plaschke (2008-10-16)
Minor modifications by Patrick Cruce(2009-10-15) for TDAS
1. Rename with thm prefix
2. Standardize documentation.
3. Replace print with dprint.
$LastChangedBy: aaflores $
$LastChangedDate: 2012-02-22 11:30:33 -0800 (Wed, 22 Feb 2012) $
$LastChangedRevision: 9811 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_cal_fgm_spintone_removal.pro $
(See themis/spacecraft/fields/thm_cal_fgm_spintone_removal.pro)
procedure: thm_cal_fgm_spin_harmonics
Purpose:
Uses spin harmonic corrections from calibration files to fix spin harmonic errors in fgm data.
The correction values are subtracted from the fgm data. These values are downloaded from files
in the data/themis/th?/l1/fgm/0000/spin_cal/ directory.
Inputs:
times: An N-length array of times matching the spinphase data and the fgmdata, in double precision seconds since 1970.
spinphase: An N-length array of spinphase data in degrees.
fgmdata: An Nx3 length array of fgm data in nT. fgmdata[*,0] = x,fgmdata[*,1] = y,fgmdata[*,2] = z
probe: The probe letter, as a string.
shadows:A struct with shadow start and stop times retrieved from the new spinmodel.
{start:shadow_starts,stop:shadow_stops}
Outputs:
Mutates fgmdata in place.
error: Set to 1 if error occurs, 0 otherwise
Notes:
1. Specifically, this corrects errors due to the solar array current. Thus it is only applied when the spacecraft is
not in shadow.
2. The correction should largely remove the 1 Hz and .66 Hz harmonics from the X & Y components of the data and
it should remove the .66 Hz and .33 Hz harmonics from the Z component of the data.(in DSL coordinates)
3. The .33 Hz harmonic of the X & Y components should remain. There should be no 1 Hz Harmonic in the Z-component
4. If a calibration file is not found it will use a default calibration file. This file will be the calibration file
for the probe that corresponds to the latest month. This could be an issue for dates very early in the mission,
as there are no calibration files for these dates, but they are not temporally close to the default calibration values.
$LastChangedBy: aaflores $
$LastChangedDate: 2012-02-22 11:30:33 -0800 (Wed, 22 Feb 2012) $
$LastChangedRevision: 9811 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_cal_fgm_spin_harmonics.pro $
(See themis/spacecraft/fields/thm_cal_fgm_spin_harmonics.pro)
Procedure: THM_CAL_FIT
Purpose: Converts raw FIT parameter data into physical quantities.
keywords:
/VERBOSE or VERBOSE=n ; set to enable diagnostic message output.
higher values of n produce more and lower-level diagnostic messages.
/ALL
/no_cal will not apply boom shortening factor or Ex offset defaults
Example:
thm_cal_fit, /all
Modifications:
Corrected (reversed) polarity of Zscale in CPAR, WMFeuerstein, 5/13/2008.
Call THM_GET_EFI_CAL_PARS.PRO and calibrate 'efs' data with EFI parameters, WMF, 5/13/2008.
Mods per McFadden and Vassilis: Do not subtract spin-independent offset for 'efs'
data, NO_CAL kw effectively sets boom_shorting_factor to 1 and spin-dependent offsets
to 0, WMF, 6/27/2008.
Notes:
-- FGM range changes are not handled properly; RANGE=0 is assumed.
-- fixed, nominal calibration pars used, rather than proper time-dependent parameters.
-- time-dependent spinn axis offset implemented Hannes 05/25/2007
-- fixed trouble reading cal files with extra lines at the end,
jmm, 8-nov-2007
$LastChangedBy: jimm $
$LastChangedDate: 2012-02-15 13:19:53 -0800 (Wed, 15 Feb 2012) $
$LastChangedRevision: 9754 $
$URL $
(See themis/spacecraft/fields/thm_cal_fit.pro)
NAME:
thm_cal_scm
PURPOSE:
calibrate THEMIS SCM data
The processing is done in 6 successive steps (Step 1 is the first)
----------- by default, processing stops after step 5.
# 0: counts, NaN inserted into each gap for proper tplotting
# 1: Volts, spinning sensor system, with DC field
# 2: Volts, spinning sensor system, without DC field[, xy DC field in nT]
# 3: nTesla, spinning sensor system, without DC field
# 4: nTesla, spinning SSL system, without DC field
# 5: nTesla, fixed DSL system, without DC field, filtered <fmin
# 6: nTesla, fixed DSL system, with xy DC field
keywords:
probe = Probe name. The default is 'all', i.e., calibrate data for all
available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be calibrated/created.
The default is 'scf', 'scp', and 'scw', that is, SCM full mode,
particle burst mode and waves burst mode data, with no diagnostic
outputs.
Each mode of output has its own set of possible diagnostic outputs:
'sc?_dc', 'sc?_misalign' and 'sc?_iano', where ? can be
f, p or w. To calibrate all modes loaded and create all diagnostic
outputs you can specify 'all'.
diagnostic outputs: raw data in Volts, dc field, axis misalignment
(angle between x and y axes in degrees),
and iano (data quality flag). Created with '_dc',
'_misalign', and '_iano' suffixes, respectively.
in_suffix = optional suffix to add to name of input data quantity, which
is generated from probe and datatype keywords.
out_suffix = optional suffix to add to name for output tplot quantity,
which is generated from probe and datatype keywords.
trange= array[2] string or double. Limit calibration to specified time range
nk = N points of the cal-convolution kernel, if set, this value will
be used regardless of sample rate.
mk = If nk is not set, set nk to (sample frequency)*mk, where sample
frequency is determined by the data. default 8 for scf, 4 for scp,
and 1 for scw.
despin =classic despin algorithm. 0:off 1:on Default is on.
n_spinfit=n spins to fit for misalignment, dc field calculation and
optionally despin.
cleanup= type of cleanup (default is 'none'):
'spin' for only spin tones (power ripples) cleanup,
'full' for spin tones and 8/32 Hz tones
'none' for no cleanup processes.
wind_dur_1s = window duration for 8/32 Hz cleanup (has to be a multiple of 1s)
default is 1.
wind_dur_spin = spintone cleanup window duration as a multiple of the spin
period. Default is 1.
clnup_author = choice of cleanup routine (default is 'ole'):
'ccc' to use scm_cleanup_ccc
'ole' to use spin_tones_cleaning_vector_v5
fdet = detrend freq. in Hz. Detrend is implemented by subtracting a boxcar
avg., whose length is determined by fdet.
Use fdet=0 for no detrending. Default is fdet=0.
fcut = Low Frequency cut-off for calibration. Default is 0.1 Hz.
fmin = Min frequency for filtering in DSL system. Default is 0 Hz.
fmax = Max frequency for filtering in DSL system. Default is Nyquist.
step = Highest Processing step to complete. Default is step 5.
dfb_butter = correct for DFB Butterworth filter response (defaut is true)
dfb_dig = correct for DFB Digital fiter response (default is true)
gainant = correct for antenna gain (default is true)
blk_con = use fast convolution for calibration and filtering.
Block size for fast convolution will be equal to
(value of blk_con) * (size of kernel). blk_con = 8 by default.
set blk_con=0 to use brute-force convolution.
edge_truncate, edge_wrap, edge_zero= Method for handling edges in
step 3, cal-deconvolution. For usage and exact specification of
these keywords, see docs for IDL convol function. Default is to
zero data within nk/2 samples of data gap or edge.
coord = coordinate system of output. Step 6 output can only be in DSL.
no_download=don't access internet to check for updated calibration files.
dircal= If set to a string, specifies directory of calibration files.
use /dircal or dircal='' to use calibration files in IDL source
distribution.
verbose=set to zero to eliminate output. currently only works with
valid_names
valid_names=use /valid_names to print out values for probe, datatype, coord
and return those in named variables passed in to corresponding
keywords.
optional parameters:
thx_scx --> input data (t-plot variable name)
thx_scx_hed --> header information for input data (t-plot variable name)
Example:
tha_cal_fgm, probe = 'a', datatype= 'scp'
HISTORY:
13-mar-2007, jmm, jimm@ssl.berkeley.edu
June-2007, krb, Based on Patrick Robert's cowave_THEscmwf.f
25-sept-2007, krb, kenneth.r.bromund@nasa.gov
merged in changes to version 893, made on 16-jul-2007 by
olivier.LeContel@cetp.ipsl.fr, including Olivier Le Contel cleanup routine
(spin_tones_cleaning_vector_v5) in thm_cal_scm
23-jul-2008, jmm, added _extra to allow keyword inheritance
jan-2010, ole@lpp.polytechnique.fr
Modification to add Nan value only for last batch
in step 6, start_step condition has been commented
in outputs to tplot section, mode has been replaced by strlowcase(mode)
$LastChangedBy: jimm $
$LastChangedDate: 2012-02-21 12:13:01 -0800 (Tue, 21 Feb 2012) $
$LastChangedRevision: 9797 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_cal_scm.pro $
(See themis/spacecraft/fields/thm_cal_scm.pro)
Purpose: Takes a bunch of intervals from different data sources and
collates all intervals of the same source into a single vector(may be multidimensional)
keywords:
r: an array of data with dimensions [time,samples,sources]
s: an array of source s[i] indices should have the source index of [*,*,i]
returns: an array with dimensions [time,samples,sources] but
all sources will be unique(ie the size of the output sources
will be <= the input sources)
Notes: --Used by thm_cal_fft,thm_cal_fbk
--The returned data will be sorted according to source index in
ascending order
(See themis/spacecraft/fields/thm_collate_intervals.pro)
Procedure: thm_comp_eac_response Purpose: Compute the voltage gain (magnitude only) as a function of frequency for the DFB EAC channels. Calling Sequence: thm_comp_eac_response, sensor, ff, resp Arguements: sensor STRING, ignored. ff FLOAT[ N], array of frequencies at which to compute the channel response. resp float[ N], array of |voltage gain| vs. frequency. Notes: -- none. $LastChangedBy: jbonnell $ $LastChangedDate: 2007-06-28 18:00:35 -0700 (Thu, 28 Jun 2007) $ $LastChangedRevision: 939 $ $URL $
(See themis/spacecraft/fields/thm_comp_eac_response.pro)
Procedure: thm_comp_efi_response Purpose: Compute the voltage gain (magnitude only) as a function of frequency for a given THEMIS EFI sensor (SPB or AXB). Calling Sequence: thm_comp_efi_response, sensor, ff, resp Arguements: sensor STRING, one of SPB or AXB. ff FLOAT[ N], array of frequencies at which to compute the sensor response. resp COMPLEX[ N], array of voltage gain vs. frequency. Notes: -- none. $LastChangedBy: aaflores $ $LastChangedDate: 2012-01-26 16:43:03 -0800 (Thu, 26 Jan 2012) $ $LastChangedRevision: 9624 $ $URL $
(See themis/spacecraft/fields/thm_comp_efi_response.pro)
Procedure: thm_comp_scm_response Purpose: Compute the voltage gain (magnitude only) as a function of frequency for a given THEMIS SCM sensor. Calling Sequence: thm_comp_scm_response, sensor, ff, resp Arguements: sensor STRING, ignored. ff FLOAT[ N], array of frequencies at which to compute the sensor response. resp float[ N], array of |voltage gain| vs. frequency. Notes: -- none. $LastChangedBy: jbonnell $ $LastChangedDate: 2007-06-28 18:00:35 -0700 (Thu, 28 Jun 2007) $ $LastChangedRevision: 939 $ $URL $
(See themis/spacecraft/fields/thm_comp_scm_response.pro)
function thm_dfb_filter(f, fsamp)
purpose: Calculates the transfer function for the DFB digital
filters at a given sample rate.
Inputs: f frequency in Hz
fsamp Sampling frequency of telemetry signal.
level of DFB filtering will be calculated
based on the raw sampling rate of the DC coupled SCM and EFI
inputs (8192 S/s )
Output: transfer function at given frequencies -- abs taken, since
phase is adjusted for in L0->L1 processing.
Author: Ken Bromund, as a wrapper around routines written by Chris Cully.
$LastChangedBy: jwl $
$LastChangedDate: 2012-03-05 11:12:17 -0800 (Mon, 05 Mar 2012) $
$LastChangedRevision: 9934 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_dfb_dig_filter_resp.pro $
(See themis/spacecraft/fields/thm_dfb_dig_filter_resp.pro)
NAME:
thm_efi_boom_deployment_time
PURPOSE:
Provides the boom_deployment time(s) for EFI on THEMIS
probes. Before this time, EFI and all ESA, SST, MOM, moments are
problematic.
CALLING SEQUENCE:
boom_time = thm_efi_boom_deployment_time(probe = probe)
INPUT:
All via keyword
KEYWORDS:
probe = 'a', 'b', 'c', 'd', 'e', the probes for which you want the
time
OUTPUT:
boom_time = the time of EFI boom_deployment for input probes:
Dates for each Probe when boom deploy was completed:
Probe Boom Deploy Complete
THA (P5) 14 Jan 2008, 1700 UT.
THB (P1) 17 Nov 2007, 0600 UT.
THC (P2) 16 May 2007, 2100 UT.
THD (P3) 7 Jun 2007, 1700 UT.
THE (P4) 7 Jun 2007, 1900 UT.
Notes:
(See themis/spacecraft/fields/thm_efi_boom_deployment_time.pro)
Despin routine for EFI high-res (eff/efp/efw) data.
Syntax:
thm_efi_despin , probe, datatype, offset, gain [, NOTCH ] [, TWEAK_GAINS ] [, STORED_TNAMES ]
Inputs:
PROBE: Input, 1-character string identifying which spacecraft.
DATATYPE: Input, string. 3-character string identifying data type ('eff','efp' or 'efw')
OFFSET: Input, float, 1 x n (2 dimensions) 3-element array: Ex, Ey, Ez offset.
GAIN: Input, float. 3-element array: E12, E34, E56 gain.
TPLOT_NAME: Input. String scalar containing the name of the TPLOT variable to operate on (regardless of PROBE and DATATYPE kwd's).
Options:
NOTCH: Numeric, 0 or 1. Set equal to the # of harmonics to remove (including fundamental) (i.e. notch=1 removes fundamental only, notch=2 also
removes 1st harmonic) (default=0 does not notch filter anything). *** DISABLED ***.
TWEAK_GAINS: Numeric, 0 or 1. Set flag to tweak the E12/E34 gains to minimize the spin tone newname: If specified, the cleaned data is stored as a
tplot variable with name=newname instead of the default 'th'+sc+'_'+datatype+'_dsl'.
Outputs:
*** Creates a new tplot variable with the name 'th'+sc+'_'+datatype+'_dsl' or whatever is specified by the newname keyword. ***
STORED_TNAMES: Returns a string array containing each TPLOT variable name invoked in a STORE_DATA operation (chronological order). (Not sorted or uniqued.)
Restrictions:
Required data must be loaded, including spin phase data.
Notes:
This routine ignores E56 when despinning. That is desireable over
the full transform (a la THM_COTRANS.PRO) because the resolution on E56
is much lower than for the spin plane sensors (E12 and E34) so mixing
in E56 would often increase the noise, and because the geometric
axis is w/in 1 degree of the spin axis making the result effectively
in DSL.
Modifications:
Switched from THM_SPIN_PHASE.PRO to Jim Lewis' SPINMODEL_INTERP_T.PRO,
(commented out GET_DATA's to _state_spinper/spinphase, modified error
conditional), edited warning message, up'd doc'n, W.M.Feuerstein,
3/19/08.
Added TPLOT_NAME to specify var. to read. Otherwise, PROBE and DATATYPE
parameters are used to derive tplot var. name to read. Changed default
suffix to "_dsz" to match the "THEMIS Science Coordinate Systems
Definition" (THM-SOC-110).
Made sure "V" field is carried through data (otherwise it crashes
THM_CAL_EFI.PRO), redined suffix to "_dsl" (effectively true), fixed
potential bitwise vs. logical conditional bug, updated doc'n, WMF,
3/21/2008 (F).
Put in return on errors w/ messages for DLIMITS.DATA_ATT.COORD_SYS equal
to 'dsl' or 'spg', set said field to 'dsl' on conclusion of
processing, updat'd doc'n, WMF, 3/24/2008.
Checks validity of pointer from SPINMODEL_GET_PTR.PRO and calls
THM_LOAD_SPIN,PROBE=PROBE[0] on fail, installed an alternate test for
spinmodel data (TNAMES('th?_spin*')) to check an error from
SPINMODEL_INTERP_T.PRO but the error is unrelated, WMF, 3/26/2008.
Removed check on pointer in favor of incorporating THM_LOAD_SPIN.PRO into
THM_LOAD_STATE.PRO, WMF, 3/27/2008.
Updated doc'n, WMF, 3/27/2008.
Changed "Despinning <variable>" PRINT to MESSAGE, if data already despun
save TPLOT var. instead of just returning (BugzID 111), WMF, 4/4/08 (F).
Disabled BOOM_OFFSET parameter which is obsolete, WMF, 4/22/2008 (Tu).
Upd'd doc'n, WMF, 5/21/2008.
Change (spin-dependent) offset parameter to optional kw OFFSET. Subtract OFFSET only if provided and only if there are 2 spin-dependent
offsets in boom plane, WMF, 3/2/2009.
Return OFFSET to a parameter: Subtract X, Y, Z for 2 spin-dependent offsets in boom plane; subtract Z only for 4 spin-dependent offsets, WMF, 3/5/09.
$LastChangedBy: michf $
$LastChangedDate: 2008-05-15 11:17:41 -0700 (Thu, 15 May 2008) $
$LastChangedRevision: 3095 $
$URL: $
(See themis/spacecraft/fields/thm_efi_despin.pro)
Function: THM_FBK_DECOMPRESS Purpose: Decompresses DFB FBK spectral data. Arguements: DATA, any BYTE data type (scalar or array), 8-bit compressed FBK band-pass amplitude estimates. keywords: VERBOSE. Example: result = thm_fbk_compress( data) Notes: -- none. $LastChangedBy: jimm $ $LastChangedDate: 2007-11-16 12:28:13 -0800 (Fri, 16 Nov 2007) $ $LastChangedRevision: 2043 $ $URL $
(See themis/spacecraft/fields/thm_fbk_decompress.pro)
Function: THM_FFT_DECOMPRESS Purpose: Decompresses DFB FFT spectral data. Arguements: DATA, any BYTE data type (scalar or array), 8-bit compressed FFT spectral estimates. keywords: VERBOSE. Example: result = thm_fft_compress( data) Notes: -- Stub version, to allow for testing. $LastChangedBy: jimm $ $LastChangedDate: 2007-11-16 12:28:13 -0800 (Fri, 16 Nov 2007) $ $LastChangedRevision: 2043 $ $URL $
(See themis/spacecraft/fields/thm_fft_decompress.pro)
thm_fft_freq_bins
(See themis/spacecraft/fields/thm_fft_freq_bins.pro)
Procedure: thm_fft_freq_bins Purpose: Given the sampling rate and number of bins, return the center frequencies of the FFT spectral estimate bins. Calling Sequence: thm_fft_freq_bins, rate=rate, nbins=nbins, cent_freq=cent_freq Arguements: rate STRING, '8k' or '16k', indicating that the source sampling rate is 8192 or 16384 samp/s. nbins INT, 16, 32, or 64; number of frequency bins in the FFT spectral estimate. Outputs: cent_freq FLOAT[ nbins], center frequencies of bins in Hz. Notes: -- none. $LastChangedBy: aaflores $ $LastChangedDate: 2012-01-26 16:43:03 -0800 (Thu, 26 Jan 2012) $ $LastChangedRevision: 9624 $ $URL $
(See themis/spacecraft/fields/thm_fft_freq_bins.pro)
Function: thm_fgm_find_shift_1p1c
Description: Returns the vector to be added to l1 data to correct
the '390 nT' jumps for one probe and one component.
Input:
b = the uncorrected measurements
threshold = threshold matrix (probe x component). A jump occurs when the field
crosses this value. Note that the actual threshold depends on the
field derivative. The value given here is for constant field (th0).
th_slope = slope of the threshold: threshold=th0+th_slope*(db/dt)
jump = jump matrix (probe x component). The expected values of the jumps.
datatype= 'fgl' or -> low resolution (4Hz)
'fgh' or -> high resolution (128 Hz)
'fge' -> engeneering data (8 Hz)
Keywords:
/fixed: take the correction from the jump matrix. Default for fgh
is to compute the correction for each jump such way that
the first derivative is constant across the jump from low
to high values. It has no effect for fge or fgl data for
which the correction is taken by default from the jump
matrix.
/constant: average the correction over all jumps for fgh. It has no
effect for fge or fgl.
Return value: the correction vector
Example:
corr = thm_fgm_find_shift_1p1c(b, th_up, th_dn, jump, /constant, datatype='fgh')
Notes
- this function is used by fgm_find_shift
Written by Dragos Constantinescu
Minor modifications by Patrick Cruce for incorporation into TDAS.
Specifically:
1. Changed Function Name
2. Disabled output of statistics to file.
$LastChangedBy: aaflores $
$LastChangedDate: 2012-02-22 11:30:33 -0800 (Wed, 22 Feb 2012) $
$LastChangedRevision: 9811 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_fgm_find_shift_1p1c.pro $
(See themis/spacecraft/fields/thm_fgm_find_shift_1p1c.pro)
Procedure:
thm_get_efi_cal_pars
Purpose:
Given the particular EFI waveform data type, and begin and end of the time interval, return the waveform RAW->PHYS
transformation parameters.
Calling Sequence:
thm_get_efi_cal_pars, times, name, probes, cal_pars=cal_pars
Arguements:
TIMES: Input, DOUBLE, time basis of data since THEMIS epoch.
NAME: Input, STRING, waveform data type indicator.
PROBES: Input, SCALAR STRING, name of THEMIS probe (i.e., only one probe -- 'a','b',...).
Keywords:
CAL_PARS: Output, STRUCT, see Notes below for elements.
/TEST: Input, numeric, 0 or 1. Disables selected /CONTINUE to MESSAGE. For QA testing.
Modifications:
Added FILE_RETRIEVE() mechanism so that this routine can read the
template and calibration files from the THEMIS local data directory.
Also, added the "probes" parameter for the above purpose,
W.M.Feuerstein, 2/27/2008.
Changed "History" to "Modifications" in header, commented out all local
calibration parameters, redifined ASCII template, now retrieving all
calibration parameters from calibration files (these were expanded last
Friday). Updated doc'n, WMF, 3/17/08.
Implemented EAC/EDC gain conditional based on 1st element of TH?_EF?_HED_AC
tplot variable, updated doc'n, WMF, 3/18/08.
Inserted modern compile options, made ADC offsets integers in calibration
files, updated read templates, WMF, 3/20/08.
Fixed potential logical vs. bitwise conditional bug, updated calibration
fields, WMF, 3/21/2008.
Preparing for time-dependent calibration params. and AC/DC coupling gain
conditional -- code still commented, WMF, 4/4/2008 (F).
Replaced PRINT w/ MESSAGE for EAC/DC gain conditional warning. Added TEST kw
(default = 0) to disable CONTINUE kw to selected MESSAGE commands. If a
non-EFI datatype is passed then routine will stop, WMF, 4/7/2008 (M).
Fixed typo "Defaulting to EAC gain"=>"...EDC...", rephrased, WMF,
4/9/2008 (W).
Reformatted, WMF, 4/10/2008 (Th).
Corrected an error to assigning the field gain to the output structure --
would only affect AC coupled data, WMF, 4/11/2008.
Implemented time-dependent EAC/EDC gain conditional, WMF, 4/22/2008 (Tu).
Removed "[0]" in some of the CP structure fields (moving to T-D calibration
parameters), clipping CAL_PAR_TIME to TIMES, WMF, 4/23/2008 (W).
Added 'efs' datatype to switch statement, WMF, 5/12/2008 (M).
Stripped out time-dependent EAC/EDC gain conditional handling and moved to
THM_CAL_EFI.PRO. Also, now passing EAC_GAIN and EDC_GAIN instead of
just GAIN for the e?? datatype, WMF, 5/21 - 6/5/2008.
Fixed crash on reading calibration files with only one line of data, WMF, 8/6/2008.
Renamed from "thm_get_efi_cal_pars_td.pro" to "thm_get_efi_cal_pars.pro", WMF, 9/9/2008.
Notes:
-- use of TBEG and TEND for time-dependent calibration parameters is not currently implemented!
-- Difference in gain between DC and AC coupled E-field data implemented, but not calibrated yet (as of 6/18/2009)!
-- Elements of CAL_PARS are picked and chosen from the pertinent calibration file depending on NAME. See switch statement in code.
$LastChangedBy: michf $
$LastChangedDate: 2008-05-15 11:17:41 -0700 (Thu, 15 May 2008) $
$LastChangedRevision: 3095 $
$URL $
(See themis/spacecraft/fields/thm_get_efi_cal_pars.pro)
Procedure:
thm_get_efi_cal_pars
Purpose:
Given the particular EFI waveform data type, and begin and end
of the time interval, return the waveform RAW->PHYS
transformation parameters.
Calling Sequence:
thm_get_efi_cal_pars, tbeg, tend, name, probes, cal_pars=cal_pars
Arguements:
tbeg, tend DOUBLE, time in seconds since THEMIS epoch.
name STRING, waveform data type indicator.
cal_pars STRUCT, see Notes below for elements.
Keywords:
TEST:
Disables selected /CONTINUE to MESSAGE. For QA testing only.
Modifications:
Added FILE_RETRIEVE() mechanism so that this routine can read the
template and calibration files from the THEMIS local data directory.
Also, added the "probes" parameter for the above purpose,
W.M.Feuerstein, 2/27/2008.
Changed "History" to "Modifications" in header, commented out all local
calibration parameters, redifined ASCII template, now retrieving all
calibration parameters from calibration files (these were expanded last
Friday). Updated doc'n, WMF, 3/17/08.
Implemented EAC/EDC gain conditional based on 1st element of TH?_EF?_HED_AC
tplot variable, updated doc'n, WMF, 3/18/08.
Inserted modern compile options, made ADC offsets integers in calibration
files, updated read templates, WMF, 3/20/08.
Fixed potential logical vs. bitwise conditional bug, updated calibration
fields, WMF, 3/21/2008.
Preparing for time-dependent calibration params. and AC/DC coupling gain
conditional -- code still commented, WMF, 4/4/2008 (F).
Replaced PRINT w/ MESSAGE for EAC/DC gain conditional warning. Added TEST kw
(default = 0) to disable CONTINUE kw to selected MESSAGE commands. If a
non-EFI datatype is passed then routine will stop, WMF, 4/7/2008 (M).
Fixed typo "Defaulting to EAC gain"=>"...EDC...", rephrased, WMF,
4/9/2008 (W).
Reformatted, WMF, 4/10/2008 (Th).
Corrected an error to assigning the field gain to the output structure --
would only affect AC coupled data, WMF, 4/11/2008.
Implemented time-dependent EAC/EDC gain conditional, WMF, 4/22/2008 (Tu).
Removed "[0]" in some of the CP structure fields (moving to T-D calibration
parameters), clipping CAL_PAR_TIME to TIMES, WMF, 4/23/2008 (W).
Added 'efs' datatype to switch statement, WMF, 5/12/2008 (M).
Renamed from "thm_get_efi_cal_pars.pro" to "thm_get_efi_cal_pars_nonTD.pro", WMF, 9/9/2008.
Notes:
-- use of TBEG and TEND for time-dependent calibration parameters is
not currently implemented!
-- E-field gains and units are for voltages, not fields, since we have
not deployed yet!
-- Difference in gain between DC and AC coupled E-field data not
implemented yet!
-- Elements of cal_pars are as follows:
gain, FLOAT[ 3 or 6], gain of source channel at DC in (phys
unit)/ADC.
offset, FLOAT[ 3 or 6], offset of channel in ADC.
$LastChangedBy: jimm $
$LastChangedDate: 2011-11-21 13:42:48 -0800 (Mon, 21 Nov 2011) $
$LastChangedRevision: 9324 $
$URL $
(See themis/spacecraft/fields/thm_get_efi_cal_pars_nonTD.pro)
Procedure: thm_get_fbk_cal_pars Purpose: Given the signal source, and begin and end of the time interval, return the filter bank RAW->PHYS transformation parameters. Calling Sequence: thm_get_fbk_cal_pars, tbeg, tend, fb_sel, cal_pars=cal_pars Arguements: tbeg, tend DOUBLE, time in seconds since THEMIS epoch. fb_sel INT, FilterBank source selection indicator. cal_pars STRUCT, see Notes below for elements. Notes: -- use of TBEG and TEND for time-dependent calibration parameters is not currently implemented! -- E-field gains and units are for voltages, not fields, since we have not deployed yet! -- Elements of cal_pars are as follows: gain, FLOAT, gain of source channel at 0 dB response in (phys unit)/ADC. freq_resp FLOAT[ 6], effective attenuation factor for source channel for each of the six FilterBank channels. $LastChangedBy: jimm $ $LastChangedDate: 2007-11-16 12:28:13 -0800 (Fri, 16 Nov 2007) $ $LastChangedRevision: 2043 $ $URL $
(See themis/spacecraft/fields/thm_get_fbk_cal_pars.pro)
Procedure: thm_get_fft_cal_pars Purpose: Given the signal source, and begin and end of the time interval, return the FFT RAW->PHYS transformation parameters. Calling Sequence: thm_get_fft_cal_pars, tbeg, tend, fft_sel, nbins, cal_pars=cal_pars Arguements: tbeg, tend DOUBLE, time in seconds since THEMIS epoch. fft_sel INT, FilterBank source selection indicator. nbins, INT, number of frequency bins in spectrum (16, 32, 64). cal_pars STRUCT, see Notes below for elements. Notes: -- use of TBEG and TEND for time-dependent calibration parameters is not currently implemented! -- E-field gains and units are for actual deployed boom lengths (CDE). -- Elements of cal_pars are as follows: $LastChangedBy: jimm $ $LastChangedDate: 2007-11-16 12:28:13 -0800 (Fri, 16 Nov 2007) $ $LastChangedRevision: 2043 $ $URL $
(See themis/spacecraft/fields/thm_get_fft_cal_pars.pro)
Procedure: THM_LOAD_EFI
Purpose: Loads THEMIS EFI data
Syntax: THM_LOAD_EFI [, <optional keywords below> ]
keywords:
PROBE: Input, string. Specify space-separated probe letters, or string array (e.g., 'a c', ['a', 'c']). Defaults to all probes.
DATATYPE: Input, string. Default setting is to calibrate all raw quantites and also produce all _0 and _dot0 quantities. Use DATATYPE
kw to narrow the data products. Wildcards and glob-style patterns accepted (e.g., ef?, *_dot0).
SUFFIX: Input, scalar or array string. Set (scalar) to append SUFFIX to all output TPLOT variable names. Set (array with same # elements
as COORD) to put suffixes for corresponding COORD elements (one TPLOT variable with suffix for each element of COORD). When COORD has
> 1 element, SUFFIX must have the same # of elements (or be unset).
TRANGE: Input, double (2 element array). Time range of interest. If this is not set, the default is to prompt the user. Note that if the
input time range is not a full day, a full day's data is loaded.
LEVEL: I/O, string. The level of the data, the default is 'l1', or level-1 data. A string (e.g., 'l2') or an integer can be used. Only
one level can be specifed at a time. Set /VALID_NAMES to return the valid level names.
CDF_DATA: Output, string. Named variable in which to return cdf data structure: only works for a single spacecraft and datafile name.
VARNAMES: *** CDF_DATA must be present *** Output, string. Returns CDF variable names that were loaded.
/GET_SUPPORT_DATA: Input, numeric, 0 or 1. Set to load support_data variables as well as data variables into tplot variables.
/DOWNLOADONLY: Input, numeric, 0 or 1. Set to download file but not read it.
/VALID_NAMES: Input, numeric, 0 or 1. If set, then this routine will return the valid probe, datatype and/or level options in named variables
supplied as arguments to the corresponding keywords.
FILES: Output, string. Named varible for output of pathnames of local files.
/VERBOSE: Input, numeric, 0 or 1. Set to output some useful info.
/NO_DOWNLOAD: Input, numeric, 0 or 1. Set to use only files which are online locally.
RELPATHNAMES_ALL: Output, string. Named variable in which to return all files that are required for specified timespan, probe, datatype, and level. If
present, no files will be downloaded, and no data will be loaded.
TYPE: Input, string. Set to 'calibrated' or 'raw'.
COORD: Input, string. What coordinate system you would like your data in. For choices, see THEMIS Sci. Data Anal. Software Users Guide.
TEST: Input, numeric, 0 or 1. Disables selected /CONTINUE to MESSAGE. For QA testing only.
/NO_TIME_CLIP: Disables time clipping, which is the default
Example:
thg_load_efi,/get_suppport_data,probe=['a', 'b']
Notes:
Modifications:
Added TEST kw to disable certain /CONTINUE to MESSAGE, and passed TEST
through to THM_CAL_EFI.PRO, W.M.Feuerstein, 4/7/2008 (M).
Fixed crash on passing an argument for RELPATHNAMES_ALL, WMF, 4/9/2008 (Tu).
Added _extra keyword to ease the passing of keywords to thm_cal_efi
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-09 15:50:20 -0800 (Mon, 09 Jan 2012) $
$LastChangedRevision: 9520 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_load_efi.pro $
(See themis/spacecraft/fields/thm_load_efi.pro)
Procedure: THM_LOAD_EFI_l2
Purpose: Loads THEMIS EFI level 2 data
Syntax: THM_LOAD_EFI [, <optional keywords below> ]
keywords:
PROBE: Input, string. Specify space-separated probe
letters, or string array (e.g., 'a c', ['a', 'c']). Defaults to
all probes.
DATATYPE: Input, string. Default setting is to load
quantities. Use DATATYPE kw to narrow the data products.
Wildcards and glob-style patterns accepted (e.g., ef?, *_dot0).
SUFFIX: Input, scalar or array string. Set (scalar)
to append SUFFIX to all output TPLOT variable names. Set (array
with same # elements as COORD) to put suffixes for corresponding
COORD elements (one TPLOT variable with suffix for each element of
COORD). When COORD has > 1 element, SUFFIX must have the same # of
elements (or be unset).
TRANGE: Input, double (2 element array). Time range
of interest. If this is not set, the default is to prompt the
user. Note that if the input time range is not a full day, a full
day's data is loaded.
/DOWNLOADONLY: Input, numeric, 0 or 1. Set to download file
but not read it.
/VALID_NAMES: Input, numeric, 0 or 1. If set, then this
routine will return the valid probe, datatype and/or level options
in named variables supplied as arguments to the corresponding
keywords.
FILES: Output, string. Named varible for output of
pathnames of local files.
/VERBOSE: Input, numeric, 0 or 1. Set to output some
useful info.
/NO_DOWNLOAD: Input, numeric, 0 or 1. Set to use only files
which are online locally.
RELPATHNAMES_ALL: Output, string. Named variable in which to
return all files that are required for specified timespan, probe,
datatype, and level. If present, no files will be downloaded, and
no data will be loaded.
COORD: Input, string. What coordinate system you
would like your data in. For choices, see THEMIS Sci. Data
Anal. Software Users Guide.
TEST: Input, numeric, 0 or 1. Disables selected
/CONTINUE to MESSAGE. For QA testing only.
/NO_TIME_CLIP: Disables time clipping, which is the default
Example:
thg_load_efi,/get_suppport_data,probe=['a', 'b']
Notes:
Modifications:
Added TEST kw to disable certain /CONTINUE to MESSAGE, and passed TEST
through to THM_CAL_EFI.PRO, W.M.Feuerstein, 4/7/2008 (M).
Fixed crash on passing an argument for RELPATHNAMES_ALL, WMF, 4/9/2008 (Tu).
$LastChangedBy: aaflores $
$LastChangedDate: 2012-02-22 11:09:25 -0800 (Wed, 22 Feb 2012) $
$LastChangedRevision: 9808 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_load_efi_l2.pro $
(See themis/spacecraft/fields/thm_load_efi_l2.pro)
Procedure: THM_LOAD_FBK
Purpose: Loads THEMIS FilterBank data
keywords:
probe = Probe name. The default is 'all', i.e., load all available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be loaded, can be an array of strings
or single string separate by spaces. The default is 'all'
TRANGE= (Optional) Time range of interest (2 element array), if
this is not set, the default is to prompt the user. Note
that if the input time range is not a full day, a full
day's data is loaded
level = the level of the data, the default is 'l1', or level-1
data. A string (e.g., 'l2') or an integer can be used. 'all'
can be passed in also, to get all levels.
type= 'raw' or 'calibrated'. default is calibrated.
suffix= suffix to add to output data quantity (not added to support
data)
relpathnames_all: named variable in which to return all files that are
required for specified timespan, probe, datatype, and level.
If present, no files will be downloaded, and no data will be loaded.
and/or level options in named variables supplied as
arguments to the corresponding keywords.
files named varible for output of pathnames of local files.
CDF_DATA: named variable in which to return cdf data structure: only works
for a single spacecraft and datafile name.
VARNAMES: names of variables to load from cdf: default is all.
/GET_SUPPORT_DATA: load support_data variables as well as data variables
into tplot variables.
/DOWNLOADONLY: download file but don't read it.
/VALID_NAMES, if set, then this routine will return the valid
probe, datatype
/NO_DOWNLOAD: use only files which are online locally.
/VERBOSE set to output some useful info
/NO_TIME_CLIP: Disables time clipping, which is the default
Example:
thg_load_fbk,/get_suppport_data,probe=['a', 'b']
Notes:
Added the new frequency center values, 24-oct-2008, jmm, jimm@ssl.berkeley.edu
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-26 16:43:03 -0800 (Thu, 26 Jan 2012) $
$LastChangedRevision: 9624 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_load_fbk.pro $
(See themis/spacecraft/fields/thm_load_fbk.pro)
Procedure: THM_LOAD_FFT
Purpose: Loads THEMIS FFT spectra (ParticleBurst and WaveBurst) data
keywords:
probe = Probe name. The default is 'all', i.e., load all available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be loaded, can be an array of strings
or single string separate by spaces. The default is 'all'
TRANGE= (Optional) Time range of interest (2 element array), if
this is not set, the default is to prompt the user. Note
that if the input time range is not a full day, a full
day's data is loaded
level = the level of the data, the default is 'l1', or level-1
data. A string (e.g., 'l2') or an integer can be used. 'all'
can be passed in also, to get all levels.
type= 'raw' or 'calibrated'. default is calibrated.
suffix= suffix to add to output data quantity (not added to support
data)
relpathnames_all: named variable in which to return all files that are
required for specified timespan, probe, datatype, and level.
If present, no files will be downloaded, and no data will be loaded.
files named varible for output of pathnames of local files.
CDF_DATA: named variable in which to return cdf data structure: only works
for a single spacecraft and datafile name.
VARNAMES: names of variables to load from cdf: default is all.
/GET_SUPPORT_DATA: load support_data variables as well as data variables
into tplot variables.
/DOWNLOADONLY: download file but don't read it.
/VALID_NAMES: if set, then this routine will return the valid
probe, datatype and/or level options in named variables supplied as
arguments to the corresponding keywords.
/NO_DOWNLOAD: use only files which are online locally.
/VERBOSE set to output some useful info
/NO_TIME_CLIP: Disables time clipping, which is the default
Example:
thm_load_fft,/get_suppport_data,probe=['a', 'b']
Notes:
$LastChangedBy: jimm $
$LastChangedDate: 2012-02-01 23:02:21 -0800 (Wed, 01 Feb 2012) $
$LastChangedRevision: 9671 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_load_fft.pro $
(See themis/spacecraft/fields/thm_load_fft.pro)
Procedure: THM_LOAD_FGM
Purpose: Loads THEMIS fluxgate magnetometer data
keywords:
probe = Probe name. The default is 'all', i.e., load all available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be loaded, 'fge', 'fgh', or 'fgl'. 'all'
can be passed in also, to get all variables.
TRANGE= (Optional) Time range of interest (2 element array), if
this is not set, the default is to prompt the user. Note
that if the input time range is not a full day, a full
day's data is loaded
level = the level of the data to read, the default is 'l1', or level-1
data. A string (e.g., 'l2') or an integer can be used. 'all'
can be passed in also, to get all levels.
type= 'raw' or 'calibrated'. default is calibrated.
coord= coordinate system of output. default is 'dsl'
suffix= suffix to add to output data quantity (not added to support data)
CDF_DATA: named variable in which to return cdf data structure: only works
for a single spacecraft and datafile name.
VARNAMES: names of variables to load from cdf: default is all.
/GET_SUPPORT_DATA: load support_data variables as well as data variables
into tplot variables.
/DOWNLOADONLY: download file but don't read it.
/no_download: use only files which are online locally.
relpathnames_all: named variable in which to return all files that are
required for specified timespan, probe, datatype, and level.
If present, no files will be downloaded, and no data will be loaded.
/valid_names, if set, then this routine will return the valid probe, datatype
and/or level options in named variables supplied as
arguments to the corresponding keywords.
files named varible for output of pathnames of local files.
/VERBOSE set to output some useful info, set to 0 to or 1 to reduce output.
/NO_TIME_CLIP: Disables time clipping, which is the default
NOTE: The following keywords are only used if level=1 is set
cal_dac_offset = apply calibrations that remove digital analog
converter nonlinearity by addition of offset.
Algorithm generated by Dragos Constantine
<d.constantinescu@tu-bs.de>. This is the default
process as of 7-Jan-2010, to disable, explicitly
set this keyword to 0.
cal_spin_harmonics = apply calibrations from a file that remove
spin harmonics by applying spin-dependent
offsets generated by David Fischer
<david.fischer@oeaw.ac.at>. This is the default
process as of 7-Jan-2010, to disable, explicitly
set this keyword to 0.
cal_tone_removal = fitting algorithm removes orbit dependent
spintone without removing scientifically salient
features. Algorithm generated by Ferdinand Plaschke
<f.plaschke@tu-bs.de>. This is the default
process as of 7-Jan-2010, to disable, explicitly
set this keyword to 0.
cal_get_fulloffset = returns the offset used for spintone removal.(this keyword used for valididation)
Because there may be a different offset for each combination of probe and datatype,
This is returned as a struct of structs, with each element in the child structs being an N by 3 array.
For example, if offset_struct is the name of a struct with the return value from the cal_get_fulloffset keyword,
print,offset_struct.tha.fgl
Will print the fulloffset for probe a and datatype fgl.
cal_get_dac_dat = Returns the raw data from directly after the DAC(non-linearity offset) calibration is applied. For verification.
cal_get_spin_dat = Returns the raw data from directly after the spin harmonic(solar array current) calibration is applied. For verification.
Example:
thg_load_fgm,probe=['a','b']
Notes:
This routine is (should be) platform independent.
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-09 15:50:20 -0800 (Mon, 09 Jan 2012) $
$LastChangedRevision: 9520 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_load_fgm.pro $
(See themis/spacecraft/fields/thm_load_fgm.pro)
Procedure: THM_LOAD_FIT
Purpose: Loads THEMIS FIT data
keywords:
probe = Probe name. The default is 'all', i.e., load all available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be loaded, can be an array of strings
or single string separate by spaces. The default is 'all'
TRANGE= (Optional) Time range of interest (2 element array), if
this is not set, the default is to prompt the user. Note
that if the input time range is not a full day, a full
day's data is loaded
level = the level of the data, the default is 'l1', or level-1
data. A string (e.g., 'l2') or an integer can be used. 'all'
can be passed in also, to get all levels.
CDF_DATA: named variable in which to return cdf data structure: only works
for a single spacecraft and datafile name.
VARNAMES: names of variables to load from cdf: default is all.
/GET_SUPPORT_DATA: load support_data variables as well as data variables
into tplot variables.
/DOWNLOADONLY: download file but don't read it.
/valid_names, if set, then this routine will return the valid probe, datatype
and/or level options in named variables supplied as
arguments to the corresponding keywords.
files named varible for output of pathnames of local files.
/no_cal if set will not include boom shortening or Ex offset in output
/VERBOSE set to output some useful info
/NO_TIME_CLIP: Disables time clipping, which is the default
Example:
thg_load_fit,/get_suppport_data,probe=['a', 'b']
Modifications:
J. McFadden passed through the NO_CAL kw to THM_CAL_FIT.PRO, WMF, 6/27/2008.
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-26 16:43:03 -0800 (Thu, 26 Jan 2012) $
$LastChangedRevision: 9624 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_load_fit.pro $
(See themis/spacecraft/fields/thm_load_fit.pro)
Procedure: THM_LOAD_SCM
Purpose: Loads THEMIS SCM data
keywords:
probe = Probe name. The default is 'all', i.e., load all available probes.
This can be an array of strings, e.g., ['a', 'b'] or a
single string delimited by spaces, e.g., 'a b'
datatype = The type of data to be loaded, can be an array of strings
or single string separate by spaces. The default is 'all'
TRANGE= (Optional) Time range of interest (2 element array), if
this is not set, the default is to prompt the user. Note
that if the input time range is not a full day, a full
day's data is loaded
level = the level of the data, the default is 'l1', or level-1
data. A string (e.g., 'l2') or an integer can be used. 'all'
can be passed in also, to get all levels.
CDF_DATA: named variable in which to return cdf data structure: only works
for a single spacecraft and datafile name.
VARNAMES: names of variables to load from cdf: default is all.
/GET_SUPPORT_DATA: load support_data variables as well as data variables
into tplot variables.
/DOWNLOADONLY: download file but don't read it.
/no_download: use only files which are online locally.
relpathnames_all: named variable in which to return all files that are
required for specified timespan, probe, datatype, and level.
If present, no files will be downloaded, and no data will be loaded.
/valid_names, if set, then this routine will return the valid probe, datatype
and/or level options in named variables supplied as
arguments to the corresponding keywords.
files named varible for output of pathnames of local files.
/VERBOSE set to output some useful info, set to 0 to or 1 to reduce output.
CLEANUP: Pass through to THM_CAL_SCM.PRO.
SCM_CAL: Structure containing the calibration parameters
/NO_TIME_CLIP: Disables time clipping, which is the default
KEYWORDS FOR CALIBRATION PROCESS: These are passed through to the
THM_SCM_CAL procedure:
in_suffix = optional suffix to add to name of input data quantity, which
is generated from probe and datatype keywords.
out_suffix = optional suffix to add to name for output tplot quantity,
which is generated from probe and datatype keywords.
trange= array[2] string or double. Limit calibration to specified time range
nk = N points of the cal-convolution kernel, if set, this value will
be used regardless of sample rate.
mk = If nk is not set, set nk to (sample frequency)*mk, where sample
frequency is determined by the data. default 8 for scf, 4 for scp,
and 1 for scw.
despin =classic despin algorithm. 0:off 1:on Default is on.
n_spinfit=n spins to fit for misalignment, dc field calculation and
optionally despin.
cleanup= type of cleanup (default is 'none'):
'spin' for only spin tones (power ripples) cleanup,
'full' for spin tones and 8/32 Hz tones
'none' for no cleanup processes.
wind_dur_1s = window duration for 8/32 Hz cleanup (has to be a multiple of 1s)
default is 1.
wind_dur_spin = spintone cleanup window duration as a multiple of the spin
period. Default is 1.
clnup_author = choice of cleanup routine (default is 'ole'):
'ccc' to use scm_cleanup_ccc
'ole' to use spin_tones_cleaning_vector_v5
fdet = detrend freq. in Hz. Detrend is implemented by subtracting a boxcar
avg., whose length is determined by fdet.
Use fdet=0 for no detrending. Default is fdet=0.
fcut = Low Frequency cut-off for calibration. Default is 0.1 Hz.
fmin = Min frequency for filtering in DSL system. Default is 0 Hz.
fmax = Max frequency for filtering in DSL system. Default is Nyquist.
step = Highest Processing step to complete. Default is step 5.
dfb_butter = correct for DFB Butterworth filter response (defaut is true)
dfb_dig = correct for DFB Digital fiter response (default is true)
gainant = correct for antenna gain (default is true)
blk_con = use fast convolution for calibration and filtering.
Block size for fast convolution will be equal to
(value of blk_con) * (size of kernel). blk_con = 8 by default.
set blk_con=0 to use brute-force convolution.
edge_truncate, edge_wrap, edge_zero= Method for handling edges in
step 3, cal-deconvolution. For usage and exact specification of
these keywords, see docs for IDL convol function. Default is to
zero data within nk/2 samples of data gap or edge.
coord = coordinate system of output. Step 6 output can only be in DSL.
no_download=don't access internet to check for updated calibration files.
dircal= If set to a string, specifies directory of calibration files.
use /dircal or dircal='' to use calibration files in IDL source
distribution.
Example:
thg_load_scm,level=1,/get_suppport_data,probe=['a', 'b']
Notes:
This routine is (should be) platform independent.
Modifications:
Added CLEANUP kw to pass through to THM_CAL_SCM.PRO, W.Michael Feuerstein,
4/21/2008.
30-may-2008 cg, added optional keyword SCM_CAL which is a structure
containing all the calibration parameters.
modified the call to thm_cal_scm so that parameters
can be used.
23-jul-2008, jmm, added _extra to allow SCM cal keywords to allow
cal parameters to be set from the command line,
also fixed bug where program would crash when
called from the command line. Re-tabbed, to find
an 'End of file encountered...' bug.
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-26 16:43:03 -0800 (Thu, 26 Jan 2012) $
$LastChangedRevision: 9624 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_load_scm.pro $
(See themis/spacecraft/fields/thm_load_scm.pro)
function thm_scm_fastconvol(a, kernel)
purpose: a wrapper that gives a unified interface to convol and blk_con -
Unlike convol, it implements convolution in the mathematical sense
while centering the kernel over each data point. center is at
n_elements(k)/2
Unlike blk_con, it implements centering the kernel and the
/edge keywords
Default is to zero the edges within n_elements(k)/2 of the edge.
parameters:
a the data (floating point array).
k the kernel to be convolved with the data (floating point array)
keywords:
edge_zero: pad beginning and ending of data with zero
edge_truncate: pad beginning and ending of data with first/last value
edge_wrap: pad beginning and ending of data by wrapping data around edge.
blk_con: if non-zero, set block size to blk_con times kernel size. if zero
always use brute-force convolution. Defaults to 8.
Author:
Ken Bromund Sept 18, 2007
$LastChangedBy: jimm $
$LastChangedDate: 2012-02-21 12:13:01 -0800 (Tue, 21 Feb 2012) $
$LastChangedRevision: 9797 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/thm_scm_deconvo_vec.pro $
(See themis/spacecraft/fields/thm_scm_deconvo_vec.pro)
Name:
thm_scm_deconvo_vec
Purpose:
continuous calibration accomplished by
convolveing a signal with a kernel.
The kernel is derived by taking the fft of the
inverse of the frequency reponse. The kernel is also constructed
to account for any sample delay.
Inputs:
xio: input/output waveform
nbp: number of points in xio
nk: number of points in kernel: power of 2.
f1: low frequency
f2: high frequency
fe: sample frequency
gainant: gain function, such as thm_scm_gainant. If gainant is an empty
string, unity gain will be used.
ix: antenna number (1,2,3)
pathfil: calibration file name
tau: time correction
Keywords:
edge_truncate
edge_wrap
edge_zero same functionality as keywords of same name to convol()
blk_con if non-zero, use block convolution (fast FFT-based convolution)
with a block size of the value of this keyword times the kernel
size. If data size is too small, it will revert to
brute-force convolution.
plotk create diagnostic plots of the kernel and frequency response.
(See themis/spacecraft/fields/thm_scm_deconvo_vec.pro)
Name:
spinavg
Purpose:
performs a spinavg on B or E field data, results are average values
over the spin periods -- nothing else
Calling Sqeuence:
spinavg,arr_in_t,arr_in_data,arr_in_sunpulse_t,arr_in_sunpulse_data, $
arr_out_data,arr_out_sigma,npoints,sun_data,$
min_points=min_points,alpha=alpha,beta=beta
Input:
arr_in_t = time array for the data
arr_in_data = the data to be spin fit
arr_in_sunpulse_t = time array for sunpulse data
arr_in_sunpulse_data = sunpulse data
Output:
arr_out_data = the array averaged over the spin periods
sigma = sigma for each spin period
npoints = number of points in fit for each spin period
sun_data = midpoint times of spitfit data
keywords:
min_points = Minimum number of points to fit. Default = 5.
alpha = A parameter for finding fits. Points outside of sigma*(alpha + beta*i)
will be thrown out. Default 1.4.
beta = A parameter for finding fits. See above. Default = 0.4
(See themis/spacecraft/fields/thm_spinavg.pro)
NAME:
thm_spinavg
PURPOSE:
average data over spin periods, and return a tplot variable
CALLING SEQUENCE:
thm_spinavg,var_name_in, $
sigma=sigma, npoints=npoints, spinaxis=spinaxis, median=median, $
plane_dim=plane_dim, axis_dim=axis_dim, $
min_points=min_points,alpha=alpha,beta=beta, $
phase_mask_starts=phase_mask_starts,phase_mask_ends=phase_mask_ends, $
sun2sensor=sun2sensor
INPUT:
var_name_in = tplot variable name containing data to fit
keywords:
sigma = If set, will cause program to output tplot variable with
sigma for each period.
npoints = If set, will cause program to output tplot variable with
of points in fit.
spin_frac_offset = If set, the time array of the variable will be
offset by this fraction of an average spin
period before averaging.
absv = if set, fit the absolute value.
min_points = Minimum number of points to fit. Default = 5.
alpha = A parameter for finding fits. Points outside of
sigma*(alpha + beta*i) will be thrown out for the ith
iteration. Default 1.4.
beta = A parameter for finding fits. See above. Default = 0.4
$LastChangedBy: aaflores $
$LastChangedDate: 2012-01-26 16:43:03 -0800 (Thu, 26 Jan 2012) $
$LastChangedRevision: 9624 $
$URL:
(See themis/spacecraft/fields/thm_spinavg.pro)
procedure: thm_spinfit
Purpose: finds spinfits of field data
finds A,B, and C fits for each period of data, over the entire day
required parameters:
var_name_in = tplot variable name containing data to fit
keywords:
sigma = If set, will cause program to output tplot variable with sigma for each period.
npoints = If set, will cause program to output tplot variable with number of points in fit.
spinaxis = If set, program will output a tplot variable storing the average over the spin axis dimension
for each time period.
median = If spinaxis set, program will output a median of each period instead of the average.
plane_dim = Tells program which dimension to treat as the plane. 0=x, 1=y, 2=z. Default 0.
axis_dim = Tells program which dimension contains axis to average over. Default 0. Will not
create a tplot variable unless used with /spinaxis.
min_points = Minimum number of points to fit. Default = 5.
alpha = A parameter for finding fits. Points outside of sigma*(alpha + beta*i)
will be thrown out. Default 1.4.
beta = A parameter for finding fits. See above. Default = 0.4
phase_mask_starts = Time to start masking data. Default = 0
phase_mask_ends = Time to stop masking data. Default = -1
sun2sensor = Tells how much to rotate data to align with sun
sensor. This defaults to 45 degrees for plane_dim = 1
and 135 degrees for plane_dim = 0
build_efi_var = if set to a valid string, then this will return an
EFI-like variable, with Ex set to spinfit_b, and Ey
set to spinfit_c, with the name of build_efi_var
Example:
thm_spinfit,'th?_fg?',/sigma
Notes: under construction!!
Written by Katherine Ramer
$LastChangedBy: kramer $
$LastChangedDate: 2007-06-08 10:10:36 -0700 (Fri June 8, 2007) $
$LastChangedRevision: 0 $
$URL:
(See themis/spacecraft/fields/thm_spinfit.pro)
Function: THM_UNPACK_HED
thm_unpack_hed, data_type, hed_array
Purpose: Unpacks data packed into HED data.
Arguements:
DATA_TYPE STRING, one of the L1 data types (eff, scp, fbk, etc.)
HED_ARRAY BYTE[ N, 16], array of header data.
keywords:
None.
Example:
get_data, 'tha_fit_hed', data=d_hed
hed_data = thm_unpack_hed( 'fit', d_hed.y)
Notes:
-- Returns int( 0) if requested DATA_TYPE is not implemented.
-- Returns annonymous structure with variable elements if DATA_TYPE is recognized.
-- Not all DATA_TYPEs are implemented; implemented data types (APIDs) listed below:
FIT (on-board EFI and FGM spin fits, 410),
FBK (FilterBank data, 440),
EFI waveform (VA?, VB?, EF?; 441,442,443, 445,446,447, 449,44A,44B),
SCM waveform (SCF, SCP, SCW; 444; 448; 44C),
FGM waveform (FGL, FGH; 460, 461),
FFT spectra (FFP, FFW; 44D, 44E).
Modification History:
Written by J Bonnell, 31 Jan 2007
Modified by
LeContel 2007-05-24 10:39 (Wed, 24 May 2007)
Modification for reading scm and efw headers:
speed = reform( dh[ *, 14]/16b)
$LastChangedBy: jbonnell $
$LastChangedDate: 2007-06-16 10:57:56 -0700 (Sat, 16 Jun 2007) $
$LastChangedRevision: 794 $
$URL $
(See themis/spacecraft/fields/thm_unpack_hed.pro)
function time_domain_filter
purpose: filter data in a tplot structure, assuming constant dt between points,
returns filtered data in a new tplot structure.
usage
new_data = time_domain_filter(data, freq_low, freq_high)
Parameters
data : a structure with elements x and y for time and data, respectively, with
time in seconds.
freq_low: low cutoff freqency in Hz
freq_high: high cutoff frequency in Hz
HISTORY
Chris Chaston 9-May-2007 ?
$LastChangedBy: kenb-mac $
$LastChangedDate: 2007-10-02 09:24:50 -0700 (Tue, 02 Oct 2007) $
$LastChangedRevision: 1645 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_7_01/idl/themis/spacecraft/fields/time_domain_filter.pro $
(See themis/spacecraft/fields/time_domain_filter.pro)