PROCEDURE: thm_part_getspec PURPOSE: Generates tplot variables containing energy-time angular particle spectra for any angle range and/or any energy range. 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' 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. phi = Angle range of interest (2 element array) in degrees relative to probe-sun direction in the probe's spin plane. Specify angles in ascending order (e.g. [90, 180]) to specify the 'daylight' hemisphere in DSL coordinates. Default is all 360 degrees (e.g. [0, 360]). If the phi range is greater than 360 degrees, then the phi bins at the beginning of the phi range are added and wrapped around the end of phi range. For example, if phi=[-90,360], the phi bins corresponding to 270-360 degrees are appended to the bottom of the plot. Also controls which bins are selected for pitch/gyrovelocity spectra. Phi is limited to be between -360 and 720 degrees. Note that, if the ENERGY keyword is set (as is true in the default case). This is also true for 'pa' and 'gyro' cases. theta = Angle range of interest (2 element array) in degrees relative to spin plane, e.g. [-90, 0] or [-45, 45] in the probe's spin plane. Specify in acending order. Default is all (e.g. [-90, 90]). Also controls which bins are selected for pitch/gyrovelocity spectra. pitch = Angle range of interest (2 element array) in degrees relative to the magnetic field. Default is all (e.g. [0, 180]). Has no effect on phi/theta spectra plots. gyro = Gyrovelocity angle range of interest (2 element array) in degrees. Same rules as specifying phi apply to gyrophse. Default is all (e.g. [0, 360]). Has no effect on phi/theta spectra plots. erange = Energy range (in eV) of interest (2 element array). Default is all. data_type = The type of data to be loaded (e.g. ['peif', 'peef']) start_angle = Angle at which to begin plotting the data the bottom of the plot along the y-axis. At this time this works for phi only. If not set, keyword defaults to first element of phi input. suffix = Suffix to add to tplot variable names. /AUTOPLOT: Set to activiate a simple plotting routine to display tplot variables created by this routine. /ENERGY: Set to output tplot variables containing the energy spectrum of the energy/angle ranges input above. angle = Type of angular spectrum tplot variable created and plotted using the energy/angle ranges input above e.g. 'phi'. Default is 'phi'. The type of angular spectra is appended to its corresponding tplot variable name. All possible options are: phi = phi angular spectrum theta = theta angular spectrum pa = pitch angular spectrum (only works with full angle ranges) gyro = gyrovelocity angular spectrum (only works with full angle ranges) NOTE: If neither of ENERGY and ANGLE keywords are specified, then then both are turned on with ANGLE defaulting to 'phi'. /GET_SUPPORT_DATA: load support_data variables as well as data variables into tplot variables. regrid = [m,n] Number of angle bins, used to re-grid (2-element array) along phi (gyrovelocity) and theta (pitch), respectively, when calculating pitch/gyrovelocity angle spectrum. For example, e.g. [32,16] creates a regularly-spaced array of 32 phi angles by 16 theta angles that resample the probe(s) native angle bin array. Default is [16,8]. Keyword has no effect on phi and theta spectragrams. Accuracy of the spectragrams increases when more angle bins are used to re-grid. Suitable numbers for m and n are numbers like 2^k. So far, k=2-6 has been tested and work. Other numbers will work provided 180/n and 360/m are rational. other_dim = Keyword passed to THM_FAC_MATRIX_MAKE for conversion to field aligned coordinates to create pitch angle and gyrovelocity spectra. See THM_FAC_MATRIX_MAKE for valid input. Default is 'mphigeo'. /NORMALIZE: Set to normalize the flux for each time sample to 0-1. badbins2mask = A 0-1 array that indicates which SST bins will be masked with NaN to eliminate things like sun contamination. The array should have the same number of elements as the number of angle bins for a given data type. A 0 indicates that will be masked with a NaN. This is basically the output from the bins argument of EDIT3DBINS. datagap = Maximum time gap in seconds over which to interpolate the plot. Sets the DATAGAP flag in the dlimits which SPECPLOT uses to interpolate pixels in time gaps less than DATAGAP. Use this keyword when overlaying spectra plots, allowing the underlying spectra to be shown in the data gaps of the overlying spectra. Default is zero. fractional_counts = Flag to keep the ESA unit conversion routine from rounding to an even number of counts when removing the dead time correction (no effect if input data already in counts, no effect on SST data). dist_array: Provide an array of data instead of having thm_part_getspec/thm_part_moments2 load the data directly. This allows preprocessing/sanitization operations to be performed prior to moment generation. See thm_part_dist_array.pro, thm_part_conv_units.pro ESA PEER/PEIR/PEIF Background Removal Keywords: /bdnd_remove: Turn on ESA background removal. bgnd_type(Default 'anode'): Set to string naming background removal type: 'angle','omni', or 'anode'. bgnd_npoints(Default = 3): Set to the number of lowest values points to average over when determining background. bgnd_scale(Default=1): Set to a scaling factor that the background will be multiplied by before it is subtracted GUI-RELATED KEYWORDS: /GUI_FLAG: Flag tells code to recognize status bar and history window objects. gui_statusBar = Object reference to status bar object in GUI. gui_historyWin = Object reference to history window object in GUI. EXAMPLE: thm_part_getspec, probe='d', trange=['07-06-17','07-06-19'] SEE ALSO: THM_CRIB_PART_GETSPEC, THM_PART_MOMENTS2, THM_PART_GETANBINS, THM_LOAD_SST, THM_LOAD_ESA_PKT, THM_FAC_MATRIX_MAKE,THM_REMOVE_SUNPULSE,THM_CRIB_SST_CONTAMINATION NOTES: For documentation on sun contamination correction keywords that may be passed in through the _extra keyword please see: thm_sst_remove_sunpulse.pro or thm_crib_sst_contamination.pro BACKGROUND REMOVAL(BGND) Description, Warnings and Caveats(from Vassilis Angelopoulos): This code allows for keywords that permit omni-directional or anode-dependent background removal from penetrating electrons in the ESA ion and electron detectors. Anode-dependent subtraction is used when possible by default, i.e., when angle information is available; but user has full control by keyword specification. Default bgnd estimates use 3 lowest counts/s values. Scaling of the background (artificial scaling) can also allow playing with background estimates to account for noise statistics in the background itself. The parameters that have worked well for me during high bgnd levels are: ,/bgnd_remove, bgnd_type='anode', bgnd_npoints=3, bgnd_scale=1.5 The same keywords when used in thm_part_getspec, and thm_part_moments are understood and passed to the data extraction routines, such that they will do the removal before computing moments or spectra. This background subtraction to be used at the inner magnetosphere, or when SST electron fluxes indicate presence of significant electron fluxes at the satellite (injections). At quiet times the code tends to remove real fluxes, so beware. CREATED BY: Bryan Kerr $LastChangedBy: bckerr $ $LastChangedDate: 2008-06-13 13:29:12 -0700 (Fri, 13 Jun 2008) $ $LastChangedRevision: 3204 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/trunk/idl/themis/spacecraft/particles/thm_part_getspec.pro $