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

Last modified: Wed Aug 27 18:18:06 2025.

# Directory Listing of Routines

# projects/SPP/fields/util

- PSP_FLD_PCLOSE
- PSP_FLD_POPEN
- PSP_FLD_TPLOT_ABC
- PSP_FLD_TPLOT_PDF
- PSP_FLD_TPLOT_TICKSOUT
- READ_XML8
  READ an XML document file into IDL (Interactive Data Language, ITT).
- SPP_FLD_MAKE_OR_RETRIEVE_CDF
- [1]
- SPP_FLD_STATUSPLOT
  Procedure used to display status bars on a TPLOT.
- STR_CLEAN
  To remove all unprintable characters from the given string
- XML2IDL8
  Translate a DOM (Document Object Model) object (read in

# Routine Descriptions

## PSP_FLD_PCLOSE

[Next Routine] [List of Routines]

     psp_fld_pclose

     :Purpose:
       Wrapper for the SPEDAS 'pclose' function, used to close the
       encapsulated PostScript file and convert it to PDF/PNG format. Used
       for creating plots in PSP/FIELDS SOC routines.

       This function requires the 'gs' command-line utility to be
       installed and accessible in the system's PATH for converting EPS
       to PDF, and the "pdftoppm" or "sips" utility for converting PDF to PNG/JPEG.
       The function currently only works on Linux and macOS systems due to
       the above dependencies.

     :Keywords:
       keep_eps: in, optional, boolean
         If true, keep the original EPS file after conversion. By default,
         the EPS file is deleted.
       png: in, optional, boolean
         If true, convert the EPS file to PNG format. By default,
         the PNG file is not created.
       round_eps: in, optional, boolean
         If true, edit the EPS file before conversion to use rounded
         line caps and joins. True by default.

     $LastChangedBy: pulupalap $
     $LastChangedDate: 2025-07-24 13:40:33 -0700 (Thu, 24 Jul 2025) $
     $LastChangedRevision: 33495 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/SPP/fields/util/psp_fld_pclose.pro $

(See projects/SPP/fields/util/psp_fld_pclose.pro)

## PSP_FLD_POPEN

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

     psp_fld_popen

     :Purpose:
       Wrapper for the SPEDAS 'popen' function, used to set default
       parameters used by PSP/FIELDS plot routines for encapsulated
       PostScript output.

       See the corresponding 'psp_fld_pclose' function for closing the plot
       and converting to PDF/PNG format.

     :Arguments:
       n: in, required, string
         The name of the PostScript file to open. Do not include
         the extension.

     :Keywords:
       _extra: in, optional, any
         Parameters to pass to the 'popen' function.
       thick: in, optional, any
         Line thickness for the plot. Line, axis, and text thickness are
         set to the same value.

     $LastChangedBy: pulupalap $
     $LastChangedDate: 2025-07-24 13:40:33 -0700 (Thu, 24 Jul 2025) $
     $LastChangedRevision: 33495 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/SPP/fields/util/psp_fld_popen.pro $

(See projects/SPP/fields/util/psp_fld_popen.pro)

## PSP_FLD_TPLOT_ABC

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

     $LastChangedBy: pulupalap $
     $LastChangedDate: 2025-07-24 16:40:58 -0700 (Thu, 24 Jul 2025) $
     $LastChangedRevision: 33496 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/SPP/fields/util/psp_fld_tplot_abc.pro $

(See projects/SPP/fields/util/psp_fld_tplot_abc.pro)

## PSP_FLD_TPLOT_PDF

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

     $LastChangedBy: pulupalap $
     $LastChangedDate: 2025-07-24 16:40:58 -0700 (Thu, 24 Jul 2025) $
     $LastChangedRevision: 33496 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/SPP/fields/util/psp_fld_tplot_pdf.pro $

(See projects/SPP/fields/util/psp_fld_tplot_pdf.pro)

## PSP_FLD_TPLOT_TICKSOUT

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

     psp_fld_tplot_ticksout

     Adjust xticklen and yticklen for tplot variables based on calculated
     aspect ratio for each plotted tplot variable.

     Default parameters are those used by the PSP/FIELDS plot routines.

     :Keywords:
       xmargin: bidirectional, optional, numeric
         Option to set tplot xmargin.
       ymargin: bidirectional, optional, numeric
         Option to set tplot ymargin.

     $LastChangedBy: pulupalap $
     $LastChangedDate: 2025-07-24 13:40:33 -0700 (Thu, 24 Jul 2025) $
     $LastChangedRevision: 33495 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/SPP/fields/util/psp_fld_tplot_ticksout.pro $

(See projects/SPP/fields/util/psp_fld_tplot_ticksout.pro)

## READ_XML8

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

     NAME:
    	READ_XML8

     PURPOSE:
    	READ an XML document file into IDL (Interactive Data Language, ITT).
    	This function is specifically for IDL version 8 and above because
    	it uses both OrderedHashes and Lists which were introduced in version 8.
    	Output is an IDL Ordered Hash with Lists for repeating elements.
    	This function reads the file and parses the XML document into a DOM
    	(Document Object Model) object or IDLffXMLDOMDocument.
    	It passes oDoc to XML2IDL8 which walks through the nodes creating the hash.

     CATEGORY:
    	Datafile handling; XML

     CALLING SEQUENCE:
    	Result = READ_XML8(filename, [ outFile=outFile, validation = validation ])

     INPUTS:
    	filename  - name of XML file to read (string)

     OUTPUTS:
    	Result is a hash of hashes or lists that represents the XML file.
    	One can access the various nodes
    	by indexing into it, like this:
    	IDL> print, hash[rootname,elname,childname,'_text']

    	If there are siblings with the same name, then they are pulled together
    	in a list which is indexed by number:

    	IDL> i++
    	IDL> print, hash[rootname,repeatedname,i,childname,'_text'];

    	To see what the childnames are for element elnameN:

    	IDL> print, hash[rootname,elname,...,elnameN].Keys()

     KEYWORDS:
    	outFile - If set to a filename, will save pretty printout to that file

    	validation - Turns on validation of xml file
    			The Schema or DTD need to on local disk.

     PROCEDURES USED:
    	XML2IDL8

     PACKAGE LOCATION:
    	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

     MODIFICATION HISTORY:
    	Written by Ed Shaya / U. of Maryland [Nov 5, 2013]
    	Removed path variable.  Now filename should contain path if needed. ES/Dec 3, 2013.
    	Switched to ordered hash so elements stay in order.  Now using
    	XML2IDL8.pro.  ES/Oct 10, 2014.
    	Removed use of prettyhash (toscreen) since IDL now does this
    	natively when you enter the hash name ES/Oct 10, 2014

(See projects/SPP/fields/util/read_xml8.pro)

## SPP_FLD_MAKE_OR_RETRIEVE_CDF

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

     This program is outdated, and in nearly every case it is simpler and easier
     to use 'spp_fld_load' (or, equivalently, 'psp_fld_load') instead.

     Kept around for backward compatibility with some old routines.

     $LastChangedBy: pulupalap $
     $LastChangedDate: 2024-11-12 10:43:29 -0800 (Tue, 12 Nov 2024) $
     $LastChangedRevision: 32943 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/SPP/fields/util/spp_fld_make_or_retrieve_cdf.pro $

(See projects/SPP/fields/util/spp_fld_make_or_retrieve_cdf.pro)

## SPP_FLD_STATUSPLOT

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

     NAME:
     	spp_fld_statusplot

     PROCEDURE:
     	spp_fld_statusplot, x, y, overplot = overplot, limits = lim, data = data

     INPUT:
     	x: array of x values.
    	  y: array of y strings.

     PURPOSE:
     	Procedure used to display status bars on a TPLOT.
       SPP_FLD_STATUSPLOT uses the SPECPLOT routine to plot a TPLOT variable
       that can take on one of several discrete STRING values.

     KEYWORDS:
    	DATA:		A structure containing the elements 'x' and 'y'.
    	LIMITS:		The limits structure for the TPLOT variable.
    	OVERPLOT:	If set, data is plotted over current plot.
    	STAT_VALS:	An array of strings containing possible
    			values for the 'y' variable.  If STAT_VALS is unset,
    			STATUSPLOT plots status bars for each unique
    			string contained in the 'y' variable.

     EXAMPLE:
    	If 'Channel' is a TPLOT variable with possible values of
    	'Ch1', 'Ch2', and 'Off', then the following commands
    	will set up statusplot.

    	options, 'Channel', 'tplot_routine', 'statusplot'
    	options, 'Channel', 'stat_vals', ['Off', 'Ch1', 'Ch2']
    	tplot, 'Channel'

     MOD HISTORY:
     	Original version, based on the STRPLOT procedure,
    	created 27 May 2009 by Marc Pulupa.

(See projects/SPP/fields/util/spp_fld_statusplot.pro)

## STR_CLEAN

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

     NAME:
    	STR_CLEAN

     PURPOSE:
    	To remove all unprintable characters from the given string

     CALLING SEQUENCE:
    	Result = STR_CLEAN (text, [/SPACE])

     INPUTS:
    	Text: Scalar string of characters to be cleaned

     OUTPUTS:
    	Result: Scalar string of characters removed of all unprintable characters

     OPTIONAL INPUTS:
    	SPACE: removes all unprintable characters including all space chars.

     EXAMPLE:
    	To remove all unprintable chars except space
    	IDL> word = STR_CLEAN ('the [tab]file is [lf][cr]')
    	IDL> print, word
    	the file is

    	To remove all unprintable chars including space
    	IDL> word = STR_CLEAN ('the [tab]file is [lf][cr]',/SPACE)
    	IDL> print, word
    	thefileis

     PACKAGE LOCATION:
    	http://www.astro.umd.edu/~eshaya/PDS/pds4readxml.tar

     MODIFICATION HISTORY:
    	Written by Puneet Khetarpal, January 15, 2003

(See projects/SPP/fields/util/str_clean.pro)

## XML2IDL8

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

     NAME:
    	XML2IDL8

     PURPOSE:
    	Translate a DOM (Document Object Model) object (read in
    	from an XML file with read_xml.pro) into either an IDL hash
    	by recursion through the document tree.	The '8' in the name
    	indicates this version is for IDL version 8.3 and above
    	as it uses ordered hashes and lists which were introduced to IDL in
    	version 8.3.  For the IDL hash, XML element names become
    	key names in the hash.  Elements with non-null text get a
    	'_text' key.  Comments are attached to parent elements with
    	'_comment' key.  Attributes are similarly treated with the
    	attribute name as the key.  They can be distinguished from
    	element text by the lack of a '_text' key.

    	All non-essential whitespace is removed.  IDL variable names are allowed
    	to have only the special characters '_','$', and '!', so all other
    	special characters are converted to '_'.

     CATEGORY:
    	Datafile handling; XML

     CALLING SEQUENCE:
    	myhash = XML2IDL8(oChild,nodeName=childName,nodeValue=childValue)

     INPUTS:
    	oNode -  DOM Document object (IDLffXMLDOMDocument) or top DOM Node
    		(IDLffXMLDOMNode) to convert to string array

     OUTPUTS:
    	Returns a hash of hashes or lists that represents the XML file.  One can access the various nodes
    	by indexing into it, like this:

    	IDL> print, hash[rootname,elName,childname,'_text']

    	If there are siblings with the same name, then they are pulled together in a list which
    	is indexed by number:

    	IDL> i++
    	IDL> print, hash[rootname,repeatedname,i,childname,'_text']

     KEYWORDS:
    	nodeName - returns nodeName of oNode

    	nodeVAlue - returns nodeValue of oNode
    	hash - If there are children elements, this returns a hash
    	holding information on them

     PROCEDURE:
    	A number of input parameters and keywords are used internally only.
    	They are used when the program walks through the document tree by
    	recursively calling itself.  These are: paramArr, nodeName,
    	and nodeValue

     MODIFICATION HISTORY:
    	Written by Ed Shaya / U. of Maryland [Nov 5, 2013]
    	Removed empty _text except for true empty elements ES [Dec 2013]

(See projects/SPP/fields/util/xml2idl8.pro)

## [1]

[Previous Routine] [List of Routines]

     NAME:

       SPP_FLD_RFS_FLOAT

     DESCRIPTION:

       The 64 bit values of onboard RFS spectra are compressed to
       16 bit floating point values for telemetry.  The specifications
       of the bits for exponent, mantissa, and sign (cross spectra only)
       as well as example calculations are in the documents

       SPF_FSW_908_RFS_Calcs.xlsx
       SPF_FSW_912_RFS_HFR_Verification.xlsx

       This program is an IDL version of the calculation which decompresses
       those values.

       Input can be integers (long or long longs also OK), a string
       with an integer value, a four character hex string (e.g. '2D73x'),
       or a sixteen bit binary string (e.g. '0010110101110011b').

       Input can be an array, but the input array has to all be the
       same type (e.g., all integers or all hex strings).

       Input must be within the range of 0 to 2^16 - 1.  Out of range
       inputs will return a value of -1.0D30.

       Output is an array of the same dimensions as the input,
       containing the double precision uncompressed RFS quantities.

       Typical compression errors are less than 0.1%.

     KEYWORDS:

       CROSS: Use the signed cross spectra calculation instead of the
         unsigned auto spectra calculation.

       VERBOSE: Show detailed output of the input in various formats,
         the sign, exponent, and mantissa.

       BIGINTS: If this keyword is set to a variable, then a list of
         IDL BigInteger values is returned.  The calculated values for the
         RFS floating point calculation can overflow a 64 bit integer, so if
         the exact (non-double-precision) values are necessary, they can
         be returned with this keyword.

         BigIntegers don't work with array-based operations, so use of this
         keyword will make the program run much more slowly.

         This keyword also only currently works with scalar or vector inputs.

       ZERO_FIX: Correct an error in which can assign a value of zero to
         telemetered compressed data. See details in comments below.

     EXAMPLES:

       A single value:

       IDL> print, spp_fld_rfs_float(11635, /verbose)
       IDL> print, spp_fld_rfs_float('0x2D73')

       Both should return an exponent of 11, a mantissa of 371, and
       a return of 1428480.

       Calculate all valid inputs for auto and cross product compressed values:

       IDL> rfs_comp = lindgen(2l^16)
       IDL> rfs_auto_decomp = spp_fld_rfs_float(rfs_comp, bigints = rfs_auto_big)
       IDL> rfs_cros_decomp = spp_fld_rfs_float(rfs_comp, bigints = rfs_cros_big, /cross)

       IDL> rfs_auto_decomp = spp_fld_rfs_float(rfs_comp)
       IDL> rfs_cros_decomp = spp_fld_rfs_float(rfs_comp, /cross)

       The calculations should produce the same result, but the ones without
       the bigints will be much faster.

       Plot results:

       IDL> plot, rfs_comp, rfs_auto_decomp, /ylog, yrange = [1.,1.e25], psym = 3
       IDL> oplot, rfs_comp, rfs_cros_decomp, psym = 3, col = 2
       IDL> oplot, rfs_comp, -rfs_cros_decomp, psym = 3, col = 6

       The plots should show the floating point variables which correspond
       to all valid 16 bit inputs.

     HISTORY:

       Initial version Spring 2016 by MPP
       Commented and cleaned up August 2016 by MPP

     $LastChangedBy: pulupalap $
     $LastChangedDate: 2023-08-17 21:12:53 -0700 (Thu, 17 Aug 2023) $
     $LastChangedRevision: 32025 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/projects/SPP/fields/util/spp_fld_rfs_float.pro $

(See projects/SPP/fields/util/spp_fld_rfs_float.pro)