Procedure: THM_CAL_EFI Purpose: Converts raw EFI (V, EDC, and EAC waveform) data into physical quantities. Syntax: THM_CAL_EFI [, ] 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. TRY_DESPIKE: If set, despike the raw E field data before calibration, uses function SIMPLE_DESPIKE_1d for the calculation. DESPIKE_THRESHOLD: Threshold in ADC units for despike calculation, the default is 200 DESPIKE_WIDTH: Half Width of the median filter used for the despike calculation, the default is 11 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 'l2' use_eclipse_corrections: Only applies when loading and calibrating Level 1 data. Defaults to 0 (no eclipse spin model corrections applied). use_eclipse_corrections=1 applies partial eclipse corrections (not recommended, used only for internal SOC processing). use_eclipse_corrections=2 applies all available eclipse corrections. 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: $ $LastChangedDate: $ $LastChangedRevision: $ $URL: $