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

# projects/themis/spacecraft/particles/slices

- THM_PART_SLICE1D
- THM_PART_SLICE2D
- THM_PART_SLICE2D_PLOT
- THM_UI_SLICE2D
  Front end window allowing user to create and view "2D" slices

# Routine Descriptions

## THM_PART_SLICE1D

[Next Routine] [List of Routines]

    Procedure:
      thm_part_slice1d.pro

    Purpose:
      Produce line plots from 2D particle velocity slices along various orientations.

    Calling Sequence:
      thm_part_slice1d, slice, [,xcut=xcut | ,ycut=ycut | ,vcut=vcut | ,ecut=ecut ]
                               [,angle=angle] [,/overplot] [,data=data] [,window=window]

    Input:
         slice: slice structure from thm_part_slice2d
          xcut: value at which to align a linear cut along the x axis (vertical slice)
          ycut: value at which to align a linear cut along the y axis (horizontal slice)
                (defaults to ycut=0 if xcut, ycut, vcut, and ecut not set)
          vcut: value at which to align a radial cut (km/s)
          ecut: value at which to align a radial cut (eV)
         angle: value (degrees) to rotate a cut by (clockwise) if using xcut or ycut
      overplot: flag to add trace to the previous plot
        window: index of plotting window to be used

      *IDL graphics keywords may also be used; see IDL documentation for usage.
       (e.g. color, psym, linestyle)

    Output:
      data: set this keyword to a named variable to return a structure
            containing the data for the specified 1D slice

    Notes:
      See also: thm_crib_part_slice1d.pro

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-02-18 11:45:09 -0800 (Thu, 18 Feb 2016) $
    $LastChangedRevision: 20062 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/thm_part_slice1d.pro $

(See projects/themis/spacecraft/particles/slices/thm_part_slice1d.pro)

## THM_PART_SLICE2D

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d

    Purpose:
       Wrapper for using spd_slice2d to create particle distribution contours.
       This essentially performs all THEMIS-specific operations that occured
       in the original thm_part_slice2d and should be backward-compatible.

       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.pro.

       There are three methods for generating slices:

       Geometric:
         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. (default)

    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)

     GEOMETRIC: Flag to use geometric method (described above)
     TWO_D_INTERP: Flag to use 2D interpolation method (described above)
     THREE_D_INTERP: Flag to use 3D interpolation method (described above, the default)

     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: 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]

     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.

     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 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 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

     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

           project_name: name of project
           spacecraft: spacecraft designation
           data_name: string or string array containing the type(s) of distribution used
           n_samples: number of distributions averaged to create slice

           mass: partile 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=geo, 2=2D interp, 3=3D interp);
           energy: flag that x and y are energy instead of velocity
           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 bfiend 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 containting 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:
      A. Flores Based on work by Bryan Kerr and Arjun Raj, and Xuzhi Zhou

    EXAMPLES:
      See the crib file: thm_crib_part_slice2d.pro

    $LastChangedBy: nikos $
    $LastChangedDate: 2020-06-09 16:15:53 -0700 (Tue, 09 Jun 2020) $
    $LastChangedRevision: 28772 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/thm_part_slice2d.pro $

(See projects/themis/spacecraft/particles/slices/thm_part_slice2d.pro)

## THM_PART_SLICE2D_PLOT

[Previous Routine] [Next Routine] [List of Routines]

    Procedure:
      thm_part_slice2d_plot

    Purpose:
      Create plots for 2D particle slices.
      This routine calls the general spd_slice2d_plot routine.
      Use thm_part_slice2d_plot_old if calling thm_part_slice2d_old.

    Calling Sequence:
      thm_part_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)
      ZLOG: Boolean indicating logarithmic countour 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 thm_part_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)
      PLOTBFIELD: Boolean to plot projection of scaled B field (cyan line).
                  Requires B field data to be loaded and specified to
                  thm_part_slice2d with mag_data keyword.

      CLABELS: Boolean to annotate contour lines.
      CHARSIZE: Specifies character size of annotations (1 is normal)
      TITLE: String specifying the title of the plot.
      [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 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')
      [B,V,SUN]_COLOR: Specify the color of the corresponding support vector.
                       (e.g. "b_color=0", see IDL graphics documentation for options)

      WINDOW:  Index of plotting window to be used.
      PLOTSIZE: The size of the plot in device units (usually pixels)
                (Not implemented for postscript).

    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.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-03-24 16:48:06 -0700 (Thu, 24 Mar 2016) $
    $LastChangedRevision: 20586 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/thm_part_slice2d_plot.pro $

(See projects/themis/spacecraft/particles/slices/thm_part_slice2d_plot.pro)

## THM_UI_SLICE2D

[Previous Routine] [List of Routines]

    NAME:
      thm_ui_slice2d

    PURPOSE:
      Front end window allowing user to create and view "2D" slices
      of particle distributions.

    CALLING SEQUENCE:
      thm_ui_slice2d

    INPUT:
      gui_id: group leader widget if opening from SPEDAS GUI

    OUTPUT:
      N/A

    NOTES:
      This routine requires SPEDAS to run.

      For command line use see:
        thm_crib_part_slice2d.pro

    $LastChangedBy: jwl $
    $LastChangedDate: 2022-03-02 12:37:51 -0800 (Wed, 02 Mar 2022) $
    $LastChangedRevision: 30641 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/themis/spacecraft/particles/slices/thm_ui_slice2d.pro $

(See projects/themis/spacecraft/particles/slices/thm_ui_slice2d.pro)