This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
Important:
This is an incomplete helper function and is still in development.
Procedure:
thm_part_slice1d_mult
Purpose:
Produce line plots from particle velocity slices along various orientations.
Calling Sequence:
thm_part_slice1d, slice, [,x=x | ,y=y | ,v=v | ,e=e ] [,angle=angle] [,data=data]
Input:
slice: slice structure from thm_part_slice2d
x: values at which to align cut along the x axis (km/s)
y: values at which to align cut along the y axis (km/s)
(defaults to y=0 if x, y, v, e not set)
v: values at which to align a radial cut (km/s)
e: values at which to align a radial cut (eV)
angle: value (degrees) to rotate the cut by if using x or y
Graphis Keywords:
-Any IDL graphics keywords that are valid for the "plot" and "oplot" procedure
may also be used.
Output:
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
$LastChangedRevision: 20331 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_mult.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_mult.pro)
Procedure:
thm_part_slice1d_r
Purpose:
Return the set of points at which a radial cut will be interpolated
and corresponding plot labels.
Calling Sequence:
thm_part_slice1d_r, slice (vin=vin | ein=ein), xout=xout, yout=yout,
xaxis=xaxis, xtitle=xtitle
Input:
slice: 2D slice structure
vin: velocity (km/s) at which to create cut
ein: energy (eV) at which to create cut
Output:
xout: x coordinates of points to interpolate to
yout: y coordinates of points to interpolate to
xaxis: final plot's x axis (angle)
xtitle: title for final plot's x axis
error: flag, 1 if error 0 if not
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
$LastChangedRevision: 20331 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_r.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_r.pro)
Procedure:
thm_part_slice1d_xy
Purpose:
Return the set of points at which a linear cut will be interpolated
and corresponding plot labels.
Calling Sequence:
thm_part_slice1d_r, slice (xin=xin | yin=yin), xout=xout, yout=yout,
xaxis=xaxis, xtitle=xtitle
Input:
slice: 2D slice structure
xin: x value at which to create cut perpendicular to the x axis
yin: y value at which to create cut perpendicular to the y axis
Output:
xout: x coordinates of points to interpolate to
yout: y coordinates of points tointerpolate to
xaxis: final plot's x axis
xtitle: title for final plot's x axis
error: flag, 1 if error 0 if not
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
$LastChangedRevision: 20331 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_xy.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice1d_xy.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 projects/themis/spacecraft/particles/slices/core/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 projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_3di.pro)
Procedure: thm_part_slice2d_climit Purpose: Helper function for thm_part_slice2d_getxyz Input: dist: 3D particle data structure (UNSANITIZED) datatpoints: final averaged data array from thm_part_slice2d_getxyz units: string specifying units (e.g. 'eflux', 'df') subtract_counts: (float) subtract this many counts from all values count_threshold: (float) removed datapoints with less than this number of counts Output: none, modifies datapoints Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_climit.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_climit.pro)
Procedure: thm_part_slice2d_collate Purpose: Collate data aggregated as thm_part_slice2d_getdata loops over modes and times. Data aggregation continues until a a change in energy or angle bins occurs (mode chance or other) or aggregation completes. At those points this procedure is called to average the data, apply any necessary processing, concatenate data to output variables, and undefine the appropriate variables for the next loop. Input: data_t: summed data for all bins weight_t: summed weights for all bins rad_in: radial coords phi_in: phi coords theta_in: theta coords dr_in: radial bin widths dp_in: phi bin widths dt_in: theta bin widths Output: data_out: averaged data rad_out: radian coords phi_out: phi coords theta_out: theta corods dr_out: radian bin widths dp_out: phi bin widths dt_out: theta bin widths fail: string output message, set if error occurs Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_collate.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_collate.pro)
Procedure: thm_part_slice2d_cotrans Purpose: Helper function for thm_part_slice2d. Performs coordinate transformations from DSL to requested coordinates (COORD keyword to thm_part_slice2d). Input: probe: (string) spacecraft designation (e.g. 'a') coord: (string) target coordinates (e.g. 'gsm') trange: (double) two element time range for slice vectors: (float) N x 3 array of velocity vectors bfield: (float) magnetic field 3-vector vbulk: (float) bulk velocity 3-vector sunvec: (float) spacecraft-sun direction 3-vector Output: If 2d or 3d interpolation are being used then this will transform the velocity vectors and support vectors into the target coordinate system. The transformation matrix will be passed out via the MATRIX keyword. Notes: This assumes the transformation does not change substantially over the time range of the slice. $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_cotrans.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_cotrans.pro)
Procedure: thm_part_slice2d_ebounds Purpose: Returns an array of gapless energy boundaries. The number of elements returned will always be N+1 for N energy levels. Input: dist: 3D particle data structure Output: return value: Array of energy bin boundaries (# energy bins + 1) Notes: Energy levels are ordered differently between ESA/SST $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_ebounds.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_ebounds.pro)
Procedure: thm_part_slice2d_fac Purpose: Helper function for thm_part_slice2d. Retrieves transformation matrix into field alligned coordinate systems. Input: probe: (string) spacecraft designation (e.g. 'a') coord: (string) target coordinates (e.g. 'phigeo') trange: (double) two element time range for slice mag_data: (string) name of tplot variable containing magnetic field data vectors: (float) N x 3 array of velocity vectors bfield: (float) magnetic field 3-vector vbulk: (float) bulk velocity 3-vector sunvec: (float) spacecraft-sun direction 3-vector Output: If 2d or 3d interpolation are being used then this will transform the velocity vectors and support vectors into the target coordinate system. The transformation matrix will be passed out via the MATRIX keyword. Notes: This assumes the transformation does not change substantially over the time range of the slice. $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_fac.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_fac.pro)
Name: thm_part_slice2d_geo.pro
Purpose: Helper function for thm_part_slice2d.pro
Produces slice using each bin's boundaries.
Input:
data: N element array of data values
rad: N element array of radial values
phi: N element array of phi values
theta: N element array of theta values
dp: N element array of phi ranges
dt: N element array of theta ranges
dr: N element array of velocity ranges
resolution: Single value (R) giving the number of points in each
dimension of the slice
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
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:
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 projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_geo.pro)
Procedure:
thm_part_slice2d_getdata
Purpose:
Helper function for thm_part_slice2d.pro
Returns an array of averaged data along with the corresponding
bin centers and widths in spherical coordinates. This routine
will apply energy range constraints and count thresholds.
Input:
dist_array: Array of 3d data structures
units: String denoting data output units
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:
data: N element array containing averaged particle data
rad: N element array of bin centers along r (eV or km/s)
phi: N element array of bin centers along phi
theta: N element array of bin centers along theta
dr: N element array of bin widths along r (eV or km/s)
dp: N element array of bin widths along phi
dt: N element array of bin widths along theta
Notes:
2014-11-07 count threshold moved to main routine
2013-02-05 allow specific values for count threshold
2012-12-21 - 2013-07-02 count threshold applied before averaging
$LastChangedBy: aaflores $
$LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
$LastChangedRevision: 20331 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getdata.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getdata.pro)
Procedure: thm_part_slice2d_getmag Purpose: Helper function for thm_part_slice2d. Retrieves an average of the b-field vectors over the slice's time range either from the particle structures or a user specified tplot variable. Input: ds: (pointer) Pointer array to particle distribution structures. trange: (double) Two element time range. mag_data: (string) Name of tplot variable containing b-field data. Output: return value: (float) Average magnetic field vector or -1 on error. Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getmag.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getmag.pro)
Procedure: thm_part_slice2d_getsphere Purpose: Helper function for thm_part_slice2d_getdata Calculates the center and width of all bins in spherical coordinates. Input: dist: 3D data structure energy: flag to return energy as radial componenet instead of velocity Output: data: N element array containing interpolated particle data rad: N element array of bin centers along r (eV or km/s) phi: N element array of bin centers along phi theta: N element array of bin centers along theta dr: N element array of bin widths along r (eV or km/s) dp: N element array of bin widths along phi dt: N element array of bin widths along theta Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getsphere.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getsphere.pro)
Procedure: thm_part_slice2d_getsun Purpose: Helper function for thm_part_slice2d. Retrieves sun vectors for all distributions within the specified time range and averages them. Input: ds: (pointer) Pointer array to particle distribution structures. trange: (double) Two element time range for the slice. Output: Returns averaged sun vector (3-vector float) on success or 0 on failure. Notes: This assumes that the spacecraft-sun vector is roughly constant over the time range of the slice. $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getsun.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getsun.pro)
Procedure: thm_part_slice2d_getvel Purpose: Helper function for thm_part_slice2d. Retrieves an average of the bulk velocity vectors over the slice's time range either from the particle structures or a user specified tplot variable. Input: ds: (pointer) Pointer array to particle distribution structures. trange: (double) Two element time range. vel_data: (string) Name of tplot variable containing bulk velocity data (in km/s). Output: return value: (float) Average bulk velocity vector (m/s) or -1 on error. Notes: thm_esa_slice2d divides total flux over the time range by the total density; here the flux/density was previously calculated for each distribution and is now averaged. $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getvel.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_getvel.pro)
Procedure: thm_part_slice2d_intrange Purpose: Helper function for thm_part_slice2d. Retrieves the indices of all samples in the specified time range from a particle distribution pointer. Input: ds: (pointer) Single particle distribution pointer. trange: (double) Two element array specifying the slice's time range. Output: return value: indices of all sample within trange. n: number of samples Notes: Uses the center of each sample's time window. $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_intrange.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_intrange.pro)
Procedure: thm_part_slice2d_ncount Purpose: Helper function for thm_part_slice2d_getxyz Converts one count value to requested units and returns converted data array. Input: dat: 3d data structure to be used units: string describing new units Output: return value: array of data corresponding to the specified number of counts Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_ncount.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_ncount.pro)
Name: thm_part_slice2d_2di.pro
Purpose: Helper function for thm_part_slice2d.pro
Produces slice using nearest neighbor interpolation.
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_nn.pro)
Procedure:
thm_part_slice2d_old
Purpose:
**** Deprecated - Use THM_PART_SLICE2D ****
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_old.pro.
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
$LastChangedBy: aaflores $
$LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
$LastChangedRevision: 20331 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_old.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_old.pro)
Procedure: thm_part_slice2d_orientslice Purpose: Helper function for thm_part_slice2d. Performs transformation into user specified coordinates. This transformation is applied after the COORD and ROTATION transformation have been performed. Input: slice_z: (float) 3 vector specifying the slice's normal slice_x: (float) 3 vector to be projected into the slice plane vectors: (float) N x 3 array of velocity vectors bfield: (float) magnetic field 3-vector vbulk: (float) bulk velocity 3-vector sunvec: (float) spacecraft-sun direction 3-vector Output: If 2d or 3d interpolation are being used then this will transform the velocity vectors and support vectors into the target coordinate system. The transformation matrix will be passed out via the MATRIX keyword. Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_orientslice.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_orientslice.pro)
Procedure:
thm_part_slice2d_regridsphere
Purpose:
Helper function for thm_part_slice2d_getdata
Spherically interpolates a structure's data to a specified regular grid
and returns the center and width of all bins in spherical coordinates.
Input:
dist: 3D data structure
energy: flag to return radial componenets in eV instead of km/s
regrid: 3 Element array specifying the new number of points in
phi, theta, and energy respectively.
Output:
data: N element array containing interpolated particle data
bins: N element array of flags denoting datapoint validity
rad: N element array of bin centers along r (eV or km/s)
phi: N element array of bin centers along phi
theta: N element array of bin centers along theta
dr: N element array of bin widths along r (eV or km/s)
dp: N element array of bin widths along phi
dt: N element array of bin widths along theta
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $
$LastChangedRevision: 20331 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_regridsphere.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_regridsphere.pro)
Procedure: thm_part_slice2d_rlog Purpose: Apply radial log scaling to aggregated velocity/energy vectors. Input: r: N element array of radii dr: N element array of radial bin withds (full width) displacement: scalar denoting slice's offset of the origin along the normal Output: None, modifies input variables by tranforming into log space and normalizing along the range of the data. Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_rlog.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_rlog.pro)
Procedure: thm_part_slice2d_rotate Purpose: Helper function for thm_part_slice2d. Performs transformation from coordinates specified by COORD (thm_part_slice2d) to those specified by ROTATION (thm_part_slice2d). Input: probe: (string) spacecraft designation (e.g. 'a') coord: (string) target coordinates (e.g. 'phigeo') trange: (double) two element time range for slice vectors: (float) N x 3 array of velocity vectors bfield: (float) magnetic field 3-vector vbulk: (float) bulk velocity 3-vector sunvec: (float) spacecraft-sun direction 3-vector Output: If 2d or 3d interpolation are being used then this will transform the velocity vectors and support vectors into the target coordinate system. The transformation matrix will be passed out via the MATRIX keyword. Notes: This assumes the transformation does not change substantially over the time range of the slice. $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_rotate.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_rotate.pro)
Procedure: thm_part_slice2d_s2c Purpose: Helper function for thm_part_slice2d_getxyz Converts spherical coordinates to cartesian Input: 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 ( " ) Output: vec: Nx3 array of cartesian values in x,y,z order Notes: could probably just use sphere_to_cart? $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_s2c.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_s2c.pro)
Procedure: thm_part_slice2d_smooth Purpose: Helper function for thm_part_slice2d. Smooths the output data by applying a gaussian blur. Input: part_slice: (float) N x N array containing the slice data width: (int) width of smoothing window in points in both x and y Output: None, modifies part_slice. Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_smooth.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_smooth.pro)
Procedure: thm_part_slice2d_subtract Purpose: Helper function for thm_part_slice2d. Subtracts bulk velocity vector from velocity array. Input: vectors: (float) N x 3 array of particle vectors vbulk: (float) bulk velocity 3-vector vel_data: (string) name of tplot variable containing bulk velocity data Output: none, modifies vectors Notes: This shift should NOT be applied when using the geometric method. $LastChangedBy: aaflores $ $LastChangedDate: 2016-03-04 18:05:22 -0800 (Fri, 04 Mar 2016) $ $LastChangedRevision: 20331 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/tags/spedas_4_0/projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_subtract.pro $
(See projects/themis/spacecraft/particles/slices/core/thm_part_slice2d_subtract.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 projects/themis/spacecraft/particles/slices/core/thm_part_slice_extract.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 projects/themis/spacecraft/particles/slices/core/thm_ui_slice2d_bar__define.pro)