This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
Function:
spd_slice2d
Purpose:
Return an interpolated 2D slice of 3D particle data for plotting.
Interpolation Methods:
3D Interpolation (default):
The entire 3-dimensional distribution is linearly interpolated onto a
regular 3d grid and a slice is extracted from the volume.
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.
Geometric:
Each point on the plot is given the value of the bin it intersects.
This allows bin boundaries to be drawn at high resolutions.
Calling Sequence:
slice = spd_slice2d( data [,data2 [,data3 [,data4]]] $
[,time=time [,window=window | samples=samples]]
[trange=trange] ... )
Example Usage:
slice = spd_slice2d(data, time=time) ;get slice from distribution closest to TIME
slice = spd_slice2d(data, time=time, samples=4) ;use average of the 4 samples nearest to TIME
slice = spd_slice2d(data, time=time, window=10) ;use average of all data within [TIME,TIME+10sec]
;add "/center_time" for [TIME-5sec,TIME+5sec]
slice = spd_slice2d(data, trange=trange) ;use average of all data within TRANGE
slice = spd_slice2d(data, time=time, /three_d_interp) ;use 3D interpolation (default)
slice = spd_slice2d(data, time=time, /two_d_interp) ;use 2D interpolation
slice = spd_slice2d(data, time=time, /geometric) ;use geometric interpolation
See crib sheets:
THEMIS: thm_crib_part_slice2d (called by thm_part_slice2d)
MMS: mms_slice2d_fpi_crib
mms_slice2d_hpca_crib
Arguments:
DATARR[#]: An array of pointers to 3D data structures.
See spd_dist_array.pro for more.
Basic Keywords:
TRANGE: Two-element time range over which data will be averaged. (string or double)
TIME: Time at which the slice will be computed. (string or double)
SAMPLES: Number of nearest samples to TIME to average. (int/double)
If neither SAMPLES nor WINDOW are specified then default=1.
WINDOW: Length in seconds from TIME over which data will be averaged. (int/double)
CENTER_TIME: Flag denoting that TIME should be midpoint for window instead of beginning.
SUM_SAMPLES: Flag denoting that the data should be summed over the requested trange rather than averaged
THREE_D_INTERP: Flag to use 3D interpolation method (described above)
TWO_D_INTERP: Flag to use 2D interpolation method (described above)
GEOMETRIC: Flag to use geometric interpolation method (described above)
Orientation Keywords:
CUSTOM_ROTATION: Applies a custom rotation matrix to the data. Input may be a
3x3 rotation matrix or a tplot variable containing matrices.
If the time window covers multiple matrices they will be averaged.
This is applied before other transformations
ROTATION: Aligns the data relative to the magnetic field and/or bulk velocity.
This is applied after the CUSTOM_ROTATION. (BV and BE are invariant
between coordinate systems)
Use MAG_DATA keyword to specify magnetic field vector.
Use VEL_DATA keyword to specify bulk velocity (optional).
'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 data's x axis and y is along the data's y axis
'xz': The x axis is along the data's x axis and y is along the data's z axis
'yz': The x axis is along the data's y axis and y is along the data's z axis
'xvel': The x axis is along the data'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 data's x & y axes are projected onto the plane normal to the B field
'perp_xz': The data's x & z axes are projected onto the plane normal to the B field
'perp_yz': The data'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
CUSTOM_ROTATION and ROTATION. Both keywords take
3-vectors as input. (See note below)
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 along the data's x-z plane:
ROTATION='xz'
Slice plane's x axis is GSM x and y is in the direction of the bulk velocity:
CUSTOM_ROTATION='my_gsm_tvar', ROTATION='xvel'
Slice is perpendicular to "tvar1" and x axis is defined by projection of "tvar2"
SLICE_NORM='tvar1', SLICE_X='tvar2'
NOTE: Update at 06/04/2018 - The SLICE_X & SLICE_NORM are defined after CUSTOM_ROTATION
but before the ROTATION.
DISPLACEMENT: Vector. New center of the coordinate system.
example:
Slice at the point x=0.5, y = 0.5 and z=0.1.
DISPLACEMENT = [0.5, 0.5. 0.1]
MAG_DATA: Name of tplot variable containing magnetic field data or 3-vector.
This will be used for slice plane alignment and must be in the
same coordinates as the particle data.
VEL_DATA: Name of tplot variable containing the bulk velocity data or 3-vector.
This will be used for slice plane alignment and must be in the
same coordinates as the particle data.
If not set the bulk velocity will be automatically calculated
from the distribution (when needed).
Other Keywords:
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 a smoothing window in #
of points. Smoothing is applied to the final plot using a gaussian
convolution. Even entries will be incremented, 0 and 1 are ignored.
ENERGY: Flag to plot data against energy (in eV) instead of velocity.
LOG: Flag to apply logarithmic scaling to the radial measure (i.e. energy/velocity).
(on by default if /ENERGY is set)
ERANGE: Two element array specifying the energy range to be used in eV.
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.
AVERAGE_ANGLE: (geometric interpolation only)
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 horizontal axis;
positive in the right handed direction. This will
average over all data within that range.
Note: for the default rotation='xy', the angle is measured from the XY
slice plane and about the x-axis
e.g. rotation='xy', average_angle=[-25,25] will average data within 25 degrees
of the XY slice plane about it's x-axis
or
rotation='yz', average_angle=[-25,25] will average data within 25 degrees
of the YZ slice plane about it's y-axis
SUM_ANGLE: (geometric interpolation only)
Two element array specifying an angle range over which
summing will be applied. The angle is measured
from the slice plane and about the slice's horizontal axis;
positive in the right handed direction. This will
sum over all data within that range.
Note: for the default rotation='xy', the angle is measured from the XY
slice plane and about the x-axis
e.g. rotation='xy', sum_angle=[-25,25] will sum data within 25 degrees
of the XY slice plane about it's x-axis
or
rotation='yz', sum_angle=[-25,25] will sum data within 25 degrees
of the YZ slice plane about it's y-axis
MSG_OBJ: Reference to dprint display object.
DETERM_TOLERANCE: tolerance of the determinant of the custom rotation matrix
(maximum acceptable difference from determ(C)=1 where C is the
user's custom rotation matrix); default is 1e-6
SUBTRACT_BULK: Subtract bulk velocity vector
PERP_SUBTRACT_BULK: Subtract the component of velocity perpendicular to the B field
Output:
Returns a structure to be passed to spd_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
project_name: name of project
spacecraft: spacecraft designation
data_name: string or string array containing the type(s) of distribution used
mass: particle mass in ev/(km/s)^2
units: the data's units
xyunits: the x & y axes' units
coord: placeholder for coordinate system label
rot: the applied rotation option
type: flag denoting interpolation type (0,2,3 for geometric, 2D, 3D respectively)
rlog: flag denoting radial log scaling
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
bulk: 3-vector containing the bulk velocity in the slice plane's coordinates
bfield: 3-vector containing the B-field in the slice plane's coordinates
sunvec: 3-vector containing the sun direction in the slice plane's coordinates
custom_matrix: The applied custom rotation matrix.
rotation_matrix: Rotation matrix from the the original or custom coordinates
to those defined by ROTATION.
orient_matrix: 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).
}
NOTES:
- Regions containing no data are assigned zeros instead of NaNs.
- Interpolation may occur across data gaps or areas with recorded zeroes
when using 3D interpolation (use geometric interpolation to see bins).
- The center/midpoint time of a distribution is used as it's timestamp
when determining it's inclusion in the requested time range. The full
time range of all included samples is stored in the metadata.
CREATED BY:
Aaron Flores, based on work by Bryan Kerr, Arjun Raj, and Xuzhi Zhou
$LastChangedBy: jimm $
$LastChangedDate: 2020-05-04 13:59:39 -0700 (Mon, 04 May 2020) $
$LastChangedRevision: 28665 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/science/spd_slice2d/spd_slice2d.pro $
(See general/science/spd_slice2d/spd_slice2d.pro)
Procedure:
spd_slice2d_plot
Purpose:
Create plots for 2D particle slices.
Calling Sequence:
spd_slice2d_plot, slice
Arguments:
SLICE: 2D array of values to plot
Plotting Keywords:
LEVELS: Number of color contour levels to plot (default is 60)
OLINES: Number of contour lines to plot (default is 0)
CONTOURS_OPLOT: Boolean indicating to only plot contours, not the data.
this is especially useful if you're interested in plotting
2-d or 3-d interpolated contours onto plots using geometric
interpolation; requires an already existing 2d slice plot
ZLOG: Boolean indicating logarithmic contour scaling (on by default)
ECIRCLE: Boolean to plot circle(s) designating min/max energy
from distribution (on by default)
SUNDIR: Boolean to plot the projection of scaled sun direction (black line).
Requires GET_SUN_DIRECTION set with spd_dist_array.
PLOTAXES: Boolean to plot x=0 and y=0 axes (on by default)
PLOTBULK: Boolean to plot projection of bulk velocity vector (red line).
(on by default)
PLOTORIGIN: Boolean to plot a new origin at the bulk velocity and/or sun location
instead of plotting the projection
PLOTBFIELD: Boolean to plot projection of scaled B field (cyan line).
Requires B field data to be loaded and specified to
spd_slice2d with mag_data keyword.
TITLE: String used as plot's title
SHORT_TITLE: Flag to only use time range and # of samples for title
CLABELS: Boolean to annotate contour lines.
CHARSIZE: Specifies character size of annotations (1 is normal)
[XYZ]RANGE: Two-element array specifying x/y/z axis range.
[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 integers.
[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')
[B,V,SUN]_COLOR: Specify the color of the corresponding support vector.
(e.g. "b_color=0", see IDL graphics documentation for options)
[B,V,SUN]_THICK: Specify the line thickness of the corresponding support vector
[B,V,SUN]_LINESTYLE: Specify the linestyle of the corresponding support vector
NOCOLORBAR: Suppress z axis color bar.
WINDOW: Index of plotting window to be used.
PLOTSIZE: The size of the plot in device units (usually pixels)
(Not implemented for postscript).
CUSTOM: Flag that to disable automatic window creation and allow
user-controlled plots.
BACKGROUND_COLOR_INDEX: Integer (0-255) specifying a custom background color
where data = 0.0
BACKGROUND_COLOR_RGB: 3D array of integers (0-255) representing RGB values
of the background color where data == 0.0; this keyword modifies the
current color table to include this color at index = 7
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:
Aaron Flores, based on work by Bryan Kerr and Arjun Raj
$LastChangedBy: egrimes $
$LastChangedDate: 2019-01-08 15:44:16 -0800 (Tue, 08 Jan 2019) $
$LastChangedRevision: 26442 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/general/science/spd_slice2d/spd_slice2d_plot.pro $
(See general/science/spd_slice2d/spd_slice2d_plot.pro)