This page was created by the IDL library routine
mk_html_help2.
Last modified: Fri Jan 3 18:16:39 2025.
FUNCTION: spd_cal_rot(v1,v2) INPUT: v1: 3 component vector, v2: 3 component vector, PURPOSE: Returns a rotation matrix that rotates v1,v2 to the x-y plane v1 is rotated to the x-axis and v2 into the x-y plane NOTES: Function normally called by "add_df2d.pro" to rotate velocities into the plane of Vsw and B CREATED BY: J.McFadden LAST MODIFICATION: 95-9-13 J.McFadden 15-9-08 A.Flores - forked $LastChangedBy: aaflores $ $LastChangedDate: 2015-09-08 18:47:45 -0700 (Tue, 08 Sep 2015) $ $LastChangedRevision: 18734 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_cal_rot.pro $
(See general/science/spd_slice2d/core/spd_cal_rot.pro)
Procedure:
spd_part_vis
Purpose:
View data from 3D distribution structures in 3 dimensions.
This is primarily a diagnostic tool.
Calling Sequence:
spd_part_vis, input [,trange=trange] [,samples=samples]
[,time=time [,window=window [,/center_time]]
[/zeros]
Input:
input: Structure array or scalar pointer to structure array
samples: Specify # of distributions to plot (default=1)
trange: Plot distribution(s) within this time range
time: Plot distribution(s) closest to this time
window: Use a time range of this width (sec) from TIME
center_time: TIME is the center of the window instead of the start
zeros: Flag to plot zeros instead of nonzero data
Output:
fail: Returns message in case of error
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2015-12-09 18:11:14 -0800 (Wed, 09 Dec 2015) $
$LastChangedRevision: 19562 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_part_vis.pro $
(See general/science/spd_slice2d/core/spd_part_vis.pro)
PROCEDURE:
spd_slice1d_plot
PURPOSE:
Create 1D plot from a 2D particle slice; note that:
1) if the 'value' argument is a scalar, this provides
a cut through the distribution at the nearest point
in that direction
2) if the 'value' argument is an array, this sums over
the values between the min and max of the array
EXAMPLES:
MMS> spd_slice1d_plot, slice, 'x', 0.0, title='Vx at Vy=0'
or
MMS> spd_slice1d_plot, slice, 'x', [-1000, 1000], title='Vx at Vy=[-1000, 1000] (summed)'
see: projects/mms/examples/advanced/mms_slice2d_1d_plot_crib.pro for more examples
INPUT:
slice: slice returned by spd_slice2d
direction: axis to plot - 'x' or 'y'
value: if direction is 'x', this is the y-value to create a 1D plot at;
can also be a range of values, e.g., [-1000, 1000] to sum over
the y-values from -1000 to +1000
KEYWORDS:
accepts most keywords accepted by the PLOT procedure
NOTES:
work in progress! please send bugs/problems/complaints/etc to egrimes@igpp.ucla.edu
$LastChangedBy: egrimes $
$LastChangedDate: 2018-11-30 13:11:06 -0800 (Fri, 30 Nov 2018) $
$LastChangedRevision: 26211 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice1d_plot.pro $
(See general/science/spd_slice2d/core/spd_slice1d_plot.pro)
Procedure:
spd_slice2d_2di.pro
Purpose:
Helper function for spd_slice2d. Produces slice by interpolating projected data.
This code is meant to preserve the functionality of thm_esa_slice2d.
Input:
datapoints: N elements array of data values
xyz: Nx3 array of vectors
resolution: Resolution (R) in points of each dimension of the output
thetarange: Elevation range about the slice plane used to select points for interpolation
zdirrange: Linear range perpendicular to the slice plane used to select points
for interpolation (if thetarange is not specified).
Output:
slice_data: RxR array of interpolated data points
x/ygrid: R element array s of x and y axis values corresponding to slice_data
Notes
$LastChangedBy: egrimes $
$LastChangedDate: 2020-05-14 09:56:46 -0700 (Thu, 14 May 2020) $
$LastChangedRevision: 28690 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_2di.pro $
(See general/science/spd_slice2d/core/spd_slice2d_2di.pro)
Procedure:
spd_slice2d_3di.pro
Purpose:
Helper function for spd_slice2d. Produces slice by interpolating the
entire data set in three dimensions then extracting a plane of values
using the nearest neighbor.
Input:
datapoints: N elements array of data values
xyz: Nx3 array of vectors
resolution: Resolution (R) in points of each dimension of the output
Output:
slice_data: RxR array of interpolated data points
x/ygrid: R element array s of x and y axis values corresponding to slice_data
Notes
$LastChangedBy: adrozdov $
$LastChangedDate: 2018-05-21 12:46:11 -0700 (Mon, 21 May 2018) $
$LastChangedRevision: 25240 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_3di.pro $
(See general/science/spd_slice2d/core/spd_slice2d_3di.pro)
Procedure:
spd_slice2d_checkbins
Purpose:
Checks if two particle distribution structures have identical
energy, phi, theta, and mass values.
Input:
dist1: 3D particle data structure
dist2: 3D particle data structure
Output:
return value: (bool) 1 if all fields match or second input
is undefined, 0 otherwise
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2015-09-08 18:47:45 -0700 (Tue, 08 Sep 2015) $
$LastChangedRevision: 18734 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_checkbins.pro $
(See general/science/spd_slice2d/core/spd_slice2d_checkbins.pro)
Procedure: spd_slice2d_collate Purpose: Collate data aggregated as spd_slice2d_get_data loops over input Data aggregation continues until a change in energy or angle bins occurs (mode change or other) or aggregation completes. At those points this procedure is called to average the data, concatenate data to output variables, and clear 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: egrimes $ $LastChangedDate: 2018-03-26 12:33:55 -0700 (Mon, 26 Mar 2018) $ $LastChangedRevision: 24954 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_collate.pro $
(See general/science/spd_slice2d/core/spd_slice2d_collate.pro)
Procedure: spd_slice2d_const Purpose: Store constants in a single place for consistency $LastChangedBy: aaflores $ $LastChangedDate: 2015-09-08 18:47:45 -0700 (Tue, 08 Sep 2015) $ $LastChangedRevision: 18734 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_const.pro $
(See general/science/spd_slice2d/core/spd_slice2d_const.pro)
Procedure: spd_slice2d_custom_rotation Purpose: Retrieve a user-provided rotation matrix and apply to data as needed. Input: custom_rotation: 3x3 rotation matrix or name to tplot variable containing such matrix trange: time range of the slice, tplot vars will be averaged over this range determ_tolerance: acceptable tolerance for determ=1, defaults to 1e-6 Output: matrix: the transformation matrix Input/Output (transformed if present): vectors: array of particle 3 vectors bfield: b field vector vbulk: bulk velocity vector sunvec: sun position vector Notes: $LastChangedBy: jimm $ $LastChangedDate: 2020-05-04 13:37:27 -0700 (Mon, 04 May 2020) $ $LastChangedRevision: 28663 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_custom_rotation.pro $
(See general/science/spd_slice2d/core/spd_slice2d_custom_rotation.pro)
Name:
spd_slice2d_geo.pro
Purpose:
Helper function for spd_slice2d.pro
Produces slices showing each bin's boundaries by assigning
each bin's value to all points on the slice plane that
fall within that bin's boundaries.
This is essentially a hack to allow plotting of bin boundaries
with contour instead of creating a new plotting routine.
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
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 x-axis.
e.g. [-25,25] will sum data within 25 degrees
of the slice plane about it's x-axis
custom_matrix: Rotation matrix from native -> user specified coordinates
(applied first)
rotation_matrix: Rotation matrix from given coordinates to built in
rotated coordinates, e.g. GSM -> BV, perp_xy
(applied second)
slice_matrix: Rotation matrix from specified coords/rotation into
the slice plane's final coordinates as defined by
the user specified normal and x projection.
(applied last)
shift: Vector by which the slice should be shifted (e.g. bulk velocity subtraction).
The slice plane will be shifted by the z value and the x & y values will be
subtracted from the corresponding axes' grids (it should already be in 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
slice: RxR element array containing the slice data
Other Keywords:
msg_obj: dprint display object reference
msg_prefix: String prefix to be printed with progress messages.
Notes:
-This routine will slow as the number of bins (N) increases.
Averaging will significantly lengthen the required time.
$LastChangedBy: egrimes $
$LastChangedDate: 2018-04-12 13:51:19 -0700 (Thu, 12 Apr 2018) $
$LastChangedRevision: 25039 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_geo.pro $
(See general/science/spd_slice2d/core/spd_slice2d_geo.pro)
Procedure:
spd_slice2d_get_data
Purpose:
Helper function for spd_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
trange: Two element time range
erange: Two element array specifying min/max energies to be used
energy: flag to get energy instead of velocity bins for radial distances
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:
$LastChangedBy: egrimes $
$LastChangedDate: 2018-03-26 12:33:55 -0700 (Mon, 26 Mar 2018) $
$LastChangedRevision: 24954 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_get_data.pro $
(See general/science/spd_slice2d/core/spd_slice2d_get_data.pro)
Procedure: spd_slice2d_get_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 may be ordered differently between instruments $LastChangedBy: aaflores $ $LastChangedDate: 2015-10-02 20:01:21 -0700 (Fri, 02 Oct 2015) $ $LastChangedRevision: 18995 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_get_ebounds.pro $
(See general/science/spd_slice2d/core/spd_slice2d_get_ebounds.pro)
Procedure: spd_slice2d_get_sphere Purpose: Helper function for spd_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: 2015-10-02 20:01:21 -0700 (Fri, 02 Oct 2015) $ $LastChangedRevision: 18995 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_get_sphere.pro $
(See general/science/spd_slice2d/core/spd_slice2d_get_sphere.pro)
Procedure: spd_slice2d_intrange Purpose: Helper function for spd_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: 2015-09-08 18:47:45 -0700 (Tue, 08 Sep 2015) $ $LastChangedRevision: 18734 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_intrange.pro $
(See general/science/spd_slice2d/core/spd_slice2d_intrange.pro)
Procedure: spd_slice2d_nearest Purpose: Helper function for spd_slice2d. Get a time range that encompasses a specified number of samples closest to a specified time range. Input: ds: (pointer) Particle distribution pointer array. time: (double) Time near which to search samples: (int/long) Number of samples to use Output: return value: (double) two element time range Notes: Uses the center of each sample's time window to determine distance. $LastChangedBy: aaflores $ $LastChangedDate: 2015-12-02 19:04:33 -0800 (Wed, 02 Dec 2015) $ $LastChangedRevision: 19516 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_nearest.pro $
(See general/science/spd_slice2d/core/spd_slice2d_nearest.pro)
Procedure: spd_slice2d_orientslice Purpose: Helper function for spd_slice2d. Performs transformation into user specified coordinates. This transformation is applied after the CUSTOM_ROTATION 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. Input/Output (transformed if present): vectors: array of particle 3 vectors bfield: b field vector vbulk: bulk velocity vector sunvec: sun position vector Notes: $LastChangedBy: jimm $ $LastChangedDate: 2020-05-04 13:37:27 -0700 (Mon, 04 May 2020) $ $LastChangedRevision: 28663 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_orientslice.pro $
(See general/science/spd_slice2d/core/spd_slice2d_orientslice.pro)
Procedure: spd_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: 2015-09-08 18:47:45 -0700 (Tue, 08 Sep 2015) $ $LastChangedRevision: 18734 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_rlog.pro $
(See general/science/spd_slice2d/core/spd_slice2d_rlog.pro)
Procedure: spd_slice2d_rotate Purpose: Helper function for spd_slice2d. Performs transformation to coordinates specified by ROTATION option. This is done after the CUSTOM_ROTATION is applied. Input: 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: egrimes $ $LastChangedDate: 2022-03-08 13:25:16 -0800 (Tue, 08 Mar 2022) $ $LastChangedRevision: 30661 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_rotate.pro $
(See general/science/spd_slice2d/core/spd_slice2d_rotate.pro)
Procedure: spd_slice2d_s2c Purpose: Helper function for spd_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: 2015-09-08 18:47:45 -0700 (Tue, 08 Sep 2015) $ $LastChangedRevision: 18734 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_s2c.pro $
(See general/science/spd_slice2d/core/spd_slice2d_s2c.pro)
Procedure: spd_slice2d_smooth Purpose: Helper function for spd_slice2d. Smooths the output data by applying a gaussian blur. Input: 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 slice array. Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2015-09-08 18:47:45 -0700 (Tue, 08 Sep 2015) $ $LastChangedRevision: 18734 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_smooth.pro $
(See general/science/spd_slice2d/core/spd_slice2d_smooth.pro)
Procedure: spd_slice2d_subtract Purpose: Shift velocities by specified vector Calling Sequence: spd_slice2d_subtract, vectors=vectors, velocity=velocity, fail=fail Input: vectors: Nx3 array of vectors in km/s velocity: 3-vector to shift by in km/s Output: fail: contains error message if error occurs Notes: $LastChangedBy: aaflores $ $LastChangedDate: 2015-09-18 18:17:56 -0700 (Fri, 18 Sep 2015) $ $LastChangedRevision: 18847 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_subtract.pro $
(See general/science/spd_slice2d/core/spd_slice2d_subtract.pro)
Procedure: spd_slice2d_translate Purpose: Shift xyz by specified vector Calling Sequence: spd_slice2d_translate, vectors=vectors, translate=translate, fail=fail Input: vectors: Nx3 array translate: 3-vector to shift by Keyword: truncate: cut the data of the exeded domain Output: fail: contains error message if error occurs Notes: $LastChangedBy: adrozdov $ $LastChangedDate: 2018-05-21 12:46:11 -0700 (Mon, 21 May 2018) $ $LastChangedRevision: 25240 $ $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_slice2d_translate.pro $
(See general/science/spd_slice2d/core/spd_slice2d_translate.pro)
Name:
spd_tplot_average.pro
Purpose:
Returns the average value of a tplot variable over a specified time range.
Calling Sequence:
result = spd_tplot_average( tplot_var, trange [,interpolate=interpolate] )
Input:
tplot_var: String containing the name of valid tplot variable
trange: String or double specifying the time range
interpolate: Flag to attempt interpolation from data outside the specifed
range if none is found within. At least 20 min or half the
specified range will be checked past both time limits.
Output:
return value: averate of tplot variable's y component or NaN if unsuccessful
Example Usage:
trange = '2008-4-12/' + ['01:00','02:00']
bfield_ave = spd_tplot_average('bfield_data', trange)
Notes:
$LastChangedBy: aaflores $
$LastChangedDate: 2016-05-13 17:46:11 -0700 (Fri, 13 May 2016) $
$LastChangedRevision: 21085 $
$URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_slice2d/core/spd_tplot_average.pro $
(See general/science/spd_slice2d/core/spd_tplot_average.pro)