This page was created by the IDL library routine `mk_html_help2`.

Last modified: Tue Aug 5 18:17:40 2025.

# Directory Listing of Routines

# general/science/spd_slice2d

- SPD_SLICE2D
- SPD_SLICE2D_PLOT

# Routine Descriptions

## SPD_SLICE2D

[Next Routine] [List of Routines]

    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: 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/spd_slice2d.pro $

(See general/science/spd_slice2d/spd_slice2d.pro)

## SPD_SLICE2D_PLOT

[Previous Routine] [List of Routines]

    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/trunk/general/science/spd_slice2d/spd_slice2d_plot.pro $

(See general/science/spd_slice2d/spd_slice2d_plot.pro)