This page was created by the IDL library routine
mk_html_help2.
Last modified: Thu Aug 6 12:53:14 2020.
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_new)
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 general/science/3d_structure.pro)
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)
Calculate moment weighting factors Davin Larson, 2005
(See general/science/calc_omega_flt2.pro)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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/tags/spedas_4_0/general/science/slice2d.pro $
(See general/science/slice2d.pro)
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)
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/tags/spedas_4_0/general/science/spd_units_string.pro $
(See general/science/spd_units_string.pro)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)
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)