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

Last modified: Wed Jan 7 01:15:11 2009.

# Directory Listing of Routines

# ssl_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], and
- EDIT3DBINS
- 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_OPTIONS
- PLOT_MAP
- PRESTENS
- ENLARGE_PERIODIC
- SMOOTH_PERIODIC
- SPEC3D
- SPHERE_TO_CART
- SUB3D
- SUM3D
- SUPERPO_HISTO
- SUPERPO_INTERPOL
- SYMM3D
- SYMMETRY_DIR
- T_3D
  Returns the temperature, [Tx,Ty,Tz,Tavg], eV
- THM_CRIB_SUPERPO_INTERPOL_HISTO
- 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 obtained from the WIND data set:

    ** 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)
       DATA            FLOAT     Array(15, 88)
       ENERGY          FLOAT     Array(15, 88)
       THETA           FLOAT     Array(15, 88)
       PHI             FLOAT     Array(15, 88)
       GEOM            FLOAT     Array(15, 88)      Req'd by convert_esa_units
       DENERGY         FLOAT     Array(15, 88)
       DTHETA          FLOAT     Array(15, 88)
       DPHI            FLOAT     Array(15, 88)
       DOMEGA          FLOAT     Array(15, 88)
       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
       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.)

    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 ssl_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 ssl_general/science/add_bdir.pro)

## CALC_OMEGA_FLT2

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

     Calculate moment weighting factors
     Davin Larson, 2005

(See ssl_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 ssl_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 ssl_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 ssl_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 ssl_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 ssl_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], 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:
    	95-9-29		Tai Phan

(See ssl_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 scaler, 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" and "PLOT3D_OPTIONS"
    CREATED BY:	Davin Larson
    FILE: edit3dbins.pro
    VERSION:  1.14
    LAST MODIFICATION: 98/01/16

(See ssl_general/science/edit3dbins.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 ssl_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 ssl_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 ssl_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 ssl_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 ssl_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 ssl_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 ssl_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".
    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 ssl_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:
    	95-9-29		Tai Phan

(See ssl_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 ssl_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 ssl_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 ssl_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 ssl_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 ssl_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 scaler, 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.

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

(See ssl_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" and "PLOT3D_OPTIONS"

(See ssl_general/science/plot3d_com.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 ssl_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 ssl_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 ssl_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 ssl_general/science/p_3d.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 ssl_general/science/smooth_periodic.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" 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 ssl_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 scaler)
    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 ssl_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 ssl_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 ssl_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

    	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 ssl_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 ssl_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 ssl_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 ssl_general/science/symmetry_dir.pro)

## THM_CRIB_SUPERPO_INTERPOL_HISTO

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

    	Batch File: THM_CRIB_SUPERPOSED_INTERPOL_HISTO

    	Purpose:  Demonstrates the application of the routines
     		      superpo_interpol and superpo_histo

       Note:  The examples in this crib sheet call 'superpo_interpol'. Simply
              replace the calls with 'superpo_histo' to try the other routine.
              Both routines accept the same input parameters.

       Written by Andreas Keiling

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

(See ssl_general/science/thm_crib_superpo_interpol_histo.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 ssl_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 ssl_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 ssl_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 ssl_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 ssl_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.
    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 ssl_general/science/xyz_to_polar.pro)