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

Last modified: Mon Oct 20 03:17:44 2025.

# Directory Listing of Routines

# general/science/spd_part_products

- SPD_DIST_TO_HASH
- SPD_PART_COPY
- SPD_PGS_ALIGN_PHI
- SPD_PGS_CLIP_SPEC
- SPD_PGS_CONCAT_SPEC
- SPD_PGS_CONCAT_YAXIS
- SPD_PGS_DO_FAC
- SPD_PGS_EXPORT
  Exports SPEDAS particle data to ASCII files
- SPD_PGS_LIMIT_RANGE
- SPD_PGS_MAKE_E_SPEC
- SPD_PGS_MAKE_PHI_SPEC
- SPD_PGS_MAKE_THETA_SPEC
- SPD_PGS_MAKE_TPLOT
- SPD_PGS_MAP_AZIMUTH
- SPD_PGS_MOMENTS
- SPD_PGS_MOMENTS_TPLOT
- SPD_PGS_PROGRESS_UPDATE
- SPD_PGS_REGRID
- SPD_PGS_SHIFT_PHI_SPEC[1]
- SPD_PGS_SHIFT_PHI_SPEC[2]
- SPD_PGS_V_SHIFT

# Routine Descriptions

## SPD_DIST_TO_HASH

[Next Routine] [List of Routines]

    Procedure:
      spd_dist_to_hash

    Purpose:
      Convert standard 3D partical distribution structure into hash
      compatible with ISEE_3D

    Calling Sequence:
      hash = spd_dist_to_hash( dist [,counts=dist_counts]

    Input:
      dist:  Standard distribution structure array (pointer) in df units
      counts:  Optional copy of dist in counts

    Output:
      return value: A hash whose elements are each single distributions,
                    The keys are the sample time in millisecond precision.

    Notes:
      -Requires IDL 8.0+, 8.2+ recommended

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-05-23 18:52:50 -0700 (Mon, 23 May 2016) $
    $LastChangedRevision: 21180 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_dist_to_hash.pro $

(See general/science/spd_part_products/spd_dist_to_hash.pro)

## SPD_PART_COPY

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

    Procedure: spd_part_copy

    Purpose: Performs deep copy on particle data that is returned by thm_part_dist_array

    Arguments:  Old: A particle data structure to be copied
                New: A variable name to which the particle data should be copied

    Keywords: error=error:  Set to named variable. Returns 0 if no error, nonzero otherwise.

    Usage: spd_part_copy,old,new

      $LastChangedBy: aaflores $
      $LastChangedDate: 2016-02-09 16:31:11 -0800 (Tue, 09 Feb 2016) $
      $LastChangedRevision: 19920 $
      $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_part_copy.pro $

(See general/science/spd_part_products/spd_part_copy.pro)

## SPD_PGS_ALIGN_PHI

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

    Procedure:
      spd_pgs_align_phi

    Purpose:
      Align phi bins with respect to energy in order to reduce
      fringing artifacts on field aligned spectrograms.

    Input:
      data: single sanitized data structure

    Output:
      -Phi values in DATA will be averaged across energy.
      -If the inter-energy phi difference is too large for an
       accurate average over energy then an error will be thrown.
       (Hopefully this will never happen, if it does a more
        sofisticated algorithm will be needed)

    Notes:
      -sigh

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-01-04 15:09:48 -0800 (Mon, 04 Jan 2016) $
    $LastChangedRevision: 19671 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_align_phi.pro $

(See general/science/spd_part_products/spd_pgs_align_phi.pro)

## SPD_PGS_CLIP_SPEC

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

    Procedure:
      spd_pgs_clip_spec

    Purpose:
      Place NaNs in areas of a spectrogram that are beyond
      the requested limits.

    Input:
      y: spectrogram y axis
      z: spectrogram data
      range: The initial range limit applied to the data along an axis
             where that axis now serves as the spectrogram's y axis.
             (e.g. phi=[0,180] for a phi spectrogram)

    Output:
      NaNs applied to out of range data in Z

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-01-04 15:09:48 -0800 (Mon, 04 Jan 2016) $
    $LastChangedRevision: 19671 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_clip_spec.pro $

(See general/science/spd_part_products/spd_pgs_clip_spec.pro)

## SPD_PGS_CONCAT_SPEC

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

    Procedure:
      spd_pgs_concat_spec

    Purpose:
      Concatenates spectrograms pieces from across a mode change

    Input:
      a: First spectrogram piece (in time)
      b: Second spectrogram piece (in time)

    Output:
      None, appends b to end of a; b will be undefined afterwards.

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-01-04 15:09:48 -0800 (Mon, 04 Jan 2016) $
    $LastChangedRevision: 19671 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_concat_spec.pro $

(See general/science/spd_part_products/spd_pgs_concat_spec.pro)

## SPD_PGS_CONCAT_YAXIS

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

    Procedure:
      spd_pgs_concat_yaxis

    Purpose:
      Concatenates different y axes as spectrogram is built across mode changes

    Input:
      y: Previous y axes, either single dimension or ny x ntimes
      yc: Y axis for current sample, single dimension
      ns: Number of samples before the current one in the spectrogram.
          (used when 1D y axis is converted to 2D axis)

    Output:
      -If y is 1D and yc==y then no variables are changed.
      -If y is 1D and yc!=y then y will become a two dimensional
       and yc will be appended
      -If y is 2D then yc will be appended.
      -If y and yc have different numbers of elements the smaller
       will be expanded and padded with NaNs

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-01-04 15:09:48 -0800 (Mon, 04 Jan 2016) $
    $LastChangedRevision: 19671 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_concat_yaxis.pro $

(See general/science/spd_part_products/spd_pgs_concat_yaxis.pro)

## SPD_PGS_DO_FAC

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

    Procedure:
      spd_pgs_do_fac

    Purpose:
      Applies field aligned coordinate transformation to input data

    Input:
      data: The struct to be rotated
      mat: The fac rotation matrix

    Output:
      output=output:  The struct of rotated data
      error=error: 1 indicates error occured, 0 indicates no error occured

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-03-10 11:44:24 -0800 (Fri, 10 Mar 2017) $
    $LastChangedRevision: 22938 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_do_fac.pro $

(See general/science/spd_part_products/spd_pgs_do_fac.pro)

## SPD_PGS_EXPORT

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

     PROCEDURE:
       spd_pgs_export

     PURPOSE:
       Exports SPEDAS particle data to ASCII files

     INPUT:
       data_in: standard SPEDAS particle data structure

     KEYWORDS:
      filename: output filename
      precise: increases precision to the maximum (microseconds)

    $LastChangedBy: egrimes $
    $LastChangedDate: 2019-04-10 07:20:38 -0700 (Wed, 10 Apr 2019) $
    $LastChangedRevision: 26982 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_export.pro $

(See general/science/spd_part_products/spd_pgs_export.pro)

## SPD_PGS_LIMIT_RANGE

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

    Procedure:
      spd_pgs_limits_range

    Purpose:
      Applies phi, theta, and energy limits to data structure(s) by
      turning off the corresponding bin flags.

    Input:
      data: single sanitized data structure
      phi: phi min/max (min>max allowed)
      theta: theta min/max
      energy: energy min/max

    Output:
      Turns off all bins that do not intersect the specified limits.

    Notes:

    $LastChangedBy: jimm $
    $LastChangedDate: 2019-07-16 13:07:25 -0700 (Tue, 16 Jul 2019) $
    $LastChangedRevision: 27461 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_limit_range.pro $

(See general/science/spd_part_products/spd_pgs_limit_range.pro)

## SPD_PGS_MAKE_E_SPEC

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

    Procedure:
      spd_pgs_make_e_spec

    Purpose:
      Builds energy spectrogram from simplified particle data structure.

    Input:
      data: single sanitized data structure

    Input/Output:
      spec: The spectrogram (ny x ntimes)
      yaxis: The y axis (ny OR ny x ntimes)

      -Each time this procedure runs it will concatenate the sample's data
       to the SPEC variable.
      -Both variables will be initialized if not set
      -The y axis will remain a single dimension until a change is detected
       in the data, at which point it will be expanded to two dimensions.

    Notes:

    $LastChangedBy: nikos $
    $LastChangedDate: 2017-02-21 18:05:49 -0800 (Tue, 21 Feb 2017) $
    $LastChangedRevision: 22843 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_make_e_spec.pro $

(See general/science/spd_part_products/spd_pgs_make_e_spec.pro)

## SPD_PGS_MAKE_PHI_SPEC

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

    Procedure:
      spd_pgs_make_phi_spec

    Purpose:
      Builds phi (longitudinal) spectrogram from simplified particle data structure.

    Input:
      data: single sanitized data structure

    Input/Output:
      spec: The spectrogram (ny x ntimes)
      yaxis: The y axis (ny OR ny x ntimes)
      resolution: (optional) Specify output resolution

      -Each time this procedure runs it will concatenate the sample's data
       to the SPEC variable.
      -Both variables will be initialized if not set
      -The y axis will remain a single dimension until a change is detected
       in the data, at which point it will be expanded to two dimensions.

    Notes:
      -Code for original value_locate() based version remains commented out
       below. It should produce identical spectrograms for regular phi grids.

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-04-20 16:08:59 -0700 (Tue, 20 Apr 2021) $
    $LastChangedRevision: 29895 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_make_phi_spec.pro $

(See general/science/spd_part_products/spd_pgs_make_phi_spec.pro)

## SPD_PGS_MAKE_THETA_SPEC

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

    Procedure:
      spd_pgs_make_theta_spec

    Purpose:
      Builds theta (latitudinal) spectrogram from simplified particle data structure.

    Input:
      data: single sanitized data structure

    Input/Output:
      spec: The spectrogram (ny x ntimes)
      yaxis: The y axis (ny OR ny x ntimes)
      resolution: (optional) Specify output resolution
      colatitude: Flag to specify that data is in colatitude

      -Each time this procedure runs it will concatenate the sample's data
       to the SPEC variable.
      -Both variables will be initialized if not set
      -The y axis will remain a single dimension until a change is detected
       in the data, at which point it will be expanded to two dimensions.

    Notes:
      -Resolution of output grid is determined by number of unique theta values
       for the first energy.

    History:
      2016-01-20: Changed algorithm to allow ungrouped theta values (~8% slower now)
      2016-09-23: Generalized to remove restrictions on data regularity

    $LastChangedBy: egrimes $
    $LastChangedDate: 2021-04-21 11:59:09 -0700 (Wed, 21 Apr 2021) $
    $LastChangedRevision: 29896 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_make_theta_spec.pro $

(See general/science/spd_part_products/spd_pgs_make_theta_spec.pro)

## SPD_PGS_MAKE_TPLOT

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

    Procedure:
      spd_pgs_make_tplot

    Purpose:
      Create tplot variable with standard spectrogram settings.

    Input:
      name: name of new tplot variable to create
      x: x axis (time)
      y: y axis
      z: z axis (data)
      _extra: Any other keywords used will be passed to tplot and
              set in the dlimits of the new variable.
              (e.g. ylog=1 to set logarithmic y axis)

    Output:
      Creates a tplot variable.
      tplotnames=tplotnames : Concatenates the name of the new variable onto tnames argument

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-01-04 16:08:31 -0800 (Mon, 04 Jan 2016) $
    $LastChangedRevision: 19675 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_make_tplot.pro $

(See general/science/spd_part_products/spd_pgs_make_tplot.pro)

## SPD_PGS_MAP_AZIMUTH

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

    Procedure:
      spd_pgs_map_azimuth

    Purpose:
      Map any range of azimuth values in [-inf,inf] to [0,360]

    Calling Sequence:
      new_angles = thm_pgs_map_azimuth(angles)

    Input:
      phi: Array of azimuth values in degrees

    Output:
      return value: Input values mapped to [0,360]

    Notes:

      -values of 360 will not be wrapped to zero
       (otherwise a [0,360] range is mapped to [0,0])

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-01-04 15:09:48 -0800 (Mon, 04 Jan 2016) $
    $LastChangedRevision: 19671 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_map_azimuth.pro $

(See general/science/spd_part_products/spd_pgs_map_azimuth.pro)

## SPD_PGS_MOMENTS

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

    Procedure:
      spd_pgs_moments

    Purpose:
      Calculates moments from a simplified particle data structure.

    Arguments:
      data: single sanitized data structure

    Input Keywords:
      get_error: Flag indicating that error esitmates (sigma) should be returned
      mag_data: Optional array containing magnetic field vectors for all time samples
      scpot_data: Optional array containing spacecraft potential data for all time samples
      index: Index into mag_data/scpot_data specifying which sample to use

    Output Keywords:
      moments: Structure output from moments_3d containing the data.
      sigma: Structure output from moments_3d containing error estimates.

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-02-26 18:33:58 -0800 (Fri, 26 Feb 2016) $
    $LastChangedRevision: 20235 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_moments.pro $

(See general/science/spd_part_products/spd_pgs_moments.pro)

## SPD_PGS_MOMENTS_TPLOT

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

    Procedure:
      spd_pgs_moments_tplot

    Purpose:
      Creates tplot variables from moments structures.  Originally developed for THEMIS, but can be used for other missions (e.g. MMS).

    Arguments:
      moments:  Array of moments structures returned from moments_3d

    Keywords:
      get_error: Flag indicating that the current moment structure
                 contains error estimates.
      no_mag: Flag to omit outputs associated with b field
      prefix: Tplot variable name prefix (e.g. 'tha_peif_')
      suffix: Tplot variable name suffix
      tplotnames: Array of tplot variable names created by the parent
                  routine.  Any tplot variables created in this routine
                  should have their names appended to this array.
      coords: Coordinate system to be used for non-FA moments that need coordinate metadata. Defaults to 'DSL'.
      use_mms_sdc_units: Flag to convert pressure values and units to nPa, and heat flux values and units to mW/m^2,
                  for compatibility with MMS SDC moments data.

    Notes:
      Much of this code was copied from thm_part_moments.pro

    $LastChangedBy: jwl $
    $LastChangedDate: 2025-07-12 19:14:21 -0700 (Sat, 12 Jul 2025) $
    $LastChangedRevision: 33459 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_moments_tplot.pro $

(See general/science/spd_part_products/spd_pgs_moments_tplot.pro)

## SPD_PGS_PROGRESS_UPDATE

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

    Procedure:
      spd_pgs_progress_update

    Purpose:
      Helper routine prints status message indicating completion percent

    Input:
      last_update_time: The last time an update was posted(you can just set this to an undefined variable name)
      current_sample: The current sample index
      total_samples: The total number of samples
      display_object=display_object(optional): dprint display object
      type_string=type_string(optional): set to specify a type in the output message

    Notes:

    $LastChangedBy: pcruce $
    $LastChangedDate: 2016-01-04 15:09:48 -0800 (Mon, 04 Jan 2016) $
    $LastChangedRevision: 19671 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_progress_update.pro $

(See general/science/spd_part_products/spd_pgs_progress_update.pro)

## SPD_PGS_REGRID

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

    Procedure:
      spd_pgs_regrid

    Purpose:
      Regrids rotated data to a new set of regularly gridded spherical interpolates

    Input:
      data: The struct to be regridded
      regrid_dimen: 2-element array specifying the requested number of phis & thetas in regridded output.

    Output:
      output=output:  The struct of regridded data
      error=error: 1 indicates error occured, 0 indicates no error occured

    $LastChangedBy: egrimes $
    $LastChangedDate: 2017-07-05 09:17:03 -0700 (Wed, 05 Jul 2017) $
    $LastChangedRevision: 23548 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_regrid.pro $

(See general/science/spd_part_products/spd_pgs_regrid.pro)

## SPD_PGS_SHIFT_PHI_SPEC[1]

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

    Purpose:
      The new y range may not align perfectly with the shifted
      data, causing a white bar at the top of the plot.  This
      routine copies the botton row onto the top to cover the
      white space.

      (requested fix, probably no good solution)

      ^ The other solution would be to snap the new y axis range
        to that of the reordered bins rather than plotting exactly
        what the user requested.

    Arguments:
      data: data structure from tplot, already shifted
      yrange: full range of y data from main routine

(See general/science/spd_part_products/spd_pgs_shift_phi_spec.pro)

## SPD_PGS_SHIFT_PHI_SPEC[2]

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

    Procedure:
      spd_pgs_shift_phi_spec

    Purpose:
      Shifts phi (longitudinal) spectrogram's y-axis to start at a different angle.

    Input:
      names: string or string array of tplot variable names (wildcards accepted)
      start_angle: value in degrees at which to start the plot (e.g. 90, 180)

    Output:
      None, alters input tplot variable(s).

    Notes:
      -Bins intersected by the start angle will be copied to the top (end)
       of the spectrogram to ensure that the portion of those bin that is <
       the start angle is still plotted.
      -This procedure assumes that the input variables' y axes are
       monotonic and that any NaNs are at the end of the arrays.
      -NaNs in the y axis are shifted along with valid numbers to
       ensure that missing data along the original spectrogram's
       edge is represented correctly.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-08-04 18:15:27 -0700 (Thu, 04 Aug 2016) $
    $LastChangedRevision: 21602 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_shift_phi_spec.pro $

(See general/science/spd_part_products/spd_pgs_shift_phi_spec.pro)

## SPD_PGS_V_SHIFT

[Previous Routine] [List of Routines]

    Procedure:
      spd_pgs_v_shift

    Purpose:
      Shift a single distribution strucure by a specified velocity vector

    Input:
      data:  Sanitized particle data structure to be operated on
      vector:  3-vector in km/s
      matrix:  (optional) rotation matrix to apply to vector before shift

    Output:
      error:  flag, 1 indicates error, 0 none

    Notes:
      -Particle velocities are assumed to be small enough
       to use classical calculation.

    $LastChangedBy: aaflores $
    $LastChangedDate: 2016-09-30 17:28:46 -0700 (Fri, 30 Sep 2016) $
    $LastChangedRevision: 21990 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_part_products/spd_pgs_v_shift.pro $

(See general/science/spd_part_products/spd_pgs_v_shift.pro)