This page was created by the IDL library routine
mk_html_help2.
Last modified: Wed Jun 24 12:41:17 2009.
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: 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_5_1/idl/themis/spacecraft/fields/scm_cleanup_ccc.pro $
(See themis/spacecraft/fields/scm_cleanup_ccc.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: jimm $
$LastChangedDate: 2009-02-09 17:51:14 -0800 (Mon, 09 Feb 2009) $
$LastChangedRevision: 4926 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/idl/themis/spacecraft/fields/spin_tones_cleaning_vector_v5.pro $
(See themis/spacecraft/fields/spin_tones_cleaning_vector_v5.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 -1 if
Syntax:
result = thm_get_efi_edc_offset( Y, Sample_Rate, N_Spins, Spin_Period [, Offset_Estimation_Window_Truncated ] [, NEW_NSPINS ] )
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_Nspins Output If OFFSET_ESTIMATION_WINDOW_TRUNCATED is set, then this will contain the adjusted number of spins.
(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.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 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.
STORED_TNAMES: An OUTPUT. Returns a string array containing each TPLOT variable name
invoked in a STORE_DATA operation (chronological order).
(Not sorted or uniqued.)
ONTHEFLYEDCOFFSET: Return the EDC offset array calculated on-the-fly *** FOR THE LAST EF? DATATYPE PROCESSED ONLY ***.
GAP_TRIGGER_VALUE: An INPUT and OUTPUT. 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.
NUMBER_OF_SPINS: I/O. Specify the number of spins for the on-the-fly EDC offset
calculation estimation window, or read out the default (20 spins).
OFFSET_ESTIMATION_FUNC: OUTPUT <string scalar>. The name of the function used to
estimate the EDC offset for the on-the-fly window.
/EDGE_TRUNCATE: I/O. 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.
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 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.
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: mfeuerstein $
$LastChangedDate: 2008-09-09 17:30:11 -0700 (Tue, 09 Sep 2008) $
$LastChangedRevision: 3471 $
$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.
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: jwl $
$LastChangedDate: 2009-01-29 15:07:18 -0800 (Thu, 29 Jan 2009) $
$LastChangedRevision: 4691 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/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_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: jbonnell $
$LastChangedDate: 2008-11-18 15:43:48 -0800 (Tue, 18 Nov 2008) $
$LastChangedRevision: 3999 $
$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
$LastChangedBy: jimm $
$LastChangedDate: 2009-02-09 17:50:57 -0800 (Mon, 09 Feb 2009) $
$LastChangedRevision: 4925 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/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: jbonnell $ $LastChangedDate: 2007-06-28 18:00:35 -0700 (Thu, 28 Jun 2007) $ $LastChangedRevision: 939 $ $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: kenb-mac $
$LastChangedDate: 2007-09-24 13:05:40 -0700 (Mon, 24 Sep 2007) $
$LastChangedRevision: 1620 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/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.
Inputs:
probe: 1-character string identifying which spacecraft
datatype: 3-character string identifying data type ('eff','efp' or 'efw')
offset: 1 x n (2 dimensions) 3-element array: Ex, Ey, Ez offset
gain: 3-element array: E12, E34, E56 gain
tplot_name: String scalar containing the name of the TPLOT variable to
operate on (regardless of PROBE and DATATYPE kwd's).
Options:
notch: 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)
tweak_gains: 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: jbonnell $ $LastChangedDate: 2007-06-28 17:58:19 -0700 (Thu, 28 Jun 2007) $ $LastChangedRevision: 938 $ $URL $
(See themis/spacecraft/fields/thm_fft_freq_bins.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: DOUBLE, time basis of data since THEMIS epoch.
name: STRING, waveform data type indicator.
probes: SCALAR STRING, name of THEMIS probe ('a','b',...).
Keywords:
cal_pars: STRUCT, see Notes below for elements.
TEST: 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!
-- 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: 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: mfeuerstein $
$LastChangedDate: 2008-09-09 17:30:11 -0700 (Tue, 09 Sep 2008) $
$LastChangedRevision: 3471 $
$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
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.
/VERBOSE set to output some useful info
/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.
type: 'calibrated' or 'raw'
coord: what coordinate system you would like your data in.
TEST: Disables selected /CONTINUE to MESSAGE. For QA testing only.
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: jimmpc $
$LastChangedDate: 2009-05-29 15:10:52 -0700 (Fri, 29 May 2009) $
$LastChangedRevision: 6004 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/idl/themis/spacecraft/fields/thm_load_efi.pro $
(See themis/spacecraft/fields/thm_load_efi.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
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: jimm $
$LastChangedDate: 2008-10-28 10:57:47 -0700 (Tue, 28 Oct 2008) $
$LastChangedRevision: 3840 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/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
Example:
thm_load_fft,/get_suppport_data,probe=['a', 'b']
Notes:
$LastChangedBy: jimm $
$LastChangedDate: 2008-07-15 17:50:56 -0700 (Tue, 15 Jul 2008) $
$LastChangedRevision: 3281 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/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 'ssl'
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.
Example:
thg_load_fgm,probe=['a','b']
Notes:
This routine is (should be) platform independent.
$LastChangedBy: jimm $
$LastChangedDate: 2008-10-27 11:52:08 -0700 (Mon, 27 Oct 2008) $
$LastChangedRevision: 3829 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/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
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: jimmpc $
$LastChangedDate: 2008-07-15 16:26:59 -0700 (Tue, 15 Jul 2008) $
$LastChangedRevision: 3279 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/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
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: jimm $
$LastChangedDate: 2008-09-30 13:07:28 -0700 (Tue, 30 Sep 2008) $
$LastChangedRevision: 3583 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_5_1/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: 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_5_1/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)
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.
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_5_1/idl/themis/spacecraft/fields/time_domain_filter.pro $
(See themis/spacecraft/fields/time_domain_filter.pro)