;+ ;PROCEDURE: thm_crib_part_getspec ; ; ***** A copy and paste crib ***** ; ;PURPOSE: ; A crib showing how to create energy and angular spectrograms using ; THM_PART_GETSPEC. ; ;DETAILS ; THM_PART_GETSPEC is a wrapper that takes user input and creates tplot ; variables containing energy and/or angular spectra of ESA and SST data. The ; tplot variables created end in 'en_eflux' for energy spectra and 'an_eflux' ; plus a suffix corresponding to the type of angular spectrum specified by ; the ANGLE keyword for angular spectra by default. The user can select a ; range of probe(s), PROBE, and time range, TRANGE, of interest. The energy ; range of interest, ERANGE, is specified in eV. The user can also choose to ; create tplot variable for one or more data types, DATA_TYPE. The phi, PHI, ; and theta, THETA, ranges of interest, specified in DSL coordinates, can also ; be input, by the user. SUFFIX specifies a string that will be added to the ; *an_eflux*' tplot variables. ; ; 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=[0,420], the phi bins corresponding to 0-60 ; degrees are appended to the top of the plot. ; ; The START_ANGLE keyword specifies the start of the y-axis (phi). This is ; useful to center the spectra plot on the y-axis at a particular phi angle. ; If this keyword is not set, the y-axis starts at the first angle input to ; the PHI keyword. ; ; Use the ENERGY and ANGLE keywords to specify whether to create tplot ; variables for energy and/or angular spectra. The ANGLE keyword is also used ; to specify the type of angular spectrum created (e.g. phi, theta, pa, gyro). ; If neither of ENERGY and ANGLE keywords are specified, then both are turned ; on and the angular spectrum type defaults to phi. ; ; When set, the AUTOPLOT keyword enables to the tplot variables to be ; automatically plotted using some simple code located at the end of ; THM_PART_GETSPEC. The tplot variables created are properly formatted by ; THM_PART_MOMENTS2 and THM_PART_GETSPEC whether or not AUTOPLOT is set. ; Setting AUTOPLOT will also create a default tplot title containing the ; theta, phi, and energy ranges used to create the plot. ; ; After reading in the user's input, THM_PART_GETSPEC then calls THM_LOAD_SST ; and/or THM_LOAD_ESA_PKT to load the particle data. THM_PART_MOMENTS2 is ; then called to format the spectra data based on the user's input and create ; the tplot variables. THM_PART_MOMENTS2 calls THM_PART_GETANBINS in order to ; determine which energy/angle bins should be turned on/off. If there's a mode ; change, THM_PART_MOMENTS2 will re-call THM_PART_GETANBINS to account for any ; changes in the mode's anglemap. ; ; Pitch angle (ANGLE='pa') and gyrovelocity (ANGLE='gyro') spectra are generated ; by gridding a globe in a field-aligned coordinate (FAC) system at regular ; intervals along pitch (latitude) and gyrovelocity (longitude) as specified by ; the REGRID keyword. These FAC angle bins are then rotated back into the ; native DSL coordinates of the particle distribution data. The flux assigned ; to a given FAC angle bin is determined by native angle bin to which the center ; of FAC angle bin has been rotated. So if a FAC angle bin center is rotated ; into the 88th angle bin of the probe's particle distribution data, the flux ; for that FAC angle bin is the same as the flux in angle bin 88 of the ; particle distribution data. This rotation occurs for each time sample of the ; probe's particle data. ; ; The size of the FAC system grid is specified with the REGRID = [m,n], a two- ; element array in which the first element of the array specifies the number ; of grid elements in the gyrovelocity (longitudinal) direction while the second ; element sets he number of grid elements in the pitch (latitudinal) ; direction. Increasing the number of elements in the FAC system grid will ; increase the accuracy of the pitch angle and gyrovelocity angle spectra as it ; decreases the degree to which the FAC bins overlap into one or more native ; distribution angle bin. 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. ; ; The PITCH and GYRO keywords set the angle range of interest for pitch angle ; and gyrovelocity spectra plots similarly to the THETA and PHI keywords. ; Setting PHI and THETA will affect pitch angle and gyrovelocity plot, but the ; PITCH and GYRO keywords will be ignored when the ANGLE keyword is set to ; 'PHI' or 'THETA'. Energy spectra, generated by using the /ENERGY keyword, will ; also be affected by PITCH and GYRO settings. ; ; The OTHER_DIM keyword specifies the second axis for the field aligned ; coordinate system, necessary when plotting pitch angle or gyrovelocity spectra. ; See THM_FAC_MATRIX_MAKE for more info. If the keyword is not set in ; THM_PART_GETSPEC, OTHER_DIM defaults to 'mphigeo'. ; ; Also, when calculating pitch angle and/or gyrovelocity spectra ; THM_FAC_MATRIX_MAKE might require the data be de-gapped in order to ; calculate the rotation matrix. If so, the /degap keyword and tdegap keywords ; can passed in the call to THM_PART_GETSPEC. See TDEGAP and ; THM_FAC_MATRIX_MAKE for more info. ; ; The /NORMALIZE keyword will normalize the flux for each time sample in a ; spectra plot to values between 0 and 1. ; ; BADBINS2MASK is a 0-1 array that will be mask SST bins with a NaN to ; eliminate artifacts such as 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. ; ; The DATAGAP is very useful when you want to overlay burst mode spectra plots ; over full mode spectra. Set the DATAGAP keyword to a number of seconds that ; is less than the time gap of the burst data, but greater than the sample ; interval of the underlying full mode data. This way the time gaps between ; the burst mode data won't be interpolated by SPECPLOT and cover up the full ; mode data between the burst mode data. ; ; ;NOTES: ; - All angles are in DSL coordinates ; - All datatypes are now valid ; - Theta input must satisfy: -90 < theta[0] < theta[1] < 90 ; - Phi input must be specified in ascending order in degrees ; (e.g. [270, 450] or [-90, 90] to specify the 'daylight' hemisphere in DSL ; coordinates) ; - Incorporates improvements contained in v1.2 ; ;CREATED BY: Bryan Kerr ;VERSION: 1.2 ; $LastChangedBy: aaflores $ ; $LastChangedDate: 2011-02-17 16:08:13 -0800 (Thu, 17 Feb 2011) $ ; $LastChangedRevision: 8241 $ ; $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/thmsoc/tags/tdas_8_00/idl/themis/examples/thm_crib_part_getspec.pro $ ;- ; thm_crib_part_getspec_01 ; Example of plotting the angular phi spectrum in phi for 2 days of data ; beginning 12:30pm, June 17, 2007 for probes D and E, for peif and peef data ; for energies between 15 and 40 keV, for all thetas, and for all phi angles. ; Setting the start_angle to -35 degrees sets up tplot variable so that the phi ; angles are plotted from -35 to 325 degrees. del_data, '*' thm_part_getspec, probe=['d','e'], trange=['07-06-17/12:30','07-06-19/12:30'], $ theta=[-90,90], phi=[0,360], erange=[15000,40000], $ data_type=['peif','peef'], start_angle=-35, $ /autoplot, angle='phi' ; thm_crib_part_getspec_02 ; Example of plotting the angular phi spectrum in phi for 2 days of data beginning ; 12:30pm, June 17, 2007 for probes A and B, for the psif and psef data types ; for all energies between 100 and 1000 eV, a theta angle between -45 and +45 ; degrees, and for all phi angles with an additional 90 degrees wrapped to the ; top of the plot. del_data, '*' thm_part_getspec, probe=['a', 'b'], trange=['07-06-17/12:30','07-06-19/12:30'], $ theta=[-45,45], phi=[0,450], erange=[5e4, 1e6], $ data_type=['psif','psef'], /autoplot, angle='phi' ; thm_crib_part_getspec_03 ; Example of plotting the energy spectrum for 1.5 hours of data beginning ; 10:30am, March 23, 2007 for probes A and E, for the peif, psif, peef, and psef ; data types for all energies for all theta angles, and for dayside phi angles. ; Alternatively, the 'dayside' angles can also be specified as phi=[270,450]. del_data, '*' thm_part_getspec, probe=['a','e'], trange=['07-03-23/10:30','07-03-23/12'], $ theta=[-90,90], phi=[-90,90], $ data_type=['peif', 'psif', 'peef', 'psef'], $ /energy, /autoplot ; thm_crib_part_getspec_04 ; Example of plotting the angular phi spectrum for 1.5 hours of data beginning ; 10:30am, March 23, 2007 for probes A and E, for the peib, psif, peeb, and psef ; data types for the energy range between 10 and 100 keV, for all theta angles, ; and for all phi angles. A start_angle for phi of 180 degrees is specified to ; center the plot at phi = 360. A suffix, '_march23', is added to all tplot ; variables. ; This example also shows how to create your own plot without using the AUTOPLOT ; keyword. del_data, '*' thm_part_getspec, probe=['a','e'], trange=['07-03-23/10:30','07-03-23/12'], $ theta=[-90,90], phi=[0,360], start_angle = 180, $ data_type=['peib', 'psif', 'peeb', 'psef'], $ erange=[10000, 100000], suffix='_march23', angle='phi' tplot,'th*an_eflux_phi_march23' ; thm_crib_part_getspec_05 ; Example plotting full energy and phi angular spectra for full, reduced, and ; burst iESA data del_data, '*' thm_part_getspec, probe=['e'], trange=['07-03-23/11:13','07-03-23/12'], $ theta=[-90,90], phi=[0,360], start_angle=180, $ data_type=['peif','peib','peir'], erange=[0, 100000], $ /energy, angle='phi', /autoplot ; thm_crib_part_getspec_06 ; Example plotting full energy and phi angular spectra for SST and ESA ; reduced data. del_data, '*' thm_part_getspec, probe=['e'], trange=['07-06-17/9:50','07-06-17/10:50'], $ theta=[-90,90], phi=[0,360], $ data_type=['psir','pser','peir','peer'], $ /energy, /autoplot, angle='phi' ; thm_crib_part_getspec_07 ; Example plotting full eESA theta angular spectra for all 5 probes del_data, '*' thm_part_getspec, probe=['a','b','c','d','e'], trange=['07-03-23/11:13','07-03-23/12'], $ theta=[-90,90], phi=[0,360], data_type=['peif'], /autoplot, $ angle='theta' ; thm_crib_part_getspec_08 ; Example plotting low-energy eESA pitch angular spectra for all 5 probes. del_data, '*' thm_part_getspec, probe=['a','b','c','d','e'], trange=['07-06-03/01:08','07-06-03/04:20'], $ data_type=['peef'], erange=[100,300], angle='pa', regrid=[30,20], /autoplot ; Note: to calculate the gyrovelocity spectrum, set angle='gyro' ; thm_crib_part_getspec_09 ; Create a tplot variable, thc_pser_an_eflux_phi,containing the phi spectrum ; for 6-angle pser data for probe c. del_data, '*' thm_part_getspec, probe=['c'], trange=['08-02-12/03:37','08-02-12/03:45'], $ data_type='pser', angle='phi' tplot,'thc_pser_an_eflux_phi' ; thm_crib_part_getspec_10 ; Plot low-energy eESA gyrovelocity spectra for phi angles between 270-360 degrees. del_data, '*' thm_part_getspec, probe=['c'], trange=['07-06-03/01:08','07-06-03/03:49'], $ pitch=[0,180], $ gyro=[0,540], $ theta=[-90,90], $ phi=[270,360], $ other_dim='xgse', $ data_type=['peef'], $ angle='gyro', /autoplot, regrid=[30,20], erange=[100,300] ; thm_crib_part_getspec_11 ; Plot iSST pitch angle spectra for theta angles between -45 and 45 degrees, and ; normalize the data. del_data, '*' thm_part_getspec, probe=['c'], trange=['08-02-16/04:50','08-02-16/04:53'], $ ;pitch=[0,180], $ ;gyro=[0,360], $ theta=[-45,45], $ ;phi=[160,180], $ other_dim='xgse', $ /normalize, $ data_type=['psif'], $ angle='pa', /autoplot, regrid=[32,16], /degap, dt=3 ; thm_crib_part_getspec_12 ; This crib shows how to locate sun-contaminated iSST angle bins, and save the ; bin numbers to an array that can be passed to THM_PART_MOMENTS to mask the ; contaminated bins with NaNs. The whole crib can be copied an pasted at once. del_data, '*' if keyword_set(badbins2mask) then tmp=temporary(badbins2mask) ; clear previous version of BADBINS2MASK for EDIT3DBINS sc='c' ; specify probe ; plot the pitch angle distribution with no masking applied thm_part_getspec, probe=sc, trange=['08-02-12/03:37','08-02-12/03:45'], $ data_type='psif', angle='pa', regrid=[32,32], /autoplot edit3dbins,thm_sst_psif(probe=sc, gettime(/c)), badbins2mask ; Select the time at which you want to plot the SST data distribution by a ; single left-click of the mouse. A plot of the distribution will then appear. ; All angle bins should be turned on (unmasked) as indicated by their black bin ; numbers. Click the middle-mouse button (scroll-wheel) to turn off (mask) one ; or more angle bins. Sun-contaminated bins should have much higher values ; relative to non-contaminated bins, usually appearing red. Right-click when ; finished. ;plot pitch angle distribution with masked SST bins thm_part_getspec, probe=sc, trange=['08-02-12/03:37','08-02-12/03:45'], $ data_type='psif', angle='pa', regrid=[32,32], /autoplot, $ badbins2mask=badbins2mask ; thm_crib_part_getspec_13 ; Same as above crib except shows how to work eSST data. del_data, '*' if keyword_set(badbins2mask) then tmp=temporary(badbins2mask) ; clear previous version of BADBINS2MASK for EDIT3DBINS sc='b' ; specify probe ; plot the pitch angle distribution with no masking applied thm_part_getspec, probe=sc, trange=['08-02-13/01:00','08-02-13/05:00'], $ data_type='psef', angle='pa', regrid=[32,32], /autoplot edit3dbins,thm_sst_psef(probe=sc, gettime(/c)), badbins2mask ; Select the time at which you want to plot the SST data distribution by a ; single left-click of the mouse. A plot of the distribution will then appear. ; All angle bins should be turned on (unmasked) as indicated by their black bin ; numbers. Click the middle-mouse button (scroll-wheel) to turn off (mask) one ; or more angle bins. Sun-contaminated bins should have much higher values ; relative to non-contaminated bins, usually appearing red. Right-click when ; finished. ;plot pitch angle distribution with masked SST bins thm_part_getspec, probe=sc, trange=['08-02-13/01:00','08-02-13/05:00'], $ data_type='psef', angle='pa', regrid=[32,32], /autoplot, $ badbins2mask=badbins2mask ; thm_crib_part_getspec_14 ; Shows how to limit energy spectra to a specified pitch and gyrovelocity range ; in mphigeo field aligned coordinate system. Since the REGRID keyword is not ; specified, it defaults to [16,8]. OTHER_DIM defaults to 'mphigeo' when not ; explicitly specified. del_data, '*' thm_part_getspec, probe=['a'], trange=['07-03-23/10:30','07-03-23/12'], $ data_type=['peif'], pitch=[75,105], gyro=[150,210], $ /autoplot, /energy ; thm_crib_part_getspec_15 ; This crib shows how to combine full and burst mode spectra into one plot by ; overlaying the burst mode data on top of the full mode data. del_data,'*' ; Set DATAGAP keyword to a number of seconds greater than highest full mode ; sample rate in the timspan (~390 sec), but less than the length of the time gap ; between burst segments (~44 minutes) thm_part_getspec, probe=['a'], trange=['07-03-23/10:30','07-03-23/12:40'], $ theta=[-90,90], phi=[0,360], data_type=['peif','peib'], /energy, datagap=390 ; Store the data in a tplot psuedovariable. store_data,'tha_comb',data=['tha_peif_en_eflux','tha_peib_en_eflux'] ylim,'th*comb',5,23000 ; set y-axis limits for spectra plots zlim,'th*comb',10,3e6 ; set all spectra to same color scale ylim,'tha*eflux',5,23000 ; set y-axis limits for spectra plots zlim,'tha*eflux',10,3e6 ; set all spectra to same color scale tplot,'tha_comb' ; plot only the combined spectra ; Plot the full, burst, and combined spectra in separate panels. ;tplot,['tha_peif_en_eflux','tha_peib_en_eflux','tha_comb'] end