Procedure: thm_part_slice2d Purpose: Returns a 2-D slice of THEMIS ESA/SST particle distributions. This procedure works in conjunction with thm_part_dist_array.pro and thm_part_slice2d_plot.pro. See thm_crib_part_slice2d.pro for exaples. There are three methods for generating slices: 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. Notes: - Interpolation may occur across data gaps or areas with recorded zeroes - Higher resolution regridding will severely slow this method Calling Sequence: thm_part_slice2d, datArr, [datArr2, [datArr3, [datArr4]]], $ timewin = timewin, slice_time=slice_time, $ part_slice=part_slice Arguments: DATARR[#]: An array of pointers to 3D data structures. See thm_part_dist_array.pro for more. Keywords: SLICE_TIME: Beginning of time window in seconds since Jan. 1, 1970. If CENTER_TIME keyword set, then TIME is the center of the time widow specified by the TIMEWIN keyword. TIMEWIN: Length in seconds over which to compute the slice. CENTER_TIME: Flag that, when set, centers the time window around the time specified by SLICE_TIME keyword. UNITS: A string specifying the units to be used. ('counts', 'DF' (default), 'rate', 'crate', 'flux', 'eflux') ENERGY: Flag to plot data against energy (in eV) instead of velocity. LOG: Flag to apply logarithmic scaling to the radial mesure (i.e. energy/velocity). (on by default if /ENERGY is set) TWO_D_INTERP: Flag to use 2D interpolation method (described above) THREE_D_INTERP: Flag to use 3D interpolation method (described above) COORD: A string designating the coordinate system in which the slice will be oriented. Options are 'DSL', '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 ROTATION: The rotation keyword specifies the orientation of the slice plane within the given coordinates (BV and BE 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 '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': The x axis is the bulk velocity projected onto the plane normal to the B field; y is B x V(bulk) '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 SLICE_X/SLICE_NORM: These keywords respectively specify the slice plane's x-axis and normal within the coordinates specified by COORD and ROTATION. Both keywords take 3-vectors as input. If SLICE_X is not specified then the given coordinate's x-axis will be used. If SLICE_X is not perpendicular to the normal it's projection onto the slice plane will be used. An error will be thrown if no projection exists. If SLICE_NORM is not specified then the given coordinate's z-axis will be used (slice along by x-y plane in those coordinates). examples: Slice plane perpendicular to DSL z-axis using [3,2,0] as plane's x-axis: (this is the same as only using SLICE_X=[3,2,1]) COORD='dsl' (default), ROTATION='xyz' (default), SLICE_X=[3,2,1] Slice plane perp. to GSE x-axis, bulk velocity used to define plane's x-axis: COORD='gse', ROTATION='xvel', SLICE_NORM=[1,0,0], SLICE_X=[0,1,0] Slice plane along the B field and radial position vectors, B field used as slice's x-axis: COORD='rgeo', SLICE_NORM=[0,1,0], SLICE_X=[0,0,1] DISPLACEMENT: Value in m/s that specifies how far from the origin the slice plane will be cut. example: Slice plane cut at Z_gse = 500 COORD='gse', ROTATION='xyz' (default), DISPLACEMENT=500. AVERAGE_ANGLE: Two element array specifying an angle range over which averaging will be applied. The angle is measured from the slice plane and about the slice's x-axis; positive in the right handed direction. This will average over all data within that range. e.g. [-25,25] will average data within 25 degrees of the slice plane about it's x-axis VEL_DATA: Name of tplot variable containing the bulk velocity data. This will be used for slice plane alignment and subtraction. If not set the bulk velocity will be automatically calculated from the distribution (when needed). MAG_DATA: Name of tplot variable containing magnetic field data. This will be used for slice plane alignment. ERANGE: Two element array specifying the energy range to be used. COUNT_THRESHOLD: Mask bins that fall below this number of counts after averaging. (e.g. COUNT_THRESHOLD=1 masks bins with counts below 1) RESOLUTION: Integer specifying the resolution along each dimension of the slice (defaults: 2D/3D interpolation: 150, geometric: 500) SMOOTH: An odd integer >=3 specifying the width of the smoothing window in # of points. Even entries will be incremented, 0 and 1 are ignored. Smoothing is performed with a gaussian convolution. REGRID: (2D/3D Interpolation only) A three element array specifying regrid dimensions in phi, theta, and energy respectively. If set, all distributions' data will first be spherically interpolated to the requested reslotution using the nearest neighbor. The resolution in energy will only be interpolated to integer multiples of the original resolution (e.g. data with 16 energies will be interpolated to 32, 48, ...) THETARANGE: (2D interpolation only) Angle range, in degrees [-90,90], used to calculate slice. Default = [-20,20]; will override ZDIRRANGE. ZDIRRANGE: (2D interpolation only) Z-Axis range, in km/s, used to calculate slice. Ignored if called with THETARANGE. MSG_OBJ: Object reference to GUI message bar. If included useful console messages will also be output to GUI. Output: PART_SLICE: Structure to be passed to thm_part_slice2d_plot. { data: two dimensional array (NxN) containing the data to be plotted xgrid: N dimensional array of x-axis values for plotting ygrid: N dimensional array of y-axis values for plotting probe: string containing the probe dist: string or string array containing the type(s) of distribution used mass: assumed particle mass from original distributions coord: string describing the coordinate system used for the slice rot: string describing the user specified rotation (N/A for 2D interp) units: string describing the units twin: time window of the slice rlog: flag denoting radial log scaling ndists: number time samples included in slice type: flag denoting slice type (0=geo, 2=2D interp, 3=3D interp) zrange: two-element array containing the range of the un-interpolated data rrange: two-element array containing the radial range of the data trange: two-element array containing the numerical time range shift: 3-vector containing any translations made in addition to requested rotations (e.g. subtracted bulk velocity) bulk: 3-vector containing the bulk velocity in the slice plane's coordinates sunvec: 3-vector containing the sun direction in the slice plane's coordinates coord_m: Rotation matrix from original data's coordinates (DSL) to those specified by the COORD keyword. rot_m: Rotation matrix from the the specified coordinates to those defined by ROTATION. orient_m: Rotation matrix from the coordinates defined by ROTATION to the coordinates defined by SLICE_NORM and SLICE_X (column matrix of new coord's basis). } CAVEATS: Due to IDL software constraints regions containing no data are assigned zeros instead of NaNs. NOTES: In general this code makes the following assumptions about the particle data: - Look directions, energies, and assumed particle mass may vary between modes but not within a mode (this is checked within the code). - If assumed mass varies greatly between modes then the mass field in the output structure should be ignored. This will prevent 1D slice plots from being made with the output CREATED BY: A. Flores Based on work by Bryan Kerr and Arjun Raj EXAMPLES: see the crib file: thm_crib_part_slice2d.pro