;+ ;Purpose: A basic overview of how to obtain and plot two-dimentional slices of ; SST and/or ESA particle distributions. ; ; Run "thm_ui_slice2d" on the IDL console to use for the GUI version. ; ; ;Methods: ; Geomtric: ; Each point on the plot is given the value of the bin it instersects. ; This allows bin boundaries to be drawn at high resolutions. ; ; 2D Interpolation: ; Datapoints within the specified theta or z-axis range are projected onto ; the slice plane and linearly interpolated onto a regular 2D grid. ; ; 3D Interpolation: ; The entire 3-dimensional distribution is linearly interpolated onto a ; regular 3D grid and a slice is extracted from the volume. ; ; ;Coordinates: ; The coordinate system in which the slice will be oriented. ; Options are 'DSL' (default), 'GSM', 'GSE' and the following magnetic ; field aligned coordinates (field parallel to z axis). ; ; 'xgse': The x axis is the projection of the GSE x-axis ; 'ygsm': The y axis is the projection of the GSM y-axis ; 'zdsl': The y axis is the projection of the DSL z-axis ; 'RGeo': The x is the projection of radial spacecraft position vector (GEI) ; 'mRGeo': The x axis is the projection of the negative radial spacecraft position vector (GEI) ; 'phiGeo': The y axis is the projection of the azimuthal spacecraft position vector (GEI), positive eastward ; 'mphiGeo': The y axis is the projection of the azimuthal spacecraft position vector (GEI), positive westward ; 'phiSM': The y axis is the projection of the azimuthal spacecraft position vector in Solar Magnetic coords ; 'mphiSM': The y axis is the projection of the negative azimuthal spacecraft position vector in Solar Magnetic coords ; ; ;Slice Orientation ; The slice plane is oriented by using the following options to specify ; its x and y axes with respect to the coordinate system. ; ("BV," "BE", and "perp" will be invariant between coordinate systems). ; ; 'BV': The x axis is parallel to B field; the bulk velocity defines the x-y plane ; 'BE': The x axis is parallel to B field; the B x V(bulk) vector defines the x-y plane ; 'perp': The x axis is the bulk velocity projected onto the plane normal to the B field; y is B x V(bulk) ; 'xy': (default) The x axis is along the coordinate's x axis and y is along the coordinate's y axis ; 'xz': The x axis is along the coordinate's x axis and y is along the coordinate's z axis ; 'yz': The x axis is along the coordinate's y axis and y is along the coordinate's z axis ; 'xvel': The x axis is along the coordinate's x axis; the x-y plane is defined by the bulk velocity ; 'perp_xy': The coordinate's x & y axes are projected onto the plane normal to the B field ; 'perp_xz': The coordinate's x & z axes are projected onto the plane normal to the B field ; 'perp_yz': The coordinate's y & z axes are projected onto the plane normal to the B field ; ; ;OTHER: ; ; For more detailed/advanced usage see: ; thm_crib_part_slice2d_adv.pro ; thm_crib_part_slice2d_multi.pro ; ; ;NOTES: ; ; ;$LastChangedBy: nikos $ ;$LastChangedDate: 2016-11-30 11:48:57 -0800 (Wed, 30 Nov 2016) $ ;$LastChangedRevision: 22422 $ ;$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/examples/basic/thm_crib_part_slice2d.pro $ ; ;- compile_opt idl2 thm_init nl = ssl_newline() print, nl,'Starting basic 2D particle distribution slice crib.',nl ;-------------------------------------------------------------------------------------- ;Generate basic slice from ESA data ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;generate a 30 second slice starting at the beginning of the time range thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice ;plot the output thm_part_slice2d_plot, slice print, nl,'This example shows a basic slice of ESA burst data (ions) along the DSL xy plane.' print, 'The default method will produce a plot with visible bin boundaries.' print, 'The red line is the projection of the bulk velocity vector.',nl stop ;-------------------------------------------------------------------------------------- ;Generate basic slice using 2D interpolation ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;generate an identical cut using 2D interpolation thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ /two_d_interp thm_part_slice2d_plot, slice print, nl,'This is an identical cut produced using the 2D interplation method.' print, 'This method linearly interpolates all data within a specified range ' print, 'onto the slice plane (default is +-20 degrees)',nl stop ;-------------------------------------------------------------------------------------- ;Generate basic slice using 3D interpolation ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;generate an identical cut using 3D interpolation thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ /three_d_interp thm_part_slice2d_plot, slice print, nl,'Another identical cut using the 3D interpolation method,' print, 'Here the entire distribution is linearly interpolated in print, 'three dimensions and a slice is extracted.',nl stop ;-------------------------------------------------------------------------------------- ;Basic ESA background removal ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;Background removal is enabled by default with the options listed below. ;See thm_crib_esa_bgnd_remove for more info. ; bgnd_remove/esa_bgnd_remove: Flag to switch background removal on/off (set to 0 to disable) ; bgnd_type: Type of removal ('anode', 'omni', 'angle') ; bgnd_npoints: Number of points used to calculate background ; bgnd_scale: Factor to multiply calculated background by thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ /bgnd_remove, bgnd_type='anode', bgnd_npoints=3, bgnd_scale=1.0, $ /three_d_interp thm_part_slice2d_plot, slice print, nl,'Another identical cut using the 3D interpolation method.' print, 'Also, the ESA background removal is explicitly applied; ' print, 'you can change settings (or into "eflux" or "counts" as needed.' print, 'Here main point is: the entire distribution is linearly interpolated in print, 'three dimensions and a slice is extracted.',nl stop ;-------------------------------------------------------------------------------------- ;Smoothing ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;Increase the smoothing width to create smoother plots. ;The value supplied to the SMOOTH keyword is the width (in points) ;of the gaussian blur that is applied to the slice data. ;2D interpolate and 3D interpolation use smooth=3 by default. thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ smooth=15, /three_d_interp ;Add contour lines to the plot thm_part_slice2d_plot, slice print,nl,'Set the SMOOTH keyword to specify the width of the smoothing window.' print, '(in # of points). 2D interpolate and 3D interpolation use smooth=3 print, 'by default.',nl stop ;-------------------------------------------------------------------------------------- ;Units / Show N count level ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;This example uses the UNITS keyword to create a slice in counts. ; valid units are: 'df', 'flux', 'eflux', 'counts', and 'rate' thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice_counts, $ units='counts', /three_d_interp ;get default phase space density slice thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice_df, $ /two_d_interp ;plot counts slice thm_part_slice2d_plot, slice_counts, window=2 ;plot DF slice with contour line at 1 count thm_part_slice2d_plot, slice_df, window=1 spd_slice2d_add_line, slice_counts, 0.1 ;plot DF slice with dotted colored contour lines at 1, 5, and 10 count ; see IDL documentation for CONTOUR procedure for valid keywords thm_part_slice2d_plot, slice_df, window=0 spd_slice2d_add_line, slice_counts, [1,5,10], c_colors=[60,170,230], c_linestyle=1 print,nl,'Use the UNITS keyword to select what units the data will be presented in.' print,nl,'Use spd_slice2d_add_line to add annotation in different units' print, ' (e.g. "Counts", "DF", "Rate", "Flux", "EFlux")',nl stop ;-------------------------------------------------------------------------------------- ;Plot Against Energy ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;Setting the /ENERGY keyword will plot the data against energy instead of velocity. ;By default this will use radial log scaling, to use linear scaling use LOG=0. thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ /energy, /three_d_interp ;, log=0 thm_part_slice2d_plot, slice print,nl,'Use the ENERGY keyword to plot the data against energy instead of velocity.' print, 'Energy plots will use radial log scaling; use "log=0" for linear scaling.',nl stop ;-------------------------------------------------------------------------------------- ;Basic Orientation ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;This will produce a slice along the DSL xz plane. ;See the top of this crib for more options. thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ rotation='xz', /three_d_interp thm_part_slice2d_plot, slice print,nl,'This example cuts along the DSL xz plane instead of xy' print, 'See the documentation at the top of this crib for a full ' print, 'description of the available rotations.',nl stop ;-------------------------------------------------------------------------------------- ;Basic Field Aligned Orientation ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;Field aligned rotations require magnetic field data to be loaded beforehand. thm_load_fit, probe='b', datatype='fgs', coord='dsl', suff='_dsl', trange=trange ; could be FGL (averaged later) thm_load_esa, probe='b', datatype='peib_velocity_dsl', trange=trange ; load ground precomputed moments, can be other ;This example aligns the slice plane along the BV plane. ;The MAG_DATA keyword is used to specify a tplot variable containing magnetic field data. ;The VEL_DATA keyword is used to specify a tplot variable containing a bulk velocity vector. ; -bulk velocity is calculated from distribution if tplot variable is not specified ;These vectors will be averaged over the time range of the slice. thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ rotation='BV', mag_data='thb_fgs_dsl', vel_data='thb_peib_velocity_dsl', /three_d_interp thm_part_slice2d_plot, slice print, nl,'This example orients the slice along a plane defined by the magnetic' print, 'field and bulk velocity vectors. Orientations that use the magnetic ' print, 'field will require support data to be loaded first. Bulk velocity can ' print, 'be calculated automatically or loaded separately. See the documentation ' print, 'at the top of this crib for a list of valid inputs to the ROTATION keyword.',nl stop ;-------------------------------------------------------------------------------------- ;Basic Orientation and Coordinates ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;This example combines the COORD and ROTATION keywords. ;The COORD keyword specifies GSM coordinates and the ROTATION keyword specifies ;the slice plane's orientation with respect to those coordinates. ;The 'xvel' rotation aligns the slice's x axis with the (GSM) x axis and the ;slice's y axis is defined by the bulk velocity. thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ coord='gsm', rotation='xvel', /three_d_interp thm_part_slice2d_plot, slice print,nl,'This example plots a slice oriented along the GSM x axis and the ' print, 'bulk velocity vector. See the documentation at the top of this crib ' print, 'for a list of valid inputs to the COORD and ROTATION keywords.',nl stop ;-------------------------------------------------------------------------------------- ;Eclipse Corrections ;-------------------------------------------------------------------------------------- ;set time range trange = '2011-11-28/' + ['21:50','22:55'] ;Eclipse corrections are loaded when the raw data is loaded. ; use_eclipse_corrections = 0 No corrections are loaded (default). ; = 1 Load partial corrections (not recommended) ; = 2 Load full corrections. dist_corr = thm_part_dist_array(probe='b',type='peif', trange=trange, $ use_eclipse_corrections=2) ;load data without corrections for comparison dist_uncorr = thm_part_dist_array(probe='b',type='peif', trange=trange) ;create idential plots from each data set thm_part_slice2d, dist_corr, slice_time=trange[0], timewin=300, part_slice=slice_corr thm_part_slice2d, dist_uncorr, slice_time=trange[0], timewin=300, part_slice=slice_uncorr ;compare zrange = [1e-13,1e-7] thm_part_slice2d_plot, slice_corr, zrange=zrange, window=0, title='Corrected' thm_part_slice2d_plot, slice_uncorr, zrange=zrange, window=1, title='Uncorrected' print,nl,'This example demonstrates how to use spin corrections when the ' print, 'spacecraft is in the Earth''s shadow. Corrections are loaded with ' print, 'the raw particle data and applied when plot is generated.',nl stop ;-------------------------------------------------------------------------------------- ;Plotting options (standard) ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;generate slice thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ /three_d_interp ;Set tick numbers, character size, and range keywords. ;Keywords with an axis prefix can be set for all axes. ; (e.g. xticks/yticks/zticks) thm_part_slice2d_plot, slice, $ charsize = 1.5, $ ;set charcter size to 1.5 times the default xticks = 6, $ ;set number of major x ticks yminor = 2, $ ;set number of minor y ticks zrange = [1e-15,1e-9] ;specify the z axis range zprecision = 2 ;specify number of significant digits for ;tick annotations print,nl,'This example demonstrates the keywords that control some of the print, 'standard annotation options (character size, ticks, ranges, and print, 'numerical annotations)',nl stop ;-------------------------------------------------------------------------------------- ;Plotting options (miscellaneous) ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data ; -use /get_sun_direction keyword to load requisite ; data for plotting sun direction vector dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange, /get_sun) ;load B field data so it can be plotted on slice thm_load_fit, probe='b', datatype='fgs', coord='dsl', suff='_dsl', trange=trange ;generate slice thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ mag_data='thb_fgs_dsl', /three_d_interp ;Various keywords control other aspects of the plot. ; -/sundir requires that thm_part_dist_array is called with /get_sun_direction ; -/plotbfield requires that mag_data was specified to thm_part_slice2d ; -sun direction and B field vectors are scaled to the size of the plotting ; area, i.e. an in-plane vector will be drawn to the x/y maximum ; while an orthogonal vector will not appear thm_part_slice2d_plot, slice, $ olines = 0, $ ;do not plot contour lines plotbulk = 0, $ ;do not plot velocity vector plotaxes = 0, $ ;do not plot axis zeros ecircle = 1, $ ;plot instrument's energy limits sundir = 1, $ ;plot projection of sun direction plotbfield = 1 ;plot projection of B field print,nl,'This example demonstrates the keywords that control some of the print, 'non-standard annotations seen on slice plots (plotting of bulk print, 'velocity, sun direction, energy limits, and contour lines).',nl stop ;-------------------------------------------------------------------------------------- ;Plotting options (exporting) ;-------------------------------------------------------------------------------------- ;set time range trange = '2008-02-26/' + ['04:54','04:55'] ;esa ion burst data dist_arr = thm_part_dist_array(probe='b',type='peib', trange=trange) ;generate slice thm_part_slice2d, dist_arr, slice_time=trange[0], timewin=30, part_slice=slice, $ /three_d_interp ;The EXPORT keyword can be used to automatically produce .png or .eps ;images of the plot. Set export='filename' to write a .png file and ;add /EPS to use postscript output. thm_part_slice2d_plot, slice, export='slice_crib_plot' ;, /eps print,nl,'This example demostrates how to automatically export a plot ' print, 'to a png image or postscript file. This should create a ' print, '"slice_crib_plot.png" in your current home directory.',nl stop print, 'End of crib.' end