This page was created by the IDL library routine
mk_html_help2.
Last modified: Tue May 7 11:36:21 2013.
Purpose:
Return an array of formatted annotation strings to be passed
to an IDL plotting procedure through the [xyz]tickname keyword.
Associated tick values are returned via keyword (2013-April)
Notes:
- This function should be called after the plot window has been initialized;
otherwise, the AXIS procedure will create an extra window.
- If the # of ticks is not specified it will be determined by IDL.
Input Keywords:
ticks: # of ticks requested by user (optional)
range: two element array specifying axis range
log: flag to denote logarithmic axis (optional)
Output:
tickname: String array of tick names
tickv: Array of tick values
ticks: Number of ticks - 1
(See themis/spacecraft/particles/slices/plot_part_slice2d.pro)
Procedure: plot_part_slice2d
Purpose: Create plots for 2D particle slices.
Calling Sequence:
plot_part_slice2d, slice
Arguments:
SLICE: 2D array of values to plot
Plotting Keywords:
RANGE: Two-element array specifying zaxis range (units vary)
[XY]RANGE: Two-element array specifying x/y axis range
LEVELS: Number of color contour levels to plot (default is 60)
OLINES: Number of contour lines to plot (default is 0)
PLOTSIZE: The size of the plot in device units (usually pixels)
(Not yet implemented for postscript).
LOGPLOT: Boolean indicating plot should be log-scaled (on by default)
SUNDIR: Boolean to plot sun direction vector (on by default)
ECIRCLE: Boolean to plot circle(s) designating min/max energy
from distribution (on by default)
PLOTAXES: Boolean to plot zero axes (on by default)
PLOTBULK: Boolean to plot projection of bulk velocity vector on the
slice plane (on by default)
CLABELS: Boolean to annotate contour lines.
CHARSIZE: Specifies character size of annotations (1 is normal)
[XYZ]TICKS: Integer(s) specifying the number of ticks for each axis
[XYZ]PRECISION: Integer specifying annotation precision (sig. figs.).
Set to zero to truncate printed values to inegers.
[XYZ]STYLE: Integer specifying annotation style:
Set to 0 (default) for style to be chosen automatically.
Set to 1 for decimal annotations only ('0.0123')
Set to 2 for scientific notation only ('1.23e-2')
Exporting keywords:
EXPORT: String designating the path and file name of the desired file.
The plot will be exported to a PNG image by default.
EPS: Boolean indicating that the plot should be exported to
encapsulated postscript.
Created by: A. Flores
Based on work by Bryan Kerr and Arjun Raj
(See themis/spacecraft/particles/slices/plot_part_slice2d.pro)
Procedure: thm_part_dist_vels
Purpose: Calculate bulk particle velocities from a structure array of particle
distrubutions and store in a tplot variable.
Arguments:
DIST_ARR: An array of data structures as returned by one of the get_th?_p???
routines (or THM_PART_DIST_ARRAY).
OUT_NAME: Name of tplot variable in which to store the velocities.
See Also: THM_PART_DIST_ARRAY, V_3D
Created by Bryan Kerr
(See themis/spacecraft/particles/slices/thm_part_dist_vels.pro)
Procedure: thm_part_slice2d
Purpose: Returns a 2-D slice of the 3-D THEMIS ESA/SST ion or electron distribution
function. The 2-D slice is returned via the PART_SLICE, XGRID, YGRID, and
SLICE_INFO keywords.
This procedure works in conjunction with thm_part_dist_array.pro and
plot_part_slice2d.pro. The corresponding crib is thm_crib_part_slice2d.pro
There are three methods for generating slices for plotting:
Geomtric:
Exact method showing the bounds of all bins intersecting the slice plane.
Values are averaged in cases of overlapping bins or when the slice plane
is coplanar with a bin's boundary.
2D Interpolation (from thm_esa_slice2d):
Datapoints within the specified theta or z-axis range are projected onto
the slice plane and linearly interpolated onto a regular 2d grid.
X,Y-range values determined slightly differently for 2D Interpolation
3D Interpolation:
The entire 3-dimensional distribution is linearly interpolated onto a
regular 3d grid and a this slice is extracted. The slice will consist of
up to resolution^2 datapoints from within 0.866/resolution of the total
velocity range along the normal. This method works best with dense data.
Note: - Not all points within the aforemention range will be used.
- Interpolation may occur across data gaps or areas with recorded zeroes
- Higher resolution regridding will severely slow this method
Callins Sequence:
thm_part_slice2d, datArr, [datArr2, [datArr3, [datArr4]]], $
timewin = timewin, slice_time=slice_time, $
part_slice=part_slice, $
fail=fail
Arguments:
DATARR[#]: An array of pointers to 3D data structures.
See thm_part_dist_array.pro for more.
Input 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.
COORD: A string designating what coordinate system the slice will be based off.
Default is 'DSL', but can also be 'GSE' or 'GSM'
ROTATION: The rotation keyword further specifies the coordinates system used
to create a slice. A description of each new set of cartesian coordinates
is given below. Some rotations are invariant of the coordinates
specified by COORD (BV,perp), other are not (xy,perp_xy). By default
the slice will be cut along the x-y plane of the given coordinates.
Field alligned coordinates (FAC) are also available.
See thm_fac_matrix_make for available options. Any valid input to
the OTHER_DIM keyword may be used (examples below).
Special Coordinates
'BV': The x axis is parallel to the B field; the bulk velocity defines the x-y plane.
'BE': The x axis is parallel to the B field; the B x V(bulk) vector defines the x-y plane.
'xy'/'xyz': (Default) The x axis is V_x and the y axis is V_y.
'xz': The x axis is V_x and the y axis is V_z.
'yz': The x axis is V_y and the y axis is V_z.
'xvel': The x axis is V_x; the y axis 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': Geometric xy coordinates projected onto the plane normal to the B field.
'perp_xz': Geometric xz coordinates projected onto the plane normal to the B field.
'perp_yz': Geometric yz coordinates projected onto the plane normal to the B field.
Field Alligned Coordinates
'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_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:
ROTATION='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.
TWO_D_INTERP: Flag to use 2D interpolation method (described above)
THREE_D_INTERP: Flag to use 3D interpolation method (described above)
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
UNITS: A string designating the desired units ('Counts','DF','Rate','CRate',
'Flux','EFlux','E2Flux','E3Flux')
Default = DF
COUNT_THRESHOLD: Mask out bins that fall below this number of counts BEFORE averaging.
(e.g. COUNT_THRESHOLD=1 masks bins with counts below 1)
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).
RESOLUTION: A single integer specfying the resolution of each dimension of the
slice (as well as the interpolated volume in the the 3d case).
Defaults: 2D Interpolation: 51
3D Interpolation: 150
Geometric: 500
ERANGE: Two element array specifying the energy range to be used
SMOOTH: An odd integer >=3 specifing the width of the smoothing window in #
of points. Even entries will be incrimented, 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 using the nearest neighbor method. For example
the default [64,32,64] will yield distributions with 63x32 points per
energy, and 64 energy bins). Increasing the regridding resolution will
slow slice production, particularly if using 3D interpolation.
Default = [64,32,64]
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 plot_part_slice2d.
{
data: two dimentional array (NxN) containing the datato be plotted (the slice)
xgrid: N dimentional array of x-axis values for plotting
ygrid: N dimentional array of y-axis values for plotting
probe: string containing the probe
dist: string (or array of) containing the type of distribution used
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: string describing the time window of the slice
range: array containing the range of the un-interpolated data
vrange: array containing the velocity range of the instrument(s)
trange: 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.
CREATED BY: A. Flores
Based on work by Bryan Kerr and Arjun Raj
EXAMPLES: see the crib file: thm_crib_part_slice2d.pro
(See themis/spacecraft/particles/slices/thm_part_slice2d.pro)
Name: thm_part_slice2d_2di.pro
Purpose: Helper function for thm_part_slice2d.pro
Produces slice using 2D linear interpolation
Note: This code is meant to preserve the functionality of
thm_esa_slice2d for the new set of slices routines.
(See themis/spacecraft/particles/slices/thm_part_slice2d_2di.pro)
Name: thm_part_slice2d_2di.pro
Purpose: Helper function for thm_part_slice2d.pro
Produces slice by interpolating the volume
in three dimensions then extracting a slice.
(See themis/spacecraft/particles/slices/thm_part_slice2d_3di.pro)
Name: thm_part_slice2d_geo.pro
Purpose: Helper function for thm_part_slice2d.pro
Produces slice using each bin's boundaries.
Arguments:
datapoints: N element array of data values
velocities: Nx3 element array of cartesian velocities
resolution: Single value (R) giving the number of points in each
dimension of the slice
dp: N element array of phi ranges
dt: N element array of theta ranges
dv: N element array of velocity ranges
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.
e.g. [-25,25] will average data within 25 degrees
of the slice plane about it's x-axis
Input Keywords:
ct: Rotation matrix from DSL -> desired coordinates
rot: Rotation matrix from given coordinates to specific rotation
(e.g. DSL, GSM -> BV, perp_xy)
mt: Rotation matrix from specified coords/rotation into
the slice plane's coordinates
Output Keywords:
xgrid: R element array of x-axis values for the slice
ygrid: R element array of y-axis values for the slice
part_slice: RxR element array containing the slice data
Other Keywords:
msg_obj: Object reference to GUI message bar. If included useful
console messages will also be output to GUI.
msg_prefix: String prefix to be printed with progress messages.
Caveats: This routine will slow as the number of bins (N) increases.
Averaging will significantly lengthen the require time.
(See themis/spacecraft/particles/slices/thm_part_slice2d_geo.pro)
Purpose: Checks for changes compatability between distributions and returns boolean. Arguments/Keywods: dist1/dist2: 3d data structures to be compared msg: string describing discrepancy
(See themis/spacecraft/particles/slices/thm_part_slice2d_getxyz.pro)
Purpose: Converts one count value to requested units and returns converted data array. Arguments: dat: 3d data structure to be used units: string describing new units
(See themis/spacecraft/particles/slices/thm_part_slice2d_getxyz.pro)
Purpose: Returns an array of gapless energy boundaries. The number of elements returned will always be N+1 for N energy levels. Notes: Energy levels are ordered differently between ESA/SST
(See themis/spacecraft/particles/slices/thm_part_slice2d_getxyz.pro)
Purpose: Converts spherical coordinates to cartesian Arguments: r: N element array of radial values (can be any dimensions) theta: N element array of theta values ( " ) phi: N element array of phi values ( " ) vec: Nx3 array of cartesian values in x,y,z order
(See themis/spacecraft/particles/slices/thm_part_slice2d_getxyz.pro)
Purpose:
Copy particle data into new array.
Calculate the center of all bins in cartesian coordinates.
Corresponding arrays for d-phi, d-theta, and d-v will be
calculated if requested.
Arguments/Keywords:
thedata: 3D data structure
grid_set: (bool) Flag to track whether the cartesian velocity
components have been set yet.
ncounts: New variable the particle data is copied to
velocities: Nx3 array of cartesian coordiantes for N bins
dp: N element array of bin width in phi
dt: N element array of bin width in theta
dv: N element array of bin width in velocity
(See themis/spacecraft/particles/slices/thm_part_slice2d_getxyz.pro)
Purpose:
Copy particle data into new array and calculate a new set of interpolated
data points in cartesian coordinates.
Angular data from each energy bin will be spherically interpolated using the
nearest neighbor. Energy bins are interpolated next, again with the nearest
neighbor. Finally, the cartesian coordinates for the new interpolated points
are returned.
Arguments/Keywords:
thedata: 3D data structure
grid_set: (bool) Flag to track whether the cartesian velocity
components have been set yet.
bins: Boolean array indicating which bins are OK to use
(invalid bins are zeroed so as to not be overwritten)
regrid: 3 Element array specifying the new number of points in
phi, theta, and energy respectively.
ncounts: New variable the particle data is copied to
velocities: Nx3 array of cartesian coordiantes for N bins
(See themis/spacecraft/particles/slices/thm_part_slice2d_getxyz.pro)
Name: thm_part_slice2d_getXYZ
Purpose: Helper function for thm_part_slice2d.pro
Converts data into the requested units and calculates cartesian
velocity bins based off the distributions energy and angle bins.
If regridding, then all data will first be interpolated onto a regular
grid in spherical coordinates.
If geometric method will be used then phi, theta, and enegery ranges
will also be returned via keywords.
Arguments:
datStructs: Array of 3d data structures
units: String descriping the units desired
type: Number specifying the type of slice that will be created
(see thm_part_slice2d)
Input Keywords:
count_threshold: Mask out bins with counts below the specified value.
If not already working in counts the value will
be converted to the specified units.
(after averaging -> before averaging - 2012-12-21)
(allow specified value - 2013-02-25)
regrid: 3 Element array specifying the new number of points desired in
phi, theta, and energy respectively.
erange: Two element array specifying min/max energies to be used
Output Keywords:
velocities: N x 3 array of velocity components (v_x, v_y, v_z) in km/s
corresponding to the center of each bin (except when regridding).
datapoints: N element array of datapoints
orange: Two element array; min/max of the data in specified units (with constraints applied)
vrange; Two element array; min/max velocities from the dist. (with constraints applied)
(for geometric only)
dp: N element array of bin width in phi
dt: N element array of bin width in theta
dv: N element array of bin width in velocity
(See themis/spacecraft/particles/slices/thm_part_slice2d_getxyz.pro)
Name: thm_part_slice2d_2di.pro
Purpose: Helper function for thm_part_slice2d.pro
Produces slice using nearest neighbor interpolation.
(See themis/spacecraft/particles/slices/thm_part_slice2d_nn.pro)
Procedure: thm_part_slice_extract
Purpose: Returns a 2-D slice of a scattered 3-D distribution along
the designated plane. Points near the slice plane are
projected onto the plane and then interpolated onto a regular
grid using the nearest neighbor method.
Arguments:
DATA: An array of N datapoints to be used.
VECTORS: An array of N x 3 datapoints designating, respectively,
the x,y,z values for each point in DATA
RESOLUTION: The number of points along each dimention of the
interpolated slice
Input Keywords:
CENTER: A vector designating the slice plane's center, default = [0,0,0]
NORMAL: A vector designating the slice plane's normal, default = [0,0,1]
XVEC: A vector whose projection into the slice plane will form its
x-axis. The data's x-axis is used by default, if no projection
exists an error will be returned
SLICE_WIDTH: The width of the slice given in % (of data range)
Output Keywords:
XGRID: Array of x-locations for the slice.
YGRID: Array of y-locations for the slice.
FAIL: This keyword will contain a message in the event of an error
(See themis/spacecraft/particles/slices/thm_part_slice_extract.pro)
NAME:
thm_ui_slice2d
PURPOSE:
Front end window allowing user to create and view "2D" slices
of velocity distributions.
CALLING SEQUENCE:
thm_ui_slice2d [, gui_ID=gui_ID [, historywin=historywin]]
INPUT:
gui_id: group leader widget if opening from THEMIS GUI
historywin: history window object if opening from THEMIS GUI
;
OUTPUT:
N/A
NOTES: For command line use see:
plot_part_slice2d.pro
thm_part_slice2d.pro
thm_part_dist_array.pro
(See themis/spacecraft/particles/slices/thm_ui_slice2d.pro)
NAME:
thm_ui_slice2d_bar__define.pro
PURPOSE:
Object created for the 2d slices interface. Allows scrolling back
and forth over a temporal series of slices.
CALLING SEQUENCE:
sb = obj_new('THM_UI_SLICE2D_BAR', parentID, xScreenSize, (windowStorage, loadedData, drawObject,) $
statusbar=statusbar, value = 500, range = [0,1000])
ATTRIBUTES:
id: slider widget's ID
parent: parent widget's ID
xsize: screen size, in pixels, of the slider bar
range: the numerical integer range about which the slider can move (in sec), [0,1000] by default
value: the current value of the slider, zero (fully left) in the absence of data
ok: flag indicating whether the slider should be sensitized
PUBLIC METHODS:
getValue: Allows retrieval of value, range, and xsize
setValue: Allows setting of value and xsize, mainly for the purpose of gui resize events
update: Update procedure to be called when:
-new plots have been generated (after setValue)
-there was an error (after setValue)
-events are processed (w/ EVENT keyword)
NOTES:
HISTORY:
Initial version: 4-02-10
Added title 3-5-12
(See themis/spacecraft/particles/slices/thm_ui_slice2d_bar__define.pro)