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

Last modified: Mon Jul 28 18:17:17 2025.

# Directory Listing of Routines

# general/science

- 3D_STRUCTURE
  Documentation for the 3d structure.
- ADD_BDIR
  Adds magnetic field direction [theta,phi] to a 3d structure
- C_3D
  Returns the sum of the counts in temp.data
- CAL_BSN2
  Function returns a structure that describes the interaction of a B-field
- CALC_OMEGA_FLT2
- CONV_UNITS
- CONVERT_PH_UNITS
  Converts the units of the data array of ph data structures.
- TRANSFORM_VELOCITY
- CONVERT_VFRAME
- DIAG_P
  Returns the temperature: [Tpara,Tperp,Tperp], T_total and
- EDIT3DBINS
- EDIT3DBINS_REFORM
- GET_3DT
  To generate time series data for "tplot"
- GET_BSN2
  Generates tplot structures for intersection of Bow Shock and s/c B-field line.
- GET_SYMM
- HEATFLUX
- J_3D
  Returns the flux, [Jx,Jy,Jz], 1/(cm^2-s)
- JE_3D
  Returns the energy flux, [Je_x,Je_y,Je_z], ergs/(cm^2-s)
- MAKE_3DMAP
  Returns a 3d map using the theta's and phi's of a 3d structure.
- MAT_DIAG
  Diagonalize a 3x3 symmetric matrix
- N_3D
  Returns the density, n, 1/cm^3
- OMNI3D
- P_3D
  Returns the pressure tensor, [Pxx,Pyy,Pzz,Pxy,Pxz,Pyz], eV/cm^3
- PAD
- PADPLOT
- PANGLE
  Computes pitch angle given two sets of theta and phi
- PLOT3D
  Draws a series of 3d color plots, one plot per energy step.
- PLOT3D_COM
- PLOT3D_NEW
  Draws a series of 3d color plots, one plot per energy step.
- PLOT3D_OPTIONS
- PLOT_MAP
- PRESTENS
- REFORM_3D_STRUCT
  If a 3-d data structure has fromat (nenergy, nphi, ntheta) reform into (nenergy, nbins)
- SLICE2D
  creates a 2-D slice of the 3-D distribution function
- ENLARGE_PERIODIC
- SMOOTH_PERIODIC
- SPD_UNITS_STRING
- SPEC3D
- SPHERE_TO_CART
- SUB3D
- SUM3D
- SUPERPO_HISTO
- SUPERPO_INTERPOL
- SYMM3D
- SYMMETRY_DIR
- T_3D
  Returns the temperature, [Tx,Ty,Tz,Tavg], eV
- UNITS
- V_3D
  Returns the velocity, [Vx,Vy,Vz], km/s
- VTH_3D
  Returns the thermal velocity, [Vthx,Vthy,Vthz,Vthavg], km/s
- XYZ_TO_POLAR

# Routine Descriptions

## 3D_STRUCTURE

[Next Routine] [List of Routines]

    NAME:
       3d_structure
    PURPOSE:
       Documentation for the 3d structure.
       This is NOT a procedure or a function. It is ONLY Documentation. don't
       try to run it!
       The 3d structure is the standard structure that contains all information
       necessary to do data analysis on a particle distribution function.
       The following is an example structure, not all of the tags are
       present for each mission, and some missions may have extra tags,
       please refer to each individual mission's documentation for
       the correct version. This example is from WIND 3dp data.:

    ** Structure <1b689b0>, 29 tags, length=35304, refs=1:
       PROJECT_NAME    STRING    'Wind 3D Plasma'
       DATA_NAME       STRING    'Eesa Low'
       UNITS_NAME      STRING    'Counts'           Current Units.
       TIME            DOUBLE       8.2313292e+08   Sample start. Secs since 1970
       END_TIME        DOUBLE       8.2313292e+08   Sample End. Secs since 1970.
       INTEG_T         DOUBLE           3.0000000   Integration Time.  Seconds.
       NBINS           INT             88           number of angle bins.
       NENERGY         INT             15           number of energy bins.
       MAP             INT       Array(32, 32)      bin map (req'd only for plot3d_new)
       DATA            FLOAT     Array(15, 88)      can be different units, see the appropriate "conv_unts" procedure
       ENERGY          FLOAT     Array(15, 88)      eV
       THETA           FLOAT     Array(15, 88)      degrees
       PHI             FLOAT     Array(15, 88)      degrees
       GEOM            FLOAT     Array(15, 88)      Req'd by convert_esa_units
       DENERGY         FLOAT     Array(15, 88)      eV
       DTHETA          FLOAT     Array(15, 88)      degrees
       DPHI            FLOAT     Array(15, 88)      degrees
       DOMEGA          FLOAT     Array(15, 88)      steradians, not alwas present
       EFF             FLOAT     Array(15, 88)      Req'd by convert_esa_units
       FEFF            FLOAT     Array(15, 88)      Req'd by convert_esa_units
       MASS            DOUBLE       5.6856593e-06   mass (energy in eV)/c(in km/sec)^2
       GEOMFACTOR      DOUBLE       0.00039375000   Req'd by convert_esa_units
       VALID           LONG                 1
       SPIN            LONG             17152       (Optional)
       UNITS_PROCEDURE STRING    'convert_esa_units'
       MAGF            FLOAT     Array(3)           (Optional magnetic field vec.)
       VSW             FLOAT     Array(3)           (Optional flow velocity vec.)
       SC_POT          FLOAT     1.71572            (Optional spacecaft potential)

    The following functions will return a 3d structure:

      For the WIND data set:            ("LOAD_3DP_DATA" must be called first.)
        "GET_EL", "GET_PL","GET_EH","GET_PH","GET_PLB","GET_PHB","GET_ELB",
        "GET_EHS","GET_SF","GET_SO","GET_SFB","GET_SOB"

      For the GIOTTO data set:
        "GET_GI"

      For the CLUSTER data set:
        In Progress....

      For the FAST data set:
        In Progress....

    Once the 3d structure is obtained then it can be displayed with the following
    routines:
        "SPEC3D", "PLOT3D", "CONT3D"

    The following routines are useful for manipulating the data:
        "CONV_UNITS", "CONVERT_VFRAME", "PAD"

(See general/science/3d_structure.pro)

## ADD_BDIR

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

    PROCEDURE:  add_bdir,dat,source
    PURPOSE:
        Adds magnetic field direction [theta,phi] to a 3d structure
        The new structure element will be a two element vector [theta,phi]
        with the tag name 'bdir'.
    INPUT:
        dat:   3D data structure        (i.e. from 'GET_EL')
        [source] : String index that points to magnetic field data.
    Notes:
        	Magnetic field data must be loaded first.
    	See 'GET_MFI'

(See general/science/add_bdir.pro)

## CALC_OMEGA_FLT2

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

     Calculate moment weighting factors
     Davin Larson, 2005

(See general/science/calc_omega_flt2.pro)

## CAL_BSN2

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

    FUNCTION:	cal_bsn2(sx,sy,sz,bx,by,bz,vmag,bow=bow)
    INPUT:
    	sx,sy,sz:	x, y, and z coodinates of spacecraft in GSE with
    			units of Re
    	bx,by,bz:	magnetic field direction
    OPTIONS:
    	bow:	structure containing {L,ecc,x0}
    		L:	standoff parameter with units of Re
    		ecc:	eccentricity of shock
    		x0:	focus location in Re

           hyperbolic bow shock, see JGR 1981, p.11401, Slavin Fig.7
           r = L/(1+ecc*cos(theta))
           1 = (x-x0-c)^2/a^2 - (y^2+z^2)/b^2
           default L = b^2/a = 23.5
                   ecc = c/a = 1.15
                   xoffset= 3
                   c = (a^2 + b^2)^.5 = L*e/(e^2-1) = 83.8
                   a = L/(e^2-1) = 72.87
                   b = L/(e^2-1)^.5 = 41.38
    PURPOSE:
    	Function returns a structure that describes the interaction of a B-field
    	with a hyperboloid bow shock model.
    	Returned structure elements include:
    		th_bn: the angle (in degrees) between shock normal and the
    			field line that passes through the spacecraft
    		l1: the distance along the field line to the shock
    		l2: the distance from a point that is missdist from the
    			spacecraft in x to the tangent point
    		d,m: the distance along x from the spacecraft to a point
    			where the B field line would be tangent to the
    			bow shock.  A postive d means that the field
    			line has already intersected the shock.  A positive
    			m indicates that the field line has not yet
    			intersected the shock.
    		intpos: position vector in GSE of point where field line
    			originating at spacecraft intersects bow shock
    	All distances are in Re.
    CREATED BY:
    	P. Schroeder
    LAST MODIFICATION:
           L. Winslow 9/15/00
    LAST MODIFICATION: %W% %E%

(See general/science/cal_bsn2.pro)

## CONVERT_PH_UNITS

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

    NAME:      convert_ph_units
    PURPOSE:
               Converts the units of the data array of ph data structures.
    CALLING SEQUENCE:      convert_ph_units,data,units
    INPUTS:    data:  a ph data structure returned by "get_ph1.pro" or "get_ph2.pro"
                      data.data is rescaled in the requested units, and
                      data.units is set to the name of the new units
               units: a string.  One of: 'COUNTS','RATE','EFLUX','FLUX','DF'

    KEYWORD PARAMETERS:
               DEADTIME: (double) specifies a deadtime: the interval during which
                         a channel plate detector is turned off to record an event.
                         data.deadtime defaults to 1e-6
    		      (and has precedence over deadtime)
    COMMON BLOCKS:   get_ph_com: contains one element: deadtime

    LAST MODIFICATION:     @(#)convert_ph_units.pro	1.1 97/04/21
    CREATED BY:            Frank Marcoline.  Patterened after other convert_*_units.pro procedures.

(See general/science/convert_ph_units.pro)

## CONVERT_VFRAME

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

    NAME:
    	convert_vframe

    FUNCTION:  convert_vframe ,  dat,  velocity
    PURPOSE:   Change velocity frames
    INPUT:
      dat: 3d data structure
      velocity: SW velocity vector  [VX,VY,VZ]
    OUTPUT:  3d data structure.  Data will be in a different coordinate frame.
        (data will also be in units of distrubution function.)
    KEYWORDS:
       ETHRESH:  Threshold energy for interpolation.
       BINS:     Angle bins to be used
       EVALUES:
       INTERPOLATE:  set to non-zero value to have the data evaluated
       (interpolated) at the original energy steps.

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)convert_vframe.pro	1.21 02/11/01

(See general/science/convert_vframe.pro)

## CONV_UNITS

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

    FUNCTION:	conv_units

    PURPOSE:	To convert from counts to any other unit which is supported.
    		This procedure is just a shell that calls whatever conversion
    		procedure is specified in data.units_procedure.
    		right now the only conversion procedures are
    		"convert_esa_units" and
    		"convert_sst_units"
    INPUT:
    	data:	A 3d data structure such as those generated by get_el, get_eh,
    		get_pl,get_ph,etc.
    		e.g. "get_el"
    	units:	The units you wish to convert to, such as eflux,flux,df,ncounts,
    		rate,nrate.
    KEYWORDS:
    	scale:	a dummy keyword, returns the scale used to convert.

    CREATED BY:	Davin Larson
    LAST MODIFICATION: 	@(#)conv_units.pro	1.8 95/11/07

(See general/science/conv_units.pro)

## C_3D

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

    FUNCTION:	c_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
    INPUT:
    	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
    KEYWORDS
    	ENERGY:	fltarr(2),	optional, min,max energy range for integration
    	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
    	EBINS:	bytarr(na),	optional, energy bins array for integration
    					0,1=exclude,include,
    					na = dat.nenergy
    	ANGLE:	fltarr(2,2),	optional, angle range for integration
    				theta min,max (0,0),(1,0) -90<theta<90
    				phi   min,max (0,1),(1,1)   0<phi<360
    	ARANGE:	fltarr(2),	optional, min,max angle bin numbers for integration
    	BINS:	bytarr(nb),	optional, angle bins array for integration
    					0,1=exclude,include,
    					nb = dat.ntheta
    	BINS:	bytarr(na,nb),	optional, energy/angle bins array for integration
    					0,1=exclude,include
    PURPOSE:
    	Returns the sum of the counts in temp.data
    NOTES:
    	Function normally called by "get_3dt" to generate
    	time series data for "tplot".

    CREATED BY:
    	J.McFadden	95-7-27
    LAST MODIFICATION:
    	96-7-6		J.McFadden

(See general/science/c_3d.pro)

## DIAG_P

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

    Procedure:	diag_p, p, n, t=t, s=s
    INPUT:
    	p:	pressure array of n by 6 or a string (e.g., 'p_3d_el')
    	n:	density array of n or a string (e.g., 'n_3d_el')
    PURPOSE:
    	Returns the temperature: [Tpara,Tperp,Tperp], T_total and
    		the unit symmetry axis s. Also returns 'T_diag' and 'S.axis'
    		for plotting purposes.

    CREATED BY:
    	Tai Phan	95-09-28
    LAST MODIFICATION:
    	2015-09-09		Tai Phan

(See general/science/diag_p.pro)

## EDIT3DBINS

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

    PROCEDURE:  edit3dbins,dat,bins
    PURPOSE:   Interactive procedure to produce a bin array for selectively
        turning angle bins on and off.  Works on a 3d structure (see
        "3D_STRUCTURE" for more info)

    INPUT:
       dat:  3d data structure.  (will not be altered)
       bins:  a named variable in which to return the results.
    KEYWORDS:
       EBINS:     Specifies energy bins to plot.
       SUM_EBINS: Specifies how many bins to sum, starting with EBINS.  If
                  SUM_EBINS is a scalar, that number of bins is summed for
                  each bin in EBINS.  If SUM_EBINS is an array, then each
                  array element will hold the number of bins to sum starting
                  at each bin in EBINS.  In the array case, EBINS and SUM_EBINS
                  must have the same number of elements.
    SEE ALSO:  "PLOT3D_NEW" and "PLOT3D_OPTIONS"
    CREATED BY:	Davin Larson
    FILE: edit3dbins.pro
    VERSION:  1.14
    LAST MODIFICATION: 98/01/16

(See general/science/edit3dbins.pro)

## EDIT3DBINS_REFORM

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

    PROCEDURE:  edit3dbins_reform,dat,bins
    PURPOSE:   wrapper for edit3dbins, Interactive procedure to produce a
    bin array for selectively turning angle bins on and off.  Works on a
    3d structure with phi, theta dimensioned separately, so that the data
    array in the structure is (nenergy, nphi, ntheta), rather than
    (nenergy, nbins) as in the typical 3d data structure.
    INPUT:
       dat:  3d data structure.  (will not be altered, bin flags are not set)
       bins:  a named variable in which to return the results, dimensions
              (nphi, ntheta), not (nbins)
    KEYWORDS:
       NTHETA: number of theta bins, if not set, obtain from
               the data structure
       NPHI: number of phi bins, if not set, obtain from
               the data structure
       Note that if ntheta*nphi is not equal to data.nbins, then
       edit3dbins is called directly. This may resuly in unpredictable results.
       EBINS:     Specifies energy bins to plot.
       SUM_EBINS: Specifies how many bins to sum, starting with EBINS.  If
                  SUM_EBINS is a scalar, that number of bins is summed for
                  each bin in EBINS.  If SUM_EBINS is an array, then each
                  array element will hold the number of bins to sum starting
                  at each bin in EBINS.  In the array case, EBINS and SUM_EBINS
                  must have the same number of elements.
     $LastChangedBy: $
     $LastChangedDate: $
     $LastChangedRevision: $
     $URL: $

(See general/science/edit3dbins_reform.pro)

## ENLARGE_PERIODIC

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

    NAME:
    	enlarge_periodic
    FUNCTION:   enlarge_periodic
    INPUT:   image   (On the surface of a sphere)
    PURPOSE: enlarges a 2 dimensional matrix by n elements on each side
       It assumes the array has spherical boundary conditions.
    OUTPUT:  enlarged image array
    NOTES:   Called from function: 'SMOOTH_PERIODIC'

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)smooth_periodic.pro	1.5 95/10/04

(See general/science/smooth_periodic.pro)

## GET_3DT

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

    PROGRAM:	get_3dt(funct,get_dat,ERANGE=erange,BINS=bins,NAME=name)
    INPUT:
    	funct:	function,	function that operates on structures generated
    					by get_pl, get_el, etc.
    				e.g. "get_el"

    				funct   = 'n_3d','j_3d','v_3d','p_3d','t_3d',
    					  'vth_3d', or 'c_3d'
    				"n_3d"
    				"j_3d"
    				"v_3d"
    				"p_3d"
    				"t_3d"
    				"vth_3d"
    				"c_3d"
    	get_dat:function,	function that returns 3d data structures
    				function name must be "get_"+"get_dat"
    				get_dat = 'pl' for get_pl,
    				get_dat = 'el' for get_el, etc.
    KEYWORDS:
    	erange:	fltarr(2),	optional, min,max energy bin numbers for integration
    	bins:	bytarr(nbins),	optional, angle bins for integration, see edit3dbins.pro
    				0,1=exclude,include,  nbins = temp.nbins
    	name:	string		New name of the Data Quantity
    				Default: funct+'_'+get_dat
           times:  dblarr(1or2)or  Specifies start time (and end time)
                   strarr(1or2)
           index:  lonarr(1 or 2)  Specifies starting index (and ending index)
                                   keyword time overrides keyword index
    PURPOSE:
    	To generate time series data for "tplot"
    NOTES:
    	Program names time series data to funct+"_"+get_dat.
    		See "tplot_names".

    CREATED BY:    J.McFadden
    LAST MODIFICATION:  01/05/09
    FILE:   @(#)get_3dt.pro	1.13

(See general/science/get_3dt.pro)

## GET_BSN2

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

    PROGRAM:	get_bsn2,PNAME=pname,BNAME=bname,VNAME=vname,BOW=bow,
    			intpos=intpos

    INPUT OPTIONS
    	pname:	string,		Name of orbital position structure
    				Default is 'wi_pos'
    	bname:	string,		Name of magnetic field structure
    				Default is 'wi_B3'
    	vname:  string,		Name of solar wind velocity structure
    				Default is 'wi_pm_Vp'
    	bow:	structure	Bow Shock parameters
    				Default bow={standoff:23.5,eccentricity:1.15,x_offset:3.0}
    PURPOSE:
    	Generates tplot structures for intersection of Bow Shock and s/c B-field line.
    	Generates the following structures:
                   th_bn: the angle (in degrees) between shock normal and the
                           field line that passes through the spacecraft
                   l1: the distance along the field line to the shock
                   l2: the distance from a point that is missdist from the
                           spacecraft in x to the tangent point
                   d,m: the distance along x from the spacecraft to a point
                           where the B field line would be tangent to the
                           bow shock.  A positive d means that the field
                           line has already intersected the shock.  A positive
    			m indicates that the field line has not yet intersected
                           the shock.
           All distances are in Re. l1 and l2 are negative if the field line is
    	anti-parallel to the vector connecting the spacecraft and the point
    	of field line intersection.
    OPTIONAL OUTPUT:
    	intpos:	array of position vectors giving points where bow shock
    		intersects B field line that passes through spacecraft
    CREATED BY:
    	P.Schroeder
    LAST MODIFICATION:
    	@(#)get_bsn2.pro	1.5 02/04/17

(See general/science/get_bsn2.pro)

## GET_SYMM

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

    PROCEDURE:	get_symm
    PURPOSE:	Gets symmetry direction of magnetic field
    INPUT:
    	none
    KEYWORDS:
    	use_mag:
    	use_q:
    	use_dir:
    	time:
    	stheta:
    	sphi:

    CREATED BY: 	Davin Larson
    LAST MODIFICATION:	@(#)get_symm.pro	1.5 95/08/24

(See general/science/get_symm.pro)

## HEATFLUX

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

    FUNCTION:	heatflux
    PURPOSE:	Calulates heatlux from a 3dimensional data structure such as
    		those generated by get_el,get_pl,etc.
    		e.g. "get_el"
    INPUT:
    	dat:	A 3d data structure.
    KEYWORDS:
    	esteprange:	the energy step range to use, default is full range
    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)heatflux.pro	1.5 95/10/06

(See general/science/heatflux.pro)

## JE_3D

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

    FUNCTION:	je_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
    INPUT:
    	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
    KEYWORDS
    	ENERGY:	fltarr(2),	optional, min,max energy range for integration
    	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
    	EBINS:	bytarr(na),	optional, energy bins array for integration
    					0,1=exclude,include,
    					na = dat.nenergy
    	ANGLE:	fltarr(2,2),	optional, angle range for integration
    				theta min,max (0,0),(1,0) -90<theta<90
    				phi   min,max (0,1),(1,1)   0<phi<360
    	ARANGE:	fltarr(2),	optional, min,max angle bin numbers for integration
    	BINS:	bytarr(nb),	optional, angle bins array for integration
    					0,1=exclude,include,
    					nb = dat.ntheta
    	BINS:	bytarr(na,nb),	optional, energy/angle bins array for integration
    					0,1=exclude,include
    PURPOSE:
    	Returns the energy flux, [Je_x,Je_y,Je_z], ergs/(cm^2-s)
    NOTES:
    	Function normally called by "get_3dt" or "get_2dt" to
    	generate time series data for "tplot.pro".

    CREATED BY:
    	J.McFadden	97-12-4
    LAST MODIFICATION:
    	97-12-4		J.McFadden

(See general/science/je_3d.pro)

## J_3D

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

    FUNCTION:	j_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
    INPUT:
    	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
    KEYWORDS
    	ENERGY:	fltarr(2),	optional, min,max energy range for integration
    	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
    	EBINS:	bytarr(na),	optional, energy bins array for integration
    					0,1=exclude,include,
    					na = dat.nenergy
    	ANGLE:	fltarr(2,2),	optional, angle range for integration
    				theta min,max (0,0),(1,0) -90<theta<90
    				phi   min,max (0,1),(1,1)   0<phi<360
    	ARANGE:	fltarr(2),	optional, min,max angle bin numbers for integration
    	BINS:	bytarr(nb),	optional, angle bins array for integration
    					0,1=exclude,include,
    					nb = dat.ntheta
    	BINS:	bytarr(na,nb),	optional, energy/angle bins array for integration
    					0,1=exclude,include
    PURPOSE:
    	Returns the flux, [Jx,Jy,Jz], 1/(cm^2-s)
    NOTES:
    	Function normally called by "get_3dt" or "get_2dt" to
    	generate time series data for "tplot.pro".

    CREATED BY:
    	J.McFadden	95-7-27
    LAST MODIFICATION:
    	96-7-6		J.McFadden

(See general/science/j_3d.pro)

## MAKE_3DMAP

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

    FUNCTION make_3dmap, dat,nx,ny
    PURPOSE:
      Returns a 3d map using the theta's and phi's of a 3d structure.
      This routine is primarily used by "PLOT3D_NEW".
    INPUT:  dat:  a 3d structure (see "3D_STRUCTURE" for more info).
             nx:  x dimension of output array.
             ny:  y dimension of output array.
    OUTPUT: A 2 dimensional array of bin values that reflect the mapping.
    KEYWORDS:
       HIGHEST:  force the highest bin number to prevail for overlapping bins.
    ASSUMPTIONS: theta +/- dtheta should be in the range:  -90 to +90.
    NOTES: if there are any overlapping bins, then the lowest bin number
        will win, unless the HIGHEST keyword is set.
    WRITTEN BY:  Davin Larson,   96-2-8
    LAST MODIFICATION:	@(#)make_3dmap.pro	1.7 99/10/22

(See general/science/make_3dmap.pro)

## MAT_DIAG

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

    Program:	mat_diag, p, EIG_VAL= eig_val, EIG_VEC= eig_vec
    INPUT:
    	p	6-element vector [Pxx, Pyy, Pzz, Pxy, Pxz, Pyz] of a
    		symmetric matrix
    OUTPUT:
    	eig_val, eig_vec
    PURPOSE:
    	Diagonalize a 3x3 symmetric matrix
    	Returns the eigenvalues and eigenvectors.
    	The eigenvalues are the diagnonal elements of the matrix
    	The eigenvectors are the associated principle axis.
    NOTES:
    	The first eigenvalue (eig_val(0)) and eigenvector (eig_vec(*,0))
    	are the distinguisheable eigenvalue and the major (symmetry) axis,
    	respectively.
    	The "degenerate" eigenvalues are sorted such that the 2nd eigenvalue
    	is smaller than the third one.
    CREATED BY:
    	Tai Phan (95-9-15)
    LAST MODIFICATION:
    	2015-12-09		Tai Phan

(See general/science/mat_diag.pro)

## N_3D

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

    FUNCTION:	n_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
    INPUT:
    	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
    KEYWORDS
    	ENERGY:	fltarr(2),	optional, min,max energy range for integration
    	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
    	EBINS:	bytarr(na),	optional, energy bins array for integration
    					0,1=exclude,include,
    					na = dat.nenergy
    	ANGLE:	fltarr(2,2),	optional, angle range for integration
    				theta min,max (0,0),(1,0) -90<theta<90
    				phi   min,max (0,1),(1,1)   0<phi<360
    	ARANGE:	fltarr(2),	optional, min,max angle bin numbers for integration
    	BINS:	bytarr(nb),	optional, angle bins array for integration
    					0,1=exclude,include,
    					nb = dat.ntheta
    	BINS:	bytarr(na,nb),	optional, energy/angle bins array for integration
    					0,1=exclude,include
    PURPOSE:
    	Returns the density, n, 1/cm^3
    NOTES:
    	Function normally called by "get_3dt" or "get_2dt" to
    	generate time series data for "tplot.pro".

    CREATED BY:
    	J.McFadden	95-7-27
    LAST MODIFICATION:
    	96-7-6		J.McFadden	added more keywords

(See general/science/n_3d.pro)

## OMNI3D

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

    FUNCTION:  omni3d
    PURPOSE:  produces an omnidirectional spectrum structure by summing
     over the non-zero bins in the keyword bins.
     this structure can be plotted with "spec3d"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)omni3d.pro	1.12 02/04/17

     WARNING:  This is a very crude structure; use at your own risk.

(See general/science/omni3d.pro)

## PAD

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

    FUNCTION:	pad
    PURPOSE:	makes a data pad from a 3d structure
    INPUT:
    	dat:	A 3d data structure such as those gotten from get_el,get_pl,etc.
    		e.g. "get_el"
    KEYWORDS:
    	bdir:	Add B direction
    	esteps:	Energy steps to use
    	bins:	bins to sum over
    	num_pa:	number of the pad

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)pad.pro	1.21 02/04/17

(See general/science/pad.pro)

## PADPLOT

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

    PROCEDURE: padplot,pad
       Plots pad data vs pitch angle.
    INPUTS:
       pad   - structure containing pitch angle distribution (PAD) data.
               (Obtained from "pad()" routine)
    KEYWORDS:
       LIMITS - limit structure. (see "xlim" , "YLIM" or "OPTIONS")
          The limit structure can have the following elements:
          UNITS:  units to be plotted in.
          ALL PLOT and OPLOT keywords.
       UNITS  - convert to given data units before plotting
       MULTI  - Set to the number of plots desired across the page.
       OPLOT  - Overplots last plot if set.
       LABEL  - set to print labels for each energy step.

    SEE ALSO:	"spec3d"

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)padplot.pro	1.18 02/04/17

(See general/science/padplot.pro)

## PANGLE

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

    FUNCTION:  pangle,theta,phi,b_theta,b_phi
    PURPOSE:
     Computes pitch angle given two sets of theta and phi
    INPUT:
      theta,phi:       double (array or scaler)  first directions
      b_theta,b_phi :  double (array or scaler)  second directions
    RETURNS:  pitch angle (array or scaler) same dimensions as theta and phi

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)pangle.pro	1.4 95/11/28

(See general/science/pangle.pro)

## PLOT3D

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

    NAME:
      PLOT3D
    PROCEDURE: plot3d, dat , latitude, longitude
    PURPOSE:
      Draws a series of 3d color plots, one plot per energy step.
    INPUT:
      dat:  3d data structure.
      latitude:  latitude of center of plot
      longitude:  longitude of center of plot
    KEYWORDS:
       EBINS:     Specifies energy bins to plot.
       SUM_EBINS: Specifies how many bins to sum, starting with EBINS.  If
                  SUM_EBINS is a scalar, that number of bins is summed for
                  each bin in EBINS.  If SUM_EBINS is an array, then each
                  array element will hold the number of bins to sum starting
                  at each bin in EBINS.  In the array case, EBINS and SUM_EBINS
                  must have the same number of elements.
       BNCENTER:  if > 0 then lat,lon set so that B direction is in center
                  if < 0 then lat,lon set so that -B direction is in center
                  ('magf' element must exist in dat structure. See "ADD_MAGF")
       BINS:    bins to use for autoscaling.
       SMOOTH:  smoothing parameter.  0=none,  2 is typical
       TITLE:   overrides default plot title.
       NOTITLE: if set, suppresses plot title.
       NOCOLORBAR: if set, suppresses colorbar.
       NOBORDER: if set, suppresses plot border.
    SEE ALSO:  "PLOT3D_OPTIONS" to see how to set other options.

    NOTE: plot3d_new has replaced plot3d to eliminate a naming conflict between plot3d and a library routine that was added to IDL in version 8.1.
          The original plot3d.pro remains to preserve backwards compatibility for users using IDL 7.1 or earlier.

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)plot3d.pro	1.43 02/04/17

(See general/science/plot3d.pro)

## PLOT3D_COM

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

    COMMON BLOCK:	plot3d_com
    PURPOSE:	Common block for "PLOT#D" routines
    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)plot3d_com.pro	1.8 95/11/07
    SEE ALSO:   "PLOT3D_NEW" and "PLOT3D_OPTIONS"

(See general/science/plot3d_com.pro)

## PLOT3D_NEW

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

    NAME:
      PLOT3D_NEW
    PROCEDURE: plot3d_new, dat , latitude, longitude
    PURPOSE:
      Draws a series of 3d color plots, one plot per energy step.
    INPUT:
      dat:  3d data structure.
      latitude:  latitude of center of plot
      longitude:  longitude of center of plot
    KEYWORDS:
       EBINS:     Specifies energy bins to plot.
       SUM_EBINS: Specifies how many bins to sum, starting with EBINS.  If
                  SUM_EBINS is a scalar, that number of bins is summed for
                  each bin in EBINS.  If SUM_EBINS is an array, then each
                  array element will hold the number of bins to sum starting
                  at each bin in EBINS.  In the array case, EBINS and SUM_EBINS
                  must have the same number of elements.
       BNCENTER:  if > 0 then lat,lon set so that B direction is in center
                  if < 0 then lat,lon set so that -B direction is in center
                  ('magf' element must exist in dat structure. See "ADD_MAGF")
       BINS:    bins to use for autoscaling.
       SMOOTH:  smoothing parameter.  0=none,  2 is typical
       TITLE:   overrides default plot title.
       NOTITLE: if set, suppresses plot title.
       NOCOLORBAR: if set, suppresses colorbar.
       NOBORDER: if set, suppresses plot border.
    SEE ALSO:  "PLOT3D_OPTIONS" to see how to set other options.

    ;NOTE: plot3d_new has been created to eliminate a naming conflict between plot3d and a library routine that was added to IDL in version 8.1.
          The original plot3d.pro remains to preserve backwards compatibility for users using IDL 7.1 or earlier.

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)plot3d.pro	1.43 02/04/17

(See general/science/plot3d_new.pro)

## PLOT3D_OPTIONS

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

    PROCEDURE:  plot3d_options
    PURPOSE:  Sets default options for the "plot3d" routine
       The only inputs are through keywords:
    KEYWORDS:
       MAP:  one of the following strings:
           'cylindrical', 'molleweide', 'ait' ,'lambert'  ....
           (See manual for other maps, only the first 3 characters are req'd)
       COMPRESS:  integer defining map resolution (see manual)  1 si default
       SMOOTH:    0 gives no smoothing.
       LOG:       0: linear color scale;   1: log color scale
       TRIANGULATE:  Uses spherical triangulation if set
       LATITUDE:  Center Latitude.
       LONGITUDE: Center Longitude.

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)plot3d_options.pro	1.10 96/09/24

(See general/science/plot3d_options.pro)

## PLOT_MAP

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

     PROCEDURE:
    	PLOT_MAP

     DESCRIPTION:

    	Plot the map from the standard 3-D data structure that is returned
    	from the IDL from SDT interface.  The THETA, PHI, DTHETA, DPHI,
    	DATA_NAME and PROJECT_NAME tags must exist for this routine to work.
    	(The standard 3-D data structure should contain these.)

     CALLING SEQUENCE:

     	plot_map, data_structure

     ARGUMENTS:

    	data_structure 		The standard 3-D data structure to plot the
    				map from.

     REVISION HISTORY:

    	@(#)plot_map.pro	1.1 22 Aug 1995
     	Originally written by Jonathan M. Loran,  University of
     	California at Berkeley, Space Sciences Lab.   Aug. '95

(See general/science/plot_map.pro)

## PRESTENS

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

    PROCEDURE:	prestens
    PURPOSE:	This function computes the relative components of the pressure
    		tensor
    INPUT:
    	dat:	A 3d structure such as those gotten by using get_el,get_pl,etc.
    		e.g. "get_el"
    KEYWORDS:
    	esteprange:	energy range to use

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)prestens.pro	1.5 95/10/06

    NOTE:	 It is NOT yet corrected to give physical results

(See general/science/prestens.pro)

## P_3D

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

    FUNCTION:	p_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
    INPUT:
    	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
    KEYWORDS
    	ENERGY:	fltarr(2),	optional, min,max energy range for integration
    	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
    	EBINS:	bytarr(na),	optional, energy bins array for integration
    					0,1=exclude,include,
    					na = dat.nenergy
    	ANGLE:	fltarr(2,2),	optional, angle range for integration
    				theta min,max (0,0),(1,0) -90<theta<90
    				phi   min,max (0,1),(1,1)   0<phi<360
    	ARANGE:	fltarr(2),	optional, min,max angle bin numbers for integration
    	BINS:	bytarr(nb),	optional, angle bins array for integration
    					0,1=exclude,include,
    					nb = dat.ntheta
    	BINS:	bytarr(na,nb),	optional, energy/angle bins array for integration
    					0,1=exclude,include
    PURPOSE:
    	Returns the pressure tensor, [Pxx,Pyy,Pzz,Pxy,Pxz,Pyz], eV/cm^3
    NOTES:
    	Function normally called by "get_3dt" or "get_2dt" to
    	generate time series data for "tplot.pro".

    CREATED BY:
    	J.McFadden	95-7-27
    LAST MODIFICATION:
    	96-7-6		J.McFadden

(See general/science/p_3d.pro)

## REFORM_3D_STRUCT

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

    NAME:
    reform_3d_struct
    CALLING SEQUENCE:
    dat1 = reform_3d_struct(dat, reverse=reverse, nphi=nphi, ntheta=ntheta)
    PURPOSE:
    If a 3-d data structure has fromat (nenergy, nphi, ntheta) reform into (nenergy, nbins)
    For testing with older plot3d_new, edit3dbins code.
    Note that the input structure data, theta, phi have to be dimensioned nenergy,
    nphi, ntheta (as for MMS FPI data distributions), nenergy, ntheta, nphi give unpredictable
    results.
    INPUT:
    dat = a 3d structure, with data, etc, dimensions (nenrgy, nphi, ntheta)
    OUTPUT:
    dat1 = a new 3d structure, with data, etc, reformed to dimensions (nenrgy, nbins = nphi*ntheta),
           provided that ntheta*nphi = nbins.
    KEYWORDS:
    reverse=if set, reverse the process, this allows you to call edit3dbins to get bin flags,
            and then recover the original structure, But ntheta and nphi keywords must be set.
            Do not call this on structures for which ntheta is not the same for all phi (e.g.,
            THEMIS ESA data).
    nphi = the number of phi angles
    ntheta = the number of theta angles
    HISTORY:
    2018-01-08, jmm, jimm@ssl.berkeley.edu

(See general/science/reform_3d_struct.pro)

## SLICE2D

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

     PROCEDURE:
           slice2d
     PURPOSE:
           creates a 2-D slice of the 3-D distribution function
     CALLING SEQUENCE:
           slice2d, dat
     INPUTS:
           dat: standard 3d data structure (cf. 3d_structure.pro)
     KEYWORDS:
           all optional
           ROTATION: (case insensitive)
             'xy': the x axis is v_x and the y axis is v_y. (DEFAULT)
             'xz': the x axis is v_x and the y axis is v_z.
             'yz': the x axis is v_y and the y axis is v_z.
           rotations shown below require valid MAGF tag in the data structure
             'BV': the x axis is v_para (to the magnetic field) and
                   the bulk velocity is in the x-y plane.
             'BE': the x axis is v_para (to the magnetic field) and
                   the VxB direction is in the x-y plane.
             'perp': the x-y plane is perpendicular to the B field,
                     while the x axis is the velocity projection on the plane.
             'perp_xy': the x-y plane is perpendicular to the B field,
                        while the x axis is the x projection on the plane.
             'perp_xz': the x-y plane is perpendicular to the B field,
                        while the x axis is the x projection on the plane.
             'perp_yz': the x-y plane is perpendicular to the B field,
                        while the x axis is the y projection on the plane.
           ANGLE: the lower and upper angle limits of the slice selected
                  to plot (DEFAULT [-20,20]).
           THIRDDIRLIM: the limits of the velocity component perpendicular to
                        the slice plane (Def: inactivated)
                        Once activated, the ANGLE keyword would be invalid.
           XRANGE: vector specifying the xrange (Def: adjusted to energy range)
           RANGE: vector specifying the color range
                  (Def: from min to max of the unsmoothed, uninterpolated data)
           ERANGE: specifies the energy range to be used (Def: all energy)
           UNITS: specifies the units ('eflux', 'df', etc.) (Def. is 'df')
           NOZLOG: specifies a linear Z axis
           POSITION: positions the plot using a 4-vector
           NOFILL: doesn't fill the contour plot with colors
           NLINES: says how many lines to use if using NOFILL
                   (DEFAULT 60, MAX 60)
           NOOLINES: suppresses the black contour lines
           NUMOLINES: how many black contour lines (DEFAULT 20, MAX 60)
           REMOVEZERO: removes the data with zero counts for plotting
           SHOWDATA: plots all the data points over the contour (symsize = showdata)
           VEL: specifies the bulk velocity in the instrument coordinates
                used for subtraction & rotation (default is calculated with v_3d)
           NOGRID: forces no triangulation (no interpolation)
           NOSMOOTH: suppresses smoothing
                     IF NOT SET, DEFAULT IS SMOOTH (boxcar smoothing w/ width=3)
           SUNDIR: specifies the sun direction in the instrument coordinates
                   if set, sun direction line is plotted
           NOVELLINE: suppresses the red velocity line
           SUBTRACT: Can take on a value from 0 to 4:
               0 : do nothing
               1 : subtract the bulk velocity before plotting
                     if there are few data points around (0,0), use
                     ThirdDirLim keyword to select data points
               2 : subtract the X component of the bulk velocity before plotting
                     (useful for cuts in the Y-Z plane)
               3 : subtract the Y component of the bulk velocity before plotting
                     (useful for cuts in the X-Z plane)
               4 : subtract the Z component of the bulk velocity before plotting
                     (useful for cuts in the X-Y plane)
           RESOLUTION: resolution of the mesh (DEFAULT 51)
           ISOTROPIC: forces the scaling of the X and Y axes to be equal
           XTITLE, YTITLE, ZTITLE, TITLE: set titles
           NOPLOT: if set, does not generate a plot
           DATPLOT: returns a structure which contains data used to plot
           other keywords are passed to contour
     CREATED BY:
           Yuki Harada on 2014-05-26
           Modified from 'thm_esa_slice2d' written by Arjun Raj & Xuzhi Zhou

     $LastChangedBy: dmitchell $
     $LastChangedDate: 2018-01-02 15:04:01 -0800 (Tue, 02 Jan 2018) $
     $LastChangedRevision: 24474 $
     $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/slice2d.pro $

(See general/science/slice2d.pro)

## SMOOTH_PERIODIC

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

    NAME:
    	smooth_periodic

    FUNCTION: smooth_periodic, old_image, n
    PURPOSE:  Uses box car smoothing of a surface with sperical periodic boundary
        conditions.
    INPUT:
       old_image:  2d matrix
       n:          size of boxcar averaging window
    Output:  smoothed image.

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)smooth_periodic.pro	1.5 95/10/04

(See general/science/smooth_periodic.pro)

## SPD_UNITS_STRING

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

    Procedure:
      spd_units_string

    Purpose:
      Return string describing particle data units for labels etc.

    Calling Sequence:
      string = spd_units_string(units, [,/simple] [,/units_only])

    Input:
      units:  String describing units
      simple:  Flag to return string with no special formatting
      units_only:  Flag to return just the units

    Output:
     return value:  String containing unit description and breakdown

    Notes:

    $LastChangedBy: egrimes $
    $LastChangedDate: 2020-08-04 13:04:13 -0700 (Tue, 04 Aug 2020) $
    $LastChangedRevision: 28986 $
    $URL: svn+ssh://thmsvn@ambrosia.ssl.berkeley.edu/repos/spdsoft/trunk/general/science/spd_units_string.pro $

(See general/science/spd_units_string.pro)

## SPEC3D

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

    PROCEDURE: spec3d,data
       Plots 3d data as energy spectra.
    INPUTS:
       data   - structure containing 3d data  (obtained from get_??() routine)
    		e.g. "get_el"
    KEYWORDS:
       LIMITS - A structure containing limits and display options.
                 see: "options", "xlim" and "ylim", to change limits
       UNITS  - convert to given data units before plotting
       COLOR  - array of colors to be used for each bin
       BINS   - array of bins to be plotted  (see "edit3dbins" to change)
       OVERPLOT  - Overplots last plot if set.
       LABEL  - Puts bin labels on the plot if set.

    See "plot3d_new" for another means of plotting data.
    See "conv_units" to change units.
    See "time_stamp" to turn time stamping on and off.

    CREATED BY:	Davin Larson  June 1995
    FILE:  spec3d.pro
    VERSION 1.25
    LAST MODIFICATION: 02/04/17

(See general/science/spec3d.pro)

## SPHERE_TO_CART

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

    PROCEDURE sphere_to_cart,r,theta,phi, x,y,z
    PURPOSE:  transform from spherical to cartesian coordinates
    INPUTS:  r, theta, phi    (array or scalar) (Units are degrees)
    OUTPUTS: x, y, z          (will have the same dimensions as r,theta,phi)
    KEYWORD OUTPUT:
       VEC:  a named variable in which the vector [x,y,z] is returned

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)sphere_to_cart.pro	1.6 02/11/01

    NOTES:
       -90 < theta < 90   (latitude not co-lat)

    SEE ALSO:
      xyz_to_polar.pro

(See general/science/sphere_to_cart.pro)

## SUB3D

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

    FUNCTION: sub3d
    PURPOSE: Takes two 3D structures and returns a single 3D structure
      whose data is the difference of the two.
      This routine is useful for subtracting background counts.
      Integration period is considered if units are in counts.
    INPUTS: d1,d2  each must be 3D structures obtained from the get_?? routines
    	e.g. "get_el"
    RETURNS: single 3D structure

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)sub3d.pro	1.10 01/10/08

    Notes: This is a very crude subroutine. Use at your own risk.

(See general/science/sub3d.pro)

## SUM3D

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

    FUNCTION: sum3d
    PURPOSE: Takes two 3D structures and returns a single 3D structure
      whose data is the sum of the two
    INPUTS: d1,d2  each must be 3D structures obtained from the get_?? routines
    	e.g. "get_el"
    RETURNS: single 3D structure

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)sum3d.pro	1.8 02/04/17

    Notes: This is a very crude subroutine. Use at your own risk.

(See general/science/sum3d.pro)

## SUPERPO_HISTO

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

    	Name: SUPERPO_HISTO

    	Purpose:  This routine calculates the minimum (maximum, etc.) function of
                 several time series. The time bin (resolution) can be specified.
                 An example would be the calculation of AL (AU, AE) indices. The
                 results are stored in tplot variables. This routine only uses
                 the actual values in the time series; no interpolation is done.
                 An alternative routine exists which interpolates ('superpo_interpol').

    	Variable:

    		quantities = string of tplot variable names (e.g., ground stations)

    	Keywords:
    		res        = sampling interval (by default 60 sec)
    		min        = e.g., 'thg_pseudoAL'
    		max	       = e.g., 'thg_pseudoAU
    		dif	       = e.g., 'thg_pseudoAE
    		avg	       = average values
           med        = median values
           output_names: an array that stores the tplot variable names created
                         by this routine

    	Example:
     		superpo_histo,'thg_mag_ccnv_x thg_mag_drby_x thg_mag_fsim_x
    				       thg_mag_fsmi_x thg_mag_fykn_x',
    			           min='thg_pseudoAL',avg='thg_avg'
    					   res=600.0

    		superpo_histo,'thg_mag_????_x',min='thg_pseudoAL', res=30.0

     		superpo_histo,'thg_mag_????_x' ; default values for all keywords

       Speed:
           With an input of magnetometer data from 27 ground stations (178000 data points each)
           and a bin resolution of 60 s (res=60.0), the running time is about 3 sec (using IBM PC).
           With res=1.0, the running time is about 9 sec.

       Notes:
           Written by Andreas Keiling, 30 July 2007

     $LastChangedBy:   $
     $LastChangedDate:   $
     $LastChangedRevision:  $
     $URL $

(See general/science/superpo_histo.pro)

## SUPERPO_INTERPOL

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

    	Name: SUPERPO_INTERPOL

    	Purpose:  This routine calculates the minimum (maximum, etc.) function of
                 several time series. The time bin (resolution) can be specified.
                 An example would be the calculation of AL (AU, AE) indices. The
                 results are stored in tplot variables. This routine interpolates
                 at desired sampling rate. An alternative routine exists which does
                 not interpolate (see 'superpo_histo').

    	Variable:

    		quantities = string of tplot variable names (e.g., ground stations)

    	Keywords:
    		res        = sampling interval (by default 60 sec)
    		min        = e.g., 'thg_pseudoAL'
    		max	       = e.g., 'thg_pseudoAU
    		dif	       = e.g., 'thg_pseudoAE
    		avg	       = average values
           med        = median values

    	Example:
     		superpo_interpol,'thg_mag_ccnv_x thg_mag_drby_x thg_mag_fsim_x
    				          thg_mag_fsmi_x thg_mag_fykn_x',
    			        	  min='thg_pseudoAL',avg='thg_avg'
    						  res=600n.0,

    		superpo_interpol,'thg_mag_????_x',min='thg_pseudoAL', res=30.0

     		superpo_interpol,'thg_mag_????_x' ; default values for all keywords

       Speed:
           With an input of magnetometer data from 27 ground stations (178000 data points each)
           and a bin resolution of 60 s (res=60.0), the running time is less than 1 sec (using IBM PC).
           With res=1.0, the running time is around 1 sec.

       Notes:
           Written by Andreas Keiling, 30 July 2007

     $LastChangedBy:   $
     $LastChangedDate:   $
     $LastChangedRevision:  $
     $URL $

(See general/science/superpo_interpol.pro)

## SYMM3D

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

    FUNCTION:	symm3d
    PURPOSE:	Returns [theta,phi]  given a 3d data struct
    INPUT:
    	dat:	A 3d data structure such as those generated by get_el,get_pl,etc
    		e.g. "get_el"
    KEYWORDS:
    	esteps:		energy steps to use

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)symm3d.pro	1.5 95/10/06

(See general/science/symm3d.pro)

## SYMMETRY_DIR

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

    FUNCTION:	symmetry_dir
    PURPOSE:	Calculates symmetry direction
    INPUT:
    	Pt:	array of pts
    KEYWORDS:
    	none

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)symmetry_dir.pro	1.3 95/08/24

(See general/science/symmetry_dir.pro)

## TRANSFORM_VELOCITY

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

    NAME:
    	transform_velocity

    PROCEDURE:   transform_velocity,  vel, theta, phi,  deltav
    PURPOSE:  used by the convert_vframe routine to transform arrays of velocity
        thetas and phis by the offset deltav
    INPUT:
      vel:  array of velocities
      theta: array of theta values
      phi:   array of phi values
      deltav: [vx,vy,vz]  (transformation velocity)
    KEYWORDS:
    	vx,vy,vz:	return vx,vy,vz separately as well as in vector form

    CREATED BY:	Davin Larson
    LAST MODIFICATION:	@(#)convert_vframe.pro	1.21 02/11/01

(See general/science/convert_vframe.pro)

## T_3D

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

    FUNCTION:	t_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
    INPUT:
    	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
    KEYWORDS
    	ENERGY:	fltarr(2),	optional, min,max energy range for integration
    	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
    	EBINS:	bytarr(na),	optional, energy bins array for integration
    					0,1=exclude,include,
    					na = dat.nenergy
    	ANGLE:	fltarr(2,2),	optional, angle range for integration
    				theta min,max (0,0),(1,0) -90<theta<90
    				phi   min,max (0,1),(1,1)   0<phi<360
    	ARANGE:	fltarr(2),	optional, min,max angle bin numbers for integration
    	BINS:	bytarr(nb),	optional, angle bins array for integration
    					0,1=exclude,include,
    					nb = dat.ntheta
    	BINS:	bytarr(na,nb),	optional, energy/angle bins array for integration
    					0,1=exclude,include
    PURPOSE:
    	Returns the temperature, [Tx,Ty,Tz,Tavg], eV
    NOTES:
    	Function normally called by "get_3dt" or "get_2dt" to
    	generate time series data for "tplot.pro".

    CREATED BY:
    	J.McFadden	95-7-27
    LAST MODIFICATION:
    	96-7-6		J.McFadden

(See general/science/t_3d.pro)

## UNITS

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

    PROCEDURE:  units
    PURPOSE:    adds the tag 'units' to the structure "struct"
    INPUTS:
       struct:  structure to be added to.  (Created if non-existent)
       units:     string containing units name.
    Typical usage:
       units,lim,'Counts'

    CREATED BY:	Davin Larson
    LAST MODIFICATION: 	@(#)units.pro	1.4 02/04/17

(See general/science/units.pro)

## VTH_3D

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

    FUNCTION:	vth_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
    INPUT:
    	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
    KEYWORDS
    	ENERGY:	fltarr(2),	optional, min,max energy range for integration
    	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
    	EBINS:	bytarr(na),	optional, energy bins array for integration
    					0,1=exclude,include,
    					na = dat.nenergy
    	ANGLE:	fltarr(2,2),	optional, angle range for integration
    				theta min,max (0,0),(1,0) -90<theta<90
    				phi   min,max (0,1),(1,1)   0<phi<360
    	ARANGE:	fltarr(2),	optional, min,max angle bin numbers for integration
    	BINS:	bytarr(nb),	optional, angle bins array for integration
    					0,1=exclude,include,
    					nb = dat.ntheta
    	BINS:	bytarr(na,nb),	optional, energy/angle bins array for integration
    					0,1=exclude,include
    PURPOSE:
    	Returns the thermal velocity, [Vthx,Vthy,Vthz,Vthavg], km/s
    NOTES:
    	Function normally called by "get_3dt" or "get_2dt" to
    	generate time series data for "tplot.pro".

    CREATED BY:
    	J.McFadden	95-7-27
    LAST MODIFICATION:
    	96-7-6		J.McFadden

(See general/science/vth_3d.pro)

## V_3D

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

    FUNCTION:	v_3d(dat,ENERGY=en,ERANGE=er,EBINS=ebins,ANGLE=an,ARANGE=ar,BINS=bins)
    INPUT:
    	dat:	structure,	2d data structure filled by get_eesa_surv, get_eesa_burst, etc.
    KEYWORDS
    	ENERGY:	fltarr(2),	optional, min,max energy range for integration
    	ERANGE:	fltarr(2),	optional, min,max energy bin numbers for integration
    	EBINS:	bytarr(na),	optional, energy bins array for integration
    					0,1=exclude,include,
    					na = dat.nenergy
    	ANGLE:	fltarr(2,2),	optional, angle range for integration
    				theta min,max (0,0),(1,0) -90<theta<90
    				phi   min,max (0,1),(1,1)   0<phi<360
    	ARANGE:	fltarr(2),	optional, min,max angle bin numbers for integration
    	BINS:	bytarr(nb),	optional, angle bins array for integration
    					0,1=exclude,include,
    					nb = dat.ntheta
    	BINS:	bytarr(na,nb),	optional, energy/angle bins array for integration
    					0,1=exclude,include
    PURPOSE:
    	Returns the velocity, [Vx,Vy,Vz], km/s
    NOTES:
    	Function normally called by "get_3dt" or "get_2dt" to
    	generate time series data for "tplot.pro".

    CREATED BY:
    	J.McFadden	95-7-27
    LAST MODIFICATION:
    	96-7-6		J.McFadden

(See general/science/v_3d.pro)

## XYZ_TO_POLAR

[Previous Routine] [List of Routines]

    PROCEDURE:  xyz_to_polar,xyz
    PURPOSE: Calculates magnitude, theta and phi given a 3 vector
    INPUT:   several options exist for xyz:
        string:    data associated with the string is used.
        structure: data.y is assumed to contain the xyz array
        array(n,3)   n by (x,y,z components)
        array(3)      vector:  [x,y,z]
    RETURN VALUES: through the keywords.  Same dimensions and type as the
        input value of x.
    KEYWORDS:    Named variables in which results are put
       MAGNITUDE:
       THETA:
       PHI:
       MAX_VALUE:
       MIN_VALUE:
       MISSING:
    OPTION KEYWORDS:  These are used to set "cart_to_sphere" opts.
       CO_LATITUDE:   If set theta will be in co-latitude. (0<=theta<=180)
       PH_0_360:      If set positive, 0<=phi<=360, if zero, -180<=phi<=180.
                      If set negative, will guess the best phi range.
       PH_HIST:       A 2 element vector, a min and max histeresis value.

    SEE ALSO:
      sphere_to_cart.pro

    EXAMPLES:

         Passing arrays:
    x = findgen(100)
    y = 2*x
    z = x-20
    vecs = [[x],[y],[z]]
    xyz_to_polar,vecs,mag=mag      ;mag will be the magnitude of the array.

         Passing a structure:
    dat = {ytitle:'Vector',x:findgen(100),y:vecs}
    xyz_to_polar,dat,mag=mag,theta=th,phi=ph
    mag,th and ph will be all be structures.

         Passing a string:  (see store_data, get_data)
    xyz_to_polar,'Vp'   ; This assumes data has been created for this string.
        This will compute new data quantities: 'Vp_mag','Vp_th','Vp_ph'

(See general/science/xyz_to_polar.pro)