This page was created by a MODIFICATION of the IDL library routine
mk_html_help. For more information on
this routine, refer to this page
or type:
doc_library, 'mk_html_help'
at the IDL command line prompt.
List Last updated: Tue Jul 7 13:06:27 2015.
NOTE: Non-PPPL employees may access these routines by following procedure GEN-034 .
Category: 2-D Plotting
[List of Routines]
NAME:
drawcircle
PURPOSE:
draw a circle centered on [x0, y0].
YOU HAVE TO HAVE YOUR AXES ESTABLISHED BEFORE CALLING THIS.
Return out arrays for later drawing on a surface, too. These are in two
parts, so you won't have a line down the middle when drawing.
CATEGORY:
2-D Plotting,
CALLING SEQUENCE:
IDL> (some plot command to estable coordinates)
IDL> drawcircle, x0, y0, radius
INPUTS:
x0,y0 - origin of circle
radius - radius of circle
KEYWORDS:
Inputs:
color -
dashed - if set, will draw curve with dashed line
angle1 - angle in radians to start drawing arc
angle2 - angle in radians to stop drawing arc
deg1 - angle in degrees to start drawing arc
deg2 - angle in degrees to stop drawing arc
bottom - draw arc in bottom of circle
Outputs:
outX1 - X1 output for other ploting
outY1 - Y1 "
outX2 - X2 "
outY2 - Y2 "
npts - # of points to use for drawing circle (all the way around)
(default may be too coarse, so curve not smooth)
EXAMPLE:
IDL> x = findgen(100) & y = x
IDL> Right_Aspect, x, y, IN_POS=[.1,.1,.9,.9], POSITION=position
IDL> plot, findgen(100), /nodata, POSITION=position
IDL> drawcircle, 40, 60, 20
IDL> drawcircle, 40, 60, 15, /dashed
IDL> drawcircle, 40, 60, 15, deg1=-60,deg2=-30, /bot
LIMITATIONS:
angle1 & angle2 can't cross over 0 or !PI
ANGLES NEED FIXING (determine where starting from)
04-Feb-2010 - added angle1 & angle2 keywords (in radians), bottom and npts
WRITTEN by Bill Davis
NAME:
drawellipse
PURPOSE:
draw an ellipse centered on [x0, y0].
YOU HAVE TO HAVE YOUR AXES ESTABLISHED BEFORE CALLING THIS.
CATEGORY:
2-D Plotting
CALLING SEQUENCE:
IDL> (some plot command to estable coordinates)
IDL> drawellipse, x0, y0, radius1, radius2, tilt=tilt
INPUTS:
x0,y0 - origin of circle/ellipse
radius1 - Ellipse semi axis 1
radius2 - Ellipse semi axis 2
KEYWORDS:
Inputs:
tilt - Ellipse rotation angle (radians, unless /deg set)
Clockwise; zero is horizontal, to the left
degrees - if set, tilt is in degrees
convention - if set, zero is to the right, CCW is positive,
with 90 straight up and -90 down
color - an index into the color table, or 'red', 'blue', etc.
dashed - if set, will draw curve with dashed line
npts - # of pts used in drawing (will be made > 100)
Outputs:
xout - x pts in outline
yout - y pts in outline
EXAMPLE:
IDL> x = findgen(100) & y = x
IDL> Right_Aspect, x, y, IN_POS=[.1,.1,.9,.9], POSITION=position
IDL> plot, findgen(100), /nodata, POSITION=position
IDL> drawellipse, 40, 60, 20, 10
IDL> drawellipse, 40, 60, 15, 10, /dashed
IDL> drawellipse, 40, 60, 15, 10, tilt=-1
IDL> drawellipse, 40, 60, 15, 10, tilt=60, /deg
IDL> drawellipse, 40, 60, 15, 10, tilt=30, /deg
IDL> drawellipse, 40, 60, 15, 10, tilt=10, /deg
IDL> drawellipse, 40, 60, 15, 10, tilt=-10, /deg
IDL> drawellipse, 40, 60, 15, 10, tilt=60, /deg, /conv
IDL> drawellipse, 40, 60, 15, 10, tilt=30, /deg, /conv
IDL> drawellipse, 40, 60, 15, 10, tilt=10, /deg, /conv
IDL> drawellipse, 40, 60, 15, 5, tilt=20, /deg, /con
IDL> drawellipse, 40, 60, 15, 5, tilt=30, /deg, /con
IDL> drawellipse, 40, 60, 15, 5, tilt=40, /deg, /con
IDL> drawellipse, 40, 60, 15, 5, tilt=50, /deg, /con
IDL> drawellipse, 40, 60, 15, 5, tilt=60, /deg, /con
IDL> drawellipse, 40, 60, 15, 5, tilt=-10, /deg, /con
IDL> drawellipse, 40, 60, 15, 5, tilt=-30, /deg, /con
IDL> tilt = 10
IDL> tilt = tilt+20 & drawellipse, 40, 60, 15, 10, tilt=tilt, /deg
to get the points back:
IDL> drawellipse, 40, 60, 15, 10, tilt=1, /noPlot, xout=xout, yout=yout
LIMITATIONS:
MODIFICATION HISTORY:
30-Oct-2013 added height keyword
15-Jan-2013 added "convention" keyword to have tilt angle be like Jr. High
19-Sep-2012 used polyfill for filled ellipses
12-Sep-2012 added thick and fill keywords (fill is faked)
WRITTEN by Bill Davis, 30-Aug-2011
NAME:
findRatZ
PURPOSE:
find the r of desired Z, but on the outer part of curve, if there
is more than one point that would cross Z=desiredZ. Use spline
interpolation.
CATEGORY:
2-D Plotting, EFIT
CALLING SEQUENCE:
IDL> desiredR = findRatZ( r, z, desiredZ )
INPUTS:
r - radius of plasma edge, (can be an array)
z - Z of plasma edge, (can be an array of same dimension as r)
desiredZ - Z at which you want R value on the outer edge returned
can be
KEYWORD PARAMETERS:
inner - if set, will return the inner value rather than the outer
plot - if set, will plot inputs and results
test - if set, will restore test values for inputs
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
EXAMPLE:
IDL> desiredR = findRatZ( r, z, desiredZ, /test, /debug, /plot )
WRITTEN 18-Feb-2010 by Bill Davis
NAME:
followcontour
PURPOSE:
Follow a contour line to find where it intersects a desired Y and
return the X value. I.e., where the 2D input array has the same value as
at specified coordinates. This is used to find the R value at Z=0 with
the same Psi value as a specified point on the flux surface. So, it can
be used for plotting things in relation to flux surfaces.
CATEGORY:
2-D Plotting, Normalized Psi
CALLING SEQUENCE:
IDL> xWant = followcontour( data2d [, x, y], xpt=xpt, ypt=ypt [, yWant=yWant])
INPUTS:
data2d - 2D array, e.g., flux values
x - X values (defaults to indices)
y - Y values (defaults to indices)
xpt - X value at which to get flux (will linearly interpolate)
ypt - Y value at which to get flux (will linearly interpolate)
yWant - Y value at which to determine X with same flux value [Def=0]
KEYWORD PARAMETERS:
outer - if set will return largest value, else will return all
(closed contours may intersect a constant Y line in two,
or more, locations)
inner - if set will return smallest value, else will retrun all
level - contour/value you want to follow (else determined by xpt & ypt)
exact - if set will interpolate to get level, rather than use nearest data pt
plot - if set will plot contours and input point and found point
_extra - passed to the contour routine
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
xWant - X value where Y=yWant and data2D has same value as at [xpt,ypt]
(finds the nearest point)
EXAMPLE:
IDL> restore, '/u/bdavis/contfollowtest.sav'
IDL> xWant = followcontour( data2d, x, y, xpt=xpt, ypt=ypt, /plot )
; where psiRZ, R, Z are from EFIT/LRDfit at a particular time:
IDL> RatZ0 = followContour( psiRZ, R, Z, xpt=Rwant, ypt=Zwant, $
yWant=0.0, /OUTER, /EXACT )
19-Nov-2010 added SAME keyword for speed when looking up a lot of points
WRITTEN 15-Feb-2010 by Bill Davis
NAME:
oplotdash
PURPOSE:
Overplot a variety of dashed lines, even if terminal
emulator doesn't for different linestyles
CATEGORY:
2-D Plotting
CALLING SEQUENCE:
IDL> oplotdash, x, y, dashfracdashfrac=, blankfrac=blankfrac
INPUTS:
x - x data to overplot
y - y data to overplot
KEYWORD PARAMETERS:
Optional:
dashfrac - fraction of distance (0-1) dash will be (def=0.01)
blankfrac - fraction of distance (0-1) blank will be
smallFrac - fraction of distance (0-1) for a small dash, or a dot.
OUTPUTS:
COMMON BLOCKS:
NONE
NOTES:
This will probably be slow for large numbers of points.
EXAMPLE:
x = findgen(100)
y = sin(x/5)
plot, x, y, title='My Plot', xtitle='Seconds', ytitle='Function', $
charsize=1.5
oplotdash, x, y/2, dashfrac=.02, blankfrac=.01
TVIMAGE, bytscl(dist(100,50)), x, y, POSITION=thisPosition, $
/KEEP_ASPECT_RATIO
oplotdash, x, y/2, dashfrac=.02, blankfrac=.01
MODIFICATION HISTORY:
06-Mar-2013 made to work when other graph type drawn first
16-Apr-2012 Written by Bill Davis, PPPL
NAME:
plot3_mpts
PURPOSE:
Make 3 Multi-point Thomson Scattering Plots: 2-D plots of
electron Temp and Density and a time history.
CATEGORY:
2-D Plotting, MPTS, GPI
CALLING SEQUENCE:
IDL> plot3_mpts, shot
INPUTS:
shot = NSTX shot number
KEYWORD PARAMETERS:
Inputs:
Plot_IP - if=0, do not have Ip plot on graph
Tplot = vector of times to plot profiles (default = all times)
(if multiple shots only first time point is used)
Temax = value of maximum Te to plot [ keV]
Nemax = value of maximum Ne to plot [1e13 /cm^3]
Pemax = value of maximum Pe to plot [kPa]
Nelmax = value of maximum NeL to plot [1e15 /cm^2]
Temin = value of minimum Te to plot [ keV]
Nemin = value of minimum Ne to plot [1e13 /cm^3]
Pemin = value of minimum Pe to plot [kPa]
Nelmin = value of minimum NeL to plot [1e15 /cm^2]
CHI = if set, changes plotting defaults to values appropriate
to lower temperature plasmas
Nospline = set to connect data with straight lines instead of splines.
Rrange = two element vector to set radial range of plot [Rmin, Rmax]
Fancy = sets Font to Triplex Roman
Tmin = minimum time to plot (def=0)
Tmax = set maximum value of time in plot
Pk = set Te(t) to peak value of spline
Efit = value of EFIT tree to use '1,2,3,4,5'
GPI = if set, will add trace of average light vs. time from GPI
camera frames.
NB = if set, add neutral beam power to time history plot
RF = if set, add HHFW power to time history plot
MHD = if set, add Mirnov trace to time history
Vloop = if set, add loop voltage to time history plot
Mld = if set, add microwave line density to time history
HA = if set, add hydrogen alpha signal to time history
USXR = if set, add ultra-soft x-ray signal to time history
Wmhd = if set, add EFIT Total energy (Wmhd) to time history
Tf = if set, add TF current to time history
Qmin = if set, add qmin to time history
Q95 = if set, add q95 to time history
noTimeLines - if set, will draw dotted lines on color contours showing
times of Thomson data
box -
c_colors - contour colors
charsize - sets size of characters in plot
contour - draw contour lines over color contours
ctb - the IDL color table (defaults to 3, hot metal)
deltaT -
efileType -
emailPsAddress -
fit - type of fit for separatrix plot
GPI - if set, plot GPI average in bottom plot
interp -
lastPoint -
lastTime -
mailPsFile -
nospline -
PlotsDesired -
psFileName -
r1 -
r2 -
rescale -
rf -
sep -
sh2 -
surf -
t1 -
t2 -
tRange -
xmargin - sent to plot command
XOR_cont - use XOR for color of contour lines
xpos -sent to plot command
xRange -
xsize -
ymargin - sent to plot command
ypos - sent to plot command
ysize -
OUTPUTS:
opt = returned value out
COMMON BLOCKS:
NONE
EXAMPLE:
To add GPI average to lowest plot:
IDL> plot3_mpts, 138846, /GPI,/box
IDL> wset, 32
IDL> plot3_mpts, 138846, /GPI,tmin=.45, tmax=.85, r1=1.2,r2=1.56, $
/contour, Plot_ip=0
; for Stewart's paper Fig. 3:
IDL> !p.font=0
IDL> setup_ps,'MPTS_138844.ps', printer='postscript color'
IDL> plot3_mpts, 138844, /GPI,tmin=.45, tmax=.85, $
Temax=1.2, Line_TeMax=2, Nemax=8, /NoBigLabels, $
/contour, Plot_ip=0, /Plot_NeL, /Plot_Te, $
charsize=1.5, BARSZ_CHARS=3, /magAxis
IDL> unsetup_ps
IDL> !p.font=0
IDL> setup_ps,'MPTS_138843.ps', printer='postscript color'
IDL> plot3_mpts, 138843, tmin=.45, tmax=.85, $
Temax=1.2, Line_TeMax=2, Nemax=8, /NoBigLabels, $
/contour, Plot_ip=0, /Plot_NeL, /Plot_Te, $
charsize=1.5, BARSZ_CHARS=3, /magAxis
IDL> unsetup_ps
IDL> for shot=138844,138847 do plot3_mpts, shot, /GPI, $
tmin=.45, tmax=.85, r1=1.2,r2=1.56, /contour, Plot_ip=0, $
efile='PDF'
IDL> for shot=138844,138847 do $
plot3_mpts, shot, /GPI, /Sep, $
tmin=.3, tmax=.9, r1=1.25,r2=1.5, /contour, $
Plot_ip=0, c_colors=[115,110,100,50,30,20,10], /debug
IDL> for shot=138844,138847 do $
plot3_mpts, shot, /GPI, /Sep, $
tmin=.45, tmax=.85, r1=1.35,r2=1.5, /contour, $
Plot_ip=0, c_colors=[115,110,100,50,30,20,10], /debug
to make a post script plot:
IDL> !p.font=0
IDL> setup_ps,'Plot3_MPTS.ps', printer='postscript color'
IDL> plot3_mpts, 138846, /GPI,tmin=.45, tmax=.85, r1=1.2, r2=1.56, $
/contour
IDL> unsetup_ps
NOTES:
MODIFICATION HISTORY:
06-May-2014 added MagAxis keyword to allow like for magnetic axis
10-Oct-2013 EFIT keyword was not getting to sepvstime for edge
09-Oct-2013 if just GPI in bottom frame, make smaller than other 2
30-May-2013 added GPI option for Stewart Zweben
31-Aug-2010 moved PNB read to end, because opening tree takes ~12s !
29-Jul-2010 added LastPoint and lastTime keywords
15-Jul-2010 added xmargin keyword for wall display
05-Nov-2009 handle no times or deltaT entered.
14-Apr-06 Added default to mail PDF file if e-mail checked and user specified.
26-Jan-06 No longer e-mail to 'USER' if username not specified
Tidy up screen message for postscript output
19-Jul-04 Added emailPsFile and emailPsAddress keywords
WRITTEN November, 2003, by Bill Davis.
NAME:
plotdash
PURPOSE:
Plot a variety of dashed lines, even if terminal emulator doesn't for
different linestyles
CATEGORY:
2-D Plotting
CALLING SEQUENCE:
IDL> plotdash, x, y, dashfracdashfrac=, blankfrac=blankfrac
INPUTS:
x - x data to plot
y - y data to plot
KEYWORD PARAMETERS:
Optional:
dashfrac - fraction of distance (0-1) dash will be (def=0.01)
blankfrac - fraction of distance (0-1) blank will be
smallFrac - fraction of distance (0-1) for a small dash, or a dot.
OUTPUTS:
COMMON BLOCKS:
NONE
NOTES:
This will probably be slow for large numbers of points.
EXAMPLE:
x = findgen(100)
y = sin(x/5)
plotdash, x, y
plotdash, x, y, dashfrac=.02, blankfrac=.01
oplotdash, x, y/2, dashfrac=.02, blankfrac=.01, color=mk_color('red')
y = randomu(seed,100)
plotdash, x, y
plotdash, x, y, dashfrac=.02, smallFrac=0.005, blankfrac=.002
plotdash, x, y, dashfrac=.02, smallFrac=0.002, blankfrac=.005
MODIFICATION HISTORY:
17-Apr-2012 added smallFrac keyword, so can have dot-dash style lines
16-Apr-2012 Written by Bill Davis, PPPL
NAME:
shade_surfrange
PURPOSE:
make SHADE_SURF plots with x & y ranges (correctly)
CATEGORY:
2-D Plotting
CALLING SEQUENCE:
shade_surfrange, f, x, y, XRANGE=xrange, YRANGE=yrange, _EXTRA =_extra
INPUTS:
f, x & y are just as for surf in
KEYWORD PARAMETERS
Input:
XRANGE - array containing min x & max x
YRANGE - array containing min y & max y
ZRANGE - array containing min y & max y
_EXTRA - standard idl EXTRA keyworrd
OUTPUTS:
none
EXAMPLE:
x=findgen(100)
y=x
f=DIST(100)
_EXTRA = { title: 'My Title', $ ; pass any extra SHADE_SURF keywords here
xtitle: 'seconds', $
ax : 40 }
shade_surfrange, f, x, y, xrange=[20,40], yrange=[50,70], _EXTRA =_EXTRA
COMMON BLOCKS:
NOTES:
If your are using color tables with reserved colors at the the top,
e.g., if you use mk_color, you should first call:
IDL> dum=mk_color(n_nonfixed=ncolors)
IDL> set_shading, values=[0,ncolors-1]
skirt doesn't seem to work
MODIFICATION HISTORY:
09-Jul-02 Handle when yrange or xrange reversed (i.e., first > last)
17-Aug-01 Handle correctly when !z.range set
17-Oct-00 Written by Bill Davis
NAME:
SHOW3m
PURPOSE:
Show a 2D array three ways in a display that combines SURFACE,
CONTOUR, and an image (color/gray scale pixels).
CATEGORY:
2-D Plotting, Graphics, Image Processing.
CALLING SEQUENCE:
SHOW3m, Image [, INTERP = Interp, SSCALE = Sscale]
INPUTS:
Image: The 2-dimensional array to display.
OPTIONAL INPUTS:
X = a vector containing the X values of each column of Image.
If omitted, columns have X values 0, 1, ..., Ncolumns-1.
Y = a vector containing the Y values of each row of Image.
If omitted, columns have Y values 0, 1, ..., Nrows-1.
KEYWORD PARAMETERS:
INTERP: Set this keyword to use bilinear interpolation on the pixel
display. This technique is slightly slower, but for small
images, it makes a better display.
SSCALE: Reduction scale for surface. The default is 1. If this
keyword is set to a value other than 1, the array size
is reduced by this factor for the surface display. That is,
the number of points used to draw the wire-mesh surface is
reduced. If the array dimensions are not an integral multiple
of SSCALE, the image is reduced to the next smaller multiple.
E_CONTOUR: a structure containing additional keyword parameters
that are passed to the CONTOUR procedure. See the example
below.
E_SURFACE: a structure containing additional keyword parameters
that are passed to the SURFACE procedure. See the example
below.
TITLE: Top plot title
XTITLE: x-axis title
YTITLE: y-axis title
FLOOR: if = 0, will not show color contours on floor
CHARTHICK; character thickness on color bar
DRAWLINES: draw lines to indicate a region of interest
DRAWBOX : draw box around region of interest
BOXYMID: y-mid point of box, an line location (default=0.1)
BOXXMID: x-mid point of box, an line location (default=1)
BOXWIDTH: width of box (default=0.1)
BAR: if = 0, will not draw color bar
C_COLOR: colors for contours
OUTPUTS:
No explicit outputs.
EXAMPLE:
IDL> gp, '/u/bdavis/MarthRedi/kineticballooning.txt'
SIDE EFFECTS:
A new plot is generated.
RESTRICTIONS:
The display gets too "busy" when displaying larger (say 50 by 50),
images, especially if they are noisy. It can be helpful to use
the SSCALE keyword or the SMOOTH and/or REBIN functions to smooth the
surface plot.
You might want to modify the calls to CONTOUR and SURFACE slightly
to customize the display to your tastes, i.e., with different colors,
skirts, linestyles, contour levels, etc.
PROCEDURE:
First, do a SURFACE with no data to establish the 3D to 2D scaling.
Then convert the coordinates of the corner pixels of the array to
2D. Use POLYWARP to get the warping polynomial to warp the
2D image into the area underneath the SURFACE plot. Output the image,
output the surface (with data) and then output the contour plot at
the top (z=1).
EXAMPLES:
A = BESELJ(SHIFT(DIST(30,20), 15, 10)/2.,0) ;Array for example
SHOW3, A ;Show it with default display.
SHOW3, A, SQRT(FINDGEN(30)) ;Make X axis proportional to sqrt
SHOW3, A, E_CONTOUR={C_CHARSIZE:2, DONW:1} ;Label CONTOUR lines with
double size characters, and include downhill tick marks.
SHOW3, A, E_SURFACE={SKIRT:-1, ZRANGE:[-2,2]} ;Draw a surface with
a skirt and scale Z axis from -2 to 2.
MODIFICATION HISTORY:
DMS. Jan, 1988.
Added fudges for PostScript, April, 1988.
Fixed bug where contour plot was occasionally clipped. Dec, 1990.
Added optional axis variables, and _EXTRA keywords for CONTOUR,
and SURFACE. Jan, 1996.
DD. Added code to ignore !ORDER for the TV of the image. Mar 1997.
SJL Fixed bug from scaling with polywarp. July, 1998.
DD. Add better support for TrueColor devices.
Honor !P.BACKGROUND (rather than assuming black or white
background). Sept, 2000.
Feb/2005 hacked by Bill Davis for Martha Redi:
better scaling of bottom image. Added lines and a square to indicate region.
When bottom values are zero, make white (transparent). Add color bar.
NAME:
surfrange
PURPOSE:
make SURF plots with x & y ranges (correctly)
CATEGORY:
2-D Plotting
CALLING SEQUENCE:
surfrange, f, x, y, XRANGE=xrange, YRANGE=yrange, _EXTRA =_extra
INPUTS:
f, x & y are just as for surf in
KEYWORD PARAMETERS
Input:
XRANGE - array containing min x & max x
YRANGE - array containing min y & max y
ZRANGE - array containing min y & max y
_EXTRA - standard idl EXTRA keyworrd
OUTPUTS:
none
EXAMPLE:
x=findgen(100)
y=x
f=DIST(100)
_EXTRA = { title: 'My Title', $ ; pass any extra SURF keywords here
xtitle: 'seconds', $
ax : 40 }
surfrange, f, x, y, xrange=[20,40], yrange=[50,70], _EXTRA =_EXTRA
COMMON BLOCKS:
NOTES:
logic is still not perfect. See, e.g.,
AUSER4:[BDAVIS.TEST.NDD]NDD3D.PRO for a working example of overlaying
surface plot on a shaded surface plot with ranges set.
MODIFICATION HISTORY:
09-Jul-02 Handle when yrange or xrange reversed (i.e., first > last)
17-Aug-01 Handle correctly when !z.range set
17-Oct-00 Written by Bill Davis
NAME:
TH_IMAGE_CONT
PURPOSE:
Plot contours of Images with both contour lines and colors
CATEGORY:
2-D Plotting
USAGE:
******************** HIGH FREQUENCY RADAR DIVISION, SRL **********************
*************************** Ionospheric Effects ******************************
HELP
1 TH_IMAGE_CONT
Overlays an image and a contour plot and optionally adds a scale bar.
Based on the IDL USERLIB routine IMAGE_CONT. This routine supersedes
the USERLIB one, having far more functionality, yet capable of EXACTLY
reproducing the effect of IMAGE_CONT. Scale bar appears on the
right-hand-side unless /NOBAR is set. NB: the scale bar is
automatically created by a recursive call to this routine using the
same color and image parameters
Format:
In its simplest form (allowing all parameters to default)
IDL> TH_IMAGE_CONT, IMAGE
or,
IDL> TH_IMAGE_CONT, IMAGE, X, Y
And in its most complex form, specifying ALL parameter
IDL> TH_IMAGE_CONT, IMAGE, $
ASPECT=aspect, $
BADPTS=badpts,$
BAR_LABEL_LENGTH=bar_label_length, $
BAR_RANGE=bar_range, $
BAR_SEPARATION=bar_separation, $
BAR_TICKLEN=bar_ticklen, $
BAR_TICKNAME=bar_tickname, $
BAR_TICKS=bar_ticks, $
BAR_TICKV=bar_tickv,$
BARSZ_CHARS=barsz_chars, $
BOTTOMcolor=bottomcolor,$
C_COLORS=c_colors,$
C_LINESTYLE=c_linestyle, $
C_THICK=c_thick, $
CONGRID=congrid, $
CONT=cont, $
CRANGE=crange, $
CT=ct, $
CUBIC=cubic, $
DEBUG=debug, $
EXACT=exact, $
RAISE_PTITLE=raise_ptitle
IMAGE_WINDOW=image_window, $
INTERP=interp,$
LEVELS=levels,$
MAX_VALUE=max_value, $
NLEVELS=nlevels, $
NOBAR=nobar, $
NOCONT=nocont, $
NOERASE=noerase,$
TOPcolor=topcolor,$
TSIZE=tsize, $
WINDOW_SCALE=window_scale, $
XRANGE=xrange, $
YRANGE=yrange
2 IMAGE
2-dimensional array to display as an image.
2 /ASPECT
set to retain image's aspect ratio. Assumes square
pixels. If /WINDOW_SCALE is set, the aspect ratio is retained.
2 BADPTS
indices into IMAGE data which define the bad points.
These will not be contoured
2 BAR_LABEL_LENGTH
the space, in characters (default = 2), for the bar label
2 Btitle
Bar title
2 BAR_RANGE
set the range limits for the color scale bar
(same as CRANGE, defaults to autoscaling if
BAR_TICKV not set)
2 BAR_SEPARATION
the separation, in characters (default = 2), between the scale
bar and the image. Note that the |y-ticklength| will be added
to this value if y-ticklength < 0.
Both the image and the color bar need to fit
into the space allowed for the plot window, otherwise an
informative message will be printed and unpredictable results
may occur for the displayed image
2 BAR_TICKS
set the number of tick intervals for the labelling
of the scale bar
(defaults to !z.ticks)
2 BAR_TICKV
the values to label on the scale bar. If this is set
then the scale bar will have AT LEAST this range
(defaults to !z.tickv)
2 BAR_TICKNAME
the labels to use on the scale bar
(defaults to !z.range)
2 BAR_TICKLEN
the length of the ticks on the scale bar in fractions of tick
bar window, (defaults to !z.ticklen)
2 BARSZ_CHARS
the size of the scale bar in characters (default = 2).
Both the image and the color bar need to fit
into the space allowed for the plot window, otherwise an
informative message will be printed and unpredictable results
may occur for the displayed image. If the value of this
keyword is <=0 then no bar will be displayed BUT the scaling
and window size will be calculated as those a color bar is to
be used. This is useful when doing multiple plots per page
where only some scale bars are not required but you want the
plots to all be the same size. Set BARSZ_CHARS = -#chars to
allow room for a bar of #chars size but not to put a scale bar
on the plot. Then set BARSZ_CHARS = +#chars to plot the bar on
alongside another plot, to end up with images of the same
size. Useful in collaboration with the SIDES procedure (which
will set flags for when the plot is on the Left,Right,Top and
Bottom of the plot window).
2 BOTTOMcolor
Set this keyword to the color index of the desired bottom
color (range from 0 to TOPcolor-1).
Note that the default value for this keyword is 1,
which allows the color of the image to
be independent of the background and axes colors
(!P.background and !P.color). If the user sets this keyword
then allowance should be made for these colors as they are
generally swapped for POSTSCRIPT and X-Window devices
2 /CONGRID
if the image has to be resampled then use the USERLIB CONGRID
routine
2 /CONT
only do the contouring (no image)
2 CRANGE
set the range limits for the color scale bar
(same as BAR_RANGE, defaults to autoscaling if
BAR_TICKV not set)
2 CT
load a color table (uses LOADCT via MK_COLOR)
2 /CUBIC
if the image has to be resampled AND interpolated then use the
CUBIC interpolation rather than the bi-linear (see INTERP
Keyword)
2 /DEBUG
write out some inforamtion as it goes
2 /EXACT
When set this will force the contour routine to fit to the
exact positions relative to the image.
When data is displayed as an image each datum is expanded out
to fill a pixel of finite dimensions. The assignment of where
the "data value" resides within this space is open to debate,
but is most appropriately (to this author) assigned to the
geometric centre of the pixel. Most defaults assign this
position to be at the bottom left-hand corner of the
pixel. Contour will fit to the 2-d plane assuming that the
data value is associated with the bottom left-hand corner. To
reconcile this with the notion of the value being in the
middle of the pixel the contour call is made with the x/y
values and ranges for the image adjusted (effectively by half
a pixel in the x/y directions). This is the EXACT mapping. By
default, the mapping will be the default contour one.
2 RAISE_PTITLE
Raise the plot title by this many character units above the
plot to allow room to put a label on the top x-axis. Default
is raise by 1 char. If not called then the default y-position
is 1 char unit above plot (allowing room for xticks, and
scaled by !P.charsize)
2 IMAGE_WINDOW
the position of the image window. Can be used to set
!p.position so you can over-plot the image.
(Only useful when the scale-bar has been used)
2 /INTERP
set to bi-linear interpolate if image is resampled.
(see also the CUBIC keyword)
2 /NOBAR
dont put a scale bar on the right-hand-side
2 /NOCONT
only do the imaging (no contours)
2 /NOERASE
dont erase the previous plot
/NOLOAD
if set, do not load color table
2 TOPcolor
Set this keyword to the color index of the desired bottom
color (range from BOTTOMcolor+1 to !D.n_colors-1). Note that
the default value for this keyword is !D.n_colors-2, which
allows the color of the image to be independent of the
background and axes colors (!P.background and !P.color). If
the user sets this keyword then allowance should be made for
these colors as they are generally swapped for POSTSCRIPT and
X-Window devices
2 TSIZE
size of the plot title (default = 1)
2 /WINDOW_SCALE
set to scale the window size to the image size,
otherwise the image size is scaled to the window size.
Ignored when outputting to devices with scalable pixels.
2 XRANGE
will set the ranges for the x-axes labelling
2 YRANGE
will set the ranges for the y-axes labelling
2 Contour
most of the CONTOUR parameters are passed directly
2 Examples
IDL> th_image_cont, image
IDL> th_image_cont, image, /nocont, /nobar
IDL> !p.title = "!17 This is an example of what can be done!3"
IDL> !x.title = "X Title" & !y.title = "Y Title" & !z.title = "Z Title"
IDL> !x.ticklen = -0.02 & !y.ticklen = -0.02 & !z.ticklen = -0.02
IDL> !p.charsize = 1.5
IDL> levels = findgen(5)*2
IDL> image = findgen(20,20)/40.
IDL> th_image_cont, image, crange=[0,10], /follow, level=levels, $
tsize=1.5*!p.charsize, bar_tickv=levels
2 Error_responses
Returns to the calling procedure on an error
2 Limitations/Assumptions
The currently selected display is affected.
If the device has scalable pixels then the image is written over
the plot window.
As with all TV style image displays, the axes range is independent of
the image, so it is up to the user the ensure correct labelling of the
axes.
NOTE: if the user aborts while this routine is processing then the
system variables (in particular !p.position) will have
been changed, causing subsequent plots to appear different. Issue the
command "resetplt,/all" to reset all the system variables back to the
startup state.
NOTE: if x or y does not have a constant interval, the image will be
wrong. Instead, use contour, /fill...
2 References
See USERLIB IMAGE_CONT
2 Keywords
Graphics images contours
2 MODIFICATIONS:
-------------
12-Dec-2013 added barlabel keyword
05-Sep-2013 if /NoLoad set, use values in common block from mk_colors (if set)
for max values
07-Jun-2013 make /EXACT the default
27-Jul-2012 tweeked color table handling. Add rainbow keyword.
07-Jan-2010 print error if input not 2-D array
06-Jun-2006 several changes including adding x & ytickformat keywords
06-Apr-2006 limit max dimension of interpolated postscript plots to 2000 pixels
14-Mar-2006 added zrange keyword [BD]
25-Oct-01 Made Contours work when /ASPECT set. Made Contours work when
XRANGE or YRANGE set.
18-Apr-00 Made interpolated image align with data. /EXACT does not give
an exact representation. Warn if style=2
06-Dec-99 Added another pixel to TV image size, so it fills the grid square
23-Aug-99 Allow Contour, Z, X, Y format. Use MK_COLOR
07-Jan-98 BD allow more space at the bottom and right-hand side for text
(keyword BAR_LABEL_LENGTH added)
07-Aug-97 Bill Davis- v. 2.24
[1] added _extra call to main CONTOUR and removed
it from those making the bar.
(more modifications in file)
NAME:
TVIMAGE_CONGRID
PURPOSE:
Shrink or expand the size of an array by an arbitrary amount.
This IDL procedure simulates the action of the VAX/VMS
CONGRID/CONGRIDI function.
This function is similar to "REBIN" in that it can resize a
one, two, or three dimensional array. "REBIN", however,
requires that the new array size must be an integer multiple
of the original size. CONGRID will resize an array to any
arbitrary size (REBIN is somewhat faster, however).
REBIN averages multiple points when shrinking an array,
while CONGRID just resamples the array.
CATEGORY:
2-D Plotting
CALLING SEQUENCE:
array = TVIMAGE_CONGRID(array, x, y, z)
INPUTS:
array: A 1, 2, or 3 dimensional array to resize.
Data Type : Any type except string or structure.
x: The new X dimension of the resized array.
Data Type : Int or Long (greater than or equal to 2).
OPTIONAL INPUTS:
y: The new Y dimension of the resized array. If the original
array has only 1 dimension then y is ignored. If the
original array has 2 or 3 dimensions then y MUST be present.
z: The new Z dimension of the resized array. If the original
array has only 1 or 2 dimensions then z is ignored. If the
original array has 3 dimensions then z MUST be present.
KEYWORD PARAMETERS:
INTERP: If set, causes linear interpolation to be used.
Otherwise, the nearest-neighbor method is used.
CUBIC: If set, uses "Cubic convolution" interpolation. A more
accurate, but more time-consuming, form of interpolation.
CUBIC has no effect when used with 3 dimensional arrays.
MINUS_ONE:
If set, will prevent CONGRID from extrapolating one row or
column beyond the bounds of the input array. For example,
If the input array has the dimensions (i, j) and the
output array has the dimensions (x, y), then by
default the array is resampled by a factor of (i/x)
in the X direction and (j/y) in the Y direction.
If MINUS_ONE is present (AND IS NON-ZERO) then the array
will be resampled by the factors (i-1)/(x-1) and
(j-1)/(y-1).
HALF_HALF:
If set, will tell CONGRID to extrapolate a *half* row
and column on either side, rather than the default of
one full row/column at the ends of the array. If you
are interpolating images with few rows, then the
output will be more consistent with this technique.
This keyword is intended as a replacement for
MINUS_ONE, and both keywords probably should not be
used in the same call to CONGRID.
OUTPUTS:
The returned array has the same number of dimensions as the original
array and is of the same data type. The returned array will have
the dimensions (x), (x, y), or (x, y, z) depending on how many
dimensions the input array had.
PROCEDURE:
IF the input array has three dimensions, or if INTERP is set,
then the IDL interpolate function is used to interpolate the
data values.
If the input array has two dimensions, and INTERP is NOT set,
then the IDL POLY_2D function is used for nearest neighbor sampling.
If the input array has one dimension, and INTERP is NOT set,
then nearest neighbor sampling is used.
EXAMPLE:
; vol is a 3-D array with the dimensions (80, 100, 57)
; Resize vol to be a (90, 90, 80) array
vol = TVIMAGE_CONGRID(vol, 90, 90, 80)
MODIFICATION HISTORY:
DMS, Sept. 1988.
DMS, Added the MINUS_ONE keyword, Sept. 1992.
Daniel Carr. Re-wrote to handle one and three dimensional arrays
using INTERPOLATE function.
DMS, RSI, Nov, 1993. Added CUBIC keyword.
Craig Markwardt, Dec, 1997. Added halfhalf keyword to
more evenly distribute "dead" pixel row
Use uniformly spaced grid points for half_half W. Landsman Feb. 2000
(and slightly modified by C. Markwardt 14 Feb 2000)
DWF, FSC, 22 Apr 2007. Modified the program so that 3D arrays use nearest-neighbor
interpolation unless the INTERP keyword is set.
DWF, FSC, 22 Apr 2007. Function renamed from CMCONGRID to TVIMAGE_CONGRID on
recommendation of Craig Markwardt as he wants no part of this. :-)
NAME:
vectorsurf
PURPOSE:
Shows a fancy way to plot irregulary spaced data from x,y & z vectors.
CATEGORY:
2-D Plotting, Example
CALLING SEQUENCE:
vectorsurf, x, y, z
INPUTS:
tag - MDSplus tag or node name in
KEYWORD PARAMETERS
Input:
DRAWXSIZE = drawXsize
DRAWYSIZE = drawYsize
BG_COLOR = bg_color
OUTPUTS:
none
EXAMPLE:
IDL> x=[4,6,1,7,1,8,5,2,4]
IDL> y=[3,3,1,6,4,5,6,8,1]
IDL> z=sqrt((x-3)^2+(y-2)^2)+randomn(seed)+2
IDL> vectorsurf, x, y, z
MODIFICATION HISTORY:
05-Sep-97 Written by Bill Davis
from IDL's d_mathstat.pro in the IDL 5.0 release
Written by: DC, RSI, 1995
Category: Animation
[List of Routines]
NAME:
alphamovie10
PURPOSE:
Plot every 10th frame in time, and overlay
10 d-alpha traces. Have a marching vertical line indicating time
in a plot indicating the Strike Point Radius.
CATEGORY:
Animation, NSTX
CALLING SEQUENCE:
IDL> d=alphamovie10( 138000, tStart=tStart, tEnd=tEnd )
INPUTS:
shot = NSTX shot number
KEYWORD PARAMETERS:
Inputs:
tStart -
tEnd -
rMin - minimum time to display (DEFAULT: 25 )
rMax - minimum time to display (DEFAULT: 85 )
inc - how many D-alpha traces to put on a plot
efit -
xsize - horizontal size of X window (DEFAULT: 600 )
ysize - vertical size of X window (DEFAULT: 450 )
xpos - initial X position of lower left of X window in pixels
ypos - initial Y position of lower left of X window in pixels
charsize - size of characters on plot (Default: 1.5)
verbose - if set, will print many informational messages
debug - if set, will stop before returning
OUTPUTS:
MPEGS can be saved from the IDL Animation Widget interface
EXAMPLE:
IDL> d=alphamovie10( 138000, /verb )
NOTES:
This routine uses X-memory, so too many frames can cause X errors.
Try reducing the number of frames or xsize and ysize.
MODIFICATION HISTORY:
19-Jul-2010 put into xinteranimate by Bill Davis
20-Apr-2010 written by Josh Kallman. cam4_fy10 written by Vlad.
NAME:
anim2cine
PURPOSE:
Create an mpeg or avi movie from two .cin files from Phantom Cameras.
The data can be color or monochrome
CATEGORY:
animation
CALLING SEQUENCE:
anim2cine, CineFile1, CineFile2, movieFile=movieFile, t1=t1, t2=t2
INPUTS:
CineFile1 - cine file
CineFile2 - (optional)
-
OPTIONAL KEYWORD PARAMETERS:
movieFile - name of output MPEG or QuickTime file (will default to a nice name), or
prefix - what would precede _shot_t1_t2 (in msec) in the output filename
t1 - start time of animation in seconds
t2 - end time of animation in seconds
VIEW - if set, just displays images, and does not make an mpeg
ndups - if given means repeat every image 'ndups' times
despeckle - if set call despeckle routine (slow, but less "intrusive"
than median)
nSmooth - number input to median smoothing routine for camera data
sigSmooth - number input to median smoothing routine for signal data
topPixels -
botPixels -
charsize - character size for plots. Default=2
ctb - color table for non-color image
label1 - label on plot for CineFile1 (default='Monochrome')
label2 - label on plot for CineFile2 (default='Color')
gamma1 - gamma setting for camera 1
gamma2 - gamma setting for camera 2
saturation1 - saturation setting for camera 1, if color
saturation2 - saturation setting for camera 2, if color
min1 - minimum value for bytescaling camera 1
min2 - minimum value for bytescaling camera 2
max1 - maximum value for bytescaling camera 1
max2 - maximum value for bytescaling camera 2
region1 - crop region to display for camera 1
region2 - crop region to display for camera 2
byteScale - if set, will scale
sigName - if set, will not show Fast Camera images, but this
signal vs. time (defaults to \passivespec::BAYC_DALF_HAIFA)
sigT1 - starting time of signal vs. time plot
sigT2 - ending time of signal vs. time plot
sigTitle - if set, will be displayed above sigName plot,
else tries to get label from MDSplus
verbose - if set will print out info as it works
OUTPUTS:
an MPEG file named by movieFile keyword
EXAMPLE:
anim2cine,camera1="Phantom710-9206", camera2="Phantom73-6663", shot=138767, $
sig1='\wf::ip',sig2='\wf::nel', t1=.405, t2=.406, $
gamma1=.37, min1=20, max1=1442, $
gamma2=.8, sat2=.3, max2=1440, rot2=1 ,/debug
anim2cine,camera1="Phantom710-9206", camera2="Miro2-7988", shot=138767, $
sig1='\wf::ip',sig2='\wf::nel', t1=.405, t2=.406, $
gamma1=.37, min1=20, max1=1442, $
gamma2=.3, sat2=.3, max2=255 ,/debug
f1=findcamfiles('nstx_1_135258.cin')
f2=findcamfiles('Miro_135258.cin')
anim2cine,f1,f2,t1=.17,t2=.53, inc=10, mag1=2, mag2=3, $
region1=[.08,.05,1,1], region2=[.1,.0, 1.0,.9], $
sig1='\operations::mi_h908_01:input_03*(-1.6)', sig2='\wf::prf', $
Units1='mTor', /QUICKTIME, sigLabel1='Antenna Power', /debug
anim2cine, camera1='Phantom710-9206', camera2='Miro2-7988', $
shot=140000, t1=0.2, t2=0.3, sigT1=0.0, sigT2=1.0, $
sig1='\wf::ip', sig2='\wf::pnb', nSmooth=5, /verbose , /debug
anim2cine, 'NSTX_130387.cin', $
'MIRO_130387.cin', $
t1=0.1, t2=1.4, sig1='\wf::ip', sigTitle='Plasma Current', /verbose
anim2cine, shot=130370, t1=0.5, t2=0.58, /verbose, /view , /debug
f1=findcamfiles('nstx_1_135254.cin')
f2=findcamfiles('Miro_135254.cin')
anim2cine,f1,f2,t1=.180,t2=.580, inc=10, $
movieFile='NSTX_135254_180-580ms.mpg', mag1=2, mag2=3 , /debug
f1='/p/nstxcam-archive/Phantom71-5040/2009/nstx_1_135254.cin'
f2='/p/nstxcam-archive/Miro2-7988/2009/Miro_135254.cin'
anim2cine,f1,f2,t1=.180,t2=.580, inc=10, $
region1=[.08,.05,1,1], region2=[.1,.0, 1.0,.9], $
movieFile='NSTX_135254_180-580ms.mpg', mag1=2, mag2=3 , /debug
f1=findcamfiles('nstx_1_136159.cin') ; fastest one
f2=findcamfiles('Miro_136159.cin')
anim2cine, f1,f2, mag2=2, $
label1='Full', label2='Dropper View', $
gamma1=0.096, min1=65, max1=4095, $
gamma2=1.188, min2=1114, max2=11075 , /debug
mv files to /w/nstx.pppl.gov/htdocs/nstx/Software/Diagnostics/FC2008
(or whatever year) for web viewing at
http://nstx.pppl.gov/nstx/Software/Diagnostics/
MODIFICATION HISTORY:
08-Dec-2011 added flip1 and flip2 keywords (also made work with just 1 file)
31-Aug-2010 lots of changes to allow to work off web tool nstxmovie.html
01-Jul-2010 added region1 and region2 keywords and allow different
magnifications for different cameras
08-Oct-2009 updates for 2009 cameras. Extract shot # from filenames,
if not input
12-Nov-2008 mods because cineload now assuming frame 0 is beginning of data
16-Jul-2008 Use Z-buffer, even when viewing, for smoother displays
15-Jul-2008 Written by Bill Davis
NAME:
animxyplot
PURPOSE:
Animate X-Y plot of a 2-D array
CATEGORY:
Animation
CALLING SEQUENCE:
IDL> animxyplot, data2d, x, time [, ....]
INPUTS:
data2d - 2 d array (1st dimension like x, 2nd like time)
x - array for x-axis of x-yplot
time
KEYWORD PARAMETERS:
(can have any keywords used in PLOT command -- will be passed on)
mpeg - if set, will create an mpeg of animation
filename - name of mpeg file (default = 'plotanimation.mpg')
rep - # number of times to repeat frames (to slow down mpeg) default=0
t1 - time to start animation (indexes into time array) (default=start)
t2 - time to end animation (default=end)
xtitle -
ytitle -
xsize - xsize of window in pixels
ysize - ysize of window in pixels
flip - if set, will flip mpeg image
timeTitle - appended to indication of time on plot (def='Sec.')
pause - # of seconds to pause between plotted frames when creating
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
NONE; just the mpeg file, if specified
EXAMPLE:
nframes = 20
nPts = 1000
data2d = fltarr(npts, nframes)
time = findgen(nFrames)/1000 +0.2
x =findgen(npts)/npts*150 + 50
for i=0,nframes-1 do data2d[0,i]=sin(x*5/max(x)+i/10.)*exp(1.-x/100-i/10.)
animxyplot, data2d, x, time, xtitle='Radii', ytitle='Value', /mpeg
NOTES:
MODIFICATION HISTORY:
18-Jan-2008 Written by Bill Davis, PPPL
NAME:
cine2mpeg
PURPOSE:
Create a movie from a .cin files from Phantom Fast Cameras.
Will default to writing jpegs and spawning jmovie to create a
QuickTime movie. If /MPEGout keyword set, will write an MPEG.
The data can be color or monochrome,
CATEGORY:
animation
CALLING SEQUENCE:
cine2mpeg, CineFile1, outFile=outfile, t1=t1, t2=t2, ndups=ndups
or
cine2mpeg, shot=shot, t1=t1, t2=t2, /verbose
INPUTS:
CineFile1 - a cine filename
shot - if used instead of filename, it will search appropriate directories.
OPTIONAL KEYWORD PARAMETERS:
outFile - name of output MPEG file (will default to a nice name), or
prefix - what would precede _shot_t1_t2 (in msec) in the output filename
t1 - start time of animation in msec
t2 - end time of animation in msec
MPEGout - if set will create an MPEG movie
FramesOut - if=0, will not create QuickTime movie
VIEW - if set, just displays images, and does not make an mpeg
ndups - if given means repeat every image 'ndups' times
despeckle - if set call despeckle routine (slow, but less "intrusive"
than median)
badValue - if data is this or above, replace with median of surrounding pixels
nSmooth - number input to median smoothing routine
gamma - gamma correction. (Default=1, which is no correction).
0.5 probably better for Miro
saturation - As in HSV color representation, for color camera.
Default is 0.3.
topPixels -
botPixels -
AveT1 - start time of range for Average Frame in msec
AveT2 - end time oof range for Average Frame in msec
manifold - if set, will draw line for manifold positon
charsize - character size for labels. Default=1.5
ctb - color table for non-color image
label - label on plot
horizontal_flip - if set, flip images horizontally
vertical_flip - if set, flip images vertically
byteScale - if set, will scale
minVal - if this and byteScale set, will use this as minimum value
maxVal - if this and byteScale set, will use this as maximum value
inc - default 1o 1; use every "inc"th frame
noCaption - do not put text on or above image
Rotate - integer from 0-3, passed to IDL ROTATE function
verbose - if set will print out info here and there
OUTPUTS:
an MPEG file named by outFile keyword
NOTES:
*** you have to be careful with MAXVAL. If too big, all frames will be black
EXAMPLE:
cine2mpeg, '/p/nstxcam-archive/Miro2-7988/2008/MIRO_130389.cin', $
t1=0.02, t2=0.0300, /verbose , /debug
cine2mpeg, shot=130277, t1=0.100, t2=0.200, /verbose, /view , /debug
cine2mpeg, GETENV("NSTXUSR")+'/phantom4/GDNex10usFps27000DC110maP1.98torr-1.cin', $
outfile='Ne110us.mpg', t1=.0007, t2=0.0017, ndups=4, mag=3
minHt and maxChi2 are the most useful to adjust:
blobCriteria = { minHt : 1.2, $
maxChi2 : 3., $
maxFrames : 1, $
maxJump : 10, $
minArea : 9, $
minLifetime : 3, $
maxAreaChange : 100, $
minRise : 0.02 $
}
cine2mpeg,'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138234.cin',$
aveT1=0.530, aveT2=0.550, t1=0.532, t2= 0.5326, /blobs, $
blobCriteria=blobCriteria, $
colorTable=3, min=256, /surface, /RotCC, /arrow , /view,/debug
cine2mpeg,'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138234.cin',$
aveT1=0.530, aveT2=0.550, t1=0.530, t2= 0.5302, /blobs, $
colorTable=3, minWidth=256, /surface, /horiz, /RotCC, /arrow , /view,/debug
; to test drawing plasma EDGE and limiter shadow:
cine2mpeg,'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138234.cin',$
aveT1=0.530, aveT2=0.550, t1=0.530, t2= 0.5301, $
colorTable=3, minWidth=256, /horiz, /RotCC, /arrow, /EDGE , /view,/debug
mv files to /w/nstx.pppl.gov/htdocs/nstx/Software/Diagnostics/Miro/GlobalMPEGs
for web viewing at
http://nstx.pppl.gov/nstx/Software/Diagnostics/Miro/GlobalMPEGs
for Stewart's FY15 GPI paper:
IDL> cinethumbnails, /edge, $
nSmooth=3, Rotation=1, /horiz, xSize=668*10./8+80, ySize=652*.666, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_140395.cin', $
/rainbow, border=3, /ellip, nWanted=10, nrows=2, howFar=.1, /norm, $
bytescale=0, aveT1=.5505, aveT2=.5515, minVal=0.405, maxVal=2.159, $
/colorbar, t1=.550929, t2=.551029, label=0,/verbose
cine2mpeg,'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_140395.cin', $
aveT1=550.5, aveT2=551.5, t1=550.929, t2=550.95, $ ;;;t2= 551.019, $
/ellip, /horiz, /rotccw, howFar=0.1, $
ctb=3, minWidth=256 ;;;, /view
MODIFICATION HISTORY:
09-Apr-2015 added ellipses keyword for Stewart Zweben GPI paper
04-Feb-2015 using cgImage and cgSnapshot instead of TV and TVRD so color
JPEGS easy.
12-Mar-2014 added Fit keyword for separatrix calculation
15-Oct-2013 BIG CHANGE: Bytescale with minVal & maxVal, unless showMax
defined
08-Oct-2013 added manifold-showing option. New limiter position
06-Mar-2013 black out top and bottom after drawing separatrix
05-Mar-2013 if bytescale set, don't use maxVal and minVal to scale image
25-Oct-2012 added showNumbers, xvals, and yvals, for suppressing blob #s and
having surface axes in cm.
27-Mar-2012 use fastcam_times and fastcam_frame so can support HDF files from simulation
12-mar-2012 moved smoothing out of cine2mpeg, and let be done in findblobs,
like other apps doing. Have time inputs in msec. Default to Gaussian smoothing
24-Feb-2012 added gaussian smoothing option
23-Feb-2012 many adjustments for showing CMOD data, especially when window size
not optimal.
31-Aug-2011 added Surface option for better Blob tracking
07-Apr-2011 added NoCaption keyword for NOVA work.
10-Aug-2010 added option to make .mov files from Eliots Java code that uses
jpegs
09-Jun-2010 made do loops start with LONG so can handle > 32K frames
27-Aug-2009 added /horizontal_flip and /vertical_flip
22-Jul-2009 if not MIRO, and maxVal not specified, scale each frame to it's max.
added NORMALIZE keyword (default) to read through all frames
and get the max value for use in BYTSCL.
24-Jun-2009 added showMin and showMax keywords.
12-Nov-2008 mods because cineload now assuming frame 0 is beginning of data
18-Sep-2008 mods to magnify keyword
05-Aug-2008 Written by Bill Davis
NAME:
cineave
PURPOSE:
Produce an average frame from a time ranged from .cin files from
Phantom Fast Cameras. This frame is typically used to divide GPI
images by to get normalized image.
CATEGORY:
animation
CALLING SEQUENCE:
IDL> a=cineave( CineFile, aveT1=aveT1_in, aveT2=aveT2_in, aveInt=aveInt )
INPUTS:
CineFile - a cine filename
aveT1 - start time for averaging (seconds)
aveT2 - end time for averaging
nsmooth - # of points for median smoothing on individual frames
despeckle - if set call despeckle routine (slow, but less "intrusive"
than median)
badValue - if data is this or above, replace with median of surrounding pixels
inc - default 1o 1; use every "inc"th frame
FrameOffset - if set, subtract this (like a baseline) from all pixels
FrameAveMin - if set, make close-to-zero pixels this number,
so when dividing into data, as in normalizing, result is near zero
OUTPUTS:
maxInt - the maximum intensity anywhere in the frame vs. time
aveInt - the average intensity anywhere in the frame vs. time
maxVal - maximum value over interval
minVal - minimum value over interval
maxNorm - max value of normalized images over that the same time range
times - times used to create this average frame
status - odd if OK
EAXMPLES:
filename='/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216029.cin'
or filename='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_142000.cin'
IDL> t0=systime(1) & a=cineave( filename, aveInt=aveInt ) & print, systime(1)-t0
Without finding AveInt, took 6.5 sec for nstx_1_142000.cin.
When finding average, 33.6 seconds .
MODIFICATION HISTORY:
05-Mar-2014 added keywords fr1 & fr2 for files with whacky times
05-Sep-2012 added keywords FrameOffset and FrameAveMin
04-Sep-2012 fixed bug where was dividing by n-1 rather than n.
27-Mar-2012 use fastcam_times and fastcam_frame so can support HDF files from simulation
01-Sep-2011 added nsmooth, inc, despeckle & badvalue keywords
27-Jul-2011 made max intensity at a pixel be the 99.9% pixel value so bad pixels
don't form max (as Ricky Macqueda did)
25-Jul-2011 added keyword maxInt to return maximum intensity vs. time
22-Jul-2011 default aveT1 and aveT2 to entire file and option to return
average intensity vs. time [BD]
18-Jan-2011 added minAll and maxAll keywords
WRITTEN Jan-2011 by Bill Davis for Stewart Zweben
NAME:
displayfctiffs
PURPOSE:
Animate Fast Camera images with the time overlayed
CATEGORY:
Animation
CALLING SEQUENCE:
IDL> displayfctiffs, shot
INPUTS:
shot = nstx shot number
KEYWORD PARAMETERS:
Keywords:
minmsec - min time in msec to include
maxmsec - max time in msec to include
loop - number of times to loop through animation (default=1)
pause - time in seconds to pause between frames (default=0)
minToPlot - min value for bytscl of image
maxToPlot - max value for bytscl of image
skip - frames to skip between those displayed (default=0)
magnify - magnification factor ( note that bigger movies are slower)
charThick -
charsize -
debug -
mpg -
mds - if set, look for data in MDS plus (little there as of Jul/04)
OUTPUTS:
none
LIMITATIONS:
MPEG movies created from widget are poor.
EXAMPLE:
IDL> displayfctiffs,shot=113723,minms=140,maxms=170
MODIFICATION HISTORY:
16-Mar-05 Only read in times within times requested
29-Jul-04 access /v/kodak area from Unix
22-Jul-04 Added mpg creation [DM]
Written by Bill Davis, PPPL
NAME:
fcdcmovies
PURPOSE:
Plot Fast Camera and Divertor Camera images along with EFIT field
lines, and, optionally, Thomson Scattering Density and Temperature.
You may also plot H-alpha (or another) signal vs. time.
CATEGORY:
Animation, NSTX, EFIT, Thomson Scattering
CALLING SEQUENCE:
IDL> fcdcmovies, 114333,time=[.008,.012],thom=0, sigT1=.005,sigT2=.020
To get a postscript frame printed:
IDL>fcdcmovies,114333,time=0.01,thom=0,sigT1=.005,sigT2=.02,anim=0,/postscript
if the FC images are too light, you can make them 4 times as bright:
IDL> fcdcmovies, 112608, FCimgScale=4
to get an animation with no more than 40 frames between 50 and 317 msec:
IDL> fcdcmovies, shot, time=[0.05,0.317],max=40
INPUTS:
shot = nstx shot number
diverter camera data must be moved manually to linux. Examples are
at $NSTXUSR/uppercam/114333 and $NSTXUSR/divcam/114333.
A .cih file must also be in each directory for the timing information
KEYWORD PARAMETERS:
Keywords:
half - if set, only show left half of fast camera image
time - 2-element array for animation; single value for one frame
thomson - if set to 0, will NOT plot Thomson Te and Ne below EFIT contours
animate - if set to 0, will NOT make a movie in an IDL XINTERANIMATE window.
maxFrames - max # of frames over time range -- necessary if X-memory
imSmooth - amount to median smooth images (default=3)
is limited (default is 200).
sigName - if set, will not show Fast Camera images, but this
signal vs. time (defaults to \passivespec::BAYC_DALF_HAIFA)
sigT1 - starting time of signal vs. time plot
sigT2 - ending time of signal vs. time plot
sigTitle - if set, will be displayed above sigName plot,
else tries to get label from MDSplus
OUTPUTS:
none
LIMITATIONS:
MPEG movies created from widget are poor.
All Fast Camera data is on VMS, but can be mounted from petrel084 to
petrel092. Only what has been moved manually
is on Unix.
NOTES:
you need to use /save to get Mpeg quality=100 (but it's not clear there's
any improvement in the Mpeg.
to get tiff files from the fastcamera system into the right taurus directory:
scp them from the KODAK directory, or one of it's subdirectories, on VMS
Postscript files can be huge; may try making separate one with only Fast Camera image.
MODIFICATION HISTORY:
05-Jan-2015 BD added shot, so can draw NSTX-U tiles
Devon Battaglia modified code in plot_tiles_nstxu
03-Sep-04 Fixed bug in times of Thomson when animating partial shot
05-Aug-2004 Added two Hiroshima cameras
23-Jul-04 added ExtendEFITtime keyword to continue animation after efit
15-Jul-04 Make default to do animation and include Thomson data
13-Jul-04 Made the default be to show whole fast camera image
05-May-04 Adapted from EfitMovies for Fast Camera data plus x-y plots
Original EFIT animation written by Dave Gates
NAME:
fctiffsvcr
PURPOSE:
animate Fast Camera tiffs with VCR-like controls.
from the resulting widget, you may write an Mpeg file
CATEGORY:
Animation
CALLING SEQUENCE:
IDL> fctiffsvcr, shot
INPUTS:
shot = nstx shot number (Optional - you can navigate for a shot)
KEYWORD PARAMETERS:
Keywords:
minmsec - min time in msec to include
maxmsec - max time in msec to include
minToPlot - min value for bytscl of image
maxToPlot - max value for bytscl of image
skip - frames to skip between those displayed (default=0)
magnify - magnification factor ( note that bigger movies are slower)
InitPath - Initial Path of Fast Camera data
rate - initial display rate
verbose - if set, will print info as it progresses
charThick -
charsize -
debug -
mds - if set, look for data in MDS plus (little there as of Jul/04)
OUTPUTS:
none
LIMITATIONS:
as of 29-Jul-2004, FC data just available on NSTX Petrels,
the VMS cluster.
MPEG movies created from widget are poor.
EXAMPLE:
IDL> fctiffsvcr,shot=113723,minms=140,maxms=170
IDL> fctiffsvcr, frame1=1000, skip=5, maxframes=100, $
files='/p/camdata/dust/120325_TIFF/*.tif', mag=3, /debug
MODIFICATION HISTORY:
29-Jul-2004 Written by Bill Davis, PPPL
NAME:
fcvcr
PURPOSE:
Plot Fast Camera images with a VCR-like interface
CATEGORY:
Animation, Fast Camera
CALLING SEQUENCE:
to get an animation with a maximum of 40 frames (spaced with time selection):
IDL> fcvcr, 128030, time=[0.05,0.317], max=40
to see what shots have fast camera data in the tree:
IDL> MDSnodeChanges,'\fc3d', shot1=119120, shot2=119330, tree='cameras'
INPUTS:
shot = nstx shot number
KEYWORD PARAMETERS:
Keywords:
sigName - MDSplus signal name of 3-D signal
tree - MDSplus tree of signal (defaults to cameras2)
bytescale - if set, will scale each frame to 0-255
ndups - number of times each frame of movie is duplicated (default=0)
time - 2-element array for animation; single value for one frame
animate - if set to 0, will plot individual frames instead of movie.
maxFrames - max # of frames over time range -- necessary if X-memory
is limited (default is 200).
pixMap - if set, will not send each frame to the screen (faster)
maxVal - maximum value to use when byte scaling
minVal - minimum value to use when byte scaling
camt0 - time of first frame (overrides what is in MDSplus)
camdt - time between frames (overrides what is in MDSplus)
OUTPUTS:
calls XIA, from which you can save pictures of frames, or an mpeg file
EXAMPLES:
IDL> fcvcr, 138116, signal='\cameras2::top.edge_neutral.rawdata.data', mag=2
IDL> fcvcr, 138178, signal='\cameras2::fastsoftxray:frames', ndecimals=5, mag=5
LIMITATIONS:
NOTES:
MODIFICATION HISTORY:
08-Jun-2010 use amedian, so edges of images get filtered
03-Jun-2010 added handling of time outside of shot, and overrides
02-Jun-2010 added keywords maxVal, minVal, bytescale (does all data at once)
28-Mar-2008 written by Bill Davis
NAME:
mk_mpeg
PURPOSE:
Write a sequence of images from a 3-D array, or a series of tiff
files, as an mpeg movie.
CATEGORY:
animation
CALLING SEQUENCE:
mk_mpeg, 'movie.mpg' ,ims
or
mk_mpeg, 'movie.mpg', files=files
INPUTS:
ims: sequence of images as a 3D array with dimensions [sx, sy, nims]
where sx = xsize of images
sy = ysize of images
nims = number of images
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
delafter: if set delete temporary array after movie was created
you should actually always do it otherwise you get
problems with permissions on multiuser machines (since
/tmp normally has the sticky bit set)
rep: if given means repeat every image 'rep' times
(as a workaround to modify replay speed). i.e., if = 2, make 2 copies of
each frame.
files: file list. If just one value, needs to include a wild card
justone: just plot D-alpha
despeckle : if set call despeckle routine (slow, but less "intrusive" than median)
OUTPUTS: None
OPTIONAL OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
creates some files in TMPDIR which are only removed when
the delafter keyword is used
RESTRICTIONS:
depends on the program mpeg_encode from University of
California, Berkeley, which must be installed in /usr/local/bin
PROCEDURE:
writes a parameter file based on the dimensions of the image
array + the sequence of images in ppm format into a
temporary directory; finally spawns mpeg_encode to build the
movie
EXAMPLE:
IDL> shot = 111840
IDL> f = file_search( GETENV("NSTXUSR")+'/divcam/'+strtrim(shot,2)+'/*.tif')
IDL> mk_mpeg, strtrim(shot,2)+'_divcam'+'.mpg',files=f,shot=shot,/fliphoriz
LIMITATIONS:
mpeg_encode must be in your path (not currently on PPPL Linux)
MODIFICATION HISTORY:
22-Apr-04 lots of kludges to make nice movies of camera data
from Hiroshima University on NSTX. [BD]
29-Apr-02 Modified write_mpeg to accept a filelist or wildcard spec [BD].
Mon Nov 18 13:13:53 1996, Christian Soeller
grabbed original from the net and made slight modifications
NAME:
mpeg_from_screen
PURPOSE:
Example of creating a color Mpeg animation with text overlayed.
Works on both 8-bit and 24-bit monitors. Can read from files, but those
returning 24-bit data will not have the text overlaying option.
CATEGORY:
Animation
CALLING SEQUENCE:
IDL> mpeg_from_screen
or
IDL> mpeg_from_screen, data3d=data3D, mpeg_filename='mymovie.mpg'
or
IDL> mpeg_from_screen, ndups=5, $
files=['out1.jpg','out2.jpg','out3.jpg','out4.jpg','out5.jpg']
INPUTS:
none required
KEYWORD PARAMETERS:
All optional inputs:
data3D - optional 3-D array ( nx, ny, nFrames )
nFrames - # of frames when using dummy data.
files - a string array of filenames.
Can be of type 'jpg','tif','tif','bmp','jpeg,'png', or 'gif'
mpeg_filename - output filename for mpeg movie
ndups - number of times each frame of movie is duplicated (default=3)
showFrame - if =0, will not show frame around image (irrelevant for rgb files)
useScreen - if=0, don't bother using screen for output (i.e., no text to overlay)
(irrelevant for rgb files)
border - # of pixels around data (default=25)
ctb - color table to use (default=39)
charsize - character size (default=1.5)
charthick - character thickness (default=2)
pixMap - if = 0, will write and read each frame from screen (much slower)
OUTPUTS:
mpeg file
MODIFICATION HISTORY:
20-Oct-2004 Optionally operate off a list of files
15-Oct-2004 Written by Bill Davis
NAME:
mptscam
PURPOSE:
Animate several plots, including MPTS variables
CATEGORY:
Animation, MPTS
CALLING SEQUENCE:
IDL> mptscam, shot, xSize=xSize, ySize=ySize, sideSigs=sideSigs, $
MAX_COLORS_TO_USE = max_colors_to_use, dirs=dirs, $
noSides=noSides, colortable=colortable, $
mpegFile=mpegFile, rf=rf, nb=nb, pixMap=pixMap, $
gaps=gaps
INPUTS:
shot - NSTX shot # to display
KEYWORD PARAMETERS:
Optional Inputs:
...
dirs - directories to search. If not set, typical NSTX camera
is set to 'none', no camera file will be used
directories will be searched.
defPath - path to find most recent "Miro*.cin" file for default selection
first - if set, will just return the first match (for speed)
pick - if set, and more than one match found, will pop a dialog
box for user to pick one.
bigger - DEFAULT=1, so will reduce other graphs on left, so camera image is
bigger.
nSmooth - # of pixels to median smooth over (3 is great for bit noise)
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
VCR-like widget; can create mpegs
EXAMPLE: for output example, see
http://nstx.pppl.gov/nstx/Software/Diagnostics/MPTS/mptsdata.html
IDL> mptscam, 130376, dir='/p/nstxcam-archive/Miro2-7988/2008/'
IDL> mptscam, 140300, dir='/p/nstxcam/Phantom73-8032/2010/'
IDL> f=findcamfiles(141833, /pick) ; select camera from those available
IDL> fdecomp, f, disk, dir, name
IDL> mptscam, 141833, dir=dir
IDL> mptscam, 141833, dir='/p/nstxcam/Phantom4-6878/2010/'
NOTES:
This routine has not been tested for many combinations of signals
Logic for making movies with less than the full time needs improving.
MODIFICATION HISTORY:
12-Oct-2010 cleaned up for new camera searching, and added /bigger keyword
18-Aug-2009 limit radial plots from 18-160 cm per Adam McLean.
14-Aug-2009 major changes for new camera data locations
16-Nov-01 Fine tuned for xsize=600, ysize=400 (for publication)
Written by Bill Davis
+
NAME:
WRITE_MPEG
PURPOSE:
Write a sequence of images as an mpeg movie
CATEGORY:
animation
CALLING SEQUENCE:
WRITE_MPEG,'movie.mpg',ims
INPUTS:
ims: sequence of images as a 3D array with dimensions [sx, sy, nims]
where sx = xsize of images
sy = ysize of images
nims = number of images
OPTIONAL INPUTS:
KEYWORD PARAMETERS:
delaft: if set delete temporary array after movie was created
you should actually always do it otherwise you get
problems with permissions on multiuser machines (since
/tmp normally has the sticky bit set)
rep: if given means repeat every image 'rep' times
(as a workaround to modify replay speed)
OUTPUTS: None
OPTIONAL OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
creates some files in TMPDIR which are only removed when
the DELAFT keyword is used
RESTRICTIONS:
depends on the program mpeg_encode from University of
California, Berkeley, which must be installed in /usr/local/bin
PROCEDURE:
writes a parameter file based on the dimensions of the image
array + the sequence of images in ppm format into a
temporary directory; finally spawns mpeg_encode to build the
movie
EXAMPLE:
IDL> s=openmdsshot('efit',112800)
IDL> data3d=mdsvalue('\efit01::psirz')
IDL> write_mpeg, 'efit_112800.mpg', bytscl(congrid(data3d,65*8,65*8,128))
or
IDL>write_mpeg,'test.mpg',reform([[dist(100)],[dist(100)],[dist(100)]],100,100,3)
MODIFICATION HISTORY:
15-Jul-04 warn if file not 3d [BD]
Mon Nov 18 13:13:53 1996, Christian Soeller
grabbed original from the net and made slight modifications
NAME:
XanimJpeg
PURPOSE:
animate jpegs (or other image files) in a VCR-like widget,
which can make an MPEG Movie.
CATEGORY:
Animation, MPEG, jpegs
KEYWORDS:
jpegDir - directory containing files to animate
ext - extension of files to animate (DEFAULT='jpg')
showTime - if set, try to show time on image
times - times of images in msec
increment - for file list, ie., to skip frames, set > 1
maxFrames - max # of frames to load (to many can cause an X-window problem)
prefix - prefix of files for search. Default='*'
byteScale - if set, will scale individual frames from 0-255
minVal - if this and byteScale set, will use this as minimum value
maxVal - if this and byteScale set, will use this as maximum value
ctb - color table to load (not sure makes a difference) DEFAULT=3
mag - magnification factor for images
EXAMPLE:
IDL> xanimjpeg, jpegDir='~bdavis/ShockWaveOutput/Output'
IDL> jpegDir='/p/gyro/wgutten/gyro-9.0wg/sim/NSTX_120968A02_560/nonlin/ra60/franklin_runs/x80y60_n8r200ob8v6/jpeg_files/'
IDL> xanimjpeg, jpegDir=jpegDir, prefix='frame06', maxframes=10
IDL> xanimjpeg, jpegDir='~bdavis/DustTracking/Data/130388/Cam2_NO'
NOTE:
this routine requires substantial "X memory" so, Exceed on a Mac,
may need more memory; an X-terminal may give a "toolkit error".
MODIFICATIONS:
13-Jul-2010 use XIA & other features
WRITTEN by Bill Davis
NAME:
XeasyAnim
PURPOSE:
animate 3-D array and optionally make MPEG Movie
CATEGORY:
Animation, MPEG
KEYWORDS:
nreps - number of frames to repeat when creating mpeg (1 means no dups)
xSize -
ySize -
rate -
MAX_COLORS_TO_USE -
magnification -
xpos -
ypos -
colortable - color table for movie
ctbFile - color table file (for personal color tables)
noLoad - if set, do not load any color table
SCALEEACHFRAME -
bottom - if set, then position window at bottom of screen
despeckle -
XWIN -
YWIN -
STDEV_MULT
ctbfile - color table file (for personal color tables)
EXAMPLE:
IDL> Array3D_In = [DIST(200,200),DIST(200,200)*1.2,DIST(200,200)*1.4]
IDL> Array3D_In = bytscl(reform( Array3D_In, 200, 200, 3 ))
IDL> XEasyAnim, Array3D_In, /bottom
you may wish to the following:
IDL> dum=MK_COLOR(N_NONFIXED=ncolors)
IDL> Array3D = BYTSCL( Array3D, TOP=ncolors )
IDL> XEasyAnim, Array3D
Modifications:
12-May-2008 added noLoad and ctbFile keywords
02-Aug-2007 add gamma keyword [BD]
02-May-06 added nreps keyword
14-Apr-06 added xpos & ypos keywords
06-Mar-02 Added printing, resizing of array, added despeckling [BD]
NAME:
XIA
PURPOSE:
Display an animated sequence of images using X-windows Pixmaps.
The speed and direction of the display can be adjusted using
the widget interface.
CATEGORY:
Animation, Image display, widgets.
CALLING SEQUENCE:
To initialize:
XIA, SET = [Sizex, Sizey, Nframes]
To load a single image:
XIA, IMAGE = Image, FRAME = Frame_Index
To load a single image that is already displayed in an existing window:
XIA, FRAME = Frame_index, $
WINDOW = [Window_Number [, X0, Y0, Sx, Sy]]
(This technique is much faster than reading back from the window.)
To display the animation after all the images have been loaded:
XIA [, Rate]
To close and deallocate the pixmap/buffer (which also takes place
automatically when the user presses the "Done With Animation"
button or closes the window with the window manager):
XIA, /CLOSE
OPTIONAL INPUTS:
Rate: A value between 0 and 100 that represents the speed of the
animation as a percentage of the maximum display rate.
The fastest animation is with a value of 100 and the slowest
is with a value of 0. The default animation rate is 100.
The animation must be initialized using the SET
keyword before calling XIA with a rate value.
KEYWORD PARAMETERS:
BOTTOM: If set, window will be at bottom of screen or parent window
CLOSE: Set this keyword to delete the offscreen pixwins and Widget,
freeing storage.
CYCLE: If set, cycle. Normally, frames are displayed going either
forward or backwards. If CYCLE is set, reverse direction
after the last frame in either direction is displayed.
Provide this keyword with the SET keyword.
FRAME: The frame number when loading frames. This keyword only has
an effect when used in conjunction with the SET keyword.
FRAME must be set to a number in the range 0 to Nframes-1.
GROUP: The widget ID of the widget that calls XIA. When
this ID is specified, the death of the caller results in the
death of XIA.
IMAGE: A single image to be loaded at the animation position given
by FRAME. The keyword parameter FRAME must also be specified.
KEEP_PIXMAPS: If TRUE, XIA doesn't destroy the animation
pixmaps when it is killed. Calling it again without
going through the SET and LOAD steps will cause the same
animation to play without the overhead of creating
the pixmaps.
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
ORDER: Set this keyword to display images from the top down instead
of the default bottom up. This keyword is only used when
loading images.
MODAL: If set, then XIA runs in "modal" mode, meaning that
all other widgets are blocked until the user quits
XIA.
MPEG_FILENAME: Set this keyword equal to a string for the desired
MPEG filename. If not set, idl.mpg is used.
MPEG_CLOSE: Set this keyword to write the MPEG file.
NREPS - number of frames to repeat when creating mpeg (1 means no dups)
SHOWLOAD: Set this keyword (in conjunction with the SET keyword) to
display each frame and update the frame slider as frames are
loaded.
SET: This keyword initializes XIA. SET should be equated
to a 3-element integer vector containing the following
parameters:
Sizex, Sizey: The width and height of the images to be
displayed, in pixels.
Nframes: The number of frames in the animated sequence
(since XIA is an animation routine,
Nframes must be at least 2 frames).
TITLE: A string to be used as the title of the widget. If this
keyword is not specified, the title is set to "XIA"
This keyword has an effect only when used in conjunction with
the SET keyword).
TRACK: If set, the frame slider tracks the current frame. Default
is not to track. Provide this keyword with the SET keyword.
WINDOW: When this keyword is specified, an image is copied from an
existing window to the animation pixmap. When using X
windows, this technique is much faster than reading
from the display and then calling XIA with a 2D
array.
The value of this parameter is either an IDL window
number (in which case the entire window is copied),
or a vector containing the window index and the rectangular
bounds of the area to be copied, for example:
WINDOW = [Window_Number, X0, Y0, Sx, Sy]
XOFFSET: The horizontal offset, in pixels from the left of the frame,
of the image in the destination window.
YOFFSET: The vertical offset, in pixels from the bottom of the frame,
of the image in the destination window.
OUTPUTS:
No explicit outputs.
COMMON BLOCKS:
XIA_COM: a private common block.
SIDE EFFECTS:
A pixmap and widget are created.
RESTRICTIONS:
Only a single copy of XIA can run at a time.
PROCEDURE:
When initialized, this procedure creates an approximately square
pixmap or memory buffer, large enough to contain Nframes of
the requested size. Once the images are loaded, using the
IMAGE and FRAME keywords, they are displayed by copying the images
from the pixmap or buffer to the visible draw widget.
EXAMPLE:
Enter the following commands to open the file ABNORM.DAT (a series
of images of a human heart) and animate the images it contains using
XIA. For a more detailed example of using XIA,
see the example in the "Using IDL Widgets" chapter of "IDL Basics".
Read the images into the variable H by entering:
OPENR, 1, FILEPATH('abnorm.dat', SUBDIR = 'examples/data')
H = BYTARR(64, 64, 16)
READU, 1, H
CLOSE, 1
H = REBIN(H, 128, 128, 16)
XIA, SET=[128, 128, 16], /SHOWLOAD
FOR I=0,15 DO XIA, FRAME = I, IMAGE = H[*,*,I]
XIA
MODIFICATION HISTORY:
02-May-06 added nreps keyword
14-Apr-06 added xpos & ypos, bottom & right keywords
02-Aug-01 modified XInterAnimate to have printing [Bill Davis]
NAME:
xyanim
PURPOSE:
Animate a series of X-Y plots.
Makes an animation in a XINTERANIMATE window. An MPEG file
can then be saved, or the movie can be played with VCR-like
controls
CATEGORY:
Animation
CALLING SEQUENCE:
IDL> xyanim, Radii, YvsT, times, xSize=xSize, ySize=ySize
INPUTS:
Radii - 1-D array of Radii (for example)
YvsT - 2-D array of Independent axis vs. time
times - times for which an x-y plot will be made (defaults to 1/frame)
KEYWORD PARAMETERS:
Keywords:
xSize - x size of resulting output frame (default=400)
ySize - y size of resulting output frame (default=xSize)
OUTPUTS:
just the XinterAnimate window. MPEGs can be made from that widget.
COMMON BLOCKS:
NONE
EXAMPLE:
See /u/bdavis/cvs/idl_cvs/testxyanim.pro
MODIFICATION HISTORY:
12-Jun-01 Written by Bill Davis, PPPL
Category: Bits
[List of Routines]
NAME:
bits
PURPOSE:
Given a byte or integer, return a vector of 8 or 16 values
which are the binary representation of the value.
CATEGORY:
bits, hardware
INPUT:
invalue - The byte or integer value to check
OUTPUT:
bitarr - The 8-element array with values set
if the bit is set
EXAMPLE:
IDL> BITS, invalue, BITARR
HISTORY:
Written 1988 by M.Morrison
13-Nov-92 (MDM) - Modified to allow integer*2 values
and to allow an array of values.
7-Apr-94 (MDM) - Allow integer*4 values
15-Aug-94 (MDM) - Corrected error from 7-Apr-94 mod which
did not allow an array of inputs
NAME:
BTEST
PURPOSE:
To test bit N in FIX(X)
CATEGORY:
Bits, Hardware
CALLING SEQUENCE:
YesNo = btest( X, N )
PARAMETERS:
Inputs:
X (REQ) (I) (0 1) (I F)
X is the variable to be tested
N (REQ) (I) (0) (I)
The bit of X to be tested
Returned:
YESNO (REQ) (O) (0 1) (I)
The result of the test. 1(true) if bit N is set, 0(false)
otherwise.
EXAMPLES:
YESNO = btest( !X.STYLE, 4 )
IF YESNO THEN PRINT,'X-axis suppressed' $
ELSE PRINT,'Draw X-axis'
To find points in NEWSIPS which are outside calibrated region:
YESNO = btest( ABS(NU),1 ) ; look for nu flag = -2
IND = WHERE (YESNO EQ 0) ; keep points where yesno = 0
PLOT,W(IND),F(IND) ; plot calibrated points
NOTES:
Note that negative integers are stored in twos complement form.
Therefore, the left-most bits are ON rather than OFF as they are for
positive numbers. Input the absolute value of X is negative numbers
to avoid this problem.
This procedure can be used to check the values of complex
IDL system variables such as ![XYZ].STYLE.
PROCEDURE:
Checks whether (FIX(X) OR (NOT 2^N)) = -1 to set the output
flag YESNO.
MODIFICATION HISTORY:
26-Oct-99 Convert from btest to make a function (like FORTRAN)
Mar 6 1983 RJP GSFC initial program
Aug 24 1987 RWT GSFC add PARCHECK
Mar 7 1988 CAG GSFC all VAX RDAF-style prolog
Jul 13 1990 RWT GSFC Sun mods: use examples pertinent to SUN IDL
and add listing of procedure call statement
Jun 19 1991 PJL GSFC cleaned up; tested on SUN and VAX; updated prolog
Mar 8 1993 RWT GSFC modify to allow X & YESNO to be vectors and
add documentation about negative numbers.
NAME:
DECODE_GRAY
PURPOSE:
Convert a gray-code value to an integer
CATEGORY:
Bits, CAMAC, Hardware, Stepper Motor Control
CALLING SEQUENCE:
IDL> int = DECODE_GRAY(grayCode)
INPUTS:
grayCode = number in gray code.
KEYWORD PARAMETERS:
Optional Input:
NBits - # of bits to decode; defaults to 8
OUTPUTS:
int = returned integer out
COMMON BLOCKS:
NONE
EXAMPLES:
IDL> print,DECODE_GRAY(1)
1
IDL> print,DECODE_GRAY(2)
3
IDL> print,DECODE_GRAY(255)
170
IDL> print,DECODE_GRAY(255+512)
170
IDL> print,DECODE_GRAY(255+512,nbits=16)
853
NOTES:
This can probably be sped up considerably.
MODIFICATION HISTORY:
26-Oct-99 Written by Bill Davis, PPPL
NAME:
mk_bitarray
PURPOSE:
Create an array of 1's & 0's corresponding to input bits set
(works for negative numbers, too, unlike similar routines)
CATEGORY:
Bits
CALLING SEQUENCE:
IDL> array= mk_bitarray( input )
IDL> array= mk_bitarray( input, nbits=5 )
INPUTS:
input = whatever; might be something like !X.STYLE
KEYWORD PARAMETERS:
NBITS=nbits - length of returned array (default to input type)
PRINT - if set, will print bits in groups of fours.
OUTPUTS:
Byte array containing 1's and 0's out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> print,mk_bitarray(3, nbits=8)
1 1 0 0 0 0 0 0
IDL> dum = mk_bitarray( 1025, /print )'
1 0 0 0 0 0 0 0 0 0 1 0 0 0 0 0
LIMITATION:
Only works on a scalar.
MODIFICATION HISTORY:
05-Jun-00 default nbits to input type. add print keyword.
30-Mar-99 Written by Bill Davis, PPPL
NAME:
showbits
PURPOSE:
Given a byte or integer, return a vector of 8 or 16 values
which are the binary representation of the value.
CATEGORY:
Bits, Hardware
USAGE:
bitarr = SHOWBITS( invalue, /print )
INPUT:
invalue - The byte or integer value to check
OUTPUT:
bitarr - The 8-element array with values set
if the bit is set
KEYWORDS:
(Optional)
NtoShow - # of bits to show
HISTORY:
29-Oct-99 Converted to Function by Bill Davis, ntoshow added
Written 1988 by M.Morrison
13-Nov-92 (MDM) - Modified to allow integer*2 values
and to allow an array of values.
7-Apr-94 (MDM) - Allow integer*4 values
15-Aug-94 (MDM) - Corrected error from 7-Apr-94 mod which
did not allow an array of inputs
LIMITATIONS:
Only works for non-negative, fixed-point numbers
Category: blobs
[List of Routines]
NAME:
blobbinranges
PURPOSE:
plot bins of one variable vs another from blob database and draws
ranges, of say 90%, in Y for each binned point. Uses color filled
contours for square bin values.
See http://nstx.pppl.gov/nstx/Software/Applications/blobDBdefs.txt
for an explanation of variables and units of database variables.
CATEGORY:
Blobs
CALLING SEQUENCE:
IDL> blobBinRanges, filename
INPUTS:
------
filename - file saved from DbAccess
KEYWORDS:
--------
xVar - Column in DbAccess for independent variable (default='topNorm')
yVar - Column in DbAccess for dependent variable (default='xVel')
Note: velocities are in Km/sec. Most other things are in pixels.
x1 - starting pixel in horizontal direction to consider
x2 - ending pixel in horizontal direction to consider
t1 - starting pixel in vertical direction to consider
t2 - ending pixel in vertical direction to consider
percent - % of data points to draw bars over (Default=90, but 95% might be better)
binSize - length of bin (on X axis)
nBins - if set, will set binsize so this # of bins cover range of X data
minHt - min value of topNorm
maxHt - max value of topNorm
saveFile - if=1, will save a JPEG file
plotFile - file name to save JPEG to
position - bounding box in normalized coords (def=[.1,.1,.95, .9])
xrange - the x limits of the plot (set !x.style=1 before running for exact)
yrange - the y limits of the plot (set !y.style=1 before running for exact)
explain - include in the legend an explanation of bars and numbers
ctb - color table for color contours (default=3, hot metal)
interp - if set, will interpolate colors indicating blobs per bin
EXAMPLES:
--------
IDL> blobBinRanges, '/u/bdavis/cvs/database/DBoutSH141741.txt', $
x1=10, x2=50, charsize=1.5, $
xtitle='Normalized Blob Brightness', $
ytitle='Radial Velocity (Km/s)', $
title='Shot 141741; 212-216 msec', $
percent=90, yrange=[-2,4], xrange=[1,7], /contours, /rainbow
IDL> blobBinRanges, '/u/bdavis/cvs/database/DBoutSH139286.txt', $
x1=10, x2=50, charsize=1.5, $
xtitle='Normalized Blob Brightness', $
ytitle='Radial Velocity (Km/s)', $
title='Shot 139286; 312-316 msec', $
percent=90, yrange=[-2,4], xrange=[1,7], /contours, /rainbow
IDL> blobBinRanges, '/u/bdavis/cvs/idl_cvs/DBoutSH142000.txt', /debug
IDL> blobBinRanges, '/u/bdavis/cvs/idl_cvs/DBoutSH142000.txt', $
x1=40, charsize=1.5, $
xtitle='Normalized Blob Brightness', $
ytitle='Radial Velocity (Km/s)', $
title='Shot 142000; 240-270 msec', legend='Outside Separatrix', $
percent=90, yrange=[-2,4], xrange=[1,7], /contours, /rainbow
IDL> blobBinRanges, '/u/mko/testfile_142000.txt', x1=40, charsize=1.5, $
xtitle='Normalized Blob Brightness', $
ytitle='Radial Velocity (Km/s)', $
title='Shot 142000; 240-270 msec', legend='Outside Separatrix', $
percent=90, yrange=[-2,4], xrange=[1,7], /contours, /rainbow
MODIFICATION HISTORY:
--------------------
29-Oct-2013 change order of columns read to fit (new?) DbAccess files.
WRITTEN 26-Jul-2012 by Bill Davis
NAME:
blobtrails
PURPOSE:
draw trails of blob trajectories that go through a certain region of the image.
Data comes from a database of blob characteristics for a given shot, and perhaps
just part of a shot (see populateblobs.pro).
CATEGORY:
Blobs
CALLING SEQUENCE:
IDL> blobtrails, table=table, xpt=xpt, ypt=ypt, box=box, minht=minht
INPUTS:
-------
database - SQL database (server maintained by Tom Carroll) for blobs, DEF='BLOBS'
table - table name in database of blobs for a period within a shot, or
shot - will assume table is named 'SH'+shot
xpt - horizontal center of region from which trajectories start
ypt - vertical center of region from which trajectories start
boxradius - # of pixels around [xpt, ypt] to allow for start of trajectories
minHt - min height of blob in normalized image. (when blob passes through box)
lifeRequired - lifetime required in seconds (after passing through box) , or
needed - number of frames needed (after passing through box) to bother with
t1 - (optional) 1st time to consider (seconds)
t2 - (optional) last time to consider (seconds)
timeOffSet - amount needed to be added to camera time to get to shot time
rainbow - if set, will use "betterrainbow" pallette, rather than hot metal.
nSmooth - smoothing to be applied before track is plotted (default=3)
maxJump - max # of pixel to change per frame to be considered same blob
(DEF=10)
msec - if set, display times in millisec
ellipse - if set, draw ellipses where fit was made
symWidth - if <=0 then draw ellipses in realistic shapes
scale - if realistic blob sizes drawn, scale their size by this factor
xplot1 - starting x pixel for plot
xplot2 - ending x pixel for plot
yplot1 - starting y pixel for plot
yplot2 - ending y pixel for plot
verbose - if set, lots of information output listed
debug - if set, will output even more and may stop at some spots
"rise" was the difference from the max of a blob (after normalizing frame)
and the lowest closed contour line that enclosed it.
EXAMPLES:
IDL> blobtrails, 32,32, box=2, /rainbow, minht=1.1, /list, /debug
IDL> blobtrails, 25,25, box=2, /rainbow, shot=138234, ny=80, /list , /debug
IDL> maxJump=5
IDL> blobtrails, table='SH138234',xpt='32',ypt='32',boxRadius='2',minHt='2', $
maxJump=maxJump, needed='3',t1='0',t2='20', ctb='-1', ListTimes='on', $
eFileType='None',psfilename='blobtrails',emailPsAddress='', /deb
IDL> blobtrails, table='SH1091216028', x1=39, x2=41, y1=2,y2=62, psym=4, minHt='1.5', $
maxJump=10, needed='3',t1='0',t2='20', ctb='-1', ListTimes='on', $
xplot1=30, xplot2=60, /msec, chimax=5, nSmooth=3, $
eFileType='None',psfilename='blobtrails',emailPsAddress='', /deb
blobtrails, table='SH138234',xpt='20',ypt='20',boxRadius='3', minHt='2', $
maxJump=maxJump, needed='3',ctb='-1', $
t1=530, t2=550, $
xplot1=10, xplot2=50, yplot1=10, yplot2=80, charsize=1.5, /ellip , /deb
blobtrails, table='SH138234',x1=15, x2=30, y1=20, y2=22, minHt='2.5', $
maxJump=maxJump, needed='3',ctb='-1', $
t1=530, t2=550, $
xplot1=15, xplot2=50, yplot1=10, yplot2=80, charsize=1.5, /ellip , /deb
blobtrails, 20, 20, boxRadius=3, shot=138234, $
minHt=2.2, t1=530, t2=550, xSize=500, ySize=600, $
/ListTimes, charsize=1.8, psym=4, symSize=2,$
xplot1=10, xplot2=40, yplot1=0, yplot2=30
to get a track of just one blob:
blobtrails, 8, 40, boxRadius=4, shot=138234, $
minHt=2.2, t1=534, t2=535, xSize=500, ySize=600, $
/ListTimes, charsize=1.6, psym=4, symSize=2,$
xplot1=-10, xplot2=40 ;;;, yplot1=0, yplot2=30
to make plots for Stewart's 2014 paper:
IDL> !p.font=0
IDL> setup_ps, 'bt_140395_1pt5.ps', printer='postscript', /color
IDL> blobtrails, shot=140395, t1=549.25, t2=550.75, minHt=1.5, $
x1box='0',x2box='63', y1box='0',y2box='79', $
limiter='on', charsize=1.8, symbol='none', $
yplot1='', yplot2='', $
efitVersion='EFIT02', $
/noYellow, /rainbow, /first, symwidth=3
IDL> unsetup_ps
IDL> setup_ps, 'bt_141746.ps', printer='postscript', /color
IDL> blobtrails, shot=141746, t1=213.5 ,t2=214.5, minHt=1.5, $
x1box='0',x2box='63', y1box='0',y2box='79', $
limiter='on', charsize=1.8, symbol='none', $
yplot1='', yplot2='', $
efitVersion='EFIT02', $
/noYellow, /rainbow, /first, symwidth=3
IDL> unsetup_ps
to make plots for Stewart's 2014 paper, but with times printed:
IDL> blobtrails, shot=140395, t1=549,t2=551, minHt=1.5, $
x1box='0',x2box='63', y1box='0',y2box='79', $
limiter='on', charsize=charsize, symbol='none', $
yplot1='', yplot2='', $
efitVersion='EFIT02', $
noYellow=noYellow, rainbow=rainbow, $
titleChrSz=titleChrSz, /first, symwidth=3, $
/ListTimes, Xplot1=-40, Xplot2=50
to make plot for Stewart's 2014 paper, but with just one blob:
IDL> blobtrails, shot=140395, t1=550.92 ,t2=550.96, minHt=1.5, $
x1box='0',x2box='63', y1box='0',y2box='79', $
limiter='on', charsize=1.5, $
yplot1='', yplot2='', first=0, $
efitVersion='EFIT02', $
noYellow=noYellow, rainbow=rainbow, $
/ellipse, symwidth=3, $
/ListTimes, Xplot1=0, Xplot2=50, nskip=3
IDL> blobtrails, shot=141746, t1=213.192 ,t2=213.195, minHt=1.5, $
x1box='0',x2box='63', y1box='0',y2box='79', $
limiter='on', charsize=1.5, $
yplot1='', yplot2='', first=0, $
efitVersion='EFIT02', $
noYellow=noYellow, rainbow=rainbow, $
/ellipse, symwidth=3, /ListTimes, $
Xplot1=-20, Xplot2=50, nskip=3
MODIFICATION HISTORY:
29-Jul-2014 add /degrees to call to drawellipse, since the tilts in
the database are degrees (zero left, 90 straight up,
180 to right). Also added nskip factor for when drawing
all locations for a single track
16-Jul-2014 add noYellow keyword
01-Oct-2012 colors for single tracks was broken; fixed.
Now, both blob positions and separatrix (and limiter) are plotted
physical coordinates when plotting in cm. Previously, and still when
plotting vs. pixels, the "rhomboid" shape of the fiber bundle is
not accounted for.
28-Sep-2012 when axesInCm set, use actual R & Z values for blob positions, and
plot separtrix from actual R & Zs.
13-Sep-2012 added EveryOther, suppress, noTitle keywords
18-Jul-2012 adjust for plot area not all the pixels
26-Mar-2012 option to draw separatrix
22-Mar-2012 Use HM values for ellipse shapes (have an option for size, too)
01-Dec-2011 fixed duplication of first and last blob indices
17-Jun-2011 fixed for Database time in msec
08-Mar-2011 added wholeLife field to database, so "needed" makes more sense
(the blob has to have persisted for that many frames to be considered)
WRITTEN 2-Feb-2011 by Bill Davis for Stewart Zweben
NAME:
gennetcdfblobs
PURPOSE:
Write NetCDF files of dummy Blob data for code validation.
Files with known blob velocities are generated. This code
prints out these average x- and y-velocities, as as writing
the averages to a variable in the file (although, as of Nov.
4, 2013, an array was written for those variables and only
the first value represents the averages).
CATEGORY:
Blobs
CALLING SEQUENCE:
IDL> gennetcdfblobs, type, nframes=nframes, speed=speed, $
plot=plot, radius1=radius1, radius2=radius2, $
tilt=tilt, noise=noise, x0=x0, y0=y0, $
base=base, top=top, nblobs=nblobs, $
times=times
OUTPUTS:
files
The files have an _#, where # ends up being the shot number in the
database table.
filenames
---------
'circoneup_1.nc' one circular blob moving upwards
xVel & yVel = 0 3 pixels/frame
0.000 0.009489 Km/s
'circoneout_2.nc' one circular blob moving outwards
xVel & yVel = 3 0 pixels/frame
0.01116 0.00000 Km/s
'circmany_3.nc' many circular blobs moving in different directions
xVel & yVel = 0.60 0.378 pixels/frame
0.00223 0.001195 Km/s
'elipseone_4.nc' one circular blob moving upwards and slowly outwards
xVel & yVel = 1 3 pixels/frame
0.00372 0.009489 Km/s
'elipsemany_5.nc' many eliptical blobs moving outwards, but up and down
xVel & yVel = 1.50 0.333 pixels/frame
0.00558 0.001054 Km/s
(note that these speeds are much smaller than typical blobs, because
the time between frames is only 1ms instead of 2.2usec.)
EXAMPLES
--------
IDL> gennetcdfblobs, 2, /plot, /debug
IDL> for i=1,5 do gennetcdfblobs, i
files can be read by IDL> img = readnetcdfblobs(filename, framenumber)
Once they are loaded into a database (with loadblobs.pro), speeds can
be checked by running checkvaves.pro.
MODIFICATION HISTORY:
WRITTEN 31-Oct-2013 by Bill Davis, PPPL, for Stewart Zweben
NAME:
gpicont
PURPOSE:
plot GPI data (an average of a center strip vs. time) as a
color contour with the separatrix overlayed
CATEGORY:
Blobs, Cameras, GPI, MDSplus, NSTX, edge
CALLING SEQUENCE:
IDL> gpicont, shot
INPUT PARAMETERS:
shot - MDSplus shot #
KEYWORD PARAMETERS:
t1 - start time (Def=0.3 s)
t2 - end time (Def=0.9 s)
maxtimes - max number of points in time to plot (def=100000)
nTimes - the final number of times on the color contours
moreSmooth - after smoothing is done in the time dimension
when reducing the # of times plotted, this
is used for the whole image (with edges handled)
fit - e.g., 'LRDfit04'. Defaults to "EFIT02"
XSIZE - initial horizontal size of graphics window
YSIZE - initial vertical size of graphics window
charsize - size of characters on plot (Def=2)
sep - if=0, will not show separatrix
jpeg - if set, will make a jpeg of a screen dump
ps - if set, will save a postscript file
pdf - if set and ps set, will save a pdf file
new - forces rereading and saving data, even if times have
been done before
frac - if = 1, then plot the fraction inside the separatrix
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
EXAMPLE:
IDL> gpicont, 138844
IDL> gpicont, 138846, /new, t1=0.59, t2=0.67
IDL> for i=138844, 138846 do gpicont, i, t1=0.59, t2=0.67, $
/psout, /pdf
MODIFICATION HISTORY:
02-Dec-2013 option to draw +/- 5ms band around peak GPI data
(if bandCenter present)
28-Oct-2013 if times not specified, get from file containing peak time
10-Oct-2013 added fit keyword, so doesn't always use "best fit"
18-Sep-2013 from efit edge points was using nearest point
to the camera middle. Now interpolate edge values
using sepatmidgpi.
14-Aug-2013 Written by Bill Davis for Stewart Zweben.
NAME:
gpimountain
PURPOSE:
plot GPI data (an average of a center strip vs. time) as a surface
with the separatrix overlayed
CATEGORY:
Blobs, 3-D Plotting, MDSplus, NSTX, GPI, edge
CALLING SEQUENCE:
IDL> gpimountain, shot
INPUT PARAMETERS:
shot - MDSplus shot #
KEYWORD PARAMETERS:
t1 - start time (Def=0.3 s)
t2 - end time (Def=0.9 s)
maxtimes - max number of points in time to plot (def=1000)
az - degrees to rotate around Z axis (def=30)
ax - degrees to rotate around X axis (def=30)
XSIZE - initial horizontal size of graphics window
YSIZE - initial vertical size of graphics window
charsize - size of characters on plot (Def=2)
sep - if=0, will not show separatrix
nudge - amount to nudge separatrix line up, so shows above surface
Def=30
fence - height to draw top of fence where separatrix is.
Def=100. If=0, no fence will be drawn.
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
LIMITATIONS:
To show the separatrix on the surface, you have to find the right
Z, which is hard without lots of interpolation. The work around is
to nudge the Z values up so they will show above the surface even
if it isn't quite right.
EXAMPLE:
IDL> gpimountain, 138844, az=50, ax=40, nudge=10, $
position=[.15,.1,.85,.85], nSmooth=5, nTimes=100
IDL> gpimountain, 138846, az=50, ax=40, nudge=10, /new, $
position=[.15,.1,.85,.85], nSmooth=5, nTimes=1000
MODIFICATION HISTORY:
11-Jun-2013 Written by Bill Davis for Stewart Zweben.
NAME:
loadblobs
PURPOSE:
calls many routines used for loading blob tracking info into a
database and making plots and output files
CATEGORY:
blobs
CALLING SEQUENCE:
IDL> loadblobs, filename
if you want to load many shots from a list in a file, use something
like /u/bdavis/GPI/call_loaddb.pro
INPUTS:
filename - a .cin or .hdf file containing plasma images
KEYWORD PARAMETERS:
filename - cine file to analyze
outfilename - output of text with blob info (default formed from inputs)
t1 - start time desired in terms of times in .cin file (in sec)
t2 - end time desired in terms of times in .cin file (in sec)
aveT1 - start for averaging frame (DEF=t1) if normalize=1
aveT2 - ending time for averaging frame (DEF=t2)
horiz - if=0, do not flip frames horizontally
RotCCW - if set, will rotate frame Counter-clockwise (after horizontal flip)
default for NSTX, but not for CMOD
BlobCriteria - structure for blob criteria, like min normalized height, etc.
normalize - normalize images (divide by average frame) before looking for
blobs.
deleteFirst - if = 0, will NOT first delete the existing database table.
dbOut - if=0, will not write to an SQL database
outDBfile - if set, will write database info to this filename, rather than db
table - if not set, will write to table SH+
database - if not set, will write to database 'BLOBS'
nSmooth - amount to smooth image before looking for blobs
GaussSmooth - if set, will do "gaussian" smoothing (sort of a double smooth)
instead of boxcar smoothing
velSmooth - amount to smooth velocity tracks before putting into database
FrameOffset - if set, subtract this (like a baseline) from all pixels
FrameAveMin - if set, make close-to-zero pixels this number,
so when dividing into data, as in normalizing, result is near zero
AveFrameSmooth - smoothing for the averaged frame(s)
verbose - if set, lots of information output listed
debug - if set, will output even more and may stop at some spots
NOTES:
see CheckBlobVel.txt for validation case
see /u/bdavis/w3_html/swdoc/Blob_Tilt_Calcs.txt for other facts.
populateblobs.pro reads a file of blob characteristics created from fcplayer.pro
or saveblobs.pro, which is usually called, together with populateblobs, from
loadblobs.pro. I.e.,
--loadblobs
--saveblobs
--findblobs
--fcfitellipse (returns tilts in radians, clockwise from zero to left)
--mpfitellipse
--blobfilewrite (writes file with tilts in radians, CW zero to left)
--populateblobs (reads file, and converts tilts to degrees)
EXAMPLES:
; for test blobs
loadblobs, 'circoneup_1.nc', t1=0., t2=0.010, horiz=0, norm=0
loadblobs, 'circoneout_2.nc', t1=0., t2=0.010, horiz=0, norm=0
loadblobs, 'circmany_3.nc', t1=0., t2=0.010, horiz=0, norm=0
loadblobs, 'elipseone_4.nc', t1=0., t2=0.010, horiz=0, norm=0
loadblobs, 'elipsemany_5.nc', t1=0., t2=0.010, horiz=0, norm=0
camDir = '/p/nstxcam-archive/Phantom710-9205/2010/'
loadblobs, camdir+'nstx_5_139286.cin', t1=0.312, t2=0.316
; NB scan
loadblobs, T1=0.500, T2=0.510, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139481.cin'
loadblobs, T1=0.500, T2=0.510, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139482.cin'
loadblobs, T1=0.500, T2=0.510, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139483.cin'
; Li scan
loadblobs, T1=0.580, T2=0.590, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141319.cin'
loadblobs, T1=0.580, T2=0.590, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141326.cin'
loadblobs, T1=0.530, T2=0.540, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141320.cin'
loadblobs, T1=0.530, T2=0.540, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141324.cin'
loadblobs, T1=0.530, T2=0.540, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141322.cin'
loadblobs, T1=0.480, T2=0.490, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141307.cin'
; two CMOD cameras for same shot
(when data retrieved from MDSplus at MIT, times are shot times):
loadblobs, T1=1.089, T2=1.091, /verb, table='SH1120224030x', $ ; cam near X-pt
/horiz, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120224030x_blobs_1116-1118ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, $
'shot_1120224030.cine'
loadblobs, T1=1.089, T2=1.091, /verb, table='SH1120224030m', $ ; cam near mid-plane
/horiz, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120224030m_blobs_1116-1118ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, $
'shot_1120224030.cin'
shot='1120224009' & t1=0.701 & t2=t1+0.005
shot='1120224015' & t1=0.801 & t2=t1+0.004
shot='1120224022' & t1=1.044 & t2=t1+0.004 ;
shot='1120224023' & t1=1.113 & t2=t1+0.003
shot='1120224024' & t1=1.130 & t2=t1+0.005
shot='1120224027' & t1=1.144 & t2=t1+0.004
shot='1120712026' & t1=1.144 & t2=t1+0.004
shot='1120712027' & t1=1.144 & t2=t1+0.004
shot='1120712028' & t1=1.144 & t2=t1+0.005 ;
shot='1120712029' & t1=1.144 & t2=t1+0.003
shot='1120815018' & t1=1.270 & t2=t1+0.004
shot='1120815021' & t1=1.190 & t2=t1+0.003
shot='1120815030' & t1=1.260 & t2=t1+0.004
shot='1120815034' & t1=1.150 & t2=t1+0.003
st1 = strtrim( string(t1*1000,format='(I4.4)'), 2)
st2 = strtrim( string(t2*1000,format='(I4.4)'), 2)
loadblobs, T1=t1, T2=t2, table='SH'+shot+'x', $ ; cam near X-pt
/horiz, /RotCW, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_'+shot+'x_blobs_'+st1+'-'+st2+'ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, FrameAveDeltaMS=0, $
'shot_'+shot+'.cine', /verb
loadblobs, T1=t1, T2=t2, table='SH'+shot+'m', $ ; cam near midplane
/horiz, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_'+shot+'m_blobs_'+st1+'-'+st2+'ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, FrameAveDeltaMS=0, $
'shot_'+shot+'.cin', /verb ; midplane camera file does not end in e
; for fake blobs covering whole center of image:
; and tilts
.r getfakeblobs
loadblobs, T1=0.080, T2=0.080+.002, /verb, table='FakeShotXall', $
nSmooth=3, /GaussSmooth, outFile='shot_1120815021FakeX_blobs_80-80ms.txt', $
norm=0, horiz=0, minHt=3, velSmooth=0, $
'/p/gpi/szweben/Phantom2_Data/2012_shots/1120815/shot_1120815021.cine'
loadblobs, T1=0.080, T2=0.080+.0055, /verb, table='FakeShotM', $
nSmooth=3, /GaussSmooth, outFile='shot_1120815021FakeM_blobs_80-80ms.txt', $
norm=0, horiz=0, minHt=3, velSmooth=0, $
'/p/gpi/szweben/Phantom_Data/2012_data/1120815/shot_1120815021.cin'
loadblobs, T1=0.080, T2=0.080+.0055, /verb, table='FakeShotXT', $
nSmooth=3, /GaussSmooth, outFile='shot_1120815021FakeXT_blobs_80-80ms.txt', $
norm=0, horiz=0, minHt=3, velSmooth=0, $
'/p/gpi/szweben/Phantom2_Data/2012_shots/1120815/shot_1120815021.cine'
loadblobs, T1=0.080, T2=0.080+.0055, /verb, table='FakeShotXT30', $
nSmooth=3, /GaussSmooth, outFile='shot_1120815021FakeXT30_blobs_80-80ms.txt', $
norm=0, horiz=0, minHt=3, velSmooth=0, $
'/p/gpi/szweben/Phantom2_Data/2012_shots/1120815/shot_1120815021.cine'
; two CMOD cameras for same shot:
loadblobs, T1=1.086, T2=1.088, /verb, table='SH1120224029x', $ ; cam near X-pt
/horiz, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120224029x_blobs_1086-1088ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, $
'shot_1120224029.cine'
loadblobs, T1=1.086, T2=1.088, /verb, table='SH1120224029m', $ ; cam near X-pt
/horiz, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120224029m_blobs_1086-1088ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, $
'shot_1120224029.cin'
; two CMOD cameras for same shot
(stewarts Movie is from 1.116-1.118, but stuff starts happening at 1.117):
loadblobs, T1=1.115, T2=1.117, /verb, table='SH1120224022x', $ ; cam near X-pt
/horiz, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120224022x_blobs_1116-1118ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, $
'shot_1120224022.cine'
loadblobs, T1=1.115, T2=1.117, /verb, table='SH1120224022m', $ ; cam near X-pt
/horiz, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120224022m_blobs_1116-1118ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, $
'shot_1120224022.cin'
loadblobs, T1=0.080, T2=0.090, /verb, table='SH1120815021xN', $ ; cam near X-pt
/horiz, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120815021xN_blobs_80-90ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, $
'/p/gpi/szweben/Phantom2_Data/2012_shots/1120815/shot_1120815021.cine'
loadblobs, T1=0.080, T2=0.090, /verb, table='SH1120815021mN', $ ; midplane cam
/horiz, minHt=0.33, minRise=0.04, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120815021mN_blobs_80-90ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, FrameOffset=25, $
'/p/gpi/szweben/Phantom_Data/2012_data/1120815/shot_1120815021.cin'
loadblobs, T1=0.080, T2=0.090, /verb, table='SH1120224022xN', $ ; cam near X-pt
/horiz, minHt=0.5, minRise=0.06, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120224022x_blobs_80-90ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, $
'/p/gpi/szweben/Phantom2_Data/2012_shots/1120224/shot_1120224022.cine'
loadblobs, T1=0.080, T2=0.090, /verb, table='SH1120224022mN', $ ; midplane cam
/horiz, minHt=0.33, minRise=0.04, Chi=5, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120224022m_blobs_80-90ms.txt', $
AveFrameSmooth=0, FrameAveMin=25, FrameOffset=25, $
'/p/gpi/szweben/Phantom_Data/2012_data/1120224/shot_1120224022.cin'
; two CMOD cameras for same shot -- try without normalization
loadblobs, T1=0.020, T2=0.040, /verb, table='SH1120815021x', $ ; cam near X-pt
/horiz, minHt=20, norm=0, minRise=4, Chi=8, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120815021x_blobs_20-40ms.txt', $
'/p/gpi/szweben/Phantom2_Data/2012_shots/1120815/shot_1120815021.cine'
loadblobs, T1=0.020, T2=0.040, /verb, table='SH1120815021m', $
/horiz, minHt=20, norm=0, minRise=4, Chi=8, velSmooth=0, $
nSmooth=3, /GaussSmooth, outFile='shot_1120815021m_blobs_20-40ms.txt', $
'/p/gpi/szweben/Phantom_Data/2012_data/1120815/shot_1120815021.cin'
; try that shot with normal params
loadblobs, T1=0.020, T2=0.040, /verb, table='SH1120815021', $
/horiz, outFile='shot_1120815021_blobs_20-40ms.txt', $
'/p/gpi/szweben/Phantom_Data/2012_data/1120815/shot_1120815021.cin'
; defaults work pretty well when normalizing:
loadblobs, T1=0, T2=0.020, /verb, $
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216017.cin'
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216018.cin'
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216019.cin'
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216023.cin'
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216025.cin'
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216026.cin'
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216028.cin'
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216029.cin'
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216030.cin'
loadblobs, T1=0.050, T2=0.070, /verb, $
'/p/gpi/szweben/Phantom_Data/2010_data/1100120/shot_1100120025.cin'
'/p/gpi/szweben/Phantom_Data/2010_data/1100120/shot_1100120026.cin'
'/p/gpi/szweben/Phantom_Data/2010_data/1100120/shot_1100120027.cin'
loadblobs, T1=0.050, T2=0.070, /verb, $
'/p/gpi/szweben/Phantom_Data/2010_data/1100803/shot_1100803005.cin'
'/p/gpi/szweben/Phantom_Data/2010_data/1100803/shot_1100803008.cin'
'/p/gpi/szweben/Phantom_Data/2010_data/1100803/shot_1100803011.cin'
'/p/gpi/szweben/Phantom_Data/2010_data/1100803/shot_1100803015.cin'
loadblobs, T1=0.060, T2=0.080, /verb, $
'/p/gpi/szweben/Phantom_Data/2010_data/1100824/shot_1100824017.cin'
'/p/gpi/szweben/Phantom_Data/2010_data/1100824/shot_1100824019.cin'
'/p/gpi/szweben/Phantom_Data/2010_data/1100824/shot_1100824021.cin'
loadblobs, T1=0, T2=0.020, /verb, $
'/p/gpi/szweben/Phantom_Data/2011_data/1110114/shot_1110114023.cin'
'/p/gpi/szweben/Phantom_Data/2011_data/1110114/shot_1110114026.cin'
'/p/gpi/szweben/Phantom_Data/2011_data/1110114/shot_1110114027.cin'
loadblobs, T1=0.017, T2=0.027, /verb, $
'/p/gpi/szweben/Phantom_Data/2011_data/1110114/shot_1110114032.cin'
For Matt:
loadblobs, T1=0.24, T2=0.27, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_142000.cin'
loadblobs, T1=0.219, T2=0.229, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138120.cin'
loadblobs, T1=0.225, T2=0.235, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138114.cin'
; APS NB
loadblobs, T1=0.280, T2=0.300, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138119.cin'
loadblobs, T1=0.290, T2=0.300, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138128.cin'
loadblobs, T1=0.280, T2=0.300, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_142220.cin'
loadblobs, T1=0.530, T2=0.550, /verb, FrameAveDeltaMS=0, table='SH138234z', $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138234.cin'
loadblobs, T1=0.268, T2=0.288, /verb, table='SH139432', $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139432.cin'
loadblobs, T1=0.258, T2=0.278, /verb, table='SH139444', $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139444.cin'
loadblobs, T1=0.200, T2=0.220, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141751.cin'
loadblobs, T1=0.210, T2=0.230, /verb, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141752.cin' , /deb
loadblobs, T1=0.021, T2=0.031, /verb, '/p/nstxcam/CMOD/shot_1120223031.cin' , /deb
to load a file, but not a database:
loadblobs, '/u/bdavis/Blobs/solt_012_3.5b.hdf', shot=99901203, dbout=0, $
outDBfile='solt_012_3.5b.txt', normalize=0, minHt=0.01, minRise=0.01
27-Feb-2012 added smoothing options, since default in findblobs now=0
MODIFICATION HISTORY:
30-Jun-2015 changed default of velSmooth to 0, so manual checks work
had no effect since
28-Mar-2014 added camera keyword
12-Mar-2014 made EFIT02 the default for separatrix calc
12-Nov-2012 made default GaussSmooth=1, to be consistent with FCplayer.
17-May-2012 several updates to pass parameters to saveblobs for file output
WRITTEN by Bill Davis, PPPL, for Stewart Zweben
NAME:
plotblobvyvsbin
PURPOSE:
plot a series of vertical velocity traces vs. time
from the blob database. Each trace will be from a horizontal
range
CATEGORY:
Blobs
CALLING SEQUENCE:
IDL> plotblobvyvsbin, shot=shot
KEYWORDS:
shot - shot (has to be in the database)
table - table in the database (name can be created from shot)
database - SQL database (default='blobs')
xBinSize - # of pixels to bin over in X (default=6)
tBinSize - time width over which to average velocities (default=0)
nSmooth - number of time points to smooth over before plotting
(default=21)
minHt - minimum normalized height for blobs to count (default=1.2)
needed - # of frames for which blob exists to count (default=2)
x1 - pixel location to start binning (defaults to min of center in data)
x2 - pixel location to stop binning
t1 - time to start data bining (default to start of times in database)
t2 - time to end binning (default to end of times in database)
VyMin - plot min (auto scales otherwise)
VyMax - plot max
colors - color indices for lines
charsize - character size for plot labels
yTitle - title for vertical axis
timeOffSet - time to add to camera times to get shot times (ms)
(can be automatically read from file for some shots)
jpeg - if set makes a jpeg in your home directory and prints the name
OUTPUTS:
just plotting
NOTES:
keywords for the PLOT command will be passed along
EXAMPLE:
IDL> plotblobvyvsbin, shot=1110114032, nSmooth=21
IDL> colors=[49,53,51,56,50,52]
IDL> plotblobvyvsbin, shot=1110114032, xbinsize=6, tBinSize=0.025, $
VyMin=-2, VyMax=3, xrange=[21,23],colors=colors, x1=25
IDL> plotblobvyvsbin, shot=1110114032, xbinsize=7, nsmooth=5, tbin=0.025, $
VyMin=-1, VyMax=1, xrange=[21,23],colors=colors, x1=25
IDL> plotblobvyvsbin, shot=1120223031, xbinsize=8, nsmooth=31, x1=32, /jpeg
WRITTEN 03-May-2012 by Bill Davis, PPPL, for Stewart Zweben
NAME:
populateblobs
PURPOSE:
Read a file created from fcplayer.pro with columns of blob
characteristics vs time. compute frame-to-frame statistics like x & y
velocity and duration, based on "reasonableness" factors, like maximum
movement per frame allowed. Velocities are recomputed after parent-child
relationships determined, so the velocity tracks can be smoothed.
(loadblobs.pro can be used for all the steps needed to populate the
database.)
CATEGORY:
Blobs
CALLING SEQUENCE:
IDL> populateblobs, filename=filename, table=table
INPUTS:
-------
filename - name of input file produced from FCplayer.
database - SQL database (server maintained by Tom Carroll) for blobs,
DEF='blobs'
make - if set, will try to create datbase table (if already exists, will
complain, but no harm done)
table - table name in database of blobs for a period within a shot, or
shot - will assume table is named 'SH'+shot
maxJump - max # of pixel to change per frame to be considered same blob
(DEF=10)
minFrames - minimum # of contigous frames blob must be identified to
be considered (DEF=3)
maxArea max area change (sq. pixels) per frame to be considered same blob
outFileName - if present, will write data to a table-delimited file
rather than an SQL database
BlobCriteria - structure for blob criteria, like min normalized height, etc.
(just for writing to the output "database" file.)
verbose - if set, lots of information output listed
debug - if set, will output even more and may stop at some spots
EXAMPLES:
filename='shot_1120815034m_blobs_1150-1153ms.txt'
outfile='shot_1120815034m_out.txt'
populateblobs, filename=filename, table=table, /deletefirst, $
timeoffset=0, shot=1120815034, outfile=outfile, $
/verb, doRhos=0
filename='shot_1120224022x_blobs_1044-1048ms.txt'
table = 'SH1120224022x'
populateblobs, filename=filename, table=table, /verb, /deletefirst, $
timeoffset=0, shot=1120224022
filename='/u/bdavis/cvs/idl_cvs/shot_1120815021Fake_blobs_80-80ms.txt'
table = 'FakeShot'
populateblobs, filename=filename, table=table, /verb , /make
filename='/u/bdavis/cvs/idl_cvs/shot_1091216028_blobs_0-20ms.txt'
table = 'SH1091216028'
populateblobs, filename=filename, table=table, /verb , /make
filename='/u/bdavis/cvs/idl_cvs/shot_1091216029_blobs_0-20ms.txt'
table = 'SH1091216029'
populateblobs, filename=filename, table=table, /verb , /make
filename='nstx_5_138234_blobs_530-550ms.txt'
table = 'SH138234'
populateblobs, filename=filename, table=table, /verb , /make
filename='nstx_5_138128_blobs_280-300ms.txt'
table = 'SH138128'
populateblobs, filename=filename, table=table, /verb, /deleteFirst , /debug
filename='nstx_5_142200_blobs_280-300ms.txt'
table = 'SH138128'
populateblobs, filename=filename, table=table, /verb , /make
filename='nstx_5_141751_blobs_200-220ms.txt'
table = 'SH141751'
populateblobs, filename=filename, table=table, /verb , /make
--- to write out a file that Stewart can read in Kalideograph:
filename='nstx_5_138234_blobs.txt'
populateblobs, filename=filename, out=filename+'OUT', /verb
NOTES
see CheckBlobVel.txt for validation case.
see /u/bdavis/w3_html/swdoc/Blob_Tilt_Calcs.txt for other facts.
MODIFICATION HISTORY:
29-Jun-2015 BD mk_blobtable now makes the blob # the primary key (Identity)
was getting warnings on this. Changed.
24-Jun-2014 BD "wholelife" was -1 for last occurence of blob. Also, when
blob just seen in one frame, make wholelife = delta time
10-Oct-2012 BD compute XfromSep at each time step
20-Sep-2012 BD back to no negative ellipticity.
Tilt stored in degrees, from PI/2 (straight up) to -Pi/2 (down)
and zero tilt is horizontal
04-Sep-2012 BD changed def of ellipticity, so can have < 1.
ellip = Major Radius/Minor Radius, if tilt between pi/4 and
3pi/4, then make ellipticity negative.
29-Aug-2012 BD added ellip, ellipHM and Rho (R-Rsep at midplane)
17-May-2012 BD several updates to receive parameters to output to file
06-Jan-2012 BD changing velocities from pixels/frame to Km/s. Adding column
in databases for x distance to the separatrix.
WRITTEN 2-Feb-2011 by Bill Davis for Stewart Szweben
NAME:
saveblobs
PURPOSE:
Save blob tracks, just like FCplayer, but easier and faster. Usually called from
LoadBlobs.pro.
CATEGORY:
blobs
CALLING SEQUENCE:
IDL> saveblobs, filename
INPUTS:
filename - a .cin or .hdf file containing plasma images
KEYWORD PARAMETERS:
filename - cine file to analyze
outfilename - output of text with blob info (default formed from inputs)
t1 & t2 - time range to load (in sec)
aveT1 - start for averaging frame (DEF=t1) (in sec)
aveT2 - ending time for averaging frame (DEF=t2)
horiz - if=0, do not flip frames horizontally
RotCCW - if set, will rotate frame Counter-clockwise (after horizontal flip)
default for NSTX, but not for CMOD
BlobCriteria - structure for blob criteria, like min normalized height, etc.
nSmooth - amount to smooth image before looking for blobs
GaussSmooth - if set, will do "gaussian" smoothing (sort of a double smooth)
instead of boxcar smoothing
FrameOffset - if set, subtract this (like a baseline) from all pixels
FrameAveMin - if set, make close-to-zero pixels this number,
so when dividing into data, as in normalizing, result is near zero
AveFrameSmooth - smoothing for the averaged frame(s)
FrameAveDeltaMS - make frames used for normalizing an average of this many millisec
EXAMPLES:
saveblobs, T1=0, T2=20, /verb, $
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216030.cin'
'/p/gpi/szweben/Phantom_Data/2010_data/1100120/shot_1100120025.cin'
saveblobs, T1=90, T2=92, /verb, $
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1110114/1110114026.cin'
saveblos, '/u/bdavis/Blobs/solt_012_3.5b.hdf', shot=99901203, norm=0
MODIFICATION HISTORY:
12-Nov-2012 added FrameAveDeltaMS keyword and feature to have an average for
a particular frame just be over this # of milliseconds.q
17-May-2012 several updates to receive parameters to output to file
01-Mar-2012 decided not to smooth average frame
WRITTEN 09-Feb-2012 by Bill Davis, PPPL, for Stewart Zweben
Category: Colors
[List of Routines]
NAME:
betterrainbow
PURPOSE:
Loads a rainbow color palette with 6 evenly-spaced (roughly) colors
CATEGORY:
Colors, Graphics
CALLING SEQUENCE:
IDL> betterrainbow
INPUTS:
NONE
KEYWORD PARAMETERS:
Optional Keywords:
BAR - if set, will draw a color bar on plot
nColors - # of colors to load (Defaults to !D.TABLE_SIZE)
lessRed - if set, rainbow will have a smaller red region
WhiteBottom - if set, there will be a white region at the bottom
topColor - can be an index or 'white' or 'black'
botColor - can be an index or 'white' or 'black'
linePlots - if set, top color will be black and bottom color will be white
noYellow - if set, don't have yellow (because doesn't show up well on white)
OUTPUTS:
NONE (color table changed)
EXAMPLE:
IDL> betterrainbow, botColor='white', /bar
IDL>
LIMITATIONS:
always starts at the bottom of color palette.
MODIFICATION HISTORY:
13-Aug-2012 mucked with white bottom
04-Nov-2011 smoothed out corners in green between 180 & 240, so discontinuity not
seen in organge
26-Aug-2011 added smooth parameter, default it to 50. Round off purple to
blue transition.
18-Jun-2008 added NoYellow keyword
02-Aug-2007 fix bug for /lineplot and ncolors<256;
if /linePlots keyword set, reset !p.color & !p.background
30-Apr-2007 added linePlots keyword
26-May-2006 added ncolors and whiteBottom keywords
14-Feb-2005 add topColor and botColor keywords
15-Jul-2002 Written by Bill Davis, PPPL
NAME:
colorSearch
PURPOSE:
Return color index (or closest available) from the color name.
CATEGORY:
Colors, Graphics
CALLING SEQUENCE:
index = colorSearch( colorName )
INPUT:
colorName: A string with the name of the color. 'WHITE','BLACK','YELLOW',
'RED','GREEN','BLUE','MAGENTA','YELLOW','ORANGE', 'PURPLE',
'DarkGreen','LTBLUE', 'GREY', 'GOLD','GreenYellow','PaleGoldenrod','BROWN',
'LightSeaGreen', 'SALMON', 'MediumVioletRed'
(colorName is NOT case sensitive)
Synonyms are handled as follows:
'GREY' = 'GRAY'
'DARKGRAY' = 'GRAY'
'CHARCOAL' = 'GRAY'
'AQUAMARINE' = 'GREEN'
'SKYBLUE' = 'LTBLUE'
'LT_BLUE' = 'LTBLUE'
'CYAN' = 'LTBLUE'
'DKBLUE' = 'BLUE'
'DARKBLUE' = 'BLUE'
'DK_BLUE' = 'BLUE'
'VIOLET' = 'MAGENTA'
or, if colorName =
'FOREGROUND' then simply return, !p.color
'BACKGROUND' then simply return, !p.background
KEYWORD PARAMETERS:
INIT - if set, will load color table 39 (rainbow with Black and white),
and !p.color will be set to black, and !p.background to white.
*** NOTE that the SET_PLOT command can change !p.color and !p.background.
debug - if set, will print informational messages
quiet - if set, will not warn if color found is not close to that asked for
status - if = 1, then color was found, else 0
RESTRICTIONS:
If match is not found it will return the index of the "closest" table location, and
status=0, and, if /quiet is not set, it will print a warning.
Note that the SET_PLOT command (from IDL Help):
"sets the default color !P.COLOR to the maximum color index minus one or,
in the case of devices with white backgrounds, such as PostScript, to 0 (black)."
After calling SET_PLOT,'X' or SET_PLOT,'Z' you will have to re-call a=colorSearch( /init )
to return to plotting black lines on a white background.
EXAMPLES:
plot, indgen(10), color=colorSearch( /init )
oplot, indgen(10)/2, color=colorSearch('red')
names = colorsearch( /RETURNnames )
dum = mk_color(table=32)
plot, indgen(280), ystyle=3, /nodata
for i=0, n_elements( names )-1 do oplot, [0,255], [colorsearch(names[i]),colorsearch(names[i])], $
color=colorsearch(names[i])
for i=0, n_elements( names )-1 do xyouts, 256,colorsearch(names[i]), names[i], color=colorsearch(names[i])
MODIFICATION HISTORY:
26-Jan-2007 Written by Bill Davis, PPPL
NAME:
DECOMPOSEDCOLOR
PURPOSE:
This function is used to determine, in a device independent way, if the
current graphics device is using color decomposition. The function returns
a 1 if color decomposition is turned on, and a 0 if it is turned off. When
color decomposition is turned on, we say the device is using a true-color
display. If color decomposition is turned off, we say the device is using
an indexed color display.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Colors
CALLING SEQUENCE:
result = DecomposedColor()
RETURN VALUE:
result: A 1 if color decomposition is turned on. A 0 if color decomposition is turned off.
ARGUMENTS:
device: The IDL graphics device whose color decomposition state you wish to know the
current value of. If undefined, the current graphics device is used.
KEYWORDRS:
DEPTH: An output keyword that returns the depth of the graphics device. Normally,
either 8 for index color devices, with color decomposition turned off, or 24
for true-color devices with color decomposition turned on.
EXAMPLE:
IDL> Print, DecomposedColor() ; Color decomposition state of current graphics device.
1
IDL> Print, DecomposedColor('PS') ; Color decomposition state of PostScript graphics device.
0
MODIFICATION HISTORY:
Written by: David W. Fanning, May 24, 2009.
Modified the way decomposition was obtained for PostScript devices IDL 7.1 and higher. 12 Dec 2010. DWF.
Fixed a problem in the CASE statement with ELSE clause and added a NULL device segment. 4 Jan 2011. DWF.
It now appears 24-bit PostScript support was added in IDL 7.1, although the Get_Decomposed keyword
didn't work until IDL 7.1.1. 13 January 2011. DWF
NAME:
mk_color
PURPOSE:
Create color tables with 12 fixed colors at the top. These colors
can be referenced by name.
CATEGORY:
Colors, Graphics
CALLING SEQUENCE:
index = mk_color( color )
index = mk_color( color, TABLE=5, MAX_COLORS_TO_USE = 128 )
OPTIONAL INPUTS:
COLOR: A string with the name of the color. 'WHITE','BLACK','YELLOW',
'RED','GREEN','BLUE','MAGENTA','LTBLUE', and (if device
supports more than 8 colors) 'GREY' are allowed.
Alternately, COLOR may be an integer from 0 - 8.
If the COLOR input is anything else, or not present, an index
for yellow is returned.
KEYWORD PARAMETERS:
LOAD: If set, return a structure containing all 8 colors.
e.g. IDL> c=MK_COLOR(/load)
IDL> plot,x,y,color=c.red
MAX_COLORS_TO_USE: The maximum number of colors to use for all of
IDL . The default
is 64 so IDL doesn't grab all the colors on a 256-color
monitor. If an IDL window, or a call to LOADCT, was made
before the first call to mk_color, the number of colors
will already have been allocated.
TABLE: The number of the pre-defined color table to load, from 0 to 40.
The same as for LOADCT. The default is 0.
FILE: If present, will load color table from this file.
These colors will be squeezed into the number of
colors used for the palette (N_NONFIXED colors).
N_NONFIXED (returned) number of colors other than the nine fixed ones.
e.g., MAX_COLORS_TO_USE-12.
SILENT: If this keyword is set, the Color Table message is suppressed.
SEARCH - if set, will do a least squares fit to color table to find
closest index to color -- good if color table was set outside
of mk_color
GAcolors - if set, create a color table with colors beginning at zero,
in the same order as GA color_setup routine.
COMMON BLOCKS:
mk_color_local
SIDE EFFECTS:
Limits the maximum number of colors for this IDL session.
(The default is 64 colors).
RESTRICTIONS:
Reserving the right number of colors only works if this is called
before any IDL window is drawn, and before LOADCT is called.
Good Luck if you try and run with 24-bit color.
If a device allows less than 12 colors (like Tek), the colors beyond
the number allowed will not be available.
EXAMPLES:
Simply:
plot,indgen(100),color=mk_color('red'),background=mk_color('white')
or:
plot,[0,1],[0,10]-1
for i=0,8 do oplot,[i,i],color=mk_color(i) ; to see all colors
x-y overlays:
PLOT,INDGEN(100),/NODATA, COLOR=MK_COLOR('blue') ; axes in blue
PLOT,INDGEN(100), COLOR=MK_COLOR('red') ; data in red
OPLOT,INDGEN(100)/2, COLOR=MK_COLOR('yellow') ; overlay yellow
Using color contours AND x-y plots:
array_2D = DIST(150) ; generate a test array
yellow_index = mk_color( TABLE=5, MAX_COLORS_TO_USE = 128, $
N_NONFIXED = n_nonfixed)
WINDOW, XSIZE=400, YSIZE=250 ; make wide window
TV, BYTSCL( array_2D, TOP = n_nonfixed-1 ), 25, 50 ; plot scaled 2-D image
PLOT, HISTOGRAM(array_2D), COLOR=mk_color('LtBlue'), $ ; lt. blue axes
POSITION=[0.55, 0.15, 0.95, 0.95], /NOERASE, /NODATA
OPLOT, HISTOGRAM(array_2D) > 10, COLOR=mk_color('Magenta') ; data in magenta
whatever = mk_color(TABLE=39) ; change colors of contours, but not lines
NOTES:
Tek Colors are 0=black, 1=white, 2=red, 3=green, 4=blue,
5=cyan, 6=magenta, 7=yellow, 8=orange.
default Green is [0,192,0] so it won't be so light.
MODIFICATION HISTORY:
29-Sep-2009 made dark green actually forest green, so shows up better.
make green [0,192,0] rather than [0,255,0], so not so bright.
24-May-04 moved creation of X-window when Z-buffer the device
(necessary when mk_color first called with PS or Z.)
22-Apr-2004 fixed bug when Z-buffer set on first call.
14-Nov-03 - fixed new bug for Tek colors.
13-Mar-03 - if requested color not found, try to find black (instead of yellow)
if ask for 'FOREGROUND' or 'BACKGROUND' return !p values.
GAcolor Keyword for doing colors like GA (same order and position)
20-Aug-02 - set !p.color & !p.background to previous colors (closest
r,g,b value), when called the first time, or when changing
color tables. Add FILE keyword
07-Mar-02 - Change !d.n_colors to !d.table_size
08-May-01 - When in Tek, make !p.color=black (was going to index 15)
23-Apr-01 - added three more colors (orange, purple, darkgreen)
26-Jan-01 - limit structure returned to !d.n_colors (e.g., when=2).
28-Sep-00 - Added bottom keyword (passes straight through to loadct)
24-Jan-00 - If color found at multiple indices, return highest valid one
02-Jan-00 - Both /LOAD and individual colors return valid indices in
24-bit mode.
05-Oct-99 - BD Synonyms & Structure return as in new D. Fanning routine.
09-Jun-99 - BD If desired color not found, return index of nearest color.
11-May-99 - BD make return valid values for 24-bit (decomposed) color
28-Jan-99 - BD handle device with less than 9 colors.
14-Dec-98 - BD allow COLOR input to be an integer from 0-8.
Return index of 0 when color not found in table.
04-Dec-98 - Bill Davis changed GETCOLORS to load color table, return color
index, etc. Colors were added.
GETCOLORS Written by: David Fanning, 10 February 96.
NAME:
stretchsteps
PURPOSE:
stretch parts of the color tables into steps.
CATEGORY:
Colors, Image processing
CALLING SEQUENCE:
stretchsteps, Low, High, steps=n [, /CHOP]
INPUTS:
Low: The lowest pixel value to use. If this parameter is omitted,
0 is assumed. Appropriate values range from 0 to the number
of available colors-1.
High: The highest pixel value to use. If this parameter is omitted,
the number of colors-1 is assumed. Appropriate values range
from 0 to the number of available colors-1.
OPTIONAL INPUTS:
Gamma: Gamma correction factor. If this value is omitted, 1.0 is
assumed. Gamma correction works by raising the color indices
to the Gamma power, assuming they are scaled into the range
0 to 1.
steps: number of steps/colors of the resulting color table (default=16)
KEYWORD PARAMETERS:
CHOP: If this keyword is set, color values above the upper threshold
are set to color index 0. Normally, values above the upper
threshold are set to the maximum color index.
OUTPUTS:
No explicit outputs.
COMMON BLOCKS:
COLORS: The common block that contains R, G, and B color
tables loaded by LOADCT, HSV, HLS and others.
SIDE EFFECTS:
Image display color tables are loaded.
RESTRICTIONS:
Common block COLORS must be loaded before calling stretchsteps.
PROCEDURE:
New R, G, and B vectors are created by linearly interpolating
the vectors in the common block from Low to High. Vectors in the
common block are not changed.
If NO parameters are supplied, the original color tables are
restored.
EXAMPLE:
Load the STD GAMMA-II color table by entering:
LOADCT, 5
Create and display and image by entering:
TVSCL, DIST(300)
Now adjust the color table with stretchsteps. Make the entire color table
fit in the range 0 to 70 by entering:
stretchsteps, 0, 70
Notice that pixel values above 70 are now colored white. Restore the
original color table by entering:
stretchsteps
MODIFICATION HISTORY:
26-May-2006 Fixed green & blue switch & get color table rather than
relying on common block [BD]
18-Dec-2002 Modified RSI STRETCH.PRO [BD]
DMS, RSI, Dec, 1983.
DMS, April, 1987. Changed common.
DMS, October, 1987. For unix.
DMS, RSI, Nov., 1990. Added GAMMA parameter.
NAME:
whiteout
PURPOSE:
white-out a portion of the color table
-- defaults to the 5 lowest locs.
CATEGORY:
Colors, Graphics
CALLING SEQUENCE:
IDL> whiteout
INPUTS:
NONE
KEYWORD PARAMETERS:
Optional Keywords:
loc - index within color table to start whiting out (Default=0)
nlocs - number of locations to whiteout (Default=5
OUTPUTS:
NONE (color table changed)
LIMITATIONS:
Reloading color table will undo this.
MODIFICATION HISTORY:
May-2006 Written by Bill Davis, PPPL
Category: Compound widgets
[List of Routines]
NAME:
CW_BGROUP3_6
PURPOSE:
CW_BGROUP3_6 is a compound widget that simplifies creating
a base of buttons. It handles the details of creating the
proper base (standard, exclusive, or non-exclusive) and filling
in the desired buttons. Events for the individual buttons are
handled transparently, and a CW_BGROUP3_6 event returned. This
event can return any one of the following:
- The Index of the button within the base.
- The widget ID of the button.
- The name of the button.
- An arbitrary value taken from an array of User values.
CATEGORY:
Compound widgets.
CALLING SEQUENCE:
Widget = CW_BGROUP3_6(Parent, Names)
To get or set the value of a CW_BGROUP3_6, use the GET_VALUE and
SET_VALUE keywords to WIDGET_CONTROL. The value of a CW_BGROUP3_6
is:
-----------------------------------------------
Type Value
-----------------------------------------------
normal None
exclusive Index of currently set button
non-exclusive Vector indicating the position
of each button (1-set, 0-unset)
-----------------------------------------------
INPUTS:
Parent: The ID of the parent widget.
Names: A string array, containing one string per button,
giving the name of each button.
KEYWORD PARAMETERS:
BUTTON_UVALUE: An array of user values to be associated with
each button and returned in the event structure.
COLUMN: Buttons will be arranged in the number of columns
specified by this keyword.
EVENT_FUNCT: The name of an optional user-supplied event function
for buttons. This function is called with the return
value structure whenever a button is pressed, and
follows the conventions for user-written event
functions.
EXCLUSIVE: Buttons will be placed in an exclusive base, with
only one button allowed to be selected at a time.
FONT: The name of the font to be used for the button
titles. If this keyword is not specified, the default
font is used.
FRAME: Specifies the width of the frame to be drawn around
the base.
IDS: A named variable into which the button IDs will be
stored, as a longword vector.
LABEL_LEFT: Creates a text label to the left of the buttons.
LABEL_TOP: Creates a text label above the buttons.
MAP: If set, the base will be mapped when the widget
is realized (the default).
NONEXCLUSIVE: Buttons will be placed in an non-exclusive base.
The buttons will be independent.
NO_RELEASE: If set, button release events will not be returned.
RETURN_ID: If set, the VALUE field of returned events will be
the widget ID of the button.
RETURN_INDEX: If set, the VALUE field of returned events will be
the zero-based index of the button within the base.
THIS IS THE DEFAULT.
RETURN_NAME: If set, the VALUE field of returned events will be
the name of the button within the base.
ROW: Buttons will be arranged in the number of rows
specified by this keyword.
SCROLL: If set, the base will include scroll bars to allow
viewing a large base through a smaller viewport.
SET_VALUE: The initial value of the buttons. This is equivalent
to the later statement:
WIDGET_CONTROL, widget, set_value=value
SPACE: The space, in pixels, to be left around the edges
of a row or column major base. This keyword is
ignored if EXCLUSIVE or NONEXCLUSIVE are specified.
UVALUE: The user value to be associated with the widget.
XOFFSET: The X offset of the widget relative to its parent.
XPAD: The horizontal space, in pixels, between children
of a row or column major base. Ignored if EXCLUSIVE
or NONEXCLUSIVE are specified.
XSIZE: The width of the base.
X_SCROLL_SIZE: The width of the viewport if SCROLL is specified.
YOFFSET: The Y offset of the widget relative to its parent.
YPAD: The vertical space, in pixels, between children of
a row or column major base. Ignored if EXCLUSIVE
or NONEXCLUSIVE are specified.
YSIZE: The height of the base.
Y_SCROLL_SIZE: The height of the viewport if SCROLL is specified.
OUTPUTS:
The ID of the created widget is returned.
SIDE EFFECTS:
This widget generates event structures with the following definition:
event = { ID:0L, TOP:0L, HANDLER:0L, SELECT:0, VALUE:0 }
The SELECT field is passed through from the button event. VALUE is
either the INDEX, ID, NAME, or BUTTON_UVALUE of the button,
depending on how the widget was created.
RESTRICTIONS:
Only buttons with textual names are handled by this widget.
Bitmaps are not understood.
MODIFICATION HISTORY:
15 June 1992, AB
7 April 1993, AB, Removed state caching.
NAME:
CW_PDList
PURPOSE:
A compound widget that simplifies creating
pulldown menus. It has a simpler interface than the XPDMENU
procedure, which it is intended to replace. Events for the
individual buttons are handled transparently, and a CW_PDList
event returned. This event can return any one of the following:
- The Index of the button within the base.
- The widget ID of the button.
- The name of the button.
- The fully qualified name of the button. This allows
different sub-menus to contain buttons with the same
name in an unambiguous way.
CATEGORY:
Compound widgets.
CALLING SEQUENCE:
widget = CW_PDList(Parent, Desc)
INPUTS:
Parent: The ID of the parent widget.
Desc: An array of strings or structures. Each element contains
a menu description with two fields, a flag field, and
the name of the item. If a structure, each element
is defined as follows:
{ CW_PDList_S, flags:0, name:'' }
The name tag gives the name of button. The flags
field is a two-bit bitmask that controls how the button is
interpreted:
Value Meaning
-------------------------------------------
0 This button is neither the beginning
nor the end of a pulldown level.
1 This button is the root of a
sub-pulldown menu. The sub-buttons
start with the next button.
2 This button is the last button at the
current pulldown level. The next button
belongs to the same level as the current
parent button.
If none or empty string is specified as a
the name, the button is not created, but
the next button belongs to the upward level.
3 This button is the root of a sub-pulldown
menu, but it is also the last entry of
the current level.
4 Same as 0, above, except that this button will
be preceeded by a separator as with the SEPARATOR
keyword to WIDGET_BUTTON.
5 Same as 1, above, except that this button will
be preceeded by a separator.
6 Same as 2, above, except that this button will
be preceeded by a separator.
7 Same as 3, above, except that this button will
be preceeded by a separator.
If Desc is a string, each element contains the flag field
followed by a backslash character, followed by the menu item's
contents. See the example below.
EVENT PROCEDURES: An event procedure may be specified for an
element and all its children, by including a third field
in Desc, if Desc is a string array. Events for buttons without
an event procedure, are dispatched normally.
See the example below.
KEYWORD PARAMETERS:
DELIMITER: The character used to separate the parts of a
fully qualified name in returned events. The
default is to use the '.' character.
FONT: The name of the font to be used for the button
titles. If this keyword is not specified, the
default font is used.
HELP: If MBAR is specified and one of the buttons on the
menubar has the label "help" (case insensitive) then
that button is created with the /HELP keyword to
give it any special appearance it is supposed to
have on a menubar. For example, Motif expects
help buttons to be on the right.
IDS: A named variable into which the button IDs will
be stored as a longword vector.
MBAR: if constructing a menu-bar pulldown, set this
keyword. In this case, the parent must be the
widget id of the menu bar of a top-level base,
returned by WIDGET_BASE(..., MBAR=mbar).
RETURN_ID: If present and non-zero, the VALUE field of returned
events will be the widget ID of the button.
RETURN_INDEX: If present and non-zero, the VALUE field of returned
events will be the zero-based index of the button
within the base. THIS IS THE DEFAULT.
RETURN_NAME: If present and non-zero, the VALUE field of returned
events will be the name of the selected button.
RETURN_FULL_NAME: If present and non-zero, the VALUE field of returned
events will be the fully qualified name of the
selected button. This means that the names of all
the buttons from the topmost button of the pulldown
menu to the selected one are concatenated with the
delimiter specified by the DELIMITER keyword. For
example, if the top button was named COLORS, the
second level button was named BLUE, and the selected
button was named LIGHT, the returned value would be
COLORS.BLUE.LIGHT
This allows different submenus to have buttons with
the same name (e.g. COLORS.RED.LIGHT).
UVALUE: The user value to be associated with the widget.
UNAME: The user name to be associated with the widget.
XOFFSET: The X offset of the widget relative to its parent.
YOFFSET: The Y offset of the widget relative to its parent.
OUTPUTS:
The ID of the top level button is returned.
SIDE EFFECTS:
This widget generates event structures with the following definition:
event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0 }
VALUE is either the INDEX, ID, NAME, or FULL_NAME of the button,
depending on how the widget was created.
RESTRICTIONS:
Only buttons with textual names are handled by this widget.
Bitmaps are not understood.
EXAMPLE:
The following is the description of a menu bar with two buttons,
"Colors" and "Quit". Colors is a pulldown containing the colors
"Red", "Green", Blue", "Cyan", and "Magenta". Blue is a sub-pulldown
containing "Light", "Medium", "Dark", "Navy", and "Royal":
; Make sure CW_PDList_S is defined
junk = { CW_PDList_S, flags:0, name:'' }
; The description
desc = [ { CW_PDList_S, 1, 'Colors' }, $
{ CW_PDList_S, 0, 'Red' }, $
{ CW_PDList_S, 0, 'Green' }, $
{ CW_PDList_S, 5, 'Blue\BLUE_EVENT_PROC' }, $
{ CW_PDList_S, 0, 'Light' }, $
{ CW_PDList_S, 0, 'Medium' }, $
{ CW_PDList_S, 0, 'Dark' }, $
{ CW_PDList_S, 0, 'Navy' }, $
{ CW_PDList_S, 2, 'Royal' }, $
{ CW_PDList_S, 4, 'Cyan' }, $
{ CW_PDList_S, 2, 'Magenta\MAGENTA_EVENT_PROC' }, $
{ CW_PDList_S, 2, 'Quit' } ]
The same menu may be defined as a string by equating the Desc parameter
to the following string array:
desc =[ '1\Colors' , $
'0\Red' , $
'0\Green' , $
'5\Blue\BLUE_EVENT_PROC' , $
'0\Light' , $
'0\Medium' , $
'0\Dark' , $
'0\Navy' , $
'2\Royal' , $
'4\Cyan' , $
'2\Magenta\MAGENTA_EVENT_PROC' , $
'2\Quit' ]
The following small program can be used with the above description
to create the specified menu:
base = widget_base()
menu = CW_PDList(base, desc, /RETURN_FULL_NAME)
WIDGET_CONTROL, /REALIZE, base
repeat begin
ev = WIDGET_EVENT(base)
print, ev.value
end until ev.value eq 'Quit'
WIDGET_CONTROL, /DESTROY, base
end
Note that independent event procedures were specified for
the multiple Blue buttons (blue_event_proc), and the Magenta button
(magenta_event_proc).
MODIFICATION HISTORY:
18 June 1992, AB
16 Jan 1995, DMS, Added MBAR keyword, event procedures,
and menu descriptor strings.
2 July 1995, AB, Added HELP keyword.
3 September 1996, LP, Added button-less end of current level
Apirl, 2003 copied from CW_PDMENU. added xsize & event_pro keywords.
setting showSelection keyword will cause the menu
selection to be displayed as the title of the button [BD]
NAME:
CW_PDMENU
PURPOSE:
CW_PDMENU is a compound widget that simplifies creating
pulldown menus. It has a simpler interface than the XPDMENU
procedure, which it is intended to replace. Events for the
individual buttons are handled transparently, and a CW_PDMENU
event returned. This event can return any one of the following:
- The Index of the button within the base.
- The widget ID of the button.
- The name of the button.
- The fully qualified name of the button. This allows
different sub-menus to contain buttons with the same
name in an unambiguous way.
CATEGORY:
Compound widgets.
CALLING SEQUENCE:
widget = CW_PDMENU(Parent, Desc)
INPUTS:
Parent: The ID of the parent widget.
Desc: An array of strings or structures. Each element contains
a menu description with two fields, a flag field, and
the name of the item. If a structure, each element
is defined as follows:
{ CW_PDMENU_S, flags:0, name:'' }
The name tag gives the name of button. The flags
field is a two-bit bitmask that controls how the button is
interpreted:
Value Meaning
-------------------------------------------
0 This button is neither the beginning
nor the end of a pulldown level.
1 This button is the root of a
sub-pulldown menu. The sub-buttons
start with the next button.
2 This button is the last button at the
current pulldown level. The next button
belongs to the same level as the current
parent button.
If none or empty string is specified as a
the name, the button is not created, but
the next button belongs to the upward level.
3 This button is the root of a sub-pulldown
menu, but it is also the last entry of
the current level.
4 Same as 0, above, except that this button will
be preceeded by a separator as with the SEPARATOR
keyword to WIDGET_BUTTON.
5 Same as 1, above, except that this button will
be preceeded by a separator.
6 Same as 2, above, except that this button will
be preceeded by a separator.
7 Same as 3, above, except that this button will
be preceeded by a separator.
If Desc is a string, each element contains the flag field
followed by a backslash character, followed by the menu item's
contents. See the example below.
EVENT PROCEDURES: An event procedure may be specified for an
element and all its children, by including a third field
in Desc, if Desc is a string array. Events for buttons without
an event procedure, are dispatched normally.
See the example below.
KEYWORD PARAMETERS:
DELIMITER: The character used to separate the parts of a
fully qualified name in returned events. The
default is to use the '.' character.
FONT: The name of the font to be used for the button
titles. If this keyword is not specified, the
default font is used.
HELP: If MBAR is specified and one of the buttons on the
menubar has the label "help" (case insensitive) then
that button is created with the /HELP keyword to
give it any special appearance it is supposed to
have on a menubar. For example, Motif expects
help buttons to be on the right.
IDS: A named variable into which the button IDs will
be stored as a longword vector.
MBAR: if constructing a menu-bar pulldown, set this
keyword. In this case, the parent must be the
widget id of the menu bar of a top-level base,
returned by WIDGET_BASE(..., MBAR=mbar).
RETURN_ID: If present and non-zero, the VALUE field of returned
events will be the widget ID of the button.
RETURN_INDEX: If present and non-zero, the VALUE field of returned
events will be the zero-based index of the button
within the base. THIS IS THE DEFAULT.
RETURN_NAME: If present and non-zero, the VALUE field of returned
events will be the name of the selected button.
RETURN_FULL_NAME: If present and non-zero, the VALUE field of returned
events will be the fully qualified name of the
selected button. This means that the names of all
the buttons from the topmost button of the pulldown
menu to the selected one are concatenated with the
delimiter specified by the DELIMITER keyword. For
example, if the top button was named COLORS, the
second level button was named BLUE, and the selected
button was named LIGHT, the returned value would be
COLORS.BLUE.LIGHT
This allows different submenus to have buttons with
the same name (e.g. COLORS.RED.LIGHT).
UVALUE: The user value to be associated with the widget.
UNAME: The user name to be associated with the widget.
XOFFSET: The X offset of the widget relative to its parent.
YOFFSET: The Y offset of the widget relative to its parent.
OUTPUTS:
The ID of the top level button is returned.
SIDE EFFECTS:
This widget generates event structures with the following definition:
event = { ID:0L, TOP:0L, HANDLER:0L, VALUE:0 }
VALUE is either the INDEX, ID, NAME, or FULL_NAME of the button,
depending on how the widget was created.
RESTRICTIONS:
Only buttons with textual names are handled by this widget.
Bitmaps are not understood.
EXAMPLE:
The following is the description of a menu bar with two buttons,
"Colors" and "Quit". Colors is a pulldown containing the colors
"Red", "Green", Blue", "Cyan", and "Magenta". Blue is a sub-pulldown
containing "Light", "Medium", "Dark", "Navy", and "Royal":
; Make sure CW_PDMENU_S is defined
junk = { CW_PDMENU_S, flags:0, name:'' }
; The description
desc = [ { CW_PDMENU_S, 1, 'Colors' }, $
{ CW_PDMENU_S, 0, 'Red' }, $
{ CW_PDMENU_S, 0, 'Green' }, $
{ CW_PDMENU_S, 5, 'Blue\BLUE_EVENT_PROC' }, $
{ CW_PDMENU_S, 0, 'Light' }, $
{ CW_PDMENU_S, 0, 'Medium' }, $
{ CW_PDMENU_S, 0, 'Dark' }, $
{ CW_PDMENU_S, 0, 'Navy' }, $
{ CW_PDMENU_S, 2, 'Royal' }, $
{ CW_PDMENU_S, 4, 'Cyan' }, $
{ CW_PDMENU_S, 2, 'Magenta\MAGENTA_EVENT_PROC' }, $
{ CW_PDMENU_S, 2, 'Quit' } ]
The same menu may be defined as a string by equating the Desc parameter
to the following string array:
desc =[ '1\Colors' , $
'0\Red' , $
'0\Green' , $
'5\Blue\BLUE_EVENT_PROC' , $
'0\Light' , $
'0\Medium' , $
'0\Dark' , $
'0\Navy' , $
'2\Royal' , $
'4\Cyan' , $
'2\Magenta\MAGENTA_EVENT_PROC' , $
'2\Quit' ]
The following small program can be used with the above description
to create the specified menu:
base = widget_base()
menu = cw_pdmenu(base, desc, /RETURN_FULL_NAME)
WIDGET_CONTROL, /REALIZE, base
repeat begin
ev = WIDGET_EVENT(base)
print, ev.value
end until ev.value eq 'Quit'
WIDGET_CONTROL, /DESTROY, base
end
Note that independent event procedures were specified for
the multiple Blue buttons (blue_event_proc), and the Magenta button
(magenta_event_proc).
MODIFICATION HISTORY:
18 June 1992, AB
16 Jan 1995, DMS, Added MBAR keyword, event procedures,
and menu descriptor strings.
2 July 1995, AB, Added HELP keyword.
3 September 1996, LP, Added button-less end of current level
Apirl, 2003 added xsize & event_pro keywords. [BD]
July, 2003 removed setting ids in structure in UVALUE
Category: Database
[List of Routines]
NAME:
create_locus_table
PURPOSE:
Create a table in the Locus database following the convention
of data columns named xx0, xx1, xx2, etc.
CATEGORY:
Database, SQL
CALLING SEQUENCE:
IDL> create_locus_table, table, nvars
INPUTS:
table - table name to create in Locus database
nvars - number of variable in table (not counting shot & times)
KEYWORD PARAMETERS:
Optional Inputs:
database - if not present, will default to 'locus'
columns - if not present, will be named 'xx0', 'xx1', 'xx2', etc. as needed
by Locus. These are in addition to the required columns, shot, time, etc.
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
status - if odd, then success
OUTPUTS:
EXAMPLE:
IDL> create_locus_table, 'metals', 7
or
IDL> columns=['Zn','Ar','Li','Al','C']
IDL> create_locus_table, 'metals', n_elements(columns), columns=columns
NOTES:
You need to have permission to create tables in the database
(else send email to dbadmin).
You will need a file called locus.sybase_login in your home
directory -- it can be created with commands similar to those in
/p/nstxusr/util/setup/mkmdsplusdbfile.csh
MODIFICATION HISTORY:
19-Oct-2009 Written by Bill Davis, PPPL
NAME:
db_columns
PURPOSE:
list database tables and columns in which the column name
contains a string.
CATEGORY:
Database
USE:
IDL> info = db_columns( wildCard='te')
or IDL> info = db_columns( 'te', /print)
KEYWORDS:
wildCard - string to match
(do not include *'s or other wildcard strings)
dataBase - database to search. Defaults to nstxlogs.
print - if set, will print tables and columns fitting criteria
WRITTEN Oct-2002 by Bill Davis
NAME:
db_list
PURPOSE:
List info from an NSTX Database Table; especially to be displayed
in output from a Web Tool database, like
http://nstx.pppl.gov/nstx/Software/WebTools/searchefitdb.html.
Searches from a database will be MUCH faster than from MDSplus trees.
CATEGORY:
Database, NSTX, Web Tools
CALLING SEQUENCE:
IDL> db_list, shot1=shot1, shot2=shot2, runID=runID, $
rundate=rundate, username=username, $
str1=str1, str2=str2, str3=str3, logical1=logical1, logical2=logical2, $
database=database, include=include, outFile=outFile
INPUTS:
(none required)
KEYWORD PARAMETERS:
(all optional)
shot1 - beginning shot, e.g., 120200
shot2 - ending shot (if missing, will just search 100 shots before shot1)
database - database to query; defaults to 'NSTXLOGS'
table - table in database to query; defaults to 'EFIT02'
outFile - string (if not present, data listed to screen)
_extra - contains all the (arbitrary) parameters for the query.
These must be the column names in the table; e.g., gapin1=gapin1
qualifiers ending with 1 or 2 are limits for that parameter
if value = '*', want to list parameter, but not include in qualifier
OUTPUTS:
data to screen or file, if specified. File can be displayed in the calling web page.
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> db_list, shot1=120200
IDL> db_list, rundate=20060426 ; all shots from Apri. 25, 2006
IDL> db_list, shot1=120200, shot2=120500, pnbi1=600000
MODIFICATION HISTORY:
20-Dec-2007 Written by Bill Davis, PPPL
NAME:
logbook_list_plus
PURPOSE:
List info from the NSTX logbook (to a screen or file)
CATEGORY:
Database, NSTX
CALLING SEQUENCE:
IDL> logbook_list_plus, shot1=shot1, shot2=shot2, XP=XP, $
rundate=rundate, username=username, $
str1=str1, str2=str2, str3=str3, logical1=logical1, logical2=logical2, $
database=database, include=include, outFile=outFile
INPUTS:
(none required)
KEYWORD PARAMETERS:
(all optional)
shot1 - beginning shot, e.g., 120200
shot2 - ending shot (if missing, will just search shot1)
XP - Typically the XP #, e.g., 5
rundate - run date (YYYYMMDD), e.g., 20060426
username - computer username of person who made the entry, e.g. 'KAYE'
str1, str2, str3 - strings that must be in the comments for a shot to be included
logical1, logical2, 'AND' or 'OR' between str1, 2, & 3
include - if NOT=0 and USERNAME specified then include any entries satisfying
other criteria for which TOPIC='PHS OPS' or 'SESSION LEADER'
database - defaults to 'NSTXLOGS'
break - if set, lines longer than 72 characters will be broken at an earlier space
outFile - string (if not present, data listed to screen)
xsize - horizontal size of plot summary
ysize - vertical size of plot summary
OUTPUTS:
data to screen or file, if specified
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> logbook_list_plus, shot1=120200
IDL> logbook_list_plus, rundate=20060426 ; all shots from April 25, 2006
IDL> logbook_list_plus, shot1=120200, shot2=130000, username='PAUL'
IDL> logbook_list_plus, shot1=120200, /verb, /debug, outfile='temp.html'
MODIFICATION HISTORY:
29-Jan-2015 moved JPEG directory to /w/nstx.pppl.gov/htdocs/nstx_site.data/Scratch/
so it wouldn't get searched from the software web page
09-Jan-2014 added "lastrundate" keyword, so can get a range of days.
09-Aug-2013 don't set shot # if blank, but rundate specified.
11-Jul-2012 make work if just username specified (didn't use %) and allow strings
of shot numbers.
24-Aug-2010 included 'RF' as default entries.
26-Jul-2010 addes for having checkboxes for topics on weblogplus.html
15-Jul-2010 made lightning fast by searching subdirectories like 138000s for plot
summary files. See mkandmv.pro to make these directories and move files.
08-Apr-2010 allow pre-existing jpegs to be in subdirectories
08-Dec-2009 added keywords charsize, xsize, ysize
14-Jul-2009 Return error if no entries found
25-Jul-2008 Removed RunID keyword, and added XP [BD]
10-Jul-2008 Added "order by shot" to query, so all shots shown
29-Nov-2007 Had to change supersep to wrap long lines
28-Nov-2007 Written by Bill Davis, PPPL (some code from Josh Stillerman)
NAME:
logbook_list
PURPOSE:
List info from the NSTX logbook (to a screen or file)
CATEGORY:
Database, NSTX
CALLING SEQUENCE:
IDL> logbook_list, shot1=shot1, shot2=shot2, runID=runID, $
rundate=rundate, username=username, $
str1=str1, str2=str2, str3=str3, logical1=logical1, logical2=logical2, $
database=database, include=include, outFile=outFile
INPUTS:
(none required)
KEYWORD PARAMETERS:
(all optional)
shot1 - beginning shot, e.g., 120200
shot2 - ending shot (if missing, will just search shot1)
runID - Typically the XP #, e.g., 5
rundate - run date (YYYYMMDD), e.g., 20060426
username - computer username of person who made the entry, e.g. 'KAYE'
str1, str2, str3 - strings that must be in the comments for a shot to be included
logical1, logical2, 'AND' or 'OR' between str1, 2, & 3
include - if NOT=0 and USERNAME specified then include any entries satisfying
other criteria for which TOPIC='PHS OPS' or 'SESSION LEADER'
database - defaults to 'NSTXLOGS'
break - if set, lines longer than 72 characters will be broken at an earlier space
outFile - string (if not present, data listed to screen)
OUTPUTS:
data to screen or file, if specified
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> logbook_list, shot1=120200
IDL> logbook_list, rundate=20060426 ; all shots from Apri. 25, 2006
IDL> logbook_list, shot1=120200, shot2=130000, username='PAUL'
MODIFICATION HISTORY:
07-Apr-2009 made response better when nothing found
29-Nov-2007 Had to change supersep to wrap long lines
28-Nov-2007 Written by Bill Davis, PPPL (some code from Josh Stillerman)
NAME:
logbook_options (copied from logbook_options)
PURPOSE:
List info from the NSTX logbook (to a screen or file)
CATEGORY:
Database, NSTX
CALLING SEQUENCE:
IDL> logbook_options, shot1=shot1, shot2=shot2, XP=XP, $
rundate=rundate, username=username, $
str1=str1, str2=str2, str3=str3, logical1=logical1, logical2=logical2, $
database=database, include=include, outFile=outFile
INPUTS:
(none required)
KEYWORD PARAMETERS:
(all optional)
shot1 - beginning shot, e.g., 120200
shot2 - ending shot (if missing, will just search shot1)
XP - Typically the XP #, e.g., 5
rundate - run date (YYYYMMDD), e.g., 20060426
username - computer username of person who made the entry, e.g. 'KAYE'
str1, str2, str3 - strings that must be in the comments for a shot to be included
logical1, logical2, 'AND' or 'OR' between str1, 2, & 3
include - if NOT=0 and USERNAME specified then include any entries satisfying
other criteria for which TOPIC='PHS OPS' or 'SESSION LEADER'
database - defaults to 'NSTXLOGS'
break - if set, lines longer than 72 characters will be broken at an earlier space
outFile - string (if not present, data listed to screen)
xsize - horizontal size of plot summary
ysize - vertical size of plot summary
OUTPUTS:
data to screen or file, if specified
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> logbook_options, shot1=120200
IDL> logbook_options, rundate=20060426 ; all shots from April 25, 2006
IDL> logbook_options, shot1=120200, shot2=130000, username='PAUL'
IDL> logbook_options, shot1=120200, /verb, /debug, outfile='temp.html'
MODIFICATION HISTORY:
24-Aug-2010 included 'RF' as default entries.
26-Jul-2010 addes for having checkboxes for topics on weblogplus.html
15-Jul-2010 made lightning fast by searching subdirectories like 138000s for plot
summary files. See mkandmv.pro to make these directories and move files.
08-Apr-2010 allow pre-existing jpegs to be in subdirectories
08-Dec-2009 added keywords charsize, xsize, ysize
14-Jul-2009 Return error if no entries found
25-Jul-2008 Removed RunID keyword, and added XP [BD]
10-Jul-2008 Added "order by shot" to query, so all shots shown
29-Nov-2007 Had to change supersep to wrap long lines
28-Nov-2007 Written by Bill Davis, PPPL (some code from Josh Stillerman)
NAME: SYB_ENTRY
PURPOSE : Display/modify/create entries in the NSTX logbook database.
CATEGORY:
Database
CALLING SEQUENCE:
IDL> SYB_ENTRY
IDL> syb_entry, font=find_font(/courier,/bold, size=12)
KEYWORD PARAMETERS:
DEFAULT='save_file' to restore settings.
FONT = a font
FSIZE = font size (default=14)
WARNING - if=0, will not display intial warning of "RUN_INFO has not been run today"
INITAL_QUERY - the initial query of the database, e.g.
'rundate=20070523 and VOIDED IS NULL'
defaults to current user, last day with
entries, topic in ('PHYS OPS','SESSION LEADER')) and VOIDED IS NULL
LIMITATIONS
About
- ENTRY_DISPLAY is a widget based IDL procedure for
looking at entries in the LOGBOOK database. Its primary
purpose is to display an up-to-date set of logbook entries
during a run.
The user specified the record selection criteria
(Options->Display Options). Whenever a new logbook
entry is made, the display is automatically updated to
include the new record(s) if they meet the criteria
(unless one is in a blocking entry widget).
This tool allows the user to create new logbook entries.
Chose 'Make Final Entry' from the Entry menu.
In addition this tool can be used to void and edit
existing logbook entries. Select part of an entry in
main display, and then choose 'Edit Entry' or
'Void Entry' from the Entry menu.
NOTE: you may only void or edit entries which you have
entered into the database! Send email to dbadmin to have other
entries changed.
NOTES
To get a white background on text, you need certain commands in a .Xresources
file. You can have these loaded under the file menu in syb_entry.
use add_topic_logbook.pro to add topics.
to void a topic:
IDL> cmd = "DELETE FROM topics WHERE topic='BOLOMETERS'"
IDL> count = DSQL(cmd, stat=stat)
MODIFICATION HISTORY:
10-Oct-2013 fill in rundate automatically for entries when shot entered
02-Aug-2010 added timer to refresh every n seconds (DEFAULT=60)
04-Jun-2010 increased default max rows to 300
02-Apr-2010 added help on pattern matching syntax
12-Mar-2009 use common to pass display options, because structures
within structures have bugs, and are too convoluted. [BD]
02-Oct-2008 only do an mdsconnect if mds_event_server not defined.
20-May-2008 fixed Make Entry Options.
12-May-2008 calling mdssetevent breaks the connection needed for the widget to
recognize events, so now just spawn "setevent".
Requires that environmental variable mds_event_target be set.
(e.g. to birch.pppl.gov:8501) Tidied up several other issues
like consistancy of "Auto Updates" checkbox.
27-Jul-2007 Added WARNING and INITIAL_QUERY keywords.
Added UPDATE button to MAKE_ENTRY widget, so entries can be made
in steps. Help added to CUSTOM QUERY window to aid searches.
02-May-2007 changed default printing to your default printer. Added debug printing
30-Apr-2007 fixed auto updates on Linux
09-Apr-2007 Get Current shot from MDSplus, rather getting the largest
shot number from the database [BD]
05-Mar-2007 Allow text with special characters
('%', '^', '$', '*', '@', '#', '(', '!', ')', '?', ';') to go
into the logbook.
added some color buttons. [BD]
22-Jan-2007 Make sure connect to an event server (default to europa:8501).
18-Jul-2005 change !version.os to !version.os_family to pick up linux
05-Mar-2004 Upon startup update the screen with a query [BD]
02-Mar-2004 Font keyword added, and changed options to ascending order and
auto scroll = off (Bill Davis)
Josh Stillerman 9/20/96 initial version
Lew Randerson 1999-11-04 Convert from ENTRY_DISPLAY to SYB_ENTRY by
mimicking Stan Kaye's mods to create VMS SYB_ENTRY
... Convert entry_display to syb_entry (*** default file = $HOME/SybEntry.dat ***)
(*** strayed from sk default file handling ***)
... Add GetCurrentDate
Lew Randerson 1999-11-08 Change 'logbook' to 'nstxlogs'
Lew Randerson 1999-11-16 Check for os when handling print options
Lew Randerson 1999-11-17 Add event handling stuff
Lew Randerson 2000-01-11 Fix typo in get_entry_text parameters
Lew Randerson 2000-01-11 Put back 'RUN_INFO' check
Lew Randerson 2000-01-11 Handle unix printing
Check hand.key exists
Category: Dates
[List of Routines]
NAME:
addDate
PURPOSE:
Add days to a date. Tries to return string in same form as input
CATEGORY:
Dates
CALLING SEQUENCE:
newDate = addDate(date, ndays)
INPUTS:
date = date string, e.g., '6/17/1951', '1951/6/17', or 19510617
17 Jun, 1951 Jun 17 1951 1951 Jun 17
17/Jun/85 17-Jun-1951 85-Jun-17 17 June, 1951.
nDays - number of days to add (negative number OK)
KEYWORD PARAMETERS:
JULIAN - if set, return as Julian day
LONGYEAR - if set, return year as 4-digits
OUTPUTS:
newDate = Returned date string
EXAMPLES:
IDL> print, addDate('6/17/1951', 13)
06/30/1951
IDL> print, addDate('June 17, 1951', 13)
June 30, 1951
IDL> print, addDate('6/17/51', 365)
06/16/52
IDL> print, addDate('6-17-1951', -30)
05-18-1951
IDL> print, addDate('17-Jun-1951', -30)
18-May-1951
IDL> print, addDate('20110520', -30)
20110420
IDL> print, adddate(systime(),-2)
28 Jun 11
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
20-May-2011 fix for longdates
19-Feb-2010 add LONGYEAR keyword so 4-digit year returned
17-Aug-2009 Written by Bill Davis
NAME:
DATE2JD
PURPOSE:
Convert a date string to Julian Day number.
CATEGORY:
Dates
CALLING SEQUENCE:
jd = date2jd(date)
INPUTS:
date = date string, e.g., '6/17/1951', '1951/6/17', or 19510617
KEYWORD PARAMETERS:
OUTPUTS:
jd = Returned Julian Day number. out
COMMON BLOCKS:
NOTES:
Note: date must contain month as a name of 3 or more leeters.
MODIFICATION HISTORY:
18-Aug-2009 return 0 if date blank
12-Feb-2008 handle input date of form 19510617 (yyymmdd)
27-Nov-2006 Handle date of form 2006/4/28 [Bill Davis, PPPL]
R. Sterner, 1996 Sep 15
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
DATE2YMD
PURPOSE:
Date text string to the numbers year, month, day.
CATEGORY:
Dates
CALLING SEQUENCE:
date2ymd,date,y,m,d, dateString=dateString
INPUTS:
date = date string. in
KEYWORD PARAMETERS:
dateString - (OPTIONAL OUTPUT) of form yyyymmdd (e.g., 20030613)
OUTPUTS:
y = year number. out
m = month number. out
d = day number. out
COMMON BLOCKS:
NOTES:
Notes: The format of the date is flexible except that the
month must be month name.
Dashes, commas, periods, or slashes are allowed.
Some examples: 23 sep, 1985 sep 23 1985 1985 Sep 23
23/SEP/85 23-SEP-1985 85-SEP-23 23 September, 1985.
Doesn't check if month day is valid. Doesn't
change year number (like 86 does not change to 1986).
Dates may have only 2 numeric values, year and day. If
both year & day values are < 31 then day is assumed first.
systime() can be handled: date2ymd,systime(),y,m,d
For invalid dates y, m and d are all set to -1.
MODIFICATION HISTORY:
29-Jul-2011 handle strings like 7/25/2011-04:46:0-6.538
12-Feb-2008 handle input date of form 19510617 (yyymmdd)
17-Apr-2006 - added keyword longDate for return of 20051014.
14-Oct-2005 - fix to allow dates like 10/14/2005
13-Jun-2003 - added keyword output of composite string of form
yyyymmdd (e.g., 20030613)
R. Sterner, 1994 Mar 29 --- Modified to handle arrays.
RES 18 Sep, 1989 --- converted to SUN.
25-Nov-1986 --- changed to REPCHR.
Written by R. Sterner, 29 Oct, 1985.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
fileshotdate
PURPOSE:
Print time and date of an NSTX shot, but get data from a file
CATEGORY:
Dates, MDSplus, Tree Status
CALLING SEQUENCE:
IDL> date = fileshotdate( shot, time=time )
INPUTS:
shot = MDSplus shot number
KEYWORDS:
optional output:
time = time of shot, e.g., 12:25:02.00
OUTPUT:
date - e.g., '18-Mar-2010'
EXAMPLE:
IDL> date=fileshotdate(136942,time=time)
IDL> print, date, ' ', time
18-Mar-2010 13:51:00.00
COMMON BLOCKS:
fileshotdate_local
NOTES:
LIMITATIONS:
MODIFICATION HISTORY:
08-Jul-2013 converted from mdsshotdate by Bill Davis
NAME:
fileTime2dbTime
PURPOSE:
Return times in filetimes format in database format
CATEGORY:
Dates, times
CALLING SEQUENCE:
seconds = filetime2dbtime( time )
INPUTS:
time - string in military style '11:04' or '23:59' (no double quotes!)
KEYWORDS
addminutes - minutes to add (can be negative, but cannot cross midnight)
OUTPUT
time - string with AM or PM after it (no space between). This is the
format SQL queries want.
EXAMPLE:
IDL> print,filetime2dbtime( '6:08',addminutes=-10)
5:58AM
IDL> print,filetime2dbtime( '13:35')
1:35PM
MODIFICATION HISTORY:
WRITTEN by 27-Nov-2006 Bill Davis
NAME:
fromidlseconds
PURPOSE:
Convert from IDL-syle time (output from SYSTIME(1),
to form of '06/14/2004 11:04:52'
CATEGORY:
Dates
CALLING SEQUENCE:
date_time = fromIdlSeconds( secondsSince )
INPUTS:
secondsSince - seconds since 1/1/1970
KEYWORD PARAMETERS:
monthString - if set, return dateString as 1-Jan-1970
optional output:
datestr - just the date string
OUTPUTS:
date_time - string line '06/14/2004 11:04:52' (no double quotes!)
NOTES:
EXAMPLE:
IDL> print,fromIdlSeconds(1129295443)
10/14/2005 09:28:10
MODIFICATION HISTORY:
WRITTEN 27-Mar-2009 by Bill Davis
NAME:
fromidltime
PURPOSE:
Convert from IDL-syle time (output from SYSTIME(0),
to form of '06/14/2004 11:04:52'
CATEGORY:
Dates
CALLING SEQUENCE:
date_time = fromidlTIME( idldatetime )
INPUTS:
idldatetime - like Fri Oct 14 09:28:10 2005 (DEFAULTS to now)
KEYWORD PARAMETERS:
monthString - if set, return dateString as 1-Jan-1970
optional output:
secondsSince - seconds since 1/1/1970
datestr - just the date string
OUTPUTS:
date_time - string line '06/14/2004 11:04:52' (no double quotes!)
NOTES:
EXAMPLE:
IDL> print,fromidltime('Fri Oct 14 09:28:10 2005')
10/14/2005 09:28:10
MODIFICATION HISTORY:
12-Feb-2008 added secondsSince and monthString keywords
WRITTEN 14-Oct-2005 by Bill Davis
NAME:
getfiletime
PURPOSE:
return creation date and time of a file
(not sure atime and ctime are right, for files from a PC)
CATEGORY:
Dates, files
CALLING SEQUENCE:
IDL> times = getfiletime(files=files)
INPUT KEYWORDS:
files - string array of filenames, needed unless list used
list - alternate way: filename containing a list of files
dir - if present, is prepended to filenames before finding
KEYWORD PARAMETERS:
print - if present, will print results
atime - access time in seconds since 1 January 1970 UTC
ctime - creation time in seconds since 1 January 1970 UTC
mtime - modification time in seconds since 1 January 1970 UTC
OUTPUTS:
times - string array of creation date and times of files,
e.g.,
COMMON BLOCKS:
NONE
EXAMPLE:
% /bin/ls -1 * > list.txt
idl
IDL> times = getfiletime( list='list.txt',/print )
camerasbig Tue Oct 2 11:35:37 2007
cpp Fri Nov 9 16:28:02 2007
dothis.csh Tue Oct 2 11:33:37 2007
...
NOTES:
MODIFICATION HISTORY:
03-Mar-2009 added atime, ctime & mtime keywords
16-Apr-2008 Written by Bill Davis, PPPL
NAME:
hours2time
PURPOSE:
Return time string like 23:59:05 from floating point hour value
CATEGORY:
Dates, times
CALLING SEQUENCE:
timeStr = hours2time( hours )
INPUTS:
hours - floating pt., from 0-23.9999
KEYWORDS
optional outputs:
hours - integer hours
minutes - integer minutes
seconds - floating point seconds
OUTPUT
timeStr - string like 23:59:05.123, 03:01:59.777, etc.
EXAMPLE:
IDL> print,hours2time( 3.333333 )
03:19:59.999
NOTES:
use rgatime2hr() to go the other way
MODIFICATION HISTORY:
07-Jul-2011 WRITTEN by Bill Davis
NAME:
ISOtime
PURPOSE:
Return time in ISO 8601 standard, assuming US East Coast.
(handles Daylight Savings time)
CATEGORY:
Dates
CALLING SEQUENCE:
IDL> timeStr = ISOtime( DateTime )
INPUTS:
DateTime - like "06/14/2004 11:04:52"
KEYWORD PARAMETERS:
Keywords:
OUTPUTS:
timeStr - like 2004-06-14T11:04:52.0-4:00
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> print,isotime('06/14/2004 11:04:52')
2004-06-14T11:04:52.0-4:00
NOTES:
The ISO standard includes the adjustment to Grenwich Mean Time, so
you need to know whether Daylight Savings time is in affect.
This includes routines to find last and first Sunday of a month.
Assumes no fractions of seconds.
MODIFICATION HISTORY:
WRITTEN 19-Jan-2005 by Bill Davis, PPPL
NAME:
JD2DATE
PURPOSE:
Convert a Julian Day number to a date string.
CATEGORY:
dates
CALLING SEQUENCE:
date = jd2date(jd)
INPUTS:
jd = Julian Day number. in
KEYWORD PARAMETERS:
Keywords:
FORMAT = format string. Allows output date to be customized.
The following substitutions take place in the format string:
Y$ = 4 digit year.
y$ = 2 digit year.
N$ = full month name.
n$ = 3 letter month name.
m$ = 2 digit month number.
d$ = day of month number.
0d$ = day of month number as a 2 digit number.
W$ = full weekday name.
w$ = 3 letter week day name.
OUTPUTS:
date = returned date string. out
COMMON BLOCKS:
NOTES:
Notes:
The default format string is 'd$-n$-Y$' giving 24-Sep-1989
Example: FORMAT='w$ N$ d$, Y$' would give 'Mon
MODIFICATION HISTORY:
17-Aug-2009 added $m option so can get dates like 17-8-2009.
R. Sterner, 27 Feb, 1991
Copyright (C) 1991, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
JD2YMD
PURPOSE:
Find year, month, day from julian day number.
CATEGORY:
Dates
CALLING SEQUENCE:
jd2ymd, jd, y, m, d, dateString=dateString
INPUTS:
jd = Julian day number (like 2447000). in
KEYWORD PARAMETERS:
dateString - (OPTIONAL OUTPUT) of form yyyymmdd (e.g., 20030613)
OUTPUTS:
y = year (like 1987). out
m = month number (like 7). out
d = day of month (like 23). out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
12-Feb-2008 added dateString optional output keyword
Theo Brauers, 21 Sep, 1997 long loop index i
R. Sterner, 30 Apr, 1993 --- cleaned up and allowed arrays.
R. Sterner. 21 Aug, 1986.
Johns Hopkins Applied Physics Lab.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
long64date2str
PURPOSE:
Return date from a 64-bit longword, like 1112308040, as returned
from file_info, in a more conventional format.
CATEGORY:
Dates
CALLING SEQUENCE:
dateString = long64date2str( long64date )
INPUTS:
long64date returned from file_info, e.g., 1112308040
RETURNED:
dateString - conventional date string, e.g. 02/18/2006
KEYWORDS
delim - (string) delimeter used for output (Default is /)
twoDigitsForYear - if set, year will be last two digits of year
filetime - time of day of file, e.g. 14:32:59
year - year of file
month - numerical month of file
day - numerical day of file
EXAMPLES:
IDL> print,long64date2str( 1112308040 )
03/31/2005
IDL> print,long64date2str( 1112308040, /twoDigitsForYear )
03/31/05
MODIFICATION HISTORY:
WRITTEN 3-Jan-2007 by Bill Davis
NAME:
longdate2str
PURPOSE:
Return date from a longword, like 20060218, in a more conventional
format
CATEGORY:
Dates
CALLING SEQUENCE:
dateString = longdate2str( longDate )
INPUTS:
date in form yyyymmdd, e.g., 20060218
RETURNED:
dateString - conventional date string, e.g. 02/18/2006
KEYWORDS
delim - (string) delimeter used for output (Default is /)
twoDigitsForYear - if set, year will be last two digits of year
EXAMPLES:
IDL> print,longdate2str( 20060218 )
02/18/2006
IDL> print,longdate2str( 19951229, /twoDigitsForYear )
12/29/95
MODIFICATION HISTORY:
WRITTEN by 1-May-2006 Bill Davis
NAME:
MDSshotDate
PURPOSE:
Print time and date of an NSTX shot.
CATEGORY:
Dates, MDSplus, Tree Status
CALLING SEQUENCE:
IDL> date = MDSshotDate( shot, time=time )
INPUTS:
shot = MDSplus shot number
KEYWORDS:
optional output:
time = time of shot, e.g., 12:25:02
longDate - returned date in form of yyyymmdd, e.g., 20030613
optonally returned:
year
month
day
OUTPUT:
date - e.g., '11-FEB-2003 15:09:37.60'
EXAMPLE:
IDL> date=mdsshotdate(110109,time=time)
IDL> print, date, ' ', time
11-FEB-2003 15:09:37.60
COMMON BLOCKS:
none
NOTES:
This runs fairly quickly, but SQL access is quicker.
Also see SURVEYDB to quickly see first & last shot of day.
LIMITATIONS:
MODIFICATION HISTORY:
10-Oct-2013 fixed keyword longdate
22-Apr=2010 added noOpen keyword
06-Apr-2009 fixed bug with new date format coming from MDSplus & introduced
slash keyword, to get date in the form
03-Apr-2009 allow for missing value
14-Jan-2009 Changed node read to be \NSTX::TOP.ACQ_INFO.STATISTICS:STORE_START
04-Sep-2008 replace openMDSshot with mdsopen
09-Feb-2004 Added status (shots before around 104611 don't work)
03-Jun-02 use \WF::ACQ_START
03-Oct-00 Written by Bill Davis
NAME:
mdsTime2dbTime
PURPOSE:
Convert date & time from MDSplus to database format
CATEGORY:
Dates, times
CALLING SEQUENCE:
sqltime = mdsTime2dbTime( time )
INPUTS:
time - from MDSplus, e.g. '10-MAR-2008 09:50:46.36'
KEYWORDS
OUTPUT
sqltime - in SQL format, e.g., Mar 10 2008 09:50AM
EXAMPLE:
IDL> print,mdsTime2dbTime( '10-MAR-2008 09:50:46.36')
MAR 10 2008 09:50AM
MODIFICATION HISTORY:
WRITTEN by 10-Mar-2008 Bill Davis
NAME:
mdsTime2vsTime
PURPOSE:
Convert date & time from MDSplus to Visual Studio format
CATEGORY:
Dates, times
CALLING SEQUENCE:
vstime = mdsTime2vsTime( time )
INPUTS:
time - from MDSplus, e.g. '10-MAR-2008 09:50:46.36'
KEYWORDS
OUTPUT
vstime - in SQL format, e.g., Mar 10 2008 09:50AM
EXAMPLE:
IDL> print,mdsTime2vsTime( '10-MAR-2008 09:50:46.36')
MAR 10 2008 09:50AM
MODIFICATION HISTORY:
WRITTEN by G. Zimmer Feb '15
NAME:
MONTHNAMES
PURPOSE:
Returns a string array of month names.
CATEGORY:
Dates
CALLING SEQUENCE:
mnam = monthnames()
INPUTS:
monthNum - if present, just the name for this month returned
KEYWORD PARAMETERS:
nchars - max number of characters in month names
OUTPUTS:
mnam = string array of 13 items: out
['Error','January',...'December']
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
28-Jan-2009 Added nchars keyword
22-Feb-2006 Added monthNum optional input [BD]
R. Sterner, 18 Sep, 1989
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
monthnumber
PURPOSE:
Returns a month number given a month name.
CATEGORY:
Dates
CALLING SEQUENCE:
monthNum = monthnumber(monthStr)
INPUTS:
monthStr - e.g., 'Dec', or 'MAR'
KEYWORD PARAMETERS:
OUTPUTS:
monthNum = number of month, 1-12, or -1 if not found out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
09-Jul-2013 made to work with an array
29-Jan-00 Written by Bill Davis
NAME:
shotAtTime
PURPOSE:
find the NSTX shot number closest to a certain time
CATEGORY:
Dates, MDSplus
CALLING SEQUENCE:
IDL> shot = MDSshotDate( date, time )
INPUTS:
date - e.g. '2009/2/10' or '15-Oct-2010'
time - e.g., '12:13'
OUTPUT:
shot - NSTX shot number, probably 6 digits
NOTES:
Looks up shot range for the year and then does a binary search to find
the nearest shot number to the input time.
EXAMPLE:
IDL> date='2009/2/10' & time='12:13'
IDL> print, shotattime( date, time )
131441
31-May-2011 WRITTEN by Bill Davis, PPPL, for Doug Darrow
>> TIMES RETURNED FROM FILE_INFO AREN'T CORRECT!!!!!!!!
NAME:
shotsOfFiles
PURPOSE:
Return MDSplus shots (based on creation time) of files
CATEGORY:
dates, MDSplus
CALLING SEQUENCE:
IDL> shots = shotsOfFiles( rundate )
INPUTS:
files - array of files, or scalar string which may contain wild cards
KEYWORD PARAMETERS:
dates - dates (LONG) of files in YYYYMMDD (e.g., 20061231)
times - time of day of file, e.g., 23:59:59
seconds - seconds since midnight of time of file creation
delta_seconds - time of shot minus time of file creation
outfiles - files corresponding to shots out (useful when wild cards used)
beforeSeconds - seconds before shot to count as that shot (Default=60)
verbose - if set, will print informational output
OUTPUTS:
shots - array of shot numbers associated with files
EXAMPLE:
IDL> shots=shotsOfFiles( '*.dat',dates=dates,times=times,out=outfiles )
IDL> d=read_cih(filename, shot=120337, filedate=filedate2,filetime=filetime2)
IDL> print,shotsoffiles( filename)
NOTES:
On Windows, in IDL v. 6.2 and before, when running during Daylight Savings time,
for files created before DST, use keyword addSeconds=-3600
MODIFICATION HISTORY:
31-Mar-2006 Written by Bill Davis, PPPL
NAME:
time2Sec
PURPOSE:
Return seconds since midnight, if no date given. Otherwise,
since Jan. 1, 1970.
CATEGORY:
Dates, times
CALLING SEQUENCE:
seconds = time2Sec( time )
INPUTS:
time - string in military style '11:04' or '23:59' (no double quotes!)
or '6:08PM'
or IDL style, like 'Oct 16 2013 12:56:24'
KEYWORDS
none
OUTPUT
seconds - seconds (double precision) since midnight, if no date given.
Otherwise, since Jan. 1, 1970.
EXAMPLE:
IDL> print,time2Sec( '6:08')
22080.000
IDL> print,time2Sec( '6:08PM')
65280.000
IDL> print,time2Sec( 'Oct 16 2013 12:56:24')
1.3819282e+09
MODIFICATION HISTORY:
28-Oct-2013 handle array input, and do since 1970, if date specified
WRITTEN by 03-Mar-2009 Bill Davis
NAME:
timesofshots
PURPOSE:
return dates and times, like 12:26PM, of NSTX shot
CATEGORY:
dates, MDSplus
CALLING SEQUENCE:
IDL> times = timesofshots( shot1, shot2, dates=dates )
IDL> times = timesofshots( year=2010, dates=dates )
INPUTS:
shot1 - starting shot
shot2 - ending shot
KEYWORD PARAMETERS:
year - if set, will find the shots for that year
dates - dates of files in dd-mon-yyyy (e.g., 07-Jul-2007)
longDates - dates (LONG) of files in YYYYMMDD (e.g., 20061231)
times - time of day of file, e.g., 23:59:59
verbose - if set, will print informational output
OUTPUTS:
times - time of day of file, e.g., '12:05PM'
EXAMPLE:
IDL> times = timesofshots( year=2010, dates=dates, shots=shots, longd=longd )
IDL> for i=0,4 do print, shots[i], ' ', dates[i], ' ', times[i]
136730 23-Feb-2010 12:05PM
136731 23-Feb-2010 12:17PM
136732 23-Feb-2010 12:23PM
136733 23-Feb-2010 12:30PM
136734 23-Feb-2010 12:40PM
NOTES:
you will need database setup done, as for the NSTX logbook. E.g.,
source /p/nstxusr/util/setup/mkmdsplusdbfile.csh
MODIFICATION HISTORY:
08-Jul-2013 added year keyword
WRITTEN by Bill Davis, 27-Feb-2009
NAME:
toIdlTime
PURPOSE:
Convert a date string to IDL time (output from SYSTIME(1),
i.e., seconds since 1/1/1970
CATEGORY:
Dates
CALLING SEQUENCE:
seconds = TOIDLTIME( date_time )
INPUTS:
date_time - string line '06/14/2004 11:04:52' (no double quotes!)
KEYWORD PARAMETERS:
OUTPUTS:
seconds since 1/1/1970 (type long64)
NOTES:
EXAMPLE:
IDL> print, systime(0), long64(systime(1))
Fri Oct 14 09:10:43 2005 1129295443
IDL> print, toIdlTime('10/14/2005 09:10:43')
1129295443
IDL> print, fromIdlSeconds(1129295443)
10/14/2005 09:10:43
IDL> print, toIdlTime('20 Jun 11')
MODIFICATION HISTORY:
17-Mar-2010 Handle dates like 'Fri Feb 5 17:04:55 2010', and inputs
of Julian dates and Long dates (like 20091231)
WRITTEN 14-Oct-2005 by Bill Davis
NAME:
WEEKDAY
PURPOSE:
Compute weekday given year, month, day.
CATEGORY:
Dates
CALLING SEQUENCE:
wd = weekday(y,m,d,[nwd])
INPUTS:
y, m, d = Year, month, day (Like 1988, 10, 31). in
KEYWORD PARAMETERS:
OUTPUTS:
wd = Returned name of weekday. out
nwd = optional Weekday number. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 31 Oct, 1988.
Johns Hopkins University Applied Physics Laboratory.
RES 18 Sep, 1989 --- converted to SUN
Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
YMD2DATE
PURPOSE:
Convert from year, month, day numbers to date string.
CATEGORY:
Dates
CALLING SEQUENCE:
date = ymd2date(Y,M,D)
INPUTS:
y = year number (like 1986). in
m = month number (1 - 12). in
d = day of month number (1 - 31). in
KEYWORD PARAMETERS:
Keywords:
FORMAT = format string. Allows output date to be customized.
The following substitutions take place in the format string:
Y$ = 4 digit year.
y$ = 2 digit year.
N$ = full month name.
n$ = 3 letter month name.
m$ = 2 digit month number.
d$ = day of month number.
0d$ = day of month number with leading 0 if < 10.
W$ = full weekday name.
w$ = 3 letter week day name.
dateStr - alternate input, like '20070931'
OUTPUTS:
date = returned date string (like 24-May-1986). out
COMMON BLOCKS:
NOTES:
Notes:
The default format string is 'd$-n$-Y$' giving 24-Sep-1989
Example: FORMAT='w$ N$ d$, Y$' would give 'Mon
MODIFICATION HISTORY:
19-Mar-2010 fixed bug for $m meaning minutes in called routines
17-Aug-2009 added $m option so can get dates like 17-8-2009.
28-NOV-2007 Added DateStr keyword [ Bill Davis, PPPL ]
...
RES 18 Sep, 1989 --- converted to SUN
R. Sterner. 16 Jul, 1986.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
YMD2JD
PURPOSE:
From Year, Month, and Day compute Julian Day number.
CATEGORY:
Dates
CALLING SEQUENCE:
jd = ymd2jd(y,m,d)
INPUTS:
y = Year (like 1987). in
m = month (like 7 for July). in
d = month day (like 23). in
KEYWORD PARAMETERS:
OUTPUTS:
jd = Julian Day number (like 2447000). out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 23 June, 1985 --- converted from FORTRAN.
Johns Hopkins University Applied Physics Laboratory.
RES 18 Sep, 1989 --- converted to SUN
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
yrmonthday
PURPOSE:
Return a string of YYYYMMDD from a date string.
CATEGORY:
Dates
CALLING SEQUENCE:
IDL> dateNumberString = yrmonthday(dateString)
INPUTS:
dateString = date in one of these formats:
'7-jun-2001'
'Mon Jan 14 15:22:05 2002'
'08Aug2002'
'Jun 30 2005'
(defaults to today)
OUTPUTS:
dateNumberString = 8-character string of numbers:
YYYYMMDD
KEYWORDS
time - returns time like 08:41:55
year - year number as string
month - month number as string
day - day number as string
EXAMPLE:
IDL> print,yrmonthday()
20020114
IDL> print,yrmonthday('5-jun-2001')
20010605
NOTES:
MODIFICATION HISTORY:
19-Nov-2009 fixed bug returning month number
31-Mar-06 allow form of 'Jun 30 2005' or 'June 30, 2005'
16-Nov-04 added time keyword
15-Aug-02 Modified for UNIX date format by Stan Kaye
15-Jan-02 Allow for 2-digit years
14-Jan-02 Written by Bill Davis, PPPL
Category: EFIT
[List of Routines]
NAME:
calcbtbp
PURPOSE:
Calculates toroidal and poloidal magnetic field values (Bt & Bp)
at desired R & Z and desired time by reading data from the EFIT
(or similar) MDS+ tree. (Bt is also refered to as B-phi.)
CATEGORY:
EFIT, LRDFIT
CALLING SEQUENCE:
calcbtbp, shot, index, time, Rwant, Zwant, tree=tree, $
BpWant=Bp, BtWant=Bt ; returned
INPUTS:
shot - NSTX shot number
index - number of the run, 1,2,... etc.
time - time wanted in seconds
Rwant - Major radius in meters at which Bt & Bp wanted
Zwant - Height in meters at which Bt & Bp wanted
RETURNED:
keywords:
BpWant - Poloidal magnetic field at desired R & Z at desired time
BtWant - Toroidal magnetic field at desired R & Z at desired time
EXAMPLE:
IDL> .r /u/jmenard/idl/efit/math_routines_jem.pro
IDL> .r efit_routines_jem.pro
IDL> calcbtbp, 139444, 4, .27, 1.44, 0., BP=Bp, Bt=Bt
(will see lots of errors for LRDfits)
IDL> mdsopen,'LRDFIT04', 139444
IDL> BTAXP = mdsgetsig( '\BTAXP', xaxis=fittime )
IDL> print, BTAXP( nearesti( fitTime, 0.27 ) )
NOTES:
To see what fits are available, you could:
IDL> print, fitsrun(shot)
or
IDL> print, bestFitAvail(shot)
MODIFICATION HISTORY:
WRITTEN 19-Jan-2012 by Bill Davis with Stefan Gerhardt's help
see /u/sgerhard/NSTX/idl/lib/MSERoutines.pro
Uses many routines from Jon Menard.
NAME:
efitmovies
PURPOSE:
Plot EFIT field lines, Thomson Scattering Density and Temperature
and, optionally, Fast Camera images. Instead of Fast Camera, can
plot H-alpha (or another) signal vs. time.
CATEGORY:
EFIT, Animation, 2-D Plotting, NSTX, Thomson Scattering
CALLING SEQUENCE:
for a nice animated display of the latest shot, with a pick-list displayed for movies:
IDL> efitmovies, /thom, /summary
for a movie with a camera looking at the RF limiter and the RF power plotted:
IDL> efitmovies, 'nstx_1_134625.cin', signame='\wf::prf', time=[.05,.45], $
sigt1=0.1, sigt2=.3, maxframes=1000, $
/framesOut, QTmovie='NSTX_134625.mov', /verbose
to see the strike point plot with EFIT:
IDL> efitmovies,138000,signame='\EFIT02::RVSOUT',/nofc, sigTitle='Strike Point'
to get a single frame (with camera image):
IDL> shot=138000
IDL> efitmovies, shot, time=0.2, /thom, signame='\wf::ip', $
sigt1=0, sigt2=.4
to get a single frame with just EFIT
IDL> efitmovies, 136159,time=.2, /noFC
to get a single frame with flux surfaces on both sides:
IDL> efitmovies, 121048, time=.2, /double
to get a single frame with fast camera (determined from dialog box) image on the left:
IDL> efitmovies, 138000, time=.2, /pick
to get an IDL Animation Widget, from which you can write an MPEG:
IDL> efitmovies, 138000, time=[0.05,0.317], /thom, max=40
to get an animation with H-alpha time trace instead of Fast Camera images:
IDL> efitmovies,107314, /thom, time=[.05,.5], /noFC, $
/signame, sigtitle='H-alpha',max=40
to see limiter camera (with Lithium dropping):
IDL> efitmovies, '/p/nstxcam/phantom4/NSTX_135060.cin', /thom, time=[.1,.2]
to see miro camera (would use nstx_2*138000 in 2010):
IDL> efitmovies, 'miro*135060', /thom, time=[.1,.12], /summary
for the Open House:
IDL> efitmovies, 'miro*135260', /thom,/summ, /noEfit, time=[.18, .55], $
maxFrames=400, /press, /fahren, /HMODE
for full rotation, with just 3 contours outside of plasma:
IDL> efitmovies, 136159,time=.2, /noFC, outlevels=3, /double, /pdf, /emailPsFile
for zooming into plot for a single frame:
IDL> efitmovies, 136159,time=.2, /noFC,xmin=.25,xmax=1.25,ymin=-2,ymax=-1
to make a movie using jmovie:
IDL> efitmovies, 138497, time=[.1,.5], /thom, /framesOut, /nofc, anim=0, $
QTmovie='NSTX_138000.mov'
to see what shots have fast camera data in the tree:
IDL> MDSnodeChanges,'\fc3d',shot1=119120,shot2=119230,tree='cameras',/after
INPUTS:
shot = nstx shot number
KEYWORD PARAMETERS:
Keywords:
noEfit - if set, do not display EFIT contours
ndups - number of times each frame of movie is duplicated (default=0)
time - 2-element array for animation; single value for one frame
thomson - if set, will plot Thomson Te and Ne below EFIT contours
animate - if set to 0, will plot individual frames instead of movie.
maxFrames - max # of frames over time range -- necessary if X-memory
is limited (default is 200).
nDecimalTime - # of decimals to display for time (if in seconds)
pixMap - if set, will not send each frame to the screen (faster)
double - plot efit color contours on both sides of center stack
sigName - if set, will not show Fast Camera images, but this
signal vs. time (defaults to \passivespec::BAYC_DALF_HAIFA)
sigT1 - starting time of signal vs. time plot
sigT2 - ending time of signal vs. time plot
sigTitle - if set, will be displayed above sigName plot,
else tries to get label from MDSplus
overlayTe - overlay Thomson Te and Ne, instead of on left and right
window - starting window number (default=0)
efitVersion - the efit version to display. Defaults to the highest
available less than 5.
LRDfitVersion - the LRDfit version to display. If non-blank, will override
efitVersion keyword used.
Summary - if set will include a plot summary (Ip, Pinj, D-alpha, Wmhd)
save - if set, create the MPEG file, but don't bring up the widget
pick - if set, will let you pick from a menu when more than one Fast Camera
file matches the specification of the first argument
warning - if set to 0, will not pop dialog up for messages
OUTPUTS:
none
LIMITATIONS:
Some reds are green on printer.
NOTES:
MODIFICATION HISTORY:
17-Aug-2010 added WARNING keyword so popping dialog windows can be surpressed
10-Aug-2010 added option to make MPEGs from Eliots Java code that uses jpegs
13-Jul-2010 fixed auto-save of mpeg files. Default name has whole time range.
Improved finding of camera files. Default to showing Fast Camera
when SIGNAMES set.
01-Jul-2010 added group keyword, and pass to XIA so can be destroyed
by a calling program, like efitmovieloop.pro
04-Jun-2010 many improvements when using frames from MDSplus; have interpolated
Thomson profiles extend to adjacent EFIT times before and after
12-May-2010 added nLevels keyword for # of flux contours
07-Apr-2010 added noEfit option for Masa
02-Apr-2010 provided for color movies
16-Mar-2010 fix for selecting file after no data found for input shot
17-Dec-2009 made to work with Cine files. Include plot summaries.
02-May-06 added ndups keyword
26-Jan-06 No longer e-mail to 'USER' if username not specified.
Tidy up screen message for postscript output
27-Sep-2005 fix bug for sub-msec timing for single plots
19-Aug-2005 improve selection of efit version
17-Jul-2005 Assure black lines on plots
03-Sep-04 Better logic for missing Thomson data.
15-Apr-04 Fixed bug for full time with lots of frames
made default max frames 200.
23-Oct-03 Use spline Te and Ne from Thomson
23-Aug-03 Adds for efitflux.html
23-May-03 Added keywords for Web Plotting
01-May-03 Added /double keyword
28-May-02 Added /signame keyword and overlayTe
Original written by Dave Gates
NAME:
efit_times
PURPOSE:
Return EFIT times in MDSplus for a shot
CATEGORY:
EFIT
CALLING SEQUENCE:
IDL> etimes = efit_times(shot, tree=tree)
INPUTS:
shot = nstx shot number
KEYWORD PARAMETERS:
Keywords:
tree - defaults to EFIT02, then tries EFIT01.
RETURNED:
returns EFIT times in seconds for this shot for particular tree
LIMITATIONS:
NOTES:
MODIFICATION HISTORY:
06-Jul-2015 written by Bill Davis
NAME:
GETEFIT
PURPOSE:
Procedure to get efit data from A0 and G0 file or from MDSPLUS. This
can be used as a front end to the usual reada and readg. It prints
out a message if the efit data does not occur for the desired value
of DELTIME. It does not return any data unless time window
requirements are met.
CATEGORY:
EFIT
CALLING SEQUENCE:
getefit, shot, time, aaa, ggg [,DELTIME=DELTIME] $
[,ERR=ERR] [,MODE=MODE] [,runID=runID]
INPUTS:
shot shot number
time shot time (sec)
KEYWORDS:
DELTIME - maximum allowable time (sec) for the data to deviate from
time. If two values [t0,t1] are input, the time window is from
(time - t0) to (time + t1), otherwise, the time window is from
(time - t0) to (time + t0).
ERR - set to 0 for successful return of efit data; a non-zero
value means there was a problem getting the efit data
MODE - read a mode parameter, file or mdsplus
runID - choose EFIT01 (JT snap file) or EFIT02 (MSE snap file) from
MDSPlus efit data. Default is EFIT01, the non-MSE automatic
control room EFIT
OUTPUTS:
aaa structure from reada routine holds data from A0 file
ggg structure from readg routine holds data from G0 file
err error code returned from reada ok if err=0
RESTRICTIONS:
User can specify source of data as MDSPLUS or a file in the current
directory, or in a directory given by the environment variable
MY_EFIT_DIR.
PROCEDURE:
CODE TYPE: modeling, analysis, control
CODE SUBJECT: operation, edge, rf, transport, equilibrium, other
EASE OF USE: can be used with existing documentation
OPERATING SYSTEMS: UNIX of all flavors
EXTERNAL CALLS: READA, READG
TO TEST: IDL> getefit, 138000, 0.2, aaa, ggg
IDL> getefit, 141010, runID='LRDFIT06', 0.2, aaa, ggg
MODIFICATION HISTORY:
Created by Gary D. Porter
1998.10.20: Allow for data from a file or MDSPLus by G.D. Porter
1998.11.03: Change DELTIME check to allow for 2 values by R.A. Jong
1999.04.01: Added runID and removed BLESSED optional keywords
1999.05.06; Reset aaa.error=1 when our err parameter=1
2000.01.03; Change check on aaa.time and ggg.time to accept data if
both are in the acceptable time range, when not equal
2000.10.19; Do not cd to MY_EFIT_DIR and send message if mode=MDSPLUS
2001.10.16; Fix missing time_range flag in readg call (RAJ)
06-Aug-2010 [BD] adapted for NSTX for Jose Boedo (note EFIT times on NSTX are
in seconds, rather than milliseconds)
27-nov-2012 [BD] added aaa.shot and ggg.shot tags when getting LRDfit trees.
NAME:
getsep
PURPOSE:
Get the separatrix (last closed flux surface) R & Z values
from EFIT or LRDfit for a particular NSTX or CMOD shot.
Interpolate surfaces in time. Can also return R & Z
of limiter interior. Also works for CMOD shots (tree
opened elsewhere).
CATEGORY:
EFIT, 2-D Plotting, NSTX, CMOD
CALLING SEQUENCE:
IDL> getsep, shot, outTime, r_edge=r_edge, z_edge=z_edge, $
xLim=xLim, zLim=zLim
INPUTS:
shot - shot number for MDSplus call
outTimes - times desired in seconds
KEYWORD PARAMETERS:
Optional Inputs:
efitVersion - 1-6. Defaults to "Best Fit"
LRDfitVersion - alternate to above
BestFit - (DEFAULT) if set, will call bestFitAvail, which has preference
of LRDFIT04, any other LRDFIT, EFIT02, then highest EFIT.
outer - if set will just return edge values > median value (default)
inner - if set will just return edge values <= median value
interp - if=0, will not interpolate in time (just take nearest time)
noOpen - if set will not try to open a tree (assumes already open)
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Returned:
r_edge - r values of separatrix (edge) points
z_edge - z values of separatrix points
rLim - r values of limiter points
zLim - z values of limiter points
EXAMPLE:
; get R & Z of separatrix for CMOD shot
IDL> getsep, 1120224029, 1.08800, $
r_edge=r_edge, z_edge=z_edge, $
/debug
to get get R & Z data and limiter location:
IDL> getsep, 135036, .589, R_edge=R, Z_edge=Z, $
rLim=rLim, zLim=zLim
MODIFICATION HISTORY:
05-Mar-2014 added interp keyword, so could get specific points
WRITTEN Aug-2012 by Bill Davis for Stewart Zweben
NAME:
highestEfitRun
PURPOSE:
find highest efit version run (in the MDSplus tree)
Checks up to 5, and contigously after that
CATEGORY:
EFIT, MDSplus
CALLING SEQUENCE:
IDL> run = highestEfitRun(shot)
INPUTS:
shot = shot #
KEYWORD PARAMETERS:
FITTYPE= fit type. Defaults to 'EFIT'. Works for 'LRDFIT', too.
min2Check - will always check up to this number, and contigously
after that. E.g. if there is a EFIT05 and EFIT07,
5 will be declared the highest unless this keyword
is 6 or higher.
max2Check - will stop checking at this fit number
OUTPUTS:
integer # representing highest EFIT run in tree
EXAMPLES:
IDL> print,fitsrun(123001)
EFIT01 EFIT02 EFITRT
IDL> print,highestefitrun(123001)
2
IDL> print,fitsrun(117707)
EFIT01 EFIT02 EFIT03 EFIT06 EFITRT LRDFIT04 LRDFIT06
IDL> print,highestefitrun(117707)
6
IDL> print,highestefitrun(117707,FIT='LRDFIT')
6
NOTES:
When the routine is called with no parameters, or with the
keyword hlp set, help information is printed.
MODIFICATIONS:
13-Apr-2010 added max2Check keyword
29-Aug-2008 make min2check=20 for LRDfit
27-Aug-2007 check at least 5 runs. Add keyword for fit type and
min2Check.
Aug-2005 Written by Bill Davis
NAME:
interpEdge
PURPOSE:
Interpolate separatrix in time. From EFIT or LRDfit, find R
and Z values of last closed flux surface (separatrix) for a
particular NSTX or CMOD shot. Can also return R & Z of limiter
interior. Also works for CMOD shots (tree opened elsewhere).
CATEGORY:
EFIT, 2-D Plotting, NSTX, CMOD
CALLING SEQUENCE:
IDL> interpEdge, shot, outTime, r_edge=r_edge, z_edge=z_edge, $
xLim=xLim, zLim=zLim, $
/plot, /debug
INPUTS:
shot - shot number for MDSplus call
outTimes - times desired in seconds
KEYWORD PARAMETERS:
Optional Inputs:
efitVersion - 1-6. Defaults to 2
LRDfitVersion - alternate to above
BestFit - (DEFAULT) if set, will call bestFitAvail, which has preference
of LRDFIT04, any other LRDFIT, EFIT02, then highest EFIT.
outer - if set will just return edge values > median value
inner - if set will just return edge values <= median value
interp - if=0, will not interpolate in time (just take nearest time)
noOpen - if set will not try to open a tree (assumes already open)
plot - if set will plot data
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Returned:
r_edge - r values of edge points (in meters)
z_edge - z values of edge points
xLim - r values of limiter points
zLim - z values of limiter points
EXAMPLE:
IDL> interpEdge, 130376, .2, $
r_edge=r_edge, z_edge=z_edge, $
/plot, /debug
to get get R & Z data and limiter location:
IDL> interpEdge, 135036, .589, R_edge=R, Z_edge=Z, $
xLim=xLim, zLim=zLim
IDL> interpEdge, 1120815021, 1.15, r_edge=Rsep, z_edge=Zsep, /outer, /plot
IDL> interpEdge, 138846, .615,r_edge=Rsep,z_edge=Zsep,/outer,/plot, /deb
MODIFICATION HISTORY:
--------------------
12-Mar-2014 added fit keyword
05-Mar-2014 added interp keyword, so could get specific points
16-Sep-2013 always have noOpen=0 (bug somewhere)
04-Mar-2013 don't stop if no radii found greater than average
30-Aug-2012 add MDSconnect for CMOD; do not assume shot is open
21-Aug-2012 fixed bug for CMOD
05-Jan-2012 account for time being first dimension in r & z from CMOD EFITs
21-Dec-2011 added CMOD support
15-Dec-2011 added outer and inner keywords
WRITTEN 12-Dec-2011 by Bill Davis
NAME:
PECOMP
PURPOSE:
Interactively compare PCS and EFIT signals for a shot
CATEGORY:
EFIT, PCS
CALLING SEQUENCE:
IDL> pecomp, shot=shot
INPUTS:
shot = shot number
KEYWORD PARAMETERS:
Keywords:
print - print rather than display on screen
data - can pass in data
xsize
ysize
xrange - of plots
debug
bigCharSize
OUTPUTS:
COMMON BLOCKS:
NONE
EXAMPLE:
; for NSTX:
IDL> pecomp2010, shot=130000, bigCharSize=3
; for NSTX-U:
IDL> pecomp, shot=200005, bigCharSize=2, frac=0.6, /debug
NOTES:
Use middle mouse button to select zoom region
MODIFICATION HISTORY:
30-Apr-2015 more NSTX-U changes for Dan Boyer
24-Mar-2015 updating for NSTX-U per Stefan Gerhardt.
18-Jul-2011 fixed bug in SPA plotted times
14-Jul-2011 added "SPA Current" and "Loop Voltage Diff" buttons
14-Jul-2011 removed ["RAI_PF4", "\IPF4"] coils plotting, since bombs
10-Nov-2008 made to work with skylark defs.
don't keep reading data when not there. [BD]
21-Feb-2008 Added "RAF_FLPPPU4" & "\F_FLPPPU4" per Dennis & Dave
14-Feb-2008 Add upper-lower loop voltage difference signals per
Dennis Mueller [BD]
04-Feb-2008 add switch to allow using eng_dev tree [Dana Mastrovito]
21-Jan-2008 Don't do an MDSconnect (use mdsopen instead of
openMDSshot()) [BD]sigs like \pcs.ra:RAB_LSPPGU1
12-Feb-2007 Always read shot number field before plotting, so
not necessary. Fix recently introduced errors.
Written by Bill Davis, PPPL, for Dave Gates
NAME:
plasmaedge
PURPOSE:
From EFIT or LRDfit, find R and Z values of last closed flux surface
(separatrix) for a particular NSTX shot and time. Optionally save to a
file.Also will plot limiters and last closed flux surface with axes.
Can also return R & Z of limiter interior.
CATEGORY:
EFIT, 2-D Plotting, NSTX
CALLING SEQUENCE:
IDL> plasmaEdge, shot, time, /plot, /debug
INPUTS:
shot = nstx shot number
time - time desired in seconds (will pick closest in tree)
KEYWORD PARAMETERS:
Optional Inputs:
efitVersion - 1-6. Defaults to 2
LRDfitVersion - alternate to above
BestFit - (DEFAULT) if set, will call bestFitAvail, which has preference
of LRDFIT04, any other LRDFIT, EFIT02, then highest EFIT.
noOpen - if set will not try to open a tree (assumes already open)
outfile - Defaults to 'PlasmaEdge___ms.txt', unless='NONE'
limiter - if set, will print R & Z values for limter shell
plot - if set will plot data
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Returned:
r_edge - r values of edge points
z_edge - z values of edge points
xLim - r values of limiter points
zLim - z values of limiter points
actualTime - actual time used, i.e., nearest EFIT or LRDfit time to
that requested
EXAMPLE:
IDL> plasmaEdge, 130376, .589, /plot, /debug
to get get R & Z data and limiter location:
IDL> plasmaEdge, 135036, .589, outfile='NONE', R_edge=R, Z_edge=Z, $
xLim=xLim, zLim=zLim
08-Dec-2011 BD added keyword BestFit, and made that the default!
default output file to 'NONE'
WRITTEN 03-Feb-2010 by Bill Davis
NAME:
psiinterp
PURPOSE:
From EFIT or LRDfit, get psi of a flux surface contour at a
particular shot and time and R & Z. Then, find the R position of
that same psi value at Z=0.
CATEGORY:
EFIT, 2-D Plotting, NSTX
CALLING SEQUENCE:
IDL> PsiWant = psiinterp( shot, time, Rwant=Rwant, Zwant=Zwant )
INPUTS:
shot = nstx shot number
time - time desired in seconds (will pick closest in tree)
OUTPUTS:
PsiWant - psi at Rwant & Zwant
KEYWORD PARAMETERS:
Inputs:
Rwant & Zwant - arrays of R & Z at which Psi is wanted
efitVersion - 1-6. Defaults to 2 (if not available, the highest of
contiguous versions will be used. E.g., if 1,2,5 are
available and 3 is requested, 2 will be used).
LRDfitVersion - alternate to above
noOpen - if set will not try to open a tree (assumes already open)
plot - if set will plot data
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Output:
RatZ0 - R value at Z=0 of Psis at input R & Z
EXAMPLE:
IDL> Rwant = findgen(5)/4*0.5 + 1.1
IDL> Zwant = findgen(5)/4*0.5 + 0.3
IDL> PsiWant = psiinterp( 135036, .589, Rwant=Rwant, Zwant=Zwant, $
RatZ0=RatZ0, /plot, /debug )
IDL> XYOUTS, RatZ0, 0, 'X', align=center
to get get R & Z data:
IDL> PsiWant = psiinterp( 135036, .589, Rwant=1.4, Zwant=0.4 )
LIMITATIONS:
Takes the EFIT/LRDfit at the nearest time. Perhaps an interpolation
should be done when the desired time is between computed times.
06-Sep-2013 set /exact in call to followContour (was getting choppy results)
WRITTEN 12-Feb-2010 by Bill Davis
NAME:
sepvstime
PURPOSE:
Get the separtrix (last closed flux surface) R & Z values
vs. time.
from EFIT or LRDfit for a particular NSTX or CMOD shot.
Can also return R & Z of limiter interior.
CATEGORY:
EFIT, NSTX
CALLING SEQUENCE:
IDL> sepvstime, shot, trange=trange, Redge=Redge, Zedge=Zedge
INPUTS:
shot - shot number for MDSplus call
KEYWORD PARAMETERS:
Optional Inputs:
tRange - range of times desired (defaults to all available)
fit - fit desired. Default is "best fit"
outer - if set will just return edge values > median value (default)
inner - if set will just return edge values <= median value
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Returned:
RedgeVsTime - r values of separatrix (edge) points
ZedgeVsTime - z values of separatrix points
used_fit - the fit used
tFit - times of the fit
nPerTime - # of good values in corresponding time element of arrays
EXAMPLE:
to get get R & Z data:
IDL> sepvstime, 138847, RedgeVsTime=R, ZedgeVsTime=Z
MODIFICATION HISTORY:
14-Oct-2013 allow fit_desired to be 'BEST'
WRITTEN 05-Jun-2013 by Bill Davis for Stewart Zweben
Category: EPICS Channel Access Interface
[List of Routines]
NAME:
caGetCountAndType
PURPOSE:
This function returns the number of elements and data type of a
Channel Access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGetCountAndType(pvname, count, type)
INPUTS:
pvname: The name of the process variable for which information is to
be returned.
OUTPUTS:
count: The number of elements in the process variable. This is 1 for
scalar process variables and more than 1 for arrays.
type: This is a 3 element array containing information about the data
type of the process variable.
type(0) = Channel access data type as defined in "cadef.h"
type(1) = EZCA data type as defined in "ezca.h"
type(2) = IDL/PV-WAVE data type as defined in size()
These data types are as follows:
Name Channel Access EZCA IDL/PVWAVE
String 0 1 7
Short 1 2 2
Float 2 4 4
Enum 3 2 (short) 2 (short)
Byte 4 0 1
Long 5 3 3
Double 6 5 5
The function return value of caGetCountAndType is a status value. The
status is 0 if the routine was successful (i.e. the process variable exists)
and non-zero if the routine failed.
SIDE EFFECTS:
This routine will cause a Channel Access search to take place if this is
the first time this process variable has been referenced.
RESTRICTIONS:
The channel access data type enum is mapped to EZCA and IDL short
data types. However, application programs can use this routine to
determine if the native channel access data type is enum, and then
use caGet(pvname, value, /string) to read the string equivalent of the
process variable. Programs can also use
caGetEnumStrings(pvname, strings) to read the strings for the all of
the possible values of an enum process variable.
PROCEDURE:
This routine uses ezcaPvToChid() and then ca_element_count() and
ca_field_type().
Note that this routine always returns its values "immediately", even
if it is called between a caStartGroup and caEndGroup.
EXAMPLE:
IDL> status = caGetCountAndType('test_mca1.VAL', count, type)
IDL> print, status
0 ; Status = success
IDL> print, count
2048 ; Array with 2048 elements
IDL> print, type
5 3 3 ; Long data type
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caGet
PURPOSE:
This function reads the value of a Channel Access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGet(pvname, value, /string, max=n)
INPUTS:
pvname: The name of the process variable for which the value is to
be returned.
KEYWORD PARAMETERS:
STRING: Set this flag to force caGet to return a string, rather than
a number. This flag is particularly useful when the native
channel access data type is ENUM (3), since the string is
more descriptive than the number.
MAX: This keyword parameter is used to limit the number of
values returned by caGet. caGet normally returns the native
element count for a process variable. Setting MAX to a
number less than this will cause caGet to return only the
first MAX values in the array.
OUTPUTS:
value: The value of the process variable. By default, caGet returns
"value" with the native data type and number of elements
of the process variable. It determines this information by
calling caGetCountAndType(). Note that if caGet is called
after calling caStartGroup but before calling caEndGroup then
the IDL variable "value" is created, but will not actually
contain the data until caEndGroup is called.
The function return value of caGet is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed. If caGet is called from
within an asynchronous group then the status return only indicates
whether the operation was successfully queued.
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine tests that flag.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced. It
performs a ca_get, unless called as part of an asynchronous group.
RESTRICTIONS:
There are two important restrictions which must be kept in mind when
calling caGet from inside a "group", i.e. after calling caStartGroup
and before calling caEndGroup.
1) The IDL "value" variable (i.e. the second parameter
passed to caGet) must not be "re-used" or deleted before the call to
caEndGroup. The reason for this is that EZCA has been passed the
address of this variable as the location in which the data is to be
copied when caEndGroup is called. Thus, this location must still
point to a valid memory location when caEndGroup is called.
If the "value" variable is re-used then IDL's behavior is
unpredictable, and bus errors/access violations could occur.
2) When using caGet to read strings, the data type returned will be
a byte array, rather than a string. The reason has to do with the
manner in which IDL passes strings, which requires that EZCA actually
be passed pointers to byte arrays. When caGet is called outside of a
group it automatically converts the byte array to a string before
returning the value. However when caGet is called inside of a group
it cannot perform this conversion, since it cannot be done until after
the data is read, which does not occur until caEndGroup is called.
Thus, it is the user's responsibility to convert the data from a byte
array to a string after calling caEndGroup. This is done very simply
with the string() function. For more information see the example below.
PROCEDURE:
This routine uses ezcaGet().
EXAMPLES:
IDL> ; The following is an example of a single caGet
IDL> status = caGet('test_mca1.VAL', value)
IDL> ; The following is an example of a valid grouped operation
IDL> ; It also shows how to handle strings.
IDL> caStartGroup
IDL> status = caGet('test_mca1.VAL', mca_value)
IDL> status = caGet('test_vme1.DESC', vme_desc) ; This is a string PV
IDL> status = caEndGroup()
IDL> vme_desc = string(vme_desc) ; Convert from byte array to string
IDL> ; The following is an example of an INVALID grouped operation
IDL> caStartGroup
IDL> status = caGet('test_mca1.VAL', mca_value)
IDL> status = caGet('test_vme1.VAL', vme_value)
IDL> mca_value=0
IDL> ; We have redefined mca_value, so the previous location is
IDL> ; undefined. NO NOT DO THIS!
IDL> status = caEndGroup()
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caGetTimeout
PURPOSE:
This function returns the value of the EZCA Timeout parameter. This
value determines the time parameter passed to ca_pend_io() in EZCA.
In conjunction with the EZCA RetryCount parameter it determines how
long EZCA will try to connect to a process variable before giving up.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
timeout = caGetTimeout()
INPUTS:
None.
OUTPUTS:
The function return value of caGetTimeout is the floating point
value of the EZCA Timeout parameter, in seconds.
PROCEDURE:
This routine uses ezcaGetTimeout().
EXAMPLES:
IDL> print, caGetTimeout()
0.0500000
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caSetTimeout
PURPOSE:
This procedure sets the value of the EZCA Timeout parameter. This
value determines the time parameter passed to ca_pend_io() in EZCA.
In conjunction with the EZCA RetryCount parameter it determines how
long EZCA will try to connect to a process variable before giving up.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caSetTimeout, timeout
INPUTS:
Timeout: The timeout value in seconds (floating point).
OUTPUTS:
None
PROCEDURE:
This routine uses ezcaSetTimeout().
EXAMPLES:
IDL> caSetTimeout, .001
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caGetRetryCount
PURPOSE:
This function returns the value of the EZCA retry count parameter.
In conjunction with the EZCA Timeout parameter it determines how
long EZCA will try to connect to a process variable before giving up.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
RetryCount = caGetRetryCount()
INPUTS:
None.
OUTPUTS:
The function return value of caGetRetryCount is the integer
value of the EZCA RetryCount parameter.
PROCEDURE:
This routine uses ezcaGetRetryCount().
EXAMPLES:
IDL> print, caGetRetryCount()
599
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caSetRetryCount
PURPOSE:
This procedure sets the value of the EZCA RetryCount parameter.
In conjunction with the EZCA Timeout parameter it determines how
long EZCA will try to connect to a process variable before giving up.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caSetRetryCount, retrycount
INPUTS:
RetryCount: The integer retry count.
OUTPUTS:
None
PROCEDURE:
This routine uses ezcaSetRetryCount().
EXAMPLES:
IDL> caSetRetryCount, 100
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caPut
PURPOSE:
This procedure writes a new value to a channel access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caPut(pvname, value)
INPUTS:
pvname: The name of the process variable for which the new value
is to be written
value: The new value to be written. In general this can be a scalar
or array of any data type. There are of course restrictions
in that certain strings cannot be written to certain process
variables, and some process variables cannot be passed arrays.
KEYWORD PARAMETERS:
WAIT: Set this flag to force caPut to wait for a channel access
callback. The default is not to wait for a callback, using the
ezca function ezcaPutOldCa. The WAIT keyword results in a
call to ezcaPut, which uses channel access callbacks.
OUTPUTS:
The function return value of caPut is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists and a valid value was written) and non-zero if the routine
failed.
PROCEDURE:
This routine uses ezcaPut(). The "nelem" and "type" parameters passed
to ezcaPut are determined from the IDL data type and number of elements
of the "value" parameter passed to caPut(). Strings are converted to
to byte arrays before being passed.
RESTRICTIONS:
None. caPut can be called inside a group, i.e. after calling
caStartGroup and before calling caEndGroup. The "value"
variable passed to caPut can be immediately re-used when
inside a group, since EZCA copies it to a private location.
EXAMPLES:
IDL> ; Put a linear ramp (findgen()) to a waveform process variable.
IDL> status = caPut('my_waveform.VAL', findgen(100))
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
Sept. 16, 1998 Mark Rivers Added WAIT keyword, made non-callback
version of caput the default
NAME:
caStartGroup
PURPOSE:
This procedure starts an "asynchronous group". Within an asynchronous
group all calls to caGet and caPut are asynchronous, i.e. they queue
a request and return immediately without waiting for a reply from
the channel access servers. Calling caEndGroup causes the queue to be
flushed and waits for the replies. The use of asynchronous
groups can greatly improve the efficiency of channel access. The user
must be aware of the restrictions on caGet outlined under the
description of that routine.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caStartGroup
INPUTS:
None.
OUTPUTS:
None
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine sets that flag.
PROCEDURE:
This routine uses ezcaStartGroup().
EXAMPLES:
IDL> caStartGroup
IDL> status = caget('test_ao1.SCAN', scan)
IDL> status = caget('test_mca1.ERTM', ertm)
IDL> ; Print out values - they will be zero.
IDL> help, scan, ertm
IDL> status = caEndGroup()
IDL> ; Print out values after executing caEndGroup, they are non-zero
IDL> help, scan, ertm
Output:
SCAN INT = 0
ERTM FLOAT = 0.000000
SCAN INT = 6
ERTM FLOAT = 7.10000
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caEndGroup
PURPOSE:
This function ends an "asynchronous group". See caStartGroup for more
information on asynchronous groups.
caEndGroup flushes the queue of caGet and caPut calls and waits for
replies from the channel access servers.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
stat = caEndGroup(status)
INPUTS:
None.
OUTPUTS:
The function return value is 0 if the operation was successful,
otherwise it is the first encountered non-successful return code.
The optional status parameter can be used to return the status code
of each operation in the group.
OPTIONAL OUTPUT PARAMETERS:
status: If this optional parameter is present then it returns a
array of status information, one for each channel access
call in the group.
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine clears that flag.
PROCEDURE:
If the status parameter is present then this routine uses
ezcaEndGroupWithReport(). If the parameter is not present then
the routine calls ezcaEndGroup().
RESTRICTIONS:
When the status parameter is present, and ezcaEndGroupWithReport() is
called, there is no way to know in advance how many status values
will be returned. This routine passes a status array with 1024
elements, and then truncates it to the actual length. The maximum
number of status values which can be retrieved is thus 1024. No errors
will occur if an asynchronous group has more than 1024 calls, but
only the first 1024 status values can be obtained.
This is probably sufficient for most applications!
EXAMPLES:
IDL> caStartGroup
IDL> status = caget('test_ao1.SCAN', scan)
IDL> status = caget('test_mca1.ERTM', ertm)
IDL> ; Print out values - they will be zero.
IDL> help, scan, ertm
IDL> status = caEndGroup()
IDL> ; Print out values after executing caEndGroup, they are non-zero
IDL> help, scan, ertm
Output:
SCAN INT = 0
ERTM FLOAT = 0.000000
SCAN INT = 6
ERTM FLOAT = 7.10000
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caSetMonitor
PURPOSE:
This procedure sets a monitor on the specified process variable.
This causes a channel access callback to execute whenever the value
of that process variable changes. Subsequent calls to caGet() after
calling caSetMonitor will read the values provided by the callbacks,
rather than reading from the IOC.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caSetMonitor(pvname)
INPUTS:
pvname: The name of the process variable on which to set the monitor.
OUTPUTS:
The function return value of caSetMonitor is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaSetMonitor(). The "type" parameter required
by ezcaSetMonitor is the native EZCA data type as determined
by caGetCountAndType().
EXAMPLES:
IDL> status = caSetMonitor('test_ao1')
IDL> status = caGet('test_ao1', value)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caClearMonitor
PURPOSE:
This procedure clears a monitor on the specified process variable.
It cancels the effect of caSetMonitor().
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caClearMonitor(pvname)
INPUTS:
pvname: The name of the process variable on which to clear the monitor.
OUTPUTS:
The function return value of caClearMonitor is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaClearMonitor(). The "type" parameter required
by ezcaClearMonitor is the native EZCA data type as determined
by caGetCountAndType().
EXAMPLES:
IDL> status = caClearMonitor('test_ao1')
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caCheckMonitor
PURPOSE:
This function returns a non-zero value if there is a new (unread)
monitor for this process variable, otherwise it returns zero.
This function is particularly useful when a caGet() operation is
expensive in time, e.g. reading large arrays.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
state = caCheckMonitor(pvname)
INPUTS:
pvname: The name of the process variable on which to check the monitor.
OUTPUTS:
The function return value is zero if no new monitor value is available,
and non-zero if a new monitor value is available.
PROCEDURE:
This routine uses ezcaNewMonitorValue(). The "type" parameter required
by ezcaNewMonitorValue() is the native EZCA data type as determined
by caGetCountAndType().
EXAMPLES:
IDL> state = caCheckMonitor('test_ao1',event)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caDebug
PURPOSE:
This procedure turns the EZCA debugging flag on or off. Turning on
the debugging flag prints lots of information, which is mainly
useful to developers.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caDebug, state
INPUTS:
state: state=1 turns debugging on, state=0 turns debugging off.
OUTPUTS:
None
PROCEDURE:
This routine uses ezcaDebugOn() and ezcaDebugOff().
EXAMPLES:
IDL> caDebug, 1 ; Turn on debugging
setting Debug
IDL> status = caGet('test_ao1', value)
ca_pend_event(0.000010)
--start end-of-prologue() report
****** Start State:
AutoErrorMessage T InGroup F Debug T Trace F ErrorLocation LastOnly ListPrint
LastOnly TimeoutSeconds 0.050000
Workp : 9cf970 trashme F (nxt 0)
Channel_avail_hdr 0 :
...
...
IDL> caDebug, 0 ; Turn off debugging
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caTrace
PURPOSE:
This procedure turns the EZCA trace flag on or off. Turning on
the trace flag prints lots of information which is mainly useful
to developers. Setting the trace flag results in less
verbose output than setting the debug flag (see caDebug).
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caTrace, state
INPUTS:
state: state=1 turns trace on, state=0 turns trace off.
OUTPUTS:
None
PROCEDURE:
This routine uses ezcaTraceOn() and ezcaTraceOff().
EXAMPLES:
IDL> caTrace, 1 ;Turn on trace
setting Trace
IDL> status = caGet('test_ao1', value)
ca_pend_event(0.000010)
find_channel() found >test_ao1<
get_channel(): was able to find_channel()
ca_pend_event(0.000010)
...
...
IDL> caTrace, 0 ; Turn off trace
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caGetEnumStrings
PURPOSE:
This function returns all of the choice strings associated with a
Channel Access "enum" process variable. It is particularly useful
for building menus of options.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGetEnumStrings(pvname, strings)
INPUTS:
pvname: The name of the process variable for which the enum strings
are to be returned. The native channel access data type of
this process variable must be enum (3).
OUTPUTS:
strings: A string array containing the strings for each possible
value of the enum variable.
The function return value of caGetEnumStrings is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists and is of type enum) and non-zero if the routine failed.
SIDE EFFECTS:
This routine causes a channel access read. It does not use the
grouping mechanism of EZCA, i.e. it always executes immediately.
RESTRICTIONS:
There must be less than 16 enum strings and they must each be less
than 26 characters.
PROCEDURE:
This routine uses ezcaPvToChid and then ca_get() with a request type
of DBR_GR_ENUM. The functionality required by this routine is not
presently provided directly in EZCA, although it should probably be
added.
EXAMPLES:
IDL> status = caGetEnumStrings('test_mca1.SCAN', strings)
IDL> for i=0, n_elements(strings)-1 do print, strings(i)
Passive
Event
I/O Intr
10 second
5 second
2 second
1 second
.5 second
.2 second
.1 second
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caGetControlLimits
PURPOSE:
This procedure reads the control limits for the specified channel
access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetControlLimits(pvname, low, high)
INPUTS:
pvname: The name of the process variable from which to read the
control limits.
OUTPUTS:
low: The low control limit (double).
high: The high control limit (double).
The function return value of caGetControlLimits is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaGetControlLimits().
EXAMPLE:
IDL> status = caGetControlLimits('test_ao1', low, high)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caGetGraphicLimits
PURPOSE:
This procedure reads the graphic limits for the specified channel
access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetGraphicLimits(pvname, low, high)
INPUTS:
pvname: The name of the process variable from which to read the
graphic limits.
OUTPUTS:
low: The low graphic limit (double).
high: The high graphic limit (double).
The function return value of caGetGraphicLimits is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaGetGraphicLimits().
EXAMPLE:
IDL> status = caGetGraphicLimits('test_ao1', low, high)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caGetPrecision
PURPOSE:
This procedure reads the precision for the specified channel
access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetPrecision(pvname, precision)
INPUTS:
pvname: The name of the process variable from which to read the
precision.
OUTPUTS:
precision: The precision (short).
The function return value of caGetPrecision is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaGetPrecision().
EXAMPLE:
IDL> status = caGetPrecision('test_ao1', precision)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caGetStatus
PURPOSE:
This procedure reads the status parameters for a channel access
process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetStatus(pvname, timestamp, status, severity)
INPUTS:
pvname: The name of the process variable from which to read the
status parameters.
OUTPUTS:
timestamp: The timestamp of the last time the record was processed
lonarr(2).
status: The status flag (int).
severity: The severity flag (int).
The function return value of caGetStatus is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
PROCEDURE:
This routine uses ezcaGetStatus().
EXAMPLE:
IDL> status = caGetStatus('test_ao1', timestamp, status, severity)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caGetUnits
PURPOSE:
This procedure reads the units string for the specified channel
access process variable.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
status = caGetUnits(pvname, units)
INPUTS:
pvname: The name of the process variable from which to read the units.
OUTPUTS:
units: The units (string).
The function return value of caGetUnits is a status value. The
status is 0 if the routine was successful (i.e. the process variable
exists) and non-zero if the routine failed.
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine tests that flag.
PROCEDURE:
This routine uses ezcaGetUnits().
EXAMPLE:
IDL> status = caGetUnits('test_ao1', units)
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caError
PURPOSE:
This procedure controls error printing and returns error strings.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caError, err_string, /ON, /OFF, /PRINT, prefix=prefix
INPUTS:
None
KEYWORD PARAMETERS:
/ON
Setting this switch turns on automatic error message printing
on stdout. Automatic printing is initially enabled.
/OFF
Setting this switch turns off automatic error message printing
on stdout.
/PRINT
Setting this switch prints the last error message on stdout.
prefix=prefix
The prefix keyword can be used to pass a string which is prefixed
to error messages printed with /PRINT or fetched via the optional
output parameter.
OPTIONAL OUTPUT PARAMETERS:
err_string:
If this parameter is present then it will contain the text of the
last error message.
COMMON BLOCKS:
EZCA_COMMON contains a flag (ingroup) which indicates if we
are currently in an asynchronous group. This routine tests that flag.
PROCEDURE:
This routine uses ezcaPerror(), ezcaAutoErrorMessageOn(),
ezcaAutoErrorMessageOff(), and ezcaGetErrorString()
EXAMPLE:
IDL> ; Define a prefix and turn on error messages
IDL> caError, prefix='My program', /ON
IDL> ; Fetch the last error message
IDL> caError, err_string
MODIFICATION HISTORY:
Written by: Mark Rivers
June 28, 1995
NAME:
caVersion
PURPOSE:
This function returns the string of current version information
about ezcaIDL
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
string = caVersion()
INPUTS:
None.
OUTPUTS:
Return the string which gives the version information about
ezcaIDL, ezca, Ezca, and EPICS base verion number.
PROCEDURE:
This routine uses Ezca_version() from the ezcaScan library.
EXAMPLE:
IDL> print, caVersion()
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
NAME:
caInit
PURPOSE:
This routine sets the channel access timeout used by list array
functions defined in ezcaScan library.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caInit [,flag] [,help=help]
INPUTS:
flag: Optional flag, if set to -1 ezcaScan library default timeout
settings will be used.
KEYWORD PARAMETERS:
HELP: If ,/HELP is set, on-line help will be displayed.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine set the channel access timeout values used in the
ezcaScan library. This routine set the timeout to 3 seconds for
lists of process variables, and sets the timeout for
ca_pend_event to 0.001 second.
If a value of -1 is specified for the flag, the default value
of 10 seconds for lists of process variables will be used.
RESTRICTIONS:
None.
PROCEDURE:
This routine uses Ezca_init() from the ezcaScan library.
EXAMPLES:
IDL> caInit
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
NAME:
caPendEvent
PURPOSE:
This function causes the Ezca to call channel access ca_pend_event
function.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caPendEvent [,time=0.001] [,help=help]
INPUTS:
None.
KEYWORD PARAMETERS:
TIME: This keyword parameter is used to reset the timeout in seconds
used by ca_pend_event in ezcaScan library.
HELP: If ,/HELP is set, on-line help will be displayed.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine sets the timeout for event monitor routines used in
ezcaScan library and calls the ca_pend_event.
RESTRICTIONS:
Positive time must be used.
PROCEDURE:
This routine uses Ezca_setPendTime() from the ezcaScan library.
EXAMPLES:
IDL> caPendEvent, time=0.0001
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
NAME:
caPendIO
PURPOSE:
This routine sets the timeout used by ca_pend_io in array get/
put used in ezcaScan library.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
caPendIO, time=time, list_time=list_time
INPUTS:
None.
KEYWORD PARAMETERS:
TIME: Use the TIME=time keyword to set the timeout waiting for
channel access I/O for single process variable name.
LIST_TIME: Use the LIST_TIME=list_time keyword to set the timeout
waiting for channel access I/O for a list of PV names.
HELP: If ,/HELP is specified, on line help will be displayed.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
These times will be used in array get/put from then on in all
ca_pend_io calls in ezcaScan library.
RESTRICTIONS:
Positive real times should be used in those keywords.
PROCEDURE:
This routine uses Ezca_setPendTime() from the ezcaScan library.
EXAMPLES:
IDL> caPendIO, time=0.1, list_time=3.
IDL> caPendIO, /help
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
NAME:
caTimeStamp
PURPOSE:
This function returns the time stamp of corresponding value for
the specified record name.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
string = caTimeStamp(pvname)
INPUTS:
pvname: The name of the process variable for which the timestamp is to
be returned.
KEYWORD PARAMETERS:
None.
OUTPUTS:
string: The function returns the time stamp string for the requested
PV name.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
Only single PV name is allowed in input.
PROCEDURE:
This routine uses Ezca_timeStamp() from the ezcaScan library.
EXAMPLES:
IDL> print,caTimeStamp('chademoai1')
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
NAME:
caSearch
PURPOSE:
This function searches for a list of process variable names.
It returns 0 if successful, returns -1 if failed.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caSearch(pvname)
INPUTS:
pvname: The variable for a list of process variables for which the
channel access search to be done.
KEYWORD PARAMETERS:
None.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time pvnames has been referenced.
RESTRICTIONS:
None.
PROCEDURE:
This routine uses Ezca_search_list() from the ezcaScan library.
EXAMPLES:
IDL> print,caSearch('chademoai1')
IDL> x = ['chademoai1','chademoai2']
IDL> status = caSearch(x)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
04-11-96 bkc Fix typo error names to name
NAME:
caGetError
PURPOSE:
This function get CA return codes for a list of process variable names.
Return code can be 0 or -1, 0 for success, -1 for failure.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGetError(Pvname,Err)
INPUTS:
Pvname: The variable for a list of process variables for which the
channel access return code to be checked.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Err: The corresponding return code(s) for the Pvname(s) are returned.
Returns array of 0 or 1. 0 indicates success, 1 indicates failed.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time pvnames has been referenced.
RESTRICTIONS:
None.
PROCEDURE:
This routine uses Ezca_get_error_array() from the ezcaScan library.
EXAMPLES:
IDL> print,caGetError('chademoai1')
IDL> x = ['chademoai1','chademoai2']
IDL> status = caGetError(x)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
NAME:
caGetArray
PURPOSE:
This function reads values for a list of Channel Access process
variable. It returns 0 if successful, returns -1 if failed.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caGetArray(names,pdata,max=no,type=i,/TYPE,/EVENT)
INPUTS:
names: The variable for a list of channel access PV names for which
the array of data is to be returned.
KEYWORD PARAMETERS:
MAX: Default to 1 for a list of PV names. If more than one values
to be returned for a list of array type PV names, this keyword
must be specified. If the `no' specified is greater than the
native count, zeros will be padded in the output array.
If only one PV name is input, then caGetArray returns
the native element count for the process variable. Setting
MAX to a number less than the native count this will cause
caGetArray to return only the first MAX values for the PV.
TYPE: This keyword specifies the IDL data type to be returned by
the output array. If not specified, it defaults to 5, i.e.
double precision type of data will be returned by the
output array.
1 - byte 2 - short 3 - long 4 - float
5 - double 7 - string
/TYPE Instead of type=i a user can use the IDL data type keyword
directly, the data type keyword supercedes the type=i
specification. Valid types given below
/double
/float
/string
/long
/short
/byte
/EVENT If specified use the ca_array_get_callback otherwise use
the ca_array_get
OUTPUTS:
pdata: The output variable, pdata(max,noNames), returns the data
array for the requested list of PV names. The `max' is the no
of values specified by the keyword MAX, the `noNames' is the
number of PV names in the input variable names.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
Only one type of data can be requested for a list of PV names.
PROCEDURE:
This routine uses Ezca_getArray() from the ezcaScan library.
EXAMPLES:
Three examples are given below.
The first caGetArray call returns only the first value for each PV
name, the second and third caGetArray call both returns 10 float
values for each PV name
IDL> names=['chademowf7','chademowf8']
IDL> st = caGetArray(names,pdata)
IDL> st = caGetArray(names,pdata,max=10,/float)
IDL> st = caGetArray(names,pdata,max=10,type=4)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
04-11-96 bkc If array get failed, only the pvnames not found are
reported
04-22-96 bkc Replace caError by caGetError
NAME:
caPutArray
PURPOSE:
This function writes an array of data to a list of Channel Access
process variable. It returns 0 if successful, else retuns -1.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caPutArray(pvname, pdata, /event)
INPUTS:
pvname: The variable specifies a list of process variables for
which the input array of data is to be written to IOC.
pdata: Input data array. The data array must be consistant with
the number of PV names defined in the pvname.
KEYWORD PARAMETERS:
EVENT: If specified use the ca_array_put_callback otherwise
use the ca_array_put.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
Thus, it is the user's responsibility to make sure the adequate
pdata is provided for the pvname.
PROCEDURE:
This routine uses Ezca_putArray() from the ezcaScan library.
EXAMPLES:
In the following example write a string value '11' to two PV
names: chademomask1.VAL and chademoai2.VAL
IDL> x = ['chademomask1', 'chademoai2']
IDL> y = make_array(1, 2, /string)
IDL> y(0) = '11'
IDL> y(1) = '11'
IDL> status = caPutArray(x,y)
In the following example write values [1,2,3] to two waveform records
names: chademowf2 and chademowf5
IDL> x = ['chademowf2','chademowf5']
IDL> y = make_array(3, 2)
IDL> y(0,0) = [1,2,3]
IDL> y(0,1) = [1,2,3]
IDL> print,caPutArray(x,y)
IDL> print,caGetArray(x,pd,max=10)
IDL> print,pd
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
NAME:
caScan
PURPOSE:
This function provides add/get/zero/clear monitor features on a
scan record and a set of PV names.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caScan(name,pvnames,nonames,npts,vals,op_keyword,max=no)
INPUTS:
name: The name of the process variable which has control of
triggering scan, e.g. the scan record name.
pvnames: A list of detector process variables for which the values
are to be monitored by the trigger name.
KEYWORD PARAMETERS:
ADD: Set this flag /ADD to add a complete set of monitor for
name and pvnames.
Return 0 if successful, -1 if failed, 1 if old monitor
already existed. If succeeds, the output variable npts
is set to the number of data to be detected, and the
nonames is set to the number of PVs in pvnames.
CLEAR: Set this flag /CLEAR to clear the monitor set by add.
Return 0 if successful, -1 if failed.
GET: Set this flag /GET to get scan array of monitor values back.
Return -1 if failed, return 1 if scan is properly set up but
not triggered yet, return >1 if real data detected.
If succeeds, the npts is set to the number of data so far
detected.
ZERO: Set this flag /ZERO to zero the allocated space.
Return 0 for success, -1 for failure.
MAX: Specifies the max number of monitor values to be returned.
If the trigger name is not a scan record, the max=no must
be provided for this function.
OUTPUTS:
nonames: This variable returns the number of PVs in pvnames.
npts: This variable returns the current number of data points
detected by the scan record.
vals: This detector data array buff, vals(nonames,max), stores
the detected data so far captured.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
None.
PROCEDURE:
This routine uses Ezca_scanAddMonitor(), Ezca_scanClearMonitor(),
Ezca_scanGetMonitor(), and Ezca_scanZeroMonitor() from the Ezca
library.
EXAMPLES:
For scan record type triggered scan
IDL> print,caScan('name',pvnames,/add)
IDL> print,caScan('name',pvnames,nonames,npts,vals,/get)
IDL> print,caScan('name',pvnames,/zero)
IDL> print,caScan('name',pvnames,/clear)
For non-Scan record type triggered scan
IDL> print,caScan('name',pvnames,/add,max=100)
IDL> print,caScan('name',pvnames,nonames,npts,vals,/get,max=100)
IDL> print,caScan('name',pvnames,/zero,max=100)
IDL> print,caScan('name',pvnames,/clear,max=100)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
NAME:
caMonitor
PURPOSE:
This function provides Add/Get/Check/Clear monitor features on a
single PV or a list of PV names.
CATEGORY:
EPICS Channel Access Interface
CALLING SEQUENCE:
Status = caMonitor(name, vals, num, overflow, op_keyword,type_keyword, max=no)
INPUTS:
name: The variable for a PV or a list of PV names.
KEYWORD PARAMETERS:
ADD: Set /ADD to add CA monitor for the specified name.
Return 0 for success, -1 for failure.
CLEAR: Set /CLEAAR to clear CA monitor for the specified name.
Return 0 for success, -1 for failure.
CHECK: Set /CHECK to check for new event for the specified name.
Return 0 for success, -1 for failure.
The ouput variable 'vals' contains the return event flags.
0 - flags no new event detected
1 - flags new event detected
GET: Set /GET to get monitor values back for the specified name.
Different type of monitor returns different vals array.
If non queue type monitor set, the vals array returns a
single value for each PV in the name variable.
If the kewword /QUEUE is specified, in addition of vals,
both num and overflow variables are also returned.
QUEUE: Set /QUEUE flag to queue the value change event for the
monitored single channel until the user gets them.
MAXQUEUE: The MAXQUEUE=no must be specified if /QUEUE is specified.
MODE: This flag indicates what type of monitor queue is desired.
The MODE=i where i can be 1/2/3, it defaults to 1. The
MODE=1 or 2 monitor fills the QUEUE buff until it is fulled.
If MODE=1, the /GET will clear the QUEUE buff.
IF MODE=2, the /GET will not clear the QUEUE buff.
The MODE=3 uses the circulat buffer, it keeps the most
current MAXQUEUE values in the queue buffer.
Default Vals returned in double precision form.
/INT Return Vals converted to integer
/LONG Return Vals converted to long integer
/BYTE Return Vals converted to byte type
/FLOAT Return Vals converted to float type
/STRING Return Vals converted to string type
OUTPUTS:
vals: Returns the array of data if either keyword /GET or /CHECK
is specified
num: Returns the real number of data in the vals array for the
/QUEUE mode
overflow: Returns the buffer full indicator for the /QUEUE mode
0 - vals queue buff is not full
1 - vals queue buff is full
COMMON BLOCKS:
None.
SIDE EFFECTS:
This routine will causes a channel access search to take place if
this is the first time this process variable has been referenced.
RESTRICTIONS:
All the PVs are monitored as double values in this function
unless the PV is a DBR_STRING type then monitored as string type.
For getting the monitored queue array, only a single PV name can
be specified. For non queue type monitor, only the first value
for a PV can be returned by this function. Use caGet to get
array type of values back.
PROCEDURE:
This routine uses Ezca_monitorArrayAdd(), Ezca_monitorArrayGet(),
Ezca_monitorArrayCheck(), Ezca_monitorArrayClear(), Ezca_queueAdd(),
Ezca_queueGet(),Ezca_queueZero(), and Ezca_queueClear()
from the ezcaScan library.
EXAMPLES:
Single value monitor
IDL> print,caMonitor('chademoai1',/add)
IDL> print,caMonitor('chademoai1',vals,/get)
IDL> print,caMonitor('chademoai1',/clear)
Use queue array monitor with maxqueue=100
IDL> print, caMonitor('chademoai1',/add,/queue,maxqueue=100)
IDL> print, caMonitor('chademoai1',vals,num,overflow,/get,/queue,maxqueue=100)
IDL> print, caMonitor('chademoai1',/clear,/queue)
MODIFICATION HISTORY:
Written by: Ben-chin Cha Dec, 1995
04-12-96 bkc Modified on line help syntax
04-07-99 bkc Return monitor values specification:
/byte,/int,/long,/float,/string
Category: Events
[List of Routines]
NAME:
execonevent
PURPOSE:
Widget to spawn an executable (with shot as argument) when an
MDSplus event occurs. An IDL routine can also be spawned with shot as
the only argument, or any IDL command string executed.
CATEGORY:
Events, MDSplus
CALLING SEQUENCE:
IDL> execOnEvent, kickOffEvent='bdtest', executable='/u/bdavis/cvs/idl_cvs/echoarg.exe'
IDL> execonevent, events=['NSTX_SOC', 'my_event' ]
IDL> execonevent, emailTo=['vlad@pppl.gov, joeshmoe@pppl.gov'], $
events=['NSTX_ACQ_DONE', 'CAM1_DONE', $
'CAM2_DONE','CAM3_DONE','CAM4_DONE' ]
to get e-mail when really important events are missed, e.g., :
IDL> execonevent,add=['TS_RAW_READY','PHOENIXGO_P1','MPTS_FIT_DONE', $
'TFMON_ACQ_DONE'], emailTo='joeshmoe@pppl.gov'
INPUTS:
none.
KEYWORD PARAMETERS:
(optional)
kickOffEvent - event at which to kick of executable
executable - executable to spawn
idljob - spawns subprocess, with current shot number as the only input
cmd - IDL command string to execute (will wait until returns)
TEST - if set, appends TEST to all events
EVENTS_WANTED - Character array of events to watch for.
defaults to ['NSTX_SOC', 'CAM1_DONE',
'CAM2_DONE','CAM3_DONE','CAM4_DONE' ]
EMAIL - email address for message if all events listed not set before next shot..
NOCLEAR - if set, will not clear events when first event is recognized
noBox - if set, will not create color box for events
(can conflict with plot windows spawned from cmd)
PRINT - if set, will print messages when events are recognized
TIME - if set, will display time-of-day when event was declared
add_events - if set, will add these event(s) to the default
BIG - if set, fonts are big
WALL - if set, events of interest for display wall, and big font
GROUP_LEADER - Group_Leader ID
OUTPUTS:
none.
NOTES:
The time of day will be printed for the first event, and the other times
will be cleared. Then the time difference will be printed as mm:ss,
so :12 would mean it came 12 seconds after the first event.
TESTING
IDL> execonevent, EVENTS_WANTED=['MY_TEST_EVENT_1','MY_TEST_event_2'], $
/Shots
and from a VMS computer:
IDL> SetMDSShotEvent,'MY_TEST_EVENT_1', 999999
IDL> execonevent, EVENTS='bdtest', cmd='print, "Hi Mom"', /verbose
ROUTINES USED:
MK_COLOR, usingXwindows, MDSEVENT
EXAMPLE:
to automatically have MPTS plots come up on Display Wall:
IDL> execonevent, EVENTS='MPTS_REFRESH', cmd='plot_mpts,shot=0,chrsz=1.5, xmargin=[7,3]'
LIMITATION:
Shot numbers are only returned when running on VMS currently.
NOTES:
As the events are declared, the boxes turn color.
When the first event in the list is recognized, the other boxes are
set to yellow (unless /noClear was set). Shot numbers declared with
the events may optionally be displayed.
The status fields are initially the background color.
A program calling this routine, might want to save !D.WINDOW
before the TV commands and restore it immediately afterwards.
MODIFICATION HISTORY:
15-Jun-2010 added cmd keyword [BD]
01-Oct-2008 Removed MDSconnect
06-Mar-2006 Written by Bill Davis, PPPL
NAME:
monevents_noxmanager
PURPOSE:
monevents version to run in batch mode.
Widget to monitor occurrence of MDSplus events & optional Shot #,
if passed with the event declaration. The time of the event can also
be displayed.
EXPLANATION:
Lists various events related to an NSTX shot cycle (as a default).
As the events are declared, the boxes turn color.
When the first event in the list is recognized, the other boxes are
set to yellow (unless /noClear was set). Shot numbers declared with
the events may optionally be displayed.
CATEGORY:
Events, MDSplus, Monitoring Widget
CALLING SEQUENCE:
IDL> monevents
to get a small # of key events:
IDL> monevents, EVENTS_WANTED=['NSTX_SOC', $
'NSTX_TMINUS60', 'NSTX_SOD', $
'NSTX_ACQ_STARTED' ,'PC_908C16N08_ACQ', $ ; Digitizer that EFIT needs
'MPTS_FIT_DONE', 'NSTX_ACQ_DONE' , $
'SFLIP_IN_TREE' ], $
/SHOT, /NoClear
to get Diagnostic events and labels:
IDL> monevents_noxmanager, file_input='/u/bdavis/cvs/idl_cvs/eventlabelsdiags.txt', $
tabs=0, maxper=12, /shot, /noclear, /WebGifs, $
outFile='NSTX_Diagnostic_Status.gif'
IDL> monevents_noxmanager, file_input='/u/bdavis/cvs/idl_cvs/eventlabelssmall.txt', $
tabs=0, maxper=12, /shot, /noclear, /WebGifs, $
outFile='NSTX_Diagnostic_Status_Example.gif'
to get all MPTS-relevant events:
IDL> monevents,/shot,add=['NSTX_ABC', 'MPTS_FORCEFIT', $
'NSTX_ABS','NSTX_KLC','TS_RAW_READY']
to see all QCS at once:
IDL> monevents,/qcs,tabs=0,maxper=22, /shot, clear_event='NSTX_SOC' ,/noclear
for QCS testing:
IDL> monevents,/shot,add=['sflip_files','test2','qcs_test'],tabs=0,/nocle, $
logfile='$HOME/ShotCycleEvents.log'
for watching TF timing:
IDL> monevents,/shot,tabs=0,/nocle, $
EVENTS_WANTED=['NSTX_SOD','PC_908C36N02_ACQ','PC_908C36N06_ACQ', $
'PC_908C36N10_ACQ','PC_908C36N14_ACQ','TFMON_ACQ_DONE']; for monitoring TF joint events, with a logfile in your home directory:
for watching EFIT timing:
IDL> monevents,/shot,/noclear,tabs=0, $
EVENTS_WANTED=['NSTX_SOD','PC_908C16N08_ACQ', 'FDIA_CALC_DONE', $
'OP_H908_01_ACQUIRED', 'OP_H908_02_ACQUIRED', 'OP_H908_04_ACQUIRED', $
'OP_H908_05_ACQUIRED', 'OP_H908_07_ACQUIRED', 'OP_H908_08_ACQUIRED', $
'OP_H908_09_ACQUIRED', 'OP_H908_11_ACQUIRED', 'OP_H908_13_ACQUIRED', $
'PHOENIXGO_P1', 'MPTS_FIT_DONE', 'PHOENIXGO_P2V1', $
'phoenixDone_p1', $
'NSTX_ACQ_DONE', $
'phoenixDone_p2' ], $
logfile='$HOME/EfitEvents.log'
INPUTS:
none.
KEYWORD PARAMETERS:
(optional)
EVENTS_WANTED - String array of events to watch for
LABELS - strings array to display instead of events
FILE_INPUT - a text file of events to watch for (labels can follow each, in quotes)
format like:
NSTX_SOC "Start of Cycle"
BA_L8212_01_ACQ "Bolometers"
GS_908C28N14_ACQ "Gas Injection"
...
CLEAR_EVENT - event to clear green lights on (default to EVENTS_WANTED[0]
ADD_EVENTS - these events will be added to default events.
QCS - if set, will read the file for QCS events, and use all there.
LogFile - will log events to this file.
LogEvents - if set, and LogFile not set, will log events to MonEvens.log
nCols - number of columns wanted. Will default to 15 per column
maxPerCol - another way to determine # of columns. Default=15.
tabs - will default to tabs if more than one column. if=0, all on 1.
NOCLEAR - if set, will not clear text boxes when first event is recognized
PRINT - if set, will print messages when events are recognized
SHOWSHOTS - if set, will display shot numbers declared with the events
TIME - if set, will display time-of-day when event was declared
BIG - if set, fonts are big
WALL - if set, events of interest for display wall, and big font
GIFseconds - seconds between writes of GIF file of window contents
(good for making web-accessible displays). If not present, don't make files
WebGifs - if set, will create a gif (to be read from the web) whenever widget is
updated (DEFAULT=0)
GROUP_LEADER - Group_Leader ID
VERBOSE - if set, lots of information is output
OUTPUTS:
none.
TESTING
IDL> monevents, EVENTS_WANTED=['MY_TEST_EVENT_1','MY_TEST_event_2'], $
/Shots
and from a VMS computer:
IDL> SetMDSShotEvent,'MY_TEST_EVENT_1', 999999
COMMON BLOCKS:
none
ROUTINES USED:
MK_COLOR, usingXwindows, MDSEVENT
EXAMPLE:
IDL> monevents
LIMITATION:
Shot numbers are only returned when running on VMS currently.
NOTES:
The time of day will be printed for the first event, and the other times
will be cleared. Then the time difference will be printed as mm:ss,
so :12 would mean it came 12 seconds after the first event.
The status fields are initially the background color.
A real program might want to save !D.WINDOW before the TV commands
and restore it immediately afterwards.
MODIFICATION HISTORY:
01-Oct-2008 Removed mdsconnect [BD]
18-Aug-2008 Added labels to be displayed instead of events, if desired.
added WebGifs & GifSeconds keywords. Add
10-Jul-2008 made logging of events clearer
21-Feb-07 added /logevents and logfile as keywords
08-Feb-06 Added clear_event keyword, and made it show up 1st in list
09-Nov-05 added tabs and QCS keyword
03-Feb-04 added wall keyword
10-Feb-03 added keyword add_event [BD]
14-Jun-01 Default to showing time
20-Jul-00 Written by Bill Davis, PPPL
NAME:
monevents
PURPOSE:
Widget to monitor occurrence of MDSplus events & optional Shot #,
if passed with the event declaration. The time of the event can also
be displayed.
EXPLANATION:
Lists various events related to an NSTX shot cycle (as a default).
As the events are declared, the boxes turn color.
When the first event in the list is recognized, the other boxes are
set to yellow (unless /noClear was set). Shot numbers declared with
the events may optionally be displayed.
CATEGORY:
Events, MDSplus, Monitoring Widget
CALLING SEQUENCE:
IDL> monevents
to get a small # of events for Dummy Load testing:
IDL> monevents, EVENTS_WANTED=[ $
'NSTX_SOC', $
'nstx_initphase_done', $
'NSTX_SOD', $
'NSTX_ACQ_STARTED', $ ; Digitizer that EFIT needs
'PC_908C16N08_ACQ', $
'NSTX_ACQ_DONE' , $
'efitdb_done' ], $
/SHOT, /NoClear, tabs=0
to get a small # of key events, starting at SOC:
IDL> monevents, EVENTS_WANTED=['NSTX_SOC', 'NSTX_TM60', $
'NSTX_SOD', 'PC_908C16N08_ACQ', $ ; Digitizer that EFIT needs
'MPTS_FIT_DONE', 'NSTX_ACQ_DONE' , $
'phoenixDone_p1' ], $
/SHOT, /NoClear
to get Diagnostic events and labels:
IDL> monevents, file_input='/u/bdavis/cvs/idl_cvs/eventlabelsdiags.txt', $
tabs=0, maxper=12, /shot, /noclear, /WebGifs
to get all MPTS-relevant events:
IDL> monevents,/shot,add=['NSTX_ABC', 'MPTS_FORCEFIT', $
'NSTX_ABS','NSTX_KLC','TS_RAW_READY']
to see all MEMS at once:
IDL> monevents,/MEMS,tabs=0, maxper=22, /shot, clear_event='NSTX_SOC' ,/noclear
for MEMS testing:
IDL> monevents,/shot,add=['sflip_files','test2','qcs_test'],tabs=0,/nocle, $
logfile='$HOME/ShotCycleEvents.log'
for watching TF timing:
IDL> monevents,/shot,tabs=0,/nocle, $
EVENTS_WANTED=['NSTX_SOD','PC_908C36N02_ACQ','PC_908C36N06_ACQ', $
'PC_908C36N10_ACQ','PC_908C36N14_ACQ','TFMON_ACQ_DONE']; for monitoring TF joint events, with a logfile in your home directory:
for watching EFIT timing:
IDL> monevents,/shot,/noclear,tabs=0, $
EVENTS_WANTED=['NSTX_SOD','FDIA_CALC_DONE', $
'OP_H908_01_ACQUIRED', 'OP_H908_02_ACQUIRED', 'OP_H908_04_ACQUIRED', $
'OP_H908_05_ACQUIRED', 'OP_H908_07_ACQUIRED', 'OP_H908_08_ACQUIRED', $
'OP_H908_09_ACQUIRED', 'OP_H908_11_ACQUIRED', 'OP_H908_13_ACQUIRED', $
'PHOENIXGO_P1', 'MPTS_FIT_DONE', 'PHOENIXGO_P2V1', $
'phoenixDone_p1', $
'NSTX_ACQ_DONE', $
'phoenixDone_p2' ], $
logfile='$HOME/EfitEvents.log'
INPUTS:
none.
KEYWORD PARAMETERS:
(optional)
EVENTS_WANTED - String array of events to watch for
LABELS - strings array to display instead of events
FILE_INPUT - a text file of events to watch for (labels can follow each, in quotes)
format like:
NSTX_SOC "Start of Cycle"
BA_L8212_01_ACQ "Bolometers"
GS_908C28N14_ACQ "Gas Injection"
...
CLEAR_EVENT - event to clear green lights on (default to EVENTS_WANTED[0]
ADD_EVENTS - these events will be added to default events.
MEMS - if set, will read the file for MEMS events, and use all there.
LogFile - will log events to this file.
LogEvents - if set, and LogFile not set, will log events to MonEvens.log
nCols - number of columns wanted. Will default to 15 per column
maxPerCol - another way to determine # of columns. Default=15.
tabs - will default to tabs if more than one column. if=0, all on 1.
NOCLEAR - if set, will not clear text boxes when first event is recognized
PRINT - if set, will print messages when events are recognized
SHOWSHOTS - if set, will display shot numbers declared with the events
TIME - if set, will display time-of-day when event was declared
BIG - if set, fonts are big
WALL - if set, events of interest for display wall, and big font
GIFseconds - seconds between writes of GIF file of window contents
(good for making web-accessible displays). If not present, don't make files
WebGifs - if set, will create a gif (to be read from the web) whenever widget is
updated (DEFAULT=0)
BD - display events favored by a certain programmer.
GROUP_LEADER - Group_Leader ID
VERBOSE - if set, lots of information is output
OUTPUTS:
none.
TESTING
IDL> monevents, EVENTS_WANTED=['MY_TEST_EVENT_1','MY_TEST_event_2'], $
/Shots
and from a VMS computer:
IDL> SetMDSShotEvent,'MY_TEST_EVENT_1', 999999
COMMON BLOCKS:
none
ROUTINES USED:
MK_COLOR, usingXwindows, MDSEVENT
EXAMPLE:
IDL> monevents
IDL> monevents, num=450, prefix='gt', time=0, tab=0, npercol=30, show=0, shot=0
LIMITATION:
Shot numbers are only returned when running on VMS currently.
NOTES:
The time of day will be printed for the first event, and the other times
will be cleared. Then the time difference will be printed as mm:ss,
so :12 would mean it came 12 seconds after the first event.
The status fields are initially the background color.
A real program might want to save !D.WINDOW before the TV commands
and restore it immediately afterwards.
MODIFICATION HISTORY:
12-Apr-2010 add num and prefix keywords so can generate event names
01-Oct-2008 Removed mdsconnect [BD]
18-Aug-2008 Added labels to be displayed instead of events, if desired.
added WebGifs & GifSeconds keywords. Add
10-Jul-2008 made logging of events clearer
21-Feb-07 added /logevents and logfile as keywords
08-Feb-06 Added clear_event keyword, and made it show up 1st in list
09-Nov-05 added tabs and QCS keyword
03-Feb-04 added wall keyword
10-Feb-03 added keyword add_event [BD]
14-Jun-01 Default to showing time
20-Jul-00 Written by Bill Davis, PPPL
NAME:
watchevents
PURPOSE:
Widget to monitor occurrence of MDSplus events.
If all events do not happen before next occurance of first event,
send e-mail.
CATEGORY:
Events, MDSplus
CALLING SEQUENCE:
IDL> watchevents, events=['NSTX_SOC', 'my_event' ]
IDL> watchevents, emailTo=['vlad@pppl.gov, joeshmoe@pppl.gov'], $
events=['NSTX_ACQ_DONE', 'CAM1_DONE', $
'CAM2_DONE','CAM3_DONE','CAM4_DONE' ]
to get all MPTS-relevant events:
IDL> watchevents,/shot,/show,add=['NSTX_ABC', 'MPTS_FORCEFIT', $
'NSTX_ABS','NSTX_KLC','TS_RAW_READY']
INPUTS:
none.
KEYWORD PARAMETERS:
(optional)
TEST - if set, appends TEST to all events
EVENTS_WANTED - Character array of events to watch for.
defaults to ['NSTX_SOC', 'CAM1_DONE',
'CAM2_DONE','CAM3_DONE','CAM4_DONE' ]
GROUP_LEADER - Group_Leader ID
NOCLEAR - if set, will not clear events when first event is recognized
PRINT - if set, will print messages when events are recognized
SHOWSHOTS - if set, will display shot numbers declared with the events
TIME - if set, will display time-of-day when event was declared
add_events - if set, will add these event(s) to the default
BIG - if set, fonts are big
WALL - if set, events of interest for display wall, and big font
OUTPUTS:
none.
NOTES:
The time of day will be printed for the first event, and the other times
will be cleared. Then the time difference will be printed as mm:ss,
so :12 would mean it came 12 seconds after the first event.
TESTING
IDL> watchevents, EVENTS_WANTED=['MY_TEST_EVENT_1','MY_TEST_event_2'], $
/Shots
and from a VMS computer:
IDL> SetMDSShotEvent,'MY_TEST_EVENT_1', 999999
COMMON BLOCKS:
none
ROUTINES USED:
MK_COLOR, usingXwindows, MDSEVENT
EXAMPLE:
IDL> watchevents
LIMITATION:
Shot numbers are only returned when running on VMS currently.
NOTES:
As the events are declared, the boxes turn color.
When the first event in the list is recognized, the other boxes are
set to yellow (unless /noClear was set). Shot numbers declared with
the events may optionally be displayed.
The status fields are initially the background color.
A program calling this routine, might want to save !D.WINDOW
before the TV commands and restore it immediately afterwards.
MODIFICATION HISTORY:
08-Sep-08 removed mdsconnect.
10-Jun-05 Converted from Monevents.pro for Vlad.
03-Feb-04 added wall keyword
10-Feb-03 added keyword add_event [BD]
14-Jun-01 Default to showing time
20-Jul-00 Written by Bill Davis, PPPL
Category: Fast Cameras
[List of Routines]
NAME:
cineThumbNails
PURPOSE:
Plot thumbnails of many frames from a .cin file
CATEGORY:
Fast Cameras
CALLING SEQUENCE:
IDL> cinethumbnails, shot
INPUTS:
shot - optional alternate to filename; if more than one cine file found
you will get a dialog box (if no shot or filename entered, will be prompted)
KEYWORD PARAMETERS:
Inputs:
(Optional)
filename - optional name of cine file (fastest when this used)
t1 - start time of thumbnails (sec.)
t2 - end time of thumbnails (sec.)
nWanted - # of thumbnails (defaults to 108)
edge - if set, will show plasma edge on picture (separatrix) (NOT WORKING)
fit - type of fit for separatrix plot
deltaT - time between thumbnails
minVal - min value to use in byte scaling (default=0)
maxVal - max value to use in byte scaling (default depends on camera type)
>>> if = 0, each frame will be byte scaled.
bytescale - if set, bytescale frames
gamma - gamma to apply to image (Default=0.55)
ctb - color table for non-color image
saturation - (Default=0.3)
xsize - horizontal size of plot window (defaults to 640, but will let you manually expand)
ysize - vertical size of plot window (defaults to 512, but will let you manually expand)
label - if=0 will not label each frame with time in msec
title - if=0 will not print file name at top right of frame
horizontal_flip - if set, flip images horizontally
vertical_flip - if set, flip images vertically
RotCCW - rotate image Counter-ClockWise
RotCW - rotate image ClockWise
nRows - # of rows of thumbnails
top2bottom - if=0, time will go from bottom to top
border - # of pixels between images (default=1)
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
(none)
OUTPUTS:
just plots to graphic window
EXAMPLES:
!P.FONT=0
setup_ps, 'Thumbs_138117.ps', printer = 'postscript color'
cinethumbnails, /horiz, /rotccw, ctb=3, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138117.cin', $
minVal=20, maxVal=230, nWanted=40, /edge, $
t1=0.242,t2=0.248, xsize=900, ysize=580, nsmooth=3, thick=3
unsetup_ps
cinethumbnails, /horiz, /rotccw, ctb=3, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139050.cin', $
t1=0.399,t2=0.455, xsize=900, ysize=580,/debug
IDL> i = 0
IDL> i = i+1
IDL> cinethumbnails, '/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138120.cin', $
t1=0.219+i*0.001, t2=0.219+(i+1)*0.001, /horizontal_flip, /RotCCW, ctb=3, $
xsize=1024, ysize=780
IDL> mk_jpeg,'~/sh138120_'+strtrim(219+i,2)+'ms.jpg'
IDL> cinethumbnails, '/p/nstxcam/Miro2-7988/2010/nstx_2_137600.cin'
(expand window manually)
IDL> cinethumbnails, 137726, xsize=1600,ysize=1000, t1=.03, t2=.31, nwanted=45
(select the Miro file)
IDL> cinethumbnails,'/p/nstxcam/Phantom73-6663/2010/nstx_3_137726.cin',maxval=0, $
t1=.100,t2=.274 ; (will byte scale each frame)
IDL> cinethumbnails,'/p/nstxcam/Phantom710-9206/2010/nstx_1_137726.cin',maxval=2000, $
t1=.246,t2=.267,nw=23
; to test separtrix drawing
IDL> cinethumbnails, '/p/nstxcam/Phantom710-9205/2010/nstx_5_139444.cin', $
t1=.255,t2=.285, /horizontal_flip, /RotCCW, ctb=3, $
nwanted=20, /bytescale, /edge
; or from CMOD:
IDL> cinethumbnails, $
'/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216028.cin', $
t1=.0,t2=.02, /horizontal_flip, ctb=3, nwanted=20, /bytescale, /edge
IDL> cinethumbnails, 'nstx_5_137582.cin', t1=.32, t2=.37, $
nSmooth=3, Rotation=1, /horiz, xSize=1300, ySize=900, /edge
IDL> cinethumbnails, '/p/nstxcam/Phantom73-8032/2010/nstx_4_137702.cin'
for Stewart's FY15 GPI paper:
IDL> cinethumbnails, t1=.550929, t2=.551029, label=0, /edge, $
nSmooth=3, Rotation=1, /horiz, xSize=668, ySize=652*.666, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_140395.cin', $
/rainbow, border=3, /ellip, nWanted=8, nrows=2, howFar=.2, /verb
IDL> !P.FONT=0
IDL> setup_ps, 'thumbs_140395.ps', printer='postscript', /color
IDL> cinethumbnails, t1=.550929, t2=.551029, label=0, /edge, $
nSmooth=3, Rotation=1, /horiz, xSize=668*10./8, ySize=652*.666, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_140395.cin', $
aveT1=.5505, aveT2=.5515, showCon=1, nlevs=600, $
/rainbow, border=3, /ellip, nWanted=10, nrows=2, howFar=.1, /verb
IDL> unsetup_up
IDL> mk_jpeg, 'mythumbs.jpg' ; make a jpeg file of whatever is plotted
IDL> cinethumbnails, t1=.550929, t2=.551029, label=0, /edge, $
nSmooth=3, Rotation=1, /horiz, xSize=668*10./8+80, ySize=652*.666, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_140395.cin', $
/rainbow, border=3, /ellip, nWanted=10, nrows=2, howFar=.1, /norm, $
bytescale=0, aveT1=.5505, aveT2=.5515, minVal=0.405, maxVal=2.159, $
/colorbar
IDL> cinethumbnails, /edge, $
nSmooth=3, Rotation=1, /horiz, xSize=668*10./8+80, ySize=652*.666, $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_140395.cin', $
/rainbow, border=3, /ellip, nWanted=10, nrows=2, howFar=.1, /norm, $
bytescale=0, aveT1=.5505, aveT2=.5515, minVal=0.405, maxVal=2.159, $
/colorbar, t1=.550929, t2=.551029, label=0,/verbose
NOTES:
see http://nstx.pppl.gov/nstx/Software/Applications/cinethumbnails.html
for examples
MODIFICATION HISTORY:
30-Jul-2014 handle white at bottom of color table
14-Oct-2013 added FIT keyword for separatrix plot
07-Mar-2013 added keywords top2bot (now default), nrows, and border (def=1)
26-Feb-2013 mods to work from a web page. Added medsmooth keyword.
12-Dec-2011 put flip and rotate in for doing blob work. Also adding option to show
separatrix and limiter shadow
14-Dec-2010 made to work with monochrome files (not True Color)
Written by Bill Davis, 12-Apr-2010
NAME:
load_fc
PURPOSE:
Load summary Waveforms for Phantom Fast Cameras into MDSplus.
PROCEDURE:
CATEGORY:
Fast Cameras, MDSplus
CALLING SEQUENCE:
load_fc, shot1, shot2, path=['/p/nstxusr/miro/2009','/p/nstxcam/miro/2009'], $
prefix='Miro'
load_fc, shot1, shot2, path='/p/nstxusr/miro/2008',prefix='Miro'
INPUTS:
shot1 = starting shot number to process
shot2 = (Optional) last shot number to process
KEYWORDS:
(Optional)
test - doesn't write to MDSplus
EventDone - if there, will declare this event when all of one shot done
noDeclare - if set, will declare NO events.
COMMON BLOCKS:
NONE
NOTES:
YOU NEED PRIVILEGES to write to the MDSplus tree. On skylark:
IDL> addSigNodes, shot1, shot2, tree='CAMERAS', $
nodes=['\aveintensity', '\maxintensity', '\ave_r','\ave_g','\ave_b' ], $
tags =['\aveint', '\maxint','\ave_r','\ave_g','\ave_b']
(probably better to do the above in TCL procedure
LIMITATIONS:
MODIFICATION HISTORY:
09-Mar-2007 WRITTEN by Bill Davis
NAME:
MKMANYMOVIES
PURPOSE:
make animations for the Fast Camera data from a shot list
CATEGORY:
Fast Cameras
CALLING SEQUENCE:
IDL>
INPUTS:
shot = NSTX shot number
KEYWORD PARAMETERS:
Inputs:
infile - filename for shot list
t1 - start time in msec
t2 - end time in msec
outDir -
shortName -
minWidth -
minVal - Min pixel value to show. DEF = 0
maxVal - Max pixel value to show, DEF = 16383
Saturation
fps
skip -
auto -
baseDir -
overwrite -
xsize - horizontal size of X window
ysize - vertical size of X window
xpos - initial X position of lower left of X window in pixels
ypos - initial Y position of lower left of X window in pixels
charsize - size of characters on plot
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
status - if odd, then success
OUTPUTS:
movie files
EXAMPLE:
IDL> mkmanymovies, infile='testshots.txt'
; to just do one shot
IDL> mkmanymovies, shot=120870
NOTES:
MODIFICATION HISTORY:
04-Feb-2015 Roger wanted files from other years, so adding logic
29-Jan-2015 Written by Bill Davis, PPPL, for Roger Raman
Category: files
[List of Routines]
NAME:
FDECOMP
PURPOSE:
Routine to decompose a file name for any operating system
CATEGORY:
Files, OS Specific, Strings
CALLING SEQENCE:
FDECOMP, filename, disk, dir, name, qual, version, [OSFamily = ]
INPUT:
filename - string file name, scalar
OUTPUTS:
All the output parameters are scalar strings
disk - disk name, always '' on a Unix machine, scalar string
dir - directory name, scalar string
name - file name, scalar string
qual - qualifier, set equal to the characters beyond the last "."
version - version number, always '' on a non-VMS machine, scalar string
OPTIONAL INPUT KEYWORD:
OSFamily - one of the four scalar strings specifying the operating
system: 'vms','windows','MacOS' or 'unix'. If not supplied,
then OS_FAMILY() is used to determine the operating system.
EXAMPLES:
Consider the following file names
Unix: file = '/rsi/idl40/avg.pro'
VMS: file = '$1$dua5:[rsi.idl40]avg.pro;3
Mac: file = 'Macintosh HD:Programs:avg.pro'
Windows: file = 'd:\rsi\idl40\avg.pro'
then IDL> FDECOMP, file, disk, dir, name, qual, version
will return the following
Disk Dir Name Qual Version
Unix: '' '/rsi/idl40/' 'avg' 'pro' ''
VMS: '$1$dua5' '[RSI.IDL40]' 'avg' 'pro' '3'
Mac: 'Macintosh HD' ':Programs:' 'avg' 'pro' ''
Windows: 'd:' \rsi\idl40\ 'avg' 'pro' ''
NOTES:
(1) All tokens are removed between
1) name and qual (i.e period is removed)
2) qual and ver (i.e. VMS semicolon is removed)
(2) On VMS the filenames "MOTD" and "MOTD." are distinguished by the
fact that qual = '' for the former and qual = ' ' for the latter.
ROUTINES CALLED:
Function GETTOK(), OS_FAMILY()
Users with V4.0 or later can replace OS_FAMILY() with !VERSION.OS_FAMILY
HISTORY
version 1 D. Lindler Oct 1986
Include VMS DECNET machine name in disk W. Landsman HSTX Feb. 94
Converted to Mac IDL, I. Freedman HSTX March 1994
NAME:
file2struct
PURPOSE:
return a structure where elements are named with column headings, and
arrays are the columns
CATEGORY:
files
CALLING SEQUENCE:
IDL> struct = file2struct(filename)
INPUTS:
filename - file name with columns and, preferably, headings
KEYWORDS:
strip - if set, strip everything from column headings up to
and including the first period
FORMAT - scalar string containing a letter specifying an IDL type
for each column of data to be read. Allowed letters are
A - string data, B - byte, D - double precision, F- floating
point, I - integer, L - longword, and X - skip a column.
(G & E equate to F)
Columns without a specified format are assumed to be floating
point. Examples of valid values of FMT are
'A,B,I' ;First column to read as 6 character string, then
1 column of byte data, 1 column integer data. 'V' for LONG64
'L,L,L,L' ;Four columns will be read as longword arrays.
' ' ;All columns are floating point
If a FORMAT keyword string is not supplied, then all columns are
assumed to be floating point.
SILENT - Normally, READCOL will display each line that it skips over.
If SILENT is set and non-zero then these messages will be
suppressed.
DEBUG - If this keyword is non-zero, then additional information is
printed as READCOL attempts to read and interpret the file.
nSkip - Scalar specifying number of lines to skip at the top of file
before reading. Default is to start at the first line.
Headings for the columns (the last line skipped) will be the tags
in the structures.
COMMENT - skip if a line begins with this
NUMLINE - Scalar specifying number of lines in the file to read.
Default is to read the entire file
LINESSKIPPED - Ascii array of lines skipped
TABDELIM - If set, then assume columns are delimitted by tabs
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
struct - structure containing the filename and a tag for each column
EXAMPLES:
IDL> struct = file2struct( '/u/bdavis/Blobs/readtest.txt', nskip=1, /strip, $
FORMAT='I,F,F,F,F,F,I,F,F,F,I,F,I,F,F,F,F,F,I,F,F,F,F,F,F,F,F,F,F,F,F,F' )
IDL> loadblobs,t1=0.18,t2=0.35, dbout='/u/bdavis/Blobs/blobs141751.txt', $
'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141751.cin'
IDL> struct = file2struct( '/u/bdavis/Blobs/blobs141751.txt', nskip=3, $
FORMAT='I,F,F,F,F,F,I,F,F,F,I,F,I,F,F,F,F,F,I,F,F,F,F,F,F,F,F,F,F,F,F,F' )
REVISION HISTORY:
03-Jul-2012 take the last non-blank line at the top for the column
headings & tag names
WRITTEN 02-May-2012 by Bill Davis for Ahmed Diallo
NAME:
findcamfiles
PURPOSE:
Find camera files in various directories Environmental/System
variable FC_DATA_DIR will be used, if set, to look for files
containing the string in 'filename'
CATEGORY:
Files
CALLING SEQUENCE:
IDL> paths = findcamfiles(shotstr)
INPUTS:
shotstr = anything, but usually a shot number. If not present,
a dialog box will pop up.
KEYWORD PARAMETERS:
dirs - directories to search. If not set, the known NSTX camera
directories will be searched.
defPath - path to find most recent "*.cin" file for default selection
first - if set, will just return the first match (for speed)
pick - if set, and more than one match found, will pop a dialog
box for user to pick one.
noPick - Do not offer dialog box, even if no file found
CASE_SENSITIVE - if not set, search will be case insensitive.
subDirectories - if NOT set, WILL search subdirectories
camera - optional input, if you want cameras with file names including "_n_"
SANfaster - if file is on both /p/nstxcamera and /p/nstxcam, just
offer /p/nstxcam
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
paths = paths of files matching input in directories searched
EXAMPLE:
IDL> print, findcamfiles( '*miro*134180' )
IDL> print, findcamfiles( 142000 )
IDL> print, findcamfiles( 'nstx_5_139442' )
NOTES:
if file is on both /p/nstxcamera and /p/nstxcam, in 2010, /p/nstxcam
was much faster. if this is not true, set keyword SANfaster to 0.
MODIFICATION HISTORY:
10-Jan-2014 fix bug when shot not specified
27-Feb-2013 - don't modify camera input string
20-Sep-2012 fixed bug when shotstr_in just a shot number
10-Sep-2012 - Account for data to be read via MDSplus at MIT for CMOD.
if shot is > 9, no directory info included, and file not
if the current directory, then get from tree at MIT
08-Dec-2011 added camera keyword
25-Jul-2011 don't overwrite shotstr input
08-Dec-2010 if file is on both /p/nstxcamera and /p/nstxcam, in 2010,
/p/nstxcam was much faster, so just offer it.
03-Nov-2010 mods for running on a PC or Mac.
07-Oct-2010 fixed a bug finding old files, when search string not found in last dir
16-Jul-2010 added ext keyword, and default to "cin*" so .txt files, etc. don't show
19-Jan-2010 use getcamdirs() so list of NSTX dirs is in one place.
Assuming FILE_SEARCH will include subdirectories if 2 arguments used
(this didn't always work in some testing)
14-Jan-2010 if no files in the default directory, back up a year and check
06-Nov-2009 Default to case-insensitive searches.
21-Jul-2009 added other areas (this will probably be pretty slow)
06-Jul-2009 Written by Bill Davis, PPPL
NAME:
getNextFile
PURPOSE:
get next file in a directory, defaulting to alphabetic search
CATEGORY:
Files
CALLING SEQUENCE:
IDL> nextFile = getNextFile( inFile )
INPUTS:
input = filename with or without directory prefix
KEYWORD PARAMETERS:
numeric - if set will try to sort files numerically, so *_9.ext will
come before *_10.ext
back - if set will go back one in list
OUTPUTS:
nextFile out
EXAMPLE:
IDL> infile='/p/camdata/fastsoftxray/NSTX_119761/Frame_287.tif'
IDL> nextFile = GetNextFile( inFile)
IDL> infile='/p/camdata/fast_camera/shot000119681/NSTX000119681_35.tif'
IDL> print, GetNextFile( inFile, /numeric)
NOTES:
finds all files of the form AAAAAA_*.ext (if no "_" in file, just
return next in alphabetical order)
MODIFICATION HISTORY:
29-Jun-2006 added back keyword
20-Apr-2006 Written by Bill Davis, PPPL
NAME:
h5dfromtext
PURPOSE:
create a H5D file from a text file with columns of data
CATEGORY:
files
CALLING SEQUENCE:
IDL> h5dfromtext, in_filename=in_filename, out_filename=out_filename
KEYWORD INPUTS:
in_filename - file name with columns and, preferably, headings
out_filename - name of H5D file to write (defaults to in_filename with .H5 ext)
strip - if set, strip everything from column headings up to
and including the first period
FORMAT - scalar string containing a letter specifying an IDL type
for each column of data to be read. Allowed letters are
A - string data, B - byte, D - double precision, F- floating
point, I - integer, L - longword, and X - skip a column.
(G & E equate to F)
Columns without a specified format are assumed to be floating
point. Examples of valid values of FMT are
'A,B,I' ;First column to read as 6 character string, then
1 column of byte data, 1 column integer data. 'V' for LONG64
'L,L,L,L' ;Four columns will be read as longword arrays.
' ' ;All columns are floating point
If a FORMAT keyword string is not supplied, then all columns are
assumed to be floating point.
SILENT - Normally, READCOL will display each line that it skips over.
If SILENT is set and non-zero then these messages will be
suppressed.
DEBUG - If this keyword is non-zero, then additional information is
printed as READCOL attempts to read and interpret the file.
nSkip - Scalar specifying number of lines to skip at the top of file
before reading. Default is to start at the first line.
COMMENT - skip if a line begins with this
NUMLINE - Scalar specifying number of lines in the file to read.
Default is to read the entire file
LINESSKIPPED - Ascii array of lines skipped
TABDELIM - If set, then assume columns are delimitted by tabs
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
status
(file written)
EXAMPLES:
IDL> h5dfromtext, in_filename='/u/bdavis/Blobs/readtest.txt', nskip=1, /strip, $
FORMAT='I,F,F,F,F,F,I,F,F,F,I,F,I,F,F,F,F,F,I,F,F,F,F,F,F,F,F,F,F,F,F,F'
REVISION HISTORY:
WRITTEN 02-May-2012 by Bill Davis for Ahmed Diall0
NAME:
mkdatedir
PURPOSE:
Make a directory of the form YYYYMMDD (if it doesnt't exist)
and move files there if the files were last modified on that date.
CATEGORY:
Files, Dates
CALLING SEQUENCE:
IDL> mkdatedir, path=path, prefix=prefix, ext=ext, date=date
INPUTS:
none
KEYWORD PARAMETERS:
PATH - directory
PREFIX - file prefix for deletion
EXT - file extension for deletion; file search will be path+prefix+'*.'+ext
DATE - date for search, of form yyyymmdd, e.g., 20050617 (default=TODAY)
ALL - if set, all files will be moved to the right directory (overrides DATE)
VERBOSE - if set, will print informational output
OUTPUTS:
none
LIMITATIONS
Only works on Unix/Linux
MODIFICATION HISTORY:
03-Feb-2015 changed SpecFit directory so search doesn't get bogged down
07-Mar-2007 Added keyword all
22-Aug-2005 Written by Bill Davis, PPPL
NAME:
mk_filename
PURPOSE:
File names with system independent symbolic directories.
CATEGORY:
Files, OS Specific, File I/O
CALLING SEQUENCE:
f = mk_filename(symdir, name)
INPUTS:
symdir = symbolic directory name. in
name = file name. in
KEYWORD PARAMETERS:
Keywords:
/NOSYM means directory given is not a symbolic name.
OPSYS=os specifiy operating system to over-ride
actual. Use VMS, WINDOWS, or MACOS. UNIX is default.
SUBDIR=s Subdirectory below the symdir, e.g., SUBDIR='dir1/dir2'
DELIM=c delimiter character between directory and
file name. This is returned.
OUTPUTS:
f = file name including directory. out
COMMON BLOCKS:
NOTES:
Notes: symdir is a logical name for VMS and
an environmental variable for UNIX and WINDOWS. Ex:
DEFINE IDL_IDLUSR d0:[publib.idl] for VMS
set IDL_IDLUSR=c:\IDL\LIB\IDLUSR for WINDOWS.
setenv IDL_IDLUSR /usr/pub/idl for UNIX.
Then in IDL: f=mk_filename('IDL_IDLUSR','tmp.tmp')
will be the name of the file tmp.tmp in IDL_IDLUSR.
MODIFICATION HISTORY:
R. Sterner, 4 Feb, 1991
R. Sterner, 27 Mar, 1991 --- added /NOSYM
R. Sterner, 21 May, 1991 --- If not a listed opsys assume unix.
R. Sterner, 4 Jun, 1991 --- added DOS.
R. Sterner, 2 Jul, 1991 --- added DELIM.
R. Sterner, 17 Jan, 1992 --- added OPSYS= and avoided double //
R. Sterner, 1994 Feb 7 --- Added MacOS.
R. Sterner, 1994 Feb 14 --- Changed DOS to windows.
B. Davis - nenamed from filename.pro. Added SUBDIR keyword
Copyright (C) 1991, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
mvshotrangedir
PURPOSE:
Put files fitting a certain partern into a sub-directory of the form nnnn00s,
where nnnn00 represents a shot range,
e.g., 114100s whould contain shots 114100-114199.
CATEGORY:
Files, Dates
CALLING SEQUENCE:
IDL> mvshotrangedir, path=path, prefix=prefix, ext=ext, date=date
INPUTS:
none
KEYWORD PARAMETERS:
path - directory
prefix - file prefix for deletion
ext - file extension for deletion; file search will be path+prefix+'*.'+ext
verbose - if set, will print informational output
OUTPUTS:
none
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> mvshotrangedir,/verb
IDL> for i=1408, 1420 do mvshotrangedir, fourDigits=strtrim(i), /verb
NOTES:
LIMITATIONS
Only works on Unix/Linux
MODIFICATION HISTORY:
03-Feb-2015 changed SpecFit directory so search doesn't get bogged down
21-Oct-2010 made work
23-May-2006 do all files in dir
15-May-2006 Written by Bill Davis, PPPL
NAME:
NUMLINES
PURPOSE:
Return the number of lines in a file
CATEGORY:
Files
CALLING SEQUENCE:
nl = NUMLINES( filename )
INPUT:
filename = name of file, scalar string
OUTPUT:
nl = number of lines in the file, scalar longword
Set to -1 if the number of lines could not be determined
METHOD:
If Unix then spawn to wc; otherwise read 1 line at a time and count
PROCEDURE CALLS:
OS_FAMILY() - Determine if a unix system; Users with IDL V4.0 or later
can replace this with !VERSION.OS_FAMILY
MODIFICATION HISTORY:
22-May-2015 BD handle 0 length (because saved from mac)
07-Oct-98 BD Added StopOnError Keyword
in unix, handle stuff printed from .cshrc when spawning wc
W. Landsman February 1996
NAME:
read_array
PURPOSE:
Read a numeric array (1-D) from a text file
CATEGORY:
Files
CALLING SEQUENCE:
IDL> num_array = read_array(filename)
INPUTS:
filename = name of file containing lines of ascii data.
KEYWORD PARAMETERS:
nskip - number of lines to skip before reading
status - odd, if OK
OUTPUTS:
num_array = returned array of floating point values
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> num_array = read_array( filename )
NOTES:;
MODIFICATION HISTORY:
01-Aug-2008 Written by Bill Davis, PPPL
NAME:
READCOL
PURPOSE:
Read a free-format ASCII data file with columns of data into IDL
variables. Lines of data not meeting the specified format (e.g.
comments) are ignored. Columns may be separated by commas or spaces.
Use READFMT to read a fixed-format ASCII file. Use RDFLOAT for
much faster I/O (but less flexibility).
CATEGORY:
Files
CALLING SEQUENCE:
READCOL, name, v1 [, v2, v3, v4, v5, ... v25 , status=status, $
FORMAT = , /DEBUG , /SILENT , nSkip = , NUMLINE =, comment= ]
INPUTS:
NAME - Name of ASCII data file, scalar string. In VMS, an extension of
.DAT is assumed, if not supplied.
OPTIONAL INPUT KEYWORDS:
FORMAT - scalar string containing a letter specifying an IDL type
for each column of data to be read. Allowed letters are
A - string data,
B - byte,
D - double precision,
F- floating point,
I - integer,
L - longword, and
X - skip a column.
(G & E equate to F)
Columns without a specified format are assumed to be floating
point. Examples of valid values of FMT are
'A,B,I' ;First column to read as 6 character string, then
1 column of byte data, 1 column integer data. 'V' for LONG64
'L,L,L,L' ;Four columns will be read as longword arrays.
' ' ;All columns are floating point
If a FORMAT keyword string is not supplied, then all columns are
assumed to be floating point.
SILENT - Normally, READCOL will display each line that it skips over.
If SILENT is set and non-zero then these messages will be
suppressed.
DEBUG - If this keyword is non-zero, then additional information is
printed as READCOL attempts to read and interpret the file.
nSkip - Scalar specifying number of lines to skip at the top of file
before reading. Default is to start at the first line.
COMMENT - skip if a line begins with this
NUMLINE - Scalar specifying number of lines in the file to read.
Default is to read the entire file
LINESSKIPPED - Ascii array of lines skipped
TABDELIM - If set, then assume columns are delimitted by tabs
DELIM - e.g., ",". There can then be blanks within fields
OUTPUTS:
V1,V2,V3,...V15 - IDL vectors to contain columns of data.
Up to 25 columns may be read. The type of the output vectors
are as specified by FORMAT.
EXAMPLES:
Each row in a file POSITION.DAT contains a star name and 6 columns
of data giving an RA and Dec in sexigesimal format. Read into IDL
variables. (NOTE: The star names must not contain internal spaces.)
IDL> FMT = 'A,I,I,F,I,I,F'
IDL> READCOL,'POSITION',F=FMT,name,hr,min,sec,deg,dmin,dsec
The HR,MIN,DEG, and DMIN variables will be integer vectors.
Alternatively, all except the first column could be specified as
floating point.
IDL> READCOL,'POSITION',F='A',name,hr,min,sec,deg,dmin,dsec
To read just the variables HR,MIN,SEC
IDL> READCOL,'POSITION',F='X,I,I,F',HR,MIN,SEC
RESTRICTIONS:
This procedure is designed for generality and not for speed.
If a large ASCII file is to be read repeatedly, it may be worth
writing a specialized reader.
Columns to be read as strings must not contain spaces or commas,
since these are interpreted as column delimiters.
(UNLESS /TABDELIM is used). Use READFMT to read such files.
Numeric values are converted to specified format. For example,
the value 0.13 read with an 'I' format will be converted to 0.
When DELIM specified (and not blank), first all blanks are replaced
with |b, then delimiter characters within quoted strings are replaced
with a backtick. After the columns are parsed and put into variables,
the proper characters are put back in.
PROCEDURES CALLED
GETTOK(), NUMLINES(), REPCHR(), STRNUMBER(), ZPARCHECK
REVISION HISTORY:
20-Feb-2014 added ReplaceTab keyword for when file is tab delimited
and has @'s in it.
21-Nov-2013 added DELIM keyword. This is especially for columns with
spaces in cells. Ignore delimiters within quoted strings.
14-Apr-2010 added datatype 'V' for LONG64
16-Oct-2008 added status keyword
24-Aug-99 Added LINESSKIPPED keyword
10/99 Added TABDELIM keyword [Bill Davis]
Written W. Landsman November, 1988
Modified J. Bloch June, 1991
(Fixed problem with over allocation of logical units.)
Added nSkip and NUMLINE keywords W. Landsman March 92
Read a maximum of 25 cols. Joan Isensee, Hughes STX Corp., 15-SEP-93.
Call NUMLINES() function W. Lansdman Feb. 1996
NAME:
read_floats
PURPOSE:
Read a list from a text file and return a floating-point array
CATEGORY:
Files
CALLING SEQUENCE:
IDL> floats = read_floats(filename)
INPUTS:
filename = name of file containing lines of ascii data.
KEYWORD PARAMETERS:
HLP - When set, help information is printed.
nskip - lines to skip
status - if even, then read was successful
OUTPUTS:
floats = returned array of floats - 1 per line out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> floats = read_floats( 'hans.txt', maxlines=500000 )
NOTES:
MODIFICATION HISTORY:
26-Sep-2008 Written by Bill Davis, PPPL
NAME:
read_generic
PURPOSE:
read an image from a variety of types of files
CATEGORY:
Files, Graphics
CALLING SEQUENCE:
IDL> data2D = read_generic( filename )
INPUTS:
filename - file name to read in
can be type 'jpg','tif','tif','bmp','jpeg,'png', 'ppm', 'pgm', or 'gif'
KEYWORD PARAMETERS:
Optional output:
extension - the file extension, eg., 'jpg'
inDim - for .raww files, specify x & y dimensions (Default to [256,128])
nBytesPer- for .raww files, specify number of bytes per data point (Default=2)
center - if set, will only return center columns (1/2 of data)
OUTPUTS:
2-D data array from file out
COMMON BLOCKS:
NONE
MODIFICATION HISTORY:
17-Jul-2013 return bad status if fails in read_image
15-Apr-2009 added support for .raww type (from Photron cameras)
30-Sep-2008 added channel keyword
25-Apr-2007 added colortable keyword
21-Feb-2007 added ppm file type
19-Apr-2006 replaced keywords with args R,G,B
15-Oct-2004 Written by Bill Davis, PPPL
NAME:
READ_LIST
PURPOSE:
Read a list from a text file and return a string array.
Will ignore lines beginning with a semicolon, but will
will return blank lines.
CATEGORY:
Files
CALLING SEQUENCE:
IDL> str_array = READ_LIST(filename)
INPUTS:
filename = name of file containing lines of ascii data.
KEYWORD PARAMETERS:
HLP - When set, help information is printed.
nskip - lines to skip
status - if even, then read was successful
OUTPUTS:
str_array = returned array of strings - 1 per line out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> str_array = READ_LIST( filename )
NOTES:
MODIFICATION HISTORY:
16-Aug-2008 added skipChar keyword
01-Aug-2008 added nskip keyword
13-Apr-2007 added status keyword
11-Apr-06 added maxlines keyword [BD]
1-Apr-99 Written by Bill Davis, PPPL
NAME:
readnetcdfblobs
PURPOSE:
Read NetCDF files of dummy Blob data for code validation.
the files can be generated with gennetcdfblobs.
CATEGORY:
files, Fast Cameras
CALLING SEQUENCE:
IDL> img = readnetcdfblobs(filename, framenumber, times=times)
EXAMPLE:
IDL> img = readnetcdfblobs('circoneup_1.nc', 1)
IDL> dum=readnetcdfblobs('circmany_3.nc', 1, xvel=xvel, yvel=yvel)
IDL> print, xvel[0], yvel[0]
see ncdf_cat.pro for example of reading netcdf files.
MODIFICATION HISTORY:
WRITTEN 31-Oct-2013 by Bill Davis, PPPL, for Stewart Zweben
NAME:
read_numbers
PURPOSE:
Read a numeric array (1-D) from a text file
CATEGORY:
Files
CALLING SEQUENCE:
IDL> num_array = read_numbers(filename)
INPUTS:
filename = name of file containing lines of ascii data.
KEYWORD PARAMETERS:
nskip - number of lines to skip before reading
status - odd, if OK
OUTPUTS:
num_array = returned array of floating point values
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> num_array = read_numbers( filename )
NOTES:;
MODIFICATION HISTORY:
28-Feb-2002 Written by Bill Davis, PPPL
NAME:
READ_QUOTED
PURPOSE:
Reads a file and returns anything between first two quotes.
CATEGORY:
Files
CALLING SEQUENCE:
IDL> comments = READ_QUOTED(filename)
INPUT:
filename - e.g., "waveform.DAT"
RETURNED:
comments - string array with dimension = # of lines read (& not skipped)
KEYWORDS
delim - quote character, defaults to "
nskip - number of lines to skip before reading
RETURNED:
strings - string array
MODIFICATION HISTORY:
16-Aug-2008 added skipChar & status keywords
26-Aug-00 WMD Written
NAME:
read_table
PURPOSE:
Reads a table file, like from a spreadsheet.
CATEGORY:
files
CALLING SEQUENCE:
IDL> data2d = read_table( filename, nskip=nskip, header=header )
INPUT:
filename - e.g., "AMP.DAT"
OPTIONAL INPUT:
nskip - number of lines to skip before reading (will be returned in header)
nCols - # of data values per line
maxLines - default=1,000,000
delim - if not tab-delimited, set this to ' '
OPTIONAL OUTPUT:
strings - if set, returns a string array, rather than floats
RETURNED:
Data_2D - nCols x N array
EXAMPLE:
IDL> data2d=read_table('/u/bdavis/StrachanDB/HiRadEnergyBal.txt', nskip=1, $
header=header, /strings )
LIMITATIONS:
Can't handle blanks in fields
WRITTEN 25-Feb-2011 by Bill Davis for Jim Strachan
NAME:
rmfilesbydate
PURPOSE:
Remove files not modified since a certain date
CATEGORY:
Files, Dates
CALLING SEQUENCE:
IDL> rmfilesbydate, path=path, prefix=prefix, ext=ext, date=date
INPUTS:
none
KEYWORD PARAMETERS:
path - directory
prefix - file prefix for deletion
ext - file extension for deletion; file search will be path+prefix+'*.'+ext
date - date for search, of form yyyymmdd, e.g., 20050617 (default=TODAY)
daysbefore - optional additional number of days before date
verbose - if set, will print informational output
justprint - if set, will not remove files
OUTPUTS:
none
COMMON BLOCKS:
NONE
EXAMPLE:
IDL>
NOTES:
for safety, on Unix, you may wish to create a ~/Trash directory
and alias rm to
/bin/mv !* ~/Trash
LIMITATIONS
MODIFICATION HISTORY:
22-Aug-2005 Written by Bill Davis, PPPL
NAME:
SPEC_DIR
PURPOSE:
Provide a complete file specification by appending a default disk
or directory if necessary.
CATEGORY:
Files, OS Specific, Strings
CALLING SEQUENCE:
File_spec = SPEC_DIR( filename, [ extension ] )
INPUT:
filename - character string giving partial specification of a file
name. Examples for different operating systems include the
following:
VMS: '$1$DUA5:TEST.DAT','[.SUB]TEST'
Unix: pro/test.dat, $IDL_HOME/test
MacOS: ':Programs:test'
Windows: '\pro\test.dat','d:\pro\test'
OPTIONAL INPUT:
exten - string giving a default file name extension to be used if
filename does not contain one. Do not include the period.
OUTPUT:
File_spec - Complete file specification using default disk or
directory when necessary.
EXAMPLE:
IDL> a = spec_dir('test','dat')
is equivalent to the commands
IDL> cd, current=cdir
IDL> a = cdir + delim + 'test.dat'
where delim is the OS-dependent separator
METHOD:
SPEC_DIR() decomposes the file name using FDECOMP, and appends the
default directory (obtained from the CD command) if necessary.
Under VMS, SPEC_DIR() will also try to translate disk and directory
logical names.
SPEC_DIR() does not check whether the constructed file name actually
exists.
PROCEDURES CALLED:
FDECOMP, OS_FAMILY()
REVISION HISTORY:
Written W. Landsman STX July, 1987
Added Unix compatibility, W. Landsman, STX August 1991
Added Windows and Macintosh compatibility W. Landsman September 1995
NAME:
write_generic
PURPOSE:
write an image to the appropriate type of file, based on
file extension
CATEGORY:
Files, Graphics
CALLING SEQUENCE:
IDL> write_generic, filename, data2D [, R,G,B]
INPUTS:
filename - file name to read in
can be type 'jpg','tif','tif','bmp','jpeg,'png', 'ppm', 'pgm', or 'gif'
KEYWORD PARAMETERS:
Optional inputs:
extension - the file extension, eg., 'jpg'
quality - jpeg quality [0-100, default is 75]
order - JPEG/JFIF images are normally written in top-to-bottom order.
If the image array is in the standard IDL order (i.e., from
bottom-to-top) set ORDER to 0, its default value. If the image
array is in top-to-bottom order, ORDER must be set to 1.
OUTPUTS:
2-D data array from file out
COMMON BLOCKS:
NONE
MODIFICATION HISTORY:
25-Feb-2009 added RGB keyword
18-Oct-2007 added quality keyword
25-Apr-2007 added colortable keyword (not used!?!)
21-Feb-2007 added ppm file type
19-Apr-2006 replaced keywords with args R,G,B
15-Oct-2004 Written by Bill Davis, PPPL
NAME:
write_text
PURPOSE:
Write data to a text file
CATEGORY:
files
CALLING SEQUENCE:
IDL> write_text, filename, data, data2, data3, data4, data5, data6
INPUTS:
filename - filename for output (DEFAULT='outfile.txt')
data - array of numbers
data2, data3, etc., are optional.
KEYWORD PARAMETERS:
header - text lines to put at the beginning of file
tabs - if set, columns will be delimited by a tab characater
verbose - if set, will echo message to screen with print command
OUTPUTS:
none
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> write_text, 'myfilename.txt', findgen(100)
to write two columns with 1 header line:
IDL> write_text, 'myfilename.txt', time, data, header='Hello World!'
NOTES:
MODIFICATION HISTORY:
24-Apr-2009 option to write up to 6 columns of data
12-Jun-2008 Written by Bill Davis, PPPL
Category: GAplot
[List of Routines]
NAME: GA_Data PURPOSE: A GA_Data object defines a dataset Y as a function of X. It can be drawn on a Plot defined by a GA_Plot object. CATEGORY: GAplot SUPERCLASSES: SUBCLASSES: GA_Data3 GA_DataV CREATION: See GA_Data::Init
NAME: GA_Data::GetXRange PURPOSE: Retrieves the range of X data. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetXRange() ARGUMENTS: KEYWORDS:
NAME: GA_Data::GetYRange PURPOSE: Retrieves the range of Y data. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetYRange([XRANGE]) ARGUMENTS: XRANGE Returns Y range only for data points within XRANGE. KEYWORDS: ERRORBAR Set to retrieve Y range with errorbars included.
NAME: GA_Data::SetProperty PURPOSE: Sets the value of a property or group of properties for the GA_Data. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Data:]SetProperty ARGUMENTS: KEYWORDS: Any keyword to GA_Data::Init followed by "Set". In addition, HIDE Set to hide this data set in Plot. PROPERTIES3D SELECTEDPOINT Index of selected data point. STATUS XDATA A vector argument to replace abscissa data X. YDATA A vector argument to replace ordinate data Y. fitDegree Degree of fit to display with data. 0=none, 1=linear, 2=quadratic, 3=cubic fitThruZero if=1 then fit forced to go through zero MODIFICATION HISTORY 11-Mar-2005 Added fitDegree and fitThruZero keywords
NAME: GA_Data::GetXName PURPOSE: Retrieves the name of X vector. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetXName() ARGUMENTS: KEYWORDS:
NAME: GA_Data::GetFlagAutoLabel PURPOSE: Retrieves value of FlagAutoLabel CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetFlagAutoLabel() ARGUMENTS: KEYWORDS:
NAME: GA_Data::GetYName PURPOSE: Retrieves the name of Y vector. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetYName() ARGUMENTS: KEYWORDS:
NAME: GA_Data::GetLabel PURPOSE: Retrieves the label of this dataset. If not set, use YName. Can be overridden by subclasses to supply automatically generated label. FlagAutoLabel is provided to facilitate this. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetLabel() ARGUMENTS: KEYWORDS:
NAME: GA_Data::GetXData PURPOSE: Retrieves abscissa vector X. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetXData() ARGUMENTS: KEYWORDS: MARKER >0, returns X values of marked data points. <0, returns X values of unmarked data points. RESAMPLE Set to resample data before returning X. Data is resampled to the maximum number of data points specified by member maxpts.
NAME: GA_Data::GetYData PURPOSE: Retrieves ordinate vector Y. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetYData() ARGUMENTS: KEYWORDS: MARKER >0, returns Y values of marked data points. <0, returns Y values of unmarked data points. RESAMPLE Set to resample data before returning Y. Data is resampled to the maxmum number of data points specified by member maxpts. ERRORBAR A vector of same size of Y vector. Returns Y + ERRORBAR/2.
NAME: GA_Data::GetColor PURPOSE: Retrieves the color index associated with this data set. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetColor() ARGUMENTS: KEYWORDS:
NAME: GA_Data::GetSymbol CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetSymbol()
NAME: GA_Data::GetSymbolSize CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetSymbolSize()
NAME: GA_Data::GetLineStyle CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetLineStyle()
NAME: GA_Data::GetLineStyleNone PURPOSE: Retrieves linestyle index for 'NONE' (no line). CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetLineStyleNone()
NAME: GA_Data::GetPlot PURPOSE: Retrieves the GA_Plot object that contains this data object. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Data::]GetPlot()
NAME: GA_Data::Draw PURPOSE: Overplots this data set onto a Plot that has been established by a GA_Plot object. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Data::]Draw ARGUMENTS: KEYWORDS: DRAGOFFSET ERASE
NAME: GA_Data::Add_Text PURPOSE: Add a text annotation defined by GA_AnnotateText object that will be drawn together with this data object onto the plot object. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Data::]Add_Text(XPOS,YPOS,TEXT) ARGUMENTS: XPOS X position of the text YPOS Y position of the text TEXT a string KEYWORDS: DRAW Set to draw this data object after adding the text. USE Set to 0 to hide or 1 to display this text annotation. Default=1
NAME: GA_Data::Delete_Text PURPOSE: Deletes a text member from the data object. CATEGORY: GAplot CALLING SEQUENCE: Obj->Delete_Text,dataset ARGUMENTS: DATASET Either a text object or the index of text objects starting zero as the first one. KEYWORDS: DRAW Draw the data set upon deletion of the text object. NODESTROY Set to not destroy the text object itself, only remove from this data object. Default to destroy.
NAME: GA_Data::Set_Text_Property PURPOSE: Sets the parameters associated with a text annotation object. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Data::]Set_Text_Property [,TEXTMEMBER] ARGUMENTS: TEXTMEMBER Index number of text objects (0 being the first one). If not specified, this methon applies to all text members. KEYWORDS: DRAW Draw this data object after setting text properties. NOUSE Set to not display the text. TEXT A string to replace the text content. USE Set to display the text. All properties settable by GA_AnnotateText::SetProperty.
NAME:
GA_Data::Init
PURPOSE:
Initializes the GA_Data object.
CATEGORY:
GAplot
CALLING SEQUENCE:
Obj = OBJ_NEW('GA_Data',[X,]Y)
or
Result = Obj->[GA_Data::]Init([X,]Y) (in a subclass' Init method only)
ARGUMENTS:
X - A vector or a pointer to a vector. If not specified, Y is defined
as a function of point number starting at zero. If both arguments
are specified, Y is a function of X, and X and Y have to be of
same data type.
Y - The ordinate data or a pointer to the ordinate data.
KEYWORDS:
Properties retrieveable via GA_Data::Get{PropertyName} are
indicated by "Get" following the keyword. Properties settable via
GA_Data::SetProperty are indicated by "Set" following the keyword.
COLOR (Get,Set) The color index for plotting this data set. Default=foreground
DEBUG Set to turn on debugging.
ERRORBAR (Set) A vector of errorbar values (+- errorbar/2).
INTERPOLATE (Set) Set to set editmode to interpolate (?)
FLAGAUTOLABEL (Get,Set) Set to automatically determine label from method call.
LABEL (Get,Set) Legend label
LINESTYLE (Get,Set) The linestyle of drawing this data. Default=0 (solid line)
MARKCOLOR (Get,Set) Color index for markers
MARKER (Get,Set) Set to indicate that data points can be marked.
MARKFILL (Get,Set) Set to fill marker symbols.
MARKLABELS (Get,Set) Label used for markers.
MARKSIZE (Get,Set) Size of mark symbols.
MARKSYMBOL (Get,Set) Symbol used for markers.
PLOT (Get,Set) The GA_Plot object that contains this object.
SHIFT (Set) Set to set editmode to shift (?)
SYMBOL (Get,Set) The symbol used for this data set.
SYMFILL (Get,Set) Set this keyword to fill the symbols.
SYMFRAC (Get,Set) The fraction (0-100) of symbols to plot. Default=0.
SYMSIZE (Get,Set) The size of symbols. Default=1.
XNAME (Get,Set) A name associated with X.
XSCALE (Get,Set) Two elements arrary for X scaling. X=X*XSCALE[1]+XSCALE[0]
YNAME (Get,Set) A name associated with Y.
YSCALE (Get,Set) Two elements array for Y scaling. Y=Y*YSCALE[1]+YSCALE[0]
NAME: GA_Plot PURPOSE: A GA_Plot object draws graphs of its data members. It is a container of GA_Data objects. If it has more than one data object member, the data members are overlayed. A plot object can be thought as a wrapper to IDL's PLOT command, keyword values to the PLOT command are preserved as plot object's or data objects' members. A plot object is plotted on a window created by a GA_Plot_Window object which may contain several plot objects. CATEGORY: GAplot SUPERCLASSES: SUBCLASSES: GA_Plot3 CREATION: See GA_Plot::Init BASIC METHODS: GA_Plot::Add_Data GA_Plot::Add_Data_Object GA_Plot::Delete_Data GA_Plot::Select_Data GA_Plot::Set_Data_Property GA_Plot::Set_Plot_Property
NAME: GA_Plot::GetDataSelected PURPOSE: Retrieves the selected data object. A data object can be selected by clicking near to the data points with Left-Mouse-Button in 'Select' mode. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Plot::]GetDataSelected() KEYWORDS: INDEX A named variable to recieve the index of the selected data object
NAME: GA_Plot::Select_Data PURPOSE: This method retrieves a particular data object associated with this plot object. A data can be selected by name or by index number. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Plot::]Select_Data([DATASET]) ARGUMENTS: DATASET A string specifying the name of the data object, or an integer specifying the index number, 0 being the 1st one.
NAME: GA_Plot::Set_Data_Property PURPOSE: This method allows you to change the parameters associated with a particular data object. You must specify a particular data set by passing the object reference to the data set. (This can be obtained with the GA_Plot::Select_Data method.) If a data set object is not specified as the data member, the first data set is used by default. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot::]Set_Data_Property [,DATAMEMBER] ARGUMENTS: DATAMEMBER A GA_Data object associated with this plot object. KEYWORDS: Any keywords acceptable to GA_Data::SetProperty, and AUTORANGE Set to reset the data range automatically. DRAW Set to re-draw all datasets. EXAMPLES: oPlot->Set_Data_Property,oPlot->Select_Data(1),XData=x,Ydata=y This resets X and Y vectors for the 2nd dataset in the oPlot object.
NAME: GA_Plot::Get_Data_Property PURPOSE: This method allows you to retrieve the properties of a data member belonging to the plot. Data member is identified by passing its object reference (which can be obtained with the Select_Data method). If a data member is not specified, the first data memeber is used as a default. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot::]Get_Data_Property [,DATAMEMBER] ARGUMENTS: DATAMEMBER A GA_Data object associated with this plot object. KEYWORDS: Keywords are named variables to receive retrieved values. At least one keyword should be provided. COLOR The color index of the data member. LINESTYLE The linestyle of the data member. MARKER Used together with XDATA and/or YDATA. >0 for marked data points, <0 for unmarked data points. SYMBOL SYMFILL SYMFRAC SYMSIZE XNAME XDATA Abscissa vector X of the data member. YNAME YDATA Ordinate vector Y of the data member. EXAMPLE: oPlot->Get_Data_Property,oPlot->Select_Data(1),XData=xdata,Marker=-1 This retrives X values of the unmarked data points from the 2nd data member of this plot and stores the result in variable xdata.
NAME: GA_Plot::Add_Data_Object PURPOSE: This method allows you to add a GA_DATA or GA_DATA3 object to the plot object. The data object reference is returned. See also GA_Plot::Add_Data CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Plot::]Add_Data_Object, NEWDATA ARGUMENTS: NEWDATA A GA_Data(3) object to be added. KEYWORDS: DRAW Set to re-draw all datasets. NOAUTORANGE Set to not reset the data range automatically.
NAME: GA_Plot::Add_Data PURPOSE: This method allows you to add another data object to the plot object. Properties of the data object may be set with the method's keywords. Extra carries any keywords acceptable by Ga_Data[3]::Init. A new data object will be created and the reference is returned. See also GA_Plot::Add_Data_Object CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->Add_Data([XDATA,] YDATA [,ZDATA]]) ARGUMENTS: XDATA X vector. If not specified, X will set to a point number array starting at zero. YDATA Y vector as a function of X if ZDATA is not specified. If ZDATA is specified, YDATA is the 2nd independent data. ZDATA A two dimensional array as a function of X and Y. If ZDATA is specified, a GA_Data3 will be created. See GA_Data::Init and GA_Data3::Init for acceptable inputs. KEYWORDS: Any keywords acceptable to GA_Data::Init or GA_Data3::Init, and DRAW Set to re-draw all datasets. NOAUTORANGE Set to not reset data ranges automatically. HISTORY: 07-10-2002 Q.Peng - This method shouldn't have worked for adding a GA_Data3 (with XDATA,YDATA,ZDATA) before. The order of arguments has just been corrected.
NAME: GA_Plot::Delete_Data PURPOSE: This method allows you to delete a data set member from the Plot Object. The data set may be specified by indicating its NAME, by indicating its POSITION (index number), or by the data OBJECT itself. (See the Select_Data method for more details about a data set's NAME and POSITION.) CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot::]Delete_Data, DATASET ARGUMENTS: DATASET A string for its name, or an integer for its position (0 being the 1st), or a GA_Data object reference. KEYWORDS: DRAW Set to re-draw all datasets. NOAUTORANGE Set to not reset data ranges automatically. NODESTROY Set to not destroy the deleted data object.
NAME: GA_Plot::Auto_Range PURPOSE: Set data ranges automatically according to data. This is needed for multiple data sets. Set both xrange and yrange by default. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot::]Auto_Range KEYWORDS: OVERRIDE Set to ALWAYS autoscale both MIN and MAX regardless of the settings of xautorange and yautorange XONLY Set to only autoscale X range. YONLY Set to only autoscale Y range. ZONLY Set to only autoscale Z range.
NAME: GA_Plot::Add_Text PURPOSE: This method adds a text annotation to a specified location on the plot. CATEGORY: GAplot CALLING SEQUENCE: Obj->Add_Text, XPOS, YPOS, TEXT ARGUMENTS: XPOS X coordinate of the text. YPOS Y coordinate of the text. TEXT A string. KEYWORDS: Any keywords acceptable to GA_AnnotateText::Init, and DRAW Set to re-draw all datasets. USE 1 - display the text (default), 0 - do not display the text.
NAME: GA_Plot::Set_Text_Property PURPOSE: This method allows you to change the parameters associated with a text annotaion object. The textMember is the index number of the text object. All text members are used by default if no textMember is specified. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot::]Set_Text_Property [,TEXTMEMBER] ARGUMENTS: TEXTMEMBER An integer specifying the index number of the text memeber. 0 is the 1st text. If not specified, all texts are used. KEYWORDS: DRAW Set to re-draw all datasets. NOUSE Set to not display the text in the plot. TEXT A string to replace the text value. USE Set to display the text in the plot. Any keywords acceptable by GA_AnnotateText::SetProperty
NAME: GA_Plot::Draw PURPOSE: This method draws the Plot Object, including all of the data members included in the Plot Object. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot::]Draw KEYWORDS: NODATA If set, only the plot axes and annotation are drawn. NOERASE keyword to PLOT.
NAME: GA_Plot::SetSliceMode PURPOSE: Set mode for data slicing. For a GA_Plot object, the plot can be used as a slicer to slice through other GA_Plot3 objects in the same window. The data in this plot will not be sliced because there is no third dimension. See also GA_Plot3::SetSliceMode CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot::]SetSliceMode, MODE ARGUMENTS: MODE 'A' - Can be used to slice through the 1st dimension of a GA_Plot3 object with slicemode 'AB', or the 2nd dimension of a GA_Plot3 object with slicemode 'BA'. 'B' - Can be used to slice through the 2nd dimension of a GA_Plot3 object with slicemode 'AB', or the 2nd dimension of a GA_Plot3 object with slicemode 'AB'. 'X' - Not a slicer. In 'Slice' mode, when cursor moves into this plot, nothing happens.
NAME: GA_Plot::Set_Plot_Property PURPOSE: This method allows you to set the standard Plot properties. If the DRAW keyword is set, the plot will be drawn after the new properties are set. (See the Init Method for a more complete explanation of these Plot properties.) CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot::]Set_Plot_Property KEYWORDS: Any keywords to GA_Plot::Init followed by "Set", and DRAW LCHARSIZE NOXTICKS SETXRANGE SETYRANGE XAUTORANGE YAUTORANGE WINDOW
NAME: GA_Plot::Get_Plot_Property PURPOSE: This method allows you to obtain the standard Plot properties from the Plot Object. (See the Init Method for a more complete explanation of these Plot properties.) CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot::]Get_Plot_Property KEYWORDS: Keywords are named variables to receive retrieved values. Any keywords to GA_Plot::Init followed by "Get", and NUMDATASETS NUMTEXT LCHARSIZE NOXTICKS SETXRANGE SETYRANGE XAXIS XAUTORANGE YAXIS YAUTORANGE
NAME: GA_Plot::GetWindow PURPOSE: This method returns the GA_Plot_Window object that the plot object belongs to, for EditCallBack purpose. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Plot::]GetWindow()
NAME: GA_Plot::GetDataObjects PURPOSE: The method returns the array of data objects stored in this plot object. CATEGORY: GAplot CALLING SEQUENCE: Results = Obj->[GA_Plot::]GetDataObjects()
NAME:
GA_Plot::Init
PURPOSE:
This method initializes a GA_Plot object. Standard properties
are set with positional and keyword parameters. The routine makes
GA_DATA objects from the data passed into the method. Use the
Add_Data method to add additional data sets and the Delete_Data
method to remove data sets from the Plot Object. Data inside the
data objects can be modified with the Set_Data_Property method.
Think of this initialization routine as a wrapper for the PLOT
command. Use keywords appropriate for the PLOT command
in making the call.
CATEGORY:
GAplot
CALLING SEQUENCE:
Obj = OBJ_NEW('GA_Plot'[,X [,Y]])
or
Result = Obj->[GA_Plot::]Init([X [,Y]]) (in a subclass' Init method only)
ARGUMENTS:
X - If Y is specified, X, Y are the two arguments to GA_Data::Init
If Y is not specified, X can be a GA_Data or GA_DataV object,
or it can be the only argument to GA_Data::Init.
Y - The 2nd argument to GA_Data::Init
KEYWORDS:
Properties retrieveable via GA_Plot::Get_Plot_Property are indicated
by "Get" following the keyword. Properties settable via
GA_Plot::Set_Plot_Property are indicated by "Set".
ASPECT (Get,Set) Set to keep aspect ratio of plots.
BACKGROUND (Get,Set) The color index of background.
CHARSIZE (Get,Set) The character size for labels.
COLOR (Get,Set) The color index for axes and annotations.
CONTOUR Set to do contour plots.
DATACOLOR The color for plotting data created here.
DEBUG(Set) Set to turn on debugging.
DEP_DATA_NAME The name associated with dependent data (Y).
FLAGLEGEND (Get,Set) 0 = do not show labels, 1 = show labels
INDEP_DATA_NAME The name associated with independent data (X).
GRID (Get,Set) A two-element array (columns,rows) for the layout of all plots
in the GA_Plot_Window object to which this plot object belongs.
LEVELS The level vector for contour plot.
NAME (Get,Set) The name associated with this plot (used for plot selection).
NUMBER (Get,Set) The index number of this plot in window (starting at 0).
OVERGRIDSTYLE (Get,Set) Grid style for both X and Y axes.
OVERLAYGRID (Get,Set)
OVERLAYZERO (Get,Set)
PSYM The plot symbol used to display the data.
SLICEMODE (Get,Set)
SUBTITLE (Get,Set)
SYMFRAC The fraction (0-100) of symbols to be plotted.
SYMSIZE The plot symbol size.
TICKSOUT (Get,Set) If non 0, ticks appear on outside of the plot.
TITLE (Get,Set) The plot title.
XCHARSIZE (Get,Set)
XLOG (Get,Set)
XMTICKS (Get,Set) X minor ticks
XRANGE (Get,Set)
XSTYLE (Get,Set)
XTICKFORMAT(Set)
XTICKS (Get,Set)
XTITLE (Get,Set)
YCHARSIZE (Get,Set)
YLOG (Get,Set)
YMTICKS (Get,Set) Y minor ticks
YRANGE (Get,Set)
YSTYLE (Get,Set)
YTICKFORMAT(Set)
YTICKS (Get,Set)
YTITLE (Get,Set)
WID (Get,Set) The window index number of the window where this plot is displayed.
NAME: GA_Plot_Window PURPOSE: A GA_Plot_Window is a compound widget with a draw window that contains one or several GA_Plot[3] objects. Plots can be added or deleted. The window object handles plot layout, coordinates, preference and properties configurations, mouse events and draws all the plots through their own draw methods. CATEGORY: GAplot SUPERCLASSES: SUBCLASSES: CREATION: See GA_Plot_Window::Init BASIC METHODS: GA_Plot_Window::Add_Plot GA_Plot_Window::Delete_Plot GA_Plot_Window::SetCurrentTool GA_Plot_Window::Set_Crosshairs GA_Plot_Window::Set_Status_Window
NAME: GA_Plot_Window::RestorePreferences PURPOSE: Restore user's preferences from file specified by PreferencesFile. This file is always in user's HOME directory. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]RestorePreferences
NAME: GA_Plot_Window::SavePreferences PURPOSE: Save the current settings to user's preferences file specified by PreferencesFile. This file is always in user's HOME directory. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]SavePreferences
NAME: GA_Plot_Window::SetCharsize CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]SetCharsize, charsize
NAME: GA_Plot_Window::SetColorFlag PURPOSE: Resetting the color table. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]SetColorFlag, COLORFLAG ARGUMENTS: COLORFLAG Flag used by Color_Setup to determine the type of color table. 0 - greyscale color table, 1 - color_list() color table, 2 - black and white only. KEYWORDS: REVERSE Set to have white background. The default is with black background.
NAME: GA_Plot_Window::GetPlotList PURPOSE: Retrieves the names of plots in this window object. A name is specified or a default is given when a plot object is created. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Plot_Window::]GetPlotList()
NAME: GA_Plot_Window::GetPlot PURPOSE: Retrieves a plot object specified by its index number. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Plot_Window::]GetPlot(INDEX) ARGUMENTS: INDEX An index number of the plot object in this window. 0 = 1st plot object.
NAME: GA_Plot_Window::UserSetGrid PURPOSE: Allows manually setting the grid layout of the plots. If howeve, the total number of plots is greater than GRID[0]*GRID[1], the grid is recalculated automatically. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]UserSetGrid, GRID ARGUMENTS: GRID A two-element array specifying the layout of plots. GRID[0] = number of columns, GRID[1] = number of rows. KEYWORDS: DRAW Set to re-draw all the plots.
NAME: GA_Plot_Window::SetMaxGrid PURPOSE: Set the maximum number of columns and rows for determining grid layout of plots automatically. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]SetMaxGrid, MAXGRID ARGUMENTS: MAXGRID A two-element array. MAXGRID[0] = maxcols, MAXGRID[1] = maxrows.
NAME: GA_Plot_Window::SetAutoGrid PURPOSE: Turn on or off the automatic grid layout calculation. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]SetAutoGrid, ONOFF ARGUMENTS: ONOFF 1 - turn on auto grid, 0 - turn off auto grid. KEYWORDS: DRAW Set to re-draw all plots.
NAME: GA_Plot_Window::CheckPlotNumbers PURPOSE: Goes through member plots and checks to ensure that they are sequentially numbered. Renumbers them if they are not. Plots having the same number are overlayed and can cause confusing display results. This routine is optional - to be used by the parent application if needed. It returns 0 if no plot has been renumbered, returns 1 otherwise. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Plot_Window::]CheckPlotNumbers()
NAME: GA_Plot_Window::Replace_Plot PURPOSE: This method replaces a current plot in the window with another plot. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]Replace_Plot, OPLOT ARGUMENTS: OPLOT A replacement GA_Plot object. KEYWORDS: NUMBER The index number of the plot to be replaced. The first plot (0) is replaced if number if not specified.
NAME: GA_Plot_Window::Insert_Plot PURPOSE: Inserts a new plot at a specified index number. The plot numbers are shifted by 1 (+1) from the inserted plot. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]Insert_Plot, OPLOT, NUMBER ARGUMENTS: OPLOT A GA_Plot object to be inserted. NUMBER The index number which the new plot is inserted to. KEYWORDS: NODRAW Set to not re-draw all the plots. Useful when inserting more than one plot to complete insertion before re-draw.
NAME: GA_Plot_Window::Remove_Plot PURPOSE: If the PLOT tag in EDITFLAGS structure is set, this method deletes the plot object specified by the index number. A GA_Plot_Window::EditCallBack is generated. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]Remove_Plot ARGUMENTS: NUMBER The index number of the plot to be deleted. KEYWORDS: Any keywords acceptable by GA_Plot_Window::Delete_Plot.
NAME: GA_Plot_Window::Delete_Plot PURPOSE: This method deletes a plot from the list of plots within the window. Plots are numbered from 1 to N and are in column order in the window. NO EDITCALLBACK is generated by this method! For an EDITCALLBACK use GA_Plot_Window::RemovePlot. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]Delete_Plot, NUMBER ARGUMENTS: NUMBER The index number of the plot object to be deleted. KEYWORDS: NODRAW Set to not re-draw all plots. Useful when deleting more than one plot to complete the deletion before re-drawing what is left. NODESTROY Set to not destroy the plot object being deleted from this window. Default is to destroy the plot object.
NAME: GA_Plot_Window::Add_Plot PURPOSE: This method adds a plot to the window. A new column of plots will be created if necessary to accomodate the new plot. A plot object is required. If NoDuplicate keyword is set, check if newPlot belongs to the window already. If so, return. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]Add_Plot, NEWPLOT ARGUMENTS: NEWPLOT A GA_Plot object to be added to the window. KEYWORDS: DRAW Set to re-draw all plots. NODUPLICATE Set to make sure NEWPLOT is added to this window object only once.
NAME: GA_Plot_Window::Set_Crosshairs PURPOSE: This method turns cursor crosshair tracking on or off. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]Set_Crosshairs, ONOFF ARGUMENTS ONOFF 1 - crosshair tracking on, 0 - crosshair tracking off.
NAME: GA_Plot_Window::GetCurrentTool PURPOSE: Retrieves the name of the current mouse mode. Possible modes are ['Select','Zoom','Edit','Cursor','Slice','Mark','Vector'] plus those defined by MOUSEMODES. CATEGORY: GAplot CALLING SEQUENCE: Result = Obj->[GA_Plot_Window::]GetCurrentTool()
NAME: GA_Plot_Window::SetCurrentTool PURPOSE: This method sets the current tool(mouse mode) to be used in the window. 'SELECT' - Seleting a data or a plot for manipulation, copying and deletion, etc. 'ZOOM' - Zoom and reset a plot, switch between multiple and single-plot displays. 'EDIT' - Add, delete or move data points. 'CURSOR' - Mark reference points, switch cursor readout from absolute to relative. 'SLICE' - Change the slices of the 3D data being plotted. 'MARK' - Mark a data point with a special symbol. 'VECTOR' - Change vector magnitute, data point resampling rate, etc. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]SetCurrentTool, TOOL ARGUMENTS: TOOL A string specifies the mode to set. See above for possible values.
NAME: GA_Plot_Window::Set_Status_Window PURPOSE: This method assigns a text or label widget ID to be the status window. Cursor tracking reports are sent to the status window. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]Set_Status_Window,WID ARGUMENTS: WID The ID of a text or a label widget to report the cursor readouts and other status message.
NAME: GA_Plot_Window::EditCallback PURPOSE: Perform an IDL procedure call upon certain editing action, CALL_PROCEDURE,ProName,Parent,oData,oPlot,Action ProName is the procedure name specified by keyword EDITCALLBACK when the window object is created (see GA_Plot_Window::Init). This procedure should expect four arguments. Parent The parent widget of the PARENT argument specified in GA_Plot_Window::Init. If the GA_Plot_Window is created through CW_GAWindow, Parent will be the PARENT argument passed to CW_GAWindow. oData A GA_Data object or a null object. oPlot A GA_Plot object or a null object. Action An action string such as 'ADD_DATA','DELETE_DATA', 'DELETE_PLOT','REFERENCE_POINT',etc. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]EditCallback, oData, oPlot, Action ARGUMENTS: see above
NAME: GA_Plot_Window::Draw PURPOSE: Draws all the plots in this window by calling the plot objects Draw method. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]Draw
NAME: GA_Plot_Window::Dump PURPOSE: Prints out pointers to plot objects and their associated data objects. For debugging purposes. CATEGORY: GAplot CALLING SEQUENCE: Obj->[GA_Plot_Window::]Dump
NAME:
GA_Plot_Window::Init
PURPOSE:
Initializes a GA_Plot_Window object. The window is conceived as a
compound widget via CW_GAWindow. When you get the "value" of the
compound widget, you are returned the window object. Instead of
"setting values" to the compound widget, you call window object
methods.
CATEGORY:
GAplot
CALLING SEQUENCE:
Obj = OBJ_NEW('GA_Plot_Window',PARENT)
ARGUMENTS:
PARENT A parent widget ID in which the GA_Plot_Window object
draw widget will be build.
KEYWORDS:
ALLSAMEX Set to draw all plots with the same X range. Default = 1.
CHANGEMOUSEBITMAP Set to change cursor appearance in different modes. Default = 1.
CURRENTTOOL The index of currently selected mode from list
['Select','Zoom','Edit','Cursor','Slice','Mark','Vector']
COLOR The color index for cursor in the window.
DEBUG Set to turn on debugging.
EDITCALLBACK A string specifies a procedure name to call when editing is performed.
EDITFLAGS
EMPTYMSG A string array to display when there is no plot in the window.
ERRORCALLBACK A string specifies a procedure name to call when error occurs.
EVENTCALLBACK A string specifies a procedure name to call when WIDGET_DRAW event occurs.
GRID A two element array for plot layout.
GRID[0] = number of columns, GRID[1] = number of rows.
IMAGE_COLORS
MAXCOLS Maximum number of columns when determining grid automatically.
MAXROWS Maximum number of rows when determining grid automatically.
MBAR Widget ID of menubar for popup window.
MOUSEMODES A string array specifies additional mouse modes.
PLOTS A pointer to a vector of GA_Plot objects.
POPUPOPTIONS A 2xN string array specify entries for popup window.
If not specified, the default options are used.
POPUPOPTIONS[0,*] specify button names,
POPUPOPTIONS[1,*] specify event procedure names to call.
PREFERENCESFILE The file name for user preferences. File should be in user's HOME.
STATUS Set to include the status widget.
TRACKING Set to turn on cursor tracking.
XSIZE The X size of the draw widget display window.
YSIZE The Y size of the draw widget display window.
Category: Graphics
[List of Routines]
NAME:
bangPW
PURPOSE:
Widget to set interactively some !P values. Lists colors by name,
if mk_color used; otherwise finds "closest" index to named colors.
Allows selection of several custom plotting symbols (see PLOTSYM).
CATEGORY:
Graphics, Widgets
CALLING SEQUENCE:
IDL> bangPW
INPUTS:
KEYWORD PARAMETERS:
Optional Keywords:
UPDATECALLBACK - a routine to call after struct system variable is set
GROUP_LEADER - This widget is destroyed if it's GL is destroyed
OUTPUTS:
The system variable !P is changed
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> bangPW, UPDATECALLBACK='myReplotter'
NOTES:
If an application overrides !P.* parameters, or specifies them on
the plot command, changing settings with this widget will not override.
!P.SYMSIZE not controlled, because it seems to have no effect.
MODIFICATION HISTORY:
29-Apr-08 check for routine being compiled (vs. needing to be found)
added a "Refresh" button which, if a proper plotting routine
is provided, will replot with any changed settings.
17-Aug-01 Allow lines with symbols [BD]
30-Oct-00 Written by Bill Davis, PPPL
NAME:
COLORBARbd
PURPOSE:
The purpose of this routine is to add a color bar to the current
graphics window. (this is a mod by BD to handle veritcal plot ticknames better)
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Graphics, Widgets.
CALLING SEQUENCE:
COLORBAR
INPUTS:
None.
KEYWORD PARAMETERS:
ANNOTATECOLOR: The name of the "annotation color" to use. The names are those for
FSC_COLOR, and using the keyword implies that FSC_COLOR is also in
your !PATH. If this keyword is used, the annotation color is loaded
*after* the color bar is displayed. The color will be represented
as theColor = FSC_COLOR(ANNOTATECOLOR, COLOR). This keyword is provide
to maintain backward compatibility, but also to solve the problem of
and extra line in the color bar when this kind of syntax is used in
conjunction with the indexed (DEVICE, DECOMPOSED=0) model is used:
LoadCT, 33
TVImage, image
Colorbar, Color=FSC_Color('firebrick')
The proper syntax for device-independent color is like this:
LoadCT, 33
TVImage, image
Colorbar, AnnotateColor='firebrick', Color=255
BOTTOM: The lowest color index of the colors to be loaded in
the bar.
CHARSIZE: The character size of the color bar annotations. Default is !P.Charsize.
COLOR: The color index of the bar outline and characters. Default
is !P.Color..
DIVISIONS: The number of divisions to divide the bar into. There will
be (divisions + 1) annotations. The default is 6.
FONT: Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.
FORMAT: The format of the bar annotations. Default is '(I0)'.
INVERTCOLORS: Setting this keyword inverts the colors in the color bar.
MAXRANGE: The maximum data value for the bar annotation. Default is
NCOLORS.
MINRANGE: The minimum data value for the bar annotation. Default is 0.
MINOR: The number of minor tick divisions. Default is 2.
NCOLORS: This is the number of colors in the color bar.
NODISPLAY: COLORBAR uses FSC_COLOR to specify some of it colors. Normally,
FSC_COLOR loads "system" colors as part of its palette of colors.
In order to do so, it has to create an IDL widget, which in turn
has to make a connection to the windowing system. If your program
is being run without a window connection, then this program will
fail. If you can live without the system colors (and most people
don't even know they are there, to tell you the truth), then setting
this keyword will keep them from being loaded, and you can run
COLORBAR without a display.
POSITION: A four-element array of normalized coordinates in the same
form as the POSITION keyword on a plot. Default is
[0.88, 0.10, 0.95, 0.90] for a vertical bar and
[0.10, 0.88, 0.90, 0.95] for a horizontal bar.
RANGE: A two-element vector of the form [min, max]. Provides an
alternative way of setting the MINRANGE and MAXRANGE keywords.
REVERSE: Setting this keyword reverses the colors in the colorbar.
RIGHT: This puts the labels on the right-hand side of a vertical
color bar. It applies only to vertical color bars.
TICKNAMES: A string array of names or values for the tick marks.
TITLE: This is title for the color bar. The default is to have
no title.
TOP: This puts the labels on top of the bar rather than under it.
The keyword only applies if a horizontal color bar is rendered.
VERTICAL: Setting this keyword give a vertical color bar. The default
is a horizontal color bar.
MATCH: If set will match color bar to extent of plot.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color bar is drawn in the current graphics window.
RESTRICTIONS:
The number of colors available on the graphics display device (not the
PostScript device) is used unless the NCOLORS keyword is used.
Requires the FSC_COLOR program from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.pro
EXAMPLES:
To display a horizontal color bar above a contour plot, type:
LOADCT, 5, NCOLORS=100
CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
C_COLORS=INDGEN(25)*4, NLEVELS=25
COLORBAR, NCOLORS=100, POSITION=[0.15, 0.8, 0.95, 0.90]
To display a vertical color bar in the lower right of a contour plot, type:
IDL> device, decompose=0
IDL> loadct, 3
IDL> contour, dist(100), /fill, nlevels=100, zstyle=1
IDL> colorbar, pos=[.92,.1,.95,.4], /vert, title='Kev'
MODIFICATION HISTORY:
Written by: David W. Fanning, 10 JUNE 96.
10/27/96: Added the ability to send output to PostScript. DWF
11/4/96: Substantially rewritten to go to screen or PostScript
file without having to know much about the PostScript device
or even what the current graphics device is. DWF
1/27/97: Added the RIGHT and TOP keywords. Also modified the
way the TITLE keyword works. DWF
7/15/97: Fixed a problem some machines have with plots that have
no valid data range in them. DWF
12/5/98: Fixed a problem in how the colorbar image is created that
seemed to tickle a bug in some versions of IDL. DWF.
1/12/99: Fixed a problem caused by RSI fixing a bug in IDL 5.2. Sigh... DWF.
3/30/99: Modified a few of the defaults. DWF.
3/30/99: Used NORMAL rather than DEVICE coords for positioning bar. DWF.
3/30/99: Added the RANGE keyword. DWF.
3/30/99: Added FONT keyword. DWF
5/6/99: Many modifications to defaults. DWF.
5/6/99: Removed PSCOLOR keyword. DWF.
5/6/99: Improved error handling on position coordinates. DWF.
5/6/99. Added MINOR keyword. DWF.
5/6/99: Set Device, Decomposed=0 if necessary. DWF.
2/9/99: Fixed a problem caused by setting BOTTOM keyword, but not NCOLORS. DWF.
8/17/99. Fixed a problem with ambiguous MIN and MINOR keywords. DWF
8/25/99. I think I *finally* got the BOTTOM/NCOLORS thing sorted out. :-( DWF.
10/10/99. Modified the program so that current plot and map coordinates are
saved and restored after the colorbar is drawn. DWF.
3/18/00. Moved a block of code to prevent a problem with color decomposition. DWF.
4/28/00. Made !P.Font default value for FONT keyword. DWF.
9/26/00. Made the code more general for scalable pixel devices. DWF.
1/16/01. Added INVERTCOLORS keyword. DWF.
5/11/04. Added TICKNAME keyword. DWF.
9/29/05. Added REVERSE keywords, which does the *exact* same thing as
INVERTCOLORS, but I can never remember the latter keyword name. DWF.
1/2/07. Added ANNOTATECOLOR keyword. DWF.
4/14/07. Changed the default FORMAT to I0. DWF.
5/1/07. Unexpected consequence of default format change is colorbar annotations
no longer match contour plot levels. Changed to explicit formating of
colorbar axis labels before PLOT command. DWF.
5/25/07. Previous change has unanticipated effect on color bars using
logarithmic scaling, which is not really supported, but I have an
article on my web page describing how to do it: http://www.dfanning.com/graphics_tips/logcb.html.
Thus, I've fixed the program to accommodate log scaling, while still not OFFICIALLY
supporting it. DWF.
10/3/07. Method used to calculate TICKNAMES produces incorrect values in certain cases when
the min and max range values are integers. Now force range values to be floats. DWF.
10/17/07. Accidentaly use of INTERP keyword in CONGRID results in wrong bar values for
low NCOLORS numbers when INVERTCOLORS or REVERSE keyword is used. Removed INTERP keyword. DWF.
11/10/07. Finished fixing program to accommodate log scaling in ALL possible permutations. DWF.
8 Feb 2008. Added CRONJOB keyword and decided to use month names when I write the date. DWF.
8 Feb 2008. Renamed CRONJOB to NODISPLAY to better reflect its purpose. DWF.
21 May 2008. Changed the default CHARSIZE to !P.CHARSIZE from 1.0. DWF.
30 Oct 2008. Fixed a problem with the FONT keyword not being recognized in certain
configurations.
13-Dec-2010 Default range to !Z.CRANGE (set when contour was last called) [BD]
19-Apr-2011 handle values like 1e16. Make "nicer" intervals for tickmarks [BD]
fix use of maxrange and minrange
19-Jul-2011 Added Match keyword to make vertical colorbar match in height to plot
window. Also, default to having number on outside of colorbar when
vertical and on the right.
NAME:
COLORBAR
PURPOSE:
The purpose of this routine is to add a color bar to the current
graphics window.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Graphics, Widgets.
CALLING SEQUENCE:
COLORBAR
INPUTS:
None.
KEYWORD PARAMETERS:
ANNOTATECOLOR: The name of the "annotation color" to use. The names are those for
FSC_COLOR, and using the keyword implies that FSC_COLOR is also in
your !PATH. If this keyword is used, the annotation color is loaded
*after* the color bar is displayed. The color will be represented
as theColor = FSC_COLOR(ANNOTATECOLOR, COLOR). This keyword is provide
to maintain backward compatibility, but also to solve the problem of
and extra line in the color bar when this kind of syntax is used in
conjunction with the indexed (DEVICE, DECOMPOSED=0) model is used:
LoadCT, 33
TVImage, image
Colorbar, Color=FSC_Color('firebrick')
The proper syntax for device-independent color is like this:
LoadCT, 33
TVImage, image
Colorbar, AnnotateColor='firebrick', Color=255
BOTTOM: The lowest color index of the colors to be loaded in
the bar.
CHARSIZE: The character size of the color bar annotations. Default is !P.Charsize.
COLOR: The color index of the bar outline and characters. Default
is !P.Color..
DIVISIONS: The number of divisions to divide the bar into. There will
be (divisions + 1) annotations. The default is 6.
FONT: Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.
FORMAT: The format of the bar annotations. Default is '(I0)'.
INVERTCOLORS: Setting this keyword inverts the colors in the color bar.
MAXRANGE: The maximum data value for the bar annotation. Default is
NCOLORS.
MINRANGE: The minimum data value for the bar annotation. Default is 0.
MINOR: The number of minor tick divisions. Default is 2.
NCOLORS: This is the number of colors in the color bar.
NODISPLAY: COLORBAR uses FSC_COLOR to specify some of it colors. Normally,
FSC_COLOR loads "system" colors as part of its palette of colors.
In order to do so, it has to create an IDL widget, which in turn
has to make a connection to the windowing system. If your program
is being run without a window connection, then this program will
fail. If you can live without the system colors (and most people
don't even know they are there, to tell you the truth), then setting
this keyword will keep them from being loaded, and you can run
COLORBAR without a display.
POSITION: A four-element array of normalized coordinates in the same
form as the POSITION keyword on a plot. Default is
[0.88, 0.10, 0.95, 0.90] for a vertical bar and
[0.10, 0.88, 0.90, 0.95] for a horizontal bar.
RANGE: A two-element vector of the form [min, max]. Provides an
alternative way of setting the MINRANGE and MAXRANGE keywords.
REVERSE: Setting this keyword reverses the colors in the colorbar.
RIGHT: This puts the labels on the right-hand side of a vertical
color bar. It applies only to vertical color bars.
TICKNAMES: A string array of names or values for the tick marks.
TITLE: This is title for the color bar. The default is to have
no title.
TOP: This puts the labels on top of the bar rather than under it.
The keyword only applies if a horizontal color bar is rendered.
VERTICAL: Setting this keyword give a vertical color bar. The default
is a horizontal color bar.
MATCH: If set will match color bar to extent of plot.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color bar is drawn in the current graphics window.
RESTRICTIONS:
The number of colors available on the graphics display device (not the
PostScript device) is used unless the NCOLORS keyword is used.
Requires the FSC_COLOR program from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.pro
EXAMPLES:
To display a horizontal color bar above a contour plot, type:
LOADCT, 5, NCOLORS=100
CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
C_COLORS=INDGEN(25)*4, NLEVELS=25
COLORBAR, NCOLORS=100, POSITION=[0.15, 0.8, 0.95, 0.90]
To display a vertical color bar in the lower right of a contour plot, type:
IDL> device, decompose=0
IDL> loadct, 3
IDL> contour, dist(100), /fill, nlevels=100, zstyle=1
IDL> colorbar, pos=[.92,.1,.95,.4], /vert, title='Kev'
MODIFICATION HISTORY:
Written by: David W. Fanning, 10 JUNE 96.
10/27/96: Added the ability to send output to PostScript. DWF
11/4/96: Substantially rewritten to go to screen or PostScript
file without having to know much about the PostScript device
or even what the current graphics device is. DWF
1/27/97: Added the RIGHT and TOP keywords. Also modified the
way the TITLE keyword works. DWF
7/15/97: Fixed a problem some machines have with plots that have
no valid data range in them. DWF
12/5/98: Fixed a problem in how the colorbar image is created that
seemed to tickle a bug in some versions of IDL. DWF.
1/12/99: Fixed a problem caused by RSI fixing a bug in IDL 5.2. Sigh... DWF.
3/30/99: Modified a few of the defaults. DWF.
3/30/99: Used NORMAL rather than DEVICE coords for positioning bar. DWF.
3/30/99: Added the RANGE keyword. DWF.
3/30/99: Added FONT keyword. DWF
5/6/99: Many modifications to defaults. DWF.
5/6/99: Removed PSCOLOR keyword. DWF.
5/6/99: Improved error handling on position coordinates. DWF.
5/6/99. Added MINOR keyword. DWF.
5/6/99: Set Device, Decomposed=0 if necessary. DWF.
2/9/99: Fixed a problem caused by setting BOTTOM keyword, but not NCOLORS. DWF.
8/17/99. Fixed a problem with ambiguous MIN and MINOR keywords. DWF
8/25/99. I think I *finally* got the BOTTOM/NCOLORS thing sorted out. :-( DWF.
10/10/99. Modified the program so that current plot and map coordinates are
saved and restored after the colorbar is drawn. DWF.
3/18/00. Moved a block of code to prevent a problem with color decomposition. DWF.
4/28/00. Made !P.Font default value for FONT keyword. DWF.
9/26/00. Made the code more general for scalable pixel devices. DWF.
1/16/01. Added INVERTCOLORS keyword. DWF.
5/11/04. Added TICKNAME keyword. DWF.
9/29/05. Added REVERSE keywords, which does the *exact* same thing as
INVERTCOLORS, but I can never remember the latter keyword name. DWF.
1/2/07. Added ANNOTATECOLOR keyword. DWF.
4/14/07. Changed the default FORMAT to I0. DWF.
5/1/07. Unexpected consequence of default format change is colorbar annotations
no longer match contour plot levels. Changed to explicit formating of
colorbar axis labels before PLOT command. DWF.
5/25/07. Previous change has unanticipated effect on color bars using
logarithmic scaling, which is not really supported, but I have an
article on my web page describing how to do it: http://www.dfanning.com/graphics_tips/logcb.html.
Thus, I've fixed the program to accommodate log scaling, while still not OFFICIALLY
supporting it. DWF.
10/3/07. Method used to calculate TICKNAMES produces incorrect values in certain cases when
the min and max range values are integers. Now force range values to be floats. DWF.
10/17/07. Accidentaly use of INTERP keyword in CONGRID results in wrong bar values for
low NCOLORS numbers when INVERTCOLORS or REVERSE keyword is used. Removed INTERP keyword. DWF.
11/10/07. Finished fixing program to accommodate log scaling in ALL possible permutations. DWF.
8 Feb 2008. Added CRONJOB keyword and decided to use month names when I write the date. DWF.
8 Feb 2008. Renamed CRONJOB to NODISPLAY to better reflect its purpose. DWF.
21 May 2008. Changed the default CHARSIZE to !P.CHARSIZE from 1.0. DWF.
30 Oct 2008. Fixed a problem with the FONT keyword not being recognized in certain
configurations.
13-Dec-2010 Default range to !Z.CRANGE (set when contour was last called) [BD]
19-Jul-2011 Added Match keyword to make vertical colorbar match in height to plot
window. Also, default to having number on outside of colorbar when
vertical and on the right. [BD]
23-Sep-2013 show every other tic value when numbers large [BD]
NAME:
drawdiamond
PURPOSE:
draw a diamond in data coordinates
CATEGORY:
Graphics
USAGE:
IDL> drawdiamond, x, y, radius
INPUTS:
x - x of center
y - y of center
radius - height of diamond
KEYWORD PARAMETERS:
color - color of diamond
dashed - if set, linestyle is 4
MODIFICATION HISTORY:
22-mar-2012 Written by Bill Davis, PPPL
NAME:
drawrectangle
PURPOSE:
draw a rectangle in data coordinates
CATEGORY:
Graphics
USAGE:
IDL> drawrectangle, x1, y1, x2, y2
INPUTS:
text - text string to write to window
KEYWORD PARAMETERS:
dropshadow - if set, make a drop shadow of thick=3 text
color - color of text
dscolor - color of drop-shadow text (defaults to black or white)
nPixels - # of pixels to drop shadow
MODIFICATION HISTORY:
25-Sep-2006 Written by Bill Davis, PPPL
NAME:
FSC_COLORBAR
Note: The name of the routine has been changed from COLORBAR
on 25 Sept 2010 to avoid conflicts with an IDL 8.0 routine of the
same name. See the article "IDL 8 Name Conflicts" here:
http://www.dfanning.com/ng_tips/idl8_name_conflicts.html
PURPOSE:
The purpose of this routine is to add a color bar to the current
graphics window.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Graphics, Widgets.
CALLING SEQUENCE:
FSC_COLORBAR
INPUTS:
None.
KEYWORD PARAMETERS:
ADDCMD: Set this keyword to add the FSC_Colorbar command to the current FSC_Window
command list.
ANNOTATECOLOR: The name of the "annotation color" to use. The names are those for
FSC_COLOR, and using the keyword implies that FSC_COLOR is also in
your !PATH. If this keyword is used, the annotation color is loaded
*after* the color bar is displayed. The color will be represented
as theColor = FSC_COLOR(ANNOTATECOLOR). This keyword is provide
to maintain backward compatibility, but also to solve the problem of
an extra line in the color bar when this kind of syntax is used in
conjunction with the indexed (DEVICE, DECOMPOSED=0) model is used:
LoadCT, 33
TVImage, image
FSC_Colorbar, Color=FSC_Color('firebrick')
The proper syntax for device-independent color is like this:
LoadCT, 33
TVImage, image
FSC_Colorbar, AnnotateColor='firebrick', Color=255
Set the Modification History note for 13 November 2010 for additional
information about default values.
BOTTOM: The lowest color index of the colors to be loaded in
the bar.
CHARSIZE: The character size of the color bar annotations. Default is !P.Charsize.
CLAMP: A two-element array in data units. The color bar is clamped to these
two values. This is mostly of interest if you are "window-leveling"
an image. The clamp is set to the "window" of the color bar.
Normally, when you are doing this, you would like the colors outside
the "window" to be set to a neutral color. Use the NEUTRALINDEX keyword
to set the netural color index in the color bar. (See the Example section
for more information.
COLOR: The color index of the bar outline and characters. Default
is !P.Color. To display the color bar in a device indpendent
way, you should use the ANNOTATECOLOR keyword instead of this keyword.
If this keyword is a string color name, then ANNOTATECOLOR=color.
DIVISIONS: The number of divisions to divide the bar into. There will
be (divisions + 1) annotations. The default is 6.
FONT: Sets the font of the annotation. Hershey: -1, Hardware:0, True-Type: 1.
FORMAT: The format of the bar annotations. Default is '(I0)'.
INVERTCOLORS: Setting this keyword inverts the colors in the color bar.
MAXRANGE: The maximum data value for the bar annotation. Default is
NCOLORS.
MINRANGE: The minimum data value for the bar annotation. Default is 0.
MINOR: The number of minor tick divisions. Default is 2.
NCOLORS: This is the number of colors in the color bar.
NEUTRALINDEX: This is the color index to use for color bar values outside the
clamping range when clamping the color bar with the CLAMP keyword.
If this keyword is absent, the highest color table value is used
for low range values and the lowest color table value is used
for high range values, in order to provide contrast with the
clamped region. See the Example section for more information.
NODISPLAY: FSC_COLORBAR uses FSC_COLOR to specify some of it colors. Normally,
FSC_COLOR loads "system" colors as part of its palette of colors.
In order to do so, it has to create an IDL widget, which in turn
has to make a connection to the windowing system. If your program
is being run without a window connection, then this program will
fail. If you can live without the system colors (and most people
don't even know they are there, to tell you the truth), then setting
this keyword will keep them from being loaded, and you can run
FSC_COLORBAR without a display. As of 19 Oct 2010, set to 1 by default.
POSITION: A four-element array of normalized coordinates in the same
form as the POSITION keyword on a plot. Default is
[0.88, 0.10, 0.95, 0.90] for a vertical bar and
[0.10, 0.88, 0.90, 0.95] for a horizontal bar.
RANGE: A two-element vector of the form [min, max]. Provides an
alternative way of setting the MINRANGE and MAXRANGE keywords.
REVERSE: Setting this keyword reverses the colors in the colorbar.
RIGHT: This puts the labels on the right-hand side of a vertical
color bar. It applies only to vertical color bars.
TICKNAMES: A string array of names or values for the tick marks.
TITLE: This is title for the color bar. The default is to have
no title.
TOP: This puts the labels on top of the bar rather than under it.
The keyword only applies if a horizontal color bar is rendered.
VERTICAL: Setting this keyword give a vertical color bar. The default
is a horizontal color bar.
WINDOW: Set this keyword if you want to add the FSC_Colorbar command to
the current FSC_Window application.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color bar is drawn in the current graphics window.
RESTRICTIONS:
The number of colors available on the graphics display device (not the
PostScript device) is used unless the NCOLORS keyword is used.
Requires the FSC_COLOR program from the Coyote Library:
http://www.dfanning.com/programs/fsc_color.pro
EXAMPLE:
To display a horizontal color bar above a contour plot, type:
LOADCT, 5, NCOLORS=100
CONTOUR, DIST(31,41), POSITION=[0.15, 0.15, 0.95, 0.75], $
C_COLORS=INDGEN(25)*4, NLEVELS=25
FSC_COLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]
Example using the CLAMP and NEUTRALINDEX keywords.
LOADCT, 33, NCOLORS=254
TVLCT, FSC_COLOR('gray', /TRIPLE), 255
FSC_COLORBAR, NCOLORS=254, NEUTRALINDEX=255, RANGE=[0,1500], $
DIVISIONS=8, CLAMP=[400, 800]
MODIFICATION HISTORY:
Written by: David W. Fanning, 10 JUNE 96.
10/27/96: Added the ability to send output to PostScript. DWF
11/4/96: Substantially rewritten to go to screen or PostScript
file without having to know much about the PostScript device
or even what the current graphics device is. DWF
1/27/97: Added the RIGHT and TOP keywords. Also modified the
way the TITLE keyword works. DWF
7/15/97: Fixed a problem some machines have with plots that have
no valid data range in them. DWF
12/5/98: Fixed a problem in how the colorbar image is created that
seemed to tickle a bug in some versions of IDL. DWF.
1/12/99: Fixed a problem caused by RSI fixing a bug in IDL 5.2. Sigh... DWF.
3/30/99: Modified a few of the defaults. DWF.
3/30/99: Used NORMAL rather than DEVICE coords for positioning bar. DWF.
3/30/99: Added the RANGE keyword. DWF.
3/30/99: Added FONT keyword. DWF
5/6/99: Many modifications to defaults. DWF.
5/6/99: Removed PSCOLOR keyword. DWF.
5/6/99: Improved error handling on position coordinates. DWF.
5/6/99. Added MINOR keyword. DWF.
5/6/99: Set Device, Decomposed=0 if necessary. DWF.
2/9/99: Fixed a problem caused by setting BOTTOM keyword, but not NCOLORS. DWF.
8/17/99. Fixed a problem with ambiguous MIN and MINOR keywords. DWF
8/25/99. I think I *finally* got the BOTTOM/NCOLORS thing sorted out. :-( DWF.
10/10/99. Modified the program so that current plot and map coordinates are
saved and restored after the colorbar is drawn. DWF.
3/18/00. Moved a block of code to prevent a problem with color decomposition. DWF.
4/28/00. Made !P.Font default value for FONT keyword. DWF.
9/26/00. Made the code more general for scalable pixel devices. DWF.
1/16/01. Added INVERTCOLORS keyword. DWF.
5/11/04. Added TICKNAME keyword. DWF.
9/29/05. Added REVERSE keywords, which does the *exact* same thing as
INVERTCOLORS, but I can never remember the latter keyword name. DWF.
1/2/07. Added ANNOTATECOLOR keyword. DWF.
4/14/07. Changed the default FORMAT to I0. DWF.
5/1/07. Unexpected consequence of default format change is colorbar annotations
no longer match contour plot levels. Changed to explicit formating of
colorbar axis labels before PLOT command. DWF.
5/25/07. Previous change has unanticipated effect on color bars using
logarithmic scaling, which is not really supported, but I have an
article on my web page describing how to do it: http://www.dfanning.com/graphics_tips/logcb.html.
Thus, I've fixed the program to accommodate log scaling, while still not OFFICIALLY
supporting it. DWF.
10/3/07. Method used to calculate TICKNAMES produces incorrect values in certain cases when
the min and max range values are integers. Now force range values to be floats. DWF.
10/17/07. Accidentaly use of INTERP keyword in CONGRID results in wrong bar values for
low NCOLORS numbers when INVERTCOLORS or REVERSE keyword is used. Removed INTERP keyword. DWF.
11/10/07. Finished fixing program to accommodate log scaling in ALL possible permutations. DWF.
8 Feb 2008. Added CRONJOB keyword and decided to use month names when I write the date. DWF.
8 Feb 2008. Renamed CRONJOB to NODISPLAY to better reflect its purpose. DWF.
21 May 2008. Changed the default CHARSIZE to !P.CHARSIZE from 1.0. DWF.
30 Oct 2008. Fixed a problem with the FONT keyword not being recognized in certain
configurations.
9 Nov 2009. Fixed typo in title of vertical colorbar. DWF.
25 Sep 2010. Renamed FSC_Colorbar from Colorbar to avoid conflict with ITTVIS introduced
colorbar.pro function in IDL 8.0. DWF.
19 Oct 2010. Made changes so that axes titles are not picked up in _EXTRA and displayed
on the color bar. Also changed all _EXTRA passes to _STRICT_EXTRA to report
mis-spelled and/or inappropriate keywords. DWF.
19 Oct 2010. Changed the default value of NODISPLAY keyword to 1, since FSC_Color
no longer looks for system colors anyway. NODISPLAY is a depreciated keyword
and does nothing if using the latest version of FSC_Color. DWF.
13 Nov 2010. Samples the upper-right hand pixel on the display if it can. It this pixel is
"white" or the current device is PostScript, sets the ANNOTATECOLOR keyword
to "black" if it of the COLOR keyword is not currently set to some other color.
If the pixel is "black" then ANNOTATECOLOR is set to "white". DWF.
19 Nov 2010. Fixed a small problem when choosing an AnnnotateColor. DWF.
29 Nov 2010. Added CLAMP and NEUTRALINDEX keywords, updated ability to set
color model with SetDecomposedState command. DWF.
1 Dec 2010. Set COLOR=1 and BITS_PER_PIXEL=8 in PostScript device. Tired of getting
e-mails that "your damn colorbar doesn't work!". DWF.
6 Dec 2010. I was always setting COLOR to ANNOTATECOLOR. I should only do that if
COLOR is undefined. DWF.
24 Jan 2011. Added WINDOW keyword. DWF.
29 Jan 2011. Added ADDCMD keyword. DWF.
NAME:
FSC_COLOR
PURPOSE:
The purpose of this function is to obtain drawing colors
by name and in a device/decomposition independent way.
The color names and values may be read in as a file, or 192 color
names and values are supplied with the program. These colors were
obtained from the file rgb.txt, found on most X-Window distributions,
and from colors in the Brewer color tables (http://colorbrewer2.org/).
Representative colors were chosen from across the color spectrum. To
see a list of colors available, type:
Print, FSC_Color(/Names), Format='(6A18)'
If the color names '0', '1', '2', ..., '255' are used, they will
correspond to the colors in the current color table in effect at
the time the FSC_Color program is called.
AUTHOR:
FANNING SOFTWARE CONSULTING:
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Graphics, Color Specification.
CALLING SEQUENCE:
color = FSC_Color(theColor, theColorIndex)
NORMAL CALLING SEQUENCE FOR DEVICE-INDEPENDENT COLOR:
If you write your graphics code *exactly* as it is written below, then
the same code will work in all graphics devices I have tested.
These include the PRINTER, PS, and Z devices, as well as X, WIN, and MAC.
In practice, graphics code is seldom written like this. (For a variety of
reasons, but laziness is high on the list.) So I have made the
program reasonably tolerant of poor programming practices. I just
point this out as a place you might return to before you write me
a nice note saying my program "doesn't work". :-)
axisColor = FSC_Color("Green", !D.Table_Size-2)
backColor = FSC_Color("Charcoal", !D.Table_Size-3)
dataColor = FSC_Color("Yellow", !D.Table_Size-4)
thisDevice = !D.Name
Set_Plot, 'toWhateverYourDeviceIsGoingToBe', /Copy
Device, .... ; Whatever you need here to set things up properly.
IF (!D.Flags AND 256) EQ 0 THEN $
POLYFILL, [0,1,1,0,0], [0,0,1,1,0], /Normal, Color=backColor
Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData, $
NoErase= ((!D.Flags AND 256) EQ 0)
OPlot, Findgen(11), Color=dataColor
Device, .... ; Whatever you need here to wrap things up properly.
Set_Plot, thisDevice
OPTIONAL INPUT PARAMETERS:
theColor: A string with the "name" of the color. To see a list
of the color names available set the NAMES keyword. This may
also be a vector of color names. Colors available are these:
Active Almond Antique White Aquamarine Beige Bisque
Black Blue Blue Violet Brown Burlywood Cadet Blue
Charcoal Chartreuse Chocolate Coral Cornflower Blue Cornsilk
Crimson Cyan Dark Goldenrod Dark Gray Dark Green Dark Khaki
Dark Orchid Dark Red Dark Salmon Dark Slate Blue Deep Pink Dodger Blue
Edge Face Firebrick Forest Green Frame Gold
Goldenrod Gray Green Green Yellow Highlight Honeydew
Hot Pink Indian Red Ivory Khaki Lavender Lawn Green
Light Coral Light Cyan Light Gray Light Salmon Light Sea Green Light Yellow
Lime Green Linen Magenta Maroon Medium Gray Medium Orchid
Moccasin Navy Olive Olive Drab Orange Orange Red
Orchid Pale Goldenrod Pale Green Papaya Peru Pink
Plum Powder Blue Purple Red Rose Rosy Brown
Royal Blue Saddle Brown Salmon Sandy Brown Sea Green Seashell
Selected Shadow Sienna Sky Blue Slate Blue Slate Gray
Snow Spring Green Steel Blue Tan Teal Text
Thistle Tomato Turquoise Violet Violet Red Wheat
White Yellow
The color OPPOSITE is used if this parameter is absent or a color name is mis-spelled. To see a list
of the color names available in the program, type this:
IDL> Print, FSC_Color(/Names), Format='(6A18)'
theColorIndex: The color table index (or vector of indices the same length
as the color name vector) where the specified color is loaded. The color table
index parameter should always be used if you wish to obtain a color value in a
color-decomposition-independent way in your code. See the NORMAL CALLING
SEQUENCE for details. If theColor is a vector, and theColorIndex is a scalar,
then the colors will be loaded starting at theColorIndex.
When the BREWER keyword is set, you must use more arbitrary and less descriptive color
names. To see a list of those names, use the command above with the BREWER keyword set,
or call PICKCOLORNAME with the BREWER keyword set:
IDL> Print, FSC_Color(/Names, /BREWER), Format='(8A10)'
IDL> color = PickColorName(/BREWER)
Here are the Brewer names:
WT1 WT2 WT3 WT4 WT5 WT6 WT7 WT8
TAN1 TAN2 TAN3 TAN4 TAN5 TAN6 TAN7 TAN8
BLK1 BLK2 BLK3 BLK4 BLK5 BLK6 BLK7 BLK8
GRN1 GRN2 GRN3 GRN4 GRN5 GRN6 GRN7 GRN8
BLU1 BLU2 BLU3 BLU4 BLU5 BLU6 BLU7 BLU8
ORG1 ORG2 ORG3 ORG4 ORG5 ORG6 ORG7 ORG8
RED1 RED2 RED3 RED4 RED5 RED6 RED7 RED8
PUR1 PUR2 PUR3 PUR4 PUR5 PUR6 PUR7 PUR8
PBG1 PBG2 PBG3 PBG4 PBG5 PBG6 PBG7 PBG8
YGB1 YGB2 YGB3 YGB4 YGB5 YGB6 YGB7 YGB8
RYB1 RYB2 RYB3 RYB4 RYB5 RYB6 RYB7 RYB8
TG1 TG2 TG3 TG4 TG5 TG6 TG7 TG8
As of 3 July 2008, the Brewer names are also now available to the user without using
the BREWER keyword. If the BREWER keyword is used, *only* Brewer names are available.
The color name "OPPOSITE" is also available. It chooses a color "opposite" to the
color of the pixel in the upper-right corner of the display, if a window is open.
Otherwise, this color is "black" in PostScript and "white" everywhere else.
RETURN VALUE:
The value that is returned by FSC_Color depends upon the keywords
used to call it, on the version of IDL you are using,and on the depth
of the display device when the program is invoked. In general,
the return value will be either a color index number where the specified
color is loaded by the program, or a 24-bit color value that can be
decomposed into the specified color on true-color systems. (Or a vector
of such numbers.)
If you are running IDL 5.2 or higher, the program will determine which
return value to use, based on the color decomposition state at the time
the program is called. If you are running a version of IDL before IDL 5.2,
then the program will return the color index number. This behavior can
be overruled in all versions of IDL by setting the DECOMPOSED keyword.
If this keyword is 0, the program always returns a color index number. If
the keyword is 1, the program always returns a 24-bit color value.
If the TRIPLE keyword is set, the program always returns the color triple,
no matter what the current decomposition state or the value of the DECOMPOSED
keyword. Normally, the color triple is returned as a 1 by 3 column vector.
This is appropriate for loading into a color index with TVLCT:
IDL> TVLCT, FSC_Color('Yellow', /Triple), !P.Color
But sometimes (e.g, in object graphics applications) you want the color
returned as a row vector. In this case, you should set the ROW keyword
as well as the TRIPLE keyword:
viewobj= Obj_New('IDLgrView', Color=FSC_Color('charcoal', /Triple, /Row))
If the ALLCOLORS keyword is used, then instead of a single value, modified
as described above, then all the color values are returned in an array. In
other words, the return value will be either an NCOLORS-element vector of color
table index numbers, an NCOLORS-element vector of 24-bit color values, or
an NCOLORS-by-3 array of color triples.
If the NAMES keyword is set, the program returns a vector of
color names known to the program.
If the color index parameter is not used, and a 24-bit value is not being
returned, then colorIndex is typically set to !D.Table_Size-1. However,
this behavior is changed on 8-bit devices (e.g., the PostScript device,
or the Z-graphics buffer) and on 24-bit devices that are *not* using
decomposed color. On these devices, the colors are loaded at an
offset of !D.Table_Size - ncolors - 2, and the color index parameter reflects
the actual index of the color where it will be loaded. This makes it possible
to use a formulation as below:
Plot, data, Color=FSC_Color('Dodger Blue')
on 24-bit displays *and* in PostScript output! Note that if you specify a color
index (the safest thing to do), then it will always be honored.
INPUT KEYWORD PARAMETERS:
ALLCOLORS: Set this keyword to return indices, or 24-bit values, or color
triples, for all the known colors, instead of for a single color.
BREWER: Set this keyword if you wish to use the Brewer Colors, as defined
in this reference:
http://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_intro.html
As of 3 July 2008, the BREWER names are always available to the user, with or
without this keyword. If the keyword is used, only BREWER names are available.
DECOMPOSED: Set this keyword to 0 or 1 to force the return value to be
a color table index or a 24-bit color value, respectively.
CHECK_CONNECTION: If this keyword is set, the program will check to see if it can obtain
a window connection before it tries to load system colors (which require one). If you
think you might be using FSC_COLOR in a cron job, for example, you would want to set this
keyword. If there is no window connection, the system colors are not available from the program.
As of 18 October 2010, this keyword is no longer used, as system colors have been
removed from the program.
FILENAME: The string name of an ASCII file that can be opened to read in
color values and color names. There should be one color per row
in the file. Please be sure there are no blank lines in the file.
The format of each row should be:
redValue greenValue blueValue colorName
Color values should be between 0 and 255. Any kind of white-space
separation (blank characters, commas, or tabs) are allowed. The color
name should be a string, but it should NOT be in quotes. A typical
entry into the file would look like this:
255 255 0 Yellow
NAMES: If this keyword is set, the return value of the function is
a ncolors-element string array containing the names of the colors.
These names would be appropriate, for example, in building
a list widget with the names of the colors. If the NAMES
keyword is set, the COLOR and INDEX parameters are ignored.
listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
NODISPLAY: Normally, FSC_COLOR loads "system" colors as part of its palette of colors.
In order to do so, it has to create an IDL widget, which in turn has to make
a connection to the windowing system. If your program is being run without a
window connection, then this program will fail. If you can live without the system
colors (and most people don't even know they are there, to tell you the truth),
then setting this keyword will keep them from being loaded, and you can run
FSC_COLOR without a display. THIS KEYWORD NOW DEPRECIATED IN FAVOR OF CHECK_CONNECTION.
As of 18 October 2010, this keyword is no longer used, as system colors have been
removed from the program.
ROW: If this keyword is set, the return value of the function when the TRIPLE
keyword is set is returned as a row vector, rather than as the default
column vector. This is required, for example, when you are trying to
use the return value to set the color for object graphics objects. This
keyword is completely ignored, except when used in combination with the
TRIPLE keyword.
SELECTCOLOR: Set this keyword if you would like to select the color name with
the PICKCOLORNAME program. Selecting this keyword automaticallys sets
the INDEX positional parameter. If this keyword is used, any keywords
appropriate for PICKCOLORNAME can also be used. If this keyword is used,
the first positional parameter can be a color name that will appear in
the SelectColor box.
TRIPLE: Setting this keyword will force the return value of the function to
*always* be a color triple, regardless of color decomposition state or
visual depth of the machine. The value will be a three-element column
vector unless the ROW keyword is also set.
In addition, any keyword parameter appropriate for PICKCOLORNAME can be used.
These include BOTTOM, COLUMNS, GROUP_LEADER, INDEX, and TITLE.
OUTPUT KEYWORD PARAMETERS:
CANCEL: This keyword is always set to 0, unless that SELECTCOLOR keyword is used.
Then it will correspond to the value of the CANCEL output keyword in PICKCOLORNAME.
COLORSTRUCTURE: This output keyword (if set to a named variable) will return a
structure in which the fields will be the known color names (without spaces)
and the values of the fields will be either color table index numbers or
24-bit color values. If you have specified a vector of color names, then
this will be a structure containing just those color names as fields.
NCOLORS: The number of colors recognized by the program. It will be 104 by default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Required programs from the Coyote Library:
http://www.dfanning.com/programs/error_message.pro
http://www.dfanning.com/programs/pickcolorname.pro
http://www.dfanning.com/programs/decomposedcolor.pro
EXAMPLE:
To get drawing colors in a device-decomposed independent way:
axisColor = FSC_Color("Green", !D.Table_Size-2)
backColor = FSC_Color("Charcoal", !D.Table_Size-3)
dataColor = FSC_Color("Yellow", !D.Table_Size-4)
Plot, Findgen(11), Color=axisColor, Background=backColor, /NoData
OPlot, Findgen(11), Color=dataColor
To set the viewport color in object graphics:
theView = Obj_New('IDLgrView', Color=FSC_Color('Charcoal', /Triple))
To change the viewport color later:
theView->SetProperty, Color=FSC_Color('Antique White', /Triple)
To load the drawing colors "red", "green", and "yellow" at indices 100-102, type this:
IDL> TVLCT, FSC_Color(["red", "green", and "yellow"], /Triple), 100
MODIFICATION HISTORY:
Written by: David W. Fanning, 19 October 2000. Based on previous
GetColor program.
Fixed a problem with loading colors with TVLCT on a PRINTER device. 13 Mar 2001. DWF.
Added the ROW keyword. 30 March 2001. DWF.
Added the PICKCOLORNAME code to the file, since I keep forgetting to
give it to people. 15 August 2001. DWF.
Added ability to specify color names and indices as vectors. 5 Nov 2002. DWF.
Fixed a problem with the TRIPLE keyword when specifying a vector of color names. 14 Feb 2003. DWF.
Fixed a small problem with the starting index when specifying ALLCOLORS. 24 March 2003. DWF.
Added system color names. 23 Jan 2004. DWF
Added work-around for WHERE function "feature" when theColor is a one-element array. 22 July 2004. DWF.
Added support for 8-bit graphics devices when color index is not specified. 25 August 2004. DWF.
Fixed a small problem with creating color structure when ALLCOLORS keyword is set. 26 August 2004. DWF.
Extended the color index fix for 8-bit graphics devices on 25 August 2004 to
24-bit devices running with color decomposition OFF. I've concluded most of
the people using IDL don't have any idea how color works, so I am trying to
make it VERY simple, and yet still maintain the power of this program. So now,
in general, for most simple plots, you don't have to use the colorindex parameter
and you still have a very good chance of getting what you expect in a device-independent
manner. Of course, it would be *nice* if you could use that 24-bit display you paid
all that money for, but I understand your reluctance. :-) 11 October 2004. DWF.
Have renamed the first positional parameter so that this variable doesn't change
while the program is running. 7 December 2004. DWF.
Fixed an error I introduced on 7 December 2004. Sigh... 7 January 2005. DWF.
Added eight new colors. Total now of 104 colors. 11 August 2005. DWF.
Modified GUI to display system colors and removed PickColorName code. 13 Dec 2005. DWF.
Fixed a problem with colorIndex when SELECTCOLOR keyword was used. 13 Dec 2005. DWF.
Fixed a problem with color name synonyms. 19 May 2006. DWF.
The previous fix broke the ability to specify several colors at once. Fixed. 24 July 2006. DWF.
Updated program to work with 24-bit Z-buffer in IDL 6.4. 11 June 2007. DWF
Added the CRONJOB keyword. 07 Feb 2008. DWF.
Changed the CRONJOB keyword to NODISPLAY to better reflect its purpose. 7 FEB 2008. DWF.
Added the BREWER keyword to allow selection of Brewer Colors. 15 MAY 2008. DWF.
Added the CHECK_CONNECTION keyword and depreciated the NODISPLAY keyword for cron jobs. 15 MAY 2008. DWF.
Added the BREWER names to the program with or without the BREWER keyword set. 3 JULY 2008. DWF.
If color names '0', '1', '2', ..., '255', are used, the colors are taken from the current
color table in effect when the program is called. 23 March 2009. DWF.
Added the ability to use 24-bit PostScript color, if available. 24 May 2009. DWF.
Program relies on DecomposedColor() to determine decomposed state of PostScript device. 24 May 2009. DWF.
Mis-spelled variable name prevented color structure from being returned by COLORSTRUCTURE keyword. 14 Oct 2009. DWF.
The Z-buffer, after IDL 6.4, appears to be brain dead. It is *always* in DECOMPOSED=1
mode, even when using an 8-bit graphics buffer. (Unless set manaually.) Now I set
the decomposition mode in the program by looking at buffer depth, rather than
the decomposition state, for the Z-buffer. 23 July 2010. DWF.
Adding "system" colors to FSC_Color may have been the worst design decision I ever made.
Since these require a window connection to determine, this decision has haunted
me for years in the form of people wanting to use the software in places where
there is no window connection. For example, in cron jobs. To accommodate legacy
code, I need to *always* check for a connection. I am loath to do this because it
means opening and closing a window, which is, relatively speaking, a slow process.
I've made another attempt to solve this problem with this update and the
corresponding update to the Coyote Library program CanConnect. CanConnect how
creates the system variable !FSC_Display_Connection. If this system variable
exists, FSC_Color consults it to determine if there is a display connection. It
it doesn't exist, it calls CanConnect. This way, a window has to be open only
once in an IDL session to determine if a display connection can be made. 7 Oct 2010. DWF.
I am tired of dealing with "system" colors. I've never used them, no one I know
has ever used them, and they have given me nothing but headaches. I'm done
with them. I'll leave the code here for awhile in case you use them, but
I'm pretty sure I'm not putting them back in. 17 October 2010. DWF.
Added a new color name "OPPOSITE". This is a color that is "opposite" of the pixel color
in the upper right hand corner of the display, if a window is open and the pixel
color can be determined. Otherwise, it is black in PostScript and white everywhere
else. 19 Nov 2010. DWF.
Made sure the ColorIndex that is returned is always an INTEGER. 24 Dec 2010. DWF.
Changed the default "unknown" color from WHITE to OPPOSITE. 30 Dec 2010. DWF.
TVLCT commands protected from NULL device. 4 Jan 2011. DWF.
NAME:
MK_JPEG
PURPOSE:
make a bit-map color jpeg file of an IDL window for (viewable)
insertion into MS Word, or Powerpoint documents.
CATEGORY:
Graphics, Publication
CALLING SEQUENCE:
IDL> mk_jpeg, FILENAME=filename, WINDOW=window, /VERBOSE
INPUTS:
None required
KEYWORD PARAMETERS:
Optional Inputs:
noBorder - if set, will eliminate white space at top and bottom
and left and right
filename - Name of output file; Default='idljpeg.jpg'
overwrite - if=0, will not overwrite existing file
Window - window number to dump to file
VERBOSE - If set, print debugging information
OUTPUTS:
Just the file out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> LoadCT, 5
IDL> TH_IMAGE_CONT, dist(400) ; make a color contour with color bar
IDL> mk_jpeg, filename='myjpeg.jpg'
NOTES:
do not call mk_color, or other things that limit the number of colors,
before running this, so you get 256 colors.
You must have priviledges to write the file.
MODIFICATION HISTORY:
24-Feb-2014 added noBorder keyword
09-Oct-2013 added overwrite keyword (the default)
28-Jul-2010 add status to detect stale NFS handles
09-Aug-2009 Allow filename to be first argument
30-Aug-2004 Added test for truecolor (24-bit color), which seems
to be needed for Windows
22-Feb-00 Written by Bill Davis, PPPL; with thanks to Dave Fanning
NAME:
MK_png
PURPOSE:
make a bit-map color png file of an IDL window for (viewable)
insertion into MS Word, or Powerpoint documents.
CATEGORY:
Graphics, Publication
CALLING SEQUENCE:
IDL> mk_png, FILENAME=filename, WINDOW=window, /VERBOSE
INPUTS:
None required
KEYWORD PARAMETERS:
Optional Inputs:
filename - Name of output file; Default='idlpng.jpg'
Window - window number to dump to file
VERBOSE - If set, print debugging information
OUTPUTS:
Just the file out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> LoadCT, 5
IDL> TH_IMAGE_CONT, dist(400) ; make a color contour with color bar
IDL> mk_png, filename='mypng.jpg'
NOTES:
do not call mk_color, or other things that limit the number of colors,
before running this, so you get 256 colors.
You must have priviledges to write the file.
MODIFICATION HISTORY:
16-Jun-2011 Written by Bill Davis, PPPL for Charles Skinner
NAME:
ONESURF
PURPOSE:
This function returns a 24-bit image of a surface with various
combinations of colour, shading and grids. The colour coding can
tied to the surface height or to an independent array. A grid can
be overlaid on the surface or used to mask a coloured or shaded plot
so as to produce a coloured and/or shaded grid. Light shading can
be applied to both the coloured and gridded surface, or just the
coloured surface, leaving the grid unshaded.
The plotting is done on the current device, which can be any
device which supports the TVRD command: eg screen windows, pixmaps,
or the z-buffer.
The light shading parameters are determined by previous calls to
SET_SHADING. The viewing position and 3d-2d scaling are handled by
the usual graphics keywords - see the documentation for SURFACE and
SHADE_SURF in the IDL user's guide.
The image returned by ONESURF is a pixel-interleaved 24-bit
image of type bytarr(3, xsize, ysize), where xsize and ysize
are the dimensions of the current graphics window.
CATEGORY:
Graphics, Surface Plotting
CALLING SEQUENCE:
result = ONESURF(SURFDATA)
INPUTS:
SURFDATA: a two-dimensional array of type byte containing the
data to be plotted.
KEYWORD PARAMETERS:
COLOUR: Set this keyword to include colour coding in the plot
The default is no colour-coding.
COLDATA: A variable or array of type byte containing the colour
data to be used when plotting a colour plot.
If COLDATA is a scalar then it is assumed to be an index to
a colour in COLMAP which is used to give a single colour to
whole surface.
If COLDATA is a vector of at least three elements its first
three elements are treated as a rgb colour triple and used
to give a single colour to the whole surface.
If COLDATA is two-dimensional it is treated as an array of
colour indices of COLMAP and used to give each data point
it's own colour. If COLDATA has different dimensions to
SURFDATA, CONGRID is used to stretch or squeeze a copy of
COLDATA to fit.
If COLOUR is set but COLDATA is undefined or does not satisfy
any of the above conditions, a BYTSCL'ed version of SURFDATA is
used to produce a plot coloured according to height.
COLMAP: The colour map to use for plotting of the colour data.
If a number is given the corresponding inbuilt IDL colour
map is used. Otherwise COLMAP should be an array of three
byte vectors [red, green, blue] such as those returned by
the TVLCT, /get procedure. If COLMAP is not set, the
current colour map is used. Note that ONESURF maintains
the current colour map even if a different map is specified
for the plot.
SHADE: Set this keyword to perform light shading.
SHADE = 0: no shading
SHADE = 1: shade everything
SHADE = 2: don't shade the grid
The default is no shading
GRID: Set this keyword to apply grids to the surface
GRID = 0: no grid
GRID = 1: overlay a grid on the surface
GRID = 2: use the grid as a mask
The default is no grid
CGRID: The colour to use for overlaid grids. If CGRID is a number
it is treated as an index in the colour table given by COLMAP.
If CGRID is an three-element vector of bytes it is treated
as the rgb values for a colour. If it is anything else or
undefined the grid is plotted white.
_EXTRA: Used to pass extra plot parameters to both SHADE_SURF and
SURFACE. _EXTRA provides a convenient way of passing
common parameters such as viewing angle and plot position.
Note that only keywords valid for both SHADE_SURF and SURFACE
can be used.
If EXTRA_SHADE is set, _EXTRA is ignored for the shaded plots,
similarly with EXTRA_SURF and surface plots.
Some keywords (eg, SHADES, COLOR, NODATA, NOERASE) will
interfere with the plotting done by ONESURF and lead to
unpredictable results.
_EXTRA is itself passed to SHADE_SURF and SURFACE using
the _EXTRA keyword, so keywords which expect a data value
to be changed (eg [XYZ]TICK_GET) will not work.
Useable keywords are: AX, AZ, MAX_VALUE, MIN_VALUE, SAVE,
[XY]TYPE, CHARSIZE, CHARTHICK, CLIP, DATA, DEVICE, FONT,
NOCLIP, NORMAL, POSITION, SUBTITLE, T3D, THICK, TICKLEN,
TITLE, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN, [XYZ]MINOR
[XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK, [XYZ]TICKFORMAT,
[XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS, [XYZ]TICKV,
[XYZ]TITLE, ZVALUE.
EXTRA_SHADE: Used to pass extra plot parameters to the SHADE_SURF
procedure only. EXTRA_SHADE is passed to SHADE_SURF
using the _EXTRA keyword so keywords such as IMAGE
which expect a variable to be altered will not work.
As with _EXTRA, setting the SHADES keyword can lead
to unpredictable results. EXTRA_SURF should be an
anonymous structure.
EXTRA_SURF: Used to pass extra plot parameters to the SURFACE
procedure only. Restrictions are as for _EXTRA and
EXTRA_SHADE. If EXTRA_SHADE is set, but EXTRA_SURF
is not, EXTRA_SURF is made equal to _EXTRA, and vice
versa.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
Create an image of a surface coloured according to height using
the current colour map, with light shading and no grid:
image = onesurf(surfdata, /colour, /shade)
Create a shaded green grid on a shaded surface:
image = onesurf(surfdata, /shade, /grid, cgrid=[0,255,0])
Create a shaded view of a surface, coloured according to a second
array using colour map 25, overlaid with a grey, unshaded grid:
image = onesurf(surfdata, /colour, colmap=25, coldata=second_array, $
shade=2, /grid, cgrid=[127,127,127])
MODIFICATION HISTORY:
Part of Struan's Surface Tutorial:
http://www.sljus.lu.se/stm/IDL/Surf_Tips/
Written by: Struan Gray, Sljusfysik, Lunds Universitet, 970305.
970313 SMG - added _extra, extra_surf and extra_shade keywords
for better control of graphics keywords.
NAME:
PICKCOLORNAME
PURPOSE:
The purpose of this program is to provide a blocking
or modal widget interface for selecting a color "name".
The program uses colors familiar to the FSC_COLOR program,
and is often used to select a color name for passing to FSC_COLOR.
AUTHOR:
FANNING SOFTWARE CONSULTING:
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Graphics, Color Specification.
CALLING SEQUENCE:
colorName = PickColorName(startColorName)
OPTIONAL INPUT PARAMETERS:
startColorName: A string with the "name" of the color. Colors available are these:
Almond Antique White Aquamarine Beige Bisque Black
Blue Blue Violet Brown Burlywood Cadet Blue Charcoal
Chartreuse Chocolate Coral Cornflower Blue Cornsilk Crimson
Cyan Dark Goldenrod Dark Gray Dark Green Dark Khaki Dark Orchid
Dark Red Dark Salmon Dark Slate Blue Deep Pink Dodger Blue Firebrick
Forest Green Gold Goldenrod Gray Green Green Yellow
Honeydew Hot Pink Indian Red Ivory Khaki Lavender
Lawn Green Light Coral Light Cyan Light Gray Light Salmon Light Sea Green
Light Yellow Lime Green Linen Magenta Maroon Medium Gray
Medium Orchid Moccasin Navy Olive Olive Drab Orange
Orange Red Orchid Pale Goldenrod Pale Green Papaya Peru
Pink Plum Powder Blue Purple Red Rose
Rosy Brown Royal Blue Saddle Brown Salmon Sandy Brown Sea Green
Seashell Sienna Sky Blue Slate Blue Slate Gray Snow
Spring Green Steel Blue Tan Teal Thistle Tomato
Turquoise Violet Violet Red Wheat White Yellow
The color WHITE is used if this parameter is absent.
If the BREWER keyword is set, you can use the Brewer Color names:
WT1 WT2 WT3 WT4 WT5 WT6 WT7 WT8
TAN1 TAN2 TAN3 TAN4 TAN5 TAN6 TAN7 TAN8
BLK1 BLK2 BLK3 BLK4 BLK5 BLK6 BLK7 BLK8
GRN1 GRN2 GRN3 GRN4 GRN5 GRN6 GRN7 GRN8
BLU1 BLU2 BLU3 BLU4 BLU5 BLU6 BLU7 BLU8
ORG1 ORG2 ORG3 ORG4 ORG5 ORG6 ORG7 ORG8
RED1 RED2 RED3 RED4 RED5 RED6 RED7 RED8
PUR1 PUR2 PUR3 PUR4 PUR5 PUR6 PUR7 PUR8
PBG1 PBG2 PBG3 PBG4 PBG5 PBG6 PBG7 PBG8
YGB1 YGB2 YGB3 YGB4 YGB5 YGB6 YGB7 YGB8
RYB1 RYB2 RYB3 RYB4 RYB5 RYB6 RYB7 RYB8
TG1 TG2 TG3 TG4 TG5 TG6 TG7 TG8
INPUT KEYWORD PARAMETERS:
BOTTOM: The colors used in the program must be loaded somewhere
in the color table. This keyword indicates where the colors
start loading. By default BOTTOM is set equal to !D.Table_Size-NCOLORS-1.
BREWER: Set this keyword if you wish to use the Brewer Colors, as defined
in this reference:
http://www.personal.psu.edu/cab38/ColorBrewer/ColorBrewer_intro.html
COLUMNS: Set this keyword to the number of columns the colors should
be arranged in.
FILENAME: The string name of an ASCII file that can be opened to read in
color values and color names. There should be one color per row
in the file. Please be sure there are no blank lines in the file.
The format of each row should be:
redValue greenValue blueValue colorName
Color values should be between 0 and 255. Any kind of white-space
separation (blank characters, commas, or tabs) are allowed. The color
name should be a string, but it should NOT be in quotes. A typical
entry into the file would look like this:
255 255 0 Yellow
GROUP_LEADER: This identifies a group leader if the program is called
from within a widget program. Note that this keyword MUST be provided
if you want to guarantee modal widget functionality. (If you don't know
what this means, believe me, you WANT to use this keyword, always.)
INDEX: This keyword identifies a color table index where the selected color
is to be loaded when the program exits. The default behavior is to restore
the input color table and NOT load a color.
TITLE: This keyword accepts a string value for the window title. The default
is "Select a Color".
OUTPUT KEYWORD PARAMETERS:
CANCEL: On exit, this keyword value is set to 0 if the user selected
the ACCEPT button. IF the user selected the CANCEL button, or
closed the window in any other way, this keyword value is set to 1.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Colors are loaded in the current color table. The input color table
is restored when the program exits. This will only be noticable on
8-bit displays. The startColorName is returned if the user cancels
or destroys the widget before a selection is made. Users should
check the CANCEL flag before using the returned color.
EXAMPLE:
To call the program from the IDL comamnd line:
IDL> color = PickColorName("red") & Print, color
To call the program from within a widget program:
color = PickColorName("red", Group_Leader=event.top) & Print, color
MODIFICATION HISTORY:
Written by: David W. Fanning, 31 August 2000.
Modified program to read colors from a file and to use more
colors on 24-bit platforms. 16 October 2000. DWF.
Added the COLUMNS keyword. 16 October 2000. DWF.
Fixed a small problem with mapping a modal widget. 2 Jan 2001. DWF
Now drawing small box around each color. 13 March 2003. DWF.
Added eight new colors. Total now of 104 colors. 11 August 2005. DWF.
Modified GUI to display system colors. 13 Dec 2005. DWF.
Added BREWER keyword to allow Brewer Colors. 15 May 2008. DWF.
NAME:
PSWINDOW
PURPOSE:
This function is used to calculate the size of a PostScript
window that has the same aspect ratio (ratio of height to
width) as the current display graphics window. It creates
the largest possible PostScript output window with the
desired aspect ratio. This assures that graphics output
looks similar, if not identical, to PostScript output.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Graphics.
CALLING SEQUENCE:
pageInfo = PSWINDOW()
INPUTS:
None.
KEYWORD PARAMETERS:
CM: Normally the structure value that is returned from this
function reports its values in inches. Setting this keyword
causes the return values to be in units of centimeters.
FUDGE: A quick way to set symetrical XFUDGE and YFUDGE factors.
If this keyword is set to a value, XFUDGE and YFUDGE keywords are
set to the same value.
LANDSCAPE: Normally this function assumes a PostScript window
in Portrait mode. Setting this keyword assumes you want
the graphic in Landscape mode.
MARGIN: The margin around the edges of the plot. The value must be
a floating point value between 0.0 and 0.5. It is expressed in
normalized coordinate units. The default margin is 0.15.
PAGESIZE: Set this keyword to a string indicating the type
of PostScript page size you want. Current values are "LETTER",
"LEGAL", and "A4". Default is "LETTER".
PRINTER: Set this keyword if the output will be used to
configure the PRINTER device, rather than the PS device.
(In the PRINTER device, offsets are always calculated from
the lower-left corner of the page and do not rotate in
Landscape mode, as they do with the PS device.) Note that
the PRINTER device is only able to accept these keywords
in IDL 5.1 and higher.
XFUDGE: Printers calculate the offset point from the printable
edge of the paper (sometimes), rather from the corner of the paper.
For example, on my Lexmark printer, both X and Y offsets are
calculated from a point 0.25 inches in from the edge. This keyword
allows you to set a "fudge" factor that will be subtracted from
the XOFFSET that is returned to the user. This allows you to create
output that is centered on the page. The fudge factor should be in
the same units as the returned size and offset values.
YFUDGE: Printers calculate the offset point from the printable
edge of the paper (sometimes), rather from the corner of the paper.
For example, on my Lexmark printer, both X and Y offsets are
calculated from a point 0.25 inches in from the edge. This keyword
allows you to set a "fudge" factor that will be subtracted from
the YOFFSET that is returned to the user. This allows you to create
output that is centered on the page. The fudge factor should be in
the same units as the returned size and offset values.
OUTPUTS:
pageInfo: The output value is a named structure defined like
this:
pageInfo = {PSWINDOW_STRUCT, XSIZE:0.0, YSIZE:0.0, $
XOFSET:0.0, YOFFSET:0.0, INCHES:0, PORTRAIT:0, LANDSCAPE:0}
The units of the four size fields are inches unless the CM
keyword is set.
The output can be used to immediately configure the PostScript
or Printer device, like this:
Set_Plot, 'PS' ; or 'PRINTER'
Device, _Extra=pageInfo
RESTRICTIONS:
The aspect ratio of the current graphics window is calculated
like this:
aspectRatio = FLOAT(!D.Y_VSIZE) / !D.X_VSIZE
EXAMPLE:
To create a PostScript output window with the same aspect
ratio as the curently active display window, type:
pageInfo = PSWINDOW()
SET_PLOT, 'PS'
DEVICE, _Extra=pageInfo
To configure the PRINTER device:
pageInfo = PSWINDOW(/Printer, Fudge=0.25)
SET_PLOT, 'PRINTER'
DEVICE, _Extra=pageInfo
MODIFICATION HISTORY:
Written by: David Fanning, November 1996.
Fixed a bug in which the YOFFSET was calculated incorrectly
in Landscape mode. 12 Feb 97.
Took out a line of code that wasn't being used. 14 Mar 97.
Added correct units keyword to return structure. 29 JUN 98. DWF
Fixed a bug in how landscape offsets were calculated. 19 JUL 99. DWF.
Fixed a bug in the way margins were used to conform to my
original conception of the program. 19 JUL 99. DWF.
Added Landscape and Portrait fields to the return structure. 19 JUL 99. DWF.
Added PageSize keyword, changed MARGIN keyword, and completely
rewrote most of the intenal code. 9 FEB 2000. DWF.
Fixed a bug in how I calculated the aspect ratio. 1 MAR 2000. DWF.
Added PRINTER keyword to return proper offset values for the
PRINTER device, where the offset location is not rotated. 1 MAR 2000. DWF.
Added PRINTER fudge factors to take into account that printer offsets are
calculated from the printable area of the paper, rather than the corner
of the paper. 8 AUG 2000. DWF.
07-Mar-02 made work for correctly for landscape/portrait
NAME:
Right_Aspect
PURPOSE:
Allow contour (or x-y) plots to have the aspect ratio of the data
CATEGORY:
Graphics
USE:
IDL> RIGHT_ASPECT, xarray, yarray, IN_POSITION=in_position, $
MARGIN=margin, POSITION=position
KEYWORD PARAMETERS:
MARGIN: (INPUT) The margin around the edges of the plot. The value
must be a floating point value between 0.0 and 0.5. It is expressed
in normalized coordinate units. The default margin is 0.15.
If margin is a 2-element array, the first value is the left and
bottom margin, and the second is the right and top margin. Otherwise,
the right and top margin is set to 1/2 the value of margin.
IN_POSITION: (INPUT) A 4-element floating array of normalized coordinates.
The order of the elements is [x0, y0, x1, y1], similar to the
!P.POSITION system variable or the POSITION keyword on any IDL
graphic command. Fit resulting contour plot within these limits.
POSITION: (OUTPUT) A 4-element floating array of normalized coordinates.
The order of the elements is [x0, y0, x1, y1], similar to the
!P.POSITION system variable or the POSITION keyword on any IDL
graphic command. If not present, will set system variable !p.position.
XRANGE_IN & YRANGE_IN: (INPUTS) - hese override ranges in data
GetWithZ - if set, plots to Z buffer, and reads back X & Y ticks to
determine plot range.
EXAMPLE:
IDL> xarray=FINDGEN(41) & yarray=FINDGEN(21)
IDL> z = DIST(41,21)
IDL> in_pos = [.1,.4,.9,.9] ; draw in top part of screen
IDL> Right_Aspect, xarray, yarray, IN_POS=in_pos, POSITION=out_pos
IDL> CONTOUR, z, xarray, yarray, XSTYLE=1,YSTYLE=1, $
XMARGIN=[0,0], YMARGIN=[0,0], POSITION=out_pos
LIMITATIONS:
if the POSITION keyword is not used, then the
!P.POSITION variable will be set after calling this routine.
So, after plotting, do this: IDL> !P.POSITION = [0,0,0,0]
MODIFICATIONS:
03-Feb-2010 added GetWithZ keyword.
07-Dec-2006 Added xrange_in & yrange_in keywords. These override ranges
in data
28-May-03 Added keyword In_Position. Should now work when partial
screen specified.
04-Apr-01 Do like David Fanning routine, ASPECT, so will work with
A4 paper
14-Mar-01 Take into account !p.multi settings when computing !p.position
Also remove adjustment for x & y pixel number differences.
Add POSITION keyword (not fully tested)
NAME:
rightYaxisLimits
PURPOSE:
Widget to set some Y Axis values for the right-hand axis
in mdsw
CATEGORY:
Graphics, Widgets
CALLING SEQUENCE:
IDL> rightYaxisLimits
INPUTS:
none required
KEYWORD PARAMETERS:
Inputs (Optional):
nPlots - # of plots to allow for (def=8)
GROUP_LEADER - This widget is destroyed if it's GL is destroyed
OUTPUTS:
COMMON BLOCKS:
rightAxis
EXAMPLE:
IDL> rightYaxisLimits
NOTES:
Upgrade could use a user-defined system variable rather than common
MODIFICATION HISTORY:
13-Feb-01 Added multiple axes settings
07-Feb-01 Written by Bill Davis, PPPL
NAME:
setpmulti
PURPOSE:
partition the screen into different graphs
if 7 or less plot boxes, then 1 column of plots
if more than 7 plot boxes, then 2 columns of plots
CATEGORY:
Graphics, Color Specification.
CALLING SEQUENCE:
setpmulti, nboxes
setpmulti, nboxes, /SameXTitles
setpmulti, nboxes, /SameXTitles, /sameXlabels, /SamePTitles
INPUTS:
nboxes: number of plot boxes per page
KEYWORD PARAMETERS:
CharSize : Value desired for !P.CHARSIZE, else guesses
SameXTitles: If set and non-zero, just place xtitle at bottom
(This reserves less vertical space between plots)
SamePTitles: If set and non-zero, just place title at top
(This reserves less vertical space between plots)
SameXlabels: If set and non-zero, just label x-axis at bottom
(This reserves less vertical space between plots)
NRows : Maximum number of rows (default is 7)
COMMON BLOCKS:
SetPMulti_Local
SIDE EFFECTS:
Leaves !P.MULTI set unless you call UnSetPMulti.
Changes character sizes, etc.
MODIFICATION HISTORY:
01-May-01 fix for # of rows and columns
24-Jan-01 Don't force !x.margin[1] to 3. Only reduce this for multi-
columns if !x.margin[1] = 3.
11-Jan-01 Undid setting of !y.ticks, because can't force axis then
21-Nov-00 Fine tuned !y.multi values; if no columns, make x.margin[1]=3
18-Sep-00 Corrected SamePtitle keyword use
24-Jun-99 changed charsize when more than one plot (to 1.4 if rows or cols > 2)
03-Jun-99 added CHARSIZE keyword [BD]
Jan-99 - Written by Bill Davis
NAME:
setup_tek
PURPOSE:
Set system variables for tektronix device.
Use to direct plots to the Tek window in Versaterm, or to XTC.
CATEGORY:
Graphics, Cross-platform plotting
CALLING SEQUENCE:
setup_tek
INPUTS:
KEYWORD PARAMETERS:
Optional Inputs:
CharMagnification - magnify !p.charsize (or, if !p.charsize=0, use as charsize)
OUTPUTS:
none
CALLING EXAMPLE:
setup_tek
plot,indgen(11) ; any number of plot commands
unsetup_tek ; send to printer and back to X
setup_tek, /xtc ; use Tektronix simulator on X
plot,indgen(11) ; any number of plot commands
unsetup_tek ; send to printer and back to X
RELATED ROUTINES:
unsetup_tek
LIMITATIONS:
Y-axis ticklabels may overlay the axis. If so, you may use:
IDL> plot, x, y, YTICKFORMAT='betterticklabels', ...
SIDE EFFECTS:
System variables are changed until unsetup_tek is called.
NOTE:
see http://w3.pppl.gov/~pshare/help/xtc.htm
MODICATION HISTORY:
12-Sep-2008 change "/bin/ps -auxw" to "/bin/ps auxw"
28-Jun-2006 allow for different complier loading in .cshrc
13-Feb-2006 add XTC calls
26-Oct-2000 Written by Bill Davis
NAME:
setup_xpc
PURPOSE:
Use to direct postscript plots to the X-windows Plot Controller (XPC).
CATEGORY:
Graphics, Postscript
CALLING SEQUENCE:
setup_xpc
INPUTS:
KEYWORD PARAMETERS (all optional):
SETUP_PS Keywords:
PORTRAIT - If set, print is in portrait mode
FONT - font for printing, e.g., TIMES, HELVETICA, AVANTGARDE,
BKMAN, BOLD, PALATINO, ZAPFCHANCERY, NARROW (Default is Times)
AspectRatio - if set, Ascpect ratio of image is maintained
CharMagnification - magnify !p.charsize (or, if !p.charsize=0, use as charsize)
xsize
ysize
XPC keywords:
scratchDir - defaults to /loca/$USER/tmpdir (or value of $TMPDIR)
programs running on different computers will have differnt
areas. This must be the same used by the plotting-control
software, setup_xpc.pro.
NODELETE - if set, files in sractchDir (from previous invocation) are
not deleted when application is started.
TITLE: A scalar string to be used for the window title.
NFILES - # of files to show at one time in window (def=10)
filter - search filter for plots to show in window (def=XPC_*.ps)
psPlotFile - file with plotting application keeps plotting
(def=scratchDir+'/GV2plot.ps')
psApp - file plotting application (def="gv")
appSwitch - switch for file plotting application (def="--watch")
updateTime - time in seconds between checks to see if list needs refreshed (def=0.5)
ext - file extensions to look for (def='ps')
OUTPUTS:
establishes XPC window
CALLING EXAMPLE:
setup_xpc ; xpc and gv windows should appear
PLOT, indgen(11) ; any number of plot commands
XYOUT, .2, .3, 'This is a Label'
unsetup_xpc ; close ps file
PROCEDURE:
(see xpc.pro)
RELATED ROUTINES:
xpc
unsetup_xpc
LIMITATIONS:
Y-axis ticklabels may overlay the axis. If so, you may use:
IDL> plot, x, y, YTICKFORMAT='betterticklabels', ...
This system assumes that /local disks are unique to each system.
SIDE EFFECTS:
Post script files (default of 10) are written to ~/XPC_scratch
NOTE:
This, in conjunction with unsetup_xpc, is supposed to be a replacement for XTC.
see http://w3.pppl.gov/~pshare/help/xtc.htm
MODICATION HISTORY:
09-Jul-2011 don't use /local, so can be used from different computers
18-Nov-2009 Written by Bill Davis
NAME:
TV_24
PURPOSE:
This procedure displays a 24-bit image on the current
graphics device, constructing a custom colour table if
the device supports less than 257 colours.
CATEGORY:
Graphics.
CALLING SEQUENCE:
TV_24(image)
INPUTS:
IMAGE: the pixel-interleaved, 24-bit image to be displayed.
IMAGE should be of type BYTARR(3,M,N).
KEYWORD PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
On 8-bit displays the current colour table is overwritten,
on 24-bit displays it is preserved.
RESTRICTIONS:
None.
EXAMPLE:
Display a 24-bit image on an 8-bit display:
TV_24(image)
MODIFICATION HISTORY:
Part of Struan's Surface Tutorial:
http://www.sljus.lu.se/stm/IDL/Surf_Tips/
Written by: Struan Gray, Sljusfysik, Lunds Universitet, 970305.
NAME:
TVRD_24
PURPOSE:
This function reads a 24-bit image from a 24-bit or 8-bit
display device, returning a pixel-interleaved byte array
of type BYTARR(3, xsize, ysize), where xsize and ysize are
the dimensions of the current graphics device.
CATEGORY:
Graphics.
CALLING SEQUENCE:
image = TVRD_24()
INPUTS:
None
KEYWORD PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
image = tvrd_24()
MODIFICATION HISTORY:
Part of Struan's Surface Tutorial:
http://www.sljus.lu.se/stm/IDL/Surf_Tips/
Written by: Struan Gray, Sljusfysik, Lunds Universitet, 970305.
NAME:
TWOSURF
PURPOSE:
This function returns a 24-bit image of two interlocking surfaces
with various combinations of colour, shading and grids.
For each surface the colour coding can tied to the surface height
or to an independent array. A grid can be overlaid on the surface or
used to mask a coloured and/or shaded plot so as to produce a coloured
and/or shaded grid. Light shading can be applied to both the coloured
and gridded surface, or just the coloured surface, leaving the grid
unshaded.
The light shading parameters are determined by previous calls to
SET_SHADING. The viewing position and 3d-2d scaling are handled by
the usual graphics keywords - see the documentation for SURFACE and
SHADE_SURF in the IDL user's guide.
The image returned by TWOSURF is a pixel-interleaved 24-bit image
of type bytarr(3, xsize, ysize). If on entry the current graphics
device is a screen window or the z-buffer, xsize and ysize are the
dimensions of the current or default window on that device. If the
current device is anything else (eg a plotter or a postscript file)
the default size of the z-buffer (640x480) is used. On exit the
current graphics device and colour map are unchanged.
CATEGORY:
Graphics, Surface Plotting
CALLING SEQUENCE:
result = TWOSURF(SURFONE, SURFTWO)
INPUTS:
SURFONE: A two-dimensional array containing the data for the
first of the surfaces to be plotted.
SURFTWO: A two-dimensional array containing the data for the
second of the surfaces to be plotted.
KEYWORD PARAMETERS:
COLOUR1: Set this keyword to include colour coding in the plot
of SURFONE The default is no colour-coding.
COLOUR2: As for COLOUR1 but for SURFTWO. The default is to be
the same as COLOUR1.
COLDATA1: A variable or array of type byte containing the colour
data to be used when plotting a colour plot.
If COLDATA1 is a scalar then it is assumed to be an index to
a colour in COLMAP which is used to give a single colour to
the whole surface.
If COLDATA1 is a vector of at least three elements its first
three elements are treated as a rgb colour triple and used
to give a single colour to the whole surface.
If COLDATA1 is two-dimensional it is treated as an array of
colour indices of COLMAP and is used to give each data point
it's own colour. If COLDATA1 has different dimensions to
SURFONE, CONGRID is used to stretch or squeeze a copy of
COLDATA1 to fit.
If COLOUR1 is set but COLDATA1 is undefined or does not
satisfy any of the above conditions, a BYTSCL'ed version of
SURFONE is used to produce a plot coloured according to height.
COLDATA2: As for COLDATA1 but for SURFTWO.
SHADE1: Set this keyword to perform light shading for SURFONE.
SHADE = 0: no shading
SHADE = 1: shade everything
SHADE = 2: don't shade the grid
The default is no shading.
SHADE2: As for SHADE1 but for SURFTWO. The default is to be
the same as SHADE1.
GRID1: Set this keyword to apply grids to SURFONE.
GRID = 0: no grid
GRID = 1: overlay a grid on the surface
GRID = 2: use the grid as a mask
The default is no grid
GRID2: As for GRID1 but for SURFTWO. The default is to be
the same as GRID1.
CGRID1: The colour to use for overlaid grids on SURFONE. If CGRID
is a number it is treated as an index in the colour table
given by COLMAP. If CGRID is an three-element vector of
bytes it is treated as the rgb values for a colour. If it
is anything else or undefined the grid is plotted white.
CGRID2: As for CGRID1 but for SURFTWO. The default is to be
the same as CGRID1.
TRANSP1: The transparency factor for SURFONE, which determines how
much the hidden parts of SURFTWO show through SURFONE's
surfaces. TRANSP1 is converted to type FLOAT before use,
where 0.0 corresponds to an opaque surface and 1.0 mixes
equal parts of SURFONE and SURFTWO.
Note that if GRID1=2, the holes in the grid are already
completely transparent and TRANSP1 affects only the grid
lines.
The default is 0.0.
TRANSP2: As for TRANSP1 but for SURFTWO. The default is to be
the same as TRANSP1.
COLMAP: The colour map to use for plotting of the colour data.
If a number is given the corresponding inbuilt IDL colour
map is used. Otherwise COLMAP should be an array of three
byte vectors [red, green, blue] such as those returned by
the TVLCT, /get procedure. If COLMAP is not set, the
current colour map is used. Note that TWOSURF maintains
the current colour map even if a second colour map is
specified for the plot.
Because the z-buffer is only an 8bit device plotting
SURFONE and SURFTWO with different colours has to be done
by user manipulation of COLMAP and the arrays passed as
COLDATA1 and COLDATA2.
If either one of the surfaces has light shading applied
the background is set to [0,0,0] (black), otherwise the
background colour of COLMAP is used.
_EXTRA: Used to pass extra plot parameters to both SHADE_SURF and
SURFACE. _EXTRA provides a convenient way of passing
common parameters such as viewing angle and plot position.
Note that only keywords valid for both SHADE_SURF and
SURFACE can be used.
If EXTRA_SHADE is set, _EXTRA is ignored for the shaded
plots, similarly with EXTRA_SURF and surface plots.
Some keywords (eg, SHADES, COLOR, NODATA, NOERASE) will
interfere with the plotting done by ONESURF and lead to
unpredictable results.
_EXTRA is itself passed to SHADE_SURF and SURFACE using
the _EXTRA keyword, so keywords which expect a data value
to be changed (eg [XYZ]TICK_GET) will not work.
Useable keywords are: AX, AZ, MAX_VALUE, MIN_VALUE, SAVE,
[XY]TYPE, CHARSIZE, CHARTHICK, CLIP, DATA, DEVICE, FONT,
NOCLIP, NORMAL, POSITION, SUBTITLE, T3D, THICK, TICKLEN,
TITLE, [XYZ]CHARSIZE, [XYZ]GRIDSTYLE, [XYZ]MARGIN,
[XYZ]MINOR, [XYZ]RANGE, [XYZ]STYLE, [XYZ]THICK,
[XYZ]TICKFORMAT, [XYZ]TICKLEN, [XYZ]TICKNAME, [XYZ]TICKS,
[XYZ]TICKV, [XYZ]TITLE, ZVALUE.
EXTRA_SHADE: Used to pass extra plot parameters to the SHADE_SURF
procedure only. EXTRA_SHADE is passed to SHADE_SURF
using the _EXTRA keyword so keywords such as IMAGE
which expect a variable to be altered will not work.
As with _EXTRA, setting the SHADES keyword can lead
to unpredictable results. EXTRA_SURF should be an
anonymous structure.
EXTRA_SURF: Used to pass extra plot parameters to the SURFACE
procedure only. Restrictions are as for _EXTRA and
EXTRA_SHADE. If EXTRA_SHADE is set, but EXTRA_SURF
is not, EXTRA_SURF is made equal to _EXTRA, and vice
versa.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
SURFONE plotted as a shaded, coloured, partially transparent
surface with the colours corresponding to height and a black
grid, interlocking with SURFTWO, plotted as a shaded, coloured,
partially transparent surface also coloured according to height
but with different colours, and with an unshaded white grid:
image = twosurf(surfone, surftwo, $
colour1 = 1, $
coldata1 = 127b + bytscl(surfone)/2b, $
shade1 = 2, $
grid1 = 1, $
cgrid1 = [0,0,0], $
transp1 = 0.3, $
colour2 = 1, $
coldata2 = 127b - bytscl(surftwo)/2b, $
shade2 = 2, $
grid2 = 1, $
cgrid2 = [250,250,250], $
transp2 = 0.6, $
colmap=25)
For further examples see the SURFDEMO procedure
MODIFICATION HISTORY:
Part of Struan's Surface Tutorial:
http://www.sljus.lu.se/stm/IDL/Surf_Tips/
Written by: Struan Gray, Sljusfysik, Lunds Universitet, 970305.
970313 SMG - added _extra, extra_surf and extra_shade keywords
for better control of graphics keywords.
NAME:
WRITE_IN_BOX
PURPOSE:
Writes a text message within a box in a graphics window.
CATEGORY:
Graphics
Explanation : This procedure writes a short text message within a box-shaped
area in a graphics window. The message may be split at word
boundaries into several lines, and the character size and
orientation may be adjusted for the text to fit within the box.
CALLING SEQUENCE:
IDL> WRITE_IN_BOX, X1, X2, Y1, Y2, TEXT
Inputs : X1, X2 = X coordinates of the box limits.
Y1, Y2 = Y coordinates of the box limits.
TEXT = ASCII text string containing the message.
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords : DATA = If set, then the coordinates are in data units.
This is the default.
DEVICE = If set, then the coordinates are in device units.
NORMAL = If set, then the coordinates are in normalized
units.
MAXCHARSIZE = The maximum character size to use in displaying
the message. If not passed, then determined from
!P.CHARSIZE.
COLOR = Color to use to display the text. The default is
!COLOR.
ALIGNMENT = Controls the alignment of the text in the box. A
value of 0 means to left justify the text, 0.5
means center it (default), and 1 stands for right
justification.
Calls : None.
Common : None.
Restrictions: X2 must be greater than X1, and Y2 must be greater than Y1.
Side effects: The appearance of the displayed message may not be optimal if
any words are separated by multiple blanks, or by tab
characters.
Category : Planning, Science.
Prev. Hist. : None.
Written : William Thompson, GSFC, 7 July 1993.
Modified : Version 1, William Thompson, GSFC, 7 July 1993.
Version 2, William Thompson, GSFC, 24 September 1993.
Added ALIGNMENT keyword based on code provided by Jim
Pendleton, GRO/OSSE NU.
Version 3, William Thompson, GSFC, 21 September 1994
Added STRTRIM call.
Version : Version 3, 21 September 1994
NAME:
xAxisW
PURPOSE:
Widget to set some X Axis values via the system variable !X
CATEGORY:
Graphics, Widgets
CALLING SEQUENCE:
IDL> xAxisW
INPUTS:
input = whatever.
KEYWORD PARAMETERS:
Optional Keywords:
UPDATECALLBACK - a routine to call after axis system variable is set
GROUP_LEADER - This widget is destroyed if it's GL is destroyed
OUTPUTS:
The system variable !X is changed out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> xAxisW, UPDATECALLBACK='myAxisUpdating'
NOTES:
MODIFICATION HISTORY:
29-Apr-08 check for routine being compiled (vs. needing to be found)
added a "Refresh" button which, if a proper plotting routine
is provided, will replot with any changed settings.
08-Dec-04 Removed callback test because of compiling on PC
22-Jan-01 Added Default and Auto Scale buttons [BD]
20-Sep-00 Added TickLen & GridStyle fields [BD]
30-Mar-99 Written by Bill Davis, PPPL
NAME:
yAxisW
PURPOSE:
Widget to set some Y Axis values via the system variable !Y
CATEGORY:
Graphics, Widgets
CALLING SEQUENCE:
IDL> yAxisW
INPUTS:
input = whatever.
KEYWORD PARAMETERS:
Optional Keywords:
UPDATECALLBACK - a routine to call after axis system variable is set
GROUP_LEADER - This widget is destroyed if it's GL is destroyed
OUTPUTS:
The system variable !Y is changed out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> yAxisW, UPDATECALLBACK='myAxisUpdating'
NOTES:
If an application overrides !Y.* parameters, or specifies them on
the plot command, changing settings with this widget will have no
affect.
MODIFICATION HISTORY:
29-Apr-08 check for routine being compiled (vs. needing to be found)
added a "Refresh" button which, if a proper plotting routine
is provided, will replot with any changed settings.
08-Dec-04 Removed callback test because of compiling on PC
22-Jan-01 Added Default and Auto Scale buttons [BD]
28-Sep-00 Correct the display of initial values [BD]
20-Sep-00 Added TickLen & GridStyle fields [BD]
30-Mar-99 Written by Bill Davis, PPPL
NAME:
zAxisW
PURPOSE:
Widget to set some Z Axis values via the system variable !Y
CATEGORY:
Graphics, Widgets
CALLING SEQUENCE:
IDL> zAxisW
INPUTS:
input = whatever.
KEYWORD PARAMETERS:
Optional Keywords:
UPDATECALLBACK - a routine to call after axis system variable is set
GROUP_LEADER - This widget is destroyed if it's GL is destroyed
OUTPUTS:
The system variable !Y is changed out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> zAxisW, UPDATECALLBACK='mzAxisUpdating'
NOTES:
If an application overrides !Z.* parameters, or specifies them on
the plot command, changing settings with this widget will have no
affect.
MODIFICATION HISTORY:
17-Oct-00 Written by Bill Davis, PPPL
Category: GUI
[List of Routines]
NAME:
bitmapbuttons
PURPOSE:
Illustrate use of bitmapbuttons in IDL
CATEGORY:
GUI, buttons
CALLING SEQUENCE:
IDL> bitmapbuttons
Then click on buttons and watch them change.
COMMON BLOCKS:
none
NOTES:
Requires IDL 5.2 or later.
LIMITATIONS:
This may not be the easiest way to manage button states
MODIFICATION HISTORY:
27-Jan-00 [BD]
NAME:
color_resource_example
PURPOSE:
Example of color buttons on a widget.
CATEGORY:
GUI, Color, Example
CALLING SEQUENCE:
IDL> color_resource_example
INPUTS:
none.
KEYWORD PARAMETERS:
none.
OUTPUTS:
none.
EXAMPLE:
IDL> color_resource_example
NOTES:
For IDL color widgets, you need corresponding lines in your
~/.Xresources file (on the computer that is managing your X windows!),
e.g., :
Idl*colorbuttons*blue*background:blue
Idl*colorbuttons*red*background: red
Idl*colorbuttons*lightblue*background: lightblue
Idl*colorbuttons*green*background: green
Idl*colorbuttons*purple*background: purple
Idl*colorbuttons*yellow*background: yellow
Idl*colorbuttons*white*background: white
Idl*colorbuttons*gold*background: gold
Idl*colorbuttons*black*background: black
Idl*colorbuttons*magenta*background: magenta
Idl*colorbuttons*orange*background: orange
LIMITATIONS:
This works consistantly on PPPL Solaris 2.6 computers.
Bug On Linux, the colors initially work,
but disappear on subsequent execution!
MODIFICATION HISTORY:
18-Apr-03 Written by Bill Davis, PPPL
NAME:
color_status_example
PURPOSE:
Example of color status fields on a widget.
CATEGORY:
GUI, Example, Color, Monitoring Application
EXPLANATION:
Makes two rows, each with two buttons to send a color to an
adjacent status field. The status field is just a window in which
the appropriate colors are drawn. MK_COLOR, or a similar routine,
should be used for consistant color display.
CALLING SEQUENCE:
IDL> color_status_example
INPUTS:
none.
KEYWORD PARAMETERS:
none.
OUTPUTS:
none.
COMMON BLOCKS:
info
ROUTINES USED:
MK_COLOR
EXAMPLE:
IDL> color_status_example
NOTES:
The status fields are initially the background color.
A real program might want to save !D.WINDOW before the TV commands
and restore it immediately afterwards.
MODIFICATION HISTORY:
11-May-00 Written by Bill Davis, PPPL
NAME:
DIALOG_INPUT
PURPOSE:
A modal (blocking) dialog widget to input a line of text.
The dialog must be dismissed, by entering text and pressing the
Return key, or by clicking on the 'Ok' or 'Cancel' button before
execution of the calling program can continue.
TYPE:
FUNCTION
CATEGORY:
GUI, Input, WIDGETS
CALLING SEQUENCE:
result = DIALOG_INPUT (PROMPT)
INPUTS:
NONE
KEYWORD PARAMETERS:
PROMPT: Optional STRING or STRARR displayed on the widget.
If the keyword NFIELDS is set, then PROMPT must be a
STRARR of length NFIELDS. If NFIELDS is not set, and PROMPT is
a STRARR, each element of the array will appear on a separate line.
If not supplied, default = 'Enter Text'
TITLE: Window title [default = 'dialog_input']
INITIAL: Initial value to show in the input area. If PROMPT is
supplied, this must be a array of length FIELDS.
XSIZE, YSIZE: The width and height of the dialog
WIDTH: Set the width of the input field IN CHARACTERS.
NFIELDS: Show multiple input fields. If PROMPT and/or INITIAL are
supplied, they must be STRARR of length FIELDS.
CHECKBOX - prompt for optional check box
BOXINIT - initial value of check box (Default=0)
BOXOUT - if=1, then box was checked
TOPLABEL - label above inputs
FLOATING, INTEGER, LONG, DOUBLE - type of input
DIALOG_PARENT: Set this keyword to the widget ID of a widget over
which the message dialog should be positioned. When displayed,
the DIALOG_INPUT dialog will be positioned over the specified
widget. Dialogs are often related to a non-dialog widget tree.
The ID of the widget in that tree to which the dialog is most
closely related should be specified.
RETURN_EVENTS:
Set this keyword to make cluster return an event when a
is pressed in a text field. The default is
not to return events.
OK: STRING label for the 'Ok' button (default = ' OK ' )
CANCEL: STRING label for the 'Cancel' button (default = 'Cancel')
OUTPUTS:
result: STRING or STRARR of input text, or '' if dialog is cancelled
EXAMPLE:
IDL> a=DIALOG_INPUT('enter val', CHECK='turn on', BOXOUT=box )
IDL> a=DIALOG_INPUT(['x1:','y1:', 'x2:','y2:'], NFIELDS=4, TITLE='Box Overlay', $
INITIAL=[1,1,5,6], $
checkBox='Show Box', boxOut=showBox, boxInit=1, $
TOPLABEL='Enter lower left and upper right coords')
SIDE EFFECTS:
Creates a modal widget
MODIFICATION HISTORY:
24-Feb-2011 added Top Label & boxInit [BD]
03-Feb-2011 added Check Box [BD]
22-Jul-2009 added Alt button [BD]
15-Jul-2009 added didCancel keyword
01-Jun-06 default to return events [BD]
12-Sep-04 improvement for prompt on just one entry
Allow for no cancel button [BD]
02-Jul-01 Fixed bug for floating point values [BD]
13-Sep-00 Added RETURN_EVENTS keyword [BD]
03-Feb-00 Added FLOATING, INTEGER and LONG keywords [BD]
v1.03: RSM, Aug 1998, Added WIDTH keyword to set the width of the
input field IN CHARACTERS. Fixed layout bug when using NFIELDS.
v1.02: RSM, May 1998, Non-backward compatible changes to allow multiple
input fields.
v1.01: RSM, Mar 1998, fixed error when used with a modal toplevel base.
v1.0: Written, Robert.Mallozzi@msfc.nasa.gov, July 1997.
NAME:
EDITTABLE
PURPOSE:
Edit a structure with a table where the second item in the structure
is on/off. You can set all items (but the first) on, off, or to a specific value.
If there are more rows than will fit on your screen, it will make new columns.
CATEGORY:
GUI, Editor, Structures
CALLING SEQUENCE:
IDL> newStruct= editTable( struct )
INPUTS:
struct = structure where all tags have same number of elements, and the second
one is for on/off
KEYWORD PARAMETERS:
nrows - defaults to scFrac of screen
noFields - if set, do not show fields, other than on/off
labels - labels of columns, else use tagnames
scFrac= fraction (roughly) of y length to use
title - window title
col1Title - title of first column, else use tagname
fieldSz - size of all numeric fields (defaults to 12)
verbose - if set, print some info
debug - if set, stop in the middle
OUTPUTS:
newStruct = edited structure
EXAMPLE:
items = replicate( '\OPERATIONS::F_FLEVVL', 40 )
nitems = n_elements( items )
for i=0,nitems-1 do items[i]=items[i]+string(i,format='(i2.2)')
onoffs = replicate( 1, nitems )
errvals = replicate( 1.e6, nitems )
more = errvals
third =replicate( 1, nitems )
forth=third
struct = { items : items, onoffs : onoffs, errvals : errvals, more:more, $
third:third, forth:forth}
s= edittable( struct, title='My Dets')
MODIFICATION HISTORY:
WRITTEN 19-Jan-2005 by Bill Davis for Jon Menard
NAME:
get_text_input
PURPOSE:
Prompt the user for input with a question and
return the text string typed by user.
For X-windows the input is through a text widget, in the middle of
the screen, and the text widget waits until carriage return is entered.
Otherwise input is in the terminal window, with a beep to alert user.
CATEGORY:
GUI, Input
CALLING:
text = get_text_input( question )
INPUTS:
question = string(s), prompt for input, default is null string.
If an array is passed, each element is shown on its own line.
KEYWORDS:
DEFAULT_INPUT = optional string, setting the default response.
OUTPUTS:
Function returns the text string entered by user,
with leading and trailing blanks removed.
HISTORY:
Written, Frank Varosi NASA/GSFC 1993.
F.V.1997, question can be a string array, shown as multiple lines.
NAME:
mk_pdmenu
PURPOSE:
make a structure for a pull down menu for CW_PDMENU routine
CATEGORY:
GUI, Programming
CALLING SEQUENCE:
menu = mk_pdmenu( list )
INPUTS:
list - string array in
KEYWORD PARAMETERS:
inputs
maxPerSubMenu = max # of menu items per sub-menu. If not specified,
will try to limit max number to fit on screen.
MenuTitle = menu title (Default=Select)
outputs:
menuItems - items in the menu
OUTPUTS:
menu - structure which can be input to CW_PDMenu
EXAMPLE:
pro test_pdmenu
base = WIDGET_BASE()
colID=WIDGET_BASE(base,/col)
Printer_List = list_printer_unix( )
Printer_List = Printer_List( sort( Printer_List ))
printer_pdmenu = MK_PDMENU( Printer_List, maxPerSubMenu=20 )
menu = CW_PDMENU(colID, printer_pdmenu, /RETURN_FULL_NAME, /MBAR)
butID = WIDGET_BUTTON(colID, VALUE='Quit', UVALUE='Quit')
WIDGET_CONTROL, /REALIZE, base
repeat begin
ev = WIDGET_EVENT(base)
PRINT, ev.value
end until ev.value eq 'Quit'
WIDGET_CONTROL, /DESTROY, base
stop
end
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
11-Feb-2014 bombing on list variable
11-Apr-03 make default maxPerSubMenu fit on screen, if not given
27-Jan-03 Automatically make submenus when list of items is large
26-Mar-99 by Bill Davis
Category: Image Processing
[List of Routines]
NAME:
Bin2D
PURPOSE:
Create a density image (2D histogram) from arrays of (x,y) points,
or create an image of a function from arrays of ( x, y, f(x,y) ) data.
In first case each pixel counts # of (x,y) points falling into
a 2D bin (box), thus forming an image of counters. In optional case,
each pixel is the average of all f(x,y) data falling into the box.
Boxes are determined by dividing the (x,y) range into a uniform grid.
CATEGORY:
Image Processing
CALLING EXAMPLES:
imh = Bin2D( x, y, NPIX=64, XRAN=[0,20], YRAN=[-5,5] )
imz = Bin2D( x, y, FXY=z, NPIX=[200,100] )
INPUTS:
X = array (any dimension) of x values.
Y = array of y values, should correspond to x array.
optionally, x can be of the form [[x],[y]]
containing both x and y coordinates as rows of matrix,
and then argument y should not be specified.
KEYWORDS:
XRAN and YRAN : specify the x,y range to be mapped into the image.
Common Bin2D, xminc,xmaxc, yminc,ymaxc
can also specify the x,y range if keywords are not used,
otherwise the defaults = min-max ranges of x and y.
NPIXELS = 1 or 2 element integer array specifying size of result,
(single value means square image), default = [64,64].
/NOCLIP means do not bother checking if (x,y) are within range (faster).
TYPE_VAR = type code specifying the IDL variable type of result,
(1=byte, 2=short, 3=Long, 4=float,... default=2, short integer).
KEYWORDS (optional):
IMAGE_DENSITY = an existing image of counters (2D histogram)
to which the result is added (overrides NPIX=).
FXY = array giving z = f(x,y) for the purpose of binning into an image
however, bins with no (x,y) data points are left = zero.
(NOTE: must specify XRAN and YRAN, or set /NOCLIP).
if /BOTH is set and FXY=z is given, then the binned image of z=f(x,y) is
returned by function, and an image of (x,y) density is
returned via the keyword IMAGE_DENSITY.
OUTPUTS:
Result of function is an image of the density of (x,y) points, or an
image of scalar field function if z values are given at (x,y) points.
PROCEDURE:
Binning is performed by finding number of (x,y) duplicates
at each pixel, using the IDL sort and where functions.
HISTORY:
written Frank Varosi, U.of MD., 1988.
F.V. 1990, modif. for IDL-V2.
NAME: bpass PURPOSE: Implements a real-space bandpass filter which suppress pixel noise and slow-scale image variations while retaining information of a characteristic size. CATEGORY: Image Processing CALLING SEQUENCE: res = dgfilter( image, lnoise, lobject ) INPUTS: image: The two-dimensional array to be filtered. lnoise: Characteristic lengthscale of noise in pixels. Additive noise averaged over this length should vanish. MAy assume any positive floating value. lobject: A length in pixels somewhat larger than a typical object. Must be an odd valued integer. OUTPUTS: res: filtered image. PROCEDURE: simple 'wavelet' convolution yields spatial bandpass filtering. NOTES: MODIFICATION HISTORY: 19-May-2009 Limit filter width so convol doesn't exceed array dimensions [BD] Written by David G. Grier, The University of Chicago, 2/93. Greatly revised version DGG 5/95. Added /field keyword JCC 12/95. Revised & added 'stack','voxel' capability JCC 5/97. This code 'bpass.pro' is copyright 1997, John C. Crocker and David G. Grier. It should be considered 'freeware'- and may be distributed freely in its original form when properly attributed.
NAME:
cineload
PURPOSE:
Read a frame from a .cin file from a Phantom 7 camera.
File is opened only the first time (or when filename is new), and
pointers and things are remembered from one call to the next.
CATEGORY:
Image Processing
CALLING SEQUENCE:
IDL> image = cineload( filename, frame )
INPUTS:
filename - a .cin file
frame - absolute frame number in file desired. 0 is always the first
OUTPUTS
image - a [n,y] or [3,n,y] image
optional:
fps - frames per second
exposure - exposore time
KEYWORD PARAMETERS (optional):
input:
init - first call for this filename
verbose - print out lots of info
debug - will stop within routine if error detected.
output:
bitcount -
outMsg -
status - if odd, then OK
EXAMPLE:
IDL> filename = '/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139475.cin'
IDL> cine_time, filename, times
IDL> img = cineload(filename, 0) ; get the first frame
NOTES:
MODIFICATION HISTORY:
27-Feb-2013 error message, and assume FirstFrame=0, if frame outside
range in file. This is necessary for some apps when the
first frame in the file is not 0.
03-Jan-2013 fixed exposure output
22-Jun-2010 don't return image as UINT if only 8 bits
02-Apr-2010 flip Miro files if gt 137000, according to Lane
01-Jul-2009 merged "memory feature" of cine_time.pro with this
12-Nov-2008 Hide firstFrame ne 0 within this routine, so calling program
can ask for first frame.
10-Nov-2008 don't force frame=0 when /INIT [BD]
02-Jul-2008 added capability for MIRO color cameras [BD]
19-Apr-2007 added keyword INIT in case frames don't start at 1 [BD]
IDL> img = CINELOAD(GETENV("NSTXUSR")+'/miro/MIRO_130363.cin', 100, /debug)
IDL> img = CINELOAD(GETENV("NSTXUSR")+'/phantom4/NSTX_130363.cin', 100, /debug)
WRITTEN by Ricky Maqueda, Bill Davis & Werner Boeglin
NAME:
cinerate
PURPOSE:
Return framing rate from a .cin file from a Phantom 7 camera.
CATEGORY:
Image Processing
CALLING SEQUENCE:
IDL> rate= cinerate( filename )
RETURNED:
rate - frames per second
INPUTS:
filename - a .cin file
KEYWORD PARAMETERS:
OUTPUT:
serialNum - serial number of camera
warning - if set to 0, will not pop dialog up for messages
EXAMPLE:
IDL> cine_time,'/p/camdata/dust/nstx121048.cin', time
NOTES:
MODIFICATION HISTORY:
Written by Bill Davis 17-Jul
NAME:
cine_snum
PURPOSE:
Return camera serial number from a .cin file from a Phantom camera.
CATEGORY:
Image Processing
CALLING SEQUENCE:
IDL> serialNumber = cine_snum( filename )
INPUTS:
KEYWORD PARAMETERS:
INPUT:
filename - a .cin file
OUTPUT:
serialNumber - serial number of camera
EXAMPLE:
IDL> print, cine_snum('/p/nstxcam/Miro2-7988/2010/nstx_2_137839.cin')
MODIFICATION HISTORY:
Written May-2010 by Bill Davis
from program written by Ricky Maqueda.
NAME:
cine_time
PURPOSE:
Read time from a .cin file from a Phantom 7 camera.
CATEGORY:
Image Processing
CALLING SEQUENCE:
IDL> cine_time, filename, times[, frames, xsize=xsize, ysize=ysize]
INPUTS:
KEYWORD PARAMETERS:
INPUT:
filename - a .cin file
positive - if set, will not return negative image numbers
OUTPUT:
times - array of times in seconds of frames
frames - array of frame numbers
firstImage - first image number
imageSize - image size in bytes
xsize - horizontal size of an image
ysize - vertical size of an image
serialNum - serial number of camera
warning - if set to 0, will not pop dialog up for messages
EXAMPLE:
IDL> cine_time,'/p/camdata/dust/nstx121048.cin', time
NOTES:
MODIFICATION HISTORY:
04-Mar-2014 keyword POSITIVE to correct for negative frame numbers
16-Jan-2014 fixed exposure output
19-Aug-2012 fixed dt being 2usec, 3usec, 2usec, etc. for Phantoms with 400,000 rate
16-Aug-2010 added warning keyword, so doesn't pop dialog box on wall if error
22-Jun-2010 don't make image UINT if only 8 bits
05-May-2010 added keyword serialNum
02-Apr-2010 flip Miro files if gt 137000, according to Lane
01-Jul-2009 merged "memory feature" of cineload.pro with this
17-Jul-2008 return FirstImage (first frame)
17-Jun-2008 check for existence of file
27-Apr-2007 commented out time-correction code which was giving -NaN for
$NSTXUSR/phantom4/flipped_123648.cin (exposure time was changed)
Written by Bill Davis, for Lane Roquemore, 31-May-2006
from program written by Ricky Maqueda.
NAME:
CONVOLVE
PURPOSE:
Convolution of an image with a Point Spread Function (PSF)
CATEGORY:
Image Processing, Math
EXPLANATION:
The default is to compute the convolution using a product of
Fourier transforms (for speed).
CALLING SEQUENCE:
psf = psf_Gaussian( NPIXEL=21, FWHM=5, /NORMALIZE )
imconv = convolve( image1, psf, FT_PSF = psf_FT )
or:
correl = convolve( image1, image2, /CORREL )
or:
correl = convolve( image, /AUTO )
INPUTS:
image = 2-D array (matrix) to be convolved with psf
psf = the Point Spread Function, (size < or = to size of image).
OPTIONAL INPUT KEYWORDS:
FT_PSF = passes out/in the Fourier transform of the PSF,
(so that it can be re-used the next time function is called).
FT_IMAGE = passes out/in the Fourier transform of image.
/CORRELATE uses the conjugate of the Fourier transform of PSF,
to compute the cross-correlation of image and PSF,
(equivalent to IDL function convol() with NO rotation of PSF)
/AUTO_CORR computes the auto-correlation function of image using FFT.
/NO_FT overrides the use of FFT, using IDL function convol() instead.
(then PSF is rotated by 180 degrees to give same result)
METHOD:
When using FFT, PSF is centered & expanded to size of image.
HISTORY:
written, Frank Varosi, NASA/GSFC 1992.
Converted to IDL V5.0 W. Landsman September 1997
NAME:
fastcam_frame
PURPOSE:
a generic routine to get a frame of data from Fast Cameras.
You can get camera data from MDSplus at MIT, read
localNetCDF, HDF, or CIH files (which follow expected
conventions), as well as the Cine files.
CATEGORY:
Image Processing
CALLING SEQUENCE:
IDL> image = fastcam_frame( filename, frame )
INPUTS:
filename - a .cin file
frame - absolute frame number in file desired. 0 is always the first
OUTPUTS
image - a [n,y] or [3,n,y] image
optional:
fps - frames per second
exposure - exposore time
KEYWORD PARAMETERS (optional):
input:
timeWanted -
frameWanted -
force - for remote data from MIT, connect to MDSplus server,
open Spectroscopy tree, etc.
outMsg - error message, if problem
status - if 0, then a problem
verbose - print out lots of info
debug - will stop within routine if error detected.
Only for .cin files:
init -
bitcount -
pps -
exposure -
EXAMPLES:
IDL> data = fastcam_frame( '/u/bdavis/Blobs/solt_012_3.5b.hdf', frame=2 )
IDL> dataM = fastcam_frame( 'shot_1120224022.cin', frame=2 )
IDL> dataX = fastcam_frame( 'shot_1120224022.cine', frame=2 )
IDL> ; e.g., shot=138846 & timeWanted=0.2
IDL> ; this is an easy way to get GPI filenames for NSTX
IDL> filename = findCamFiles( shot, cam=5 )
IDL> ; if you want to access frames by time, get the allTimes array
IDL> ; (seconds) so you can look up the frame number
IDL> FASTCAM_TIMES, filename, allTimes, frames, status=status
IDL> ; (frames[0] is usually 0, but not always!)
IDL> frameNumber = nearesti( allTimes, timeWanted ) + frames[0]
IDL> image = FASTCAM_FRAME( filename, frameNumber, $ ; inputs
IDL> outMsg=outMsg, status=status ) ; returned
NOTES:
can be used in conjunction with cine_time.pro
MODIFICATION HISTORY:
31-Oct-2013 - support for NetCDF files (ext nc) for test blob files
17-Jul-2013 - try to use read_generic for single frame files
10-Sep-2012 - if no directory info, and shot is > 9, then get from tree
at MIT
26-Mar-2012 - added support for SOLT model output written by Jim Myra
WRITTEN 15-Apr-2009 by Bill Davis
NAME:
fastcam_times
PURPOSE:
a generic routine to get timing array for Fast Cameras.
You can get camera data from MDSplus at MIT, read
localNetCDF, HDF, or CIH files (which follow expected
conventions), as well as the Cine files.
CATEGORY:
Image Processing
CALLING SEQUENCE:
IDL> fastcam_times, filename, times
INPUTS:
filename - a .cin file
OUTPUTS
times - times of frames in seconds after T0
optional:
fps - frames per second
exposure - exposore time
KEYWORD PARAMETERS (optional):
inputs:
noOpen - if=1, will force a file open
cam - for MIT cameras (1 is midplane camera)
outputs:
serialNum
frame_rate
EXAMPLE:
IDL> fastcam_times, '/u/bdavis/Blobs/solt_012_3.5b.hdf', times
IDL> fastcam_times, 'shot_1120224022.cin', times, frames
MODIFICATION HISTORY:
31-Oct-2013 - support for NetCDF files (ext nc) for test blob files
10-Sep-2012 - if no directory info, and shot is > 9, then get from tree
at MIT
26-Mar-2012 - added support for SOLT model output written by Jim Myra
05-May-2010 - added keyword serialNum
WRITTEN 15-Apr-2009 by Bill Davis
NAME:
fcplayer
PURPOSE:
Also displays files from the Phantom or color Miro cameras (.cin
files) and optionally save frames as JPEG, PNG or TIFF files.
Allows recording of click locations on .cin files from a
Phantom 4 or 7 camera (for tracking dust, e.g.). Also trackes "blobs"
from images of edge turbulence.
CATEGORY:
Image Processing, Animation, Fast Cameras
CALLING SEQUENCE:
IDL> fcplayer, filename
INPUTS:
filename - a .cin file
(or will pop dialog box)
Environmental/System variable FC_DATA_DIR will be used, if set, to look for
files containing the string in 'filename'
KEYWORD PARAMETERS:
AveT1 - start time in seconds to form average frame for normalizing
AveT2 - end time in seconds to form average frame for normalizing
AveF1 - start frame to form average frame for normalizing
AveF2 - end frame to form average frame for normalizing
bgFrame - the first frame of the background (default=0)
box - if set, will try to handle two boxes that show up on one of Ricky's cameras
ByteScale - if =0, will not byte scale image before displaying.
camera - a number from 1-7, which will go into wildcard search for filename
like 'nstx_5_'
colorTable - default to IDL color table 3 (hot metal)
drawXSize - the horizontal size in pixels of the image window
gamma - gamma correction. (Default=1, which is no correction). 0.5 probably better
for Miro
horizontal_flip - if set, flip images horizontally (desired for NSTX and CMOD shots)
INTERP - if =1, pixels will be smoothed, rather than replicated
loop - if set, will continue to loop over all times, or those in widget boxes.
maxPlayMinutes - defaults to 60
minXsize - minimum X size of window displaying image
nBG - number of background frames. If=0 (the default) no background subtraction is done
noCaption - do not put text on or above image
pause - time to pause between frames when playing
radius - 1/2 of square in pixels drawn around click point, setting the area to be
used for the maxval calculation.
RotCCW - rotate image Counter-ClockWise (desired for NSTX shots)
RotCW - rotate image ClockWise
RotDegrees - rotate an arbitray # of degrees Clockwise
saturation - As in HSV color representation, for color camera. Default is 0.3.
startTime - start time in milliseconds
shot - a number which will go into wildcard search for filename
like '*123456.*'
vertical_flip - if set, flip images vertically
FrameOffset - if set, subtract this (like a baseline) from all pixels
FrameAveMin - if set, make close-to-zero pixels this number,
so when dividing into data, as in normalizing, result is near zero
(if <= 0, then just one average frame will be used)
AveFrameSmooth - smoothing for the averaged frame(s)
FrameAveDeltaMS - make frames used for normalizing an average of this many millisec
verbose - if set, lots of information output listed
debug - if set, will output even more and may stop at some spots
GROUP_LEADER - Group_Leader ID
Blob-related keywords:
blobs - if set, will track blobs (and will set normalize=1, if not set)
normalize - if set, will divide frames by the average frame
saveBlobs - if set, will save blob info to a file (may be easier to run saveblobs.pro)
BlobArrows - if set, will draw arrow from where blob was in the last frame
(if database available for shot and time range)
history - if set, will draw plus signs of previous locations of blob
(if database available for shot and time range)
surface - show shaded surface plot of blobs in another window
aveT1 - if tracking blobs, use this as start time in sec. for averaging frame (DEF=0)
aveT2 - if tracking blobs, use this as ending time in sec. for averaging frame
(DEF=end of file)
OUTPUTS:
none.
COMMON BLOCKS:
region_com
ROUTINES USED:
MK_COLOR, usingXwindows
EXAMPLE:
IDL> fcplayer ; you will be prompted for a .cin file
or IDL> fcplayer,'nstx121048.cin',start=200
or IDL> fcplayer,'MIRO_130376.cin',start=232
IDL> fcplayer,file='~bdavis/France/Data/ball_against_wall_cam2.cine', $
nsmooth=5, /gauss, nbg=1, /invert, /debug
fcplayer, colorTable=3, /horiz, minXsize=256, normalize=0, $
/RotCCW, /edge, $
file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138844.cin'
fcplayer, '/u/bdavis/03-03-2014essais5.cine', $
minX=500, blobs=1, norm=0, showNum=0, nsmooth=3, GaussSmooth=0, $
gamma=0.3, min2show=5 ,/debug
fcplayer, '/u/bdavis/03-03-2014essais5.cine', aveF1=10, aveF2=110, $
minX=500, blobs=0, norm=1, showNum=0, nsmooth=3, GaussSmooth=0
gamma=0.5, min=40 ,/debug
for GPI 2015 paper:
fcplayer,file='nstx_5_140395.cin', /horiz, /RotCC, /show5, $
colorTable=3, minxsize=500, aveT1=.5505, aveT2=.5515, $
showNum=0, plusSign=0, FrameAveDeltaMS=0 ;;;, /rainbow ;;;, minVal=0.405, maxVal=2.159
fcplayer,file='nstx_5_141746.cin', aveT1=.208, aveT2=.209, minxsize=400
for GPI study:
fcplayer,file='nstx_5_137582.cin', $
aveT1=0.329, aveT2=0.333, /horiz, /RotCC, $
colorTable=3, minXsize=400, FrameAveDeltaMS=0 ,/debug
fcplayer, '/u/bdavis/cvs/idl_cvs/circoneup_1.nc', horiz=0, minx=400
examples for Blob tracking:
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139056.cin', $
aveT1=0.420, aveT2=0.430, /horiz, /RotCC, $
colorTable=3, /blobs, minXsize=300 , FrameAveDeltaMS=0 ,/debug
fcplayer, file='/u/bdavis/Blobs/solt_012_3.5b.hdf', /horiz, /rotcw, ctb=3, minXsize=300, $
minNorm=0.001, aveT1=0.0, aveT2=1.e-5, FrameAveDeltaMS=0, /blobs , /debug
fcplayer, aveT1=0.0, aveT2=0.02, colorTable=3, /blobs, /horiz, minXsize=400, $
file='/home/bdavis/shot_1091216028.cin' ; at MIT
fcplayer, aveT1=0.0, aveT2=0.02, colorTable=3, /blobs, /horiz, minXsize=400, $
file='/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216028.cin'
(Myra:)
fcplayer, aveT1=0.055, aveT2=0.0580, colorTable=3, /blobs, /horiz, minXsize=256, $
file='/p/gpi/szweben/Phantom_Data/2010_data/1100120/shot_1100120025.cin'
fcplayer, aveT1=0.06, aveT2=0.08, colorTable=3, /blobs, /horiz, minXsize=256, $
file='/p/gpi/szweben/Phantom_Data/2010_data/1100824/shot_1100824017.cin'
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139432.cin', $
aveT1=0.268, aveT2=0.288, /horiz, /RotCC, $
colorTable=3, /blobs, minXsize=300 ,/debug
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139442.cin', $
aveT1=0.310, aveT2=0.312, /horiz, /RotCC, colorTable=3, minXsize=300 ,/debug
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_139444.cin', $
aveT1=0.265, aveT2=0.275, /horiz, /RotCC, $
colorTable=3, /blobs, minXsize=300 , FrameAveDeltaMS=0 ,/debug
fcplayer, $
file='/p/gpi/szweben/Phantom_Data/2009_Phantom_data/1091216/shot_1091216030.cin', $
colorTable=3, minXsize=256, /blobs, /horiz, aveT1=0., aveT2=0.02, /debug
fcplayer,colortable=3, minXsize=256, /blobs, /horiz, avet1=1.25, avet2=1.27, $
file='/p/gpi/szweben/Phantom_Data/2010_data/1100803/shot_1100803008.cin'
fcplayer, aveT1=0.0, aveT2=0.02, colorTable=3, /blobs, /horiz, minXsize=512, $
file='/p/gpi/szweben/Phantom_Data/2011_data/1110114/shot_1110114026.cin'
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141751.cin', $
aveT1=0.2, aveT2=0.22, /horiz, /RotCC, $
colorTable=3, minXsize=256, /blobs,/debug
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_141752.cin', $
aveT1=0.21, aveT2=0.23, /horiz, /RotCC, $
colorTable=3, minXsize=256, /blobs
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138234.cin', $
aveT1=0.530, aveT2=0.550, /horiz, /RotCC, colorTable=3, $
minXsize=300, /blobs ,/debug
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138234.cin', $
aveT1=0.530, aveT2=0.540, /horiz, /RotCC, $
colorTable=3, minXsize=300, /blobs , FrameAveDeltaMS=0 ,/debug
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138128.cin', $
aveT1=0.280, aveT2=0.290, /horiz, /RotCC, $
colorTable=3, minXsize=300, /blobs , FrameAveDeltaMS=0 ,/debug
fcplayer,file='/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138114.cin', $
aveT1=0.225, aveT2=0.235, /horiz, /RotCC, $
colorTable=3, minXsize=300, /blobs , FrameAveDeltaMS=0 ,/debug
fcplayer,'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_138120.cin' , $
avet1=0.219,avet2=0.229, colorTable=3, minXsize=256, /blobs, /horiz, $
/rotccw, starttim=.2
NB shot, with 1MW during some FC timesL
fcplayer,'/p/nstxcam-archive/Phantom710-9205/2010/nstx_5_142220.cin' , $
avet1=0.280,avet2=0.300, colorTable=3, minXsize=256, /blobs, /horiz, $
/rotccw, starttim=.29
for looking at elliptical changes at 0.922:
fcplayer, colorTable=3, /blobs, /horiz, minXsize=400, $
file='/p/gpi/szweben/Phantom_Data/2011_data/1110114/shot_1110114032.cin'
to look at X-pt camera from CMOD:
fcplayer, aveT1=0.08, aveT2=0.09, colorTable=3, /blobs, /horiz, /RotCW, minXsize=400, $
file='/p/gpi/szweben/Phantom2_Data/2012_shots/1120815/shot_1120815021.cine', $
FrameAveMin=25, FrameAveDeltaMS=1, max2show=2
to look at X-pt camera from CMOD via MDSplus (times are shot times):
fcplayer, aveT1=1.044, aveT2=1.048, colorTable=3, /blobs, /horiz, /RotCW, $
minXsize=400, file='shot_1120224022.cine', $
FrameAveMin=25, FrameAveDeltaMS=0, max2show=2
to look at mid-plane camera from CMOD via MDSplus
fcplayer, aveT1=1.044, aveT2=1.045, colorTable=3, /blobs, /horiz, $
minXsize=400, file='shot_1120224022.cin', $ ; no "e" on end for midplane
FrameAveMin=25, FrameAveDeltaMS=0, max2show=2
shot = '1120815018' & t1=1.270 & t2=1.274
; black part will be across top with /horiz and /RotCW
fcplayer, aveT1=t1, aveT2=t2, colorTable=3, /blobs, /horiz, /RotCW, $
minXsize=400, file='shot_'+shot+'.cine', $ ; .cine is X-pt cam
FrameAveDeltaMS=0, FrameAveMin=25, max2show=2
to look at corresponding mid-plane camera from CMOD:
fcplayer, aveT1=t1, aveT2=t2, colorTable=3, /blobs, /horiz, $
minXsize=400, file='shot_'+shot+'.cin', $ ; .cin is midplane cam
FrameAveDeltaMS=0, FrameAveMin=25, max2show=2 ; blacking good here?
fcplayer, aveT1=1.086, aveT2=1.088, colorTable=3, /blobs, /horiz, $
minXsize=400, file='shot_1120224029.cin', $
FrameAveMin=25, FrameAveDeltaMS=0, max2show=2 , minrise = 0.06
fcplayer, aveT1=1.440, aveT2=1.443, colorTable=3, /blobs, /horiz, $
minXsize=400, file='shot_1120712028.cin', $
FrameAveMin=25, FrameAveDeltaMS=0, max2show=2 , minrise = 0.06
fcplayer, aveT1=1.440, aveT2=1.443, colorTable=3, /blobs, /horiz, /rotcw, $
minXsize=400, file='shot_1120712028.cine', $
FrameAveMin=25, FrameAveDeltaMS=0, max2show=2 , minrise = 0.06
fcplayer, aveT1=1.086, aveT2=1.088, colorTable=3, /blobs, /horiz, $
minXsize=400, file='shot_1120224029.cine', $ ; RotDeg=51, $
FrameAveMin=25, FrameAveDeltaMS=0, max2show=2, minrise = 0.06
fcplayer, aveT1=1.089, aveT2=1.091, colorTable=3, /blobs, /horiz, /rotcw, $
minXsize=400, file='shot_11202240.cine', $
FrameAveMin=25, FrameAveDeltaMS=0, max2show=2
NOTES:
MODIFICATION HISTORY:
11-Jun-2015 Stewart wants TOPNORM, xFromSEP,tiltHM, ellipHM and EHMht printed
beside blobs
12-Mar-2014 added ability to specify Fit for separatrix
03-Mar-2014 when GPI fast camera asked for, use BD preferences.
31-Oct-2013 - support for NetCDF files (ext nc) for test blob files
08-Oct-2013 added manifold-showing option. New limiter position
17-Jul-2013 made to work (again) with a single frame
05-Mar-2013 added shot and camera keywords.
29-Nov-2012 Replaced Save-as-GIF with PNG
06-Oct-2012 allow surface plot axes to be in cm
05-Oct-2012 added showNumbers keyword so text on images can be surpressed.
13-Sep-2012 If CMOD files not in local directory, or the one specified, get from
MDSplus at MIT.
05-Sep-2012 different smoothing parameter for Frame Averaging.
Allow average frames to be for 1ms, or whatever.
New keyword FrameOffset to be subtracted from each frame.
Reinstated the printing of "rise" next to blobs.
04-Sep-2012 read file for Average Intensity plot, if not in tree.
27-Mar-2012 support for HDF files from simulations by Jim Myra.
07-Mar-2012 In findblobs, check Chi Squared first, before tossing all
interior contours (fixed a bug where occaisional blobs missing).
01-Mar-2012 decided not to smooth average frame. Changed median smoothing to regular
23-Feb-2012 allow for not smoothing the average frame. Smooth average frame the
same as the setting for the data
14-Dec-2011 added option to show separatrix (keyword edge); probably only makes
sense for GPI camera (#5) data
07-Dec-2011 subtract background right after data read, so shouldn't rotate,
flip, etc., background data
26-Sep-2011 Anticipating loading of blob database will be done with loadblob.pro,
made the blobCriteria more reasonable. MinHt 1.1, MinArea 15,
MinChiSq 5, minRise 0.05
06-Sep-2011 reworked findblobs, so can plot surface within same window
20-May-2011 fixed printer selection and aspect ration of prints
07-Apr-2011 added NoCaption keyword for NOVA work.
21-Jan-2011 use database of parent/child relations of blobs to draw arrows
Using point of maximum withing (smoothed) blob as center to track.
04-Jan-2011 blob tracking and output file for Stewart Zweben
22-Jul-2010 added Preview and Revert buttons to Image Enhancement widget.
23-Jun-2010 desensitze widgets in slave window that would create new widget IDs
14-Jun-2010 added rotate-image options
10-Jun-2010 added Master Player feature to allow synced play of two different cameras
08-Jun-2010 use amedian, so edges of images get filtered
28-May-2010 fixed play range, and made jpeg saves a screen dump (so would
use image enhancements.
27-May-2010 can specify nBG and BGframe on command line.
18-May-2010 fixed one pixel too many being displayed on zoom (so click points off a little)
06-May-2010 Improved default dir for writing Click files, and don't destroy clicked
data if cancel out of writing.
19-Apr-2010 combined background dialogs into one widget
27-Jan-2010 remove /KEEP_ASPECT from TVIMAGE and draw at z=0 so Z Position is correct
21-Jan-2010 set Val printed back to value of clicked point (for later reasonableness checking)
11-Jan-2010 Added slider for saturation in "Image Enhancement" widget, and made default=0.3
05-Jan-2010 Added display of X & Y positions
21-Dec-2009 Added "Specify region to display" option
10-Dec-2009 Added option to plot average intensity vs. time of RGB components
01-Sep=2009 added /horizontal_flip and /vertical_flip and menu items.
06-Jul-2009 Added menu option to search for movie files.
24-Jun-2009 Added Write MPEG, and min/max values to show.
15-Apr-2009 Added support for *.raww files, from new Photron camera
10-Nov-2008 cleaned up incompatibility with tvimage. Added menu options for # of
background frames to subtract, start frame for background subtraction,
turn off/on byte scaling of image.
04-Aug-2008 added Frame Time slider widget
31-Jul-2008 Added imageproc option to Special menu & gamma setting to Edit menu.
Also added median smoothing option.
16-Jul-2008 Can ungzip .gz files automatically
14-Jul-2008 Added support for color images. Added GAMMA keyword.
10-Jun-2008 Added XSectionW option. Changed default to no background subtraction
15-May-2008 Added maxPlayMinutes, so movie won't run for ever (Default to 1 hour)
12-May-2008 made advance and backup buttons more clear. Added noLoad keyword so
color palette loading can be surpressed.
15-Feb-2008 Add options to save as JPEG, GIF & TIFF
15-Mar-2007 add animation feature
26-Oct-2006 added Advance-number-of-frames box
19-Oct-2006 added BG subtraction and "box disquising"
01-Jun-2006 Written by Bill Davis, PPPL
see http://www.physics.emory.edu/~weeks/idl for more information NAME: Feature PURPOSE: Finds and measures roughly circular 'features' within an image. CATEGORY: Image Processing CALLING SEQUENCE: f = feature( image, diameter [, separation, masscut = masscut, min = min, iterate = iterate, /field, /quiet ] ) INPUTS: image: (nx,ny) array which presumably contains some features worth finding diameter: a parameter which should be a little greater than the diameter of the largest features in the image. Diameter MUST BE ODD valued. separation: an optional parameter which specifies the minimum allowable separation between feature centers. The default value is diameter+1. masscut:Setting this parameter saves runtime by reducing the runtime wasted on low mass 'noise' features. min: Set this optional parameter to the minimum allowed value for the peak brightness of a feature. Useful for limiting the number of spurious features in noisy images. field: Set this keyword if image is actually just one field of an interlaced (e.g. video) image. All the masks will then be constructed with a 2:1 aspect ratio. quiet: Supress printing of informational messages. iterate: if the refined centroid position is too far from the initial estimate, iteratively recalc. the centroid using the last cetroid to position the mask. This can be useful for really noisy data, or data with flat (e.g. saturated) peaks. Use with caution- it may 'climb' hills and give you multiple hits. OUTPUTS: f(0,*): this contains the x centroid positions, in pixels. f(1,*): this contains the y centroid positions, in pixels. f(2,*): this contains the integrated brightness of the features. f(3,*): this contains the square of the radius of gyration of the features. f(4,*): this contains the eccentricity, which should be zero for circularly symmetric features and order one for very elongated images. SIDE EFFECTS: Displays the number of features found on the screen. RESTRICTIONS: To work properly, the image must consist of bright, circularly symmetric regions on a roughly zero-valued background. To find dark features, the image should be inverted and the background subtracted. If the image contains a large amount of high spatial frequency noise, performance will be improved by first filtering the image. BPASS will remove high spatial frequency noise, and subtract the image background and thus provides a good complement to using this program. Individual features should NOT overlap. PROCEDURE: First, identify the positions of all the local maxima in the image ( defined in a circular neighborhood with diameter equal to 'diameter' ). Around each of these maxima, place a circular mask, of diameter 'diameter', and calculate the x & y centroids, the total of all the pixel values, and the radius of gyration and the 'eccentricity' of the pixel values within that mask. If the initial local maximum is found to be more than 0.5 pixels from the centroid and iterate is set, the mask is moved and the data are re-calculated. This is useful for noisy data. If the restrictions above are adhered to, and the features are more than about 5 pixels across, the resulting x and y values will have errors of order 0.1 pixels for reasonably noise free images. ********* READ THE FOLLOWING IMPORTANT CAVEAT! ********** 'feature' is capable of finding image features with sub-pixel accuracy, but only if used correctly- that is, if the background is subtracted off properly and the centroid mask is larger than the feature, so that clipping does not occur. It is an EXCELLENT idea when working with new data to plot a histogram of the x-positions mod 1, that is, of the fractional part of x in pixels. If the resulting histogram is flat, then you're ok, if its strongly peaked, then you're doing something wrong- but probably still getting 'nearest pixel' accuracy. For a more quantitative treatment of sub-pixel position resolution see: J.C. Crocker and D.G. Grier, J. Colloid Interface Sci. *179*, 298 (1996). MODIFICATION HISTORY: This code is inspired by feature_stats2 written by David G. Grier, U of Chicago, 1992. Written by John C. Crocker, U of Chicago, optimizing runtime and measurement error, 10/93. Added field keyword, 4/94. Added eccentricity parameter, 5/95. Added quiet keyword 12/95. Added iteration, fixed up the radius/diameter fiasco and did some debugging which improves non-centroid data. 4/96. This code 'feature.pro' is copyright 1997, John C. Crocker and David G. Grier. It should be considered 'freeware'- and may be distributed freely in its original form when properly attributed.
NAME:
FILTER_IMAGE
PURPOSE:
Identical to MEDIAN or SMOOTH but handle edges and allow iterations.
CATEGORY:
Image Processing
EXPLANATION:
Computes the average and/or median of pixels in moving box,
replacing center pixel with the computed average and/or median,
(using the IDL smooth or median functions).
The main reason for using this function is the option to
also process the pixels at edges and corners of image, and,
to apply iterative smoothing simulating convolution with Gaussian,
and/or to convolve image with a Gaussian kernel.
CALLING SEQUENCE:
Result = filter_image( image, SMOOTH=box_width, /MEDIAN, /ALL )
INPUT:
image = 2-D array (matrix)
OPTIONAL INPUT KEYWORDS:
SMOOTH = scalar (odd) integer specifying the width of a square box
for moving average, in # pixels.
/SMOOTH means use box width = 3 pixels for smoothing.
MEDIAN = scalar (odd) integer specifying the width of square moving
box for median filter, in # pixels.
/MEDIAN means use box width = 3 pixels for median filter.
/ALL_PIXELS causes the edges of image to be filtered as well,
accomplished by reflecting pixels adjacent to edges outward.
/ITERATE means apply smooth(image,3) iteratively for a count of
(box_width-1)/2 times (=radius), when box_width >= 5.
This is equivalent to convolution with a Gaussian PSF
of FWHM = 2 * sqrt( radius ) as radius gets large.
Note that /ALL_PIXELS is automatically applied,
giving better results in the iteration limit.
(also, MEDIAN keyword is ignored when /ITER is specified).
FWHM_GAUSSIAN = Full-width half-max of Gaussian to convolve with image.
FWHM can be a single number (circular beam),
or 2 numbers giving axes of elliptical beam.
/NO_FT_CONVOL causes the convolution to be computed directly,
with IDL function convol.
The default is to use FFT when factors of size are all LE 13.
(note that external function convolve handles both cases)
RESULT:
Function returns the smoothed, median filtered, or convolved image.
If both SMOOTH and MEDIAN are specified, median filter is applied first.
EXAMPLES:
To apply 3x3 moving median filter and
then 3x3 moving average, both applied to all pixels:
Result = filter_image( image, /SMOOTH, /MEDIAN, /ALL )
To iteratively apply 3x3 moving average filter for 4 = (9-1)/2 times,
thus approximating convolution with Gaussian of FWHM = 2*sqrt(4) = 4 :
Result = filter_image( image, SMOOTH=9, /ITER )
To convolve all pixels with Gaussian of FWHM = 3.7 x 5.2 pixels:
Result = filter_image( image, FWHM=[3.7,5.2], /ALL )
EXTERNAL CALLS:
function psf_gaussian
function convolve
pro factor
function prime ;all these called only if FWHM is specified.
PROCEDURE:
If /ALL_PIXELS or /ITERATE keywords are set then
create a larger image by reflecting the edges outward,
then call the IDL median and/or smooth function on the larger image,
and just return the central part (the orginal size image).
HISTORY:
Written, 1991, Frank Varosi, NASA/GSFC.
FV, 1992, added /ITERATE option.
FV, 1993, added FWHM_GAUSSIAN= option.
Converted to IDL V5.0 W. Landsman September 1997
NAME: GAMMA_RAISE PURPOSE: Apply gamma correction to an array, presumably an image. CATEGORY: Image Processing. CALLING SEQUENCE: newImage = GAMMA_RAISE(image, Gamma) INPUTS: Gamma: The value of gamma correction. A value of 1.0 indicates a linear ramp, i.e., no gamma correction. Higher values of gamma give more contrast. Values less than 1.0 yield lower contrast. KEYWORD PARAMETERS: OUTPUTS: A gamma-corrected image. RESTRICTIONS: None. PROCEDURE: The gamma correction is implemented as x^gamma. MODIFICATION HISTORY: Written 14-Jul-2008 by Bill Davis
NAME:
GETIMAGE
PURPOSE:
The purpose of this function is to allow the user to open either
regular or XDR binary image files of two or three dimensions.
CATEGORY:
Image Processing, Widgets, File I/O
CALLING SEQUENCE:
image = GETIMAGE(filename)
INPUTS:
filename: The name of the file to open for reading.
KEYWORD PARAMETERS:
CANCEL: An output variable that can be set to a named variable.
The value of the return variable will be 1 if the user clicked
the "Cancel" button or if there was a problem reading the file.
DIRECTORY: The name of the directory the file is located in. By
default the program looks in the "training" directory under the
main IDL directory, if one exists. Otherwise, it defaults to the
current directory.
FRAMES: The 3rd dimension of a 3D data set. Defaults to 0.
HEADER: The size of any header information in the file in BYTES.
Default is 0.
PARENT: The group leader for this widget program. The PARENT is
required if GETIMAGE is called from another widget program.
XDR: Set this keyword if the binary file is of XDR type.
XOFFSET: This is the X offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
XSIZE: The size of the 1st dimension of the data.
YOFFSET: This is the Y offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
YSIZE: The size of the 2nd dimension of the data.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A "CANCEL" operation is indicated by a 0 return value.
Any error in reading the file results in a 0 return value.
RESTRICTIONS:
None.
EXAMPLE:
To load the image "galaxy.dat" in the $IDL/examples/data
directory, type:
image = GETIMAGE('galaxy.dat', DIRECTORY=!DIR + '/examples/data', $
XSIZE=256, YSIZE=256, Cancel=cancelled, Parent=event.top)
IF NOT cancelled THEN TV, image
MODIFICATION HISTORY:
Written by: David Fanning, 3 February 96.
Fixed bug that prevented reading INTEGER data. 19 Dec 96.
Modifed program for IDL 5 MODAL operation. 19 Oct 97.
Added CANCEL keyword. 27 Oct 97. DWF.
Fixed CANCLE keyword spelling. Sigh... 29 JUN 98. DWF.
NAME:
imageproc
PURPOSE:
Demonstrate a few of IDL's image processing features:
Fourier filtering, pixel scaling, pixel distribution
(histogram), edge enhancement, dilate & erode,
convolution, and zooming.
CATEGORY:
Image Processing, 2-D Plotting
CALLING SEQUENCE:
IDL> imageproc
INPUTS:
input = a 2-D image (optional, otherwise will pop dialog for tiff file
KEYWORD PARAMETERS:
NColors - # of colors to use
Bottom - value to add to bytescaled image
magnification - magnification factor desired for image
INTERP - if magnification set, INTERP=1 will cause interpolation
XSIZE - xsize of displayed image
YSIZE - ysize of displayed image
REFERENCE: IDL Reference Guide, IDL User's Guide
NAMED STRUCTURES:
none.
COMMON BLOCS:
none.
MODIFICATION HISTORY:
July, 2004 a few more additions [BD]
23-Jan-00 Modified from RSI d_imageproc by Bill Davis.
d_imageproc Written by: DC, RSI, 1995
NAME:
shockvstime
PURPOSE:
Stack plots of a line from the center of .cin file image at various
times See http://nstx.pppl.gov/nstx/Software/Help/shockwaves.html for
sample images. After plotting, you will be prompted for times for which
calculate the speed of the leading edge of the shockwave.
CATEGORY:
Image Processing, CINE files.
CALLING SEQUENCE:
IDL> shockvstime, filename
INPUTS:
filename - a .cin file
KEYWORD PARAMETERS:
INPUTS:
filename - .cin filename
title - will default to 'Shock Wave at various times'
times - times entered in msec (are seconds in file)
jline - vertical index in image to use for line plot. Defaults to 25
addIn - vertical space between plots
inc - increment between files to plot (defaults to 1, which plots all)
gradient - if set, uses a gradient color palette
flatFrac - see leadingedge.pro
deltaPercent - see leadingedge.pro
edge - if set, draw symbol at leading edge of shockwave (defined by
point of increase after a long flat portion.
cmPerPixel - centimeters per pixel (Default=0.2423)
debug - if set, will stop
RETURNED:
allData - returns all the data within the time specified
OUTPUTS:
none.
EXAMPLE:
To get a postscript file:
IDL> setup_ps, filename='shockvstime.ps', /color
IDL> shockvstime
IDL> unsetup_ps
surftime=findgen(145)/145*(0.00119100-0.000773)*1000 +1.191
surfx =findgen(128)
surf = interpPeak(allData)
for j=1,2 do surf = interpPeak(surf)
save,surfx,surfTime,surf, file='Surf_50ma.sav'
shockvstime, /edge, inc=3
MODIFICATION HISTORY:
18-Jun-2009 Written by Bill Davis, PPPL, for Lane Roquemore
NAME:
xsectionw
PURPOSE:
Widget to display an image and x-y plots of cross-sections.
Color palettes may be loaded, adjusted and saved.
Images can be saved as 'jpg','tif','tif','bmp','jpeg,'png', 'ppm',
'pgm', or 'gif'
CATEGORY:
Image Processing, 2-D Plotting, Files, Graphics
CALLING SEQUENCE:
IDL> xsectionw[[, image], x, y]
INPUTS:
image - a 2D array. If missing, and Keyword Filename not
specified, a dialog box will appear allowing browsing
for a TIFF image.
x & y are optional inputs for x & y axes. Must be same dimension as image.
KEYWORD PARAMETERS:
(optional)
filename - file to read (can be type 'jpg','tif','tif','bmp',
'jpeg,'png','ppm', 'pgm', or 'gif')
xvals - optional values for X axis
yvals - optional values for Y axis
title - title to display at top of plot (Defaults to filename, if relevant)
xsize - horizontal size of window (default is 0.75 of screen, but > 800)
ysize - vertical size of window
xoffset - initial horizontal offset of the widget (DEFAULT=0)
yoffset - initial vertical offset of the widget (DEFAULT=30)
INTERP - if magnification set, INTERP=1 will cause interpolation,
rather than pixel replication.
max_colors - # used by display (Default is 256)
NOLOAD - if set, do not load color table
colorTable - color table to use. Default is 03 (Hot Metal)
NoCont - if set, no contours are drawn (default)
file - color table file (for personal color tables)
(other keywords to th_image_cont.pro may be included)
GROUP_LEADER - Group_Leader ID
OUTPUTS:
none.
COMMON BLOCKS:
none
ROUTINES USED:
MK_COLOR, usingXwindows, NWORDS, FLIP
EXAMPLE:
IDL> xsectionw, dist(200,200)
IDL> xsectionw, '/u/bdavis/FTP/nstx000113723_90.tif'
For serious testing of zooming, etc.:
IDL> x=findgen(120)/120
IDL> y=findgen(50)*!PI
IDL> d=sin(x*6+1)#cos(y/20+2)
IDL> d[20:30,*]=-2
IDL> d[*,35:40]=.5
IDL> d=d*1000
IDL> d=d-min(d)
IDL> th_image_cont,d,x,y
IDL> xsectionw,d,x,y
NOTES:
If you specify max_colors to be something other than 256, and
want to change color tables, you need to do something like:
IDL> dum=MK_COLOR( table=3 )
Using XLOADCT, etc. won't work well, since it loads 256 colors.
MODIFICATION HISTORY:
27-Nov-2013 handle input image file name
05-Nov-2013 list location of click line in x-y plot titles
23-Sep-2013 increase left margin when y-axis has exponents. Added
/drag to xcolors call, so colors updated when drag slider
22-Oct-2010 Fixed a couple of bugs opening new images
05-Jan-2010 Default to just red component for true color images, but COMPONENT
keyword added to override this.
18-Aug-2009 fixed bug in zooming
24-Jun-2009 added xrange, yrange, and zrange keywords
30-Sep-2008 just use channel 0 of 24-bit images
14-Jul-2008 Handle 24-bit color images (poorly, but doesn't bomb)
25-Apr-07 Added more modify color table options, and option to save color table.
Support more kinds of image files. Can set background color from menu.
Can save image or window to files. Added Median Smoothing opt
25-May-06 added noload keyword
02-May-06 fixed x-y plot axis limits when zoomed in
12-Apr-06 added x & y keywords, and made to work with resizing and drawing box
03-Feb-03 Option to force lines to black or white
11-Dec-01 Written by Bill Davis, PPPL
Category: Interpolation
[List of Routines]
NAME:
interp2dfit
PURPOSE:
fit irregularly-spaced x, y, & z points by fitting a 2-D surface
using SFIT, and, using the returned coefficients, compute new
values at other irregularly-spaced locations.
CATEGORY:
Interpolation
CALLING SEQUENCE:
IDL> zWant = interp2dfit( x, y, z, Xwant, Ywant, surfaceOut=surfaceOut )
INPUTS:
x, y, z - randomly-spaced points
Xwant, Ywant - X & Y points at which to compute new points
KEYWORD PARAMETERS:
Inputs:
degree - degree of polynomial passed to SFIT (default=6)
plot - if set, will plot data and surfaces so you can see
if fit is reasonable
gtzero - if set, will force all values to be greater than 0
NXout - # of X points to use for fitted surface, and in returned array
NYout - # of Y points to use for fitted surface, and in returned array
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
Zwant - (returned value) interpolated values at Xwant & Ywant
KX - coeficients of polynomial fit, returned from SFIT.
surfaceOut - 2-D grid to which irregular points were interpolated
EXAMPLE:
; get randomly-spaced x, y, & z values:
IDL> restore,'/u/bdavis/cvs/idl_cvs/interp2dfiteg.sav'
IDL> minx = MIN( x, MAX=maxx )
IDL> miny = MIN( y, MAX=maxy )
IDL> XWant = randomu(seed,200)*(maxX-minX) + minX ; more points make smoother plots
IDL> YWant = randomu(seed,200)*(maxY-minY) + minY
IDL> Zwant = interp2dfit( x, y, z, Xwant, Ywant, /gtZero, /plot )
NOTES:
Polynomial fits can be way off beyond the edges of the data.
(Probably should pass in as a parameter the 100 currently used
to make the interpolated surface)
MODIFICATION HISTORY:
22-Aug-2012 fix bug when plotting, but not returning regsurf
15-May-2010 Use Xwant and Ywant for output array
WRITTEN 17-Jan-2010 by Bill Davis for Manny Manickam
NAME:
interp2d
PURPOSE:
Perform bilinear 2d interpolation using the IDL intrinsic
interpolate procedure
CATEGORY:
Interpolation
CALLING SEQUENCE:
result = interp2d(A,x0,y0,x1,y1)
result = interp2d(A,x0,y0,x1,y1,/grid)
result = interp2d(A,x0,y0,x1,y1,/regular,/cubic)
result = interp2d(A,x0,y0,x1,y1,missing=missing)
INPUTS:
A = 2d array to interpolate
x0 = Values that correspond to A(0,0), A(1,0), ...
y0 = Values that correspond to A(0,0), A(0,1), ...
x1 = New X values at which A should be interpolated
y1 = New Y values at which A should be interpolated
OPTIONAL INPUTS:
nxny = [nx,ny] Vector of length 2 which specifies the size of
the regular linearized grid produced with trigrid. The
default is nxny = [51,51]. If the size of A is much larger
than 51 by 51, greater accuracy may be obtained by having
nxny = [n_elements(A(*,0),n_elements(A(0,*))]
OPTIONAL INPUT KEYWORDS:
grid= If set, return an n_elements(X1) by n_elements(y1) grid
missing = Value to points which have X1 gt max(X0) or X1 lt min(X0)
and the same for Y1.
quintic = If set, use smooth interpolation in call to trigrid
regular = If set, do not call trigrid -- x0 and y0 must be linear.
cubic = If set, use cubic convolution
extrapolate = If set, then extrapolate beyond boundary points
bin = set to bin data prior to interpolation.
(e.g. bin=2 interpolate every second pixel)
Returned:
result = a vector N_elements(X1) long
or, if /grid is set
result = an array that is N_elements(X1) by N_elements(Y1)
PROCEDURE:
First call the IDL intrinsic routines TRIANGULATE & TRIGRID to make
sure that X0 and Y0 are linear (if /regular is not set).
Then call the IDL intrinsic INTERPOLATE to do bilinear interpolation.
RESTRICTIONS:
X0 and Y0 must be linear functions.
A must be a 2-d array
HISTORY:
9-mar-94, J. R. Lemen LPARL, Written.
20-Jan-95, JRL, Added the REGULAR & CUBIC keywords
6-Sept-97, Zarro, GSFC, allowed for 2-d (X-Y) coordinate inputs
22-Apri-99, Zarro, SM&A/GSFC - added /triangulate and made /regular
the default (much faster).
NAME:
interpwf
PURPOSE:
Interpolate MDS signal, or array, to 1 KHz.
CATEGORY:
Interpolation
CALLING SEQUENCE:
IDL> data1KHz = interpwf( inData, time=intime, OUTTIME=outTime)
or
IDL> data1KHz = interpwf( sigName )
INPUTS:
inData - data array or MDSplus signal name
KEYWORDS:
intime - timebase of input. If not present will get dim_of(inData)
dt - delta time desired of output. Default to 1.0e-3 (1 KHz)
TSTART - start time desired. If not present, =0.0
TSTOP - last output time desired. If not present = max(inTime)
Returned
outTime - timebase of desired output array.
EXAMPLES:
(works with just arrays, if time present:)
IDL> data1KHz = interpwf(findgen(3000), time=findgen(3000)/(3000)*1.2, $
OUTTIME=outTime)
IDL> mdsopen, 'engineering', 130000
IDL> wf=interpwf( '\ip1', OUTTIME=outTime, $
tStart=-0.5, tStop=1.5 )
IDL> data=mdsvalue('\ip1')
IDL> time=mdsvalue('dim_of(\ip1)')
IDL> plot, time, data
IDL> oplot, outTime, wf, color=colorsearch('red')
LIMITATION:
If a signal name is passed in, assume the tree is already open
MODIFICATION HISTORY:
13-Feb-2009 do everything in IDL
27-Jun-2008 Convert to Linux
06-Apr-06 made default endtime lesser of input and output time
05-Jul-00 Written by Bill Davis, PPPL
NAME:
LINTERP
PURPOSE:
Linearly interpolate tabulated 1-d data from one grid to a new one.
CATEGORY:
Interpolation
EXPLANATION:
The results of LINTERP are numerically equivalent to the RSI
INTERPOL() function, but note the followign:
(1) LINTERP is a procedure rather than a function
(2) INTERPOL() extrapolates beyond the end points whereas LINTERP
truncates to the endpoints (or use the MISSING keyword)
(3) LINTERP (unlike INTERPOL) uses the intrinsic INTERPOLATE function
and thus may have a speed advantage
Use QUADTERP for quadratic interpolation.
CALLING SEQUENCE:
LINTERP, Xtab, Ytab, Xint, Yint, [MISSING =, /NoInterp ]
INPUT PARAMETERS:
Xtab - Vector containing the current independent variable grid.
Must be monotonic increasing or decreasing
Ytab - Vector containing the current dependent variable values at
the XTAB grid points.
Xint - Scalar or vector containing the new independent variable grid
points for which interpolated value(s) of the dependent
variable are sought.
OUTPUT PARAMETERS:
Yint - Scalar or vector with the interpolated value(s) of the
dependent variable at the XINT grid points.
YINT is double precision if XTAB or YTAB are double,
otherwise YINT is REAL*4
OPTIONAL INPUT KEYWORD:
MISSING - Scalar specifying YINT value(s) to be assigned, when Xint
value(s) are outside of the range of Xtab. Default is to
truncate the out of range YINT value(s) to the nearest value
of YTAB. See the help for the INTERPOLATE function.
/NoINTERP - If supplied then LINTERP returns the YTAB value(s)
associated with the closest XTAB value(s)rather than
interpolating.
EXAMPLE:
To linearly interpolate from a spectrum wavelength-flux pair
WAVE, FLUX to another wavelength grid defined as:
WGRID = [1540., 1541., 1542., 1543., 1544, 1545.]
IDL> LINTERP, WAVE, FLUX, WGRID, FGRID
FGRID will be a 6 element vector containing the values of FLUX
linearly interpolated onto the WGRID wavelength scale
PROCEDURE:
Uses TABINV to calculate the effective index of the values
in Xint in the table Xtab. The resulting index is used
with the intrinsic INTERPOLATE function to find the corresponding
Yint value in Ytab. Unless the MISSING keyword is supplied, out
of range Yint values are truncated to the nearest value of Ytab.
PROCEDURES CALLED:
TABINV, ZPARCHECK
MODIFICATION HISTORY:
Adapted from the IUE RDAF, W. Landsman October, 1988
Modified to use the new INTERPOLATE function June, 1992
Modified to always return REAL*4 October, 1992
Added MISSING keyword August, 1993
Converted to IDL V5.0 W. Landsman September 1997
Added NoInterp keyword W. Landsman July 1999
Category: Math
[List of Routines]
NAME:
dt_nicenumber
PURPOSE:
Makes nice delta time numbers, by rounding to 3 significant digits
Can be used if you want to know if you have a constant timebase.
CATEGORY:
Math, Graphics
CALLING SEQUENCE:
niceDts = dt_nicenumber( dts )
INPUTS:
dts - an array of numbers
KEYWORD PARAMETERS:
Optional Inputs:
nSignificantDigits - number of significant digits to round to
(defaults to 3)
Optional Outputs:
nDecimals - number of significant decimal places in returned value
EXAMPLE:
IDL> dt=[2.0003,2.15,.2003,.20009,22.0004,.250002,.5001,100000.1]
IDL> print, dt_nicenumber(dt)
2.00000 2.15000 0.200000 0.200000 22.0000 0.250000
0.500000 100000.
IDL> print, dt_nicenumber( -1.876e6 )
NOTES:
see nicenumber.pro to round to numbers like 1, 2, 2.5, 5, etc.,
which might be time intervals for older digitizer rates.
HISTORY:
13-May-2011 fixed bug
20-Apr-2011 handle arrays
05-Nov-2008 corrected for numbers like -1.876e6
26-Sep-2005 fixed nToShift for nums less than zero (like 0.0016)
26-Jul-04 work OK for 0
03-Nov-00 Rewrote [BD]
NAME:
FACTOR
PURPOSE:
Find prime factors of a given number.
CATEGORY:
Math
CALLING SEQUENCE:
FACTOR, x, p, n
INPUTS:
x = Number to factor, scalar positive integer
OUTPUT PARAMETERS:
p = Array of prime numbers.
n = Count of each element of p.
INPUT KEYWORD PARAMETER:
/HELP - Display help documentation
PROCEDURES USED:
PRIME()
Also see numfactors, print_fact in the JHUAPL Library
MODIFICATION HISTORY:
R. Sterner. 4 Oct, 1988.
RES 25 Oct, 1990 --- converted to IDL V2.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
Converted to IDL V5.0 W. Landsman September 1997
NAME:
GAUSSIAN
PURPOSE:
Compute the 1-d Gaussian function and optionally the derivative
CATEGORY:
Math
EXPLANATION:
Compute the 1-D Gaussian function and optionally the derivative
at an array of points.
CALLING SEQUENCE:
y = gaussian( xi, parms,[ pderiv ])
INPUTS:
xi = array, independent variable of Gaussian function.
parms = parameters of Gaussian, 2 or 3 element array:
parms(0) = maximum value (factor) of Gaussian,
parms(1) = mean value (center) of Gaussian,
parms(2) = standard deviation (sigma) of Gaussian.
(if parms has only 2 elements then sigma taken from common).
OPTIONAL OUTPUT:
pderiv = optional output of partial derivatives,
computed only if parameter is present in call.
pderiv(*,i) = partial derivative at all xi absisca values
with respect to parms(i), i=0,1,2.
Function returns array of Gaussian evaluated at xi.
EXAMPLE:
Evaulate a Gaussian centered at x=0, with sigma=1, and a peak value
of 10 at the points 0.5 and 1.5. Also compute the derivative
IDL> f = gaussian( [0.5,1.5], [10,0,1], DERIV )
==> f= [8.825,3.25]. DERIV will be a 2 x 3 array containing the
numerical derivative at the two points with respect to the 3 parameters.
COMMON BLOCKS:
common gaussian, sigma
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
Converted to IDL V5.0 W. Landsman September 1997
NAME:
ndecimals
PURPOSE:
returns the number of non-zero digits after decimal point.
ignores insigificant bits (in principle)
CATEGORY:
Math, Graphics
CALLING SEQUENCE:
n = ndecimals( num )
INPUTS:
num - a number
KEYWORD PARAMETERS:
Optional Inputs:
nSignificantDigits - max number of decimals to consider
(defaults to 3 decimals)
EXAMPLE:
IDL> print, ndecimals(1.40001)
1
IDL> print, ndecimals(1.123001,nsig=2)
2
IDL> print, ndecimals(1.123001 )
3
IDL> print, ndecimals('36.123456')
6
HISTORY:
21-Sep-2012 fixed bug for 1.434001 & '36.123456'
03-Mar-2011 Written [BD]
NAME:
NICENUMBER
PURPOSE:
Find a "nice" number close to the given number. Actually, this
is for older digitizers, so "rounds" to numbers like
1, 2, 2.5, 5, etc.
CATEGORY:
Math
CALLING SEQUENCE:
n = nicenumber(x)
INPUTS:
x = given number. in
KEYWORD PARAMETERS:
Keywords:
/FLOOR finds next nice number le to X.
/CEIL finds the next nice number ge to X.
MINOR=m Returned suggested minor tick spacing.
OUTPUTS:
n = nice number close to x. out
1, 2, 2.5, or 5 scaled to size of x.
COMMON BLOCKS:
NOTES:
Notes:
Default operation is useful for finding tick spacings:
dx = nicenumber((xmx-xmn)/nticks).
/FLOOR and /CEIL are useful for scaling data plots:
xmn = nicenumber(min(x),/floor)
xmx = nicenumber(max(x),/ceil)
plot, x, y, xrange=[xmn,xmx], . . .
/floor and /ceil may not give values related to the
step size, dx. The following method will:
ceil(t/dx)*dx is a multiple of dx on the high side of t.
floor(t/dx)*dx is a multiple of dx on the low side of t.
Use DT_NICENUMBER.PRO to "round" to a specific number of digits.
MODIFICATION HISTORY:
20-Apr-2011 fix for array starting with zero, like;
[ 0.0, 5.0e+15, 1.0e+16 ]
17-Feb-00 handle 190KHz ! (Bill Davis)
R. Sterner, 6 Feb, 1990
R. Sterner, 27 Jan, 1993 --- dropped reference to array.
R. Sterner, 12 Feb, 1993 --- returned 1 element array as a scalar.
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
PRIME
PURPOSE:
Return an array with the specified number of prime numbers.
CATEGORY:
Math
EXPLANATATION:
This procedure is similar to PRIMES in the standard IDL distribution,
but stores results in a common block, and so is much faster
CALLING SEQUENCE:
p = prime(n)
INPUTS:
n = desired number of primes, scalar positive integer
OUTPUTS:
p = resulting array of primes, vector of positive integers
COMMON BLOCKS:
prime_com
NOTES:
Note: Primes that have been found in previous calls are
remembered and are not regenerated.
MODIFICATION HISTORY:
R. Sterner 17 Oct, 1985.
R. Sterner, 5 Feb, 1993 --- fixed a bug that missed a few primes.
Converted to IDL V5 March 1999
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
PSF_GAUSSIAN
PURPOSE:
Create a 1-d, 2-d, or 3-d Gaussian with specified FWHM, center
CATEGORY:
Math
EXPLANATION:
Return a point spread function having Gaussian profiles,
as either a 1D vector, a 2D image, or 3D volumetric-data.
CALLING SEQUENCE:
psf = psf_Gaussian( NPIXEL=, FWHM= , [/NORMALIZE, /ST_DEV, )
or:
psf = psf_Gaussian( parameters, NPIXEL = )
REQUIRED INPUT KEYWORD:
NPIXEL = number pixels for each dimension, specify as an array,
or just one number to make all sizes equal.
OPTIONAL KEYWORDS:
NDIMEN = dimension of result: 1 (vector), 2 (image), or 3 (volume),
default = 2 (an image result).
FWHM = the desired Full-Width Half-Max (pixels) in each dimension,
specify as an array, or single number to make all the same.
CENTROID = pixels numbers of PSF maximum ( 0.5 is center of a pixel ),
default is exact center of requested vector/image/volume.
STDEV = optional way to specify width by standard deviation param.
XY_CORREL = scalar between 0 and 1 specifying correlation coefficient
Use this keyword, for example, to specify an elliptical
gaussian oriented at an angle to the X,Y axis
/NORMALIZE causes resulting PSF to be normalized so Total( psf ) = 1.
INPUTS (optional):
parameters = an NDIMEN by 3 array giving for each dimension:
[ maxval, center, stdev ], overrides other keywords.
EXAMPLE:
Create a 31 x 31 array containing a normalized centered gaussian
with an X FWHM = 4.3 and a Y FWHM = 3.6
IDL> array = PSF_GAUSSIAN( Npixel=31, FWHM=[4.3,3.6], /NORMAL
EXTERNAL CALLS:
function Gaussian
HISTORY:
Written, Frank Varosi NASA/GSFC 1991.
Converted to IDL V5.0 W. Landsman September 1997
NAME:
runTot
PURPOSE:
compute a running total of an array by calling an external routine
(this is inefficient in normal IDL)
CATEGORY:
Math
CALLING SEQUENCE:
IDL> outarray = runTot(inarray)
INPUTS:
inarray = a numeric array.
KEYWORD PARAMETERS:
Keywords:
HLP - When set, help information is printed.
OUTPUTS:
outarray = returned array of running total out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> print, runtot(findgen(10))
IDL> MDSOPEN, 'operations', 100601
IDL> ip = MDSVALUE( '\operations::ip_ipf1b_1' )
IDL> V = runTot( ip )
NOTES:
When the routine is called with no parameters, or with the
keyword hlp set, help information is printed.
MODIFICATION HISTORY:
04-Oct-99 Written by Bill Davis, PPPL
NAME:
SDEV
PURPOSE:
Returns standard deviation of an array.
CATEGORY:
Math
CALLING SEQUENCE:
s = sdev(a)
INPUTS:
a = input array. in
KEYWORD PARAMETERS:
OUTPUTS:
s = standard deviation of a. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
01-Aug-00 Commented-out checks for a major speed up. [BD]
Written by K. Kostoff, 1/16/85
Johns Hopkins University Applied Physics Laboratory.
Modified by B. Gotwols, R. Sterner --- 1 Oct, 1986.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
SIGN
VERSION:
3.0
PURPOSE:
Gives the sign of X, i.e. 1 for positive, -1 for negative, 0 for 0.
CATEGORY:
Math
CALLING SEQUENCE:
Result = SIGN(X)
INPUTS:
X
Numerical, otherwise arbitrary.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the value of SIGN(X), see above, as an long integer.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
For complex X the result is SIGN(REAL(X)), the imaginary part is ignored
PROCEDURE:
Straightforward. Using CAST from MIDL.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Modified 25-DEC-1991 by Mati Meron.
Modified 5-DEC-1993 by Mati Meron. Output type changed to LONG.
NAME:
sigx
PURPOSE:
Compute horizontal extent of blob along center axis, from
edge to edge, given theta, and the two radii.
Equation from Jim Myra
CATEGORY:
Math
CALLING SEQUENCE:
IDL> sigx = sigx( theta, radius1, radius2 )
INPUTS:
theta - radians clockwise, from zero to the horizontal left
radius1 -
radius2 -
RETURNED:
distance from center, horizontally, to edge of ellipse
will be in the same units as the input radii
TESTING:
IDL> print, sigx( .5, 6, 6)
12.00000
IDL> print, sigx( 1.5, 6, 6)
12.00000
IDL> print, sigx( 0, 10, 5)
20.0000
IDL> print, sigx( !pi/2, 10, 5)
10..00000
IDL> print, sigx( !pi/4, 10, 5)
12.6491
MODIFICATION HISTORY:
23-Jun-2015 return distance from edge to edge, rather than center to edge
16-Jun-2015 Written by Bill Davis, PPPL, for Stewart Zweben
NAME:
sigy
PURPOSE:
Compute vertical extent of blob from edge to edge along center axis
given theta, and the two radii. The units of the result will be
the same as the units of radius1 & radius2.
Equation from Jim Myra
CATEGORY:
Math
CALLING SEQUENCE:
IDL> sigy = sigy( theta, radius1, radius2 )
INPUTS:
theta - radians clockwise, from zero to the horizontal left
radius1 -
radius2 -
RETURNED:
distance from center, vertically, to edge of ellipse
will be in the same units as the input radii
TESTING:
Can be tested with testfcfitellipse.pro
IDL> print, sigy( .5, 6, 6 )
12.0000
IDL> print, sigy( 2.35, 15, 10 )
23.5902
IDL> print, sigy( 0, 15, 10 )
20.0000
MODIFICATION HISTORY:
23-Jun-2015 return distance from edge to edge, rather than center to edge
16-Jun-2015 Written by Bill Davis, PPPL, for Stewart Zweben
NAME:
TWOSCOMPLEMENT
PURPOSE:
Taking the Two's Complement of an integer
CATEGORY:
Math, Hardware, CAMAC
CALLING SEQUENCE:
twoscomp = TwosComplement( int )
INPUT:
int - raw encoder value (8, 16 or 32 bit integer)
OUTPUT:
twoscomp - Two's complement of input.
KEYWORDS:
Optional Input:
NBITS - # of bits; throw away this bit if there is a carry after
adding 1 to the complement. Default is determined by data type.
IfNeg - Only return the Two's Complement if value negative
ALGORITHM:
Taking the Two's Complement of a k-Digit Bitstring:
1.Complement the bitstring; i.e., change all 0s to 1s and all 1s to 0s; retain all leading 0s in your result.
2.Add 1 to this binary number (if there is a carry of 1 into the (k+1)st position, throw it away so that the
result is still k-digits).
3.The result from (2) is the two's complement of the bitstring
COMMENT:
Works in many cases, but sign bit may get extended in some applications
MODIFICATION HISTORY:
5-Jun-00 WMD Added Nbits & IfNeg Keywords
Category: MDSplus
[List of Routines]
NAME:
addLabelNodes
PURPOSE:
Add LABEL sub-nodes to MDSplus signal nodes reading info from a file
CATEGORY:
MDSplus, TCL
CALLING SEQUENCE:
addLabelNodes, shot1, shot2, filename=filename
INPUTS:
shot1 = starting shot number to process (defaults to last shot)
shot2 = last shot number to process (optional)
KEYWORDS:
filename - name of file with info - REQUIRED,
see, e.g., BDAVIS$:[CVS.MISC.WF]tauslabel.dat
the file must contain 4 columns, separated by white space.
the first column is the tagname (without \), the last column is
the Label text enclosed in double quotes. The middle columns
can be any single word or character (file format from another
application).
tree - name of tree -- defaults to 'WF'
COMMON BLOCKS:
NONE
NOTES:
YOU NEED PRIVILEGES to write to the MDSplus tree.
LIMITATIONS:
MODIFICATION HISTORY:
25-Jan-01 Written by Bill Davis.
NAME:
addmdstags
PURPOSE:
Add tags to MDSplus nodes
PROCEDURE:
CATEGORY:
MDSplus, Summary
CALLING SEQUENCE:
addmdstags, shot=shot, nodes=nodes, tags=tags
INPUTS:
KEYWORDS:
shot - shot number to process
nodes - MDSplus node names to which tag will added (all in same tree)
tags - to add
VERBOSE - if set, more info is printed
test - doesn't write to MDSplus
EXAMPLE:
nodes = ['\PASSIVESPEC::TOP.IR.IMG0.RAWDATA.IR_408:TIMES', $
'\PASSIVESPEC::TOP.IR.IMG1.RAWDATA.IR_408:TIMES', $
'\PASSIVESPEC::TOP.IR.IMG2.RAWDATA.IR_408:TIMES' ]
tags = ['img0_408_times', 'img1_408_times', 'img2_408_times' ]
addmdstags, shot=128000, nodes=nodes, tags=tags, /verb, /test
for i=shot1,shot1+499 do addmdstags, shot=i, nodes=nodes, tags=tags, /verb
NOTES:
YOU NEED PRIVILEGES to write to the MDSplus tree.
LIMITATIONS:
Divide by zeroes, etc. will cause a message like:
% Program caused arithmetic error: Floating illegal operand
MODIFICATION HISTORY:
27-Mar-2008 Written by Bill Davis.
NAME:
addsignodes
PURPOSE:
Add signal nodes and tags to a MDSplus tree for many shots
PROCEDURE:
CATEGORY:
MDSplus
CALLING SEQUENCE:
addsignodes, shot1, shot2, tags=[tag1,tag2,tag3,...]
INPUTS:
shot1 = starting shot number to process
shot2 = last shot number to process
KEYWORDS:
tags - tags to add (if defined in the model tree, you
will not need to specify the corresponding nodes).
nodes = if tags are not defined in the model tree, these are necessary
tree - MDSplus tree
usage - for MDSTCL node creation. Default='signal'
VERBOSE - if set, more info is printed
test - doesn't write to MDSplus
NOTES:
YOU NEED PRIVILEGES to write to the MDSplus tree.
LOGIC:
finds node names for tags. Then, if node names are not different
than the "tag" names, does not add tags.
LIMITATIONS:
all signals must be in the same tree
MODIFICATION HISTORY:
11-Apr-07 changed for Linux (add output= to mdstcl)
13-Jun-02 Written by Bill Davis.
NAME:
addTreeToTag
PURPOSE:
return tags with trees merged in
CATEGORY:
MDSplus, SCOPE
CALLING SEQUENCE:
names = addTreeToTag( tags, trees )
INPUTS:
tags - array of tags, e.g., '\ip1' (if tree already there, will not change)
trees - array of trees (same dimension as tags)
RETURNED:
names - tag names with tree in them, e.g., '\engineering::ip1'
KEYWORDS:
COMMON BLOCKS:
none
EXAMPLE:
IDL> print, addTreeToTag( ['\ip1+\ip2'], ['engineering'] )
\engineering::ip1+\engineering::ip2
IDL> print, addTreeToTag( ['\engineering::ip1.blah+\ip2'], ['engineering'] )
\engineering::ip1.blah+\engineering::ip2
LIMITATIONS:
MODIFICATION HISTORY:
30-Apr-01 Written by Bill Davis
NAME:
BreakMDSname
PURPOSE:
break an MDS pathname near the middle, if too long
CATEGORY:
MDSplus, Strings
CALLING SEQUENCE:
newLines = BreakMDSname( line )
INPUTS:
line - string containing an MDSplus tag or node name in
KEYWORD PARAMETERS:
MAXLENGTH - max line length (default 72) OPTIONAL
OUTPUTS:
newlines - string array of MDSplus name broken near middle
EXAMPLE:
IDL> line = '\ENGINEERING::OPERATIONS.PC_OH_BR_1_CUR_1'
IDL> newLines = BreakMDSname( line, MAXLENGTH=25 )
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
01-Apr-99 Written earlier by Bill Davis
NAME:
BREAK_PATH
PURPOSE:
Breaks up a path string into its component directories.
CATEGORY:
MDSplus, Strings
CALLING SEQUENCE:
Result = BREAK_PATH( PATHS [ /NoCurrent])
INPUTS:
PATHS = A string containing one or more directory paths. The
individual paths are separated by commas, although in UNIX,
colons can also be used. In other words, PATHS has the same
format as !PATH, except that commas can be used as a separator
regardless of operating system.
A leading $ can be used in any path to signal that what follows
is an environmental variable, but the $ is not necessary. (In
VMS the $ can either be part of the path, or can signal logical
names for compatibility with Unix.) Environmental variables
can themselves contain multiple paths.
OUTPUT:
The result of the function is a string array of directories.
Unless the NOCURRENT keyword is set, the first element of the array is
always the null string, representing the current directory. All the
other directories will end in the correct separator character for the
current operating system.
OPTIONAL INPUT KEYWORD:
/NOCURRENT = If set, then the current directory (represented by
the null string) will not automatically be prepended to the
output.
PROCEDURE CALLS:
Functions: DATATYPE(), breakstring()
REVISION HISTORY:
Version 1, William Thompson, GSFC, 6 May 1993.
Added IDL for Windows compatibility.
Version 2, William Thompson, GSFC, 16 May 1995
Added keyword NOCURRENT
Version 3, William Thompson, GSFC, 29 August 1995
Modified to use OS_FAMILY
Version 4, Zarro, GSFC, 4 August 1997
Added trim to input
Converted to IDL V5.0 W. Landsman 25-Nov-1997
NAME:
checkMDStree
PURPOSE:
Check MDS trees, say after a transfer. Produce a file with a
list of nodes and checksum of contents of each numerical node or first
element of non-numeric nodes.
CATEGORY:
MDSplus, Searching
CALLING SEQUENCE:
IDL> checkMDStree, tree=tree, shot=shot, outFile=outFile
INPUTS:
tree - MDSplus tree.
shot - MDSplus shot to search.
KEYWORD PARAMETERS:
Input (Optional):
server - MDSplus server. Default is the default server for the tree.
outFile - defaults to tree_nnnnnn_server_list.txt
remove - if set, removes the tree::top when listing the node name
Returned (Optional):
status - status from mdsopen call
OUTPUTS:
(Optional):
outFile -
outDir - output dir (DEF='')
EXAMPLE:
IDL> checkMDStree, tree='particles', shot=130000, server='lark:8501', /verb
IDL> checkMDStree, tree='usxr', shot=142000, server='skylark:8501', /verb
NOTES:
MODIFICATION HISTORY:
24-Feb-2011 include any port info into default output filename
01-Oct-2008 add checksum for Alphanumerics, too.
29-Aug-2008 Written by Bill Davis, PPPL
NAME:
checkSig
PURPOSE:
checks for existence of a signal in MDSplus for current shot and
optionally declares an event. It can also execute an IDL string when
it sees the event. It will then start watching for the next shot.
CATEGORY:
MDSplus, Events
CALLING SEQUENCE:
IDL> checksig, tree=tree, sig=sig, event=event
INPUTS:
KEYWORD PARAMETERS:
Inputs:
tree - MDSplus tree (DEFAULT=engineering)
sig - MDSplus signal to look for in current shot
event - MDSplus event to declare (DEFAULT=$USER_test)
logfile - where to write log messages
pause - seconds to pause between checks (default=10 sec)
test - if set, will not set event, only print messages
realVerbose - if set will tell you too much stuff
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
none, just printing
EXAMPLE:
IDL> checksig, tree='engineering', sig='\fdia', event='bdtest'
IDL> checksig, tree='engineering', sig='\fdia', /test,/verb, pause=10
IDL> checksig, sig='\cameras::ph7_1_count', $
exec='cinethumbnails, "*nstx_2_*'+strtrim(lastshot(),2)+'*.cin"'
IDL> checksig, sig='\efit02::r', $
exec='cinethumbnails,findLastFile("/p/nstxcam/Miro2-7988/2010/*.cin")'
15-Apr-2010 alternately can call an IDL routine [BD]
13-Apr-2010 increased default pauses [BD]
WRITTEN by Bill Davis, 01-Apr-2010
NAME:
cp2jScopeFile
PURPOSE:
Copy an MDSplus Scope input file to one that will work with jScope
CATEGORY:
MDSplus, SCOPE
CALLING SEQUENCE:
cp2jScopeFile, fileName, outfile=outfile
INPUTS:
filename - name of scope input filename (else will get a dialog box)
RETURNED:
KEYWORDS:
COMMON BLOCKS:
none
METHOD:
insert lines in variable addLines after line 2 of input file
EXAMPLE:
(list files changed within the last 1000 days)
find . -name "*.scope" -mtime -1000 -print > dirls.txt
find . -name "*.dat" -mtime -1000 -print >> dirls.txt
idl
IDL> files = read_list('dirls.txt')
IDL> for i=0,n_elements( files )-1 do $
IDL> cp2jScopeFile, files[i], outDir='/p/nstxusr/util/jscp'
IDL>
NOTES:
LIMITATIONS:
MODIFICATION HISTORY:
06-Apr-2010 debugged.
03-Nov-2009 Written by Bill Davis
NAME:
eventspawn
PURPOSE:
When a designated MDSplus event is detected, spawn an IDL procedure,
first killing any versions that are running.
CATEGORY:
MDSplus, Program Control
CALLING SEQUENCE:
IDL> eventspawn, event=event, procedure=procedure, server=server, $
immediate=immediate, display=display
INPUTS:
none required, but procedure is probably necessary
KEYWORD PARAMETERS:
Keywords:
event - MDSplus event to wait for (default to NSTX_ACQ_DONE
procedure - file to pass to idl batch command (default is batchmyidl.pro)
ASCII - if set, will assume data block contains ascii representation of numbers
server - MDSplus event server (default is europa.pppl.gov:8501)
immediate - if set, execute procedure even before waiting for event
display - X display to send IDL graphics to.
OUTPUTS:
none
EXAMPLE:
IDL> eventspawn, pro='/u/bdavis/RFcam/batchrfmovie', $
event='RFcamera_loaded', display='nstxwindowspc:0', /immed
LIMITATIONS:
currently, no arguments can be passed to IDL command.
only works on Unix/Linux.
NOTES:
see /u/bdavis/RFcam/batchtedmovie.pro as example of routine to call.
shot numbers must be accessed in the calling programs via LASTSHOT()
or an environmental variable.
MODIFICATION HISTORY:
09-Mar-2007 Added ASCII keyword which is needed on sflip PC
15-Aug-2005 written by Bill Davis
NAME:
fileOnEvent
PURPOSE:
When a designated MDSplus event is detected, write a file containing a shot
number, first deleting existing file.
CATEGORY:
MDSplus, Program Control
CALLING SEQUENCE:
IDL> fileOnEvent, event=event, file=file, server=server,
INPUTS:
none required
KEYWORD PARAMETERS:
Keywords:
event - MDSplus event to wait for (default to NSTX_ACQ_DONE
server - MDSplus event server (default is europa.pppl.gov:8501)
file - default to 'E:/pulse.ini'
OUTPUTS:
none
EXAMPLE:
IDL> fileOnEvent, event='bdtest', file='bdfile.txt'
LIMITATIONS:
NOTES:
MODIFICATION HISTORY:
23-Aug-2010 written by Bill Davis for Doug Darrow
NAME:
FindMDSNodes
PURPOSE:
Search for MDSplus nodes or tags with a name containing a string
CATEGORY:
MDSplus, Search, Utiltiy
CALLING SEQUENCE:
IDL> paths = FindMDSNodes( nodeString, status=status )
INPUTS:
nodeString - string to search nodenames for
KEYWORD PARAMETERS:
nonNodeString - exclude nodes in returned array if this string found in name
tags - if set, just look for nodes with tags, and search tagnames
Scalars - if=0, then only return nodes with more than one data element
JustText - if set, just look for Text nodes (no effect if /TAGS set)
usage - if /TAGS not set, what GETNCI expects
(if used, overrides /JustText; DEFAULT: ANY)
max2find - max # of nodes returned (DEFAULT=10000)
status - success if true (odd number)
debug - print some debugging info
the tree may be opened before this routine is called, or you can specify:
treeName - MDSplus tree. Default='NSTX' (unless embedded in nodeString)
shot - MDSplus shot to search. Default=-1 (the model tree).
returned:
states - string array containing 'OFF' or 'ON'.
isSignal - logical array where 1s indicate corresponding node is a signal
COMPRESS_ON_PUT - logical array
PARENT_STATE - logical array
NUMERIC - logical array
NO_WRITE_MODEL - logical array
NO_WRITE_SHOT - logical array
OUTPUTS:
paths - paths satifying search criteria
COMMON BLOCKS:
none
EXAMPLE:
IDL> paths = FindMDSNodes( 'ip', status=status, tree='wf', shot=120200 )
IDL> tags = FindMDSNodes('*', /tags, tree='lrdfit04', shot=117747)
; exclude some nodes:
IDL> paths = FindMDSNodes( 'ip',non='formula', tree='wf', shot=120200 )
IDL> paths = FindMDSNodes( 'ip',non=['formula','description'], tree='wf', shot=120200 )
IDL> p = FindMDSNodes( 'svd', tree='engineering', shot=142039)
NOTES:
if tree already open before FindMDSNodes is called, tree & shot need not be set.
if no records are found in current tree, returns ['']
LIMITATIONS:
If connect to VMS, will not get tags from trees on Linux.
MODIFICATION HISTORY:
08-Mar-2013 with tree NSTX, must be too many returned when getting all, so use
nodestring in filter.
04-Oct-2012 try with more stars for searches like from engineering tree with
'svd'
06-May-2010 never check more than 2000 nodes for being a signal (too slow)
21-Apr-2010 added keyword max2find
20-Apr-2010 added keyword isSignal & checkSignals
08-May-2009 If /tag set and no tree, use getenv('MACHINE'), and if empty, use
'nstx'.
16-Mar-2009 add Sclars keyword
02-Feb-2009 have to spawn MDSTCL and read it's commands from a file
for big results, like searching for '*' in operations.
19-Jan-2009 don't return names that are blank or have spaces in them
02-Dec-2008 added STATES keyword to return 'OFF' or 'ON'
09-Jan-08 fintags.fun not on Linux, so don't use.
nonNodeString can be an array of strings
22-Nov-06 use MDSTCL for tags on Linux trees. Use mdsopen, instead of
openMDSshot, and only if tree not entered
11-Nov-05 Added keywords for use with new treesearch web page.
31-Jan-01 Written by Bill Davis, PPPL
NAME:
findMDStime
PURPOSE:
find a time within an MDSplus shot, correspoding to
the time of Max Ip, time of Max W-tot, etc.
signals come from the EFIT tree when possible.
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> time = findMDStime( /maxIp )
INPUTS:
shotListString - a string indicating shots,
e.g., 107694 108305 108330-108350
or 108100+20
(this returns shots 108100, 108101,...,108120)
nshots - # of shots to search over (def=10)
KEYWORD PARAMETERS:
maxIp - if set, return time of Max Ip (less 3 msec)
MaxNeutrons - if set, return time of Maximum Neutron production
MaxBetaN - if set, return time of Beta Normal
MaxPTot - if set, return time of maximum heating power
MaxWMHD - if set, return time of maximum Plasma Stored Energy
MaxTAUMHD - if set, return time of maximum Energy confinement time
MaxDENS - if set, return time of maximum Line Density
shot - if set, will return value for this shot, else for opened shot
OUTPUTS:
time in seconds
EXAMPLE:
IDL> time = findMDStime( /maxIp )
NOTES:
if more than one time is found for the max, a median time will be
returned.
MODIFICATION HISTORY:
14-Jun-02 Written by Bill Davis, PPPL
NAME:
findvalidshots
PURPOSE:
Search MDS Plus Trees for valid shot numbers with data in a
particular node
CATEGORY:
MDSplus, Utility
CALLING SEQUENCE:
IDL> findvalidshots ; This is interactive widget version
or IDL> findvalidshots, signal,beginshotnumber,endshotnumber
INPUTS:
none
KEYWORD PARAMETERS:
none
OUTPUTS:
on screen: valid shot numbers in entered range
COMMON BLOCKS:
none
EXAMPLE: IDL>findvalidshots, '\passivespec::vs2.rawdata:spectra',104500,104515
NOTES:
MODIFICATION HISTORY:
01-Oct-2008 Removed mdsconnect [BD]
4-JAN-2001 Written by Dana Mastrovito, PPPL
NAME:
firstSigName
PURPOSE:
Return the first signal name in a TDI expression.
Needed when you want the xaxis from a combination of signals.
CATEGORY:
MDSplus
CALLING SEQUENCE:
sig1 = firstSigName( TDIexpr )
INPUTS:
TDIexpr - TDI expression. Can be just a signal name, or '(\ip1+\ip2)/2'
RETURNED:
sig1 - first signal name in TDI expr, e.g., '\ip1'
KEYWORDS:
Optional Outputs:
FOUNDTDI - 1 returned if TDI in node
DIMENSION - if root node is 2-D, but expression limits to 1.
SECOND - the second signame name in the expression, if any (else '')
Optional Inputs:
DATA = if set, return everything from DATA to ']', if present, or
to ')'
COMMON BLOCKS:
none
EXAMPLE:
IDL> print, firstSigName( '\engineering::ip1+\engineering::ip2' )
\engineering::ip1
LIMITATIONS:
probably won't return proper dimension when DATA() is within a TDI function,
like BCSMOOTH( data( \camera:image, 1) )
MODIFICATION HISTORY:
31-Aug-2007 added keyword SECOND
19-Jun-2007 ONLY return dimension number from syntax like ",1" if
MAXVAL, MINVAL or DATA (others can be included here).
06-Apr-2007 Added data and dimension keywords
to handle style of maxval(\efit01::pisrz,1) and
data(\efit01::pisrz)[10,*] )
01-May-01 Written by Bill Davis
NAME:
FITSRUN
PURPOSE:
Quickly tell which EFITs and LRDFITs exist for an MDSplus shot
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> fits=fitsrun(shot)
INPUTS:
shot - NSTX shot number
KEYWORD PARAMETERS:
maxefits= MAX efits to check
maxlrdfits - max lrdfits to check
quiet - if set to 0, will tell you about each open
realquiet - if set to 0, will tell you about failed opens
needSig - a node that you need in the tree to use that tree
DEFAULT='\CODE_VERSION'
OUTPUTS:
fits - string array like ['EFIT01', 'EFIT03', 'LRDFIT04']
EXAMPLE:
IDL> print,fitsrun(117707, maxefits=5, maxlrdfits=5)
EFIT01 EFIT02 EFIT03 EFIT04 EFIT05 LRDFIT04
IDL> for i=122440,123244 do print, i,' ',fitsrun(i,loadfit='EFIT03')
IDL> fits = fitsrun( 130000, run_by=user, /noLoad )
IDL> fits = fitsrun( 129125, run_by=run_by, comments=comments, $
code_version=code_version, date_run=date_run )
NOTES:
When the routine is called with no parameters,
help information is printed.
To load fits into the code_rundb database used by EFIT and other codes,
see fit_run_loader.pro
MODIFICATION HISTORY:
15-Jan-2015 add checks for efitrt, efitrt_dev, efitrt_ga, efitrt_test
11-Dec-2012 don't let comments be integer (0)
17-Aug-2010 added needSig keyword
22-Jun-2010 added comments, code_version, and date_run keywords [BD]
02-Feb-2010 Added noLoad & run_by keywords
25-May-2007 Just look in EFIT tree for all possible subtrees
12-Apr-2007 Option to load fits into code_rundb database (for efitviewer)
07-Mar-2006 Written by Bill Davis, PPPL
NAME:
foundsubtree
PURPOSE:
determine if sub trees like efit05, lrdfit06, etc. exist
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> found = foundSubTree( shot=shot, tree=tree, index=index)
INPUTS:
none but keywords
KEYWORD PARAMETERS:
shot - MDSplus shot/pulse number
tree - main fit tree, e.g., 'EFIT' or 'LRDFIT'
index - "subtree" version number, 5 would get you 'EFIT05' or 'LRDFIT05'
SERVER - MDS server (default is skylark.pppl.gov:8501 for NSTX)
RETURNED:
status - MDS status from open if failed, else from mdsvalue
OUTPUTS:
found - 1 if found, 0 if not found.
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> print, foundsubtree(shot=117449, tree='efit', index=2 )
MODIFICATION HISTORY:
26-Jun-2006 Written by Bill Davis, PPPL
NAME:
fullMDSpath
PURPOSE:
Return an MDSplus path for a tag
CATEGORY:
MDSplus
CALLING SEQUENCE:
fullpath = fullMDSpath( tag, shot=shot )
INPUTS:
MDSplus tagname
KEYWORD PARAMETERS:
shot - if present, will open NSTX tree for this shot
OUTPUTS:
fullpaths - returns full pathnames of tags found
EXAMPLE:
IDL> mdsopen, 'edge', 129850
IDL> print, fullMDSpath('\BE_H908_01')
\EDGE::TOP.BEAP.RAWDATA:BE_H908_01
NOTES:
Only returns signals with data in them.
LIMITATIONS:
An MDSplus shot file must be open first.
MODIFICATION HISTORY:
17-Jun-2008 use tree in tagname, if present. Add tip, if not found.
14-Mar-00 more efficient & added keywords [BD]
20-Jan-00 Written by Bill Davis
NAME:
getMDSlabel
PURPOSE:
return a label for an MDSplus signal. If there is a :LABEL sub-node,
use that string, else if there is a :COMMENT sub-node, use that, else
return the MDSplus signal name.
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> (the tree has to be opened)
IDL> label=getMDSlabel( signal, textNode=textNode, FOUNDTDI=foundTDI, $
status=status, /quiet, /fullPath )
INPUTS:
signal - mdsplus signal or tag name (shot must be opened)
OUTPUT:
label - contents of :LABEL substring, if found. Otherwise the
signal name is returned (just the last two elements, unless
/fullPath set)
KEYWORD PARAMETERS:
Optional Inputs:
quiet - just passed to mdsvalue
fullPath - if set, return fullpath if no :LABEL subnode found
Optional Outputs:
textNode - 1 returned if a text node
FOUNDTDI - 1 returned if TDI in node
status - if odd, successfull
NOTES:
The relevant MDSplus tree must be open for this routine to work.
MODIFICATION HISTORY:
01-Jun-01 Also look for :COMMENTS sub-node.
11-Mar-01 if no :LABEL node, look for :COMMENT node
15-Feb-01 Written by Bill Davis, PPPL
NAME:
get_nebar
PURPOSE:
Get Ne Bar (line-averaged plasma density at the midplane) from
Multi-point Thomson Scattering data and EFIT gap data.
CATEGORY:
MDSplus, Density
CALLING SEQUENCE:
nebar = get_nebar( shot, time=time )
INPUTS:
shot1 = starting shot number to process
KEYWORDS:
(Optional)
efit - #. Defaults to 2
time - time base of output (sec). Probably on the MPTS timebase
EXAMPLE:
IDL> nebar = get_nebar( 138846, time=time )
NOTES:
This has not been verified by the MPTS Cognizant Physicist
HISTORY:
08-May-2014 fixed bug in goodTimes determination
WRITTEN 23-Jul-2013, by Bill Davis for Stewart Zweben
NAME:
getScopeNames
PURPOSE:
return signal names and plot settings from an MDSplus Scope input file
CATEGORY:
MDSplus, SCOPE
CALLING SEQUENCE:
names = getScopeNames( fileName, titles=titles )
names = getScopeNames() ; will get a dialog box
INPUTS:
Optional:
filename - name of scope input filename (else will get a dialog box)
RETURNED:
names - Array of signal names, including TDI, (Y values)
if nothing found, will return a '-1'
KEYWORDS:
(All Optional) Returned:
Titles - string array of the plot titles from the scope file, else y-name
xMins - array of each plot's x-minimum from the scope file (else global, or 0)
xMaxes - array of each plot's x-maximum from the scope file (else global, or 0)
yMins - array of each plot's y-minimum from the scope file (else global, or 0)
yMaxes - array of each plot's y-maximum from the scope file (else global, or 0)
nCols - # of columns for plot
nRows - (array) # of rows in each column for plot
Optional inputs:
stripTitles - if set, remove double quotes and everything after //
noEqualSigns - if set, remove equal signs (=)
addTrees - if set, add trees into signals
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
NOTES:
LIMITATIONS:
For jScope files, won't handle 2 signals on a single frame
EXAMPLES:
IDL> file = 'wfplus.scope'
IDL> SigNames = GetScopeNames( file, titles=titles, yMins=yMins, yMaxes=yMaxes, $
IDL> xMins=xMins, xMaxes=xMaxes, xNames=xNames, $
IDL> nRows=nRows, nCols=nCols, /addTrees )
IDL> file = '/p/nstxusr/util/jscp/wfplus.jscp'
IDL> file = '/p/nstxusr/util/jscp/EAST_Mag_probes.jscp'
IDL> names = getScopeNames( file, TITLES=titles, yMins=yMins, yMaxes=yMaxes )
MODIFICATION HISTORY:
21-Jan-2015 fixed logic on newExt
14-Feb-2014 ignore sets of 3 vertical bars after Y-signal names
12-Feb-2014 added jScope keyword, so don't have to rely on .jscp
ext
22-Apr-2010 made to work with jScope input files (ext .jscp) (and with files
with blank lines in header lines)
23-Jun-2008 added nRows and nCols keywords.
22-Mar-2006 revised xName logic when some there and some not.
27-Jan-06 add xNames keyword for specied X values.
19-Oct-01 if file not found, try other versions of name
13-Sep-01 Added addTrees keyword
17-Mar-01 default directory on Unix to /p/nstxusr/util/scopes/
02-Mar-01 added x & y mins and maxes
11-Jan-01 Written by Bill Davis
NAME:
gettrees
PURPOSE:
Return subtree or subnode names from an MDSplus tree
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> opt = gettrees(shot)
INPUTS:
shot = NSTX shot number (Default=-1)
KEYWORD PARAMETERS:
Inputs:
topTree - tree to start (Default='NSTX')
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
status - if odd, then success
OUTPUTS:
trees = MDSplus trees
EXAMPLES:
IDL> trees = gettrees( )
IDL> subtrees = gettrees(top='passivespec')
NOTES:
MODIFICATION HISTORY:
20-Oct-2013 Written by Bill Davis, PPPL
NAME:
good_ip
PURPOSE:
Determine if plasma current (Ip) was good for a shot and, optionally
declare an event.
CATEGORY:
MDSplus, Shot Number, Plasma Current
CALLING SEQUENCE:
nextShot = good_ip( shot )
INPUTS:
shot - shot number
KEYWORD PARAMETERS:
Inputs:
goodValue - value required for tag for next good shot (default=30000 Amps)
event - if non-blank, will be declared if plasma current > goodValue
Server - MDS server (default is NSTX)
TagToUse - Tag to use for IP check (default to \OPERATIONS::CAL_IROGEVVUL1)
IPforGood - alternate to goodValue (for compatibility with old routine)
Verbose - if set, print debugging information
Returned:
IpTime - time of good plasma current in seconds.
OUTPUTS:
1 or 0
EXAMPLE:
IDL> ipOK = good_ip( shot, goodValue = 100. )
COMMON BLOCKS:
NOTES:
if TagToUse not specified, will try to use in the following order:
1) \ENGINEERING::IP1UNC
2) \ENGINEERING::PPCC_IP1
3) \WF::IP
if SigUnits from MDSplus begins with 'K' will mult. by 1000. If it
begins with an 'M' will mult. by 1000000.
RESTRICTIONS:
MODIFICATION HISTORY:
Written by Bill Davis March, 2006
NAME:
LastMDSshot
PURPOSE:
get the last (current) MDS shot
CATEGORY:
MDSplus
CALLING SEQUENCE:
currentShot = LastMDSshot()
INPUTS:
none
KEYWORD PARAMETERS:
SERVER - MDS server (default is NSTX)
MACHINE - machine (default is NSTX)
OUTPUTS:
currentShot - current shot number
EXAMPLE:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
30-Jan-2015 return status
25-Feb-99 BD added way to get current shot from either VMS or UNIX
default to NSTX
11-Dec-98 BD added MDSplus access for shotnumber, if on VMS at PPPL
01-Dec-98 BD use fas_dir and Mk_Filename for filename lookup
5/14/98 changing USER directory to BE1 etc [PR]
NAME:
LeafName
PURPOSE:
Return leaf name from MDSplus pathname(s)
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> leaf = leafname(mdspath)
INPUTS:
mdspath - MDSplus path string.
OUTPUTS:
leaf - MDSplus leaf node string (last signal in multi-signal TDI)
KEYWORDS:
Delim - delimiter (default is ':')
Tree - returns tree of input (last signal in multi-signal TDI),
or environmental variable 'MACHINE' if Signal Math TDI used
on signals from more than one tree
AllTrees - all trees in input path
Prefix - returns everything before the leafname
nParts - # of parts to return, counting from the end (default=1,
max of 2)
BRACKETSTR - (1st) square bracket clause, as in an array subscript
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> print,leafname('\JMENARD_DAY1::TOP.FLUX_LOOP.FLUX:FFLPF1BL')
FFLPF1BL
IDL> print,leafname('\wf::ip')
ip
IDL> print,leafname('TOP.FLUXLOOP.FLUX.CALIBRATION',delim='.')
CALIBRATION
NOTE:
for multi-signal TDI, will return the leaf name of last signal, as well as the
last tree.
MODIFICATION HISTORY:
23-Nov-2010 fixed bug introduced 15-Oct with defaulting to '::' delimiter
15-Oct-2010 fixed bug using 2-char delimiter
30-Sep-2010 set delimiter to '::' and don't return '-1' in allTrees
26-Oct-07 Ignore square bracket clauses (but return in keyword BRACKETSTR)
16-Aug-07 return last tree for multi-line TDI
06-Aug-07 fix bug where no backslash in name
11-Jul-07 return all tree names in ALLTREES keyword.
If sigadd, sigmult, etc., used with more than one tree,
return 'NSTX' in TREE keyword
11-Jan-01 Remove comma and anything after, and ')' if TDI
28-Nov-00 Don't return tree name with '\'
23-Jul-99 Written by Bill Davis, PPPL
NAME:
ListShots
PURPOSE:
List shot numbers with signal over/under a certain amount
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> listshots, shot, nshots, signal=signal, warningLevel=warningLevel
INPUTS:
shot - if an interger: beginning shot # to search for
if an array of integers, use as a shot list (ignore nshots)
nshots - # of shots to search over (def=10)
KEYWORD PARAMETERS:
Optional Inputs:
comparator - 'GT' (default) or 'LT' for cutoff and warning
cutoff - value under which value will be ignored
outFile - outFile for output
nSmooth - # for median smoothing before using signal (default=0)
noScreen - if set, do not echo output to screen
server - MDSplus server, default='EUROPA.PPPL.GOV:8501'
signal - mdsplus signal name
skip - shots to skip while looping through list
warningLevel - warn if greater than than this value
Optional Returned:
count - number of shots satisfying criteria
OUTPUTS:
just to screen and/or file
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> listshots, 102915, 10, signal='\WF::IP', warn=1.0
NOTES:
tree should be in signal name
MODIFICATION HISTORY:
17-Apr-2008 Made > 0 not return zero values
04-May-2006 changed openMDSshot to mdsopen
03-Mar-04 a little bullet proofing
23-May-01 Written by Bill Davis, PPPL
NAME:
load_nebar
PURPOSE:
Load Ne-bar Waveform into MDSplus.
CATEGORY:
MDSplus, Density
CALLING SEQUENCE:
load_nebar, shot1, shot2
INPUTS:
shot1 = starting shot number to process
shot2 = (Optional) last shot number to process
KEYWORDS:
(Optional)
test - doesn't write to MDSplus
wfTree - name of MDSplus tree to write to (defalut='WF')
NOTES:
YOU NEED PRIVILEGES to write to the MDSplus tree.
LIMITATIONS:
Divide by zeroes, etc. will cause a message like:
% Program caused arithmetic error: Floating illegal operand
MODIFICATION HISTORY:
WRITTEN 23-Jul-2013, by Bill Davis for Stewart Zweben
NAME:
mdir
PURPOSE:
Directory listing of MDSplus data files with wild cards
CATEGORY:
MDSplus, files
CALLING SEQUENCE:
IDL> list = mdir(shot, tree=tree)
INPUTS:
shot - shot number (defaults to 0). Can be a character string
with wildcards.
tree - an MDSplus e.g. 'operations' (defaults to 'wf')
KEYWORD PARAMETERS:
inputs:
tree - an MDSplus e.g. 'operations' (defaults to 'wf')
dataroot - file system root for MDSplus data (default = '/nstxdata')
extension - extension of file wanted, default = 'datafile'
server - MDSplus server for data, if not set will use
denied - if set, will not return permission-denied messages
nDigits - when trying to extract a shot number from a filename, assume
this number of digits.
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
outputs:
allShots - tries to extract shot number from all files.
date - dates of files found
ctimes - creation times of files found
files - actual file names found
OUTPUTS:
list - list of data files found
EXAMPLE:
IDL> print, mdir( '13000*', tree='wf' )
IDL> list = mdir( '555555*', tree='engineering', date=date)
IDL> result = mdir( '9??????', tree='mptscalib', date=date, allshots=shots, $
nDigits=7, files=files, /verbose, /debug )
(the above took 18 minutes!)
NOTES:
if on a system with a /nstxdata directory, will spawn "find"
otherwise, you will have to enter your password to ssh into the server.
You may also have to respond "yes" to a question about connecting.
You must have the same username on the server as the machine you are on.
You may, instead, use tree_exists.pro, which is slower.
If you get tired of entering your password when looking for data on a
remote host, see http://w3.pppl.gov/~bdavis/swdoc/SSH_login_without_pw.txt
MODIFICATION HISTORY:
03-Mar-2010 parse server name from environmental variable for remote access
19-Nov-2009 Tidied up, added keywords, let shotstring work with wildcards.
27-Mar-2009 Added ctime output for Creation time, e.g. "Mar 19 14:37" or
"May 19 2005"
18-Mar-2009 Added date keyword [Bd]
15-Nov-2008 Written by Bill Davis, PPPL
NAME:
MDSdataVsShot
PURPOSE:
Print single values of MDSplus signals vs. shot number.
The value can be the max or min, or at a specific time, including
time of Max Ip, Max Neutrons, etc. The shot list may be reduced
by certain qualifiers, such as to shots where the max of an
arbitrary signal is > a given value.
Output can be in a format suitable for importing into
Kaleidograph, Excel, etc.
CATEGORY:
MDSplus, Output
CALLING SEQUENCE:
MDSdataVsShot, shot, nshots, signal
INPUTS:
MDStree - e.g. 'operations'. Default is 'NSTX'
shot - MDSplus shot number, i.e, ID.
signal - a single MDSplus signal name, or array of names.
(ignored if Keyword "Scope" is present.)
OUTPUTS:
none returned
KEYWORDS:
(all Optional)
format - output format. Defaults to '(100(g15.6, a1))'
(a tab or space is written between the columns)
tabs - if set, columns will be separated by tabs instead of spaces
headings - if set, the signal labels are at the top of each column
in row 1.
scope - if present, gets the signal names and column titles from
this scope file.
(if present, the signal input is ignored). THIS SHOULD BE
THE FULL PATHNAME OF THE FILE, or it will default to general
areas.
status - 1=OK, 0 means shot, signal, or scope file weren't found.
units - if set, will append units to headings
WhatToList - 'MaxValues', 'MinValues',
(time of the following:) 'MaxNeutrons', 'MaxIP', 'MaxBetaN',
'MaxDENS', 'MaxWMHD'
EXAMPLES:
LIMITATION:
HISTORY:
11-Feb-05 bug fix for when 1 dimension of 2-d array smaller than nsmooth
04-Jun-04 Bug fix when lots of bad shots
04-Nov-02 default to skipping a shot if any requested signal missing
Written 17-Jul-02 by Bill Davis at the request of Steve Paul
NAME:
MDSDAT
PURPOSE:
"replacement" for gadat.pro. Get MDSplus signal data without
having to open a tree (much faster, if a tree is specified)
CATEGORY:
MDSplus
CALLING SEQUENCE:
mdsdat, X, Y, signame, SHOT [,err=ERR] [,debug=DEBUG] $
[,xmin=XMIN] [,xmax=XMAX] $
[,npts=NPTS]
KEYWORDS: (all are optional)
INPUT/OUTPUT keywords:
NPTS: (INPUT) Number of samples to return. Defaults to 64K.
Cannot exceed 64K (if it does, it is set to 64K).
(OUTPUT) Number of samples actually returned.
INPUT KEYWORDS:
DEBUG: If set (ie. called as gadat,/debug), debug printouts on
the progress of gadat are reported
XMIN: specifies the "start" time for the time window within
which to return the data. Specify the time in
milliseconds. If not set, defaults to -10000 ms.
XMAX: specifies the "end" time for the time window within
which to return the data. Specify the time in
milliseconds. If not set, defaults to 100000 ms.
XUNITS - if non-zero, return units of x-axis out
YUNITS - if non-zero, return units of y-axis out
ALWAYSOPEN - always open the tree (for when other opens or MDSconnects are done)
OUTPUT KEYWORDS:
ERR: PTDATA/MDSplus error code. 0 = success, anything
else = failure
PLABEL: plot label for pointname
OUTPUTS:
X: The time base of the requested pointname in seconds
Y: Data from the requested signal name. See keywords NPTS and
A_NPTS for details on the number of samples returned.
EXAMPLE:
IDL> mdsdat, iptime, ip, 'wf::IP', 120200
IDL> mdsdat, efittime, ipmeas, 'efit01::IPMEAS', 120200
IDL>
COMMON BLOCKS:
MDSDAT_LOCAL
SIDE EFFECTS:
RESTRICTIONS:
MODIFICATION HISTORY:
07-May-2008 added /AlwaysOpen keyword for when other opens or MDSconnects are done
outside of mdsdat. This will make it slower.
04-Feb-2008 Written by Bill Davis
NAME:
MDSDeclareEvent
PURPOSE:
set an MDS event with shot number associated with the event
CATEGORY:
MDSplus, Events
CALLING SEQUENCE:
IDL> MDSDeclareEvent, eventName [, shot_num]
INPUTS:
eventName - string of MDS event name, e.g., 'NE_DENSITY_CALC'
shot_num - NSTX shot number (OPTIONAL -- will default to current shot)
KEYWORD PARAMETERS:
Optional:
VERBOSE - If set, print debugging information
NOCONNECT - if set, will not try to connect to an MDSplus server
OUTPUTS:
none -- just sets the event
COMMON BLOCKS:
NONE
EXAMPLE:
NOTES:
Works from Unix or VMS
MODIFICATION HISTORY:
11-Feb-04 use SETEVENT in MDSVALUE on Unix. Add connect option on unix.
20-Dec-99 Written [bd]
NAME:
MDSeditBranch
PURPOSE:
Read a branch of MDSplus values, allow editing of scalar values
in a widget and write back out.
CATEGORY:
MDSplus
CALLING SEQUENCE:
MDSeditBranch, shot=shot, tree=tree, branch=branch
INPUTS:
KEYWORD PARAMETERS:
Inputs:
shot - shot number to edit
tree - MDSplus treename to edit (DEF='cameras')
branch - branch of tree to edit values in (DEF=".FC_1.SETTINGS")
cautions - array, where, if=1, will warn user about changing (not implemented)
order - if =0 will order inputs by Integers, reals & then strings
comments - tips, to go after fields (not implemented)
ignore - array, where, if=1, will not present that element for editing
ncols - # of columns in display
title - title of widget
maxPerCol -
maxFieldSize - if not present, takes reasonable defaults
nInFirstCol -
debug - if set, prints debug info and stops in a few places
verbose - if set, prints information messages
OUTPUTS:
NONE unless user chooses to write new values to a tree
(user must have priviledges to write to tree)
EXAMPLE
setenv cameras_path /u/bdavis/TCLcode
idl
IDL> MDSeditBranch, 142000, tree='cameras', branch='.FC_1.SETTINGS', $
ignore='BACKIMAGE'
NOTES:
For text nodes, you can enter \n for a new line
MODIFICATION HISTORY:
27-Mar-2010 Written by Bill Davis, PPPL
NAME:
mdseventwait
PURPOSE:
Widget to Wait for an MDSplus event,
or the user clicks the CANCEL button.
CATEGORY:
MDSplus; Event Widgets
CALLING SEQUENCE:
IDL> shot = mdseventwait( someEvent, cancel=cancel )
INPUTS:
someEvent - (string) an MDSplus event (defualts to 'nstx_acq_done')
KEYWORD PARAMETERS:
Optional:
cancel - if user hits cancel button, cancel = 1 (& shot=-1), else 0
group_leader - higher level widget to place this on top of
OUTPUTS:
shot - shot # (data) set like: IDL> setmdsshotevent,'dum',999999
COMMON BLOCKS:
NONE
EXAMPLE:
RELATED ROUTINE:
NOTES:
Only works on X.
MODIFICATION HISTORY:
29-Aug-00 Written by Bill Davis for David Swain
NAME:
MDSGETSIG
PURPOSE:
Get a signal, units and axes values easily from MDSplus
CATEGORY:
MDSplus
CALLING SEQUENCE:
d = MDSGETSIG( signal, SIGUNITS=fUnits, XAXIS=time, XUNITS=timeUnits)
INPUTS:
signal - MDSplus Signal name
KEYWORD PARAMETERS:
Keywords:
SIGUNITS - if non-zero, return units of signal out
XAXIS - if non-zero, return array of x-axis out
XUNITS - if non-zero, return units of x-axis out
YAXIS - if non-zero, return array of y-axis out
YUNITS - if non-zero, return units of y-axis out
ZAXIS - if non-zero, return array of Z-axis out
ZUNITS - if non-zero, return units of Z-axis out
status - if non-zero, return status (1=OK) out
OUTPUTS:
d - 1- or 2-D data out
COMMON BLOCKS:
NONE
EXAMPLE
MDSCONNECT, 'yourhost.pppl.gov:8501'
MDSOPEN, 'testtree', 10
sig = 'onedim'
data = MDSGETSIG( signal,SIGUNITS=fUnits, XAXIS=time,XUNITS=timeUnits )'
PLOT, time, data, XTITLE = timeUnits, YTITLE = fUnits, $
TITLE = signal + ' - shot ' + STRTRIM( STRING(shot), 2 )
NOTES:
If something like x units were NOT stored for the signal, and they are
asked for, IDL will complain about an access violation, but continue.
When signals are TDI combinations of others, use the
units and xaxis from the first signal (could be erroneous)
MODIFICATION HISTORY:
10-Aug-2009 Check for data being a number (not '*') when taking min & max
23-Jun-2008 when finding Xunits of a signal like dim_of(\...), use it
13-May-08 handle \rf::refl_avgdens[*,33]
26-Oct-07 handle 2-D square bracket clauses, as in an array subscript
31-Aug-07 made xAxis work when SigMath TDI used
06-Apr-07 made work for 'maxval(\activespec::chers_best:vt,1)'
03-Jun-05 Added Z data
01-May-01 When signals are TDI combinations of others, use the
units and xaxis from the first signal (could be erroneous)
11-Nov-99 test for input signal name not defined
10-Aug-99 Use Arg_Present so don't have to set keywords before call
26-Jan-99 Trim trailing blanks from unit strings [BD]
13-Jan-99 Written by Bill Davis, PPPL
NAME:
mdsLargestNode
PURPOSE:
find largest node in a tree
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> size = mdsLargestNode( tree, searchStr, shot=shot, $
biggestSig=biggestSig )
INPUTS:
tree - MDSplus tree. Defaults to 'PCS'
optional:
searchStr - what to use to search for nodes. Defaults to '*'
KEYWORD PARAMETERS:
Inputs:
shot = NSTX shot number (defaults to latest shot)
usage - Defaults to 'SIGNAL'. Can be "ANY", "TEXT" or "NUMERIC"
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
status - if odd, then success
biggestSig - name of biggest signal found
OUTPUTS:
size - size of contents of node in bytes
EXAMPLES:
IDL> size =mdsLargestNode( 'WF', shot=136000, biggestSig=biggestSig )
IDL> size=mdsLargestNode( 'operations', 'PCS', shot=136000, $
biggestSig=biggestSig )
IDL> help
BIGGESTSIG STRING = '\OPERATIONS::TOP.PCS.MAGCONTROL.CURRENT:IPLAS_PF1B_1'
SIZE LONG = 90
MODIFICATION HISTORY:
22-Aug-2013 Written by Bill Davis for Keith Erickson
NAME:
mdslist
PURPOSE:
Print ASCII file containing data for MDSplus signal(s).
The "dimension" of one of the signals (typically time) is in the
first column, followed by data values at that time.
Output may be in the format suitable for importing into
Kaleidograph, Excel, etc.
CATEGORY:
MDSplus, Output
CALLING SEQUENCE:
mdslist, MDStree, shot, signames
mdslist, MDStree, shot, signames, $
t1=t1, t2=t2, npts=npts, format=format, tabs=tabs, $
headings=headings, SigForX=SigForX, scope=scope
INPUTS:
MDStree - e.g. 'operations'. Default is 'NSTX'
shot - MDSplus shot number, i.e, ID.
signames - a single MDSplus signal name, or array of names.
(ignored if Keyword "Scope" is present.)
OUTPUTS:
none returned
KEYWORDS:
(all Optional)
t1 - Starting x-value desired (typically time, in seconds).
Defaults to beginning of data for 1st signal.
t2 - Ending x-value desired. Defaults to end of data
npts - number of points desired. Defaults to all points.
nth - just list every nth point
format - output format. Defaults to '(100(g15.6, a1))'
(a tab or space is written between the columns)
tabs - if set, columns will be separated by tabs instead of spaces
headings - if set, the signal labels are at the top of each column
in row 1.
SigForX - The signal from which to extract the output x-values.
Especially relevant when signals of different timebase are
requested (defaults to that of the first signal).
scope - if present, gets the signal names and column titles from
this scope file.
(if present, the signames input is ignored). THIS SHOULD BE
THE FULL PATHNAME OF THE FILE, or it will default to general
areas.
outFile - name of output file. Default is 'mdslist.txt'
status - 1=OK, 0 means shot, signames, or scope file weren't found.
units - if set, will append units to headings
EXAMPLES:
To write the first 100 points of time and
ip pairs to file mdsoutput_106138.dat:
IDL> mdslist,'wf',106138,'\ip',npts=100
To write 3 columns, of time, Ip, and Itf, from 0.1-0.2 sec to
file mdsoutput_106138.dat:
IDL> mdslist,'wf',106138,['\ip','\itf'],t1=.1,t2=.2
To make a tab-delimited file of signals from an MDSplus Scope,
with column headings, on efit times:
IDL> mdslist,'',106138,scope='/u/Old/bdavis/bv.scope', $
SigForX='EFIT', /headings, /tabs
To write time and stored energy data at 1 KHz
(like all signals in WF tree):
IDL> mdslist,'',106138,'\EFIT01::WMHD/1000', SigForX='\WF::IP'
LIMITATION:
Would be faster, if it just opened trees that were needed.
HISTORY:
01-May-2012 start time different than data wasn't working
06-Apr-2011 added nth keyword for Hiro Takahashi
05-Jan-2010 handle missing signal. Print good error messages and warning on
web page and in file.
11-Jul-2008 add /XML output option
24-Mar-08 puts tabs between columns if tabs='on' (as well as if tabs=1)
07-Jan-08 Close file before e-mailing, because not all of file begin sent
26-Sep-07 Add message on how to get file from Linux Cluster nodes
09-Aug-07 bug fix with Yunits not defined
29-Mar-07 changed openMDSshot to mdsopen, so SFLIP and such would work
13-Sep-06 Don't worry if time and data arrays different length
15-Feb-05 Handle when time not first dimension in 2-d array
20-Sep-01 converted from mdsmkfile
05-Sep-01 Added multi-column and interpolation options.
Written 13-jul-00 by Bill Davis at the request of Charlie Neumeyer
NAME:
MDSloadScalar
PURPOSE:
Load MDSplus scalar with one simple call (after opening shot)
CATEGORY:
MDSplus
CALLING SEQUENCE:
MDSloadScalar, sig, data, SIGUNITS = sigUnits, XAXIS = xAxis, $
XUNITS = xUnits, YAXIS = yAxis, YUNITS = yUnits
INPUTS:
sig - MDSplus Signal name
data - 1- or 2-D data array to load
KEYWORD PARAMETERS:
Keywords:
stat=val - if non-zero, return status (1=OK) out
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
EXAMPLE
stat=openMDSshot('engineering', 100700)
sig = '\Some_sig'
MDSloadScalar, sig, 3.14159
MODIFICATION HISTORY:
02-Nov-99 Written by Bill Davis, PPPL
NAME:
MDSLOADSIG
PURPOSE:
Load MDSplus signals with one simple call (after opening shot)
Optionally add node and/or tag to a shot tree.
CATEGORY:
MDSplus
CALLING SEQUENCE:
MDSLOADSIG, sig, data, SIGUNITS=sigUnits, XAXIS=xAxis, $
XUNITS=xUnits, YAXIS=yAxis, YUNITS=yUnits
INPUTS:
sigName - MDSplus Signal name
data - 1- or 2-D data array to load (can be 3-D, but must have all
keywords)
KEYWORD PARAMETERS:
Keywords:
SIGUNITS=val - units of signal in
XAXIS=val - array of x-axis in
XUNITS=val - units of x-axis in
YAXIS=val - array of y-axis in
YUNITS=val - units of y-axis in
ZAXIS=val - array of z-axis in
ZUNITS=val - units of z-axis in
FullX - if set, store full x-axis, even if dx constant (1-D only)
SkipCheck - if set, do not check time base for constancy (assume)
AddNode - if set, will try and add the node to the tree
TagToAdd - Tag to add
shot - needed if adding node or tag
tree - needed if adding node or tag
JustAdd - if set, just add node and/or tag, but don't load data
stat=val - bad if even, OK if odd out
quiet - passed to MDSplus routines (default=1)
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
EXAMPLE
mdsopen,'wf', 99999, stat=stat
sigName = '\ip'
x = findgen(10)
y = sin( x/n_elements( x ) * 3 * 2 * !PI )
MDSLOADSIG, sigName, y, SIGUNITS='Y Units', XAXIS=x, XUNITS='X Units'
or, to just add a signal and tag:
MDSLOADSIG, sigName, TagToAdd=tag, SHOT=shot, TREE=tree, /JUSTADD
MODIFICATION HISTORY:
17-Jul-2014 add check for 1 or less data points
23-Jul-2013 added noclose and forceAdd keywords
05-Mar-2009 check output keyword on dir in mdstcl (needed for Linux)
09-Jul-2008 use dt_nicenumber, instead of nicenumber, for
digitizing rates of 4, etc.
03-Jul-2008 Added dt keyword for Stefan Gerhardt, with ~4e-6 dt.
24-Apr-06 change mds$tcl to mdstcl for Unix.
22-Jun-04 allow 3-d, but must have all parameters
27-Jan-03 Just store x0, dx, y0, and dy for 2-D signals, if xaxis input
23-May-01 Make, as a default, signals with constant timebase
store with t0 & delta t, rather than storing whole time array.
16-Nov-00 Added the AddNode & TagToAdd keywords
28-Aug-00 Don't Use Arg_Present
07-Jan-99 Written by Bill Davis, PPPL
NAME:
mdsmkfile
PURPOSE:
Write an ascii file containing time and data for MDSplus signal(s).
Time is in the first column, followed by data values at that time.
Output may be in the format suitable for importing into
Kaleidograph, Excel, etc.
CATEGORY:
MDSplus, Output, File I/O
CALLING SEQUENCE:
mdsmkfile, MDStree, shot, signals
mdsmkfile, MDStree, shot, signals, filename=filename, $
t1=t1, t2=t2, npts=npts, format=format, tabs=tabs, $
headings=headings, timeSig=timeSig, scope=scope
INPUTS:
MDStree - e.g. 'operations'. Default is 'NSTX'
shot - MDSplus shot number, i.e, ID.
signals - a single MDSplus signal name, or array of names.
(ignored if Keyword "Scope" is present.)
OUTPUTS:
none returned
file named mdsoutput_nnnnnn.dat is written, where
nnnnnn is the shot number, or, if a scope is used, the
scope name is in the place of mdsoutput. If Keyword "Filename"
is present, that name is used.
KEYWORDS:
(all Optional)
filename - output filename (default is mdsoutput_nnnnnn.dat, where
nnnnnn is the shot number, or, if a scope is used, the
scope name -- without extension -- is in the place of
mdsoutput).
DeltaTime - time step for output - Default is that of the first
signal specified. If = 0, then do not list time.
t1 - Starting time desired, in seconds.
Defaults to beginning of data for 1st signal.
t2 - Ending time desired. Defaults to end of data
npts - number of points desired. Defaults to all points.
format - output format. Defaults to '(100(g15.6, a1))'
(a tab or space is written between the columns)
tabs - if set, columns will be separated by tabs instead of spaces
headings - if set, the signal labels are at the top of each column
in row 1.
timeSig - The signal from which to extract the output timebase.
Especially relevant when signals of different timebase are
requested (defaults to that of the first signal).
If DeltaTime is specified, this keyword is overridden.
scope - if present, gets the signal names and column titles from
this scope file.
(if present, the Signals input is ignored). THIS SHOULD BE
THE FULL PATHNAME OF THE FILE, or it will default to general
areas.
status - 1=OK, 0 means shot, signals, or scope file weren't found.
EXAMPLES:
To write the first 100 points of time and
ip pairs to file mdsoutput_106138.dat:
IDL> mdsmkfile,'wf',106138,'\ip',npts=100
To write 3 columns, of time, Ip, and Itf, from 0.1-0.2 sec to
file mdsoutput_106138.dat:
IDL> mdsmkfile,'wf',106138,['\ip','\itf'],t1=.1,t2=.2
To make a tab-delimited file of signals from an MDSplus Scope,
with column headings, on efit times:
IDL> mdsmkfile,'',106138,scope='/u/bdavis/bv.scope', $
timeSig='EFIT', /headings, /tabs
To write time and stored energy data at 1 KHz
(like all signals in WF tree):
IDL> mdsmkfile,'',106138,'\EFIT01::WMHD/1000', timeSig='\WF::IP'
LIMITATION:
HISTORY:
12-Oct-01 Added deltaTime keyword [BD]
05-Sep-01 Added multi-column and interpolation options.
Written 13-jul-00 by Bill Davis at the request of Charlie Neumeyer
NAME:
MDSnodeChanges
PURPOSE:
Print times when the last change was made to an MDSplus node.
CATEGORY:
MDSplus, Tree Status, dates
CALLING SEQUENCE:
MDSnodeChanges, node, shot1=shot1, shot2=shot2, skip=skip, tree=tree
INPUTS:
node = MDSplus node name, e.g. \OPERATIONS::TOP.RAWDATA:LM_H908_01
KEYWORDS:
shot1 = starting shot number to process
shot2 = last shot number to process (else shot1+400)
skip = skip factor
tree = MDSplus tree (defaults to nstx --
will be faster if specific tree specified)
BEFORE - show only nodes written before this date (defaults to '1-jan-1971'),
so can see what never got written.
AFTER - show only nodes written after this date (defaults to '1-jan-1971'),
so can see only nodes that HAVE been written.
OUTFILE - a file name to contain a script related all shots for which
a valid node was found in MDSplus
PREFIX - string to prefix the shot # in the script.
DEFAULT is '/bin/rm -R -f '
MAX - if set, will print max of signal
VERBOSE - if set, will tell you what shots could not be opened.
EXAMPLE:
IDL> tree='microwave'
IDL> node='\top.electron_den:line_density'
IDL> MDSnodeChanges, node, shot1=101300, shot2=101330, tree=tree
IDL> MDSnodeChanges, '\cameras2::FastSoftXray:frames',shot1=124459, $
shot2=125000, /after
to produce a script to delete shot directories that have been put in MDSplus:
IDL> MDSnodeChanges, node, shot1=shot1, shot2=shot2, /after, outfile='shots.txt'
COMMON BLOCKS:
NOTES:
see MDStreeChanges for who last changed a tree.
Note that "OWNER" returns 0 from getnci call.
This runs quickly.
LIMITATIONS:
MODIFICATION HISTORY:
20-Aug-2009 added Max keyword
30-Apr-2008 added outfile and prefix keywords, so directories can be
deleted after verifying they are in MDSplus
09-Jul-2007 added AFTER keyword, so you can see what nodes have been written
30-Apr-2007 add BEFORE keyword, so you can see what nodes never got written
26-Apr-2007 "Who" stopped working (returning numberical value)
09-May-2006 Allow for numerical or '*' for who.
20-Dec-99 Written for Rajesh Maingi.
NAME:
mdsscalars
PURPOSE:
Print ASCII file containing values of MDSplus scalars(s) for a list of shots.
CATEGORY:
MDSplus, Output
CALLING SEQUENCE:
mdsscalars, MDStree, shot, signames
INPUTS:
MDStree - e.g. 'operations'. Default is 'NSTX'
shot - MDSplus shot number, i.e, ID. Can be an array, or range of shots.
signames - a single MDSplus signal name, or array of names.
OUTPUTS:
none returned
KEYWORDS:
(all Optional)
format - output format. Defaults to '(100(g15.6, a1))'
(a tab or space is written between the columns)
tabs - if set, columns will be separated by tabs instead of spaces
headings - if set, the signal labels are at the top of each column
in row 1.
status - 1=OK, 0 means shot, signames, or scope file weren't found.
EXAMPLES:
IDL> mdsscalars,'',118956,'\ENGINEERING::TOP.EPICS.GAS.PARAMETERS:INJ1_READY'
LIMITATION:
Would be faster, if it just opened trees that were needed.
HISTORY:
28-May-2015 BD fixed bug where scalar string starts with a number. IDL wants to
make an octal out of "27-Apr-2015". So using single quotes.
Written 20-Aug-2006 by Bill Davis
NAME:
MDSSETEVENT
PURPOSE:
Generates an MDSplus event
CATEGORY:
MDSplus, Events
CALLING SEQUENCE:
MDSSETEVENT,event[,/QUIET][,STATUS=STATUS][,DATA=data][,/INFO]
INPUT PARAMETERS:
event = Name of MDSplus event to generate.
Keywords:
QUIET = prevents IDL error if TCL command fails
STATUS = return status, low bit set = success
DATA = bytarr(12) to send with event
INFO - if this keyword is set the VMS error will be displayed but
control will be returned to the caller instead of doing a
longjump back to the IDL prompt.
OUTPUTS:
istat = return status, low bit set = success
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Makes a call to MDSplus shared image library
procedure MDS$OPEN and checks for errors.
MODIFICATION HISTORY:
renamed from mds$setevent & made to work on UNIX, too [BD]
VERSION 1.0, CREATED BY T.W. Fredian, April 22,1991
NAME:
mdsSigInterp
PURPOSE:
call TDI to interpolate signals, but handle expressions
in which multiple signals are included.
(assumes all same timebase within a given TDI expression)
CATEGORY:
MDSplus, Timing
CALLING SEQUENCE:
IDL> interpData = mdsSigInterp(inSig, outXsig_in, status=status)
INPUTS:
inSig - character string of signal to interpolate
outXsig_in - signal to get timebase for output of inSig
OUTPUTS:
returns array on desired timebase
KEYWORDS:
(all Optional)
inXsig_in - signal to find timebase for. Default is dim_of(inSig)
minTime - if set, just returns time range common to both signals
outTimes - time base of returned signal
status - 1=OK, 0 means problem
EXAMPLE:
stat=openMDSshot('nstx', 109070)
interpData = mdsSigInterp( '\wf::ip', '\engineering::ip1', outTimes=outTimes, /mintime )
plot,outtimes,interpdata
HISTORY:
10-Apr-03 outTimes and minTime keywords added
05-Nov-01 Written by Bill Davis
NAME:
MDStreeChanges
PURPOSE:
Print times when the last change was made to an MDSplus tree,
and who did it.
CATEGORY:
MDSplus, Tree Status, dates
CALLING SEQUENCE:
MDStreeChanges, tree, shot1=shot1, shot2=shot2, skip=skip
INPUTS:
tree = MDSplus tree name, e.g. 'Microwave' or 'NSTX'
KEYWORDS:
shot1 = starting shot number to process
shot2 = last shot number to process
skip = skip factor (default to no skip
since = only list changes for a shot if since this date
e.g. - '20-sep-2001'
COMMON BLOCKS:
none
EXAMPLE:
IDL> mdstreechanges, 'microwave', shot1=101300, shot2=101301
Latest changes from shot 101300 to 101301 for the microwave tree
Shot Who Date Node
---- --- ---- ----
101300 [BDAVIS] 4-APR-2000 .ELECTRON_DEN:LINE_DENS_DF
101301 [BDAVIS] 4-APR-2000 .ELECTRON_DEN:LINE_DENS_DF
MODIFICATION HISTORY:
01-Feb-02 added text for repeated lines
28-Jan-02 added SINCE keyword [BD]
20-Dec-99 Written by Bill Davis for Rajesh Maingi.
NAME:
MDSunits
PURPOSE:
return units of an MDS tag, or the time, or time units
CATEGORY:
MDSplus
CALLING SEQUENCE:
units = MDSunits( tag )
INPUTS:
tag - MDSplus tag or node name in
KEYWORD PARAMETERS
Input:
TIME - If set, Time returned (unless UNITS also set)
UNITS - If set, Units of tag returned (unless TIME also set)
Returned:
STATUS- Status of call (can be used in IDL logical expressions)
OUTPUTS:
units - units
EXAMPLES:
MDSOPEN, 'tftr', 89725
tag = '.waveforms:mb_ip_sl'
f = MDSVALUE( tag )
time = MDSUNITS( tag, /TIME )
flabel = MDSUNITS( tag, /UNITS )
timelabel = MDSUNITS( tag, /TIME, /UNITS )
plot, time, f/1000., xtitle = timelabel, ytitle = 'milli'+flabel
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
29-Mar-99 Return status from MDSVALUE [BD]
21-Dec-98 Written by Bill Davis
NAME:
mdsw
PURPOSE:
Interactively plot MDS signals with Crosshairs and many options
CATEGORY:
MDSplus, Plotting, Widget Example, Printing Plots, Crosshairs
CALLING SEQUENCE:
mdsw
mdsw, xsize=800, ysize=600
KEWORDS:
XSIZE - initial horizontal size of graphics window
YSIZE - initial vertical size of graphics window
shot - MDSplus shot number, i.e, ID
tree - tree to open. Defaults to NSTX
COMMON BLOCKS:
none
EXAMPLE:
IDL> mdsw,tree='engineering',shot=130000,charsize=2, Az=140, $
signal='\engineering::ppsum'
NOTES:
Your display may have to be set to 256 colors to see the crosshairs.
LIMITATIONS:
Some of the MDSplus signals in the list may not have any data.
You need IDL version 5, or greater to run this application.
MODIFICATION HISTORY:
16-Mar-2009 Option to not display scalars in Signal list
19-Jan-2008 Added option to change Az & Ax on surface plots
16-Jan-2009 added zAxisW calls for RGA data
17-Oct-05 Add Save to Tek option.
08-Mar-02 Fixed screen dump cabability for 24-bit color, and some minor things.
05-Oct-01 Improved restoring settings. Allowed for "Next Shot" to be missing.
18-May-01 Use Vcomp for "visual compression" if more points than resolution
07-May-01 Added Reload color table. Better behavior when copying plots that
don't fill the screen.
08-Mar-01 Bug fixed on Reference Shots with signals of different length.
02-Feb-01 Use Label sub-node as title, if available. Access to
nodes, even if not tags. Display text nodes.
Display Signal List initially. Plot 2-D data.
30-Nov-00 Allow "Save Settings" to include Signal List & !X, !Y, !P.
(old settings files won't work).
Axis selection with middle mouse button just redraws last plot.
20-Nov-00 Rearranged menus (added Appearance Menu); better plot spacing.
13-Nov-00 Added "Assume same x-label" & "Assume same x-axis" options
30-Oct-00 Added widget for !P settings, so can specify symbols, etc.
26-Oct-00 Fixed "Copy Plot to Tek" to return to X color table afterwards.
18-Oct-00 Added "Edit Selected Signal" option in Signal Menu.
TDI expressions included in name will be displayed. Added button
to show treenames in list.
10-Oct-00 Added "Label Every Other tick options" & better tick labels
Made postscript output a little better for grid of plots
03-Oct-00 Add "Always Include 0 on Y-axis" (not default) and
"Draw dashes at y=0" (now default) options.
28-Sep-00 Allow yaxisw to control Y-axis range,
in some situations, at least.
20-Sep-00 Just label "No Data" if data not found. Put < & > on Signal Menu
07-Oct-99 Redraw whole screen when mouse used. Alphabetize signal list.
Default to "Only zoom X"
19-Aug-99 Allow overlays of data with different dimensions
23-Jun-99 Added Reference shot. Added "Plot all on one page" option.
12-Apr-99 Added Tek output option [BD]
29-Mar-99 Added X & Y Style editing. [BD]
15-Mar-99 Add "Get Next Good Shot" buttons [BD]
08-Mar-99 Add overlays and legends. [BD]
26-Feb-99 Multiplot option and x-only zooming [BD]
11-Feb-99 Added a pick list for MDS signals
26-Jan-99 Modified for using MDS at PPPL by Bill Davis
GA Crosshair routines originally written by John Ferron.
NAME:
mk_scope_gif
PURPOSE:
make gif files from scope-like output, using a scope file as input
CATEGORY:
MDSplus, Plot files
KEYWORD INPUTS:
shots - a string indicating shots,
e.g., 107694 108305 108330-108350
or 108100+20
(this returns shots 108100, 108101,...,108120)
scopeFile - if not specified will prompt
rightSpace - fractioanal space to right of last plot (0-1)
leftSpace - fractioanal space to left of first plot (0-1)
colSpace - fractioanal space between plot columns (0-1)
vertSpace - fractioanal space between plot rows (0-1)
t1 - start time of plots (sec)
t2 - end time of plots (sec)
nRows - # of rows of plots
nCols - # of columns of plots
pixmap - if set, will not display plots on screen (much faster)
EXAMPLE:
(on Unix:)
mk_scope_gif,shots='109071-109075',scope='wf.scope', /pixmap
or
mk_scope_gif,shots='109071+5' ; (will be prompted for file)
or
mk_scope_gif, shots='109070+2',scope='/u/kaye/Scope/sk.scope', $
leftspace=.07, rightspace=0.005, $
tweenspace=0.008, vertSpace = 0.03, $
nrows=8, ncols=4, charsize=1.3
HISTORY:
Written by Bill Davis for Stan Kaye, Dec. 2004
NAME:
nextGoodShot
PURPOSE:
find the next shot that has more than a certain Ip.
CATEGORY:
MDSplus, Shot Number
CALLING SEQUENCE:
nextShot = nextGoodShot( StartShot )
INPUTS:
StartShot - shot number to start from in
KEYWORD PARAMETERS:
Inputs:
goodValue - value required for tag for next good shot (default=30000 Amps)
Backwards - look backwards for good shots
MaxShots - Maximum number of shots to search over
(default=1000 or end). IF MAXSHOTS=1 JUST PROCESS SHOT1
Server - MDS server (default is NSTX)
TagToUse - Tag to use for IP check (default to \OPERATIONS::CAL_IROGEVVUL1)
Verbose - if set, print debugging information
OUTPUTS:
nextShot - next Shot number, based on criterion
IF no good shot meeting criterion is found, -1 is returned
EXAMPLE:
IDL> ishot = NextGoodshot( laopenStathot, goodValue = 100. )
COMMON BLOCKS:
NOTES:
this routine just works for NSTX and DIII-D (uses gadat at GA).
RESTRICTIONS:
LASTSHOT() may sometimes return a small number during test periods
MODIFICATION HISTORY:
02-Nov-2009 better debug statements
10-Mar-06 Default to \WF::IP. Check for different tree for backup tag.
15-Aug-05 add LastIpTime keyword [BD].
28-Sep-01 Return status. Assume values read are in Amps.
Use \ENGINEERING::IP2 as a backup value
28-Nov-00 Changed Ip to look for \ENGINEERING::PPCC_IP1
20-Sep-99 Add MaxShots keyword
18-Sep-99 Keep going after 1 missing shot, but stop after 5
16-Sep-99 Added TagToUse keyword & medsmooth to remove spikes [BD]
Written by Bill Davis March, 1999
NAME:
nonVarPos
PURPOSE:
find position of characters which are not valid for MDSplus names
CATEGORY:
MDSplus, Character Search, Strings
CALLING SEQUENCE:
posArray = nonVarPos( inStr )
RETURNED:
posArray = array of positions of characters which are not
valid characters for an MDSplus tag name
-1 if none found
KEYWORDS:
(OPTIONAL)
GOOD - if set, will retrun positions of good characters
noNum - if set, don't count numbers as good characters
MODIFICATION HISTORY:
01-May-01 - Added keywords
2001 Written by Bill Davis
NAME:
nsearch
PURPOSE:
Search MDS Plus Trees for a node
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> result=nsearch(searchnode[, fullpath=path])
INPUTS:
searchnode and optional variable to return an array of full paths
containing node name
KEYWORD PARAMETERS:
fullpath - full path of node found
OUTPUTS:
status of function (-1 if not found, 0 if found)
COMMON BLOCKS:
none
EXAMPLE:
IDL> result=nsearch('xray', fullpath=path)
NOTES:
tree must be open before nsearch can be called.
will return 0 if node is found and -1 if it is not found in the current
tree.
MODIFICATION HISTORY:
12-Feb-00 strip tree info, if in node name [BD]
7-Feb-00 Written by Dana Mastrovito, PPPL
NAME:
plotscope
PURPOSE:
make scope-like plots, optionally with overlays from multiple shots.
CATEGORY:
MDSplus, SCOPE
CALLING SEQUENCE:
IDL> plotscope, shots=shots, scope=scope
INPUTS:
shots - scalar or array of shot numbers, e.g. [104500,104501]
scope - name of scope input filename (else will get a dialog box)
RETURNED:
None
KEYWORDS:
(All Optional) Inputs:
t1 - starting time desired. Defaults to scope value
t2 - ending time desired. Defaults to scope value
refshot - a reference shot to be overplotted.
SameXlabels - If set and non-zero, just label x-axis at bottom
(This reserves less vertical space between plots)
NRows - Maximum number of rows.
NCols - Number of columns (default is to compute from rows & # sigs)
nSmooth - # for median smoothing before using signal (default=0)
pCharSize - Value desired for !P.CHARSIZE, else guesses
Titles - string array of the plot titles from the scope file, else y-name
xMins - array of each plot's x-minimum from the scope file (else global, or 0)
xMaxes - array of each plot's x-maximum from the scope file (else global, or 0)
yMins - array of each plot's y-minimum from the scope file (else global, or 0)
yMaxes - array of each plot's y-maximum from the scope file (else global, or 0)
tweenspace - vertical space between plots in normalized coordinates
colSpace - horizontal space between plots in normalized coordinates
rightSpace - space on right in normalized coordinates
leftSpace - space on left in normalized coordinates
EXAMPLE:
(Send plots to a Tektronix window, say, from on a Mac from VersaTerm):
IDL> setup_tek
IDL> plotscope, shots=104500, refshot=104501, scope='WF'
IDL> unsetup_tek
(Make a scope-like plot without space between plots
-- the tick labels are outside their grids, unlike in Scope)
IDL> plotscope,shot=105830,scope='wf',tweenspace=0,colspace=0
COMMON BLOCKS:
none
NOTES:
LIMITATIONS:
MODIFICATION HISTORY:
24-Aug-01 Written by Bill Davis
NAME:
printscope
PURPOSE:
print scope-like output, using a scope file as input
CATEGORY:
MDSplus, Printing Plots
KEYWORD INPUTS:
shots - a string indicating shots,
e.g., 107694 108305 108330-108350
or 108100+20
(this returns shots 108100, 108101,...,108120)
scopeFile - if not specified will prompt
printer - if not specified will prompt on Unix
rightSpace - fractioanal space to right of last plot (0-1)
leftSpace - fractioanal space to left of first plot (0-1)
colSpace - fractioanal space between plot columns (0-1)
vertSpace - fractioanal space between plot rows (0-1)
t1 - start time of plots (sec)
t2 - end time of plots (sec)
nRows - # of rows of plots
nCols - # of columns of plots
noprint - if set, will not send plot to printer
EXAMPLE:
(on Unix:)
printscope,shots='109071-109075',scope='wf.scope',printer='nstx-xn4525'
or
printscope,shots='109071+5' ; (will be prompted for file & printer)
or
printscope, shots='109070+2',scope='/u/kaye/Scope/sk.scope', $
leftspace=.07, rightspace=0.005, $
tweenspace=0.008, vertSpace = 0.03, $
nrows=8, ncols=4, $
printer='nstx-xn4525', charsize=1.3
HISTORY:
Written by Bill Davis for Stan Kaye, jan, 2003
NAME:
SearchMDSNodes
PURPOSE:
Search MDSplus nodes for string contents
CATEGORY:
MDSplus, Searching
CALLING SEQUENCE:
IDL> paths= SearchMDSNodes( str[, sensitivity, text=text][,path=path])
INPUTS:
str - string to search on
sensitivity - (Optional) if ='Sensitive', then make search case sensitive
KEYWORD PARAMETERS:
Input (Optional):
JustText - if set, just look for Text nodes (no effect if /TAGS set)
nonNodeStr - exclude nodes in returned array if this string found in name
tags - if set, just look for nodes with tags
sizesearch - when searching text, length of string to check (def=1024)
whatToSearch - = 'NAMES', 'TEXT', or 'TDI'
treeName - MDSplus tree. Default='NSTX'
shot - MDSplus shot to search. Default=-1 (the model tree).
server - MDSplus server. Default is the default NSTX data server.
Returned (Optional):
text (contains the full text found), path(returns the full path to the text)
isSignal - logical array where 1s indicate corresponding node is a signal
status - status from mdsvalue call
OUTPUTS:
result - status of function: 0 = success, -1 = failed to find
COMMON BLOCKS:
none
EXAMPLE:
IDL> paths=SearchMDSNodes('xray', text=text )
NOTES:
tree must already be open before SearchMDSNodes can be called
if no records are found in current tree returns -1 else returns 0
MODIFICATION HISTORY:
12-Feb-2015 made it so don't have to enter shot keyword
06-May-2010 added max2search keyword
20-Apr-2010 added keyword isSignal
11-Nov-05 Added tree keyword
01-Dec-00 Added capability for wildcards in search string
10-Nov-00 Added sensitivity [BD]
7-Feb-00 Written by Dana Mastrovito, PPPL
NAME:
SearchTextNodes
PURPOSE:
Search MDS Plus Trees for Textual Data
CATEGORY:
MDSplus, Searching
CALLING SEQUENCE:
IDL> result= SearchTextNodes( keyword[, sensitivity, text=text][,path=path])
INPUTS:
keyword - string to search on
sensitivity - (Optional) if ='Sensitive', then make search case sensitive
KEYWORD PARAMETERS:
text (contains the full text found), path(returns the full path to the text)
OUTPUTS:
result - status of function: 0 = success, -1 = failed to find
COMMON BLOCKS:
none
EXAMPLE:
IDL> result=SearchTextNodes('xray', text=text,path=path)
NOTES:
tree must already be open before tsearch can be called
if no records are found in current tree returns -1 else returns 0
MODIFICATION HISTORY:
01-Dec-00 Added capability for wildcards in search string
10-Nov-00 Added sensitivity [BD]
7-Feb-00 Written by Dana Mastrovito, PPPL
NAME:
setmdsshotevent
PURPOSE:
set an MDS event with shot number associated with the event
CATEGORY:
MDSplus, Events
CALLING SEQUENCE:
IDL> setmdsshotevent, eventName [, shot_num]
INPUTS:
eventName - string of MDS event name, e.g., 'NE_DENSITY_CALC'
shot_num - NSTX shot number (OPTIONAL -- will default to current shot)
KEYWORD PARAMETERS:
Optional:
VERBOSE - If set, print debugging information
NOCONNECT - if set, will not try to connect to an MDSplus server
SERVER - if not set, will connect to default server in OpenMDSshot
STATUS = return status, low bit set = success
OUTPUTS:
none -- just sets the event
COMMON BLOCKS:
NONE
EXAMPLE:
NOTES:
to test:
on one node:
IDL> wfmdsshotevent, 'mytest', shotnum
on another:
% setevent mytest 123456
or:
IDL> setmdsshotevent, 'mytest', 123456
on first node:
IDL> print, shotnum
BTW,
% setevent mytest 123456
will give 875770417, because data is not unpacked.
MODIFICATION HISTORY:
17-Dec-2008 don't try to fill valBlk if shot_num not a number [bd]
11-Nov-2008 Default to no mdsconnect [BD]
02-Nov-2008 Added status keword.
11-Feb-04 use SETEVENT in MDSVALUE on Unix. Add connect option on unix.
20-Dec-99 Written [bd]
NAME:
ShotDuration
PURPOSE:
Return the Shot Duration in seconds
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> seconds = ShotDuration(ishot, IpNeeded=IpNeeded, IpSignal=IpSignal, $
RoundUp=RoundUp)
INPUTS:
ishot - shot number. If not supplied, will use current shot
KEYWORD PARAMETERS:
Keywords:
IpNeeded - plamsa current in kiloAmps to be considered real (default=50)
IpSignal - mdsplus signal to use to determine plasma current
default = \wf::ip
NOTE if signal is not in kiloAmps, divide or multiply by correct factor
InSignal - input Ip signal, so doesn't have to be read
maxValue - returns max plasma current in KA.
nSmooth - the amount to smooth Ip signal before checking the value
Default = 11 points.
RoundUp - if set, add 0.1 seconds and round up to nearest 0.1 seconds
quiet - if not set, quiet
realquiet - if set, no "MDSOPEN success" message
Verbose - if set, print debugging information
Server - MDS server (default is for NSTX)
HLP - When set, help information is printed.
OUTPUTS:
seconds out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> opt = ShotDuration( IpNeeded=5, IpSignal='\engineering::ip2' )
to load a scalar with the shot duration time,
IDL> for i=shot1,shot2 do d=ShotDuration( i, outSig='\nstx::shotduration' )
NOTES:
MODIFICATION HISTORY:
07-Oct-2009 fixed bug recently introduced when reading default signal.
05-Mar-2008 Allow Ip to be passed in
18-Feb-2008 Account for WF tree, but no \IP
06-Feb-2008 replaced openMDSshot with mdsopen [BD]
25-Apr-2006 added MaxValue (for Ip) keyword
29-Aug-2005 nSmooth keyword added
28-Jul-2004 added realquiet keyword
08-Apr-2004 Written by Bill Davis, PPPL
NAME:
sigalert
PURPOSE:
Send email alerts when MDSplus signals are not acquired, or have
undesirable values.This routine can be run in your IDL session,
or it can be put into the "Auto-reload Facility" of NSTX-U.
CATEGORY:
MDSplus, events, Utility
CALLING SEQUENCE:
IDL> sigalert, signals, emails
INPUTS:
signals - list of MDSplus signals to monitor
emails - corresponding list of emails to notify of alarm condition
multiple recipients can be separated by a blank,comma or
semicolon. If emails are from PPPL, they do not have to have
the @pppl.gov.
KEYWORD PARAMETERS:
Inputs:
checkEvents - Events at which to check (defaults to SOP of next shot)
nSmooth - width of neighborhood to be used for the median filter
when checking for invalid values.
maxAllowed - alarm value(s) (alarm if filtered signal exceeds this)
minRequired - min required (alarm if filtered signal never reaches
this value)
if neither maxAllowed or minRequired are specified for a signal,
an alarm is raised only if there is no data for the shot
idlroutines - function to call to evaluate signal (optional)
epicsAlarm - EPICS alarm to set (optional)
setEvents - MDSplus event to set upon alarm condition (optional)
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
EXAMPLE:
IDL> sigalert, '\wf::mirnov_rms', 'bdavis', maxAllow=5
IDL> signals = ['\wf::ip', '\wf::pnb', '\wf::mirnov_rms' ]
IDL> emails = ['bdavis', 'bdavis', 'bdavis' ]
IDL> checkEvents = ['bdtest', 'bdtest1', 'bdtest' ]
IDL> sigalert, signals, emails, checkEvents=checkEvents, /debug
; should flag "too high":
IDL> sigalert, '\wf::ip', 'bdavis', checkEvents='bdtest', $
maxAllowed=800, testshot=142000, /debug
; should flag "too high":
IDL> sigalert, '\wf::ip', 'bdavis', checkEvents='bdtest', $
maxAllowed=800, testshot=142000, nsmooth=11, /debug
; should flag "too low":
IDL> sigalert, '\wf::ip', 'bdavis', checkEvents='bdtest', $
minReq=1000, testshot=142000, /debug
; should flag nothing:
IDL> sigalert, '\wf::ip', 'bdavis', checkEvents='bdtest', $
maxAllowed=2000, minReq=2, testshot=142000, /debug
IDL> sigalert, fileDir='/p/nstxops/bin/mds/SigAlert/Files', $
/debug
and then somewhere on Linux: setevent bdtest
NOTES:
If the alarm value is too large a negative value, the signal
could be specified as (-1*\signame)
MODIFICATION HISTORY:
03-Feb-2015 added files read recorded in log file
30-Sep-2013 Written by Bill Davis, PPPL, for Stefan Gerhardt
NAME:
TAG_EXIST
PURPOSE:
To test whether a tag name exists in a structure.
CATEGORY:
MDSplus, structure
CALLING SEQUENCE:
status = tag_exist(str, tag)
INPUTS:
str - structure variable to search
tag - tag name to search for
OUTPUTS:
Function returns 1 if tag name exists or 0 if it does not.
KEYWORDS:
INDEX = index of matching tag
METHOD:
Routine obtains a list of tagnames and tests whether the
requested one exists or not. The search is recursive so
if any tag names in the structure are themselves structures
the search drops down to that level.
Common : None
Restrictions: None
Side effects: None
Written : C D Pike, RAL, 18-May-94
Modified : 03-May-2007 datatype wasn't working, so just use SIZE [BD]
: Version 1.1, D Zarro, ARC/GSFC, 27-Jan-95
Passed out index of matching tag
Version : Version 1.1, 27-Jan-95
NAME:
tagRankOf
PURPOSE:
Return a list of MDSplus signals with a certain rank
(that contain data)
CATEGORY:
MDSplus
CALLING SEQUENCE:
tags = tagRankOf( rankDesired )
INPUTS:
rankDesired = 0 for scalars, 1 for vectors, etc.
KEYWORD PARAMETERS:
Optional Keywords:
filter - wild card specifer. E.g. '*ip*' will get all of
specifed rank with ip in the the tag name.
fullpaths - returns full pathnames of tags found
print - if set, tags and full pathnames found will be printed
debug - print some debugging info
the tree may be opened before this routine is called, or you can specify:
treeName - MDSplus tree. Default='NSTX' (unless embedded in nodeString)
shot - MDSplus shot to search. Default=-1 (the model tree).
server - MDSplus server. Default comes from the environmental variable _path
OUTPUTS:
tags = tagnames of specifed rank fitting any filter specified
if none are found fitting criteria, 'none' is returned.
EXAMPLE:
IDL> print, tagRankOf( 1, filter='i*', shot=120200, tree='wf' )
\WF::ICHI \WF::IOH \WF::IP \WF::IPF1AL \WF::IPF1AU \WF::IPF1B \WF::IPF2L \WF::IPF2U
\WF::IPF3L \WF::IPF3U \WF::IPF4 \WF::IPF5 \WF::ITF
IDL> mdsopen,'microwave', 120200
IDL> scalarNames = tagRankOf(0)
IDL> someSigs = tagRankOf( 1, filter='n*', /print )
COMMON BLOCKS:
none
NOTES:
Only returns signals with data in them.
LIMITATIONS:
An MDSplus shot file must be open first.
MODIFICATION HISTORY:
10-Jan-08 Added extra keywords for findMDSnodes [BD]
14-Mar-00 more efficient & added keywords [BD]
20-Jan-00 Written by Bill Davis
NAME:
tagsearch
PURPOSE:
Search MDS Plus Trees for a tag
CATEGORY:
MDSplus, Utility
CALLING SEQUENCE:
IDL> status=tagsearch(searchtag[,tag=tag, path=path])
INPUTS:
searchnode and optional variable to return an array of full paths containing
tag name and an array containing the tag names
KEYWORD PARAMETERS:
the tree may be opened before this routine is called, or you can specify:
Inputs (optional):
treeName - MDSplus tree. Default='NSTX' (unless embedded in nodeString)
shot - MDSplus shot to search. Default=-1 (the model tree).
server - MDSplus server. Default comes from the environmental variable _path
Returned:
path
tag
OUTPUTS:
status of function
COMMON BLOCKS:
none
EXAMPLE:
IDL> status=tagSearch('xp_', tag=tag, path=fullpath, tree='nstx')
NOTES:
will return 0 if tag is found and -1 if it is not found in the tree specified
MODIFICATION HISTORY:
08-May-2009 default to nstx tree if none indicated [BD]
10-Jan-08 use findMDSnodes, since findtags.fun not in Linux distribution [BD]
01-Dec-00 Added capability for wildcards in search string
28-Feb-00 Written by Dana Mastrovito, PPPL
NAME:
tdis
PURPOSE:
Search MDS Plus Trees for TDI DATA
CATEGORY:
MDSplus, Utility
CALLING SEQUENCE:
IDL> result = tdis( keyword[,sensitvity][, tdi=tdi][,path=path] )
INPUTS:
searchstring and optional variables to control case sensitivity and return an array of text strings found
and an array of paths to those strings
KEYWORD PARAMETERS:
(output)
tdi - the full tdi found
path - the full path to the text
OUTPUTS:
result=status of function
COMMON BLOCKS:
none
EXAMPLE:
IDL> result=tdi('build','sensitive',tdi=tdi,path=path)
NOTES:
this version is specifically for idl4 (?)
tree must already be open before tsearch can be called
if no records are found in current tree returns -1 else returns 0
MODIFICATION HISTORY:
30-Jan-00 Speed up. Fixed node names.
01-Dec-00 Added capability for wildcards in search string
07-Feb-00 Written by Dana Mastrovito, PPPL
NAME:
tree_exists
PURPOSE:
Return a true if an MDSplus tree exists for a given shot number
CATEGORY:
MDSplus, Trees
CALLING SEQUENCE:
found = tree_exists( shot, tree )
INPUTS:
(tree and shot arguments can be reversed, if shot is an number)
shot - MDSplus shot number, i.e, ID. Can be string acceptable to
mk_shotlist.pro
tree - tree to open. Defaults to 'wf'
KEWORDS:
(returned)
list - list of shots found
EXAMPLE:
IDL> IF tree_exists(101526,'operations') THEN ...
IDL> founds = tree_exists( '112300-112302 112305+2', 'wf', list=shots )
NOTE:
Returns true only if shot exists; the shot may be empty.
If you have an account on skylark.pppl.gov, you use mdir.pro,
which is faster.
19-Nov-2008 make work if input arguments are reversed
WRITTEN 15-Nov-2008 by Bill Davis (old version replaced)
NAME:
trimtagnames
PURPOSE:
Trim tree info from an MDSplus tag name
CATEGORY:
MDSplus, Tagnames
CALLING SEQUENCE:
trimmedList = trimtagnames( sigList )
INPUTS:
sigList - a string array of MDSplus tag names in
KEYWORD PARAMETERS:
(Optional)
all - if set, trim everything but string following the last :
treeOnly - if set only remove the tree (& top:).
Leave the backslash, TDI, etc.
OUTPUTS:
trimmedList - a string array of MDSplus tag names
EXAMPLE:
trimmedList = trimtagnames( sigList )
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
18-Oct-00 Added keyword treeOnly:
Don't assume tree name at beginning of string
(allows for trimming tree names from TDI expressions)
Written by Bill Davis March, 1999
NAME:
useSigMath
PURPOSE:
parse an MDSplus TDI string, substituting Brian Nelson's Signal Math TDI
routines for +,-,* and /, so timebases get adjusted, if necessary.
CATEGORY:
MDSplus
CALLING SEQUENCE:
IDL> newTDI = useSigMath( tdi )
INPUTS:
tdi = a TDI string in which any signals are preceded by '\'
OUTPUTS:
newTDI - math operations -, +, * & / are replaced by Brian Nelson's SigMath
functions sigsub, sigadd, sigmul and sigdiv.
EXAMPLE:
print, useSigMath('(\engineering::ip1+\engineering::ip2)/2')
SIGADD(\engineering::ip1,\engineering::ip2)/2
print, useSigMath('\wf::ip-\wf::ipf4/\wf::ipf5')
SIGDIV(SIGSUB(\wf::ip,\wf::ipf4),\wf::ipf5) NOTE ORDER OF OPERATIONS IS LEFT TO RIGHT
print, useSigMath('1000*\wf::ip-\engineering::ip1')
SIGSUB(1000*\wf::ip,\engineering::ip1)
print, useSigMath('(\engineering::ip1/1000 - \wf::ip)')
SIGSUB(\engineering::ip1/1000,\wf::ip)
print, useSigMath('1000*\wf::ip-\engineering::ip1')
SIGSUB(1000*\wf::ip,\engineering::ip1)
print, useSigMath('\wf::ip-bcsmooth(\engineering::ip1/1000)')
SIGSUB(\wf::ip,bcsmooth(\engineering::ip1/1000))
print, useSigMath('1000*\wf::ip-(\engineering::ip1+\engineering::ip2)/2')
SIGSUB(1000*\wf::ip,SIGADD(\engineering::ip1,\engineering::ip2)/2)
print, useSigMath('abs(bcsmooth(\engineering::ip1/1000)-\wf::ip)')
(abs(SIGSUB(bcsmooth(\engineering::ip1/1000),\wf::ip)))
print, useSigMath('\wf::ip-\wf::ip[0]')
LIMITATIONS:
Without brackets expressions will be evaluated from left to right.
The SigMath routines do not correct for different units, like Amps and KiloAmps.
Signals are only recognized when they begin with a backslash.
MODIFICATION HISTORY:
04-Aug-2008 made to work (i.e., not use Sigmath) with '\wf::ip-\wf::ip[0]'
WRITTEN 10-Aug-2007 by Bill Davis
NAME:
wfMDSshotEvent
PURPOSE:
Wait for an MDSplus event, with shot number coming in
CATEGORY:
MDSplus, Events
CALLING SEQUENCE:
wfMDSshotEvent, event, shotnum, [,/QUIET][,STATUS=istat]
INPUT PARAMETERS:
event = name of an MDSplus event to wait for.
RETURNED PARAMETERS:
shotnum - whatever data was passed when the event was set.
for MDSplus events, except for nstx_acq_started
Keywords (Optional):
ASCII - if set, will assume data block contains ascii representation of numbers
NOCONNECT - if set, will not try to connect to an MDSplus server
SERVER - if not set, will connect to default server in OpenMDSshot
QUIET = prevents IDL error if MDSplus command fails
STATUS = return status, low bit set = success
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
PROCEDURE:
Makes a call to MDSplus shared image library
procedure MDS$WTEVENT and checks for errors.
NOTES:
to test:
on one node:
IDL> wfmdsshotevent, 'mytest', shotnum
on another:
% setevent mytest 123456
or:
IDL> setmdsshotevent, 'mytest', 123456
on first node:
IDL> print, shotnum
BTW,
% setevent mytest 123456
will give 875770417, because data is not unpacked.
; MODIFICATION HISTORY:
11-Nov-2008 Default to no mdsconnect [BD]
02-Nov-2008 Return -1 if error from mdsvalue. Have an option not to
connect.
09-Mar-2007 Added ASCII keyword which is needed on sflip PC
08-Jul-2005 Added support for Windows
31-May-05 include server keyword
06-Apr-05 use MdsValue( 'WFEVENT($)'... instead. [BD]
24-May-01 If on Unix, connect to VMS if not already [BD]
06-Nov-00 Made same version work on VMS & Unix [BD]
copied from mds$wfevent.pro, so could have the same name on vms & unix
VERSION 1.0, CREATED BY T.W. Fredian, April 22,1991
debug version 7/14/05 PR syntax error in if/endif structure
NAME:
WithRankOf
PURPOSE:
Return a list of MDSplus signals with a certain rank
(that contain data)
CATEGORY:
MDSplus
CALLING SEQUENCE:
sigs=withrankof( rank )
INPUTS:
rank - integer rank of signal desired
KEYWORD PARAMETERS:
filter - wildcard specification to find signal names with desired rank
signalnames - if present, use these, and ignore filter
OUTPUTS:
sigs - MDSplus signal names with
EXAMPLE:
IDL> stat=mdsopen('passivespec',101964)
IDL> scalarNames = withrankof(0)
COMMON BLOCKS:
none
NOTES:
Only returns signals with data in them.
LIMITATIONS:
An MDSplus shot file must be open first.
MODIFICATION HISTORY:
31-Jan-07 add keyword to pass in signalnames
20-Jan-00 Written by Bill Davis
Category: Misc
[List of Routines]
NAME:
addGPIcomment.pro
PURPOSE:
add comments to a file for GPI web pages
CATEGORY:
GPI, Web, NSTX
CALLING SEQUENCE:
IDL> addGPIcomment, headline=headline, Description=Description, username=username, $
shot=shot, PagePassword='something',
INPUT KEYWORDS:
Required:
username - Linux username of person making entry
PagePassword - this is required
shot - NSTX shot # for which comment applies
headline - a one-line Summary of status
Optional:
Description - more detailed comment, can be up to 20 lines
outFile - web page, DEFAULT='/w/nstx.pppl.gov/htdocs/nstx/Software/nstxstatus.html'
maxLength - max length of status field
logfile - name of log file.
DEFAULT='/local/nstxops/web/log/addGPIcomment.log'
debug - if set prints debugging info
verbose - if set prints lots of info
status - if odd, successful
OUTPUTS:
appends to a text file, comments.txt, to a web-accessible directory.
METHOD:
Gets data for fields (like Description) to be updated from addGPIcomment.html
(via idlMDSPlotServer2550.pl) and appends to the output file.
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> addGPIcomment, shot=999999, headline='This is a test', $
username='bdavis', PagePassword='Masa', /debug
IDL> addGPIcomment, shot=999999, headline='This is a big test', $
username='bdavis', PagePassword='Masa', $
description=strconcat(replicate('blah', 200), delim=' '), /debug
MODIFICATION HISTORY:
15-Oct-2013 Written by Bill Davis, PPPL, for Stewart Zweben
NAME:
BAD_PTDATA_ERROR
PURPOSE:
Return a logical true IF the PTDATA error is serious
CATEGORY:
GA, error processing
CALLING SEQUENCE:
logical = Bad_PTDATA_Error(ptdata_ierr)
INPUTS:
ptdata_ierr - error return from PTDATA calls
KEYWORD PARAMETERS:
OUTPUTS:
RETURNED: logical indication of a serious error
(per IDL definition, e.g., 0 IF false)
COMMON BLOCKS:
MODIFICATION HISTORY:
1-Apr-97 WMD Written
NAME:
blobvyfit
PURPOSE:
plot Poloidal velocity (Vy) of blobs from Fast Camera data
vs. distance from the separatrix. Bin and smooth things so
a curve can be fit through data, with the ultimate goal
of categorizing the vertical shear.
CATEGORY:
GPI
CALLING SEQUENCE:
blobvyfit, shot, BinSize=binsize, barFraction=barFrac, $
title=title, Overlay=Overlay, $
WindowTitle=WindowTitle, GROUP_LEADER=group_leader, $
XSIZE=xsize_in, YSIZE=ysize_in, xtitle=xtitle, ytitle=ytitle, $
_extra=_extra
INPUTS:
shot - NSTX shot number
OUTPUTS:
plot in graphics widget
KEYWORDS:
barFraction - fraction of interval over which bar is drawn (0-1)
(default=0.5)
BinSize - The size of each bin of the histogram, scalar (not necessarily
integral). If not present (or zero), the bin size is set to 1.
Overlay - if set, overlay a curve
ShotList - list of shots to cycle through
EXAMPLE:
IDL> blobvyfit, 138234
; to be able to make JPEGS for all shots, with fixed limits:
IDL> blobvyfit, 138234, plotLimitsFile='PlotLims.txt'
MODIFICATION HISTORY:
17-Feb-2014 Written by Bill Davis
NAME:
BPWFEDIT
PURPOSE:
Read, Edit, & Plot Breakpoint Waveform files used in ppcc system on TFTR
CATEGORY:
TFTR, Waveforms, GUI Editing
REVISION HISTORY:
21-Aug-98 Written by Bill Davis
NAME:
CAMAC_here
PURPOSE:
Return 1 if CAMAC on this computer
(if environmental variable "camac_server" is non-blank)
CATEGORY:
CAMAC
CALLING SEQUENCE:
IDL> OK = CAMAC_here()
INPUTS:
none required
KEYWORD PARAMETERS:
var - Environmental variable to check to determine if CAMAC available.
(defaults to 'camac_server')
HLP - When set, help information is printed.
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
OK = 1 if environmental variable "camac_server" is non-blank
EXAMPLE:
NOTES:
When the routine is called with the
keyword hlp set, help information is printed.
MODIFICATION HISTORY:
08-Jan-2009 Written by Bill Davis, PPPL
NAME:
CH_Example
PURPOSE:
a simple example using the GA Crosshair routines
CATEGORY:
GUI Graphics, Example
CALLING SEQUENCE:
CH_Example
COMMON BLOCKS:
ch_example
NOTES:
Your display may have to be set to 256 colors to see the crosshairs.
MODIFICATION HISTORY:
Written by Bill Davis, 8/29/97
GA Crosshair routines originally written by John Ferron.
Now maintained by T. Terpstra
NAME: ch_register PURPOSE: register window for crosshair routines CATEGORY: GUI Graphics, Cursor Cross-hairs EXAMPLE: See ch_example.pro MODIFIED: 29-Nov-07 Don't handle if window names not found in ch_set [BD] 30-Oct-00 Override !P.PSYM & !P.LINESTYLE for cros-hairs [BD] 04-Dec-99 Make mask bit 6, so it's red when used with MK_COLOR [BD] 29-Mar-99 Added newX, newY & newP keywords to CH_SET for changing plotting parameters [BD] 26-Jan-99 Taken from GA [BD] Combining all ch_ files here, since this must be called 1st.
NAME:
COPY_STRUCT
PURPOSE:
Copy all fields with matching tag names from one structure to another
CATEGORY:
Programming
EXPLANATION
Fields with matching tag names are copied from one structure array to
another structure array of different type.
This allows copying of tag values when equating the structures of
different types is not allowed, or when not all tags are to be copied.
Can also recursively copy from/to structures nested within structures.
Note that the number of elements in the output structure array
is automatically adjusted to equal the length of input structure array.
If this not desired then use pro copy_struct_inx which allows
specifying via subscripts which elements are copied where in the arrays.
CALLING SEQUENCE:
copy_struct, struct_From, struct_To, NT_copied
copy_struct, struct_From, struct_To, EXCEPT=["image","misc"]
copy_struct, struct_From, struct_To, /RECUR_TANDEM
INPUTS:
struct_From = structure array to copy from.
struct_To = structure array to copy values to.
KEYWORDS:
EXCEPT_TAGS = string array of tag names to ignore (to NOT copy).
Used at all levels of recursion.
SELECT_TAGS = tag names to copy (takes priority over EXCEPT).
This keyword is not passed to recursive calls in order
to avoid the confusion of not copying tags in sub-structures.
/RECUR_FROM = search for sub-structures in struct_From, and then
call copy_struct recursively for those nested structures.
/RECUR_TO = search for sub-structures of struct_To, and then
call copy_struct recursively for those nested structures.
/RECUR_TANDEM = call copy_struct recursively for the sub-structures
with matching Tag names in struct_From and struct_To
(for use when Tag names match but sub-structure types differ).
OUTPUTS:
struct_To = structure array to which new tag values are copied.
NT_copied = incremented by total # of tags copied (optional)
INTERNAL:
Recur_Level = # of times copy_struct calls itself.
This argument is for internal recursive execution only.
The user call is 1, subsequent recursive calls increment it,
and the counter is decremented before returning.
The counter is used just to find out if argument checking
should be performed, and to set NT_copied = 0 first call.
EXTERNAL CALLS:
pro match (when keyword SELECT_TAGS is specified)
PROCEDURE:
Match Tag names and then use corresponding Tag numbers.
HISTORY:
written 1989 Frank Varosi STX @ NASA/GSFC
mod Jul.90 by F.V. added option to copy sub-structures RECURSIVELY.
mod Aug.90 by F.V. adjust # elements in TO (output) to equal
# elements in FROM (input) & count # of fields copied.
mod Jan.91 by F.V. added Recur_Level as internal argument so that
argument checking done just once, to avoid confusion.
Checked against Except_Tags in RECUR_FROM option.
mod Oct.91 by F.V. added option SELECT_TAGS= selected field names.
mod Aug.95 by W. Landsman to fix match of a single selected tag.
mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion.
NAME:
CW_ANIMATE_DUPS
PURPOSE:
This widget displays an animated sequence of images using
X-windows Pixmaps. This is a compound widget, based on the
XINTERANIMATE procedure, with the following advantages:
- It can be included in other applications.
- Multiple copies can be run simultaneously.
The speed and direction of the display can be adjusted using
the widget interface.
CATEGORY:
Image display, compound widgets.
CALLING SEQUENCE:
To initially create:
widget = CW_ANIMATE_DUPS(PARENT, SIZEX, SIZEY, NFRAMES)
To reinitialize when another animation is loaded:
CW_ANIMATE_DUPS_INIT, ANIMATEBASE, SIZEX, SIZEY, NFRAMES
To load a single image:
CW_ANIMATE_DUPS_LOAD, WIDGET, IMAGE = IMAGE, FRAME = FRAME_INDEX
To load a single image that is already displayed in an existing window:
CW_ANIMATE_DUPS_LOAD, WIDGET, FRAME = FRAME_INDEX, $
WINDOW = [WINDOW_NUMBER [, X0, Y0, SX, SY]]
(This technique is much faster than reading back from the window.)
To display the animation after all the images have been loaded:
CW_ANIMATE_DUPS, WIDGET [, RATE]
To get a copy of the vector of Pixmaps being used by the widget.
If this routine is called, the widget does not destroy the pixmaps
when it is destroyed. The user can then provide them to a later
call to CW_ANIMATE_DUPS to re-use them while skipping the Pixmap creation
and rendering step:
CW_ANIMATE_DUPS_GETP, widget, PIXMAPS
INPUTS:
CW_ANIMATE_DUPS:
PARENT: The ID of the parent widget.
SIZEX: The width of the displayed image.
SIZEY: The height of the displayed image.
NFRAMES: The number of frames in the animation sequence.
CW_ANIMATE_DUPS_INIT:
ANIMATEBASE: The ID of the base animation widget.
SIZEX: The width of the displayed image.
SIZEY: The height of the displayed image.
NFRAMES: The number of frames in the animation sequence.
CW_ANIMATE_DUPS_LOAD:
WIDGET: The ID of the widget (as created with CW_ANIMATE_DUPS)
into which the image should be loaded.
CW_ANIMATE_DUPS_RUN:
WIDGET: The ID of the widget (as created with CW_ANIMATE_DUPS)
into which the image should be loaded.
RATE: A value between 0 and 100 that represents the
speed of the animation as a percentage of the
maximum display rate. The fastest animation has
a value of 100 and the slowest has a value of 0.
The default animation rate is 100.
STOP: If this keyword is set, the animation is stopped.
NFRAMES: Specifies the number of frames to animate, must
<= the number specified in CW_ANIMATE_DUPS().
KEYWORD PARAMETERS:
CW_ANIMATE_DUPS:
PIXMAPS: This keyword provides the new widget with a vector
of pre-existing pixmap (off screen window) IDs.
This vector is usually obtained from a call to
CW_ANIMATE_DUPS_GETP applied to a previous animation
widget.
UVALUE: A user supplied value to be stored in the widget's
user value field.
UNAME: A user supplied string name to be stored in the
widget's user name field.
NO_KILL: If NOT set, an "End Animation" button is added to the
animation base. If set the button is not added.
OPEN_FUNC: A user supplied string that specifies a callback
function name. When a value is specified for this
keyword, an "Open..." pushbutton is added to the
window. When the "Open..." pushbutton is clicked
the OPEN_FUNC function is called to load new
animation data.
INFO_FILE: A filename containing text to be displayed by
XDISPLAYFILE when user selects the help button.
CW_ANIMATE_DUPS_INIT:
PIXMAPS: This keyword provides the new widget with a vector
of pre-existing pixmap (off screen window) IDs.
This vector is usually obtained from a call to
CW_ANIMATE_DUPS_GETP applied to a previous animation
widget.
CW_ANIMATE_DUPS_LOAD:
CYCLE: If set, cycle. Normally, frames are displayed
going either forward or backwards. If CYCLE is
set, reverse direction after the last frame in
either direction is displayed.
FRAME: The frame number to be loaded. This is a value
between 0 and NFRAMES. If not supplied, frame 0
is loaded.
IMAGE: The image to be loaded.
ORDER: Set this keyword to display images from the top
down instead of the default bottom up. This keyword
is only used when loading images with the IMAGE
keyword.
TRACK: If set, the frame slider tracks the current frame.
Default is not to track.
WINDOW: When this keyword is specified, an image is copied
from an existing window to the animation pixmap.
When using X windows, this technique is much faster
than reading from the display and then loading with
the IMAGE keyword.
The value of this parameter is either an IDL window
number (in which case the entire window is copied),
or a vector containing the window index and the
rectangular bounds of the area to be copied. For
example:
WINDOW = [Window_Number, X0, Y0, Sx, Sy]
XOFFSET: The horizontal offset, in pixels from the left of
the frame, of the image in the destination window.
YOFFSET: The vertical offset, in pixels from the bottom of
the frame, of the image in the destination window.
OUTPUTS:
No explicit outputs.
SIDE EFFECTS:
If the widget is realized before calls to CW_ANIMATE_DUPS_LOAD, the frames
are displayed as they are loaded. This provides the user with an
indication of how things are progressing.
When the widget is destroyed, it destroys the pixmaps used in the
animation, unless they were previously obtained via CW_ANIMATE_DUPS_GETP
and the KILL_ANYWAY keyword was not set.
The only event returned by this widget indicates that the user
has pressed the DONE button. The parent application should use
this as a signal to kill the animation widget via WIDGET_CONTROL.
RESTRICTIONS:
If more than one animation widget is running at a time, they
will fight for resources and run slower.
PROCEDURE:
When initialized, this procedure creates pixmaps containing the
frames of the animation sequence. Once the images are loaded,
they are displayed by copying the images from the pixmap or buffer
to the visible draw widget.
EXAMPLE:
Assume the following event handler procedure exists:
PRO EHANDLER, EV
WIDGET_CONTROL, /DESTROY, EV.TOP
end
Enter the following commands to open the file ABNORM.DAT (a series
of images of a human heart) and load the images it contains into
an array H:
OPENR, 1, FILEPATH('abnorm.dat', SUBDIR = 'images')
H = BYTARR(64, 64, 16)
READU, 1, H
CLOSE, 1
H = REBIN(H, 128, 128, 16)
Create an instance of the animation widget at load the frames:
base = widget_base()
animate = CW_ANIMATE_DUPS(base, 128, 128, 16)
WIDGET_CONTROL, /REALIZE, base
for i=0,15 do CW_ANIMATE_DUPS_LOAD, animate, FRAME=i, IMAGE=H[*,*,I]
Start the animation:
CW_ANIMATE_DUPS_RUN, animate
XMANAGER, "CW_ANIMATE_DUPS Demo", base, EVENT_HANDLER = "EHANDLER"
Pressing the DONE button kills the application.
MODIFICATION HISTORY:
AB, June 1992 Heavily based on the XINTERANIMATE procedure.
SR, September 1992 Fixed a problem when a paused animation's
frame selection was moved and the resulting
frame change ended up in another animation.
SR, November 1992 Fixed a problem when a single paused animation
would fail when the frame selection slider
event tried to set do a bad drawing window.
DMS/AB, March, 1993 Got rid of state caching. Got rid of
XMANAGER background tasks in favor of new
"WIDGET_CONTROL,timer=" feature.
ACY, October 1993 Set RETAIN=2 for draw widget to prevent
clipping by an overlapping window when
loading frames.
DMS, Dec, 1993 Added STOP and NFRAMES keywords to CW_ANIMATE_DUPS_RUN.
Added KILL_ANYWAY keyword to CW_ANIMATE_DUPS_GETP.
WSO, Jan, 1995 Added OPEN_FUNC keyword and updated UI.
ACY, Jan, 1997 Added INFO_FILE keyword to allow user-supplied
files for help text
JLP, Jan, 2000 Allow TrueColor images as input to CW_ANIMATE_DUPS_LOAD.
WMD, Jul, 2010 Add NDUPS field when writing MPEGS so playback can be slower.
WMD, Aug, 2010 Added button for writing QuickTime movies; "jmovie" script
needs to be known when spawned. At PPPL jmovie is aliased to
/p/nstxusr//util/scripts/javamoviemaker.csh which uses
/u/efeibush/w3_html/makemovie/jpegtomovie.jar
Project : SOHO - CDS
Name : FIND_COMMON()
Purpose : Find which elements are common to the input vectors.
Explanation : Returns the indices of the elements in second vector which
are also present in the first vector.
Use : IDL> c = find_common(first, second)
Inputs : first - vector to be searched
second - search vector
Opt. Inputs : None
Outputs : Function returns indices of elements in second vector which
are common to first and second vectors
Opt. Outputs: None
Keywords : None
Calls : FIND_DUP()
Common : None
Restrictions: None
Side effects: None
Category : Util
Prev. Hist. : None
Written : C D Pike, RAL, 9-Nov-94
Modified : Make loop variable LONG. CDP, 1-Oct-97
Version : Version 2, 1-Oct-97
NAME:
findpeaks
PURPOSE:
Find peaks in a data array. To be a peak a local maximum must have
a 25% higher range than the first and last quarter of the peak range.
CATEGORY:
Data Analysis
CALLING SEQUENCE:
IDL> peaks = findpeaks( data )
INPUTS:
data - array
OUTPUTS:
peaks - (up to "maxPeaks") values of peaks found. Returns 0 if no
peaks found.
KEYWORDS:
Optional Input:
maxPeaks - max # of peaks to search for (DEF=2)
AboveFrac - Fraction of peak height that peak must be above the
peak "tails" to be counted (default=0.25)
NeighborhoodFrac - fraction of whole X range to be a neighborhood.
Range is initially divided up in these neighborhoods
for determination of initial maxima.
HowCloseToMax - if set, will not be considered a peak, if not within
this fraction of maximum of whole data set.
OnlyBig - if set will not count peaks 1/3 the size of the biggest peak
Plot - if set, will plot data with vertical lines indicating which
peaks qualified.
Ordered - if set, returns peaks in order of highest first
Optionally Returned via Keyword:
indicesOfPeaks - array indices of peaks returned (=-1 if no peaks found)
FWHM - full width at half max estimate, in indices
nAbove - # points above 2*median
EXAMPLE:
IDL> data = mk_2peaks()
IDL> peaks = findpeaks( data, /plot )
IDL> peaks = findpeaks( data, indicesOfPeaks=indicesOfPeaks )
COMMON BLOCKS:
none
NOTES:
Maxima too close to the beginning and end of array are not counted.
You may wish to do filtering or smoothing before passing data.
LIMITATIONS:
What constitutes a "peak" is subjective, so this won't fit all needs
MODIFICATION HISTORY:
03-Dec-2014 added output keyword nAbove
07-Oct-2013 fixed bug when more than 16K points in a range being
examined for peaks (as in fast camera averages)
added SATURATED keyword, to count peaks flattopping
05-Aug-2008 Added HowCloseToMax keyword & many mods for finding Lithium peaks
08-May-2003 Written by Bill Davis, PPPL
NAME:
fluxcoords
PURPOSE:
Return flux coordinates for input R values at a given Z
CATEGORY:
Physics, Plotting
CALLING SEQUENCE:
IDL> newXs = fluxcoords( shot=shot, time=time, Radius=Radius, z=z )
INPUTS:
(only keywords)
KEYWORD PARAMETERS:
Inputs
Required:
shot - NSTX shot number
time - time after T0, in seconds
Radius - floating point array of major radii, in meters
Optional:
Z - Z value (above mid-plane) in meters (default = 0), scalar or dimensioned
same as Radius.
fit - E.g., 'EFIT01', EFIT02', 'LRDFIT04', etc. (defaults to 'EFIT01')
psi_n - if set, will return on psi_n surfaces
verbose - if set, will print many informational messages
Outputs
newXs - transformed input points to rho or psi_n, depending on keyword inputs
status - if odd, then was successful
OUTPUTS:
opt = returned value out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> Radius=findgen(10)/10.*.30+1.50
IDL> newXs = fluxcoords( shot=121100, time=0.205, Radius=Radius, fit='EFIT01')
IDL> newXs = fluxcoords( shot=120440, time=0.206, Radius=Radius, z=0.5, fit='lrdfit09')
NOTES:
Slow 1st time called for each new time. Especially slow for LRDFIT trees because
need to an MDSCONNECT to VMS, for some reason, for this to work.
MODIFICATION HISTORY:
01-Oct-2008 Removed mdsconnect [BD]
22-Feb-2007 Written by Bill Davis, PPPL, using LOTS of code from Jon Menard
NAME:
getCmodEfit
PURPOSE:
Get efit data from CMOD for separatrix and limiter locations
CATEGORY:
CMOD
CALLING SEQUENCE:
IDL>
INPUTS:
shot = CMOD shot number
KEYWORD PARAMETERS:
Inputs:
tree - MDSplus tree
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
status - if odd, then success
OUTPUTS:
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> getcmodefit, 1100824017, rbbbs=rbbbs, zbbbs=zbbbs, $
nbbbs=nbbbs, efitTimes=efitTimes ,/debug
NOTES:
MODIFICATION HISTORY:
29-Nov-2012 use connect_cmd
21-Dec-2011 Written by Bill Davis, PPPL
NAME:
get_webplotsum
PURPOSE:
Creates summary plots vs time with plasma current, D-alpha,
injected power and stored energy (W-mhd).
CATEGORY:
Web
CALLING SEQUENCE:
IDL> image = get_webplotsum( ishot )
INPUTS:
shot = NSTX shot number
KEYWORD PARAMETERS:
Inputs:
(many)
EXAMPLE:
image = get_webplotsum( ishot, tois=ftime[0:nActualTimes-1]/1000., $
sig=signals, status=status )
if status then begin
jfile = 'SHOTSUMMARY_'+strtrim( ishot, 2 )+'.jpeg'
mk_jpeg, filename=dir+subDir+jfile, image=image
PRINTF,LUN,'
'
endif
image = get_webplotsum( 127264, tois=[50,100,150,200,300]/1000.)
tv, image, true=1
MODIFICATION HISTORY:
04-Mar-2008 call webplotsum to add W-mhd (stored energy) to plot
WRITTEN by Bill Davis, PPPL
NAME: IDLV4_TO_V5 PURPOSE: Modify an IDL V4.0 (or earlier) procedure such that variables are indexed using square brackets, as allowed (and suggested) within IDL V5.0 and later CALLING SEQUENCE: IDLV4_TO_V5, infiles, outdir INPUTS: infiles - scalar string specifying IDL procedure name(s), wild card values allowed outdir - scalar string giving directory to contain output file. EXAMPLES: Convert the procedure curvefit.pro in the current directory to a IDL V5 version in the (Unix) idlv5 directory IDL> idlv4_to_v5,'curvefit.pro','idlv5/' Convert all the procedures in the current directory to IDL V5 versions in the /share/idlv5 directory IDL> idlv4_to_v5, '*.pro', '/share/idlv5/' METHOD: ISFUNCTION() is used to determine all the routine names in the file, and then ROUTINE_INFO() is used to determine the names of all variables in the procedure. Each (non-commented) line is scanned for parentheses, and converted to square brackets if the token to the left of the left parenthesis matches a variable name. NOTES: (1) Only runs under IDL V5.0 (since it calls ROUTINE_INFO()) (2) May possibly get confused by parenthesis within strings. (3) May get confused by IDL statements that extend over multiple lines idlv4_to_v5 will supply a warning when it becomes confused by unmatched parenthesis. (4) Do not include this procedure 'idlv4_to_v5' in the directory that you are trying to convert (since it will compile the procedure while executing it, and do a retall.) (5) Conversions cannot be performed unless specified procedure(s) already compile properly (6) Will not work on IDL main programs (7) May get confused by gaps between array name and parenthesis PROCEDURES CALLED: FDECOMP, MATCH, REMOVE, ISFUNCTION() REVISION HISTORY: Written W. Landsman Hughes STX June 1997 Variable names can have numerals August 1997 Never change an intrinsic IDL function to square brackets, even if it is also a variable name.
NAME:
MATCH
PURPOSE:
Routine to match values in two vectors.
CALLING SEQUENCE:
match, a, b, suba, subb, [ COUNT =, /SORT ]
INPUTS:
a,b - two vectors to match elements, numeric or string datatype
OUTPUTS:
suba - subscripts of elements in vector a with a match
in vector b
subb - subscripts of the positions of the elements in
vector b with matchs in vector a.
suba and subb are ordered such that a[suba] equals b[subb]
OPTIONAL INPUT KEYWORD:
/SORT - By default, MATCH uses two different algorithm: (1) the
/REVERSE_INDICES keyword to HISTOGRAM is used for integer data,
while a sorting algorithm is used for non-integer data. The
histogram algorithm is usually faster, except when the input
vectors are sparse and contain very large numbers, possibly
causing memory problems. Use the /SORT keyword to always use
the sort algorithm.
OPTIONAL KEYWORD OUTPUT:
COUNT - set to the number of matches, integer scalar
SIDE EFFECTS:
The obsolete system variable !ERR is set to the number of matches;
however, the use !ERR is deprecated in favor of the COUNT keyword
RESTRICTIONS:
The vectors a and b should not have duplicate values within them.
You can use rem_dup function to remove duplicate values
in a vector
EXAMPLE:
If a = [3,5,7,9,11] & b = [5,6,7,8,9,10]
then
IDL> match, a, b, suba, subb, COUNT = count
will give suba = [1,2,3], subb = [0,2,4], COUNT = 3
and suba[a] = subb[b] = [5,7,9]
METHOD:
For non-integer data types, the two input vectors are combined and
sorted and the consecutive equal elements are identified. For integer
data types, the /REVERSE_INDICES keyword to HISTOGRAM of each array
is used to identify where the two arrays have elements in common.
HISTORY:
D. Lindler Mar. 1986.
Fixed "indgen" call for very large arrays W. Landsman Sep 1991
Added COUNT keyword W. Landsman Sep. 1992
Fixed case where single element array supplied W. Landsman Aug 95
Converted to IDL V5.0 W. Landsman September 1997
Use a HISTOGRAM algorithm for integer vector inputs for improved
performance W. Landsman March 2000
Work again for strings W. Landsman April 2000
NAME:
ij2rz
PURPOSE:
Convert from fast GPI camera pixels at CMOD or NSTX to R & Z
CATEGORY:
Fast 2-D Cameras
CALLING SEQUENCE:
IDL> ij2rz, shot=shot, cam=cam, nx=nx, ny=ny, $
Rvals=Rvals, Zvals=Zvals
INPUTS:
KEYWORD PARAMETERS:
Inputs:
shot - CMOD or NSTX shot number (default to 1120224029)
cam - default to 1 for NSTX (only one), but 2 (X-pt) for CMOD
nx - # of pixels in X (defaults to that of camera)
ny - # of pixels in Y (defaults to that of camera)
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
Rvals - 2-D array of R (major Radius) values in meters of pixel location
(at Gas Puff)
Zvals - 2-D array of Z values (m) of pixel location (at Gas Puff)
OUTPUTS:
EXAMPLE:
IDL> ij2rz, shot=1120224029, cam=1, $ ; input
Rvals=Rvals, Zvals=Zvals ; returned
NOTES:
Unrotated images from NSTX are read as [80,64]. Since these need to
to be rotated so up is up, default to ny=80.
MODIFICATION HISTORY:
25-Sep-2012 don't transpose R-Z values, so 80 pixels is in vertical direction
27-Aug-2012 Written by Bill Davis, PPPL, for Stewart Zweben
NAME: ISFUNCTION() PURPOSE: Determine whether the IDL program(s) in a file are procedures or functions. Needed because the intrinisc RESOLVE_ROUTINE and ROUTINE_INFO() procedures require the user to know beforehand whether to supply the /IS_FUNCTION or /FUNCTION keywords. CALLING SEQUENCE: status = ISFUNCTION( filename, [ outnames, numlines] INPUT: filename = scalar string giving complete specification if file name (include .pro extension) OUTPUT: status - integer vector with number of elements equal to the number of routines in the file. Each status value consists of 0 or 1 1 - routine is an IDL function 0 - routine is an IDL procedure If no valid IDL functions or procedures are found in the file, then ISFUNCTION() returns a scalar value of -1 OPTIONAL OUTPUTS: outnames - vector string, giving name of each IDL procedure or function in the file numlines - integer vector, giving the number of lines in each IDL procedure or function in the file PROCEDURE CALLS: FDECOMP REVISION HISTORY: Written, W. Landsman June, 1995
NAME:
ISNUMBER
PURPOSE:
Determine if a text string is a valid number.
CATEGORY:
CALLING SEQUENCE:
i = isnumber(txt, [x])
INPUTS:
txt = text string to test. in
KEYWORD PARAMETERS:
OUTPUTS:
x = optionaly returned numeric value if valid. out
i = test flag: out
0: not a number.
1: txt is a long integer.
2: txt is a float.
-1: first word of txt is a long integer.
-2: first word of txt is a float.
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
28-Feb-2011 don't call a character when has a minus sign [BD]
15-Feb-2008 don't consider date string, like 02/15/2008, a number [BD]
29-Oct-2007 return 0 if input not defined [BD]
01-Dec-2006 handle structures (treat as not a number) [Bill Davis]
Richard Garrett, 14 June, 1992 --- fixed bug in returned float value.
R. Sterner, 12 Mar, 1990 --- upgraded.
R. Sterner. 15 Oct, 1986.
Johns Hopkins Applied Physics Lab.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
LINT
PURPOSE:
Find the intersection of two lines in the XY plane.
CATEGORY:
CALLING SEQUENCE:
lint, a, b, c, d, i1, i2
INPUTS:
a, b = Points on line 1. in
c, d = Points on line 2. in
KEYWORD PARAMETERS:
Keywords:
FLAG=f Returned flag:
0 means no intersections (lines parallel).
1 means one intersection.
2 means all points intersect (lines coincide).
/COND print condition number for linear system.
OUTPUTS:
i1, i2 = Returned intersection. out
Both i1 and i2 should be the same.
COMMON BLOCKS:
NOTES:
Notes: Each point has the form [x,y].
MODIFICATION HISTORY:
R. Sterner, 1998 Feb 4
Copyright (C) 1998, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
listFromPerl
PURPOSE:
Called from a Perl Script to list MDSplus data from a Web Page
CATEGORY:
WebTools, MDSplus
MODIFICATION HISTORY:
14-Jul-04 added parseShotInput for handling inputs
NAME:
MAKEN
PURPOSE:
Make an array of N values, linear between two given limits.
CATEGORY:
CALLING SEQUENCE:
x = makex( first, last, num)
INPUTS:
first, last = array start and end values. in
num = number of values from first to last. in
KEYWORD PARAMETERS:
OUTPUTS:
x = array of values. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
Ray Sterner, 26 Sep, 1984.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1984, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
MAKENXY
PURPOSE:
Make 2-d x and y coordinate arrays of specified dimensions.
CATEGORY:
CALLING SEQUENCE:
makenxy, x1, x2, nx, y1, y2, ny, xarray, yarray
INPUTS:
x1 = min x coordinate in output rectangular array. in
x2 = max x coordinate in output rectangular array. in
nx = Number of steps in x. in
y1 = min y coordinate in output rectangular array. in
y2 = max y coordinate in output rectangular array. in
ny = Number of steps in y. in
KEYWORD PARAMETERS:
OUTPUTS:
xarray, yarray = resulting rectangular arrays. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 1996 Jul 11
Copyright (C) 1996, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
mdsw_noch
PURPOSE:
Plot one MDS signal simply (without Crosshairs)
CATEGORY:
Example
CALLING SEQUENCE:
mdsw_noch
COMMON BLOCKS:
mdsw_noch
NOTES:
Your display may have to be set to 256 colors to see the crosshairs.
LIMITATIONS:
The printers and help file used here only work from UNIX.
Only one version of this program may be run from a given IDL session.
MODIFICATION HISTORY:
11-Feb-99 Using UNSETUP_X rather than SETUP_X
28-Jan-99 Took out cross-hair routines
26-Jan-99 Modified for using MDS at PPPL by Bill Davis
8/29/97 CH_example written by Bill Davis,
NAME:
MK_HTML_HELP
PURPOSE:
Given a list of IDL procedure files (.PRO), VMS text library
files (.TLB), or directories that contain such files, this procedure
generates a file in the HTML format that contains the documentation
for those routines that contain a DOC_LIBRARY style documentation
template. The output file is compatible with World Wide Web browsers.
CATEGORY:
Help, documentation.
CALLING SEQUENCE:
MK_HTML_HELP, Sources, Outfile
INPUTS:
Sources: A string or string array containing the name(s) of the
.pro or .tlb files (or the names of directories containing
such files) for which help is desired. If a source file is
a VMS text library, it must include the .TLB file extension.
If a source file is an IDL procedure, it must include the .PRO
file extension. All other source files are assumed to be
directories.
Outfile: The name of the output file which will be generated.
KEYWORDS:
BY_CATEGORY: if set, will group output by their first Category
INCLUDE: set to 'CATEGORY' or 'PURPOSE' to include at top of the file
TITLE: If present, a string which supplies the name that
should appear as the Document Title for the help.
VERBOSE: Normally, MK_HTML_HELP does its work silently.
Setting this keyword to a non-zero value causes the procedure
to issue informational messages that indicate what it
is currently doing. !QUIET must be 0 for these messages
to appear.
STRICT: If this keyword is set to a non-zero value, MK_HTML_HELP will
adhere strictly to the HTML format by scanning the
the document headers for characters that are reserved in
HTML (<,>,&,"). These are then converted to the appropriate
HTML syntax in the output file. By default, this keyword
is set to zero (to allow for faster processing).
EXTENSION: if want to do the for files other than .pro files
STARTHEAD: characters at the beginning of a line which indicate the
header start (default = ';+')
STOPHEAD: characters at the beginning of a line which indicate the
header end (default = ';-')
caveat: string that will be displayed above the links, like a copyright
notice.
EXAMPLE:
if on Unix:
% cd directory-where-web-pages-will-be
(e.g., /w/nstx.pppl.gov/htdocs/nstx/Software/Programming)
% rm pro_sources.txt
% /bin/ls -1 the-directory-with-IDL-code/*.pro > pro_sources.txt
(e.g., ./src/cvs/idl_cvs)
% idl
IDL> sources = READ_LIST('pro_sources.txt')
IDL> MK_HTML_HELP, sources, 'idl_routines.html', include='purpose',/by_category
IDL> exit
This just gives a relative path, but the web link will find it.
When /BY_CATEGORY is specified, an additional page, e.g.,
idl_routines_alphabet.html, will be produced as well.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A help file with the name given by the Outfile argument is
created.
RESTRICTIONS:
The following rules must be followed in formatting the .pro
files that are to be searched.
(a) The first line of the documentation block contains
only the characters ";+", starting in column 1.
(b) There must be a line which contains the string "NAME:",
which is immediately followed (same or next line) by the
name of the procedure or function being described in
that documentation block. If this NAME field is not
present, the name of the source file will be used.
(c) Likewise, for organizing by category, after the purpose,
The "CATEGORY:" line should follow. If fitting, use one of
existing categories as the first category (the only one
sorted on). If less than two routines are in a category,
they are listed in the Misc category.
(d) The last line of the documentation block contains
the characters ";-", starting in column 1.
(e) Every other line in the documentation block contains
a ";" in column 1.
Note that a single .pro file can contain multiple procedures and/or
functions, each with their own documentation blocks. If it is desired
to have "invisible" routines in a file, i.e. routines which are only
for internal use and should not appear in the help file, simply leave
out the ";+" and ";-" lines in the documentation block for those
routines.
MODIFICATION HISTORY:
26-Sep-2013 option to not put link to actual code
04-May-01 Add /BY_CATEGORY switch [BD]
31-Oct-00 Add link to actual code [BD]
07-Jun-99 Added Extension keyword [BD]
01-Apr-99 Allow CATEGORY or PURPOSE to be included in the top of
of the HTML file [Bill Davis]
July 17, 1995, DD, RSI. Added code to alphabetize the subjects;
At the end of each description block in the HTML file,
added a reference to the source .pro file.
July 13, 1995, Mark Rivers, University of Chicago. Added support for
multiple source directories and multiple documentation
headers per .pro file.
July 5, 1995, DD, RSI. Original version.
NAME:
mk_shotlist
PURPOSE:
Parse an input string for shots into an array of shots
CATEGORY:
Input, MDSplus
CALLING SEQUENCE:
IDL> shotlist = mk_shotlist(input)
INPUTS:
input =e.g., 107694 108305 108330-108350
(108100+20 will search 108100-108120)
if a shot number is given as 0, use latest MDSplus shot
KEYWORD PARAMETERS:
dupsOK - if=0, will remove duplicate shot numbers
OUTPUTS:
opt = returned value out
COMMON BLOCKS:
NONE
EXAMPLES:
IDL> print,mk_shotlist('112300+3')
112300 112301 112302 112303
IDL> print,mk_shotlist('112300-4')
112300 112299 112298 112297 112296
IDL> print,mk_shotlist('0+3')
113862 113863 113864 113865
IDL> print,mk_shotlist('0-3')
113862 113861 113860 113859
IDL> print,mk_shotlist('112300-112302 112305+2')
112300 112301 112302 112305 112306 112307
IDL> print,mk_shotlist('107694 108305 108330-108332')
107694 108305 108330 108331 108332
IDL> print,mk_shotlist('4(138846) 4(138847)')
IDL> print,mk_shotlist('138846-2 4(138847)')
NOTES:
When there are duplicate shots, the list is ordered, and the duplicates
removed.
MODIFICATION HISTORY:
22-Jul-2013 allow inputs with multipliers, like 4(138846)
*** made the default dupsOK=1
23-Nov-2009 fixed bug with test for negative shot number
08-Aug-07 added dupsOK keyword
21-Aug-06 Allow for blanks around "-" and "+"
14-Jul-04 Written by Bill Davis, PPPL
NAME:
mk_wtinputfile
PURPOSE:
Create an input file for Web Plotting Tools, like
http://nstx.pppl.gov/nstx/Software/WebTools/mdsplotfileinput.php
from an MDSplus Scope or jScope input file.
CATEGORY:
WebTools, MDSplus, SCOPE
CALLING SEQUENCE:
mk_wtinputfile, scopeFile, wtFile, status=status
INPUTS:
scopeFile - name of a scope file
wtFile - name of web tool input file (defaults to *.txt)
KEYWORDS:
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
jScope - if set, the input file is assumed to be a jScope input file
RETURNED:
status - if odd #, then was successful.
OUTPUT:
file wtFile is created.
NOTES:
can handle multi-signal expressions, but tree will only be added
to the first signal, so, if all signals must be in the first tree
LIMITATIONS:
Does not work with jScope files (yet)
EXAMPLES:
IDL> scopeFile = '/p/nstxusr/util/scopes/wfplus.scope'
IDL> wtFile = 'wfplus.txt'
IDL> mk_wtinputfile, scopeFile, wtFile
IDL> scopeFile = '/u/bdavis/bdtest.jscp'
IDL> mk_wtinputfile, scopeFile ; will output to bdtest.txt
IDL> mk_wtinputfile, "/u/psichta/scopes/pcs.jscp", "pcs.txt"
MODIFICATION HISTORY:
12-Feb-2014 added jScope keyword, so don't have to rely on .jscp ext
10-Feb-2014 Written by Bill Davis
NAME:
MPCURVEFIT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares fit (replaces CURVEFIT)
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
YFIT = MPCURVEFIT(X, Y, WEIGHTS, P, [SIGMA,] FUNCTION_NAME=FUNC,
ITER=iter, ITMAX=itmax,
CHISQ=chisq, NFREE=nfree, DOF=dof,
NFEV=nfev, COVAR=covar, [/NOCOVAR, ] [/NODERIVATIVE, ]
FUNCTARGS=functargs, PARINFO=parinfo,
FTOL=ftol, XTOL=xtol, GTOL=gtol, TOL=tol,
ITERPROC=iterproc, ITERARGS=iterargs,
NPRINT=nprint, QUIET=quiet,
ERRMSG=errmsg, STATUS=status)
DESCRIPTION:
MPCURVEFIT fits a user-supplied model -- in the form of an IDL
function -- to a set of user-supplied data. MPCURVEFIT calls
MPFIT, the MINPACK-1 least-squares minimizer, to do the main
work.
Given the data and their uncertainties, MPCURVEFIT finds the best
set of model parameters which match the data (in a least-squares
sense) and returns them in the parameter P.
MPCURVEFIT returns the best fit function.
The user must supply the following items:
- An array of independent variable values ("X").
- An array of "measured" *dependent* variable values ("Y").
- An array of weighting values ("WEIGHTS").
- The name of an IDL function which computes Y given X ("FUNC").
- Starting guesses for all of the parameters ("P").
There are very few restrictions placed on X, Y or FUNCT. Simply
put, FUNCT must map the "X" values into "Y" values given the
model parameters. The "X" values may represent any independent
variable (not just Cartesian X), and indeed may be multidimensional
themselves. For example, in the application of image fitting, X
may be a 2xN array of image positions.
MPCURVEFIT carefully avoids passing large arrays where possible to
improve performance.
See below for an example of usage.
USER FUNCTION
The user must define a function which returns the model value. For
applications which use finite-difference derivatives -- the default
-- the user function should be declared in the following way:
; MYFUNCT - example user function
; X - input independent variable (vector same size as data)
; P - input parameter values (N-element array)
; YMOD - upon return, user function values
; DP - upon return, the user function must return
; an ARRAY(M,N) of derivatives in this parameter
;
PRO MYFUNCT, x, p, ymod, dp
ymod = F(x, p) ;; Model function
if n_params() GE 4 then begin
; Create derivative and compute derivative array
dp = make_array(n_elements(x), n_elements(p), value=x[0]*0)
; Compute derivative if requested by caller
for i = 0, n_elements(p)-1 do dp(*,i) = FGRAD(x, p, i)
endif
END
where FGRAD(x, p, i) is a model function which computes the
derivative of the model F(x,p) with respect to parameter P(i) at X.
The returned array YMOD must have the same dimensions and type as
the "measured" Y values. The returned array DP[i,j] is the
derivative of the ith function value with respect to the jth
parameter.
User functions may also indicate a fatal error condition
using the ERROR_CODE common block variable, as described
below under the MPFIT_ERROR common block definition.
If NODERIVATIVE=1, then MPCURVEFIT will never request explicit
derivatives from the user function, and instead will user numerical
estimates (i.e. by calling the user function multiple times).
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - the sidedness of the finite difference when computing
numerical derivatives. This field can take four
values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
Where H is the STEP parameter described above. The
"automatic" one-sided derivative method will chose a
direction for the finite difference which does not
violate any constraints. The other methods do not
perform this check. The two-sided method is in
principle more precise, but requires twice as many
function evaluations. Default: 0.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value in
one iteration.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters. Any expression involving
constants and the parameter array P are permitted.
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo(2).tied = '2 * P(1)'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them.
[ NOTE: the PARNAME can't be used in expressions. ]
.MPPRINT - if set to 1, then the default ITERPROC will print the
parameter value. If set to 0, the parameter value
will not be printed. This tag can be used to
selectively print only a few parameter values out of
many. Default: 1 (all parameters printed)
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
the same letters; otherwise they are free to include their own
fields within the PARINFO structure, and they will be ignored.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo(0).fixed = 1
parinfo(4).limited(0) = 1
parinfo(4).limits(0) = 50.D
parinfo(*).value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
INPUTS:
X - Array of independent variable values.
Y - Array of "measured" dependent variable values. Y should have
the same data type as X. The function FUNCT should map
X->Y.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Y-FUNCT(X,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
P - An array of starting values for each of the parameters of the
model. The number of parameters should be fewer than the
number of measurements. Also, the parameters should have the
same data type as the measurements (double is preferred).
Upon successful completion the new parameter values are
returned in P.
If both START_PARAMS and PARINFO are passed, then the starting
*value* is taken from START_PARAMS, but the *constraints* are
taken from PARINFO.
SIGMA - The formal 1-sigma errors in each parameter, computed from
the covariance matrix. If a parameter is held fixed, or
if it touches a boundary, then the error is reported as
zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then SIGMA will
probably not represent the true parameter uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling SIGMA
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(P) ; deg of freedom
CSIGMA = SIGMA * SQRT(CHISQ / DOF) ; scaled uncertainties
RETURNS:
Returns the array containing the best-fitting function.
KEYWORD PARAMETERS:
CHISQ - the value of the summed, squared, weighted residuals for
the returned parameter values, i.e. the chi-square value.
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this:
IDL> PCOR = COV * 0
IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR(i,j) = COV(i,j)/sqrt(COV(i,i)*COV(j,j))
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERRMSG - a string error or warning message is returned.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTION_NAME - a scalar string containing the name of an IDL
procedure to compute the user model values, as
described above in the "USER MODEL" section.
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by FUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks.
By default, no extra parameters are passed to the
user-supplied function.
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITER - the number of iterations completed.
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. It should be declared
in the following way:
PRO ITERPROC, FUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
FUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to FUNCT. FNORM should be the
chi-squared value. QUIET is set when no textual output
should be printed. See below for documentation of
PARINFO.
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value (see
MPFIT_ERROR common block below). In principle,
ITERPROC should probably not modify the parameter
values, because it may interfere with the algorithm's
stability. In practice it is allowed.
Default: an internal routine is used to print the
parameter values.
ITMAX - The maximum number of iterations to perform. If the
number is exceeded, then the STATUS value is set to 5
and MPFIT returns.
Default: 200 iterations
NFEV - the number of FUNCT function evaluations performed.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NODERIVATIVE - if set, then the user function will not be queried
for analytical derivatives, and instead the
derivatives will be computed by finite differences
(and according to the PARINFO derivative settings;
see above for a description).
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Note that
several Levenberg-Marquardt attempts can be made in a
single iteration.
Default value: 1
PARINFO - Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
QUIET - set this keyword when no textual output should be printed
by MPFIT
STATUS - an integer status code is returned. All values other
than zero can represent success. It can have one of the
following values:
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
TOL - synonym for FTOL. Use FTOL instead.
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
YERROR - upon return, the root-mean-square variance of the
residuals.
EXAMPLE:
; First, generate some synthetic data
npts = 200
x = dindgen(npts) * 0.1 - 10. ; Independent variable
yi = gauss1(x, [2.2D, 1.4, 3000.]) ; "Ideal" Y variable
y = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
sy = sqrt(1000.D + y) ; Poisson errors
; Now fit a Gaussian to see how well we can recover
p0 = [1.D, 1., 1000.] ; Initial guess
yfit = mpcurvefit(x, y, 1/sy^2, p0, $ ; Fit a function
FUNCTION_NAME='GAUSS1P',/autoderivative)
print, p
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then the same function is fitted to the
data to see how close we can get. GAUSS1 and GAUSS1P are
available from the same web page.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. By default the value of ERROR_CODE is
zero, indicating a successful function/procedure call.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Translated from MPFITFUN, 25 Sep 1999, CM
Alphabetized documented keywords, 02 Oct 1999, CM
Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
Check to be sure that X and Y are present, 02 Nov 1999, CM
Documented SIGMA for unweighted fits, 03 Nov 1999, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Propagated improvements from MPFIT, 17 Dec 2000, CM
Corrected behavior of NODERIVATIVE, 13 May 2002, CM
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Make more consistent with comparable IDL routines, 30 Jun 2003, CM
Minor documentation adjustment, 03 Feb 2004, CM
Fix error in documentation, 26 Aug 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
Move STRICTARR compile option inside each function/procedure, 9 Oct 2006
Fix bug in handling of explicit derivatives with errors/weights
(the weights were not being applied), CM, 2012-07-22
Add more documentation on calling interface for user function and
parameter derivatives, CM, 2012-07-22
$Id: mpcurvefit.pro,v 1.2 2014/02/24 22:26:01 bdavis Exp $
NAME:
MPFIT2DFUN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares fit to a 2-D IDL function
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
parms = MPFIT2DFUN(MYFUNCT, X, Y, Z, ERR, start_parms, ...)
DESCRIPTION:
MPFIT2DFUN fits a user-supplied model -- in the form of an IDL
function -- to a set of user-supplied data. MPFIT2DFUN calls
MPFIT, the MINPACK-1 least-squares minimizer, to do the main
work. MPFIT2DFUN is a specialized version for two-dimensional
data.
Given the data and their uncertainties, MPFIT2DFUN finds the best set
of model parameters which match the data (in a least-squares
sense) and returns them in an array.
The user must supply the following items:
- Two arrays of independent variable values ("X", "Y").
- An array of "measured" *dependent* variable values ("Z").
- An array of "measured" 1-sigma uncertainty values ("ERR").
- The name of an IDL function which computes Z given (X,Y) ("MYFUNCT").
- Starting guesses for all of the parameters ("START_PARAMS").
There are very few restrictions placed on X, Y, Z, or MYFUNCT.
Simply put, MYFUNCT must map the (X,Y) values into Z values given
the model parameters. The (X,Y) values are usually the independent
X and Y coordinate positions in the two dimensional plane, but need
not be.
MPFIT2DFUN carefully avoids passing large arrays where possible to
improve performance.
See below for an example of usage.
USER FUNCTION
The user must define a function which returns the model value. For
applications which use finite-difference derivatives -- the default
-- the user function should be declared in the following way:
FUNCTION MYFUNCT, X, Y, P
; The independent variables are X and Y
; Parameter values are passed in "P"
ZMOD = ... computed model values at (X,Y) ...
return, ZMOD
END
The returned array YMOD must have the same dimensions and type as
the "measured" Z values.
User functions may also indicate a fatal error condition
using the ERROR_CODE common block variable, as described
below under the MPFIT_ERROR common block definition.
See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
in MPFIT.PRO if you wish to compute the derivatives for yourself.
AUTODERIVATIVE is accepted and passed directly to MPFIT. The user
function must accept one additional parameter, DP, which contains
the derivative of the user function with respect to each parameter
at each data point, as described in MPFIT.PRO.
CREATING APPROPRIATELY DIMENSIONED INDEPENDENT VARIABLES
The user must supply appropriate independent variables to
MPFIT2DFUN. For image fitting applications, this variable should
be two-dimensional *arrays* describing the X and Y positions of
every *pixel*. [ Thus any two dimensional sampling is permitted,
including irregular sampling. ]
If the sampling is regular, then the x coordinates are the same for
each row, and the y coordinates are the same for each column. Call
the x-row and y-column coordinates XR and YC respectively. You can
then compute X and Y as follows:
X = XR # (YC*0 + 1) eqn. 1
Y = (XR*0 + 1) # YC eqn. 2
For example, if XR and YC have the following values:
XR = [ 1, 2, 3, 4, 5,] ;; X positions of one row of pixels
YC = [ 15,16,17 ] ;; Y positions of one column of
pixels
Then using equations 1 and 2 above will give these values to X and
Y:
X : 1 2 3 4 5 ;; X positions of all pixels
1 2 3 4 5
1 2 3 4 5
Y : 15 15 15 15 15 ;; Y positions of all pixels
16 16 16 16 16
17 17 17 17 17
Using the above technique is suggested, but *not* required. You
can do anything you wish with the X and Y values. This technique
only makes it easier to compute your model function values.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - the sidedness of the finite difference when computing
numerical derivatives. This field can take four
values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
Where H is the STEP parameter described above. The
"automatic" one-sided derivative method will chose a
direction for the finite difference which does not
violate any constraints. The other methods do not
perform this check. The two-sided method is in
principle more precise, but requires twice as many
function evaluations. Default: 0.
.MPMINSTEP - the minimum change to be made in the parameter
value. During the fitting process, the parameter
will be changed by multiples of this value. The
actual step is computed as:
DELTA1 = MPMINSTEP*ROUND(DELTA0/MPMINSTEP)
where DELTA0 and DELTA1 are the estimated parameter
changes before and after this constraint is
applied. Note that this constraint should be used
with care since it may cause non-converging,
oscillating solutions.
A value of 0 indicates no minimum. Default: 0.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters. Any expression involving
constants and the parameter array P are permitted.
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo[2].tied = '2 * P[1]'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them.
[ NOTE: the PARNAME can't be used in expressions. ]
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
the same letters; otherwise they are free to include their own
fields within the PARINFO structure, and they will be ignored.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo[0].fixed = 1
parinfo[4].limited(0) = 1
parinfo[4].limits(0) = 50.D
parinfo[*].value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
COMPATIBILITY
This function is designed to work with IDL 5.0 or greater.
Because TIED parameters rely on the EXECUTE() function, they cannot
be used with the free version of the IDL Virtual Machine.
INPUTS:
MYFUNCT - a string variable containing the name of an IDL
function. This function computes the "model" Z values
given the X,Y values and model parameters, as described above.
X - Array of "X" independent variable values, as described above.
These values are passed directly to the fitting function
unmodified.
Y - Array of "Y" independent variable values, as described
above. X and Y should have the same data type.
Z - Array of "measured" dependent variable values. Z should have
the same data type as X and Y. The function MYFUNCT should
map (X,Y)->Z.
ERR - Array of "measured" 1-sigma uncertainties. ERR should have
the same data type as Z. ERR is ignored if the WEIGHTS
keyword is specified.
START_PARAMS - An array of starting values for each of the
parameters of the model. The number of parameters
should be fewer than the number of measurements.
Also, the parameters should have the same data type
as the measurements (double is preferred).
This parameter is optional if the PARINFO keyword
is used (see MPFIT). The PARINFO keyword provides
a mechanism to fix or constrain individual
parameters. If both START_PARAMS and PARINFO are
passed, then the starting *value* is taken from
START_PARAMS, but the *constraints* are taken from
PARINFO.
RETURNS:
Returns the array of best-fit parameters.
KEYWORD PARAMETERS:
BESTNORM - the value of the summed, squared, weighted residuals
for the returned parameter values, i.e. the chi-square value.
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this example:
PCOR = COV * 0
FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR[i,j] = COV[i,j]/sqrt(COV[i,i]*COV[j,j])
or equivalently, in vector notation,
PCOR = COV / (PERROR # PERROR)
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERRMSG - a string error or warning message is returned.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by MYFUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks.
By default, no extra parameters are passed to the
user-supplied function.
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
MYFUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to MYFUNCT. FNORM should be the
chi-squared value. QUIET is set when no textual output
should be printed. See below for documentation of
PARINFO.
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value (see
MPFIT_ERROR common block below). In principle,
ITERPROC should probably not modify the parameter
values, because it may interfere with the algorithm's
stability. In practice it is allowed.
Default: an internal routine is used to print the
parameter values.
MAXITER - The maximum number of iterations to perform. If the
number is exceeded, then the STATUS value is set to 5
and MPFIT returns.
Default: 200 iterations
NFEV - the number of MYFUNCT function evaluations performed.
NITER - the number of iterations completed.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Note that
several Levenberg-Marquardt attempts can be made in a
single iteration.
Default value: 1
PARINFO - Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
PERROR - The formal 1-sigma errors in each parameter, computed
from the covariance matrix. If a parameter is held
fixed, or if it touches a boundary, then the error is
reported as zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties. *If* you can assume that the true reduced
chi-squared value is unity -- meaning that the fit is
implicitly assumed to be of good quality -- then the
estimated parameter uncertainties can be computed by
scaling PERROR by the measured chi-squared value.
DOF = N_ELEMENTS(Z) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - set this keyword when no textual output should be printed
by MPFIT
STATUS - an integer status code is returned. All values other
than zero can represent success. It can have one of the
following values:
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Z - Poisson weighting (counting statistics)
1D - Unweighted
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
YFIT - the best-fit model function, as returned by MYFUNCT.
EXAMPLE:
p = [2.2D, -0.7D, 1.4D, 3000.D]
x = (dindgen(200)*0.1 - 10.) # (dblarr(200) + 1)
y = (dblarr(200) + 1) # (dindgen(200)*0.1 - 10.)
zi = gauss2(x, y, p)
sz = sqrt(zi>1)
z = zi + randomn(seed, 200, 200) * sz
p0 = [0D, 0D, 1D, 10D]
p = mpfit2dfun('GAUSS2', x, y, z, sz, p0)
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then the same function (but different
starting parameters) is fitted to the data to see how close we can
get.
It is especially worthy to notice that the X and Y values are
created as full images, so that a coordinate is attached to each
pixel independently. This is the format that GAUSS2 accepts, and
the easiest for you to use in your own functions.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. By default the value of ERROR_CODE is
zero, indicating a successful function/procedure call.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Written, transformed from MPFITFUN, 26 Sep 1999, CM
Alphabetized documented keywords, 02 Oct 1999, CM
Added example, 02 Oct 1999, CM
Tried to clarify definitions of X and Y, 29 Oct 1999, CM
Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
Check to be sure that X, Y and Z are present, 02 Nov 1999, CM
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Propagated improvements from MPFIT, 17 Dec 2000, CM
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Add DOF keyword to return degrees of freedom, CM, 23 June 2003
Minor documentation adjustment, 03 Feb 2004, CM
Fix the example to prevent zero errorbars, 28 Mar 2005, CM
Defend against users supplying strangely dimensioned X and Y, 29
Jun 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
Move STRICTARR compile option inside each function/procedure, 9 Oct 2006
Add COMPATIBILITY section, CM, 13 Dec 2007
$Id: mpfit2dfun.pro,v 1.2 2014/02/24 22:26:01 bdavis Exp $
NAME:
MPFIT2DPEAK
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Fit a gaussian, lorentzian or Moffat model to data
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
yfit = MPFIT2DPEAK(Z, A [, X, Y, /TILT ...] )
DESCRIPTION:
MPFIT2DPEAK fits a gaussian, lorentzian or Moffat model using the
non-linear least squares fitter MPFIT. MPFIT2DPEAK is meant to be
a drop-in replacement for IDL's GAUSS2DFIT function (and requires
MPFIT and MPFIT2DFUN).
The choice of the fitting function is determined by the keywords
GAUSSIAN, LORENTZIAN and MOFFAT. By default the gaussian model
function is used. [ The Moffat function is a modified Lorentzian
with variable power law index. ] The two-dimensional peak has
independent semimajor and semiminor axes, with an optional
rotation term activated by setting the TILT keyword. The baseline
is assumed to be a constant.
GAUSSIAN A[0] + A[1]*exp(-0.5*u)
LORENTZIAN A[0] + A[1]/(u + 1)
MOFFAT A[0] + A[1]/(u + 1)^A[7]
u = ( (x-A[4])/A[2] )^2 + ( (y-A[5])/A[3] )^2
where x and y are cartesian coordinates in rotated
coordinate system if TILT keyword is set.
The returned parameter array elements have the following meanings:
A[0] Constant baseline level
A[1] Peak value
A[2] Peak half-width (x) -- gaussian sigma or half-width at half-max
A[3] Peak half-width (y) -- gaussian sigma or half-width at half-max
A[4] Peak centroid (x)
A[5] Peak centroid (y)
A[6] Rotation angle (radians) if TILT keyword set
A[7] Moffat power law index if MOFFAT keyword set
By default the initial starting values for the parameters A are
estimated from the data. However, explicit starting values can be
supplied using the ESTIMATES keyword. Also, error or weighting
values can optionally be provided; otherwise the fit is
unweighted.
RESTRICTIONS:
If no starting parameter ESTIMATES are provided, then MPFIT2DPEAK
attempts to estimate them from the data. This is not a perfect
science; however, the author believes that the technique
implemented here is more robust than the one used in IDL's
GAUSS2DFIT. The author has tested cases of strong peaks, noisy
peaks and broad peaks, all with success.
COMPATIBILITY
This function is designed to work with IDL 5.0 or greater.
Because TIED parameters rely on the EXECUTE() function, they cannot
be used with the free version of the IDL Virtual Machine.
INPUTS:
Z - Two dimensional array of "measured" dependent variable values.
Z should be of the same type and dimension as (X # Y).
X - Optional vector of x positions for a single row of Z.
X[i] should provide the x position of Z[i,*]
Default: X values are integer increments from 0 to NX-1
Y - Optional vector of y positions for a single column of Z.
Y[j] should provide the y position of Z[*,j]
Default: Y values are integer increments from 0 to NY-1
OUTPUTS:
A - Upon return, an array of best fit parameter values. See the
table above for the meanings of each parameter element.
RETURNS:
Returns the best fitting model function as a 2D array.
KEYWORDS:
** NOTE ** Additional keywords such as PARINFO, BESTNORM, and
STATUS are accepted by MPFIT2DPEAK but not documented
here. Please see the documentation for MPFIT for the
description of these advanced options.
CHISQ - the value of the summed squared residuals for the
returned parameter values.
CIRCULAR - if set, then the peak profile is assumed to be
azimuthally symmetric. When set, the parameters A[2)
and A[3) will be identical and the TILT keyword will
have no effect.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERROR - upon input, the measured 1-sigma uncertainties in the "Z"
values. If no ERROR or WEIGHTS are given, then the fit is
unweighted.
ESTIMATES - Array of starting values for each parameter of the
model. If ESTIMATES is not set, then the starting
values are estimated from the data directly, before
fitting. (This also means that PARINFO.VALUES is
ignored.)
Default: not set - parameter values are estimated from data.
GAUSSIAN - if set, fit a gaussian model function. The Default.
LORENTZIAN - if set, fit a lorentzian model function.
MOFFAT - if set, fit a Moffat model function.
MEASURE_ERRORS - synonym for ERRORS, for consistency with built-in
IDL fitting routines.
NEGATIVE - if set, and ESTIMATES is not provided, then MPFIT2DPEAK
will assume that a negative peak is present -- a
valley. Specifying this keyword is not normally
required, since MPFIT2DPEAK can determine this
automatically.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
PERROR - upon return, the 1-sigma uncertainties of the parameter
values A. These values are only meaningful if the ERRORS
or WEIGHTS keywords are specified properly.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(Z) - N_ELEMENTS(A) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - if set then diagnostic fitting messages are suppressed.
Default: QUIET=1 (i.e., no diagnostics)
SIGMA - synonym for PERROR (1-sigma parameter uncertainties), for
compatibility with GAUSSFIT. Do not confuse this with the
Gaussian "sigma" width parameter.
TILT - if set, then the major and minor axes of the peak profile
are allowed to rotate with respect to the image axes.
Parameter A[6] will be set to the clockwise rotation angle
of the A[2] axis in radians.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
The ERROR keyword takes precedence over any WEIGHTS
keyword values. If no ERROR or WEIGHTS are given, then
the fit is unweighted.
EXAMPLE:
; Construct a sample gaussian surface in range [-5,5] centered at [2,-3]
x = findgen(100)*0.1 - 5. & y = x
xx = x # (y*0 + 1)
yy = (x*0 + 1) # y
rr = sqrt((xx-2.)^2 + (yy+3.)^2)
; Gaussian surface with sigma=0.5, peak value of 3, noise with sigma=0.2
z = 3.*exp(-(rr/0.5)^2) + randomn(seed,100,100)*.2
; Fit gaussian parameters A
zfit = mpfit2dpeak(z, a, x, y)
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
New algorithm for estimating starting values, CM, 31 Oct 1999
Documented, 02 Nov 1999
Small documentation fixes, 02 Nov 1999
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Small cosmetic changes, 21 Sep 2000, CM
Corrected bug introduced by cosmetic changes, 11 Oct 2000, CM :-)
Added POSITIVE keyword, 17 Nov 2000, CM
Removed TILT in common, in favor of FUNCTARGS approach, 23 Nov
2000, CM
Added SYMMETRIC keyword, documentation for TILT, and an example,
24 Nov 2000, CM
Changed SYMMETRIC to CIRCULAR, 17 Dec 2000, CM
Really change SYMMETRIC to CIRCULAR!, 13 Sep 2002, CM
Add error messages for SYMMETRIC and CIRCLE, 08 Nov 2002, CM
Make more consistent with comparable IDL routines, 30 Jun 2003, CM
Defend against users supplying strangely dimensioned X and Y, 29
Jun 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
Move STRICTARR compile option inside each function/procedure, 9 Oct 2006
Add COMPATIBILITY section, CM, 13 Dec 2007
Clarify documentation regarding what happens when ESTIMATES is not
set, CM, 14 Dec 2008
$Id: mpfit2dpeak.pro,v 1.2 2014/02/24 22:26:01 bdavis Exp $
NAME:
MPFITELLIPSE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Approximate fit to points forming an ellipse
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
parms = MPFITELLIPSE(X, Y, start_parms, [/TILT, WEIGHTS=wts, ...])
DESCRIPTION:
MPFITELLIPSE fits a closed elliptical or circular curve to a two
dimensional set of data points. The user specifies the X and Y
positions of the points, and an optional set of weights. The
ellipse may also be tilted at an arbitrary angle.
IMPORTANT NOTE: this fitting program performs simple ellipse
fitting. It will not work well for ellipse data with high
eccentricity. More robust answers can usually be obtained with
"orthogonal distance regression." (See FORTRAN package ODRPACK on
netlib.org for more information).
The best fitting ellipse parameters are returned from by
MPFITELLIPSE as a vector, whose values are:
P[0] Ellipse semi axis 1
P[1] Ellipse semi axis 2 ( = P[0] if CIRCLE keyword set)
P[2] Ellipse center - x value
P[3] Ellipse center - y value
P[4] Ellipse rotation angle (radians) if TILT keyword set
If the TILT keyword is set, then the P[0] is meant to be the
semi-major axis, and P[1] is the semi-minor axis, and P[4]
represents the tilt of the semi-major axis with respect to the X
axis. If the TILT keyword is not set, the P[0] and P[1] represent
the ellipse semi-axes in the X and Y directions, respectively.
The returned semi-axis lengths should always be positive.
The user may specify an initial set of trial parameters, but by
default MPFITELLIPSE will estimate the parameters automatically.
Users should be aware that in the presence of large amounts of
noise, namely when the measurement error becomes significant
compared to the ellipse axis length, then the estimated parameters
become unreliable. Generally speaking the computed axes will
overestimate the true axes. For example when (SIGMA_R/R) becomes
0.5, the radius of the ellipse is overestimated by about 40%.
This unreliability is also pronounced if the ellipse has high
eccentricity, as noted above.
Users can weight their data as they see appropriate. However, the
following prescription for the weighting may serve as a good
starting point, and appeared to produce results comparable to the
typical chi-squared value.
WEIGHTS = 0.75/(SIGMA_X^2 + SIGMA_Y^2)
where SIGMA_X and SIGMA_Y are the measurement error vectors in the
X and Y directions respectively. However, this has not been
robustly tested, and it should be pointed out that this weighting
may only be appropriate for a set of points whose measurement
errors are comparable. If a more robust estimation of the
parameter values is needed, the so-called orthogonal distance
regression package should be used (ODRPACK, available in FORTRAN
at www.netlib.org).
INPUTS:
X - measured X positions of the points in the ellipse.
Y - measured Y positions of the points in the ellipse.
START_PARAMS - an array of starting values for the ellipse
parameters, as described above. This parameter is
optional; if not specified by the user, then the
ellipse parameters are estimated automatically from
the properties of the data.
RETURNS:
Returns the best fitting model ellipse parameters. Returned
values are undefined if STATUS indicates an error condition.
KEYWORDS:
** NOTE ** Additional keywords such as PARINFO, BESTNORM, and
STATUS are accepted by MPFITELLIPSE but not documented
here. Please see the documentation for MPFIT for the
description of these advanced options.
CIRCULAR - if set, then the curve is assumed to be a circle
instead of ellipse. When set, the parameters P[0] and
P[1] will be identical and the TILT keyword will have
no effect.
PERROR - upon return, the 1-sigma uncertainties of the returned
ellipse parameter values. These values are only
meaningful if the WEIGHTS keyword is specified properly.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
If STATUS indicates an error condition, then PERROR is
undefined.
QUIET - if set then diagnostic fitting messages are suppressed.
Default: QUIET=1 (i.e., no diagnostics]
STATUS - an integer status code is returned. All values greater
than zero can represent success (however STATUS EQ 5 may
indicate failure to converge). Please see MPFIT for
the definitions of status codes.
TILT - if set, then the major and minor axes of the ellipse
are allowed to rotate with respect to the data axes.
Parameter P[4] will be set to the clockwise rotation angle
of the P[0] axis in radians, as measured from the +X axis.
P[4] should be in the range 0 to !dpi.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Z-MYFUNCT(X,Y,P))^2 * ABS(WEIGHTS)^2 )
Users may wish to follow the guidelines for WEIGHTS
described above.
EXAMPLE:
; Construct a set of points on an ellipse, with some noise
ph0 = 2*!pi*randomu(seed,50)
x = 50. + 32.*cos(ph0) + 4.0*randomn(seed, 50)
y = -75. + 65.*sin(ph0) + 0.1*randomn(seed, 50)
; Compute weights function
weights = 0.75/(4.0^2 + 0.1^2)
; Fit ellipse and plot result
p = mpfitellipse(x, y)
phi = dindgen(101)*2D*!dpi/100
plot, x, y, psym=1
oplot, p[2]+p[0]*cos(phi), p[3]+p[1]*sin(phi), color='ff'xl
; Fit ellipse and plot result - WITH TILT
p = mpfitellipse(x, y, /tilt)
phi = dindgen(101)*2D*!dpi/100
; New parameter P[4] gives tilt of ellipse w.r.t. coordinate axes
; We must rotate a standard ellipse to this new orientation
xm = p[2] + p[0]*cos(phi)*cos(p[4]) + p[1]*sin(phi)*sin(p[4])
ym = p[3] - p[0]*cos(phi)*sin(p[4]) + p[1]*sin(phi)*cos(p[4])
plot, x, y, psym=1
oplot, xm, ym, color='ff'xl
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Ported from MPFIT2DPEAK, 17 Dec 2000, CM
More documentation, 11 Jan 2001, CM
Example corrected, 18 Nov 2001, CM
Change CIRCLE keyword to the correct CIRCULAR keyword, 13 Sep
2002, CM
Add error messages for SYMMETRIC and CIRCLE, 08 Nov 2002, CM
Found small error in computation of _EVAL (when CIRCULAR) was set;
sanity check when CIRCULAR is set, 21 Jan 2003, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
Move STRICTARR compile option inside each function/procedure, 9
Oct 2006
Add disclaimer about the suitability of this program for fitting
ellipses, 17 Sep 2007, CM
Clarify documentation of TILT angle; make sure output contains
semi-major axis first, followed by semi-minor; make sure that
semi-axes are always positive (and can handle negative inputs)
17 Sep 2007, CM
Output tilt angle is now in range 0 to !DPI, 20 Sep 2007, CM
Some documentation clarifications, including to remove reference
to the "ERR" keyword, which does not exist, 17 Jan 2008, CM
Swapping of P[0] and P[1] only occurs if /TILT is set, 06 Nov
2009, CM
Document an example of how to plot a tilted ellipse, 09 Nov 2009, CM
Check for MPFIT error conditions and return immediately, 23 Jan 2010, CM
$Id: mpfitellipse.pro,v 1.2 2014/02/24 22:26:01 bdavis Exp $
NAME:
MPFITEXPR
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares fit to arbitrary expression
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
MYFUNCT = 'X*(1-X)+3'
parms = MPFITEXPR(MYFUNCT, XVAL, YVAL, ERR, start_parms, ...)
DESCRIPTION:
MPFITEXPR fits a user-supplied model -- in the form of an arbitrary IDL
expression -- to a set of user-supplied data. MPFITEXPR calls
MPFIT, the MINPACK-1 least-squares minimizer, to do the main
work.
Given the data and their uncertainties, MPFITEXPR finds the best set
of model parameters which match the data (in a least-squares
sense) and returns them in an array.
The user must supply the following items:
- An array of independent variable values ("X").
- An array of "measured" *dependent* variable values ("Y").
- An array of "measured" 1-sigma uncertainty values ("ERR").
- A text IDL expression which computes Y given X.
- Starting guesses for all of the parameters ("START_PARAMS").
There are very few restrictions placed on X, Y or the expression of
the model. Simply put, the expression must map the "X" values into
"Y" values given the model parameters. The "X" values may
represent any independent variable (not just Cartesian X), and
indeed may be multidimensional themselves. For example, in the
application of image fitting, X may be a 2xN array of image
positions.
Some rules must be obeyed in constructing the expression. First,
the independent variable name *MUST* be "X" in the expression,
regardless of the name of the variable being passed to MPFITEXPR.
This is demonstrated in the above calling sequence, where the X
variable passed in is called "XVAL" but the expression still refers
to "X". Second, parameter values must be referred to as an array
named "P".
If you do not pass in starting values for the model parameters,
MPFITEXPR will attempt to determine the number of parameters you
intend to have (it does this by looking for references to the array
variable named "P"). When no starting values are passed in, the
values are assumed to start at zero.
MPFITEXPR carefully avoids passing large arrays where possible to
improve performance.
See below for an example of usage.
EVALUATING EXPRESSIONS
This source module also provides a function called MPEVALEXPR. You
can use this function to evaluate your expression, given a list of
parameters. This is one of the easier ways to compute the model
once the best-fit parameters have been found. Here is an example:
YMOD = MPEVALEXPR(MYFUNCT, XVAL, PARMS)
where MYFUNCT is the expression (see MYFUNCT below), XVAL is the
list of "X" values, and PARMS is an array of parameters. The
returned array YMOD contains the expression MYFUNCT evaluated at
each point in XVAL.
PASSING PRIVATE DATA TO AN EXPRESSION
The most complicated optimization problems typically involve other
external parameters, in addition to the fitted parameters. While
it is extremely easy to rewrite an expression dynamically, in case
one of the external parameters changes, the other possibility is to
use the PRIVATE data structure.
The user merely passes a structure to the FUNCTARGS keyword. The
user expression receives this value as the variable PRIVATE.
MPFITEXPR nevers accesses this variable so it can contain any
desired values. Usually it would be an IDL structure so that any
named external parameters can be passed to the expression.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - the sidedness of the finite difference when computing
numerical derivatives. This field can take four
values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
Where H is the STEP parameter described above. The
"automatic" one-sided derivative method will chose a
direction for the finite difference which does not
violate any constraints. The other methods do not
perform this check. The two-sided method is in
principle more precise, but requires twice as many
function evaluations. Default: 0.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value in
one iteration.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters as an equality constraint. Any
expression involving constants and the parameter array P
are permitted.
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo[2].tied = '2 * P[1]'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them.
[ NOTE: the PARNAME can't be used in a TIED expression. ]
.MPPRINT - if set to 1, then the default ITERPROC will print the
parameter value. If set to 0, the parameter value
will not be printed. This tag can be used to
selectively print only a few parameter values out of
many. Default: 1 (all parameters printed)
.MPFORMAT - IDL format string to print the parameter within
ITERPROC. Default: '(G20.6)' (An empty string will
also use the default.)
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
"MP", but otherwise they are free to include their own fields
within the PARINFO structure, which will be ignored by MPFIT.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo[0].fixed = 1
parinfo[4].limited[0] = 1
parinfo[4].limits[0] = 50.D
parinfo[*].value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
COMPATIBILITY
This function is designed to work with IDL 5.0 or greater. Because
this function uses the IDL EXECUTE() function, it will not work
with the free version of the IDL Virtual machine.
INPUTS:
MYFUNCT - a string variable containing an IDL expression. The
only restriction is that the independent variable *must*
be referred to as "X" and model parameters *must* be
referred to as an array called "P". Do not use symbol
names beginning with the underscore, "_".
The expression should calculate "model" Y values given
the X values and model parameters. Using the vector
notation of IDL, this can be quite easy to do. If your
expression gets complicated, you may wish to make an IDL
function which will improve performance and readibility.
The resulting array should be of the same size and
dimensions as the "measured" Y values.
X - Array of independent variable values.
Y - Array of "measured" dependent variable values. Y should have
the same data type as X. The function MYFUNCT should map
X->Y.
ERR - Array of "measured" 1-sigma uncertainties. ERR should have
the same data type as Y. ERR is ignored if the WEIGHTS
keyword is specified.
START_PARAMS - An array of starting values for each of the
parameters of the model. The number of parameters
should be fewer than the number of measurements.
Also, the parameters should have the same data type
as the measurements (double is preferred).
This parameter is optional if the PARINFO keyword
is used (see MPFIT). The PARINFO keyword provides
a mechanism to fix or constrain individual
parameters. If both START_PARAMS and PARINFO are
passed, then the starting *value* is taken from
START_PARAMS, but the *constraints* are taken from
PARINFO.
If no parameters are given, then MPFITEXPR attempts
to determine the number of parameters by scanning
the expression. Parameters determined this way are
initialized to zero. This technique is not fully
reliable, so users are advised to pass explicit
parameter starting values.
RETURNS:
Returns the array of best-fit parameters.
KEYWORD PARAMETERS:
BESTNORM - the value of the summed, squared, weighted residuals
for the returned parameter values, i.e. the chi-square value.
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this:
IDL> PCOR = COV * 0
IDL> FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR[i,j] = COV[i,j]/sqrt(COV[i,i]*COV[j,j])
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERRMSG - a string error or warning message is returned.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTARGS - passed directly to the expression as the variable
PRIVATE. Any user-private data can be communicated to
the user expression using this keyword.
Default: PRIVATE is undefined in user expression
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
MYFUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to MYFUNCT. FNORM should be the
chi-squared value. QUIET is set when no textual output
should be printed. See below for documentation of
PARINFO.
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value (see
MPFIT_ERROR common block below). In principle,
ITERPROC should probably not modify the parameter
values, because it may interfere with the algorithm's
stability. In practice it is allowed.
Default: an internal routine is used to print the
parameter values.
MAXITER - The maximum number of iterations to perform. If the
number is exceeded, then the STATUS value is set to 5
and MPFIT returns.
Default: 200 iterations
NFEV - the number of MYFUNCT function evaluations performed.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NITER - the number of iterations completed.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NPEGGED - the number of free parameters which are pegged at a
LIMIT.
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Note that
several Levenberg-Marquardt attempts can be made in a
single iteration.
Default value: 1
PARINFO - Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
PERROR - The formal 1-sigma errors in each parameter, computed
from the covariance matrix. If a parameter is held
fixed, or if it touches a boundary, then the error is
reported as zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - set this keyword when no textual output should be printed
by MPFIT
STATUS - an integer status code is returned. All values other
than zero can represent success. It can have one of the
following values:
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
YFIT - the best-fit model function, as returned by MYFUNCT.
EXAMPLE:
; First, generate some synthetic data
x = dindgen(200) * 0.1 - 10. ; Independent variable
yi = gauss1(x, [2.2D, 1.4, 3000.]) + 1000 ; "Ideal" Y variable
y = yi + randomn(seed, 200) * sqrt(yi) ; Measured, w/ noise
sy = sqrt(y) ; Poisson errors
; Now fit a Gaussian to see how well we can recover
expr = 'P[0] + GAUSS1(X, P[1:3])' ; fitting function
p0 = [800.D, 1.D, 1., 500.] ; Initial guess
p = mpfitexpr(expr, x, y, sy, p0) ; Fit the expression
print, p
plot, x, y ; Plot data
oplot, x, mpevalexpr(expr, x, p) ; Plot model
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then a model consisting of a constant
plus Gaussian is fit to the data.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. By default the value of ERROR_CODE is
zero, indicating a successful function/procedure call.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Written, Apr-Jul 1998, CM
Added PERROR keyword, 04 Aug 1998, CM
Added COVAR keyword, 20 Aug 1998, CM
Added NITER output keyword, 05 Oct 1998
D.L Windt, Bell Labs, windt@bell-labs.com;
Added ability to return model function in YFIT, 09 Nov 1998
Parameter values can be tied to others, 09 Nov 1998
Added MPEVALEXPR utility function, 09 Dec 1998
Cosmetic documentation updates, 16 Apr 1999, CM
More cosmetic documentation updates, 14 May 1999, CM
Made sure to update STATUS value, 25 Sep 1999, CM
Added WEIGHTS keyword, 25 Sep 1999, CM
Changed from handles to common blocks, 25 Sep 1999, CM
- commons seem much cleaner and more logical in this case.
Alphabetized documented keywords, 02 Oct 1999, CM
Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
Check to be sure that X and Y are present, 02 Nov 1999, CM
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Removed ITERPROC='' when quiet EQ 1, 10 Jan 2000, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Updated the EXAMPLE, 26 Mar 2000, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Propagated improvements from MPFIT, 17 Dec 2000, CM
Correct reference to _WTS in MPFITEXPR_EVAL, 25 May 2001, CM
(thanks to Mark Fardal)
Added useful FUNCTARGS behavior (as yet undocumented), 04 Jul
2002, CM
Documented FUNCTARGS/PRIVATE behavior, 22 Jul 2002, CM
Added NFREE and NPEGGED keywords, 13 Sep 2002, CM
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Add DOF keyword, CM, 31 Jul 2003
Add FUNCTARGS keyword to MPEVALEXPR, CM 08 Aug 2003
Minor documentation adjustment, 03 Feb 2004, CM
Move STRICTARR compile option inside each function/procedure, 9 Oct 2006
Clarify documentation on user-function, derivatives, and PARINFO,
27 May 2007
Add COMPATIBILITY section, CM, 13 Dec 2007
$Id: mpfitexpr.pro,v 1.2 2014/02/24 22:26:01 bdavis Exp $
NAME:
MPFITFUN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares fit to IDL function
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
parms = MPFITFUN(MYFUNCT, X, Y, ERR, start_params, ...)
DESCRIPTION:
MPFITFUN fits a user-supplied model -- in the form of an IDL
function -- to a set of user-supplied data. MPFITFUN calls
MPFIT, the MINPACK-1 least-squares minimizer, to do the main
work.
Given the data and their uncertainties, MPFITFUN finds the best set
of model parameters which match the data (in a least-squares
sense) and returns them in an array.
The user must supply the following items:
- An array of independent variable values ("X").
- An array of "measured" *dependent* variable values ("Y").
- An array of "measured" 1-sigma uncertainty values ("ERR").
- The name of an IDL function which computes Y given X ("MYFUNCT").
- Starting guesses for all of the parameters ("START_PARAMS").
There are very few restrictions placed on X, Y or MYFUNCT. Simply
put, MYFUNCT must map the "X" values into "Y" values given the
model parameters. The "X" values may represent any independent
variable (not just Cartesian X), and indeed may be multidimensional
themselves. For example, in the application of image fitting, X
may be a 2xN array of image positions.
Data values of NaN or Infinity for "Y", "ERR" or "WEIGHTS" will be
ignored as missing data if the NAN keyword is set. Otherwise, they
may cause the fitting loop to halt with an error message. Note
that the fit will still halt if the model function, or its
derivatives, produces infinite or NaN values.
MPFITFUN carefully avoids passing large arrays where possible to
improve performance.
See below for an example of usage.
USER FUNCTION
The user must define a function which returns the model value. For
applications which use finite-difference derivatives -- the default
-- the user function should be declared in the following way:
FUNCTION MYFUNCT, X, P
; The independent variable is X
; Parameter values are passed in "P"
YMOD = ... computed model values at X ...
return, YMOD
END
The returned array YMOD must have the same dimensions and type as
the "measured" Y values.
User functions may also indicate a fatal error condition
using the ERROR_CODE common block variable, as described
below under the MPFIT_ERROR common block definition.
MPFIT by default calculates derivatives numerically via a finite
difference approximation. However, the user function *may*
calculate the derivatives if desired, but only if the model
function is declared with an additional position parameter, DP, as
described below.
To enable explicit derivatives for all parameters, set
AUTODERIVATIVE=0.
When AUTODERIVATIVE=0, the user function is responsible for
calculating the derivatives of the user function with respect to
each parameter. The user function should be declared as follows:
;
; MYFUNCT - example user function
; P - input parameter values (N-element array)
; DP - upon input, an N-vector indicating which parameters
; to compute derivatives for;
; upon output, the user function must return
; an ARRAY(M,N) of derivatives in this keyword
; (keywords) - any other keywords specified by FUNCTARGS
; RETURNS - function values
;
FUNCTION MYFUNCT, x, p, dp [, (additional keywords if desired)]
model = F(x, p) ;; Model function
if n_params() GT 2 then begin
; Create derivative and compute derivative array
requested = dp ; Save original value of DP
dp = make_array(n_elements(x), n_elements(p), value=x[0]*0)
; Compute derivative if requested by caller
for i = 0, n_elements(p)-1 do if requested(i) NE 0 then $
dp(*,i) = FGRAD(x, p, i)
endif
return, resid
END
where FGRAD(x, p, i) is a model function which computes the
derivative of the model F(x,p) with respect to parameter P(i) at X.
Derivatives should be returned in the DP array. DP should be an
ARRAY(m,n) array, where m is the number of data points and n is the
number of parameters. DP[i,j] is the derivative of the ith
function value with respect to the jth parameter.
MPFIT may not always request derivatives from the user function.
In those cases, the parameter DP is not passed. Therefore
functions can use N_PARAMS() to indicate whether they must compute
the derivatives or not.
For additional information about explicit derivatives, including
additional settings and debugging options, see the discussion under
"EXPLICIT DERIVATIVES" and AUTODERIVATIVE in MPFIT.PRO.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - the sidedness of the finite difference when computing
numerical derivatives. This field can take four
values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
Where H is the STEP parameter described above. The
"automatic" one-sided derivative method will chose a
direction for the finite difference which does not
violate any constraints. The other methods do not
perform this check. The two-sided method is in
principle more precise, but requires twice as many
function evaluations. Default: 0.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value in
one iteration.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters as an equality constraint. Any
expression involving constants and the parameter array P
are permitted.
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo[2].tied = '2 * P[1]'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them.
[ NOTE: the PARNAME can't be used in a TIED expression. ]
.MPPRINT - if set to 1, then the default ITERPROC will print the
parameter value. If set to 0, the parameter value
will not be printed. This tag can be used to
selectively print only a few parameter values out of
many. Default: 1 (all parameters printed)
.MPFORMAT - IDL format string to print the parameter within
ITERPROC. Default: '(G20.6)' (An empty string will
also use the default.)
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
"MP", but otherwise they are free to include their own fields
within the PARINFO structure, which will be ignored by MPFIT.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo[0].fixed = 1
parinfo[4].limited[0] = 1
parinfo[4].limits[0] = 50.D
parinfo[*].value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
COMPATIBILITY
This function is designed to work with IDL 5.0 or greater.
Because TIED parameters rely on the EXECUTE() function, they cannot
be used with the free version of the IDL Virtual Machine.
INPUTS:
MYFUNCT - a string variable containing the name of an IDL function.
This function computes the "model" Y values given the
X values and model parameters, as desribed above.
X - Array of independent variable values.
Y - Array of "measured" dependent variable values. Y should have
the same data type as X. The function MYFUNCT should map
X->Y.
NOTE: the following special cases apply:
* if Y is NaN or Infinite, and the NAN keyword is
set, then the corresponding data point is ignored
ERR - Array of "measured" 1-sigma uncertainties. ERR should have
the same data type as Y. ERR is ignored if the WEIGHTS
keyword is specified.
NOTE: the following special cases apply:
* if ERR is zero, then the corresponding data point
is ignored
* if ERR is NaN or Infinite, and the NAN keyword is
set, then the corresponding data point is ignored
* if ERR is negative, then the absolute value of
ERR is used.
START_PARAMS - An array of starting values for each of the
parameters of the model. The number of parameters
should be fewer than the number of measurements.
Also, the parameters should have the same data type
as the measurements (double is preferred).
This parameter is optional if the PARINFO keyword
is used (see MPFIT). The PARINFO keyword provides
a mechanism to fix or constrain individual
parameters. If both START_PARAMS and PARINFO are
passed, then the starting *value* is taken from
START_PARAMS, but the *constraints* are taken from
PARINFO.
RETURNS:
Returns the array of best-fit parameters.
KEYWORD PARAMETERS:
BESTNORM - the value of the summed squared residuals for the
returned parameter values.
BEST_FJAC - upon return, BEST_FJAC contains the Jacobian, or
partial derivative, matrix for the best-fit model.
The values are an array,
ARRAY(N_ELEMENTS(DEVIATES),NFREE) where NFREE is the
number of free parameters. This array is only
computed if /CALC_FJAC is set, otherwise BEST_FJAC is
undefined.
The returned array is such that BEST_FJAC[I,J] is the
partial derivative of the model with respect to
parameter PARMS[PFREE_INDEX[J]].
BEST_RESID - upon return, an array of best-fit deviates,
normalized by the weights or errors.
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this example:
PCOR = COV * 0
FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR[i,j] = COV[i,j]/sqrt(COV[i,i]*COV[j,j])
or equivalently, in vector notation,
PCOR = COV / (PERROR # PERROR)
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
CASH - when set, the fit statistic is changed to a derivative of
the CASH statistic. The model function must be strictly
positive. WARNING: this option is incomplete and untested.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED). It also does not account for data points which
are assigned zero weight, for example if :
* WEIGHTS[i] EQ 0, or
* ERR[i] EQ infinity, or
* any of the values is "undefined" and /NAN is set.
ERRMSG - a string error or warning message is returned.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by MYFUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks.
By default, no extra parameters are passed to the
user-supplied function.
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
MYFUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to MYFUNCT. FNORM should be the
chi-squared value. QUIET is set when no textual output
should be printed. See below for documentation of
PARINFO.
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value (see
MPFIT_ERROR common block below). In principle,
ITERPROC should probably not modify the parameter
values, because it may interfere with the algorithm's
stability. In practice it is allowed.
Default: an internal routine is used to print the
parameter values.
MAXITER - The maximum number of iterations to perform. If the
number of calculation iterations exceeds MAXITER, then
the STATUS value is set to 5 and MPFIT returns.
If MAXITER EQ 0, then MPFIT does not iterate to adjust
parameter values; however, the user function is evaluated
and parameter errors/covariance/Jacobian are estimated
before returning.
Default: 200 iterations
NAN - ignore infinite or NaN values in the Y, ERR or WEIGHTS
parameters. These values will be treated as missing data.
However, the fit will still halt with an error condition
if the model function becomes infinite.
NFEV - the number of MYFUNCT function evaluations performed.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NITER - the number of iterations completed.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NPEGGED - the number of free parameters which are pegged at a
LIMIT.
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Be aware
that several Levenberg-Marquardt attempts can be made in
a single iteration. Also, the ITERPROC is *always*
called for the final iteration, regardless of the
iteration number.
Default value: 1
PARINFO - A one-dimensional array of structures.
Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
PERROR - The formal 1-sigma errors in each parameter, computed
from the covariance matrix. If a parameter is held
fixed, or if it touches a boundary, then the error is
reported as zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
PFREE_INDEX - upon return, PFREE_INDEX contains an index array
which indicates which parameter were allowed to
vary. I.e. of all the parameters PARMS, only
PARMS[PFREE_INDEX] were varied.
QUERY - if set, then MPFIT() will return immediately with one of
the following values:
1 - if MIN_VERSION is not set
1 - if MIN_VERSION is set and MPFIT satisfies the minimum
0 - if MIN_VERSION is set and MPFIT does not satisfy it
Default: not set.
QUIET - set this keyword when no textual output should be printed
by MPFIT
STATUS - an integer status code is returned. All values greater
than zero can represent success (however STATUS EQ 5 may
indicate failure to converge). It can have one of the
following values:
-18 a fatal execution error has occurred. More information
may be available in the ERRMSG string.
-16 a parameter or function value has become infinite or an
undefined number. This is usually a consequence of
numerical overflow in the user's model function, which
must be avoided.
-15 to -1
these are error codes that either MYFUNCT or ITERPROC
may return to terminate the fitting process (see
description of MPFIT_ERROR common below). If either
MYFUNCT or ITERPROC set ERROR_CODE to a negative number,
then that number is returned in STATUS. Values from -15
to -1 are reserved for the user functions and will not
clash with MPFIT.
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERR
parameter is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS for standard weightings:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
NOTE: the following special cases apply:
* if WEIGHTS is zero, then the corresponding data point
is ignored
* if WEIGHTS is NaN or Infinite, and the NAN keyword is
set, then the corresponding data point is ignored
* if WEIGHTS is negative, then the absolute value of
WEIGHTS is used.
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
YFIT - the best-fit model function, as returned by MYFUNCT.
EXAMPLE:
; First, generate some synthetic data
npts = 200
x = dindgen(npts) * 0.1 - 10. ; Independent variable
yi = gauss1(x, [2.2D, 1.4, 3000.]) ; "Ideal" Y variable
y = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
sy = sqrt(1000.D + y) ; Poisson errors
; Now fit a Gaussian to see how well we can recover
p0 = [1.D, 1., 1000.] ; Initial guess (cent, width, area)
p = mpfitfun('GAUSS1', x, y, sy, p0) ; Fit a function
print, p
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then the same function is fitted to the
data (with different starting parameters) to see how close we can
get.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. By default the value of ERROR_CODE is
zero, indicating a successful function/procedure call.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
Written, Apr-Jul 1998, CM
Added PERROR keyword, 04 Aug 1998, CM
Added COVAR keyword, 20 Aug 1998, CM
Added ITER output keyword, 05 Oct 1998
D.L Windt, Bell Labs, windt@bell-labs.com;
Added ability to return model function in YFIT, 09 Nov 1998
Analytical derivatives allowed via AUTODERIVATIVE keyword, 09 Nov 1998
Parameter values can be tied to others, 09 Nov 1998
Cosmetic documentation updates, 16 Apr 1999, CM
More cosmetic documentation updates, 14 May 1999, CM
Made sure to update STATUS, 25 Sep 1999, CM
Added WEIGHTS keyword, 25 Sep 1999, CM
Changed from handles to common blocks, 25 Sep 1999, CM
- commons seem much cleaner and more logical in this case.
Alphabetized documented keywords, 02 Oct 1999, CM
Added QUERY keyword and query checking of MPFIT, 29 Oct 1999, CM
Corrected EXAMPLE (offset of 1000), 30 Oct 1999, CM
Check to be sure that X and Y are present, 02 Nov 1999, CM
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Corrected errors in EXAMPLE, 26 Mar 2000, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Propagated improvements from MPFIT, 17 Dec 2000, CM
Added CASH statistic, 10 Jan 2001
Added NFREE and NPEGGED keywords, 11 Sep 2002, CM
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Add DOF keyword to return degrees of freedom, CM, 23 June 2003
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
Move STRICTARR compile option inside each function/procedure, 9
Oct 2006
Add NAN keyword, to ignore non-finite data values, 28 Oct 2006, CM
Clarify documentation on user-function, derivatives, and PARINFO,
27 May 2007
Fix bug in handling of explicit derivatives with errors/weights
(the weights were not being applied), CM, 03 Sep 2007
Add COMPATIBILITY section, CM, 13 Dec 2007
Add documentation about NAN behavior, CM, 30 Mar 2009
Add keywords BEST_RESIDS, CALC_FJAC, BEST_FJAC, PFREE_INDEX;
update some documentation that had become stale, CM, 2010-10-28
Documentation corrections, CM, 2011-08-26
Additional documentation about explicit derivatives, CM, 2012-07-23
$Id: mpfitfun.pro,v 1.2 2014/02/24 22:26:01 bdavis Exp $
NAME:
MPFITPEAK
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Fit a gaussian, lorentzian or Moffat model to data
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
yfit = MPFITPEAK(X, Y, A, NTERMS=nterms, ...)
DESCRIPTION:
MPFITPEAK fits a gaussian, lorentzian or Moffat model using the
non-linear least squares fitter MPFIT. MPFITPEAK is meant to be a
drop-in replacement for IDL's GAUSSFIT function (and requires
MPFIT and MPFITFUN).
The choice of the fitting function is determined by the keywords
GAUSSIAN, LORENTZIAN and MOFFAT. By default the gaussian model
function is used. [ The Moffat function is a modified Lorentzian
with variable power law index. (Moffat, A. F. J. 1969, Astronomy &
Astrophysics, v. 3, p. 455-461) ]
The functional form of the baseline is determined by NTERMS and
the function to be fitted. NTERMS represents the total number of
parameters, A, to be fitted. The functional forms and the
meanings of the parameters are described in this table:
GAUSSIAN# Lorentzian# Moffat#
Model A[0]*exp(-0.5*u^2) A[0]/(u^2 + 1) A[0]/(u^2 + 1)^A[3]
A[0] Peak Value Peak Value Peak Value
A[1] Peak Centroid Peak Centroid Peak Centroid
A[2] Gaussian Sigma HWHM% HWHM%
A[3] + A[3] * + A[3] * Moffat Index
A[4] + A[4]*x * + A[4]*x * + A[4] *
A[5] + A[5]*x *
Notes: # u = (x - A[1])/A[2]
% Half-width at half maximum
* Optional depending on NTERMS
By default the initial starting values for the parameters A are
estimated from the data. However, explicit starting values can be
supplied using the ESTIMATES keyword. Also, error or weighting
values can optionally be provided; otherwise the fit is
unweighted.
MPFITPEAK fits the peak value of the curve. The area under a
gaussian peak is A[0]*A[2]*SQRT(2*!DPI); the area under a
lorentzian peak is A[0]*A[2]*!DPI.
Data values of NaN or Infinity for "Y", "ERROR" or "WEIGHTS" will
be ignored as missing data if the NAN keyword is set. Otherwise,
they may cause the fitting loop to halt with an error message.
Note that the fit will still halt if the model function, or its
derivatives, produces infinite or NaN values, or if an "X" value is
missing.
RESTRICTIONS:
If no starting parameter ESTIMATES are provided, then MPFITPEAK
attempts to estimate them from the data. This is not a perfect
science; however, the author believes that the technique
implemented here is more robust than the one used in IDL's
GAUSSFIT. The author has tested cases of strong peaks, noisy
peaks and broad peaks, all with success.
Users should be aware that if the baseline term contains a strong
linear component then the automatic estimation may fail. For
automatic estimation to work the peak amplitude should dominate
over the the maximum baseline.
COMPATIBILITY
This function is designed to work with IDL 5.0 or greater.
Because TIED parameters rely on the EXECUTE() function, they cannot
be used with the free version of the IDL Virtual Machine.
INPUTS:
X - Array of independent variable values, whose values should
monotonically increase.
Y - Array of "measured" dependent variable values. Y should have
the same data type and dimension as X.
NOTE: the following special cases apply:
* if Y is NaN or Infinite, and the NAN keyword is
set, then the corresponding data point is ignored
OUTPUTS:
A - Upon return, an array of NTERMS best fit parameter values.
See the table above for the meanings of each parameter
element.
RETURNS:
Returns the best fitting model function.
KEYWORDS:
** NOTE ** Additional keywords such as PARINFO, BESTNORM, and
STATUS are accepted by MPFITPEAK but not documented
here. Please see the documentation for MPFIT for the
description of these advanced options.
AUTODERIV - Set to 1 to have MPFIT compute the derivatives numerically.
Default is 0 - derivatives are computed analytically, which is
generally faster. (Prior to Jan 2011, the default was 1)
CHISQ - the value of the summed squared residuals for the
returned parameter values.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED).
ERROR - upon input, the measured 1-sigma uncertainties in the "Y"
values. If no ERROR or WEIGHTS are given, then the fit is
unweighted.
NOTE: the following special cases apply:
* if ERROR is zero, then the corresponding data point
is ignored
* if ERROR is NaN or Infinite, and the NAN keyword is
set, then the corresponding data point is ignored
* if ERROR is negative, then the absolute value of
ERROR is used.
ESTIMATES - Array of starting values for each parameter of the
model. The number of parameters should at least be
three (four for Moffat), and if less than NTERMS, will
be extended with zeroes. If ESTIMATES is not set,
then the starting values are estimated from the data
directly, before fitting. (This also means that
PARINFO.VALUES is ignored.)
Default: not set - parameter values are estimated from data.
GAUSSIAN - if set, fit a gaussian model function. The Default.
LORENTZIAN - if set, fit a lorentzian model function.
MOFFAT - if set, fit a Moffat model function.
MEASURE_ERRORS - synonym for ERRORS, for consistency with built-in
IDL fitting routines.
NAN - ignore infinite or NaN values in the Y, ERR or WEIGHTS
parameters. These values will be treated as missing data.
However, the fit will still halt with an error condition if
the model function becomes infinite, or if X has missing
values.
NEGATIVE / POSITIVE - if set, and ESTIMATES is not provided, then
MPFITPEAK will assume that a
negative/positive peak is present.
Default: determined automatically
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NO_FIT - if set, then return only the initial estimates without
fitting. Useful to find out what the estimates the
automatic guessing algorithm produced. If NO_FIT is set,
then SIGMA and CHISQ values are not produced. The
routine returns, NAN, and STATUS=5.
NTERMS - An integer describing the number of fitting terms.
NTERMS must have a minimum value, but can optionally be
larger depending on the desired baseline.
For gaussian and lorentzian models, NTERMS must be three
(zero baseline), four (constant baseline) or five (linear
baseline). Default: 4
For the Moffat model, NTERMS must be four (zero
baseline), five (constant baseline), or six (linear
baseline). Default: 5
PERROR - upon return, the 1-sigma uncertainties of the parameter
values A. These values are only meaningful if the ERRORS
or WEIGHTS keywords are specified properly.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
QUIET - if set then diagnostic fitting messages are suppressed.
Default: QUIET=1 (i.e., no diagnostics)
SIGMA - synonym for PERROR (1-sigma parameter uncertainties), for
compatibility with GAUSSFIT. Do not confuse this with the
Gaussian "sigma" width parameter.
WEIGHTS - Array of weights to be used in calculating the
chi-squared value. If WEIGHTS is specified then the ERROR
keyword is ignored. The chi-squared value is computed
as follows:
CHISQ = TOTAL( (Y-MYFUNCT(X,P))^2 * ABS(WEIGHTS) )
Here are common values of WEIGHTS:
1D/ERR^2 - Normal weighting (ERR is the measurement error)
1D/Y - Poisson weighting (counting statistics)
1D - Unweighted
The ERROR keyword takes precedence over any WEIGHTS
keyword values. If no ERROR or WEIGHTS are given, then
the fit is unweighted.
NOTE: the following special cases apply:
* if WEIGHTS is zero, then the corresponding data point
is ignored
* if WEIGHTS is NaN or Infinite, and the NAN keyword is
set, then the corresponding data point is ignored
* if WEIGHTS is negative, then the absolute value of
WEIGHTS is used.
YERROR - upon return, the root-mean-square variance of the
residuals.
EXAMPLE:
; First, generate some synthetic data
npts = 200
x = dindgen(npts) * 0.1 - 10. ; Independent variable
yi = gauss1(x, [2.2D, 1.4, 3000.]) + 1000 ; "Ideal" Y variable
y = yi + randomn(seed, npts) * sqrt(1000. + yi); Measured, w/ noise
sy = sqrt(1000.D + y) ; Poisson errors
; Now fit a Gaussian to see how well we can recover the original
yfit = mpfitpeak(x, y, a, error=sy)
print, p
Generates a synthetic data set with a Gaussian peak, and Poisson
statistical uncertainty. Then the same function is fitted to the
data.
REFERENCES:
MINPACK-1, Jorge More', available from netlib (www.netlib.org).
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
MODIFICATION HISTORY:
New algorithm for estimating starting values, CM, 31 Oct 1999
Documented, 02 Nov 1999
Small documentation fixes, 02 Nov 1999
Slight correction to calculation of dx, CM, 02 Nov 1999
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Copying permission terms have been liberalized, 26 Mar 2000, CM
Change requirements on # elements in X and Y, 20 Jul 2000, CM
(thanks to David Schlegel )
Added documentation on area under curve, 29 Aug 2000, CM
Added POSITIVE and NEGATIVE keywords, 17 Nov 2000, CM
Added reference to Moffat paper, 10 Jan 2001, CM
Added usage message, 26 Jul 2001, CM
Documentation clarification, 05 Sep 2001, CM
Make more consistent with comparable IDL routines, 30 Jun 2003, CM
Assumption of sorted data was removed, CM, 06 Sep 2003, CM
Add some defensive code against divide by zero, 30 Nov 2005, CM
Add some defensive code against all Y values equal to each other,
17 Apr 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
Move STRICTARR compile option inside each function/procedure, 9 Oct 2006
Add COMPATIBILITY section, CM, 13 Dec 2007
Missed some old IDL 4 () array syntax, now corrected, 13 Jun 2008
Slightly more error checking for pathalogical case, CM, 11 Nov 2008
Clarify documentation regarding what happens when ESTIMATES is not
set, CM, 14 Dec 2008
Add the NAN keyword, document how NAN, WEIGHTS and ERROR interact,
CM, 30 Mar 2009
Correct one case of old IDL 4 () array syntax (thanks to I. Urra),
CM, 25 Jan 2010
Improve performance by analytic derivative computation, added AUTODERIV
keyword, W. Landsman, 2011-01-21
Move estimation code to its own function; allow the user to compute
only the estimate and return immediately without fitting,
C. Markwardt, 2011-07-12
$Id: mpfitpeak.pro,v 1.2 2014/02/24 22:26:01 bdavis Exp $
NAME:
MPFIT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
UPDATED VERSIONs can be found on my WEB PAGE:
http://cow.physics.wisc.edu/~craigm/idl/idl.html
PURPOSE:
Perform Levenberg-Marquardt least-squares minimization (MINPACK-1)
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
parms = MPFIT(MYFUNCT, start_parms, FUNCTARGS=fcnargs, NFEV=nfev,
MAXITER=maxiter, ERRMSG=errmsg, NPRINT=nprint, QUIET=quiet,
FTOL=ftol, XTOL=xtol, GTOL=gtol, NITER=niter,
STATUS=status, ITERPROC=iterproc, ITERARGS=iterargs,
COVAR=covar, PERROR=perror, BESTNORM=bestnorm,
PARINFO=parinfo)
DESCRIPTION:
MPFIT uses the Levenberg-Marquardt technique to solve the
least-squares problem. In its typical use, MPFIT will be used to
fit a user-supplied function (the "model") to user-supplied data
points (the "data") by adjusting a set of parameters. MPFIT is
based upon MINPACK-1 (LMDIF.F) by More' and collaborators.
For example, a researcher may think that a set of observed data
points is best modelled with a Gaussian curve. A Gaussian curve is
parameterized by its mean, standard deviation and normalization.
MPFIT will, within certain constraints, find the set of parameters
which best fits the data. The fit is "best" in the least-squares
sense; that is, the sum of the weighted squared differences between
the model and data is minimized.
The Levenberg-Marquardt technique is a particular strategy for
iteratively searching for the best fit. This particular
implementation is drawn from MINPACK-1 (see NETLIB), and seems to
be more robust than routines provided with IDL. This version
allows upper and lower bounding constraints to be placed on each
parameter, or the parameter can be held fixed.
The IDL user-supplied function should return an array of weighted
deviations between model and data. In a typical scientific problem
the residuals should be weighted so that each deviate has a
gaussian sigma of 1.0. If X represents values of the independent
variable, Y represents a measurement for each value of X, and ERR
represents the error in the measurements, then the deviates could
be calculated as follows:
DEVIATES = (Y - F(X)) / ERR
where F is the function representing the model. You are
recommended to use the convenience functions MPFITFUN and
MPFITEXPR, which are driver functions that calculate the deviates
for you. If ERR are the 1-sigma uncertainties in Y, then
TOTAL( DEVIATES^2 )
will be the total chi-squared value. MPFIT will minimize the
chi-square value. The values of X, Y and ERR are passed through
MPFIT to the user-supplied function via the FUNCTARGS keyword.
Simple constraints can be placed on parameter values by using the
PARINFO keyword to MPFIT. See below for a description of this
keyword.
MPFIT does not perform more general optimization tasks. See TNMIN
instead. MPFIT is customized, based on MINPACK-1, to the
least-squares minimization problem.
USER FUNCTION
The user must define a function which returns the appropriate
values as specified above. The function should return the weighted
deviations between the model and the data. For applications which
use finite-difference derivatives -- the default -- the user
function should be declared in the following way:
FUNCTION MYFUNCT, p, X=x, Y=y, ERR=err
; Parameter values are passed in "p"
model = F(x, p)
return, (y-model)/err
END
See below for applications with explicit derivatives.
The keyword parameters X, Y, and ERR in the example above are
suggestive but not required. Any parameters can be passed to
MYFUNCT by using the FUNCTARGS keyword to MPFIT. Use MPFITFUN and
MPFITEXPR if you need ideas on how to do that. The function *must*
accept a parameter list, P.
In general there are no restrictions on the number of dimensions in
X, Y or ERR. However the deviates *must* be returned in a
one-dimensional array, and must have the same type (float or
double) as the input arrays.
See below for error reporting mechanisms.
CHECKING STATUS AND HANNDLING ERRORS
Upon return, MPFIT will report the status of the fitting operation
in the STATUS and ERRMSG keywords. The STATUS keyword will contain
a numerical code which indicates the success or failure status.
Generally speaking, any value 1 or greater indicates success, while
a value of 0 or less indicates a possible failure. The ERRMSG
keyword will contain a text string which should describe the error
condition more fully.
By default, MPFIT will trap fatal errors and report them to the
caller gracefully. However, during the debugging process, it is
often useful to halt execution where the error occurred. When you
set the NOCATCH keyword, MPFIT will not do any special error
trapping, and execution will stop whereever the error occurred.
MPFIT does not explicitly change the !ERROR_STATE variable
(although it may be changed implicitly if MPFIT calls MESSAGE). It
is the caller's responsibility to call MESSAGE, /RESET to ensure
that the error state is initialized before calling MPFIT.
User functions may also indicate non-fatal error conditions using
the ERROR_CODE common block variable, as described below under the
MPFIT_ERROR common block definition (by setting ERROR_CODE to a
number between -15 and -1). When the user function sets an error
condition via ERROR_CODE, MPFIT will gracefully exit immediately
and report this condition to the caller. The ERROR_CODE is
returned in the STATUS keyword in that case.
EXPLICIT DERIVATIVES
In the search for the best-fit solution, MPFIT by default
calculates derivatives numerically via a finite difference
approximation. The user-supplied function need not calculate the
derivatives explicitly. However, the user function *may* calculate
the derivatives if desired, but only if the model function is
declared with an additional position parameter, DP, as described
below. If the user function does not accept this additional
parameter, MPFIT will report an error. As a practical matter, it
is often sufficient and even faster to allow MPFIT to calculate the
derivatives numerically, but this option is available for users who
wish more control over the fitting process.
There are two ways to enable explicit derivatives. First, the user
can set the keyword AUTODERIVATIVE=0, which is a global switch for
all parameters. In this case, MPFIT will request explicit
derivatives for every free parameter.
Second, the user may request explicit derivatives for specifically
selected parameters using the PARINFO.MPSIDE=3 (see "CONSTRAINING
PARAMETER VALUES WITH THE PARINFO KEYWORD" below). In this
strategy, the user picks and chooses which parameter derivatives
are computed explicitly versus numerically. When PARINFO[i].MPSIDE
EQ 3, then the ith parameter derivative is computed explicitly.
The keyword setting AUTODERIVATIVE=0 always globally overrides the
individual values of PARINFO.MPSIDE. Setting AUTODERIVATIVE=0 is
equivalent to resetting PARINFO.MPSIDE=3 for all parameters.
Even if the user requests explicit derivatives for some or all
parameters, MPFIT will not always request explicit derivatives on
every user function call.
EXPLICIT DERIVATIVES - CALLING INTERFACE
When AUTODERIVATIVE=0, the user function is responsible for
calculating the derivatives of the *residuals* with respect to each
parameter. The user function should be declared as follows:
;
; MYFUNCT - example user function
; P - input parameter values (N-element array)
; DP - upon input, an N-vector indicating which parameters
; to compute derivatives for;
; upon output, the user function must return
; an ARRAY(M,N) of derivatives in this keyword
; (keywords) - any other keywords specified by FUNCTARGS
; RETURNS - residual values
;
FUNCTION MYFUNCT, p, dp, X=x, Y=y, ERR=err
model = F(x, p) ;; Model function
resid = (y - model)/err ;; Residual calculation (for example)
if n_params() GT 1 then begin
; Create derivative and compute derivative array
requested = dp ; Save original value of DP
dp = make_array(n_elements(x), n_elements(p), value=x[0]*0)
; Compute derivative if requested by caller
for i = 0, n_elements(p)-1 do if requested(i) NE 0 then $
dp(*,i) = FGRAD(x, p, i) / err
endif
return, resid
END
where FGRAD(x, p, i) is a model function which computes the
derivative of the model F(x,p) with respect to parameter P(i) at X.
A quirk in the implementation leaves a stray negative sign in the
definition of DP. The derivative of the *residual* should be
"-FGRAD(x,p,i) / err" because of how the residual is defined
("resid = (data - model) / err"). **HOWEVER** because of the
implementation quirk, MPFIT expects FGRAD(x,p,i)/err instead,
i.e. the opposite sign of the gradient of RESID.
Derivatives should be returned in the DP array. DP should be an
ARRAY(m,n) array, where m is the number of data points and n is the
number of parameters. -DP[i,j] is the derivative of the ith
residual with respect to the jth parameter (note the minus sign
due to the quirk described above).
As noted above, MPFIT may not always request derivatives from the
user function. In those cases, the parameter DP is not passed.
Therefore functions can use N_PARAMS() to indicate whether they
must compute the derivatives or not.
The derivatives with respect to fixed parameters are ignored; zero
is an appropriate value to insert for those derivatives. Upon
input to the user function, DP is set to a vector with the same
length as P, with a value of 1 for a parameter which is free, and a
value of zero for a parameter which is fixed (and hence no
derivative needs to be calculated). This input vector may be
overwritten as needed. In the example above, the original DP
vector is saved to a variable called REQUESTED, and used as a mask
to calculate only those derivatives that are required.
If the data is higher than one dimensional, then the *last*
dimension should be the parameter dimension. Example: fitting a
50x50 image, "dp" should be 50x50xNPAR.
EXPLICIT DERIVATIVES - TESTING and DEBUGGING
For reasonably complicated user functions, the calculation of
explicit derivatives of the correct sign and magnitude can be
difficult to get right. A simple sign error can cause MPFIT to be
confused. MPFIT has a derivative debugging mode which will compute
the derivatives *both* numerically and explicitly, and compare the
results.
It is expected that during production usage, derivative debugging
should be disabled for all parameters.
In order to enable derivative debugging mode, set the following
PARINFO members for the ith parameter.
PARINFO[i].MPSIDE = 3 ; Enable explicit derivatives
PARINFO[i].MPDERIV_DEBUG = 1 ; Enable derivative debugging mode
PARINFO[i].MPDERIV_RELTOL = ?? ; Relative tolerance for comparison
PARINFO[i].MPDERIV_ABSTOL = ?? ; Absolute tolerance for comparison
Note that these settings are maintained on a parameter-by-parameter
basis using PARINFO, so the user can choose which parameters
derivatives will be tested.
When .MPDERIV_DEBUG is set, then MPFIT first computes the
derivative explicitly by requesting them from the user function.
Then, it computes the derivatives numerically via finite
differencing, and compares the two values. If the difference
exceeds a tolerance threshold, then the values are printed out to
alert the user. The tolerance level threshold contains both a
relative and an absolute component, and is expressed as,
ABS(DERIV_U - DERIV_N) GE (ABSTOL + RELTOL*ABS(DERIV_U))
where DERIV_U and DERIV_N are the derivatives computed explicitly
and numerically, respectively. Appropriate values
for most users will be:
PARINFO[i].MPDERIV_RELTOL = 1d-3 ;; Suggested relative tolerance
PARINFO[i].MPDERIV_ABSTOL = 1d-7 ;; Suggested absolute tolerance
although these thresholds may have to be adjusted for a particular
problem. When the threshold is exceeded, users can expect to see a
tabular report like this one:
FJAC DEBUG BEGIN
# IPNT FUNC DERIV_U DERIV_N DIFF_ABS DIFF_REL
FJAC PARM 2
80 -0.7308 0.04233 0.04233 -5.543E-07 -1.309E-05
99 1.370 0.01417 0.01417 -5.518E-07 -3.895E-05
118 0.07187 -0.01400 -0.01400 -5.566E-07 3.977E-05
137 1.844 -0.04216 -0.04216 -5.589E-07 1.326E-05
FJAC DEBUG END
The report will be bracketed by FJAC DEBUG BEGIN/END statements.
Each parameter will be delimited by the statement FJAC PARM n,
where n is the parameter number. The columns are,
IPNT - data point number (0 ... M-1)
FUNC - function value at that point
DERIV_U - explicit derivative value at that point
DERIV_N - numerical derivative estimate at that point
DIFF_ABS - absolute difference = (DERIV_U - DERIV_N)
DIFF_REL - relative difference = (DIFF_ABS)/(DERIV_U)
When prints appear in this report, it is most important to check
that the derivatives computed in two different ways have the same
numerical sign and the same order of magnitude, since these are the
most common programming mistakes.
A line of this form may also appear
# FJAC_MASK = 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1
This line indicates for which parameters explicit derivatives are
expected. A list of all-1s indicates all explicit derivatives for
all parameters are requested from the user function.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of MPFIT can be modified with respect to each
parameter to be fitted. A parameter value can be fixed; simple
boundary constraints can be imposed; limitations on the parameter
changes can be imposed; properties of the automatic derivative can
be modified; and parameters can be tied to one another.
These properties are governed by the PARINFO structure, which is
passed as a keyword parameter to MPFIT.
PARINFO should be an array of structures, one for each parameter.
Each parameter is associated with one element of the array, in
numerical order. The structure can have the following entries
(none are required):
.VALUE - the starting parameter value (but see the START_PARAMS
parameter for more information).
.FIXED - a boolean value, whether the parameter is to be held
fixed or not. Fixed parameters are not varied by
MPFIT, but are passed on to MYFUNCT for evaluation.
.LIMITED - a two-element boolean array. If the first/second
element is set, then the parameter is bounded on the
lower/upper side. A parameter can be bounded on both
sides. Both LIMITED and LIMITS must be given
together.
.LIMITS - a two-element float or double array. Gives the
parameter limits on the lower and upper sides,
respectively. Zero, one or two of these values can be
set, depending on the values of LIMITED. Both LIMITED
and LIMITS must be given together.
.PARNAME - a string, giving the name of the parameter. The
fitting code of MPFIT does not use this tag in any
way. However, the default ITERPROC will print the
parameter name if available.
.STEP - the step size to be used in calculating the numerical
derivatives. If set to zero, then the step size is
computed automatically. Ignored when AUTODERIVATIVE=0.
This value is superceded by the RELSTEP value.
.RELSTEP - the *relative* step size to be used in calculating
the numerical derivatives. This number is the
fractional size of the step, compared to the
parameter value. This value supercedes the STEP
setting. If the parameter is zero, then a default
step size is chosen.
.MPSIDE - selector for type of derivative calculation. This
field can take one of five possible values:
0 - one-sided derivative computed automatically
1 - one-sided derivative (f(x+h) - f(x) )/h
-1 - one-sided derivative (f(x) - f(x-h))/h
2 - two-sided derivative (f(x+h) - f(x-h))/(2*h)
3 - explicit derivative used for this parameter
In the first four cases, the derivative is approximated
numerically by finite difference, with step size
H=STEP, where the STEP parameter is defined above. The
last case, MPSIDE=3, indicates to allow the user
function to compute the derivative explicitly (see
section on "EXPLICIT DERIVATIVES"). AUTODERIVATIVE=0
overrides this setting for all parameters, and is
equivalent to MPSIDE=3 for all parameters. For
MPSIDE=0, the "automatic" one-sided derivative method
will chose a direction for the finite difference which
does not violate any constraints. The other methods
(MPSIDE=-1 or MPSIDE=1) do not perform this check. The
two-sided method is in principle more precise, but
requires twice as many function evaluations. Default:
0.
.MPDERIV_DEBUG - set this value to 1 to enable debugging of
user-supplied explicit derivatives (see "TESTING and
DEBUGGING" section above). In addition, the
user must enable calculation of explicit derivatives by
either setting AUTODERIVATIVE=0, or MPSIDE=3 for the
desired parameters. When this option is enabled, a
report may be printed to the console, depending on the
MPDERIV_ABSTOL and MPDERIV_RELTOL settings.
Default: 0 (no debugging)
.MPDERIV_ABSTOL, .MPDERIV_RELTOL - tolerance settings for
print-out of debugging information, for each parameter
where debugging is enabled. See "TESTING and
DEBUGGING" section above for the meanings of these two
fields.
.MPMAXSTEP - the maximum change to be made in the parameter
value. During the fitting process, the parameter
will never be changed by more than this value in
one iteration.
A value of 0 indicates no maximum. Default: 0.
.TIED - a string expression which "ties" the parameter to other
free or fixed parameters as an equality constraint. Any
expression involving constants and the parameter array P
are permitted.
Example: if parameter 2 is always to be twice parameter
1 then use the following: parinfo[2].tied = '2 * P[1]'.
Since they are totally constrained, tied parameters are
considered to be fixed; no errors are computed for them,
and any LIMITS are not obeyed.
[ NOTE: the PARNAME can't be used in a TIED expression. ]
.MPPRINT - if set to 1, then the default ITERPROC will print the
parameter value. If set to 0, the parameter value
will not be printed. This tag can be used to
selectively print only a few parameter values out of
many. Default: 1 (all parameters printed)
.MPFORMAT - IDL format string to print the parameter within
ITERPROC. Default: '(G20.6)' (An empty string will
also use the default.)
Future modifications to the PARINFO structure, if any, will involve
adding structure tags beginning with the two letters "MP".
Therefore programmers are urged to avoid using tags starting with
"MP", but otherwise they are free to include their own fields
within the PARINFO structure, which will be ignored by MPFIT.
PARINFO Example:
parinfo = replicate({value:0.D, fixed:0, limited:[0,0], $
limits:[0.D,0]}, 5)
parinfo[0].fixed = 1
parinfo[4].limited[0] = 1
parinfo[4].limits[0] = 50.D
parinfo[*].value = [5.7D, 2.2, 500., 1.5, 2000.]
A total of 5 parameters, with starting values of 5.7,
2.2, 500, 1.5, and 2000 are given. The first parameter
is fixed at a value of 5.7, and the last parameter is
constrained to be above 50.
RECURSION
Generally, recursion is not allowed. As of version 1.77, MPFIT has
recursion protection which does not allow a model function to
itself call MPFIT. Users who wish to perform multi-level
optimization should investigate the 'EXTERNAL' function evaluation
methods described below for hard-to-evaluate functions. That
method places more control in the user's hands. The user can
design a "recursive" application by taking care.
In most cases the recursion protection should be well-behaved.
However, if the user is doing debugging, it is possible for the
protection system to get "stuck." In order to reset it, run the
procedure:
MPFIT_RESET_RECURSION
and the protection system should get "unstuck." It is save to call
this procedure at any time.
COMPATIBILITY
This function is designed to work with IDL 5.0 or greater.
Because TIED parameters and the "(EXTERNAL)" user-model feature use
the EXECUTE() function, they cannot be used with the free version
of the IDL Virtual Machine.
DETERMINING THE VERSION OF MPFIT
MPFIT is a changing library. Users of MPFIT may also depend on a
specific version of the library being present. As of version 1.70
of MPFIT, a VERSION keyword has been added which allows the user to
query which version is present. The keyword works like this:
RESULT = MPFIT(/query, VERSION=version)
This call uses the /QUERY keyword to query the version number
without performing any computations. Users of MPFIT can call this
method to determine which version is in the IDL path before
actually using MPFIT to do any numerical work. Upon return, the
VERSION keyword contains the version number of MPFIT, expressed as
a string of the form 'X.Y' where X and Y are integers.
Users can perform their own version checking, or use the built-in
error checking of MPFIT. The MIN_VERSION keyword enforces the
requested minimum version number. For example,
RESULT = MPFIT(/query, VERSION=version, MIN_VERSION='1.70')
will check whether the accessed version is 1.70 or greater, without
performing any numerical processing.
The VERSION and MIN_VERSION keywords were added in MPFIT
version 1.70 and later. If the caller attempts to use the VERSION
or MIN_VERSION keywords, and an *older* version of the code is
present in the caller's path, then IDL will throw an 'unknown
keyword' error. Therefore, in order to be robust, the caller, must
use exception handling. Here is an example demanding at least
version 1.70.
MPFIT_OK = 0 & VERSION = ''
CATCH, CATCHERR
IF CATCHERR EQ 0 THEN MPFIT_OK = MPFIT(/query, VERSION=version, $
MIN_VERSION='1.70')
CATCH, /CANCEL
IF NOT MPFIT_OK THEN $
MESSAGE, 'ERROR: you must have MPFIT version 1.70 or higher in '+$
'your path (found version '+version+')'
Of course, the caller can also do its own version number
requirements checking.
HARD-TO-COMPUTE FUNCTIONS: "EXTERNAL" EVALUATION
The normal mode of operation for MPFIT is for the user to pass a
function name, and MPFIT will call the user function multiple times
as it iterates toward a solution.
Some user functions are particularly hard to compute using the
standard model of MPFIT. Usually these are functions that depend
on a large amount of external data, and so it is not feasible, or
at least highly impractical, to have MPFIT call it. In those cases
it may be possible to use the "(EXTERNAL)" evaluation option.
In this case the user is responsible for making all function *and
derivative* evaluations. The function and Jacobian data are passed
in through the EXTERNAL_FVEC and EXTERNAL_FJAC keywords,
respectively. The user indicates the selection of this option by
specifying a function name (MYFUNCT) of "(EXTERNAL)". No
user-function calls are made when EXTERNAL evaluation is being
used.
** SPECIAL NOTE ** For the "(EXTERNAL)" case, the quirk noted above
does not apply. The gradient matrix, EXTERNAL_FJAC, should be
comparable to "-FGRAD(x,p)/err", which is the *opposite* sign of
the DP matrix described above. In other words, EXTERNAL_FJAC
has the same sign as the derivative of EXTERNAL_FVEC, and the
opposite sign of FGRAD.
At the end of each iteration, control returns to the user, who must
reevaluate the function at its new parameter values. Users should
check the return value of the STATUS keyword, where a value of 9
indicates the user should supply more data for the next iteration,
and re-call MPFIT. The user may refrain from calling MPFIT
further; as usual, STATUS will indicate when the solution has
converged and no more iterations are required.
Because MPFIT must maintain its own data structures between calls,
the user must also pass a named variable to the EXTERNAL_STATE
keyword. This variable must be maintained by the user, but not
changed, throughout the fitting process. When no more iterations
are desired, the named variable may be discarded.
INPUTS:
MYFUNCT - a string variable containing the name of the function to
be minimized. The function should return the weighted
deviations between the model and the data, as described
above.
For EXTERNAL evaluation of functions, this parameter
should be set to a value of "(EXTERNAL)".
START_PARAMS - An one-dimensional array of starting values for each of the
parameters of the model. The number of parameters
should be fewer than the number of measurements.
Also, the parameters should have the same data type
as the measurements (double is preferred).
This parameter is optional if the PARINFO keyword
is used (but see PARINFO). The PARINFO keyword
provides a mechanism to fix or constrain individual
parameters. If both START_PARAMS and PARINFO are
passed, then the starting *value* is taken from
START_PARAMS, but the *constraints* are taken from
PARINFO.
RETURNS:
Returns the array of best-fit parameters.
Exceptions:
* if /QUERY is set (see QUERY).
KEYWORD PARAMETERS:
AUTODERIVATIVE - If this is set, derivatives of the function will
be computed automatically via a finite
differencing procedure. If not set, then MYFUNCT
must provide the explicit derivatives.
Default: set (=1)
NOTE: to supply your own explicit derivatives,
explicitly pass AUTODERIVATIVE=0
BESTNORM - upon return, the value of the summed squared weighted
residuals for the returned parameter values,
i.e. TOTAL(DEVIATES^2).
BEST_FJAC - upon return, BEST_FJAC contains the Jacobian, or
partial derivative, matrix for the best-fit model.
The values are an array,
ARRAY(N_ELEMENTS(DEVIATES),NFREE) where NFREE is the
number of free parameters. This array is only
computed if /CALC_FJAC is set, otherwise BEST_FJAC is
undefined.
The returned array is such that BEST_FJAC[I,J] is the
partial derivative of DEVIATES[I] with respect to
parameter PARMS[PFREE_INDEX[J]]. Note that since
deviates are (data-model)*weight, the Jacobian of the
*deviates* will have the opposite sign from the
Jacobian of the *model*, and may be scaled by a
factor.
BEST_RESID - upon return, an array of best-fit deviates.
CALC_FJAC - if set, then calculate the Jacobian and return it in
BEST_FJAC. If not set, then the return value of
BEST_FJAC is undefined.
COVAR - the covariance matrix for the set of parameters returned
by MPFIT. The matrix is NxN where N is the number of
parameters. The square root of the diagonal elements
gives the formal 1-sigma statistical errors on the
parameters IF errors were treated "properly" in MYFUNC.
Parameter errors are also returned in PERROR.
To compute the correlation matrix, PCOR, use this example:
PCOR = COV * 0
FOR i = 0, n-1 DO FOR j = 0, n-1 DO $
PCOR[i,j] = COV[i,j]/sqrt(COV[i,i]*COV[j,j])
or equivalently, in vector notation,
PCOR = COV / (PERROR # PERROR)
If NOCOVAR is set or MPFIT terminated abnormally, then
COVAR is set to a scalar with value !VALUES.D_NAN.
DOF - number of degrees of freedom, computed as
DOF = N_ELEMENTS(DEVIATES) - NFREE
Note that this doesn't account for pegged parameters (see
NPEGGED). It also does not account for data points which
are assigned zero weight by the user function.
ERRMSG - a string error or warning message is returned.
EXTERNAL_FVEC - upon input, the function values, evaluated at
START_PARAMS. This should be an M-vector, where M
is the number of data points.
EXTERNAL_FJAC - upon input, the Jacobian array of partial
derivative values. This should be a M x N array,
where M is the number of data points and N is the
number of parameters. NOTE: that all FIXED or
TIED parameters must *not* be included in this
array.
EXTERNAL_STATE - a named variable to store MPFIT-related state
information between iterations (used in input and
output to MPFIT). The user must not manipulate
or discard this data until the final iteration is
performed.
FASTNORM - set this keyword to select a faster algorithm to
compute sum-of-square values internally. For systems
with large numbers of data points, the standard
algorithm can become prohibitively slow because it
cannot be vectorized well. By setting this keyword,
MPFIT will run faster, but it will be more prone to
floating point overflows and underflows. Thus, setting
this keyword may sacrifice some stability in the
fitting process.
FTOL - a nonnegative input variable. Termination occurs when both
the actual and predicted relative reductions in the sum of
squares are at most FTOL (and STATUS is accordingly set to
1 or 3). Therefore, FTOL measures the relative error
desired in the sum of squares. Default: 1D-10
FUNCTARGS - A structure which contains the parameters to be passed
to the user-supplied function specified by MYFUNCT via
the _EXTRA mechanism. This is the way you can pass
additional data to your user-supplied function without
using common blocks.
Consider the following example:
if FUNCTARGS = { XVAL:[1.D,2,3], YVAL:[1.D,4,9],
ERRVAL:[1.D,1,1] }
then the user supplied function should be declared
like this:
FUNCTION MYFUNCT, P, XVAL=x, YVAL=y, ERRVAL=err
By default, no extra parameters are passed to the
user-supplied function, but your function should
accept *at least* one keyword parameter. [ This is to
accomodate a limitation in IDL's _EXTRA
parameter-passing mechanism. ]
GTOL - a nonnegative input variable. Termination occurs when the
cosine of the angle between fvec and any column of the
jacobian is at most GTOL in absolute value (and STATUS is
accordingly set to 4). Therefore, GTOL measures the
orthogonality desired between the function vector and the
columns of the jacobian. Default: 1D-10
ITERARGS - The keyword arguments to be passed to ITERPROC via the
_EXTRA mechanism. This should be a structure, and is
similar in operation to FUNCTARGS.
Default: no arguments are passed.
ITERPRINT - The name of an IDL procedure, equivalent to PRINT,
that ITERPROC will use to render output. ITERPRINT
should be able to accept at least four positional
arguments. In addition, it should be able to accept
the standard FORMAT keyword for output formatting; and
the UNIT keyword, to redirect output to a logical file
unit (default should be UNIT=1, standard output).
These keywords are passed using the ITERARGS keyword
above. The ITERPRINT procedure must accept the _EXTRA
keyword.
NOTE: that much formatting can be handled with the
MPPRINT and MPFORMAT tags.
Default: 'MPFIT_DEFPRINT' (default internal formatter)
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the MPFIT routine. ITERPROC is always
called in the final iteration. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, DOF=dof, PFORMAT=pformat, $
UNIT=unit, ...
; perform custom iteration update
END
ITERPROC must either accept all three keyword
parameters (FUNCTARGS, PARINFO and QUIET), or at least
accept them via the _EXTRA keyword.
MYFUNCT is the user-supplied function to be minimized,
P is the current set of model parameters, ITER is the
iteration number, and FUNCTARGS are the arguments to be
passed to MYFUNCT. FNORM should be the chi-squared
value. QUIET is set when no textual output should be
printed. DOF is the number of degrees of freedom,
normally the number of points less the number of free
parameters. See below for documentation of PARINFO.
PFORMAT is the default parameter value format. UNIT is
passed on to the ITERPRINT procedure, and should
indicate the file unit where log output will be sent
(default: standard output).
In implementation, ITERPROC can perform updates to the
terminal or graphical user interface, to provide
feedback while the fit proceeds. If the fit is to be
stopped for any reason, then ITERPROC should set the
common block variable ERROR_CODE to negative value
between -15 and -1 (see MPFIT_ERROR common block
below). In principle, ITERPROC should probably not
modify the parameter values, because it may interfere
with the algorithm's stability. In practice it is
allowed.
Default: an internal routine is used to print the
parameter values.
ITERSTOP - Set this keyword if you wish to be able to stop the
fitting by hitting the predefined ITERKEYSTOP key on
the keyboard. This only works if you use the default
ITERPROC.
ITERKEYSTOP - A keyboard key which will halt the fit (and if
ITERSTOP is set and the default ITERPROC is used).
ITERSTOPKEY may either be a one-character string
with the desired key, or a scalar integer giving the
ASCII code of the desired key.
Default: 7b (control-g)
NOTE: the default value of ASCI 7 (control-G) cannot
be read in some windowing environments, so you must
change to a printable character like 'q'.
MAXITER - The maximum number of iterations to perform. If the
number of calculation iterations exceeds MAXITER, then
the STATUS value is set to 5 and MPFIT returns.
If MAXITER EQ 0, then MPFIT does not iterate to adjust
parameter values; however, the user function is evaluated
and parameter errors/covariance/Jacobian are estimated
before returning.
Default: 200 iterations
MIN_VERSION - The minimum requested version number. This must be
a scalar string of the form returned by the VERSION
keyword. If the current version of MPFIT does not
satisfy the minimum requested version number, then,
MPFIT(/query, min_version='...') returns 0
MPFIT(...) returns NAN
Default: no version number check
NOTE: MIN_VERSION was added in MPFIT version 1.70
NFEV - the number of MYFUNCT function evaluations performed.
NFREE - the number of free parameters in the fit. This includes
parameters which are not FIXED and not TIED, but it does
include parameters which are pegged at LIMITS.
NITER - the number of iterations completed.
NOCATCH - if set, then MPFIT will not perform any error trapping.
By default (not set), MPFIT will trap errors and report
them to the caller. This keyword will typically be used
for debugging.
NOCOVAR - set this keyword to prevent the calculation of the
covariance matrix before returning (see COVAR)
NPEGGED - the number of free parameters which are pegged at a
LIMIT.
NPRINT - The frequency with which ITERPROC is called. A value of
1 indicates that ITERPROC is called with every iteration,
while 2 indicates every other iteration, etc. Be aware
that several Levenberg-Marquardt attempts can be made in
a single iteration. Also, the ITERPROC is *always*
called for the final iteration, regardless of the
iteration number.
Default value: 1
PARINFO - A one-dimensional array of structures.
Provides a mechanism for more sophisticated constraints
to be placed on parameter values. When PARINFO is not
passed, then it is assumed that all parameters are free
and unconstrained. Values in PARINFO are never
modified during a call to MPFIT.
See description above for the structure of PARINFO.
Default value: all parameters are free and unconstrained.
PERROR - The formal 1-sigma errors in each parameter, computed
from the covariance matrix. If a parameter is held
fixed, or if it touches a boundary, then the error is
reported as zero.
If the fit is unweighted (i.e. no errors were given, or
the weights were uniformly set to unity), then PERROR
will probably not represent the true parameter
uncertainties.
*If* you can assume that the true reduced chi-squared
value is unity -- meaning that the fit is implicitly
assumed to be of good quality -- then the estimated
parameter uncertainties can be computed by scaling PERROR
by the measured chi-squared value.
DOF = N_ELEMENTS(X) - N_ELEMENTS(PARMS) ; deg of freedom
PCERROR = PERROR * SQRT(BESTNORM / DOF) ; scaled uncertainties
PFREE_INDEX - upon return, PFREE_INDEX contains an index array
which indicates which parameter were allowed to
vary. I.e. of all the parameters PARMS, only
PARMS[PFREE_INDEX] were varied.
QUERY - if set, then MPFIT() will return immediately with one of
the following values:
1 - if MIN_VERSION is not set
1 - if MIN_VERSION is set and MPFIT satisfies the minimum
0 - if MIN_VERSION is set and MPFIT does not satisfy it
The VERSION output keyword is always set upon return.
Default: not set.
QUIET - set this keyword when no textual output should be printed
by MPFIT
RESDAMP - a scalar number, indicating the cut-off value of
residuals where "damping" will occur. Residuals with
magnitudes greater than this number will be replaced by
their logarithm. This partially mitigates the so-called
large residual problem inherent in least-squares solvers
(as for the test problem CURVI, http://www.maxthis.com/-
curviex.htm). A value of 0 indicates no damping.
Default: 0
Note: RESDAMP doesn't work with AUTODERIV=0
STATUS - an integer status code is returned. All values greater
than zero can represent success (however STATUS EQ 5 may
indicate failure to converge). It can have one of the
following values:
-18 a fatal execution error has occurred. More information
may be available in the ERRMSG string.
-16 a parameter or function value has become infinite or an
undefined number. This is usually a consequence of
numerical overflow in the user's model function, which
must be avoided.
-15 to -1
these are error codes that either MYFUNCT or ITERPROC
may return to terminate the fitting process (see
description of MPFIT_ERROR common below). If either
MYFUNCT or ITERPROC set ERROR_CODE to a negative number,
then that number is returned in STATUS. Values from -15
to -1 are reserved for the user functions and will not
clash with MPFIT.
0 improper input parameters.
1 both actual and predicted relative reductions
in the sum of squares are at most FTOL.
2 relative error between two consecutive iterates
is at most XTOL
3 conditions for STATUS = 1 and STATUS = 2 both hold.
4 the cosine of the angle between fvec and any
column of the jacobian is at most GTOL in
absolute value.
5 the maximum number of iterations has been reached
6 FTOL is too small. no further reduction in
the sum of squares is possible.
7 XTOL is too small. no further improvement in
the approximate solution x is possible.
8 GTOL is too small. fvec is orthogonal to the
columns of the jacobian to machine precision.
9 A successful single iteration has been completed, and
the user must supply another "EXTERNAL" evaluation of
the function and its derivatives. This status indicator
is neither an error nor a convergence indicator.
VERSION - upon return, VERSION will be set to the MPFIT internal
version number. The version number will be a string of
the form "X.Y" where X is a major revision number and Y
is a minor revision number.
NOTE: the VERSION keyword was not present before
MPFIT version number 1.70, therefore, callers must
use exception handling when using this keyword.
XTOL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at most
XTOL (and STATUS is accordingly set to 2 or 3). Therefore,
XTOL measures the relative error desired in the approximate
solution. Default: 1D-10
EXAMPLE:
p0 = [5.7D, 2.2, 500., 1.5, 2000.]
fa = {X:x, Y:y, ERR:err}
p = mpfit('MYFUNCT', p0, functargs=fa)
Minimizes sum of squares of MYFUNCT. MYFUNCT is called with the X,
Y, and ERR keyword parameters that are given by FUNCTARGS. The
resulting parameter values are returned in p.
COMMON BLOCKS:
COMMON MPFIT_ERROR, ERROR_CODE
User routines may stop the fitting process at any time by
setting an error condition. This condition may be set in either
the user's model computation routine (MYFUNCT), or in the
iteration procedure (ITERPROC).
To stop the fitting, the above common block must be declared,
and ERROR_CODE must be set to a negative number. After the user
procedure or function returns, MPFIT checks the value of this
common block variable and exits immediately if the error
condition has been set. This value is also returned in the
STATUS keyword: values of -1 through -15 are reserved error
codes for the user routines. By default the value of ERROR_CODE
is zero, indicating a successful function/procedure call.
COMMON MPFIT_PROFILE
COMMON MPFIT_MACHAR
COMMON MPFIT_CONFIG
These are undocumented common blocks are used internally by
MPFIT and may change in future implementations.
THEORY OF OPERATION:
There are many specific strategies for function minimization. One
very popular technique is to use function gradient information to
realize the local structure of the function. Near a local minimum
the function value can be taylor expanded about x0 as follows:
f(x) = f(x0) + f'(x0) . (x-x0) + (1/2) (x-x0) . f''(x0) . (x-x0)
----- --------------- ------------------------------- (1)
Order 0th 1st 2nd
Here f'(x) is the gradient vector of f at x, and f''(x) is the
Hessian matrix of second derivatives of f at x. The vector x is
the set of function parameters, not the measured data vector. One
can find the minimum of f, f(xm) using Newton's method, and
arrives at the following linear equation:
f''(x0) . (xm-x0) = - f'(x0) (2)
If an inverse can be found for f''(x0) then one can solve for
(xm-x0), the step vector from the current position x0 to the new
projected minimum. Here the problem has been linearized (ie, the
gradient information is known to first order). f''(x0) is
symmetric n x n matrix, and should be positive definite.
The Levenberg - Marquardt technique is a variation on this theme.
It adds an additional diagonal term to the equation which may aid the
convergence properties:
(f''(x0) + nu I) . (xm-x0) = -f'(x0) (2a)
where I is the identity matrix. When nu is large, the overall
matrix is diagonally dominant, and the iterations follow steepest
descent. When nu is small, the iterations are quadratically
convergent.
In principle, if f''(x0) and f'(x0) are known then xm-x0 can be
determined. However the Hessian matrix is often difficult or
impossible to compute. The gradient f'(x0) may be easier to
compute, if even by finite difference techniques. So-called
quasi-Newton techniques attempt to successively estimate f''(x0)
by building up gradient information as the iterations proceed.
In the least squares problem there are further simplifications
which assist in solving eqn (2). The function to be minimized is
a sum of squares:
f = Sum(hi^2) (3)
where hi is the ith residual out of m residuals as described
above. This can be substituted back into eqn (2) after computing
the derivatives:
f' = 2 Sum(hi hi')
f'' = 2 Sum(hi' hj') + 2 Sum(hi hi'') (4)
If one assumes that the parameters are already close enough to a
minimum, then one typically finds that the second term in f'' is
negligible [or, in any case, is too difficult to compute]. Thus,
equation (2) can be solved, at least approximately, using only
gradient information.
In matrix notation, the combination of eqns (2) and (4) becomes:
hT' . h' . dx = - hT' . h (5)
Where h is the residual vector (length m), hT is its transpose, h'
is the Jacobian matrix (dimensions n x m), and dx is (xm-x0). The
user function supplies the residual vector h, and in some cases h'
when it is not found by finite differences (see MPFIT_FDJAC2,
which finds h and hT'). Even if dx is not the best absolute step
to take, it does provide a good estimate of the best *direction*,
so often a line minimization will occur along the dx vector
direction.
The method of solution employed by MINPACK is to form the Q . R
factorization of h', where Q is an orthogonal matrix such that QT .
Q = I, and R is upper right triangular. Using h' = Q . R and the
ortogonality of Q, eqn (5) becomes
(RT . QT) . (Q . R) . dx = - (RT . QT) . h
RT . R . dx = - RT . QT . h (6)
R . dx = - QT . h
where the last statement follows because R is upper triangular.
Here, R, QT and h are known so this is a matter of solving for dx.
The routine MPFIT_QRFAC provides the QR factorization of h, with
pivoting, and MPFIT_QRSOL;V provides the solution for dx.
REFERENCES:
Markwardt, C. B. 2008, "Non-Linear Least Squares Fitting in IDL
with MPFIT," in proc. Astronomical Data Analysis Software and
Systems XVIII, Quebec, Canada, ASP Conference Series, Vol. XXX, eds.
D. Bohlender, P. Dowler & D. Durand (Astronomical Society of the
Pacific: San Francisco), p. 251-254 (ISBN: 978-1-58381-702-5)
http://arxiv.org/abs/0902.2850
Link to NASA ADS: http://adsabs.harvard.edu/abs/2009ASPC..411..251M
Link to ASP: http://aspbooks.org/a/volumes/table_of_contents/411
Refer to the MPFIT website as:
http://purl.com/net/mpfit
MINPACK-1 software, by Jorge More' et al, available from netlib.
http://www.netlib.org/
"Optimization Software Guide," Jorge More' and Stephen Wright,
SIAM, *Frontiers in Applied Mathematics*, Number 14.
(ISBN: 978-0-898713-22-0)
More', J. 1978, "The Levenberg-Marquardt Algorithm: Implementation
and Theory," in Numerical Analysis, vol. 630, ed. G. A. Watson
(Springer-Verlag: Berlin), p. 105 (DOI: 10.1007/BFb0067690 )
MODIFICATION HISTORY:
Translated from MINPACK-1 in FORTRAN, Apr-Jul 1998, CM
Fixed bug in parameter limits (x vs xnew), 04 Aug 1998, CM
Added PERROR keyword, 04 Aug 1998, CM
Added COVAR keyword, 20 Aug 1998, CM
Added NITER output keyword, 05 Oct 1998
D.L Windt, Bell Labs, windt@bell-labs.com;
Made each PARINFO component optional, 05 Oct 1998 CM
Analytical derivatives allowed via AUTODERIVATIVE keyword, 09 Nov 1998
Parameter values can be tied to others, 09 Nov 1998
Fixed small bugs (Wayne Landsman), 24 Nov 1998
Added better exception error reporting, 24 Nov 1998 CM
Cosmetic documentation changes, 02 Jan 1999 CM
Changed definition of ITERPROC to be consistent with TNMIN, 19 Jan 1999 CM
Fixed bug when AUTDERIVATIVE=0. Incorrect sign, 02 Feb 1999 CM
Added keyboard stop to MPFIT_DEFITER, 28 Feb 1999 CM
Cosmetic documentation changes, 14 May 1999 CM
IDL optimizations for speed & FASTNORM keyword, 15 May 1999 CM
Tried a faster version of mpfit_enorm, 30 May 1999 CM
Changed web address to cow.physics.wisc.edu, 14 Jun 1999 CM
Found malformation of FDJAC in MPFIT for 1 parm, 03 Aug 1999 CM
Factored out user-function call into MPFIT_CALL. It is possible,
but currently disabled, to call procedures. The calling format
is similar to CURVEFIT, 25 Sep 1999, CM
Slightly changed mpfit_tie to be less intrusive, 25 Sep 1999, CM
Fixed some bugs associated with tied parameters in mpfit_fdjac, 25
Sep 1999, CM
Reordered documentation; now alphabetical, 02 Oct 1999, CM
Added QUERY keyword for more robust error detection in drivers, 29
Oct 1999, CM
Documented PERROR for unweighted fits, 03 Nov 1999, CM
Split out MPFIT_RESETPROF to aid in profiling, 03 Nov 1999, CM
Some profiling and speed optimization, 03 Nov 1999, CM
Worst offenders, in order: fdjac2, qrfac, qrsolv, enorm.
fdjac2 depends on user function, qrfac and enorm seem to be
fully optimized. qrsolv probably could be tweaked a little, but
is still <10% of total compute time.
Made sure that !err was set to 0 in MPFIT_DEFITER, 10 Jan 2000, CM
Fixed small inconsistency in setting of QANYLIM, 28 Jan 2000, CM
Added PARINFO field RELSTEP, 28 Jan 2000, CM
Converted to MPFIT_ERROR common block for indicating error
conditions, 28 Jan 2000, CM
Corrected scope of MPFIT_ERROR common block, CM, 07 Mar 2000
Minor speed improvement in MPFIT_ENORM, CM 26 Mar 2000
Corrected case where ITERPROC changed parameter values and
parameter values were TIED, CM 26 Mar 2000
Changed MPFIT_CALL to modify NFEV automatically, and to support
user procedures more, CM 26 Mar 2000
Copying permission terms have been liberalized, 26 Mar 2000, CM
Catch zero value of zero a(j,lj) in MPFIT_QRFAC, 20 Jul 2000, CM
(thanks to David Schlegel )
MPFIT_SETMACHAR is called only once at init; only one common block
is created (MPFIT_MACHAR); it is now a structure; removed almost
all CHECK_MATH calls for compatibility with IDL5 and !EXCEPT;
profiling data is now in a structure too; noted some
mathematical discrepancies in Linux IDL5.0, 17 Nov 2000, CM
Some significant changes. New PARINFO fields: MPSIDE, MPMINSTEP,
MPMAXSTEP. Improved documentation. Now PTIED constraints are
maintained in the MPCONFIG common block. A new procedure to
parse PARINFO fields. FDJAC2 now computes a larger variety of
one-sided and two-sided finite difference derivatives. NFEV is
stored in the MPCONFIG common now. 17 Dec 2000, CM
Added check that PARINFO and XALL have same size, 29 Dec 2000 CM
Don't call function in TERMINATE when there is an error, 05 Jan
2000
Check for float vs. double discrepancies; corrected implementation
of MIN/MAXSTEP, which I still am not sure of, but now at least
the correct behavior occurs *without* it, CM 08 Jan 2001
Added SCALE_FCN keyword, to allow for scaling, as for the CASH
statistic; added documentation about the theory of operation,
and under the QR factorization; slowly I'm beginning to
understand the bowels of this algorithm, CM 10 Jan 2001
Remove MPMINSTEP field of PARINFO, for now at least, CM 11 Jan
2001
Added RESDAMP keyword, CM, 14 Jan 2001
Tried to improve the DAMP handling a little, CM, 13 Mar 2001
Corrected .PARNAME behavior in _DEFITER, CM, 19 Mar 2001
Added checks for parameter and function overflow; a new STATUS
value to reflect this; STATUS values of -15 to -1 are reserved
for user function errors, CM, 03 Apr 2001
DAMP keyword is now a TANH, CM, 03 Apr 2001
Added more error checking of float vs. double, CM, 07 Apr 2001
Fixed bug in handling of parameter lower limits; moved overflow
checking to end of loop, CM, 20 Apr 2001
Failure using GOTO, TERMINATE more graceful if FNORM1 not defined,
CM, 13 Aug 2001
Add MPPRINT tag to PARINFO, CM, 19 Nov 2001
Add DOF keyword to DEFITER procedure, and print degrees of
freedom, CM, 28 Nov 2001
Add check to be sure MYFUNCT is a scalar string, CM, 14 Jan 2002
Addition of EXTERNAL_FJAC, EXTERNAL_FVEC keywords; ability to save
fitter's state from one call to the next; allow '(EXTERNAL)'
function name, which implies that user will supply function and
Jacobian at each iteration, CM, 10 Mar 2002
Documented EXTERNAL evaluation code, CM, 10 Mar 2002
Corrected signficant bug in the way that the STEP parameter, and
FIXED parameters interacted (Thanks Andrew Steffl), CM, 02 Apr
2002
Allow COVAR and PERROR keywords to be computed, even in case of
'(EXTERNAL)' function, 26 May 2002
Add NFREE and NPEGGED keywords; compute NPEGGED; compute DOF using
NFREE instead of n_elements(X), thanks to Kristian Kjaer, CM 11
Sep 2002
Hopefully PERROR is all positive now, CM 13 Sep 2002
Documented RELSTEP field of PARINFO (!!), CM, 25 Oct 2002
Error checking to detect missing start pars, CM 12 Apr 2003
Add DOF keyword to return degrees of freedom, CM, 30 June 2003
Always call ITERPROC in the final iteration; add ITERKEYSTOP
keyword, CM, 30 June 2003
Correct bug in MPFIT_LMPAR of singularity handling, which might
likely be fatal for one-parameter fits, CM, 21 Nov 2003
(with thanks to Peter Tuthill for the proper test case)
Minor documentation adjustment, 03 Feb 2004, CM
Correct small error in QR factorization when pivoting; document
the return values of QRFAC when pivoting, 21 May 2004, CM
Add MPFORMAT field to PARINFO, and correct behavior of interaction
between MPPRINT and PARNAME in MPFIT_DEFITERPROC (thanks to Tim
Robishaw), 23 May 2004, CM
Add the ITERPRINT keyword to allow redirecting output, 26 Sep
2004, CM
Correct MAXSTEP behavior in case of a negative parameter, 26 Sep
2004, CM
Fix bug in the parsing of MINSTEP/MAXSTEP, 10 Apr 2005, CM
Fix bug in the handling of upper/lower limits when the limit was
negative (the fitting code would never "stick" to the lower
limit), 29 Jun 2005, CM
Small documentation update for the TIED field, 05 Sep 2005, CM
Convert to IDL 5 array syntax (!), 16 Jul 2006, CM
If MAXITER equals zero, then do the basic parameter checking and
uncertainty analysis, but do not adjust the parameters, 15 Aug
2006, CM
Added documentation, 18 Sep 2006, CM
A few more IDL 5 array syntax changes, 25 Sep 2006, CM
Move STRICTARR compile option inside each function/procedure, 9 Oct 2006
Bug fix for case of MPMAXSTEP and fixed parameters, thanks
to Huib Intema (who found it from the Python translation!), 05 Feb 2007
Similar fix for MPFIT_FDJAC2 and the MPSIDE sidedness of
derivatives, also thanks to Huib Intema, 07 Feb 2007
Clarify documentation on user-function, derivatives, and PARINFO,
27 May 2007
Change the wording of "Analytic Derivatives" to "Explicit
Derivatives" in the documentation, CM, 03 Sep 2007
Further documentation tweaks, CM, 13 Dec 2007
Add COMPATIBILITY section and add credits to copyright, CM, 13 Dec
2007
Document and enforce that START_PARMS and PARINFO are 1-d arrays,
CM, 29 Mar 2008
Previous change for 1-D arrays wasn't correct for
PARINFO.LIMITED/.LIMITS; now fixed, CM, 03 May 2008
Documentation adjustments, CM, 20 Aug 2008
Change some minor FOR-loop variables to type-long, CM, 03 Sep 2008
Change error handling slightly, document NOCATCH keyword,
document error handling in general, CM, 01 Oct 2008
Special case: when either LIMITS is zero, and a parameter pushes
against that limit, the coded that 'pegged' it there would not
work since it was a relative condition; now zero is handled
properly, CM, 08 Nov 2008
Documentation of how TIED interacts with LIMITS, CM, 21 Dec 2008
Better documentation of references, CM, 27 Feb 2009
If MAXITER=0, then be sure to set STATUS=5, which permits the
the covariance matrix to be computed, CM, 14 Apr 2009
Avoid numerical underflow while solving for the LM parameter,
(thanks to Sergey Koposov) CM, 14 Apr 2009
Use individual functions for all possible MPFIT_CALL permutations,
(and make sure the syntax is right) CM, 01 Sep 2009
Correct behavior of MPMAXSTEP when some parameters are frozen,
thanks to Josh Destree, CM, 22 Nov 2009
Update the references section, CM, 22 Nov 2009
1.70 - Add the VERSION and MIN_VERSION keywords, CM, 22 Nov 2009
1.71 - Store pre-calculated revision in common, CM, 23 Nov 2009
1.72-1.74 - Documented alternate method to compute correlation matrix,
CM, 05 Feb 2010
1.75 - Enforce TIED constraints when preparing to terminate the
routine, CM, 2010-06-22
1.76 - Documented input keywords now are not modified upon output,
CM, 2010-07-13
1.77 - Upon user request (/CALC_FJAC), compute Jacobian matrix and
return in BEST_FJAC; also return best residuals in
BEST_RESID; also return an index list of free parameters as
PFREE_INDEX; add a fencepost to prevent recursion
CM, 2010-10-27
1.79 - Documentation corrections. CM, 2011-08-26
1.81 - Fix bug in interaction of AUTODERIVATIVE=0 and .MPSIDE=3;
Document FJAC_MASK. CM, 2012-05-08
$Id: mpfit.pro,v 1.2 2014/02/24 22:26:01 bdavis Exp $
NAME:
mptsout
PURPOSE:
write a table of MPTS data and errors from the edge along
with GPI average
CATEGORY:
MPTS, MDSplus
CALLING SEQUENCE:
mptsout, shot, r1=r1, r2=r2, t1=t1, t2=t2, outfile=outfile
INPUTS:
shot - MDSplus shot number, i.e, ID.
KEYWORDS:
(all Optional)
r1 - starting radius (cm) for printed values (default=120 cm)
r2 - starting radius (cm) for printed values (default=156 cm)
t1 - Starting x-value desired (typically time, in seconds).
Defaults to 0.3 s
t2 - Ending x-value desired. Defaults to 0.9 s
outFile - name defaults to 'MPTS_'+shot+'.txt'
EXAMPLE:
IDL> for shot=138844,138847 do mptsout, shot
HISTORY:
Written 04-Jun-2013 by Bill Davis for Stewart Zweben
NAME:
mptssurface
PURPOSE:
A graphical interface for plotting shaded surfaces of NSTX Multi-point
Thomson Scattering data (MPTS) from MDSplus. Summary plots of Ip,
D-alpha, Neutral Beam and RF input power, and stored energy (W-mhd from
EFIT). Times of NB and RF heating are indicated on the surfaces by
darker shading. Different controls are provided to change the viewing
angle and other plot parameters. Projection of data maxima vs. radius may be
projected on the "back wall". (For critical accuracy of values,
especially on the edges, please check with the Thomson diagnosticians
personally.)
CATEGORY:
3-D Plotting, MDSplus, NSTX, Widgets
CALLING SEQUENCE:
mptssurface, shot
INPUT PARAMETERS:
shot - MDSplus shot #
KEYWORD PARAMETERS:
autoRefresh - if set, will automatically refresh when MDSplus event
MPTS_REFRESH is declared
refreshEvent - default is 'MPTS_REFRESH'
warning - if=0, no widgets will be popped for warnings
charsize - character size of plots (DEFAULT=2)
density - if set, will display Density instead of Temperature initially
contour - if=0, will not overplot contours on the surface
project - if=1, will project maxima of variable vs. radius on "back wall"
GROUP: The widget ID of the widget that calls mptssurface. When this
keyword is specified, the death of the caller results in the
death of mptssurface.
BLOCK: Set this keyword to have XMANAGER block when this application is
registered. By default the Xmanager keyword NO_BLOCK is set to
1 to provide access to the command line if active command line
processing is available. Note that setting BLOCK for this
application will cause all widget applications to block, not
only this application. For more information see the NO_BLOCK
keyword to XMANAGER.
LIMITATIONS:
Some liberties have been taken "massaging" the data from MDSplus to make
nice looking surfaces, such as median smoothing with more on the edges, and
interpolating between time points and radii of the raw data.
mptssurface does not accept all of the keywords that the IDL command
SURFACE does.
EXAMPLE:
IDL> mptssurface, 142000, /project
MODIFICATION HISTORY:
06-Jun-2013 made shades work when zooming in
01-Aug-2011 Added Kelvin keyword for presentation to non-physicists
30-Nov-2010 Added color shading for other variables onto surface plot.
11-Nov-2010 Added contours and projection of maxima on back wall
28-Oct-2010 improved data filtering per Ben LeBlanc and Ahmed Diallo
22-Oct-2010 converted from MPTSsurface for Joel Hosea
20-May-04 Better message when no analysis data, or times out-of-range
10-Feb-03 Made shaded surface the default [BD]
25-Feb-02 List shot date and time on plot [BD]
01-Feb-01 Added "Copy Plot to Tek Window" option
14-Sep-00 Added min & max R options & better shot buttons. [BD]
29-Aug-00 Made from RSI xsurface [BD]
Created from a template written by: Steve Richards, January, 1991.
NAME: NNET.PRO PURPOSE: Neural network classifier. This is a standard 3-layer back-propagation net. CALLING SEQUENCE: NNET, bias_hid, w_hid, bias_out, w_out, input, h_output, $ output, first, second, third INPUTS: bias_hid - Bias weights on the hidden neurons (DP vector [n_hid]). w_hid - weights between input & hidden layers (DP array [n_in,n_hid]). bias_out - Bias weights on the output neurons (DP vector [n_out]). w_out - weights between hidden & output layers (DP array [n_hid,n_out]). input - input values (DP vector [n_in]). OUTPUTS: h_output - computed values of hidden layer neurons (DP vector [n_hid]). output - computed values of output neurons (DP vector [n_out]). first - index of output neuron with highest value. second - index of second place neuron. third - index of third place neuron (if there are more than two output neurons). KEYWORD PARAMETERS None. EXAMPLE: IDL> nnet, bias_hid, w_hid, bias_out, w_out, input, hout, output - input is the pattern you want to classify. Must be a normalized float or DP vector or the same size as the training patterns used to train the weights. HISTORY: Version 1.0 T. Beck Advanced Computer Concepts, Inc. 21 Apr 1999
NAME:
OnAlpha
PURPOSE:
Tests for running on an alpha computer. You can specify the
the desired Alpha computer. Optionally beeps, and prints a
message and returns an error if not on the desired Alpha computer.
CATEGORY:
OS Specific
CALLING SEQUENCE:
IDL> OK = OnAlpha('KEES')
INPUTS:
(Optional)
compWanted - string of VMS alpha system, e.g., 'mel' (default='KEES')
KEYWORD PARAMETERS:
(Optional)
NOBEEP - if set, no beep when not on desired alpha
QUIET - if set, no message is printed to the terminal
OUTPUTS:
OK = If = 1, then on desired alpha, else 0 out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> OK = onAlpha( )
NOTES:
MODIFICATION HISTORY:
30-May-00 Since Multinet recently added places, remove need for
it.
20-Oct-99 Written by Bill Davis, PPPL
NAME:
onComputer
PURPOSE:
Return 1 if on the specified computer.
First uses enironmental variable HOST has the computer name.
CATEGORY:
System
CALLING SEQUENCE:
IDL> OK = onComputer( computerName )
INPUTS:
computerName - name of computer (best not to have domain included)
this not case sensitive.
KEYWORD PARAMETERS:
var - Environmental variable to check for computer name.
(defaults to 'HOST'). If HOST not defined, will still work on Linux
HLP - When set, help information is printed.
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
OK = 1 if environmental variable "camac_server" is non-blank
EXAMPLE:
NOTES:
When the routine is called with no parameters, or with the
keyword hlp set, help information is printed.
MODIFICATION HISTORY:
08-Jan-2009 Written by Bill Davis, PPPL
NAME:
oplotsep
PURPOSE:
Overplot separatrix and limiter onto grid with GPI images
already drawn. Works with 2010 NSTX shots.
CALLING SEQUENCE:
IDL> oplotsep, shot, time, fit=fit
INPUTS:
shot - NSTX shot number
time - shot time in seconds
KEYWORD PARAMETERS:
Inputs:
manifold - show manifold
sepColor - color you want separatrix drawn in, 'e.g. 'green'
DEFAULT = 'white'
charsize - size of characters on plot
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
xLim_out - x pixels for drawing limiter
zLim_out - z pixels for drawing limiter
outXsep - x values of separatrix to plot in camera viewport
outZsep - z values of separatrix to plot in camera viewport
rsep - r values of right half of separatrix
zsep - z values of right half of separatrix
status - if odd, then success
EXAMPLE:
IDL> nx = 64 & ny = 80
IDL> x = findgen( nx )+1 & y = findgen( ny )+1
IDL> in_pos = [.1,.4,.9,.9] ; draw in top part of screen, say
IDL> Right_Aspect, x, y, IN_POS=in_pos, POSITION=out_pos
IDL> plot, x, y, /nodata, pos=out_pos
IDL> tvimage, 255-bytscl(dist(nx,ny)), x, y, position=getpos()
IDL> plot, x, y, /nodata, pos=out_pos, /noerase ; redraw ticks
IDL> oplotsep, 139442, 0.4, position=out_pos
if image expanded:
IDL> mag = 3
IDL> nx = 64*mag & ny = 80*mag
IDL> x = findgen( nx )+1 & y = findgen( ny )+1
IDL> x = x/mag & y = y/mag
IDL> window, xsize=nx, ysize=ny
IDL> image = 255-bytscl(dist(nx,ny))
IDL> pos = [0,0,1,1]
IDL> plot, x, y, /nodata, pos=pos
IDL> tvimage, image, x, y
IDL> oplotsep, 139442, 0.4
IDL>
IDL>
IDL>
MODIFICATION HISTORY:
13-Sep-2013 use ph7_projection for R,Z to i,j conversion
WRITTEN 19-Mar-2013 by Bill Davis for Stewart Zweben
NAME: OS_FAMILY PURPOSE: Return the current operating system as in !VERSION.OS_FAMILY CATEGORY: OS Specific CALLING SEQUENCE: result = OS_FAMILY() INPUTS: None OUTPUTS: result - scalar string containing one of the four values 'Windows','MacOS','vms' or 'unix' NOTES: OS_FAMILY is assumed to be 'unix' if !VERSION.OS is not 'windows', 'MacOS' or 'vms' To make procedures from IDL V4.0 and later compatibile with earlier versions of IDL, replace calls to !VERSION.OS_FAMILY with OS_FAMILY(). PROCEDURES CALLED: function tag_exists REVISION HISTORY: Written, W. Landsman
NAME:
PARCHECK
PURPOSE:
To check that a procedure has been called with the minimum of allowed
number of parameters.
CATEGORY:
Error checking
CALLING SEQUENCE:
PARCHECK,NPARM,MINPARMS,CALLINGPRO
PARAMETERS:
NPARM (REQ) (I) (0) (I)
required input scalar giving the number of parameters
in the procedure call (i.e. n_params(0)).
MINPARMS (REQ) (I) (0 1) (I)
If scalar, the minimum number of parameters needed for the
procedure to execute properly.
If an array, it represents the allowed numbers of
parameters (e.g. if 3,4 or 6 parameters are allowed,
then set minparms([0,1,2]) = [3,4,6] ).
CALLINGPRO (REQ) (I) (0) (S)
Required string giving the name of the calling procedure.
EXAMPLES:
To determine if procedure pro, which contains a
call to parcheck has the minimum number of parameters
(i.e. 4):
PARCHECK,N_PARAMS(),4,'PRO'
If the same procedure can have 4,5,7, or 8 parameters
then use:
PARCHECK,N_PARAMS(),[4,5,7,8],'PRO'
PROCEDURE:
The input parameters to PARCHECK are first checked themselves
using PCHECK. If MINPARMS is a scalar it is compared to NPARM.
If NPARM < MINPARMS, then an error message is printed and the
procedure returns to the main level. If MINPARMS is a vector,
then NPARM is subtracted from each value of MINPARMS and the
resulting vector is checked for zeroes. If no values are zero,
then error messages are printed and the program returns to the
main level.
MODIFICATION HISTORY :
Mar 30 1987 cag gsfc initial program
Apr 1987 rwt gsfc add vector input for parameters
Mar 15 1988 cag gsfc add vax rdaf-style prolog
Jul 12 1989 jtb gsfc converted to sun/unix idl
Nov 2 1989 rwt gsfc correct print format syntax
May 10 1991 PJL GSFC corrected prolog format
Jun 21 1991 gra casa cleaned up; tested SUN, DEC, VAX;
updated prolog.
Jun 28 1991 PJL GSFC added npar test; tested on SUN and VAX;
updated prolog
NAME: PLOTTSwall PURPOSE: This procedure will plot the fitted profiles of electron temperature and density from the NSTX Multi-Pulse Thomson Scattering (MPTS) diagnostic. CALLING SEQUENCE: PLOTTSwall,TS1[,TS2] INPUTS: TS1 = structure containing Thomson data for shot TS2 = structure containing Thomson data for second shot (optional) KEYWORDS: (INPUT) Tplot = vector of times to plot profiles (default = all times, multiple times: first time pt.) T2plot = plot times for second shot (default to first time of Tplot if not specified) /Plot_IP = if=0, do not have Ip plot on graph /NB = if set, add neutral beam power to time history plot /RF = if set, add HHFW power to time history plot /MHD = if set, add Mirnov trace to time history /Vloop = if set, add loop voltage to time history plot /Mld = if set, add microwave line density to time history /HA = if set, add hydrogen alpha signal to time history /USXR = if set, add ultra-soft x-ray signal to time history /Wmhd = if set, add EFIT Total energy (Wmhd) to time history /Tf = if set, add TF current to time history /Qmin = if set, add qmin to time history /Q95 = if set, add q95 to time history Temax = value of maximum Te to plot [ keV] Nemax = value of maximum Ne to plot [1e13 /cm^3] Pemax = value of maximum Pe to plot [kPa] Nelmax = value of maximum NeL to plot [1e15 /cm^2] Temin = value of minimum Te to plot [ keV] Nemin = value of minimum Ne to plot [1e13 /cm^3] Pemin = value of minimum Pe to plot [kPa] Nelmin = value of minimum NeL to plot [1e15 /cm^2] Big = make single large plot of : 1 - Te, 2 - Ne, 3 - Pe, 4 - time history /CHI = if set, changes plotting defaults to values appropriate to lower temperature plasmas /Nospline = set to connect data with straight lines instead of splines. Rrange = two element vector to set radial range of plot [Rmin, Rmax] Chrsz = sets size of characters in plot /Fancy = sets Font to Triplex Roman Tmax = set maximum value of time in plot Pk = set Te(t) to peak value of spline Efit = value of EFIT tree to use '1,2,3,4,5' (OUTPUT) Rescale = ratio of axis scales on time history plot Pt = actual times selected for profile plots P2t = actual time selected for second shot ADDITIONAL FEATURES: In the last plot, the time history of the line density from integrating the Thomson data is displayed as a series of solid symbols (circles). If multiple times are plotted, they are color coded to symbols on the line density plot. The time history of the central electron temperature is also plotted. When using multiple shots, data from the first shot will be plotted with solid lines, the second shot's data will be dashed. EXAMPLES: RESTRICTIONS: MODIFICATION HISTORY: 04-Jun-2013 add Plot_Ip keyword 13-Dec-2010 adjust shifts of colored labels for other device types 02-Aug-2010 color code Y-axes labels 30-Jul-2010 modified from plotts.pro by Bill Davis to pass _extra keyword on plot 4. Written by R. E. Bell, PPPL, 2000 Added CHI and NoSpline keywords, REB, 29-Aug-2001 Added Wmhd keyword, changed mhd scaling, REB, 26-Feb-2002 Updated TS function , REB, 31-Jan-2003 Modified treatement of MHD plot, REB, 31-Jan-2003 Modified to designate EFIT tree to use with EFIT keyword. REB 20-Oct-2003 Added X windows adjustment to 'Z' plot type, REB 17-Nov-2003 Fixed bugs in timing for multiple shots, REB 17-Nov-2003 Added keyword T2plot for selecting distinct time for second shot, REB 31-Mar-2006 Added valid array to ts function, REB 12-Dec-2008
NAME:
progressw
PURPOSE:
show progress bar until done, or the user clicks the STOP button.
USE:
customize for your use for progress indications.
CATEGORY:
Demo; Real Time applications
CALLING SEQUENCE:
IDL> done = progressw( seconds )
INPUTS:
seconds - total seconds for finish
KEYWORD PARAMETERS:
Optional:
print - if set, will print time elapsed
waitSeconds - seconds to wait (pause) after a timer event is fielded
default = 1/2 second.
xsize - length in pixels of progress bar
ysize - width in pixels of progress bar
group_leader - higher level widget to place this on top of
OUTPUTS:
done - 1, if time expired, or 0 if user hit STOP
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> done = ProgressW( 20 ) ; seconds expected for motor to run
IDL> IF NOT done THEN stopmotor
RELATED ROUTINE:
BarometerW
NOTES:
Only works on X.
MODIFICATION HISTORY:
19-Jul-00 Written by Bill Davis
NAME:
REMOVE
PURPOSE:
Contract a vector or up to 7 vectors by removing specified elements
CATEGORY:
Arrays
CALLING SEQUENCE:
REMOVE, index, v1,[ v2, v3, v4, v5, v6, v7]
INPUTS:
INDEX - scalar or vector giving the index number of elements to
be removed from vectors. Duplicate entries in index are
ignored. An error will occur if one attempts to remove
all the elements of a vector.
INPUT-OUTPUT:
v1 - Vector or array. Elements specifed by INDEX will be
removed from v1. Upon return v1 will contain
N fewer elements, where N is the number of values in
INDEX.
OPTIONAL INPUT-OUTPUTS:
v2,v3,...v7 - additional vectors containing
the same number of elements as v1. These will be
contracted in the same manner as v1.
EXAMPLES:
(1) If INDEX = [2,4,6,4] and V = [1,3,4,3,2,5,7,3] then after the call
IDL> remove,index,v
V will contain the values [1,3,3,5,3]
(2) Suppose one has a wavelength vector W, and three associated flux
vectors F1, F2, and F3. Remove all points where a quality vector,
EPS is negative
IDL> bad = where( EPS LT 0, Nbad)
IDL> if Nbad GT 0 then remove, bad, w, f1, f2, f3
METHOD:
If more than one element is to be removed, then HISTOGRAM is used
to generate a 'keep' subscripting vector. To minimize the length of
the subscripting vector, it is only computed between the minimum and
maximum values of the index. Therefore, the slowest case of REMOVE
is when both the first and last element are removed.
REVISION HISTORY:
Written W. Landsman ST Systems Co. April 28, 1988
Cleaned up code W. Landsman September, 1992
Converted to IDL V5.0 W. Landsman September 1997
Major rewrite for improved speed W. Landsman April 2000
NAME:
SIMP
PURPOSE:
Does Simpson numerical integration on an array of y values.
CATEGORY:
CALLING SEQUENCE:
i = simp(y, h)
INPUTS:
y = array of y values of function. in
h = separation between evenly spaced x values. in
KEYWORD PARAMETERS:
OUTPUTS:
i = value of integral. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 19 Dec, 1984.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1984, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
TABINV
PURPOSE:
To find the effective index of a function value in an ordered vector.
CALLING SEQUENCE:
TABINV, XARR, X, IEFF
INPUTS:
XARR - the vector array to be searched, must be monotonic
increasing or decreasing
X - the function value(s) whose effective
index is sought (scalar or vector)
OUTPUT:
IEFF - the effective index or indices of X in XARR
real or double precision, same # of elements as X
RESTRICTIONS:
TABINV will abort if XARR is not monotonic. (Equality of
neighboring values in XARR is allowed but results may not be
unique.) This requirement may mean that input vectors with padded
zeroes could cause routine to abort.
PROCEDURE:
A binary search is used to find the values XARR(I)
and XARR(I+1) where XARR(I) < X < XARR(I+1).
IEFF is then computed using linear interpolation
between I and I+1.
IEFF = I + (X-XARR(I)) / (XARR(I+1)-XARR(I))
Let N = number of elements in XARR
if x < XARR(0) then IEFF is set to 0
if x > XARR(N-1) then IEFF is set to N-1
EXAMPLE:
Set all flux values of a spectrum (WAVE vs FLUX) to zero
for wavelengths less than 1150 Angstroms.
IDL> tabinv, wave, 1150.0, I
IDL> flux( 0:fix(I) ) = 0.
NOTES:
Users of V5.3 or later can use a faster version of tabinv.pro
available at http://idlastro.gsfc.nasa.gov/ftp/v53/ which makes use of
the VALUE_LOCATE() intrinsic function.
FUNCTIONS CALLED:
ISARRAY()
REVISION HISTORY:
Adapted from the IUE RDAF January, 1988
More elegant code W. Landsman August, 1989
Mod to work on 2 element decreasing vector August, 1992
Converted to IDL V5.0 W. Landsman September 1997
NAME:
temidplanesep
PURPOSE:
Find the electron temperature at the midplane separatrix by
interpolating from NSTX MPTS data
CALLING SEQUENCE:
IDL> te = temidplanesep(shot, time )
INPUTS:
shot = NSTX shot number
time - seconds after T0 desired
KEYWORD PARAMETERS:
Inputs:
fit - fit to use to find separatrix (def='EFIT02')
sep - major radius (m) of the separatrix at the midplane for
this shot & time (will compute if not set)
plot - if set, will plot debug info
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
status - if odd, then success
OUTPUTS:
Te - electron temperature in KeV
EXAMPLE:
IDL> print, temidplanesep( 139442, time=0.29 )
0.013571366
NOTES:
Interpolates MPTS data (which might be only every 16 msec) to the
desired time, and then interpolates in space.
For the separatrix location (with a typical time base of 25 msec),
smooth by 3 and take the nearest point.
MODIFICATION HISTORY:
WRITTEN 29-Oct-2013 by Bill Davis, PPPL, for Stewart Zweben
NAME:
testcmd
PURPOSE:
test batch execution
CATEGORY:
Example, Batch
INVOCATION:
$ IDL runtestcmd.pro
Where runtestcmd.pro might contain:
testcmd, key='key input', file='newfile.txt'
exit
WRITTEN by Bill Davis, 23-Apr-99
NAME:
truns_get
PURPOSE:
List info (in a database) on NSTX TRANSP runs (to a screen or file)
CATEGORY:
TRANSP, Database
CALLING SEQUENCE:
IDL> truns_get, shotyear=shotyear, shotnumber=shotnumber, runID=runID, $
rundate=rundate, runby=runby, $
outFile=outFile
INPUTS:
(none required)
KEYWORD PARAMETERS:
(all optional)
shotyear - e.g., '2001'
shotnumber - e.g., 105535
runID - e.g., 01
rundate - run date (YYYYMMDD), e.g., 20010802
runby - person, e.g. 'KAYE'
outFile - string (if not present, data listed to screen)
OUTPUTS:
data to screen or file, if specified
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> truns_get, shotYear=2001 ; all 2001 NSTX TRANSP runs to screen
IDL> truns_get, rundate=20010911
MODIFICATION HISTORY:
25-May-2005 Switched double and single quotes in queries to work on RHEL.
30-Jan-2002 Written by Bill Davis, PPPL
Based on a program by Stan Kaye.
NAME:
TVIMAGE
PURPOSE:
This purpose of TVIMAGE is to enable the TV command in IDL
to be a completely device-independent and color-decomposition-
state independent command. On 24-bit displays color decomposition
is always turned off for 8-bit images and on for 24-bit images.
The color decomposition state is restored for those versions of
IDL that support it (> 5.2). Moreover, TVIMAGE adds features
that TV lacks. For example, images can be positioned in windows
using the POSITION keyword like other IDL graphics commands.
TVIMAGE also supports the !P.MULTI system variable, unlike the
TV command. TVIMAGE was written to work especially well in
resizeable graphics windows. Note that if you wish to preserve
the aspect ratio of images in resizeable windows, you should set
the KEEP_ASPECT_RATIO keyword, described below. TVIMAGE works
equally well on the display, in the PostScript device, and in
the Printer and Z-Graphics Buffer devices. The TRUE keyword is
set automatically to the correct value for 24-bit images, so you
don't need to specify it when using TVIMAGE.
AUTHOR:
FANNING SOFTWARE CONSULTING:
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Graphics display.
CALLING SEQUENCE:
TVIMAGE, image
INPUTS:
image: A 2D or 3D image array. It should be byte data.
x : The X position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
If the Y position is not used, X is taken to be the image
"position" in the window. See the TV command documenation
for details.
y : The Y position of the lower-left corner of the image.
This parameter is only recognized if the TV keyword is set.
KEYWORD PARAMETERS:
BACKGROUND: This keyword specifies the background color. Note that
the keyword ONLY has effect if the ERASE keyword is also
set or !P.MULTI is set to multiple plots and TVIMAGE is
used to place the *first* plot.
ERASE: If this keyword is set an ERASE command is issued
before the image is displayed. Note that the ERASE
command puts the image on a new page in PostScript
output.
_EXTRA: This keyword picks up any TV keywords you wish to use.
HALF_HALF: If set, will tell CONGRID to extrapolate a *half* row
and column on either side, rather than the default of
one full row/column at the ends of the array. If you
are interpolating images with few rows, then the
output will be more consistent with this technique.
This keyword is intended as a replacement for
MINUS_ONE, and both keywords probably should not be
used in the same call to CONGRID.
KEEP_ASPECT_RATIO: Normally, the image will be resized to fit the
specified position in the window. If you prefer, you can
force the image to maintain its aspect ratio in the window
(although not its natural size) by setting this keyword.
The image width is fitted first. If, after setting the
image width, the image height is too big for the window,
then the image height is fitted into the window. The
appropriate values of the POSITION keyword are honored
during this fitting process. Once a fit is made, the
POSITION coordiates are re-calculated to center the image
in the window. You can recover these new position coordinates
as the output from the POSITION keyword.
MARGIN: A single value, expressed as a normalized coordinate, that
can easily be used to calculate a position in the window.
The margin is used to calculate a POSITION that gives
the image an equal margin around the edge of the window.
The margin must be a number in the range 0.0 to 0.333. This
keyword is ignored if the POSITION or OVERPLOT keywords are
used. It is also ignormed when TVImage is executed in a
multi-plot window, EXCEPT if it's value is zero. In this
special case, the image will be drawn into its position in
the multi-plot window with no margins whatsoever. (The
default is to have a slight margin about the image to separate
it from other images or graphics.
MINUS_ONE: The value of this keyword is passed along to the CONGRID
command. It prevents CONGRID from adding an extra row and
column to the resulting array, which can be a problem with
small image arrays.
NOINTERPOLATION: Setting this keyword disables the default bilinear
interpolation done to the image when it is resized. Nearest
neighbor interpolation is done instead. This is preferred
when you do not wish to change the pixel values of the image.
This keyword must be set, for example, when you are displaying
GIF files that come with their own non-IDL color table vectors.
NORMAL: Setting this keyword means image position coordinates x and y
are interpreted as being in normalized coordinates. This keyword
is only valid if the TV keyword is set.
OVERPLOT: Setting this keyword causes the POSITION keyword to be ignored
and the image is positioned in the location established by the
last graphics command. For example:
Plot, Findgen(11), Position=[0.1, 0.3, 0.8, 0.95]
TVImage, image, /Overplot
POSITION: The location of the image in the output window. This is
a four-element floating array of normalized coordinates of
the type given by !P.POSITION or the POSITION keyword to
other IDL graphics commands. The form is [x0, y0, x1, y1].
The default is [0.0, 0.0, 1.0, 1.0]. Note that this can
be an output parameter if the KEEP_ASPECT_RATIO keyword is
used.
TV: Setting this keyword makes the TVIMAGE command work much
like the TV command, although better. That is to say, it
will still set the correct DECOMPOSED state depending upon
the kind of image to be displayed (8-bit or 24-bit). It will
also allow the image to be "positioned" in the window by
specifying the coordinates of the lower-left corner of the
image. The NORMAL keyword is activated when the TV keyword
is set, which will indicate that the position coordinates
are given in normalized coordinates rather than device
coordinates.
Setting this keyword will ensure that the keywords
KEEP_ASPECT_RATIO, MARGIN, MINUS_ONE, MULTI, and POSITION
are ignored.
OUTPUTS:
None.
SIDE EFFECTS:
Unless the KEEP_ASPECT_RATIO keyword is set, the displayed image
may not have the same aspect ratio as the input data set.
RESTRICTIONS:
If the POSITION keyword and the KEEP_ASPECT_RATIO keyword are
used together, there is an excellent chance the POSITION
parameters will change. If the POSITION is passed in as a
variable, the new positions will be returned in the same variable
as an output parameter.
If a 24-bit image is displayed on an 8-bit display, the
24-bit image must be converted to an 8-bit image and the
appropriate color table vectors. This is done with the COLOR_QUAN
function. The TVIMAGE command will load the color table vectors
and set the NOINTERPOLATION keyword if this is done. Note that the
resulting color table vectors are normally incompatible with other
IDL-supplied color tables. Hence, other graphics windows open at
the time the image is display are likely to look strange.
EXAMPLE:
To display an image with a contour plot on top of it, type:
filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
image = BYTARR(360,360)
OPENR, lun, filename, /GET_LUN
READU, lun, image
FREE_LUN, lun
TVIMAGE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10
To display four images in a window without spacing between them:
!P.Multi=[0,2,2]
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
TVImage, image, Margin=0
!P.Multi = 0
MODIFICATION HISTORY:
Written by: David Fanning, 20 NOV 1996.
Fixed a small bug with the resizing of the image. 17 Feb 1997. DWF.
Removed BOTTOM and NCOLORS keywords. This reflects my growing belief
that this program should act more like TV and less like a "color
aware" application. I leave "color awareness" to the program
using TVIMAGE. Added 24-bit image capability. 15 April 1997. DWF.
Fixed a small bug that prevented this program from working in the
Z-buffer. 17 April 1997. DWF.
Fixed a subtle bug that caused me to think I was going crazy!
Lession learned: Be sure you know the *current* graphics
window! 17 April 1997. DWF.
Added support for the PRINTER device. 25 June 1997. DWF.
Extensive modifications. 27 Oct 1997. DWF
1) Removed PRINTER support, which didn't work as expected.
2) Modified Keep_Aspect_Ratio code to work with POSITION keyword.
3) Added check for window-able devices (!D.Flags AND 256).
4) Modified PostScript color handling.
Craig Markwart points out that Congrid adds an extra row and column
onto an array. When viewing small images (e.g., 20x20) this can be
a problem. Added a Minus_One keyword whose value can be passed
along to the Congrid keyword of the same name. 28 Oct 1997. DWF
Changed default POSITION to fill entire window. 30 July 1998. DWF.
Made sure color decomposition is OFF for 2D images. 6 Aug 1998. DWF.
Added limited PRINTER portrait mode support. The correct aspect ratio
of the image is always maintained when outputting to the
PRINTER device and POSITION coordinates are ignored. 6 Aug 1998. DWF
Removed 6 August 98 fixes (Device, Decomposed=0) after realizing that
they interfere with operation in the Z-graphics buffer. 9 Oct 1998. DWF
Added a MARGIN keyword. 18 Oct 1998. DWF.
Re-established Device, Decomposed=0 keyword for devices that
support it. 18 Oct 1998. DWF.
Added support for the !P.Multi system variable. 3 March 99. DWF
Added DEVICE, DECOMPOSED=1 command for all 24-bit images. 2 April 99. DWF.
Added ability to preserve DECOMPOSED state for IDL 5.2 and higher. 4 April 99. DWF.
Added TV keyword to allow TVIMAGE to work like the TV command. 11 May 99. DWF.
Added the OVERPLOT keyword to allow plotting on POSITION coordinates
estabished by the preceding graphics command. 11 Oct 99. DWF.
Added automatic recognition of !P.Multi. Setting MULTI keyword is no
longer required. 18 Nov 99. DWF.
Added NOINTERPOLATION keyword so that nearest neighbor interpolation
is performed rather than bilinear. 3 Dec 99. DWF
Changed ON_ERROR condition from 1 to 2. 19 Dec 99. DWF.
Added Craig Markwardt's CMCongrid program and removed RSI's. 24 Feb 2000. DWF.
Added HALF_HALF keyword to support CMCONGRID. 24 Feb 2000. DWF.
Fixed a small problem with image start position by adding ROUND function. 19 March 2000. DWF.
Updated the PRINTER device code to take advantage of available keywords. 2 April 2000. DWF.
Reorganized the code to handle 24-bit images on 8-bit displays better. 2 April 2000. DWF.
Added BACKGROUND keyword. 20 April 2000. DWF.
Fixed a small problem in where the ERASE was occuring. 6 May 2000. DWF.
Rearranged the PLOT part of code to occur before decomposition state
is changed to fix Background color bug in multiple plots. 23 Sept 2000. DWF.
Removed MULTI keyword, which is no longer needed. 23 Sept 2000. DWF.
Fixed a small problem with handling images that are slices from 3D image cubes. 5 Oct 2000. DWF.
Added fix for brain-dead Macs from Ben Tupper that restores Macs ability to
display images. 8 June 2001. DWF.
Fixed small problem with multiple plots and map projections. 29 June 2003. DWF.
Converted all array subscripts to square brackets. 29 June 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Small modification at suggestion of Karsten Rodenacker to increase size of
images in !P.MULTI mode. 8 December 2004. DWF.
Minor modifications on Karsten Rodenacker's own account concerning margination
and TV behaviour. 8 December 2004. KaRo
NAME:
updateNstxStatus
PURPOSE:
Update the NSTX Status Web page
CATEGORY:
Web, NSTX
CALLING SEQUENCE:
IDL> updateNstxStatus, outTxt=outTxt, headline=headline, username=username, $
Output='UpdateWith', YourEmail='', PagePassword='',
INPUT KEYWORDS:
Required:
outTxt - status of NTX, can be up to 20 lines
headline - a one-line Summary of status
username - name of person making update (for email); can be followed by (Real Name)
Optional:
WithEmail - if 'no', will not send email
EmailAddress - where to send e-mail. Defaults to '830 Meeting'
PagePassword - if e-mail is sent, this is required
outFile - web page, DEFAULT='/w/nstx.pppl.gov/htdocs/nstx/Software/nstxstatus.html'
maxLength - max length of status field
title - title of information. DEFAULT='NSTX Status:'
XMLfile - name of XML file for RSS News Feeds,
DEFAULT='/w/nstx.pppl.gov/htdocs/nstx/Software/nstxstatus.xml'
logfile - name of log file.
DEFAULT='/local/nstxops/web/log/updateNstxStatus.log'
debug - if set prints debugging info
verbose - if set prints lots of info
status - if odd, successful
OUTPUTS:
writes an html file, ntsxstatus.html, to a web-accessible directory.
Also can email specified recipients.
METHOD:
Gets data for fields (like outTxt) to be updated from updatenstxstatus.html
(via idlMDSPlotServer2550.pl) and creates the web page nstxstatus.html (by
writing the HTML from this IDL routine).
So people can receive automatic updates, an XML file is created for
linking an RSS feed to:
the java script, refresh.js, by Peter Gehrig and Urs Dudli, is used for
refreshing nstxstatus.html
COMMON BLOCKS:
NONE
EXAMPLE:
(this is usually called from the nstxupdatestatus.html web page via a
perl script)
IDL> updatenstxstatus, outTxt='NSTX is down', WithEmail='yes', $
username='bdavis', PagePassword='Masa', /debug
MODIFICATION HISTORY:
20-Jul-2011 Changed URL for COE logbook, per Paul Sichta
07-Jan-2009 need some blank lines in PNG file for Firefox to show all.
13-Aug-2008 Add a Headline field. Update XML file with content.
08-Aug-2008 Written by Bill Davis, PPPL
NAME:
VT100
PURPOSE:
Define the TEK and VT100 commands for use in IDL. Especially
useful for MAC users who use Versaterm or users who otherwise
want to do Tektronix plots while connected to their UNIX
platform of choice.
CATEGORY:
Misc
CALLING SEQUENCE:
VT100
INPUT PARAMETERS:
NONE
OPTIONAL INPUT PARAMETERS:
NONE
KEYWORDS:
NONE
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
SIDE EFFECTS:
NONE
RESTRICTIONS:
If you want to use the TEK command, you need to issue the VT100
command first.
PROCEDURE:
CODE TYPE: modeling, analysis, control
CODE SUBJECT: operation, handling, edge, rf, transport, equilibrium
EASE OF USE: can be used with existing documentation
OPERATING SYSTEMS: UNIX of all flavors
EXTERNAL CALLS: NONE
RESPONSIBLE PERSON: Ray Jong
DATE OF LAST MODIFICATION: 01/19/99
MODIFICATION HISTORY:
Created by Michael D. Brown, LLNL
NAME:
whichComputer
PURPOSE:
Return name of Linux computer you are running on.
First uses enironmental variable HOST, then uname -n
CATEGORY:
System
CALLING SEQUENCE:
IDL> computerName = whichComputer( )
INPUTS:
none required
KEYWORD PARAMETERS:
var - Environmental variable to check for computer name.
(defaults to 'HOST'). If HOST not defined, will still work on Linux
debug - if set, debug output will be printed
OUTPUTS:
computerName - name of computer (best not to have domain included)
EXAMPLE:
NOTES:
MODIFICATION HISTORY:
07-Apr-2010 Written by Bill Davis, PPPL
NAME:
writecamavg
PURPOSE:
For camera files that exist for a particular shot, check for
\CAMERAS::TOP.FC_n.RAWDATA:FRAMES_MAX and \CAMERAS::TOP.FC_n.RAWDATA:FRAMES_AVG
(tags \PH7_n_FMAX and \PH7_n_FAVG) and write them if need be.
CALLING SEQUENCE:
IDL> writecamavg, camera, year=year, shot1=shot1, shot2=shot2
INPUTS:
camera = integer from 1-7
KEYWORDS:
year - if shot1 and shot2 not entered, use this. (Defaults to current year)
shot1
shot2
tree - defaults to 'cameras'
checkDir - if set, will work from a list of the expected directory, rather
than calling FindCamFiles for every file (recommended)
writeMax - if not = 0, will try write max intensity vs. time waveforms
writeAve - if not = 0, will try write ave intensity vs. time waveforms
force - if=1, will write maxInt and aveInt, even if they are in the tree
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
EXAMPLE:
IDL> writeCamAvg, 2, year=2010, /checkDir, /debug
; rewrite max for some shots:
IDL> writeCamAvg, 7, shot1=139025, shot2=140569, /force, writeAve=0, /checkDir, /debug
IDL> writeCamAvg, 2, shot1=140528, shot2=140569, /checkDir, /verb
MODIFICATION HISTORY:
---------------------
27-Jul-2011 option to just use a file_search of conventional directory when checking
for files (keyword CheckDir)
25-Jul-2011 Written by Bill Davis
NAME: X_COMPLAIN
PURPOSE: Pops up a one line complaint.
CATEGORY:
MDS-Widgets
CALLING SEQUENCE:
X_COMPLAIN,message
INPUTS:
message - text to display
COMMON BLOCKS:
None.
SIDE EFFECTS:
PROCEDURE:
MODIFICATION HISTORY:
NAME:
XY2RmRsep
PURPOSE:
transform pixel locations (say, from a Fast 2-D Camera image)
to distance from the Separatrix and distance along field line
parallel to flux lines
CATEGORY:
Plasma Analysis
CALLING SEQUENCE:
IDL> XY2RmRsep, shot, time, RmRsep, DistAlong
INPUTS:
shot = NSTX or CMOD shot number
time = time in seconds after shot for which values are desired
KEYWORD PARAMETERS:
Inputs:
fit - EFIT/LRDFIT indication, e.g., EFIT02
timeOffset - time to add to input time to be consistant with EFIT time
show - if set, plot, separatrix, and distance values
nx = # of pixels in X direction (default=64)
ny = # of pixels in Y direction (default=64 if shot # for CMOD, else 80)
cm - if set, distances will be in centimeters, rather than pixels
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
status - if odd, then success
OUTPUTS:
RmRsep - distance from the Separatrix in pixels
DistAlong - distance along field line from lower left, in pixels
EXAMPLE:
IDL> time = .2 ; in seconds
IDL> shot = 1100824017
IDL> shot = 138234
IDL> XY2RmRsep, shot, time, RmRsep, DistAlong
MODIFICATION HISTORY:
WRITTEN 21-Jun-2012 by Bill Davis, PPPL, for Stewart Zweben
Category: NSTX
[List of Routines]
NAME:
nstxcorner
PURPOSE:
write NSTX in upper left-hand corner of a plot
CATEGORY:
NSTX, Plotting
CALLING SEQUENCE:
IDL> nstxcorner
MODIFICATION HISTORY:
21-Aug-00 Written by Bill Davis, PPPL
NAME:
nstxlogo
PURPOSE:
draw NSTX logo in upper left-hand corner of a plot
CATEGORY:
NSTX, Plotting
CALLING SEQUENCE:
IDL> nstxlogo
KEYWORD PARAMETERS:
Optional Keywords:
CHARSIZE -Character size of NSTX characters (def=1.5)
XLOC - X location of middle of logo, in normal coordinates
YLOC - Y location of middle of logo, in normal coordinates
iBar - if set, draw center stack as an "I" rather than ")("
right -if set, drawn on the right
blue - if set, color table value for NSTX text
red - if set, color table value for bars and circles
bottom - if set, drawn on the bottom
EXAMPLE:
IDL> !y.omargin=[0,1.5]
IDL> plot,indgen(11)
IDL> nstxlogo
LIMITATONS:
This was designed to work with the default IDL font (-1).
NOTES:
You will probably want to leave extra room at the top of your plot, e.g.
IDL> !y.omargin=[0,1.5]
MODIFICATION HISTORY:
30-Jan-2015 use NSTX-U if shot number > 144500
18-Dec-2009 Added Center keyword
25-Feb-03 Made circles same font as others
14-May-01 Changed the look - no X.
01-Nov-00 Cleaned up location. Default size to 1.5
21-Aug-00 Written by Bill Davis, PPPL
NAME:
nstxlogs_get
PURPOSE:
Get info on NSTX shots from the ENTRIES table in the NSTXLOGS database
CATEGORY:
NSTX, Database
CALLING SEQUENCE:
IDL> info = nstxlogs_get(shot=shot, rundate=rundate, username=username, $
xp=xp )
INPUTS:
(none required)
KEYWORD PARAMETERS:
(all optional)
rundate - run date (YYYYMMDD), e.g., 20010802
shot - e.g., 105535
text - text that is contained in the entry
topic - per Logbook, e.g., "SESSION LEADER", "PHYS OPS", "CHI", "EFIT", "IMPURITIES"
'MAGNETCIS" ETC.
username - person, e.g. 'KAYE'
xp - Experimental proposal number, e.g., 917
(see http://nstx.pppl.gov/nstx/Software/WebTools/shotlists.html)
outFile - string (if not present, data listed to screen)
quiet - if set, will not print things to screen
status - if an even number, then there was a problem.
OUTPUTS:
info - structure containing columns from ENTRIES table
data to screen or file, if desired
NOTES:
Will need red permission for NSTX databases (send email request to
dbadmin) and sybase files. Source /p/nstxusr/util/setup/mkmdsplusdbfile.csh
EXAMPLE:
IDL> info = nstxlogs_get( shot=130000 )
IDL> info = nstxlogs_get( rundate=20060621 )
MODIFICATION HISTORY:
17-Sep-2009 Written by Bill Davis, PPPL
NAME:
nstx_xp
PURPOSE:
return the NSTX XP for an NSTX shot
CATEGORY:
NSTX, Database
CALLING SEQUENCE:
IDL> xp = nstx_xp( shot )
INPUTS:
shot - e.g., 105535
KEYWORD PARAMETERS:
none
OUTPUTS:
xp - Experimental proposal associated with shot
NOTES:
Will need read permission for NSTX databases (send email request to
dbadmin) and sybase files. Execute /p/nstxusr/util/setup/mkmdsplusdbfile.csh
EXAMPLE:
IDL> print, nstx_xp( 130000 )
829
MODIFICATION HISTORY:
17-Sep-2009 Written by Bill Davis, PPPL
NAME:
plot1sig
PURPOSE:
plot 1 NSTX signal for many shots stacked vertically
CATEGORY:
NSTX, X-Y Plotting, MDSplus
EXAMPLE:
IDL> shots = [ 111827, 111875, 111876, 112075, 112137 ]
IDL> signame = '\wf::ip'
IDL> plot1sig, shots, signame=signame
IDL>
Post script version:
IDL> shots=[112175,112171,112172]
IDL> !p.charsize=1.7
IDL> setup_ps, file='dalf.ps', printer='postscript'
IDL> device,set_font='Helvetica'
IDL> signames='\passivespec::bayc_dalf_haifa'
IDL> plot1sig,shots,0.,.6,signames=signames,tweenspace=.05
IDL> unsetup_ps
MODIFICATION HISTORY:
19-May-2004 Added _extra keyword and fixed ymaxes bug
19-Apr-2004 Written by Bill Davis for Stan Kaye
NAME: plot7 PURPOSE: plot 7 (or any number) NSTX signals on the same x-axis CATEGORY: NSTX, X-Y Plotting, MDSplus USE: IDL> plot7, shot [, t1, t2] to make 5 plots of same signal and different shots: IDL> shots = [ 111827, 111875, 111876, 112075, 112137 ] IDL> plot1sig,shots,signame='\wf::ip' KEYWORDS: all optional, but you won't like the defaults :-) signames labels units scale ymins ymaxes tweenspace - fraction of screen between plots in vertical nospace - if set, overrides tweenspace to make plots abut vertically MODIFICATION HISTORY: 19-May-2004 Added _extra keyword & don't reverse incoming shot list 19-Apr-2004 Added support for many shots, and one signal. 11-Jan-01 Added ymin & ymax and made variables optional keywords 06-Oct-00 Written by Bill Davis for Franco Paoletti
Category: Plotting
[List of Routines]
NAME:
betterticklabels
PURPOSE:
Tick labels are made a little cleaner. E.g., shorter exponentials,
no unnecessary trailing zeroes, accurate numbers when tick values
are small differences between large numbers, etc.
CATEGORY:
Plotting, Graphics
EXAMPLE:
IDL> plot, y, ytickformat='betterticklabels'
EXAMPLE A - Make a dummy plot call so can determine Tick Max:
IDL> COMMON betterticklabels_common, yticklabels
IDL> plot, y, ytick_get=yticklabels, ytickname=replicate(' ',30)
IDL> AXIS, YAXIS=1, YRANGE=!y.crange, ytickformat='betterticklabels'
IDL> dum = TEMPORARY(yticklabels) ; so doesn't affect later calls
HISTORY:
03-Mar-2008 slight mod to handle floating point comparison
03-Aug-2006 fixed for values less than 2.e-6
15-Apr-04 be able to return xtick values and x tic labels (NOT DEBUGGED)
15-Oct-01 shift y axis labels if !p.font=0 (helps with some 3-D plots)
11-Jan-01 shift y-axis labels if on TEK and !p.font=0
09-Oct-00 Written by Bill Davis
NAME:
CLEANPLOT
PURPOSE:
Reset all system variables (!P,!X,!Y,!Z) to their default values
CATEGORY:
Plotting
EXPLANATION:
Reset all system variables (!P,!X,!Y,!Z) which are set by the user
and which affect plotting to their default values.
CALLING SEQUENCE:
Cleanplot
INPUTS:
None
OUTPUTS:
None
SIDE EFFECTS:
The system variables that concern plotting are reset
to their default values. A message is output for each
variable changed. The CRANGE, S, WINDOW, and REGION fields of the
!X, !Y, and !Z system variables are not checked since these are
set by the graphics device and not by the user.
PROCEDURE:
This does NOT reset the plotting device.
This does not change any system variables that don't control plotting.
RESTRICTIONS:
If user default values for !P, !X, !Y and !Z are different from
the defaults adopted below, user should change P_old etc accordingly
MODIFICATION HISTORY:
Written IDL Version 2.3.0 W. Landsman & K. Venkatakrishna May '92
Handle new system variables in V3.0.0 W. Landsman Dec 92
Assume user has at least V3.0.0 W. Landsman August 95
V5.0 has 60 instead of 30 TICKV values W. Landsman Sep. 97
Change !D.N_COLORS to !D.TABLE_SIZE for 24 bit displays
W. Landsman April 1998
NAME:
CLEARPLT
PURPOSE:
This procedure will clear or zero all or a selection
of the system plot variables
CATEGORY:
Plotting
CALLING SEQUENCE:
clearplt,/all ;clear the !p, !x, !y, !z
clearplt,/x,/z ;clear the !x and !z variables
clearplt,/x ;only clear the !x variable
clearplt,/x,/invert ;clear all except the !x
INPUTS:
KEYWORDS:
x,y,z,p = clear the appropriate variable
all = clear all, this is equivalent to /x,/y,/z,/p
invert = invert the logic. Clear all unselected variables.
Therefore "clearplt,/all,/invert" does nothing.
OUTPUTS: none
COMMON BLOCKS:
none.
SIDE EFFECTS:
The sytem plot variables are changed.
MODIFICATION HISTORY:
20-Apr-99 [BD] more things cleared for !P
Written by: Trevor Harris, Physics Dept., University of Adelaide,
July, 1990.
NAME:
compw
PURPOSE:
Plot two signals and the difference.
CATEGORY:
Plotting
CALLING SEQUENCE:
compw
compw, xsize=800, ysize=600
compw, shot=120200, sig1='\wf::ipf2l', sig2='\wf::ipf2u'
compw, shot=120200
compw,sig1='\operations::bdot_l1dmivvhn1_raw',shot=110091, $
t1=.4, t2=.41
COMMON BLOCKS:
USE:
NOTES:
Your display may have to be set to 256 colors to see the crosshairs.
see http://w3.pppl.gov/~pshare/help/xtc.htm to setup XTC.
LIMITATIONS:
You need IDL version 5, or greater to run this application.
MODIFICATION HISTORY:
03-Dec-2007 read widget fields when plot button clicked. Reset cross-hair
dimensions when window resized
29-Nov-2007 Change plot & oplot to vplot & voplot [BD]
08-May-2003 Created from FireTips test [BD]
NAME:
fancy_title
PURPOSE:
write a title at top of screen, with option to use Hershey fonts
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> fancy_title, mytitle
INPUTS:
mytitle = whatever you want as the main plot title.
KEYWORD PARAMETERS:
Keywords:
right - When set, print at right of screen (else center)
fancy - if set, use Hershey fonts
line - if set, drop the title down by this number of lines.
bottom - if set, at bottom of screen (else top)
yloc - location of text in pixels
xloc - location of text in pixels
nudgeup - fraction of a line to nudge up title in Y direction
charcolor
charsize
charthick
OUTPUTS:
none
EXAMPLE:
IDL> !Y.OMARGIN=[0,1]
IDL> plot,indgen(100)
IDL> fancy_title, 'This is my title'
NOTES:
You'll probably want a little more room at the top of your plots, e.g.
IDL> !Y.OMARGIN=[0,1]
MODIFICATION HISTORY:
11-Jun-2010 added nudgeUp keyword
19-Sep-2008 reduce font size if title won't fit on screen
21-Sep-00 Written by Bill Davis, PPPL
NAME:
GA_PlotW
PURPOSE:
Plot widget for "table" of data, or input X & Y arrays.
CATEGORY:
Plotting, GA Plot Objects
KEYWORDS:
indicesPlot - indices to plot (plot if =1).
Same 1st dimension as Y (if Y is 2-D)
if just 1 dimension, and Y is two, use same mask for
all y's.
psym - many options. psym=7 is no symbols
0 is circle
1 is square
2 is diamond
3 is triangle
4 is upside down triangle
5 is 4-point star
6 is 5-point star
color - can be an index 0-255, or common color name, like 'red'
linestyle
xrange
yrange
PlotLabels
xtitle
ytitle
title
xsize
ysize
flagLegend - if=0, do not make a legend
EXAMPLE:
objRef = GA_PlotW( xdata=indgen(5), ydata=[1,3,5,4,2] )
or
table=strarr(3,8)
table[0,*]= ['time','0.01','0.02','0.03','0.04','0.05','0.06','0.07']
table[1,*]= ['Ip', '1.0', '1.1', '1.3', '1.6', '1.6', '1.5', '1.3' ]
table[2,*]= ['Bt', '.7', '.71', '.73', '.76', '.75', '.65', '.59' ]
objRef = GA_PlotW( table=table )
or
objRef = GA_PlotW(table=['Bt', '.7', '.71', '.73', '.76'] )
or to make a scatter plot with a y=y line through it:
x=findgen(100)
noise = randomn(seed,100)*(x+20)/10
y=(x+noise ) > 0
objRef = GA_PlotW( xdata=x, ydata=transpose([[y],[x]]), plotnum=[0,0], $
psymbol=[10,7], linestyle=[6,0] )
LIMITATIONS:
"Marking" points on a plot will select correspongind row in table,
if called "properly," as from plotdef__define.pro, but this only works
for the last table created.
MODIFICATION HISTORY
28-Jul-2011 enhanced keywords, like color and psym.
21-Mar-2003 Allow for indices array to plot different xranges.
(Can then have different ranges have different colors, etc.)
10-Dec-2002 Written by Bill Davis. Based on various object-oriented
plotting codes from General Atomics.
NAME:
getpos
PURPOSE:
Get the values for the POSITION keyword after a plot
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> pos = getpos()
INPUTS:
KEYWORD PARAMETERS:
Inputs:
window - window wanted
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
pos = position returned
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> plot, indgen(100)
IDL> pos = getpos( )
NOTES:
MODIFICATION HISTORY:
20-Mar-2013 Written by Bill Davis, PPPL
NAME:
gridplot
PURPOSE:
Widget for plotting a grid of data from MDSplus or gadat
This is an interactive version of ShotLoop.
If at GA, assume that access will be through gadat only.
When a plot on the grid is clicked on, it is expanded into a
separate window.
CATEGORY:
Plotting, MDSplus, Example, GA
CALLING SEQUENCE:
IDL> gridplot
or IDL> gridplot,tmin=2000,tmax=2002, SigFileName='mysigs.txt'
INPUTS:
none required
FILES:
lastshot.txt - if this file (or that specified by ShotFileName
keyword) is found, will initilize shot number
to that read from the first line of this file.
If this file can not be found in the directory from
which you are running, or in the IDL_PATH,
the initial shot number will be set to the current
machine shot minus 3.
mdsplussig.txt - if this file (or that specified by SigFileName
keyword) is found, will read signalnames from it
KEYWORD PARAMETERS:
Optional Keywords:
nSmooth - smoothing parameter to use when plotting data
nRows - # of rows of plots (default to 6)
nCols - # of colomns of plots (default to # signals/nrows)
printer - printer to send plots to (else goes to the default printer)
tmin - default plotting minimum for x-axis. (MDS in sec; GA in msec)
tmax - default plotting maximum for x-axis.
ShotFileName - File for storint last shot processed
(default: lastshot.txt)
SigFileName - Signal names in the file will be plotted
when you click on "Plot All." The names
should be one per row (default='mdsplusssig.txt')
sizeofplot - (2-element Real Array) x & y size of graphics area on widget
(but you are forced to stay on the screen).
OUTPUTS:
none from routine
COMMON BLOCKS:
gp_SetupParams, gp_Info, gp_GridData, gp_widgetIDs
EXAMPLE:
MAJOR FUNCTIONS and PROCEDURES:
PLOT: X-Y plotting.
NOTES:
PlotOne and PlotSomething
are routines shared in common with ShotLoop.
MODIFICATION HISTORY: Written by: WMD, PPPL, April, 1999
for Hiro Takahashi work at General Atomics
NAME:
keybrdanim
PURPOSE:
Animate frames of plots with keyboard controls.
Plot commands can be passed into the routine.
By default a vertical dashed red line shows the time.
Keyboard controls over animation:
'H': See this Help
'P' or : Toggle Pause
'C': Continue
'F': Faster
'S': Slower
'R' or '>' or : move forward 1 frame
'L' or '<' or : move backward 1 frame
'J' or : Jump forward 10 frames
'B' or : move backward 10 frames
'M': Mouse-click time desired
'Q': to quit
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> keybrdanim, x, y
INPUTS:
x - abscissa array for plotting
y - ordinate array for plotting
KEYWORD PARAMETERS:
Inputs:
plotCmd - a string array to execute. To have something indexed by the loop
variable, use iFr.
Defaults to:
["PLOT, x, y, _extra=_extra", $
"OPLOT, [x[ifr], x[ifr]], !y.crange, line=2, color=cs.red"]
nframes - # of points to plot. Defaults to # of points in X
plotCmd - a string array of plot commands. Defaults to
xsize - horizontal size of plot window, Default = 640
ysize - vertical size of plot window, Default = 480
pauseInit - Initial time to pause between frames. Default = 0.2
loops - # of times to loop through the animation. Default = 10
load - if set, will call mk_color to load colors. Default = 1.
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
any other keywords will be passed to the PLOT command via the _extra keyword.
OUTPUTS:
none (just plot window)
EXAMPLE:
IDL> cmd =["PLOT, x, y, xtitle='Sec', title='plot title'", $
"OPLOT, [x[ifr], x[ifr]], !y.crange, line=2, color=colorsearch('red')", $
"xyouts, .12, 0.92, 'Shot 999999', /norm, charsize=2"]
IDL> keybrdanim, x, y, plotCmd=cmd
NOTES:
The Z-buffer is used for plotting and then results copied to plot window for
for smooth animations.
MODIFICATION HISTORY:
19-Jul-2010 Written by Bill Davis
NAME:
labeleveryothertick
PURPOSE:
Only label every other major tic mark.
The format of the numbers is customized.
CATEGORY:
Plotting, Graphics
EXAMPLE 1 - Make a dummy plot call so can determine Tick Max:
IDL> COMMON betterticklabels_common, yticklabels
IDL> plot, y, ytick_get=yticklabels, ytickname=replicate(' ',30)
IDL> AXIS, YAXIS=1, YRANGE=!y.crange, ytickformat='labeleveryothertick'
IDL> dum = TEMPORARY(yticklabels) ; so doesn't affect later calls
EXAMPLE 2 - Just take what you get (still pretty good):
IDL> plot, y, ytickformat='labeleveryothertick'
HISTORY:
09-Oct-00 Written by Bill Davis
NAME:
linesout
PURPOSE:
Write lines out to an X window. Works like xyouts, but uses
line #'s (from the top) and /right if you want to right justify text.
CATEGORY:
Plotting, Strings
CALLING SEQUENCE:
IDL> linesout, text, line=line
INPUTS:
text - text string to write to window
KEYWORD PARAMETERS:
line - line # location, starting with 1 at the top (default=1)
right - if set, text will be right-justified, rather than left
center - if set, will center line (default to left justify).
charsize - character size of text (default to !p.charsize or 1)
dropshadow - if set, make a drop shadow of thick=3 text
thickDropShadow - thickness of drop shadow (default to 1, or 2 if /highlight)
color - color of text
dscolor - color of drop-shadow text (defaults to black or white)
bottom - if set, write lines from bottom, instead of top.
OUTPUTS:
none
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> !p.color=mk_color('black')
IDL> !p.backround=mk_color('white')
IDL> plot,indgen(11)
IDL> linesout, 'Hi Mom', line=2, /right, /dropshadow, charsize=2, $
color=mk_color('black'), dscolor=mk_color('red')
NOTES:
MODIFICATION HISTORY:
24-Oct-2006 added bottom, xpos, ypos, thickDropShadow, & highlight keyword
25-Aug-2005 Written by Bill Davis, PPPL
NAME:
mplottitle
PURPOSE:
write a plot title with NSTX label and a list of shots on left
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> mplottitle, screenTitle, shots, HLP=hlp, $
COLORS=colors, LOGO=logo, $
CHARMAG=charMag, TopMargin=TopMargin, RIGHT=right, $
INSIDE=inside, XPOS=xPos
INPUTS:
screenTitle = whatever you want as the main plot title.
shots = array of shot numbers.
KEYWORD PARAMETERS:
HLP - When set, help information is printed.
colors - color indices of each shot number (default = !p.color)
logo - Characters to draw above shot list. Default = '=NSTX=
TopMargin - in characters, extra space to shift down the characters
right - if set, labels put on left
inside - if set, lists shots inside plot box
xPos - xPos, in Device Coordinates, for left side of shot list
(overrides /RIGHT & /INSIDE)
OUTPUTS:
none
COMMON BLOCKS:
NONE
EXAMPLES:
IDL> !Y.OMARGIN=[0,1]
IDL> plot,indgen(100)
IDL> mplottitle, 'This is my title', [100523,100544]
IDL> plot,indgen(100)
IDL> cs=mk_color(/load, /quiet)
IDL> colors=[cs.black, cs.red, cs.green, cs.blue, cs.magenta]
IDL> mplottitle,' ', shots, colors=colors, logo='Shots:', $
charMag=1.35, topMargin=0.5
NOTES:
You'll probably want a little more room at the top of your plots, e.g.
IDL> !Y.OMARGIN=[0,1]
MODIFICATION HISTORY:
19-Jan-06 Added psym keyword
01-Oct-01 Added keywords for inside & right [BD]
21-Sep-99 Written by Bill Davis, PPPL
Name:
MULTIPLOT
Purpose:
Create multiple plots with shared axes.
Category:
Plotting
Explanation:
This procedure makes a matrix of plots with *SHARED AXES*, either using
parameters passed to multiplot or !p.multi in a non-standard way.
It is good for data with one or two shared axes and retains all the
versatility of the plot commands (e.g. all keywords and log scaling).
The plots are connected with the shared axes, which saves space by
omitting redundant ticklabels and titles. Multiplot does this by
setting !p.position, !x.tickname and !y.tickname automatically.
A call (multiplot,/reset) restores original values.
Note: This method may be superseded by future improvements in !p.multi
by RSI. For now, it's a good way to gang plots together.
CALLING SEQUENCE:
multiplot[pmulti][,/help][,/initialize][,/reset][,/rowmajor]
Examples:
multiplot,/help ; print this header.
; Then copy & paste, from your xterm, the following lines to test:
x = findgen(100) ; MULTIPLOT
t=exp(-(x-50)^2/300) ; -------------------------
erase ; | | |
u=exp(-x/30) ; | | |
y = sin(x) ; | UL plot | UR plot |
r = reverse(y*u) ; | | |
!p.multi=[0,2,2,0,0] ; | | |
multiplot ; y-------------------------
plot,x,y*u,title='MULTIPLOT' ; l| | |
multiplot & plot,x,r ; a| | |
multiplot ; b| LL plot | LR plot |
plot,x,y*t,ytit='ylabels' ; e| | |
multiplot ; l| | |
plot,x,y*t,xtit='xlabels' ; s-------------------------
multiplot,/reset ; xlabels
wait,2 & erase ; TEST
multiplot,[1,3] ; H------------------------
plot,x,y*u,title='TEST' ; E| plot #1 |
multiplot ; I------------------------
plot,x,y*t,ytit='HEIGHT' ; G| plot #2 |
multiplot ; H------------------------
plot,x,r,xtit='PHASE' ; T| plot #3 |
multiplot,/reset ; ------------------------
; PHASE
multiplot,[1,1],/init,/verbose ; one way to return to single plot
% MULTIPLOT: Initialized for 1x1, plotted across then down (column major).
Optional Inputs:
pmulti = 2-element or 5-element vector giving number of plots, e.g.,
multiplot,[1,6] ; 6 plots vertically
multiplot,[0,4,2,0,0] ; 4 plots along x and 2 along y
multiplot,[0,4,2,0,1] ; ditto, except rowmajor (down 1st)
multiplot,[4,2],/rowmajor ; identical to previous line
Optional Keywords:
help = flag to print header
initialize = flag to begin only---no plotting, just setup,
e.g., multiplot,[4,2],/init,/verbose & multiplot & plot,x,y
reset = flag to reset system variables to values prior to /init
default = flag to restore IDL's default value for system variables
rowmajor = flag to number plots down column first (D=columnmajor)
verbose = flag to output informational messages
Outputs:
!p.position = 4-element vector to place a plot
!x.tickname = either '' or else 30 ' ' to suppress ticknames
!y.tickname = either '' or else 30 ' ' to suppress ticknames
!p.noerase = 1
Common blocks:
multiplot---to hold saved variables and plot counter. See code.
Side Effects:
Multiplot sets a number of system variables: !p.position, !p.multi,
!x.tickname, !y.tickname, !P.noerase---but all can be reset with
the call: multiplot,/reset
Restrictions:
1. If you use !p.multi as the method of telling how many plots
are present, you have to set !p.multi at the beginning each time you
use multiplot or call multiplot with the /reset keyword.
2. There's no way to make an xtitle or ytitle span more than one plot,
except by adding spaces to shift it or to add it manually with xyouts.
3. There is no way to make plots of different sizes; each plot
covers the same area on the screen or paper.
Procedure:
This routine makes a matrix of plots with common axes, as opposed to
the method of !p.multi where axes are separated to allow labels.
Here the plots are joined and labels are suppressed, except at the
left edge and the bottom. You tell multiplot how many plots to make
using either !p.multi (which is then reset) or the parameter pmulti.
However, multiplot keeps track of the position by itself because
!p.multi interacts poorly with !p.position.
Modification history:
14-Dec-00 Account for !x.omargin and !x.ymargin [Bill Davis, PPPL]
write, 21-23 Mar 94, Fred Knight (knight@ll.mit.edu)
alter plot command that sets !x.window, etc. per suggestion of
Mark Hadfield (hadfield@storm.greta.cri.nz), 7 Apr 94, FKK
add a /default keyword restore IDL's default values of system vars,
7 Apr 94, FKK
modify two more sys vars !x(y).tickformat to suppress user-formatted
ticknames, per suggestion of Mark Hadfield (qv), 8 Apr 94, FKK
Converted to IDL V5.0 W. Landsman September 1997
NAME:
ovplot
PURPOSE:
Just like oplot, except it calls vcomp to "visually compress"
an array for faster delivery of graphs at the expense of CPU time.
All data spikes should be retained.
CATEGORY:
Plotting
CALLING SEQUENCE:
ovplot, time, data, _extra=_extra
KEYWORDS
Just like for oplot
COMMON BLOCKS:
none
EXAMPLE:
IDL> vplot, time, data, title='whatever', xrange=[0,2]
IDL> ovplot, time, data/2.
NOTES:
VComp assumes equally spaced data, but might be OK for some cases.
Probably want to use VPlot for first plot, but not necessary.
LIMITATIONS:
This is compuationally intensive, so is not appropriate for
all applications, but for I/O-bound plotting can speed up 10x or more.
Will return y points for each x -- the min & max values.
IF nFinal GE N_ELEMENTS(inData)*2 will just return inputs
MODIFICATION HISTORY:
Written 20-May-01 by Bill Davis
NAME:
plot0check
PURPOSE:
Plots blank axis if no data in !x.range or !y.range
CATEGORY:
Plotting, X-Y Plotting
CALLING SEQUENCE:
IDL> plot0check, x, y, ...
INPUTS:
x, y, .. = just like on the PLOT command.
KEYWORD PARAMETERS:
Keywords:
OUTPUTS:
none
COMMON BLOCKS:
NONE
EXAMPLE:
IDL>plot0check, x, y, line=1,color=1, /ylog
NOTES:
MODIFICATION HISTORY:
03-Oct-02 recover if x & y not right dimensions in 2-D plotting
18-May-01 Use Vcomp for "visual compression" if more points than resolution
20-Nov-00 Written by Bill Davis, PPPL
NAME:
PLOTCOLORFILL
PURPOSE:
Plots colorful bar charts
CATEGORY:
Plotting
CALLING SEQUENCE:
PLOTCOLORFILL, x, y, COLOR=col, BOTTOM=bot, WIDTH=wid, ...
DESCRIPTION:
PLOTCOLORFILL plots a colorful vertical bar chart. This may be
useful in cases where two dimensions of information need to be
conveyed in one plot. [ I use it to show total intensity as a
function of time on the vertical axis, and temperature is coded
with color. ]
Most aspects of the bars are configurable. The color is specified
by an array of colors, one for each bar. [ Alternatively, a
single color for the entire plot can be given. ] Also, one color
can be designated as transparent.
Stacked bar charts can be constructed using two calls to
PLOTCOLORFILL. See the example.
INPUTS:
X, Y - Two arrays which give the X and Y position of the points.
In this style of plot, the x values should be monotonically
increasing, but not necessarily monospaced (see WIDTH).
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
COLOR - an array giving the color of each bar, or alternatively a
scalar color for all of the bars. The current color table
is not changed. Default is color "1"
BOTTOM - normally the bottom of the bars is set to be zero. You
may either specify a scalar bottom value for all of the
bars, or an array giving the bottom of each bar
individually. See the example to see how stacked bar
charts can be constructed with this keyword.
WIDTH - sets the width of each bar, globally or individually.
Bars are centered on the "X" value, and extend 0.5 * WIDTH
to either side. Default is to assume monospacing, using
the separation between the first two x values.
TRANSPARENT - designates a color which is "transparent". Any bars
with this color are simply not plotted. Default is
no transparent color.
PANEL, SUBPANEL - An alternate way to more precisely specify the
plot and annotation positions. See SUBCELL.
Default is full-screen.
POSITION - Position of the bar chart in normal coordinates.
Overrides position given by PANEL/SUBPANEL.
XRANGE, YRANGE - gives plot range for each dimension, as for other
plot commands. Default is range of data.
Other keywords are passed to the plot command directly.
OUTPUTS:
NONE
PROCEDURE:
EXAMPLE:
Stacked barcharts can be constructed by first making one chart
with a flat bottom, and then a second chart whose bottom is top of
the first.
x = findgen(30)
y1 = x^2
y2 = 400.-x
c1 = bindgen(30)*3+1b
c2 = 100b-bindgen(30)*3+1b
plotcolorfill, x, y1, color=c1, bottom=0.
plotcolorfill, x, y1+y2, color=c2, bottom=y1, /noerase
SEE ALSO:
PLOTPAN
EXTERNAL SUBROUTINES:
SUBCELL, DEFSUBCELL, PLOTPAN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
MODIFICATION HISTORY:
Written, CM, 1997
NAME:
PLOTHIST
PURPOSE:
Plot the histogram of an array with the corresponding abcissa.
CATEGORY:
Plotting
CALLING SEQUENCE:
plothist, arr, xhist, yhist, [, BIN=, /FILL, /NOPLOT, /OVERPLOT, PEAK=,
...plotting keywords]
INPUTS:
arr - The array to plot the histogram of. It can include negative
values, but non-integral values will be truncated.
OPTIONAL OUTPUTS:
xhist - X vector used in making the plot
( = lindgen( N_elements(h)) * bin + min(arr) )
yhist - Y vector used in making the plot (= histogram(arr/bin))
OPTIONAL INPUT KEYWORDS:
BIN - The size of each bin of the histogram, scalar (not necessarily
integral). If not present (or zero), the bin size is set to 1.
/NOPLOT - If set, will not plot the result. Useful if intention is to
only get the xhist and yhist outputs.
/OVERPLOT - If set, will overplot the data on the current plot. User
must take care that only keywords valid for OPLOT are used.
PEAK - if non-zero, then the entire histogram is normalized to have
a maximum value equal to the value in PEAK. If PEAK is
negative, the histogram is inverted.
/FILL - if set, will plot a filled (rather than line) histogram.
The following keywords take effect only if the FILL keyword is set:
FCOLOR - color to use for filling the histogram
/FLINE - if set, will use lines rather than solid color for fill (see
the LINE_FILL keyword in the POLYFILL routine)
FORIENTATION - angle of lines for fill (see the ORIENTATION keyword
in the POLYFILL routine)
FPATTERN - the pattern to use for the fill (see the PATTERN keyword
in the POLYFILL routine)
FSPACING - the spacing of the lines to use in the fill (see the SPACING
keyword in the POLYFILL routine)
Any input keyword that can be supplied to the PLOT procedure (e.g. XRANGE,
LINESTYLE) can also be supplied to PLOTHIST.
EXAMPLE:
Create a vector of random 1000 values derived from a Gaussian of mean 0,
and sigma of 1. Plot the histogram of these values with a bin
size of 0.1
IDL> a = randomn(seed,1000)
IDL> plothist,a, bin = 0.1
MODIFICATION HISTORY:
09-Feb-2012 fixed use of xrange
08-Feb-2012 added ymax output keyword
Written W. Landsman January, 1991
Add inherited keywords W. Landsman March, 1994
Use ROUND instead of NINT W. Landsman August, 1995
Add NoPlot and Overplot keywords. J.Wm.Parker July, 1997
Add Peak keyword. J.Wm.Parker Jan, 1998
Add FILL,FCOLOR,FLINE,FPATTERN,FSPACING keywords. J.Wm.Parker Jan, 1998
Converted to IDL V5.0 W. Landsman 21-Jan-1998
NAME:
plotnormal
PURPOSE:
plot a normal curve on top of a histogram of data
CATEGORY:
Plotting, Statistics, GUI
CALLING SEQUENCE:
plotnormalw, data, BinSize=binsize, barFraction=barFrac, $
title=title, NormalOverlay=NormalOverlay, $
WindowTitle=WindowTitle, GROUP_LEADER=group_leader, $
XSIZE=xsize_in, YSIZE=ysize_in, xtitle=xtitle, ytitle=ytitle, $
_extra=_extra
INPUTS:
data - 1-d array
OUTPUTS:
plot in graphics widget
KEYWORDS:
barFraction - fraction of interval over which bar is drawn (0-1)
(default=0.5)
BinSize - The size of each bin of the histogram, scalar (not necessarily
integral). If not present (or zero), the bin size is set to 1.
NormalOverlay - if set, overlay a curve of the normal distribution
EXAMPLE:
IDL> data=randomN(seed, 100)
IDL> plotnormalw, data, binsize=.5
MODIFICATION HISTORY:
25-Apr-2003 don't try to plot null values (as defined by SQL, too)
March, 2003 Written by Bill Davis
NAME:
plotnshots
PURPOSE: make scope-like plots with overlays from multiple shots.
CATEGORY:
Plotting
USAGE:
IDL> plotnshots, shots, t1=t1, t2=t2, signames=signames, $
tweenspace=tweenSpace, labels=labels, $
titles=titles, scales=scales, $
rightSpace=rightSpace, leftSpace=leftSpace, colSpace=colSpace, $
pcharsize=pcharsize, bgtime=bgtime, ncols=ncols, nrows=nrows, $
biglabel=biglabel, nSmooth=nSmooth, $
SigUnits=SigUnits, topLabel=topLabel, zeroPlot=zeroPlot, $
yMins=yMins, yMaxes=yMaxes, SERVERNAMES=serverNames, noLogo=noLogo, $
anyProblem=anyProblem, sameXlabels=sameXlabels
METHOD: Reads in all requested shots for a signal, so can autoscale plot
correctly. One big 1-D array created by appending new signals, so
signals with different # of points, sampling rate, etc., will work.
EXAMPLE:
IDL> plotnshots, [104500,104501], $
signames=['\wf::ip','\engineering::ip1']
LIMITATIONS:
If max of X-data is > 100, assume not time and plot separately.
HISTORY:
17-Feb-2015 fix when # pts in X differs from # in Y by small percentage
30-Jan-2015 add code to handle EFITx trees where x is not a number
14-Jan-2015 add code for plotting 2 signals with no time base
09-Oct-2012 added EveryOther keyword for Y-axes
24-Jul-2012 a serious bug fixed when plotting a row or column of 1 2-D signal
against another with different axes.
05-May-2011 added ability to call user-written IDL routines in place of
signal names.
26-May-2010 added xstart, xdelta, xInTimeFormat keywords for HH:MM display option
26-Apr-2010 check for availability of SIGMATH TDI before usings
make order of plots from scope like in scopes
22-Apr-2010 added dateOnPlot and showMissingTags keywords
31-Aug-2009 fixed logic when some tree names missing and multiple shots [BD]
15-Nov-2008 if ymins or ymaxes are a scalar, use for all signals [BD]
03-Jul-2008 put plot order back to list of devices, and to scope order
changed "tween" space to be constant.
19-May-08 Fixed xticklen and xgridstyle use
07-Nov-07 add option to have TOPLABEL='NONE' for no plot titles
03-Oct-07 added /noshot keyword to EvalScopeTitle call
10-Aug-07 if t2 < t1, set=t1
01-May-07 Added keyword 'ShowAllXvalues' to label all X axes
06-Apr-07 get right default axis if plotting second dimension of 2-D array
07-Mar-07 continued _extra keyword into all plotting routines, so things
thick=3 in the Expert Entry field on the web tools will work.
28-Jul-06 remove auto scale if limits 1.e-5 difference
01-Mar-06 set default to be suppresserrors=0 because typos causing confusion.
changed MISSING DATA label
30-Jan-06 (re-)fixed specifed colors for multiple shots.
27-Jan-06 use x signal from scope, if present
06-Sep-2005 added SuppressError keyword
03-Aug-2005 allow colors to be input as an array or executable string
20-May-02 - In autoscale X, force all x-axis to plot on largest x scale.
also changed value indicating time (actually, meaning ranges
won't be used) changed from 100 to 300.
02-Jul-01 - convert from plot2shots, and plot 2-D images when 1 shot
28-Jun-01 - added anyProblem keyword, and sameXlabels keyword to
allow forcing time axis ticknames on plot
18-May-01 - added vplot & ovplot for "visual compression"
06-Mar-01 - added Yrange & made t1 & t2 be arrays
06-Feb-02 - put back ability to display 2-D
NAME:
plotnsigs
PURPOSE:
make scope-like plots with overlays from multiple signals.
this is the version of plotnshots that overlays different signals
on the same axes
CATEGORY:
Plotting
USAGE:
IDL> plotnsigs, shots, t1=t1, t2=t2, signames=signames, $
tweenspace=tweenSpace, labels=labels, $
titles=titles, scales=scales, $
rightSpace=rightSpace, leftSpace=leftSpace, colSpace=colSpace, $
pcharsize=pcharsize, bgtime=bgtime, ncols=ncols, nrows=nrows, $
biglabel=biglabel, nSmooth=nSmooth, $
SigUnits=SigUnits, topLabel=topLabel, zeroPlot=zeroPlot, $
yMins=yMins, yMaxes=yMaxes, SERVER=server, noLogo=noLogo, $
anyProblem=anyProblem, sameXlabels=sameXlabels
METHOD: Reads in all requested shots for a signal, so can autoscale plot
correctly. One big 1-D array created by appending new signals, so
signals with different # of points, sampling rate, etc., will work.
EXAMPLE:
IDL> plotnsigs, [104500,104500,104501,104501], $
signames=['\wf::ip','\engineering::ip1','\wf::ip','\engineering::ip1']
LIMITATIONS:
If 2-D data, will just take the first row for multiple plots.
If max of X-data is > 100, assume not time and plot separately.
HISTORY:
30-Jan-2015 add code to handle EFITx trees where x is not a number
15-Aug-2013 had to do more work on labels and many plots in a frame
01-Aug-2013 fix bug on last right axis when many shots on a frame
Allow use of ctb -1 for a better rainbow pallete.
25-Jul-2013 when many shots and many sigs, by default, make a frame for each
sig with all the shots.
07-Nov-07 add option to have TOPLABEL='NONE' for no plot titles
31-Jul-07 created from plotnshots [BD]
NAME:
plotSig1vsSig2
PURPOSE: plot 1 MDSplus signal vs. another
CATEGORY:
Plotting
USAGE:
IDL> plotSig1vsSig2, shots, t1=t1, t2=t2, signames=signames, $
labels=labels, $
titles=titles, scales=scales, $
rightSpace=rightSpace, leftSpace=leftSpace, colSpace=colSpace, $
pcharsize=pcharsize, $
biglabel=biglabel, nSmooth=nSmooth, $
SigUnits=SigUnits, topLabel=topLabel, zeroPlot=zeroPlot, $
yMins=yMins, yMaxes=yMaxes, SERVER=server, noLogo=noLogo, $
anyProblem=anyProblem, sameXlabels=sameXlabels
EXAMPLE:
IDL> plotSig1vsSig2, 116116, signames=['\wf::ip','\wf::itf']
LIMITATIONS:
HISTORY:
30-Jan-2015 add code to handle EFITx trees where x is not a number
06-Mar-06 Added HH:MM output option. Also, make title Y vs. X.
09-Sep-05 Converted from plotnshots [BD]
NAME:
PlotSummary4
PURPOSE:
Plot vs. time a summary of a shot (Ip, D-alpha, Pinj, Wmhd) in a small frame
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> PlotSummary4, shot
INPUTS:
shot - shot # (defaults to current shot)
KEYWORD PARAMETERS:
Optional Keywords:
tois - times of interest at which a dashed vertical line will be drawn
xsize -
ysize -
verbose -
debug -
labelShot -
signames -
pos -
minIP -
x1 -
y1 -
xfrac -
yFrac -
charsize -
charThick -
thick -
xmargin -
widthFactor - if set, ysize = xsize * widthFactor
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> plotsummary4, 119923
NOTES:
webplotsum.pro is an upgrade of this routine.
MODIFICATION HISTORY:
13-Mar-2008 handle missing ptot
04-Mar-2008 Written by Bill Davis, PPPL, for Stan Kaye
NAME:
plotsummary
PURPOSE:
Plot vs. time a summary of a shot (Ip, D-alpha, Pinj) in a small frame
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> plotsummary, shot
INPUTS:
shot - shot # (defaults to current shot)
KEYWORD PARAMETERS:
Optional Keywords:
tois - times of interest at which a dashed vertical line will be drawn
xsize -
ysize -
verbose -
debug -
labelShot -
signames -
pos -
minIP -
x1 -
y1 -
xfrac -
yFrac -
charsize -
charThick -
thick -
xmargin -
widthFactor - if set, ysize = xsize * widthFactor
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> plotsummary, 119923
NOTES:
Used in animation generators, amoung others. Has thicker lines than
plotsummary4.pro.
webplotsum.pro is an upgrade of this routine.
MODIFICATION HISTORY:
pre-2008 Written by Bill Davis, PPPL
NAME:
PLOTSYM
PURPOSE:
Define useful plotting symbols not in the standard !PSYM definitions.
CATEGORY:
Plotting
EXPLANATION:
After a symbol has been defined with PLOTSYM, a plotting command should
follow with either PSYM = 8 or !P.PSYM = 8 (see USERSYM)
CALLING SEQUENCE:
PLOTSYM, PSYM,[ PSIZE, /FILL, THICK=]
INPUTS:
PSYM - The following integer values of PSYM will create the
corresponding plot symbols
0 - circle
1 - downward arrow (upper limit), base of arrow begins at plot value value
2 - upward arrow (lower limt)
3 - 5 pointed star
4 - triangle
5 - upside down triangle
6 - left pointing arrow
7 - right pointing arrow
8 - square
Arrows are defined such that their base begins at their origin.
OPTIONAL INPUTS:
PSIZE - Size of the plotting symbol in multiples of the default size
(default PSIZE=1). Does not need to be an integer
OPTIONAL INPUT KEYWORD:
FILL - Parameter indicating whether to fill the symbol (see USERSYM)
The default is 0, unfilled symbol. Does not affect arrows
or character symbols.
THICK - Thickness of unfilled symbols. Default is 1.
OUTPUTS:
None
EXAMPLES:
Plot Y vs. X with filled stars as the symbol, twice the default size
IDL> PLOTSYM, 3 ,2, /FILL ;Plotting symbol is a filled star,
;twice default size
IDL> PLOT,X,Y,PSYM=8 ;Set PSYM = 8 to get star symbol
Now plot Y vs. X with an open circle as the symbol
IDL> PLOTSYM, 0 ;Plotting symbol is a circle
IDL> PLOT,X,Y,PSYM=8
METHOD:
Appropriate X,Y vectors are used to define the symbol and passed to the
USERSYM command.
REVISION HISTORY
27-Jan-2010 added circle, square, triangle, arrow, and size keywords
25-Feb-2005 added keyword usersym, for sending to Legend, for example [BD]
Written W. Landsman June 1992
18-JAN-1996 Added a square symbol, HCW.
98Aug20 Added keyword thick parameter - RCB.
NAME:
RESETPLT
PURPOSE:
This procedure will reset all or a selection
of the system plot variables to their initial values
CATEGORY:
Plotting
CALLING SEQUENCE:
resetplt,/all ;clear the !p, !x, !y, !z
resetplt,/x,/z ;clear the !x and !z variables
resetplt,/x ;only clear the !x variable
resetplt,/x,/invert ;clear all except the !x
INPUTS:
KEYWORDS:
x,y,z,p = clear the appropriate variable
all = clear all, this is equivalent to /x,/y,/z,/p
invert = invert the logic. Clear all unselected variables.
Therefore "clearplt,/all,/invert" does nothing.
OUTPUTS:
none
COMMON BLOCKS:
none.
SIDE EFFECTS:
The sytem plot variables are changed.
MODIFICATION HISTORY:
Written by: Trevor Harris, Physics Dept., University of Adelaide,
July, 1990.
NAME:
roundedAxisLimits
PURPOSE:
Find "nice" axis values, like IDL plot routine does.
CATEGORY:
Plotting
CALLING SEQUENCE:
v = roundedAxisLimits(x1,x2)
INPUTS:
x1 = Range minimum. in
x2 = Range maximum. in
KEYWORD PARAMETERS:
OUTPUTS:
v = 2-element array of "nice" axis limits. out
COMMON BLOCKS:
LIMITATION:
IDL> print,roundedaxislimits(0.0,.11)
0.00000 0.120000 OK, but
IDL> print,roundedaxislimits(0.0,.12)
0.00000 0.125000 why not 0.12?
NOTES:
includes routines copyrighted by Johns Hopkins University (see below)
MODIFICATION HISTORY:
26-Jul-04 Written by Bill Davis
NAME:
screen_title
PURPOSE:
write a plot title with shot date and time and NSTX label
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> screen_title, mytitle, ishot
INPUTS:
mytitle = whatever you want as the main plot title.
ishot = shot number.
KEYWORD PARAMETERS:
Keywords:
noShot - if set, do not plot shot number
noTime - if set, do not plot time
charsize - character size
logo - if = 0 will not put logo on plot
nstx - if - 0 will not put =NSTX= logo on plot, vs. just NSTX
ALIGNMENT - alignment of title. Default to 0.5 (centered)
HLP - When set, help information is printed.
OUTPUTS:
none
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> !Y.OMARGIN=[0,1]
IDL> plot,indgen(100)
IDL> screen_title, 'This is my title', 100523
NOTES:
You'll probably want a little more room at the top of your plots, e.g.
IDL> !Y.OMARGIN=[0,1]
MODIFICATION HISTORY:
13-Aug-2009 fixed logic for mptscam.pro
17-Sep-2008 added logo and alignment keywords
30-Jun-2008 added charsize and NSTX keywords
21-Sep-00 Written by Bill Davis, PPPL
NAME:
stackplot
PURPOSE:
An example of X-window widgets for plotting some GA data
CATEGORY:
Plotting, Example, Widgets, GA
CALLING SEQUENCE:
stackplot
USE:
If you have a file named mdsplussig.txt in the directory
from which you are running IDL, signal names in the file
will be plotted when you click on "My Signals." The names
should be one per row.
MAJOR FUNCTIONS and PROCEDURES:
PLOT: X-Y plotting.
SMOOTH: Smooths data and overplots.
MODIFICATION HISTORY: Written by: WMD, PPPL, March, 1997
based on RSI's Forecast example
26-Jan-99 Modified for using MDS at PPPL by Bill Davis
21-Oct-97 WMD Simplified for IDL class example at GA
15-Apr-97 WMD Changed for remote plotting test
NAME:
vaxis
PURPOSE:
shell around AXIS procedure that sees if number of minor y tick
marks need to be reduced, and if the number of y tick labels need
to be cut in half.
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> vaxis, /yaxis
INPUTS:
if /yaxis not set, will just call AXIS routine with whatever inputs are passed
KEYWORD PARAMETERS:
Optional:
yminor - as in plot command
yrange - as in plot command
ystyle - as in plot command
yTickFormat - defaults to 'LabelEveryOtherTick'
debug - if set, will print things and stop in routine
OUTPUTS:
none
COMMON BLOCKS:
vplot_local
EXAMPLE:
IDL> a=mk_color()
IDL> x=findgen(100)
IDL> y=sin(x/8*4)*exp(x/30)
IDL> pos=[.1,.77,.9,.9]
IDL> plot,x,y,ystyle=8, pos=pos, yTickFormat='LabelEveryOtherTick', yminor=2
IDL> vaxis, yaxis=1,/debug ;;; , yTickFormat='LabelEveryOtherTick'
NOTES:
15-Aug-2013 fixed large major Y tick marks
WRITTEN 29-Oct-2007 By Bill Davis, PPPL.
NAME:
vcomp
PURPOSE:
"visually compress" (resample) an array for faster plotting of lines.
All data spikes should be retained.
Will return y points for each x -- the min & max values.
IF nFinal GE N_ELEMENTS(inData)*2 will just return inputs
CATEGORY:
Plotting
CALLING SEQUENCE:
VComp, inTime, inData, outTime, outData, NFINAL=4096
KEYWORDS
Optional:
NFINAL - # of points to "compress" to. Defaults to estimated
# of pixels on x axis
COMMON BLOCKS:
none
EXAMPLE:
IDL> vcomp, inTime, inData, outTime, outData, NFINAL=4096
NOTES:
assumes equally spaced data, but might be OK for some cases.
LIMITATIONS:
This doesn't work precisely when:
1) only points are drawn, rather than connecting lines,
2) the X values are not monotonically increasing, or
3) even if X intervals are not constant (although errors would probably be subtle).
MODIFICATION HISTORY:
26-Jul-2004 NINT() introduced a bug in some cases; now fixed
17-May-2004 Bug fixed: not going to full time range
22-Apr-2004 If POS being used, x.margin irrelevant, so assume 0
Written 10-Nov-99 by Bill Davis
NAME:
vgds_title
PURPOSE:
write a plot title with shot date and time and NSTX label
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> vgds_title, mytitle, ishot
INPUTS:
mytitle = whatever you want as the main plot title.
ishot = shot number.
KEYWORD PARAMETERS:
Keywords:
noShot - if set, do not plot shot number
noTime - if set, do not plot time
TopMargin - in characters, extra space to shift down the characters
HLP - When set, help information is printed.
OUTPUTS:
none
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> !Y.OMARGIN=[0,1]
IDL> plot,indgen(100)
IDL> vgds_title, 'This is my title', 100523
NOTES:
You'll probably want a little more room at the top of your plots, e.g.
IDL> !Y.OMARGIN=[0,1]
MODIFICATION HISTORY:
21-Sep-99 Written by Bill Davis, PPPL
NAME:
vplot
PURPOSE:
Just like plot, except it calls vcomp to "visually compress"
an array for faster delivery of graphs at the expense of CPU time.
All data spikes should be retained.
CATEGORY:
Plotting
CALLING SEQUENCE:
vplot, time, data, _extra=_extra
KEYWORDS
Just like for plot (except you need both X & Y)
xIsHHMM - plot x axis as time in HH:MM format (assume time in hours)
xWithSeconds - plot x axis as time in HH:MM:SS format (assume time in hours)
COMMON BLOCKS:
vplot_local
EXAMPLE:
IDL> vplot, time, data, title='whatever', xrange=[0,2]
NOTES:
VComp assumes equally spaced data, but might be OK for some cases.
Use oVPlot for overplotting.
LIMITATIONS:
This is compuationally intense, so is not appropriate for
all applications, but for I/O-bound plotting can speed up 10x or more.
Will return y points for each x -- the min & max values.
IF nFinal GE N_ELEMENTS(inData)*2 will just return inputs
MODIFICATION HISTORY:
05-Jul-2011 If axes are small, reduce number of tick marks, but use defaults
if close. If aspect ratio is long, adjust ticklengths for vertical
and horizontal axes.
14-Apr-2010 create window if none in use, so can do scaling. [BD]
16-Apr-2009 Removed xTickFormat='betterTickLabels' when want HH:MM..
11-Feb-2008 fixed bug for pingplot.pro
30-Oct-2007 improve number of tick marks, and length.
08-May-2006 added logic if _extra contains range, but both equal
03-Mar-2006 add xIsHHMM keyword
26-Jul-04 make so plots "nice" range, like IDL default, if
15-Apr-04 handle when no additional paramters entered
add keyword for xtick_get (seem to need to specify explicitly)
Written 20-May-01 by Bill Davis
NAME:
webplotsum
PURPOSE:
Plot vs. time a summary of a shot in a small frame
Ip, D-alpha, stored energy, NB & RF power are plotted.
CATEGORY:
Plotting
CALLING SEQUENCE:
IDL> webplotsum, shot
INPUTS:
shot - shot # (defaults to current shot)
KEYWORD PARAMETERS:
Optional Keywords:
tois - times of interest at which a dashed vertical line will be drawn
xsize -
ysize -
verbose -
debug -
labelShot -
signames -
pos -
minIP -
x1 -
y1 -
xfrac -
yFrac -
charsize -
charThick -
thick -
xmargin -
widthFactor - if set, ysize = xsize * widthFactor
noLoad - if set, do not load a color table, even if colorsearch
returns a bad status
markTime - time at which to draw a vertical dashed line on graph
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> webplotsum, 119923
NOTES:
Used in weblogplot.pro, amoung others
MODIFICATION HISTORY:
29-Jan-2015 moved right label logic below defaults for signame
26-Feb-2014 have right label contain "& kJ" only if one signame
has "WMHD" in it.
22-Jan-2014 users confused when no beams and RF in red. Always be in green.
Also, make it so Prf can not be offscale.
20-Oct-2010 for MSE calibration, check for beam data, so can have
time include it, even if plasma current is too low
17-Aug-2010 compute X tick length based on position array
27-May-2010 fixed bug when last signals not there, was returning before
plotting.
07-Apr-2010 tweaked tick length & number of minor tick marks
02-Apr-2010 added lColor keyword for index color of dashed line
18-Dec-2009 add keyword noLoad and don't use mk_color if not necessary
29-Sep-2009 display Pnb and Prf, if present
07-Apr-2009 use \pnb+\prf if \ptot not there.
13-Mar-2008 handle missing ptot
04-Mar-2008 Written by Bill Davis, PPPL, for Stan Kaye
Category: Printing
[List of Routines]
NAME:
LIST_PRINTER_UNIX
PURPOSE:
LIST available printers from lpstat -a
CATEGORY:
Printing, Unix
SYNTAX:
IDL> printers=list_printer_unix(desc)
EXAMPLES:
(see example in mk_pdmenu)
INPUTS: None
OUTPUTS:
PRINTERS - printer que names
Opt. Outputs:
DESC - description of each printer (doesn't work for printcap.lprng)
KEYWORDS:
printcap - the printcap file to query (INPUT)
ERR - error messages (OUTPUT)
COMMON:
LIST_PRINTER_UNIX - contains last reading of printcap file
Restrictions:
Unix only.
History
22-Feb-2012 use "lpstat-a" for discovering printers
12-May-2005 Made to work for Red Hat Enterprise Linux
where names end with colon [BD]
13-Jan-2003 added printcap.lprng to file search and remove
blank printer names. If file=printcap.lprng, also
look for printer names as first character of line. [Bill Davis]
Version 1, 8-Aug-1995, D M Zarro . Written
Version 2, 1 July 1996, S.V.H.Haugan (UiO)
Added PSLASER/PSCOLOR/PSCOLOR2 environmentals check.
1-Nov-2000, Kim Tolbert - Previously only worked for unix machines with
/etc/printcap file for printers (DEC, ?). Added check
for /etc/printers.conf (Sun) also.
18-Dec-2001, Kim Tolbert. Some unix (linux) allows pipe symbol (|) in
lp definition (like :lp=|/usr/share/printconf/jetdirectprint:\)
so have to look for names in lines with | but no colon in first column.
Also, names can be in lines with |, or lines with : (if not in
first column), so append result of both kinds of search instead of
doing one or the other.
Also, eliminate all comment lines first
NAME:
PPPL_Printers
PURPOSE:
return an array of strings of printer descriptions at PPPL
CATEGORY:
Printing
CALLING SEQUENCE:
printer_list = PPPL_Printers()
INPUTS:
StartShot - shot number to start from in
KEYWORD PARAMETERS:
Inputs:
FILENAME - name of file to read printer descriptions from
an example of an entry in the file is:
crc-color - Color printer in B152
JUSTPRINTERS - if set, just return the names of the printers
OUTPUTS:
printer_list - String Array
EXAMPLE:
printer_list = PPPL_Printers()
COMMON BLOCKS:
NOTES:
On VMS, the file read is PRINTERS_VMS.txt, on Unix it is
PRINTERS_UNIX.txt. Returns a blank for other systems.
If environmental variable local_idl_dir is defined, this routine
will look for the file in this area
MODIFICATION HISTORY:
18-May-2004 add 'not implemented' for windows, and which not working
09-Jun-2003 If not on Unix or VMS, return a blank.
26-Mar-1999 Written by Bill Davis
NAME:
PS_FORM
PURPOSE:
This function displays a form the user can interactively manipulate
to configure the PostScript device driver (PS) setup. The function returns
a structure of keywords that can be sent directly to the DEVICE command
via its _EXTRA keyword
CATEGORY:
Printing, Device Drivers, Hardcopy Output, PostScript Output
PROCEDURE:
This is a pop-up form widget. It is a modal or blocking widget.
Keywords appropriate for the PostScript (PS) DEVICE command are returned.
The yellow box in the upper right hand corner of the form represents the
PostScript page. The green box represents the "window" on the PostScript
page where the graphics will be drawn.
Use your LEFT mouse button to move the plot "window" around the page.
Use your RIGHT mouse button to draw your own plot window on the page.
The CREATE FILE and ACCEPT buttons are meant to indicate slightly
different operations, although this is sometimes confusing. My idea
is that PS_FORM is a *configuration* dialog, something the user displays
if he or she wants to change the way the PostScript device is configured.
Thus, in many of my widget programs if the user clicks a "Write PostScript File"
button, I just go ahead and write a PostScript file without displaying the
form. (I can do this because I always keep a copy of the current device
configuration in my info structure.) To get to the form, the user must
select a "Configure PostScript Device" button.
At that time, the user might select the ACCEPT button to just change
the PostScript device configurations. Or the user can select the
CREATE FILE button, which both accepts the configuration *and* creates
a PostScript file. If you find the CREATE FILE button confusing, you
can just edit it out of the form and use the ACCEPT button for the
same purpose.
HELP:
formInfo = PS_FORM(/Help)
USAGE:
The calling procedure for this function in a widget program will look something
like this:
info.ps_config = PS_FORM(/Initialize)
...
formInfo = PS_FORM(Cancel=canceled, Create=create, $
Defaults=info.ps_config, Parent=event.top)
IF NOT canceled THEN BEGIN
IF create THEN BEGIN
thisDevice = !D.Name
Set_Plot, "PS"
Device, _Extra=formInfo
Enter Your Graphics Commands Here!
Device, /Close
Set_Plot, thisDevice
ENDIF
info.ps_config = formInfo
ENDIF
OPTIONAL INPUT PARAMETERS:
XOFFSET -- Optional xoffset of the top-level base of PS_Form. Default is
to try to center the form on the display.
YOFFSET -- Optional yoffset of the top-level base of PS_Form. Default is
to try to center the form on the display.
INPUT KEYWORD PARAMETERS:
BITS_PER_PIXEL -- The initial configuration of the bits per pixel button.
BLOCKING -- Set this keyword to make this a blocking widget under IDL 5.0.
(All widget programs block under IDL 4.0.)
COLOR -- The initial configuration of the color switch.
DEFAULTS -- A stucture variable of the same type and structure as the
RETURN VALUE of PS_FORM. It will set initial conditions. This makes
it possible to start PS_FORM up again with the same values it had the
last time it was called. For example:
mysetup = PS_FORM()
newsetup = PS_FORM(Defaults=mysetup)
NOTE: Using the DEFAULTS keyword will nullify any of the other
DEVICE-type keywords listed above (e.g., XSIZE, ENCAPSULATED, etc.)
ENCAPSULATED -- The initial configuration of the encapsulated switch.
FILENAME -- The initial filename to be used on the form.
HELP -- Prints a helpful message in the output log.
INCHES -- The initial configuration of the inches/cm switch.
INITIALIZE -- If this keyword is set, the program immediately returns the
"localdefaults" structure. This gives you the means to configue the
PostScript device without displaying the form to the user. I use this
to write a PostScript file directly and also to initialize my info
structure field that contains the current PostScript form setup. Passing
the setup structure into PS_FORM via the DEFAULTS keyword gives my PS_FORM
a program "memory".
info.ps_setup = PS_FORM(/Initialize)
LANDSCAPE -- The initial configuration of the landscape/portrait switch.
LOCALDEFAULTS -- A structure like the DEFAULTS structure. Used if the
"Local Defaults" button is pressed in the form. This gives you the
opportunity to have a "local" as well as "system" default setup.
If this keyword is not used, the procedure PS_Form_Set_Personal_Local_Defaults
is called. Use this procedure (see below) to define your own local
defaults.
XOFFSET -- The initial XOffSet of the PostScript window.
YOFFSET -- The initial YOffSet of the PostScript window.
XSIZE -- The initial XSize of the PostScript window.
YSIZE -- The initial YSize of the PostScript window.
OUTPUT KEYWORD PARAMETERS
CANCEL -- This is an OUTPUT keyword. It is used to check if the user
selected the "Cancel" button on the form. Check this variable rather
than the return value of the function, since the return value is designed
to be sent directly to the DEVICE procedure. The varible is set to 1 if
the user selected the "Cancel" button. Otherwise, it is set to 0.
CREATE -- This output keyword can be used to determine if the user
selected the 'Create File' button rather than the 'Accept' button.
The value is 1 if selected, and 0 otherwise.
RETURN VALUE:
formInfo = { PS_FORM_INFO, $
xsize:0.0, $ ; The x size of the plot
xoff:0.0, $ ; The x offset of the plot
ysize:0.0, $ ; The y size of the plot
yoff:0.0 $ ; The y offset of the plot
filename:'', $ ; The name of the output file
inches:0 $ ; Inches or centimeters?
color:0, $ ; Color on or off?
bits_per_pixel:0, $ ; How many bits per image pixel?
encapsulated:0,$ ; Encapsulated or regular PostScript?
landscape:0 } ; Landscape or portrait mode?
MAJOR FUNCTIONS and PROCEDURES:
None. Designed to work originally in conjunction with XWindow,
a resizable graphics window.
MODIFICATION HISTORY:
Written by: David Fanning, RSI, March 1995.
Given to attendees of IDL training courses.
19-Dec-02 fix for vms directories [Bill Davis]
Modified to work when grapics device set to PostScript: 6 May 95.
Modified to configure initial conditions via keywords: 13 October 95.
Modified to load personal local defaults if LocalDefaults keyword not
used: 3 Nov 95.
Found and fixed bits_per_pixel error in Local Defaults setting
procedure: 3 Nov 95.
Modified to produce initial plot box with the same aspect ratio as
the current graphics window. (XSIZE or YSIZE keywords overrule this
behavior.) 22 Apr 96.
Fixed annoying behavior of going to default-sized plot box when selecting
the Landscape or Portrait option. Now keeps current plot box size.
22 Apr 96.
Made the size and offset text widgets a little bigger and changed the
size and offset formatting from F4.2 to F5.2 to accomodate larger plot
box sizes. 29 Apr 96.
Fixed a bug in the filename text widget that caused a crash when a CR
was hit. 3 Sept 96.
Added the Initialize keyword to immediately return the "localdefaults"
structure. 27 Oct 96.
Fixed another problem with the BITS_PER_PIXEL keyword. 27 Oct 96.
Made the return value a named structure of the name PS_FORM_INFO.
3 Nov 96.
Discovered and fixed a problem whereby YOFFSET was set incorrectly if
LOCALDEFAULTS was used instead of DEFAULTS keyword. 3 Nov 96.
Fixed bug in how Portrait mode was set using YSIZE and XSIZE keywords.
25 Nov 96.
Fixed a bug in how YOFFSET was calculated when in Landscape mode. 27 Nov 96.
Fixed a memory leak with the local defaults pointer. 25 Jan 97.
Added the CREATE keyword and modified the appearance of the form. 22 Apr 97.
Modifed subroutine names to avoid confusion. 22 Apr 97.
Fixed a bug I introduced when I added the CREATE keyword. 23 Apr 97.
Modified the program for IDL 5. 30 May 97, DWF.
Fixed Inches to CM exclusive button problem. 30 May 97, DWF.
Fixed a problem when the widget is killed with the mouse. 30 May 97. DWF
Added a Select Filename button. 12 Oct 97.
Modified program layout slightly. 12 Oct 97.
Added valid directory/file error checking for the filename. 12 Oct 97. DWF
Added further support for IDL 5 modal functionality. 20 Oct 97. DWF
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
2642 Bradbury Court
Fort Collins, CO 80521 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
NAME:
screendump
PURPOSE:
Postscript file from an IDL window, whether 8- or 24-bit graphics
CATEGORY:
Printing, 24-bit graphics
CALLING SEQUENCE:
IDL> screendump, filename, Encapsulated=encapsulated
INPUTS:
filename (or will be prompted)
KEYWORD PARAMETERS:
Keywords:
Encapsulated - if set, will get encapsulated postscript
Right_Aspect - if set, will maintain aspect ration of window
OUTPUTS:
just the output file
MODIFICATION HISTORY:
09-May-02 Added bits_per_pixel=8 when not true color [BD]
still not working in 24-bit color (???)
27-Jun-02 Added Right_Aspect keyword [BD]
07-Mar-02 Added landscape determination [BD]
?? Written by David Fanning, www.dfanning.com.
NAME:
setup_ps
PURPOSE:
open postscript file and set system variables for postscript device
CATEGORY:
Printing
CALLING SEQUENCE:
SETUP_PS, name, PRINTER=printer
INPUTS:
(Optional)
name - name of file (defaults to IDL)
(if no extention, will add .ps)
KEYWORD PARAMETERS:
Optional Inputs:
PRINTER - printer to send file to (else will be default printer)
NOTE: if PRINTER begins with postscript', file will not be
sent to a printer
PORTRAIT - If set, print is in portrait mode
FONT - font for printing, e.g., TIMES, HELVETICA, AVANTGARDE,
BKMAN, BOLD, PALATINO, ZAPFCHANCERY, NARROW (Default is Times)
COLOR - if set, postscript will be in color
AspectRatio - if set, Ascpect ratio of image is maintained
CharMagnification - magnify !p.charsize (or, if !p.charsize=0, use as charsize)
xsize - size in inches (defaults to page size -1.5)
ysize - size in inches (defaults to page size -1.5)
tt_font
bold
OUTPUTS:
none
CALLING EXAMPLE:
printer = 'picasso color printer' ; or
printer = 'postscript color ' ; or
printer = 'b143 Laserwriter in B143' ; or
printer = 'default printer' ;
setup_ps,'myplot', PRINTER=printer
plot,indgen(11) ; any number of plot commands
unsetup_ps ; send to printer and back to X
RELATED ROUTINES:
unsetup_ps
SIDE EFFECTS:
System variables are changed until unsetup_ps is called.
NOTE:
If you haven't already, you may wish to plot on a white background, e.g.,
IDL> !p.background=MK_COLOR('white')
IDL> !p.color=MK_COLOR('black')
MODICATION HISTORY:
30-Oct-2009 default to COLOR if postscript output
07-May-08 fixed when /ASPECTRATIO made plot bigger than one dimension
19-Apr-04 Added Filename keyword
03-Aug-01 Append .ps to output filename if not specified
04-Apr-01 make max paper width 8.25 to account for A4 paper size.
make margins 3/4" (rather than 1")
21-May-99 Added Font keyword (default changed to Times) [BD]
1-Apr-99 Added Portrait Keyword [BD]
12-Feb-99 Write file in the login area. Don't send to D4D area. [BD]
Printer can have "color" after the name (following a space)
27-Jan-99 BD - change y.margin settings
10/15/97 BD - Removed bold fonts and set to landscape mode
10/13/97 TBT - Added phaser5
6/11/97 TBT - took out printer from discolor and added as
a keyword
5/22/97 TBT - added phaser4 & phaser4_trans & hpdj2
5/21/97 TBT - added include discolor to get printer passed in.
5/21/97 Ted Terpstra - Put in color printer check &
added phaser2 and phaser3 to the list.
5-16-95 K. Greene -- When setting up output file name, check
operating system. VMS cannot use Unix format.
NAME:
spawnprint
PURPOSE:
Spawn command on VMS or Unix to print a Postscript file
CATEGORY:
Printing
CALLING SEQUENCE:
IDL> spawnprint, filename, printer=printer
INPUTS:
filename (or will be prompted)
KEYWORD PARAMETERS:
Keywords:
printer - else will go to the default printer
NOTE: if PRINTER begins with postscript', file will not be
sent to a printer
OUTPUTS:
none
MODIFICATION HISTORY:
07-Mar-02 Written by Bill Davis
NAME:
unsetup_ps
PURPOSE:
close a postscript file (opened by setup_ps) and re-set system
variables for previous device.
CATEGORY:
Printing, Cross-platform Printing of Plots
CALLING SEQUENCE:
UNSETUP_PS, name, PRINTER=printer
INPUTS:
(Optional)
name - name of file without extenstion (defaults to IDL)
(extention will always be .ps)
KEYWORD PARAMETERS:
Inputs:
PRINTER - printer to send file to (only the string before the
first blank is used). The printer may have been
specified in the call to SETUP_PS, else the default
is used printer.
NOTE: if PRINTER='postscript', file will not be sent
to a printer
NOHEADER - if set, -h is inserted in lpr command
OUTPUTS:
none
CALLING EXAMPLE:
printer = 'picasso color printer' ; or
printer = 'postscript color ' ; or
printer = 'b143 Laserwriter in B143' ; or
printer = 'default printer' ;
setup_ps,'myplot', PRINTER=printer
plot,indgen(11) ; any number of plot commands
unsetup_ps ; send to printer and return to X
RELATED ROUTINES:
setup _ps
MODICATION HISTORY:
30-Oct-2009 changed NoHeader string on lp command to "-o nobanner"
05-Feb-03 added keyword NoHeader
12-Feb-99 If printer = 'postscript' or 'file', don't send to
a printer. If printer = 'default', send to the
default printer (i.e., none specified)
Write file in the login area.
27-Jan-99 adapt for SunOS; change y.margin settings [BD]
14-Oct-97 Written by Bill Davis
NAME:
unsetup_tek
PURPOSE:
undo system variables from setup_tek call.
CATEGORY:
Printing, Cross-platform plotting
CALLING SEQUENCE:
UNsetup_tek
INPUTS:
(Optional)
name - name of file without extenstion (defaults to idl)
(extention will always be .tek)
KEYWORD PARAMETERS:
OUTPUTS:
none
CALLING EXAMPLE:
setup_tek
plot,indgen(11) ; any number of plot commands
unsetup_tek ; send to printer and back to X
RELATED ROUTINES:
setup_tek
LIMITATIONS
If using the CH_ crosshair routines, will need to call the following
after this routine:
IDL> CH_SET, yourGraph, NewX=!x,NewY=!y,NewP=!p
MODICATION HISTORY:
13-Feb-06 add XTC calls
08-May-01 call CH_SET, if user calling cross-hair routines
26-Oct-00 Written by Bill Davis
NAME:
unsetup_xpc
PURPOSE:
Close plots file opened with setup_xpc, and send to the X-windows Plot Controller
(XPC) by figuring out next file in the sequence it is looking for.
CATEGORY:
Printing, Cross-platform plotting
CALLING SEQUENCE:
UNsetup_xpc
INPUTS:
(Optional)
name - name of file without extenstion (defaults to idl)
(extention will always be .tek)
KEYWORD PARAMETERS:
OUTPUTS:
none
CALLING EXAMPLE:
setup_xpc
PLOT, indgen(11) ; any number of plot commands
XYOUT, .2, .3, 'This is a Label'
unsetup_xpc ; send to printer and back to X
RELATED ROUTINES:
setup_xpc
LIMITATIONS
If using the CH_ crosshair routines, will need to call the following
after this routine:
IDL> CH_SET, yourGraph, NewX=!x,NewY=!y,NewP=!p
NOTE:
This, in conjunction with unsetup_xpc, is supposed to be a replacement for XPC.
MODICATION HISTORY:
18-Nov-2009 Written by Bill Davis
Category: Programming
[List of Routines]
NAME:
ADD_TAG
PURPOSE:
Add a new tag to the structure. NOTE: if you want to add more
than one tag at once, use ADD_TAGS
CATEGORY:
Programming
CALLING SEQUENCE:
add_tag, oldstruct, tagname, tagValue, newstruct, structyp=structyp
INPUTS:
oldstruct: The original structure (or array of structures)
tagname: string containing the new tag name
tagValue: the initial value of the new tag, e.g. fltarr(5)
or [3,5,6], or 0L, etc.
KEYWORD PARAMETERS:
structyp: a string with the name of the new structure.
if already defined an error is printed.
OUTPUTS:
newstruct: The structure with the new tag it it.
OPTIONAL OUTPUT
NONE
CALLED ROUTINES:
COMBINE_STRUCTS
REVISION HISTORY:
25-OCT-2000, Judith Racusin.
NAME:
ARRAY_EQ
PURPOSE:
Return TRUE if two arrays are equal, else false.
CATEGORY:
Programming
CALLING SEQUENCE:
logical=ARRAY_EQ(array1,array2)
INPUTS:
bigArray - an array of numbers to look in
littleArray - an array to look for matches in bigArray
OUTPUTS:
logical - 0/1
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
17-May-99 WMD Written
NAME:
BELL
PURPOSE:
Ring terminal bell.
CATEGORY:
Programming, Sound, Errors
CALLING SEQUENCE:
bell, [n]
INPUTS:
n = number of rings (def=1). in
KEYWORD PARAMETERS:
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 20 Oct, 1989.
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
CAST
PURPOSE:
Generalized type casting. Converts variables whose type code is out
of the range [LOW,HIGH] into this range.
CATEGORY:
Programming, type conversion
CALLING SEQUENCE:
Result = CAST( X, [LOW [,HIGH]])
INPUTS:
X
Numerical, arbitrary, or a character representation of a number(s).
LOW
Number representing a type code, range (1:9). If greater than 9, it is
set to 9. If less then 1, or not given, it is set to 1.
OPTIONAL INPUT PARAMETERS:
HIGH
Type code, same as LOW. Default value is 9. If provided and less then
LOW, it is set to LOW.
KEYWORD PARAMETERS:
/FIX
Switch. If set, the output is filtered through FPU_FIX, eliminating
floating underflow errors.
OUTPUTS:
If the type of X is < LOW, CAST returns X converted to type LOW.
If the type of X is > HIGH, CAST returns X converted to type HIGH.
Otherwise CAST returns X.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
1) An attempt to convert a string which is NOT a character
representation of a number into a numeric type will yield error.
2) X cannot be a structure or pointer, but can be a structure element.
3) The value 8 for either LOW or HIGH is not allowed (since it
corresponds to structure type). Value of 10 and above is ignored.
PROCEDURE:
Identifies the type of X, and if out of the range given by [LOW,HIGH]
calls the proper conversion routine using the system routine
CALL_FUNCTION. Also uses FPU_FIX and ISNUM from MIDL.
MODIFICATION HISTORY:
Created 25-DEC-1991 by Mati Meron.
Modified 15-JUN-1995 by Mati Meron to accept the new DOUBLECOMPLEX type.
Modified 25-SEP-1998 by Mati Meron. Underflow filtering added.
NAME:
COMBINE_STRUCTS
PURPOSE:
takes two arrays of structures str1,str2 which have the
same number of elements but possibly different tags
and makes another structure which has the same number of elements
but the tags of both str1,str2 and has their respective tags
values copied into it
CATEGORY:
Programming
CALLING SEQUENCE
combine_structs, struct1, struct2, newstruct, structyp=structyp
INPUTS:
struct1,struc2: The two structures to be combined. If structure arrays,
Must contain the same number of structs.
KEYWORD PARAMETERS:
structyp: a string with the name of the new structure.
if already defined the program will crash.
Author Dave Johnston UofM
NAME:
DATATYPE
PURPOSE:
Datatype of variable as a string (3 char or spelled out).
CATEGORY:
Programming
CALLING SEQUENCE:
typ = datatype(var, [flag])
INPUTS:
var = variable to examine. in
flag = output format flag (def=0). in
KEYWORD PARAMETERS:
Keywords:
/DESCRIPTOR returns a descriptor for the given variable.
If the variable is a scalar the value is returned as
a string. If it is an array a description is return
just like the HELP command gives. Ex:
datatype(fltarr(2,3,5),/desc) gives
FLTARR(2,3,5) (flag always defaults to 3 for /DESC).
OUTPUTS:
typ = datatype string or number. out
flag=0 flag=1 flag=2 flag=3 flag=4
UND Undefined 0 UND UND
BYT Byte 1 BYT BIT(8)
INT Integer 2 INT SMALLINT
LON Long 3 LON INTEGER
FLO Float 4 FLT FLOAT
DOU Double 5 DBL Double
COM Complex 6 COMPLEX COMPLEX
STR String 7 STR CHARACTER
STC Structure 8 STC STC
DCO DComplex 9 DCOMPLEX DCOMPLEX
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
Written by R. Sterner, 24 Oct, 1985.
Johns Hopkins University Applied Physics Laboratory.
RES 29 June, 1988 --- added spelled out TYPE.
R. Sterner, 13 Dec 1990 --- Added strings and structures.
R. Sterner, 19 Jun, 1991 --- Added format 3.
R. Sterner, 18 Mar, 1993 --- Added /DESCRIPTOR.
R. Sterner, 1995 Jul 24 --- Added DCOMPLEX for data type 9.
23-Jun-2009 BD added Unit, Long54, Ulong64.
28-FEB-2011 BD Added flag=4 for types used by SQL
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
get_delim
PURPOSE:
returns file delimiter that is appropriate to VMS, UNIX or Windows
CATEGORY:
Programming
CALLING SEQUENCE:
delim=get_delim()
INPUTS:
none
OUTPUTS:
delim=':' if VMS, '\' if Windows, '/' otherwise
PROCEDURE:
checks !version.os system variable
MODIFICATION HISTORY:
Written DMZ (ARC) May 1992
Modified DMZ(SAC) Sept 1997 - added Windows
NAME:
GREEK
PURPOSE:
This function returns the string needed to draw the specified
greek character using either the vector graphics font no. 4,
or PostScript font 9.
If (!d.name eq 'PS') and (!p.font eq 0), then the PostScript
font will be used. Otherwise, the vector font will be used.
CATEGORY:
Programming
CALLING SEQUENCE:
Result = GREEK(Name)
INPUTS:
Name - String specifying the greek character name. Valid
inputs are:
alpha, beta, gamma, delta, epsilon, zeta, eta, theta
iota, kappa, lambda, mu, nu, xi, omicron, pi, rho,
sigma, tau, upsilon, phi, chi, psi, omega
Alpha, Beta, Gamma, Delta, Epsilon, Zeta, Eta, Theta
Iota, Kappa, Lambda, Mu, Nu, Xi, Omicron, Pi, Rho,
Sigma, Tau, Upsilon, Phi, Chi, Psi, Omega
Although not greek, the following characters are also
valid (but will only work with the 'default' font !3):
angstrom, Angstrom, degrees, plus_minus
KEYWORDS:
FORCE_PS - Set to use PostScript font, regardless of the value
of !d.name and !p.font.
PLAIN - Set to just return Name in plain text.
APPEND_FONT - Set to append the characters specifying a
'default' font: !3. That is, if this keyword is
set, then the command
Result=GREEK(theta,/APPEND_FONT)
will return the string
'!9q!3' for PostScript and '!4h!3' for vector
fonts.
OUTPUTS:
Result - The string containing the specified greek character.
EXAMPLE:
Result=GREEK(theta)
In this case, Result='!9q' if !d.name is 'PS' and !p.font is
0; otherwise, Result='!4h'
MODIFICATION HISTORY:
David L. Windt, Bell Labs, September 1998.
windt@bell-labs.com
NAME:
int_defined
PURPOSE:
see if a value is defined and is an integer
CATEGORY:
programming
CALLING SEQUENCE:
logical = INT_DEFINED( whatever )
INPUTS:
whatever - any IDL variable in
KEYWORD PARAMETERS
none
OUTPUTS:
logical - 1 if an integer, 0 if not (or if not defined)
EXAMPLE:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
1999 Written by Bill Davis
NAME:
ISARRAY
PURPOSE:
Tests if the argument is an array.
CATEGORY:
Programming
CALLING SEQUENCE:
flag = isarray(a)
INPUTS:
a = variable to test. in
KEYWORD PARAMETERS:
OUTPUTS:
flag = test result: 0 if not array, else non-zero. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner 20 Mar, 1986.
Checked for undefined variables. RES 25 Aug, 1989.
Johns Hopkins Applied Physics Lab.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
ISNUM
VERSION:
3.0
PURPOSE:
Checks whether the input is a number.
CATEGORY:
Programming.
CALLING SEQUENCE:
Result = ISNUM(X)
INPUTS:
X
Arbitrary, doesn't even have to exist.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
/DOUBLE
Switch. If set the result is 1 only if X is DOUBLE or DCOMPLEX.
/COMPLEX
Switch. If set the result is 1 only if X is COMPLEX or DCOMPLEX.
TYPE
Optional output. See below.
OUTPUTS:
Returns 1 if X is number, 0 otherwise. Output type is byte.
OPTIONAL OUTPUT PARAMETERS:
TYPE
The name of the variable to receive the numeric code of the type of X.
Included for convenience to save an additional call to TYPE.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Using TYPE from MIDL.
MODIFICATION HISTORY:
19-Jul-2009 added U types [Bill Davis]
Created 15-JUN-1995 by Mati Meron.
Modified 5-MAY-1996 by Mati Meron. Added keywords DOUBLE, COMPLEX and
TYPE.
NAME:
LEGEND
PURPOSE:
Create an annotation legend for a plot.
CATEGORY:
Programming, 2-D Plotting
EXPLANATION:
This procedure makes a legend for a plot. The legend can contain
a mixture of symbols, linestyles, Hershey characters (vectorfont),
and filled polygons (usersym). A test procedure, legendtest.pro,
shows legend's capabilities. Placement of the legend is controlled
with keywords like /right, /top, and /center or by using a position
keyword for exact placement (position=[x,y]) or via mouse (/position).
CALLING SEQUENCE:
LEGEND [,items][,keyword options]
EXAMPLES:
The call:
legend,['Plus sign','Asterisk','Period'],psym=[1,2,3]
produces:
-----------------
| |
| + Plus sign |
| * Asterisk |
| . Period |
| |
-----------------
Each symbol is drawn with a plots command, so they look OK.
Other examples are given in optional output keywords.
lines = indgen(6) ; for line styles
items = 'linestyle '+strtrim(lines,2) ; annotations
legend,items,linestyle=lines ; vertical legend---upper left
items = ['Plus sign','Asterisk','Period']
sym = [1,2,3]
legend,items,psym=sym ; ditto except using symbols
legend,items,psym=sym,/horizontal ; horizontal format
legend,items,psym=sym,box=0 ; sans border
legend,items,psym=sym,delimiter='=' ; embed '=' betw psym & text
legend,items,psym=sym,margin=2 ; 2-character margin
legend,items,psym=sym,position=[x,y] ; upper left in data coords
legend,items,psym=sym,pos=[x,y],/norm ; upper left in normal coords
legend,items,psym=sym,pos=[x,y],/device ; upper left in device coords
legend,items,psym=sym,/position ; interactive position
legend,items,psym=sym,/right ; at upper right
legend,items,psym=sym,/bottom ; at lower left
legend,items,psym=sym,/center ; approximately near center
legend,items,psym=sym,number=2 ; plot two symbols, not one
legend,items,/fill,psym=[8,8,8],colors=[10,20,30]; 3 filled squares
INPUTS:
items = text for the items in the legend, a string array.
For example, items = ['diamond','asterisk','square'].
You can omit items if you don't want any text labels.
OPTIONAL INPUT KEYWORDS:
linestyle = array of linestyle numbers If linestyle[i] < 0, then omit
ith symbol or line to allow a multi-line entry.
psym = array of plot symbol numbers. If psym[i] is negative, then a
line connects pts for ith item. If psym[i] = 8, then the
procedure usersym is called with vertices define in the
keyword usersym. If psym[i] = 88, then use the previously
defined user symbol
vectorfont = vector-drawn characters for the sym/line column, e.g.,
['!9B!3','!9C!3','!9D!3'] produces an open square, a checkmark,
and a partial derivative, which might have accompanying items
['BOX','CHECK','PARTIAL DERIVATIVE'].
There is no check that !p.font is set properly, e.g., -1 for
X and 0 for PostScript. This can produce an error, e.g., use
!20 with PostScript and !p.font=0, but allows use of Hershey
*AND* PostScript fonts together.
N. B.: Choose any of linestyle, psym, and/or vectorfont. If none is
present, only the text is output. If more than one
is present, all need the same number of elements, and normal
plot behaviour occurs.
By default, if psym is positive, you get one point so there is
no connecting line. If vectorfont[i] = '',
then plots is called to make a symbol or a line, but if
vectorfont[i] is a non-null string, then xyouts is called.
/help = flag to print header
/horizontal = flag to make the legend horizontal
/vertical = flag to make the legend vertical (D=vertical)
box = flag to include/omit box around the legend (D=include)
clear = flag to clear the box area before drawing the legend
delimiter = embedded character(s) between symbol and text (D=none)
colors = array of colors for plot symbols/lines (D=!P.color)
textcolors = array of colors for text (D=!P.color)
margin = margin around text measured in characters and lines
spacing = line spacing (D=bit more than character height)
pspacing = psym spacing (D=3 characters)
charsize = just like !p.charsize for plot labels
charthick = just like !p.charthick for plot labels
thick = array of line thickness numbers, if used, then linestyle
must also be specified
box_color=color for the box
position = data coordinates of the /top (D) /left (D) of the legend
normal = use normal coordinates for position, not data
device = use device coordinates for position, not data
number = number of plot symbols to plot or length of line (D=1)
usersym = 2-D array of vertices, cf. usersym in IDL manual. (D=square)
/fill = flag to fill the usersym
/left = flag to place legend snug against left side of plot window (D)
/right = flag to place legend snug against right side of plot window
If /right,pos=[x,y], then x is position of RHS and text
runs right-to-left.
/top = flag to place legend snug against top of plot window (D)
/bottom = flag to place legend snug against bottom of plot window
/top,pos=[x,y] and /bottom,pos=[x,y] produce same positions.
If LINESTYLE, PSYM, VECTORFONT, THICK, COLORS, or TEXTCOLORS are
supplied as scalars, then the scalar value is set for every line or
symbol in the legend.
Outputs:
legend to current plot device
OPTIONAL OUTPUT KEYWORDS:
corners = 4-element array, like !p.position, of the normalized
coords for the box (even if box=0): [llx,lly,urx,ury].
Useful for multi-column or multi-line legends, for example,
to make a 2-column legend, you might do the following:
c1_items = ['diamond','asterisk','square']
c1_psym = [4,2,6]
c2_items = ['solid','dashed','dotted']
c2_line = [0,2,1]
legend,c1_items,psym=c1_psym,corners=c1,box=0
legend,c2_items,line=c2_line,corners=c2,box=0,pos=[c1(2),c1(3)]
c = [c1(0)c2(2),c1(3)>c2(3)]
plots,[c(0),c(0),c(2),c(2),c(0)],[c(1),c(3),c(3),c(1),c(1)],/norm
Useful also to place the legend. Here's an automatic way to place
the legend in the lower right corner. The difficulty is that the
legend's width is unknown until it is plotted. In this example,
the legend is plotted twice: the first time in the upper left, the
second time in the lower right.
legend,['1','22','333','4444'],linestyle=indgen(4),corners=corners
; BOGUS LEGEND---FIRST TIME TO REPORT CORNERS
xydims = [corners(2)-corners(0),corners(3)-corners(1)]
; SAVE WIDTH AND HEIGHT
chdim=[!d.x_ch_size/float(!d.x_size),!d.y_ch_size/float(!d.y_size)]
; DIMENSIONS OF ONE CHARACTER IN NORMALIZED COORDS
pos = [!x.window(1)-chdim(0)-xydims(0) $
,!y.window(0)+chdim(1)+xydims(1)]
; CALCULATE POSITION FOR LOWER RIGHT
plot,findgen(10) ; SIMPLE PLOT; YOU DO WHATEVER YOU WANT HERE.
legend,['1','22','333','4444'],linestyle=indgen(4),pos=pos
; REDO THE LEGEND IN LOWER RIGHT CORNER
You can modify the pos calculation to place the legend where you
want. For example to place it in the upper right:
pos = [!x.window(1)-chdim(0)-xydims(0),!y.window(1)-xydims(1)]
Common blocks:
none
Procedure:
If keyword help is set, call doc_library to print header.
See notes in the code. Much of the code deals with placement of the
legend. The main problem with placement is not being
able to sense the length of a string before it is output. Some crude
approximations are used for centering.
Restrictions:
Here are some things that aren't implemented.
- An orientation keyword would allow lines at angles in the legend.
- An array of usersyms would be nice---simple change.
- An order option to interchange symbols and text might be nice.
- Somebody might like double boxes, e.g., with box = 2.
- Another feature might be a continuous bar with ticks and text.
- There are no guards to avoid writing outside the plot area.
- There is no provision for multi-line text, e.g., '1st line!c2nd line'
Sensing !c would be easy, but !c isn't implemented for PostScript.
A better way might be to simply output the 2nd line as another item
but without any accompanying symbol or linestyle. A flag to omit
the symbol and linestyle is linestyle[i] = -1.
- There is no ability to make a title line containing any of titles
for the legend, for the symbols, or for the text.
Side Effects:
Modification history:
10-Aug-07 add debug keyword. Don't die if more lines than labels. [BD]
01-Mar-99 squeeze legend closer to top [Bill Davis]
write, 24-25 Aug 92, F K Knight (knight@ll.mit.edu)
allow omission of items or omission of both psym and linestyle, add
corners keyword to facilitate multi-column legends, improve place-
ment of symbols and text, add guards for unequal size, 26 Aug 92, FKK
add linestyle[i]=-1 to suppress a single symbol/line, 27 Aug 92, FKK
add keyword vectorfont to allow characters in the sym/line column,
28 Aug 92, FKK
add /top, /bottom, /left, /right keywords for automatic placement at
the four corners of the plot window. The /right keyword forces
right-to-left printing of menu. 18 Jun 93, FKK
change default position to data coords and add normal, data, and
device keywords, 17 Jan 94, FKK
add /center keyword for positioning, but it is not precise because
text string lengths cannot be known in advance, 17 Jan 94, FKK
add interactive positioning with /position keyword, 17 Jan 94, FKK
allow a legend with just text, no plotting symbols. This helps in
simply describing a plot or writing assumptions done, 4 Feb 94, FKK
added thick, symsize, and clear keyword Feb 96, W. Landsman HSTX
David Seed, HR Wallingford, d.seed@hrwallingford.co.uk
allow scalar specification of keywords, Mar 96, W. Landsman HSTX
added charthick keyword, June 96, W. Landsman HSTX
DM, allow choosing of color for box
NAME:
maxstruct
PURPOSE:
find the maximum of a structure
(ignores structures within the input structure)
CATEGORY:
Programming, Math
EXAMPLE:
IDL> structure = { a: 2.3, b:10, c:[2.1,22.3], d:'Hi Mom' }
IDL> print, maxstruct(structure)
22.3000
IDL> structure2 = { a: 2.3, b:10, c:[2.1,99], d:'Hi Mom' }
IDL> structure = [structure, structure2]
IDL> print, maxstruct(structure)
99.0000
IDL> inStruc = {a:77., b:88., c:101.}
IDL> structure = { a: 2.3, b:10, c:[2.1,22.3], d:'Hi Mom', e:inStruc }
IDL> print, totstruct(structure)
101.000
NOTES:
will not consider values in sub-structures
MODIFICATIONS
25-Mar-2008 handles arrays of structures, and go into nested
structures [BD]
01-Dec-2006 Ignore non-numeric structure elements [BD]
NAME:
minmax
PURPOSE:
print the min and the max of an array
CATEGORY:
programming
CALLING SEQUENCE:
minmax, a
INPUTS:
a- an array in
KEYWORD PARAMETERS
OUTPUTS:
none (just printing to IDL session)
EXAMPLE:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
1998 Written by Bill Davis
NAME:
Msg_Bell
PURPOSE:
Print a message to the IDL session and ring a bell
CATEGORY:
Programming. Terminal Outpout
CALLING SEQUENCE:
Msg_Bell, msg, nrings
INPUTS:
msg - string to print to the IDL session
nrings - (OPTIONAL) # of times to ring
KEYWORD PARAMETERS:
OUTPUTS:
EXAMPLE:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
1997 Written by Bill Davis
NAME:
NEARESTI_ARRAY
PURPOSE:
Return indices of big input array closest to the values
in the little input array.
CATEGORY:
Programming, Search, Arrays
CALLING SEQUENCE:
i=NEARESTI_ARRAY(bigArray,littleArray)
INPUTS:
bigArray - an array of numbers to look in
littleArray - an array to look for matches in bigArray
OUTPUTS:
ret_indices - the indices of bigarray closest to values of littleArray
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
09-Oct-2009 make loop index a LONG
17-Jul-97 WMD Written
NAME:
NEARESTI
PURPOSE:
Return index of input array closest to the value of "pt"
CATEGORY:
Programming, Search
CALLING SEQUENCE:
i=NEARESTI(array,pt)
INPUTS:
array - an array of numbers
pt - a number
OUTPUTS:
iclosest - the index of the array value closet to "pt"
COMMON BLOCKS:
NOTES:
limited by precision. e.g.,
IDL> print, nearesti([2,3], 2.5000001)
0
MODIFICATION HISTORY:
16-Jul-02 WMD Handle really big "pt"
03-Dec-99 WMD make input a scalar, if necessary
17-Jul-97 WMD more like Harris Library version - faster
29-Mar-88 WMD Written
NAME:
PRONAME
PURPOSE:
This function retrieves the name of the currently active procedure.
CATEGORY:
Programming
INPUTS:
none
OUTPUT:
The output is a string containing the name of the procedure
KEYWORD:
pr0; set kw to genetae a prompt corresponding to proname.
MODIFICATION HISTORY:
16-Aug-2010 fixed a case where name was 3rd word
10-Apr-2007 Added prompt 'pr0' keyword [BPL]
20-Aug-07 add checks for array length (when window too narrow,
array elements are not right)
Written by B.P. LeBlanc following a hint by Bill Davis, 01-DEC-2006
NAME:
PTR_FREE_RECURSIVELY
PURPOSE:
This routine when passed a pointer will free up any memory associated
with that pointer. This includes structures, which could contain
pointers, or other structures which could in turn contain more
pointers. It also destroys objects it comes across. It can also
cope with null pointers that are found on its travels.
CATEGORY:
programming
CALLING SEQUENCE:
Ptr_Free_Recursively, AValidPointer
INPUTS:
InitialPointer: The pointer whose 'heap memory hierachy' will be freed.
KEYWORD PARAMETERS:
None.
OUTPUTS:
None.
COMMON BLOCKS:
None, of course.
SIDE EFFECTS:
Well as far as I can see, there are none. But please try and find them
so I can improve the program.
RESTRICTIONS:
The program will destroy any objects it meets but if the cleanup
methods for those objects are not tight then there will be leakage.
There are no restrictions on the number of levels of referencing -
the routine is totally general.
Also you must have my modified version of coyotelist (DWF).
EXAMPLE:
First you have to have a valid pointer and while obviously your hierachy
doesn't have to be as complictated as this, the example shows just what
it can do.
ThisPointer = Ptr_New( [Ptr_New(), $
Ptr_New({h:'hello', point0:ptr_new(ptr_new(ptr_new($
{string:'hello', point1:ptr_new(),point2:ptr_new('hello')}))), $
point3:ptr_new(), b:'bye'}), $
Ptr_New('Hello'), $
Ptr_New({Object:Obj_New('Coyotelist'), Point4:Ptr_New(), $
Point5:[ptr_new('hello'),ptr_new('bye')]}) $
])
Ptr_Free_Recursively, ThisPointer
............and all your memory will be gone.
MODIFICATION HISTORY:
Written by: Phil Aldis
March 3rd, 1999: Fixed the last few bugs and attempted to make the comments
a bit clearer. PJA
AUTHOR:
Philip Aldis
14 Milton Road,
Bentley Heath,
B93 8AA.
Phone: 0044 1564 773437
E-Mail:philaldis@geocities.com
NAME:
rem_elem
PURPOSE:
return subscripts of input array remaining after elements in
a second array are removed
CATEGORY:
Programming
INPUT PARAMETERS:
inarray - array to search/remove from
remarray - array of elements to search/remove from inarray
OUTPUT PARAMETERS:
count - number of elements (subscripts) returned
CALLING SEQUENCE:
ss = rem_elem(inarray,remarray) ; subscripts remaining or -1
HISTORY:
slf, 20-jan-1993
slf, 7-feb-1993 - documentation carification and variable name change
NAME:
sameType
PURPOSE:
make two variables the same numerical type
CATEGORY:
Programming
CALLING SEQUENCE:
IDL> sametype, x, y
INPUTS:
inputs - numerical scalars or arrays
(not for structures or strings)
OUTPUTS:
inputs are re-typed, as needed
MODIFICATION HISTORY:
30-Jan-2007 Written by Bill Davis, PPPL
NAME: SIZE_STRUCT PURPOSE: Obtain the size in bytes of an IDL structure definition. CATEGORY: Programming CALLING SEQUENCE: bytes = size_struct( structure ) examples: print, size_struct( "fdq_sdf" ) INPUTS: structure = a structure variable or a string giving the structure name as known by IDL (help,/struct,variable). /PRINT = to print all sub structure sizes. inputs/outputs used recursively: struct = the structure VARIABLE currently analyzed. Max_Field_Size = size of the largest field found in structure. RESULT: Function returns the total size in bytes of a structure element. EXPLANATION: For most applications this function is superceded by use of the /LENGTH keyword to the intrinsic N_TAGS function introduced in IDL V2.3.0 PROCEDURE: Strategy is to call size_struct recursively if structure contains sub-structures. Otherwise just add up the field sizes. MODIFICATION HISTORY: written 1990 Frank Varosi STX @ NASA/GSFC (using align_struct). Converted to IDL V5.0 W. Landsman September 1997
NAME:
totstruct
PURPOSE:
find the total of numerical values in a structure
(handles structures within the input structure)
CATEGORY:
Programming, Math
EXAMPLE:
IDL> structure = { a: 2.3, b:10, c:[2.1,22.3], d:'Hi Mom'}
IDL> print, totstruct(structure)
36.7
IDL> structure2 = { a: 2.3, b:10, c:[2.1,99], d:'Hi Mom' }
IDL> structure = [structure, structure2]
IDL> print, totstruct(structure)
99.0000
IDL> inStruc = {a:77., b:88., c:101.}
IDL> structure = { a: 2.3, b:10, c:[2.1,22.3], d:'Hi Mom', e:inStruc }
IDL> print, totstruct(structure)
302.700
NOTES:
will not consider values in sub-structures
MODIFICATIONS
25-Mar-2008 handles arrays of structures, and go into nested
structures [BD]
01-Dec-2006 Ignore non-numeric structure elements [BD]
NAME:
TYPE
VERSION:
3.0
PURPOSE:
Finds the type class of a variable.
CATEGORY:
Programming.
CALLING SEQUENCE:
Result = TYPE(X)
INPUTS:
X
Arbitrary, doesn't even need to be defined.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the type of X as a long integer, in the (0,9) range.
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Extracts information from the SIZE function.
MODIFICATION HISTORY:
Created 15-JUL-1991 by Mati Meron.
Category: Smoothing
[List of Routines]
NAME:
AMEDIAN
PURPOSE:
Works the same as MEDIAN, but the effect tapers off at the edges.
CATEGORY:
Smoothing, Math
CALLING SEQUENCE:
Result = AMEDIAN( ARRAY, WIDTH )
INPUT PARAMETERS:
ARRAY = One or two-dimensional array to be median filtered.
WIDTH = Width of the median filter box.
OPTIONAL KEYWORD PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
ARRAY must be one or two-dimensional.
PROCEDURE:
A larger array is constructed with the border filled with the reflected
edges of the original array. Then MEDIAN is applied to this larger
array, and the area corresponding to the original array is returned as
the result of the function.
MODIFICATION HISTORY:
26-Oct-2010 added edge keyword
15-Jul-2008 for True Color images (dimensioned [3,xsize,ysize]),
smooth over each color.
12-Jun-01 Made work for 1 dimension of 2 being small. [BD]
21-Feb-01 Just return array if width < or = 1. [BD]
WRITTEN by William Thompson, February 1993.
NAME:
medsmoothedge
PURPOSE:
Median smoothing of an array, including handling edges.
CATEGORY:
Smoothing
CALLING SEQUENCE:
SMarray - medsmoothedge( ARRAY, WINDOW_WIDTH )
INPUTS:
ARRAY - The array to be smoothed
WINDOW_WIDTH - The full width of the window over which the median is
determined for each point.
OUTPUT:
SMarray - smoothed array
SUBROUTINES CALLED:
MEDIAN, to find the median, and smoothedge
PROCEDURE:
Each point is replaced by the median of the nearest WINDOW of points.
the rows aroung the edge, which are not smoothed by MEDIAN, are
replaced by those from calling smoothedge.pro (so are not median-smoothed)
REVISION HISTORY:
28-Aug-2012 Written by Bill Davis.
NAME:
MEDSMOOTH
PURPOSE:
Median smoothing of a vector, including point near it's ends.
CATEGORY:
Smoothing, Math
CALLING SEQUENCE:
SMOOTHED = MEDSMOOTH( VECTOR, WINDOW_WIDTH )
INPUTS:
VECTOR = The vector to be smoothed
WINDOW = The full width of the window over which the median is
determined for each point.
OUTPUT:
Function returns the smoothed vector
SUBROUTINES CALLED:
MEDIAN, to find the median
PROCEDURE:
Each point is replaced by the median of the nearest WINDOW of points.
The width of the window shrinks towards the ends of the vector, so that
only the first and last points are not filtered. These points are
replaced by forecasting from smoothed interior points.
REVISION HISTORY:
Written, H. Freudenreich, STX, 12/89
H.Freudenreich, 8/90: took care of end-points by shrinking window.
NAME:
poly_smooth
PURPOSE:
Reduce noise in 1-D data (e.g. time-series, spectrum)
but retain dynamic range of variations in the data by
applying a least squares smoothing polynomial filter,
also called the Savitzky-Golay smoothing filter.
The low-pass filter coefficients are computed by effectively
least-squares fitting a polynomial in moving window,
centered on each data point, so the new value will be the
zero-th coefficient of the polynomial. Approximate first derivates
of the data can be computed by using first degree coefficient of
each polynomial, and so on. The filter coefficients for a specified
polynomial degree and window width are computed independent of any
data, and stored in a common block. The filter is then convolved
with the data array to result in smoothed data with reduced noise,
but retaining higher order variations (better than averaging).
CATEGORY:
Smoothing, Math
CALLING SEQUENCE:
spectrum = poly_smooth( data, width, DEGREE=4 )
INPUTS:
data = 1-D array, such as a spectrum or time-series.
width = total number of data points to use in filter convolution,
(default = 5, using 2 past and 2 future data points),
must be larger than DEGREE of polynomials, and a guideline is
make WIDTH between 1 and 2 times the FWHM of desired features.
KEYWORDS:
DEGREE = degree of polynomials to use in designing the filter
via least squares fits, (default DEGREE = 2), and
the higher degrees will preserve sharper features.
NLEFT = # of past data points to use in filter convolution,
excluding current point, overrides width parameter,
so that width = NLEFT + NRIGHT + 1. (default = NRIGHT)
NRIGHT = # of future data points to use (default = NLEFT).
DERIV_ORDER = order of derivative desired (default = 0, no derivative).
COEFFICIENTS = optional output of the filter coefficients applied,
but they are all stored in common block for reuse, anyway.
RESULTS:
Function returns the data convolved with polynomial filter coefs.
COMMON BLOCKS:
common poly_smooth, degc, nlc, nrc, coefs, ordermax
PROCEDURE:
As described in Numerical Recipies, sec.14.8, Savitsky-Golay filter.
Matrix of normal eqs. is formed by starting with small terms
and then adding progressively larger terms (powers).
The filter coefficients of up to derivative ordermax are stored
in common, until the specifications change, then recompute coefficients.
Coefficients are stored in convolution order, zero lag in the middle.
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC 1993.
NAME:
quickdespike
PURPOSE:
Quick way (execution-wise) to remove single-element spikes.
CATEGORY:
Smoothing
CALLING SEQUENCE:
IDL> smoothedData = despike( data )
INPUTS:
input = 1-D or 2-D data array.
KEYWORDS
spike - value that is considered a spike (or higher)
DEFAULT= 3 times the difference between the
average and the minimum.
downward - if = 0, will not check for downward spikes
lowest - for downward pointing spikes, fraction of points to
check for ones "percent" below this value (DEFAULT=0.333)
percent - (see above) DEFAULT = 1%
replacement - value to replace spikes with
EXAMPLE:
IDL> mdsopen, 'usxr', 130000
IDL> y=mdsvalue('\USXR_HUP_00:RAW')
IDL> d=quickdespike( y, spike=20 )
IDL> plot,y
IDL> oplot,d,color=mk_color('red')
To test:
IDL> s = quickdespike( /plot )
To test not needing despiking:
IDL> d = replicate(20,100)+randomu(seed,100)*5
IDL> s= quickdespike( d, /plot )
NOTE:
if keyword "spike" not present, will use a value 3 times as large
as the difference between the average and the minimum. Since this
is not so good if there are no spikes, the maximum of the data set
must be 4 times this, otherwise, just use 0.9*2^16.
spikes way below the average will just be flipped around before
removing ones above. The identification of ones below are not as
good. Test your data !!!
MODIFICATION HISTORY:
27-Oct-2010 added REPLACEMENT keyword
15-Mar-2010 cleaned up
30-Sep-2009 Written by Bill Davis, PPPL
NAME:
resample
PURPOSE:
Resample a vector with triangular smoothing.
CATEGORY:
Smoothing
CALLING SEQUENCE:
smallerVector = resample( VECTOR, nth )
INPUTS:
VECTOR = The vector to be smoothed
nth = The full width of the window over which the median is
determined for each point (if even, use window+1).
OUTPUT:
Function returns every nth point of the smoothed input vector
KEYWORDS:
Indices - Optionally returned. Indices of resulting vector
Guass - if set, will do psuedo-gaussian weighting, rather than triagular
SUBROUTINES CALLED:
PROCEDURE:
Each point is replaced by triangular weighting of the nearest WINDOW of points.
The width of the window shrinks towards the ends of the vector.
LIMITATION:
This type of looping is inherently slow in IDL.
Should make a FORTRAN routine based on
BDAVIS$:[IDL.MDS.FOR]BCSMOOTH.FOR or interpwf.for &
use a CALL_EXTERNAL
REVISION HISTORY:
Written, Bill Davis. 23-Mar-00
NAME:
SMOOTH2
PURPOSE:
Do multiple smoothing. Gives near Gaussian smoothing.
CATEGORY:
Smoothing
CALLING SEQUENCE:
b = smooth2(a, w)
INPUTS:
a = array to smooth (1,2, or 3-d). in
w = smoothing window size. in
KEYWORD PARAMETERS:
EDGE_TRUNCATE - as in SMOOTH
OUTPUTS:
b = smoothed array. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 8 Jan, 1987.
Johns Hopkins University Applied Physics Laboratory.
RES 14 Jan, 1987 --- made both 2-d and 1-d.
RES 30 Aug, 1989 --- converted to SUN.
R. Sterner, 1994 Feb 22 --- cleaned up some.
25-Apr-00 Added EDGE_TRUNCATE keyword. [BD]
06-Jul-2009 for RGB images, smooth component separately [BD]
limit smoothing width to dimension of data
Copyright (C) 1987, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
smoothedge
PURPOSE:
smooth a 2-D array using /edge_truncate, but then smooth the
remaining rows and columns within width/2 of the edge even more.
CATEGORY:
Smoothing
CALLING SEQUENCE:
IDL> smarray = smoothedge( array, nsmooth )
INPUTS:
array - a 2-D array. (If 2-D array, will just call smooth)
KEYWORD PARAMETERS:
Inputs:
any keywords will be passed directly to IDL smooth routine
nsmooth - a number passed to smooth routine
OUTPUTS:
smarray - smoothed array
EXAMPLE:
array = dist(100,100)+randomu(seed,100,100)*20
!p.multi=[0,2,0]
thcont, array
thcont, smoothedge(array, 11)
NOTES:
MODIFICATION HISTORY:
28-Aug-2012 smooth corners, as well
04-May-2009 WRITTEN by Bill Davis, PPPL
NAME:
smoothtruecolor
PURPOSE:
smooth a true color array 1 component at a time.
CATEGORY:
Smoothing
CALLING SEQUENCE:
IDL> smarray = smoothTrueColor( array, nsmooth )
INPUTS:
array - a 3xNXxNY array. (If 2-D array, will just call smooth)
nsmooth - a number passed to smooth routine
KEYWORD PARAMETERS:
Inputs:
any keywords will be passed directly to IDL smooth routine
OUTPUTS:
smarray - smoothed array
EXAMPLE:
array = dist(100,100)+randomu(seed,100,100)*20
array = [[array], [array], [array]]
array = reform( array, 3, 100, 100 )
!p.multi=[0, 2,0]
thcont, array
thcont, smoothtruecolor(array, 11)
NOTES:
MODIFICATION HISTORY:
09-Nov-2011 Written by Bill Davis, PPPL
NAME:
trismooth
PURPOSE:
Triangular smoothing of a vector, including points near the ends.
CATEGORY:
Smoothing
CALLING SEQUENCE:
SMOOTHED = trismooth( VECTOR, WINDOW_WIDTH )
INPUTS:
VECTOR = The vector to be smoothed
WINDOW_WIDTH = The full width of the window over which the weighted
average is determined for each point (if even, use window+1).
KEYWORDS:
GAUSS - if set, weighting is gaussian, rather than triangular
OUTPUT:
Function returns the smoothed vector
SUBROUTINES CALLED:
PROCEDURE:
Each point is replaced by triangular weighting of the nearest WINDOW of points.
The width of the window shrinks towards the ends of the vector.
REVISION HISTORY:
Written, Bill Davis. 23-Mar-00, per Michael Bell
Category: Strings
[List of Routines]
NAME:
BreakString
PURPOSE:
Break a string up and return a string array
CATEGORY:
Strings
CALLING SEQUENCE:
IDL> str_array = BreakString(longString)
INPUTS:
longString = a string of words
KEYWORD PARAMETERS:
Optional Keywords:
MAXLENGTH - Maximum length of array elements of output (else=72)
DELIMITER - delimiter, else ' '
(see WORDARRAY for multispace delmiters')
COMPRESS - if set, squeeze out extra imbedded blanks
OUTPUTS:
str_array = returned array of strings out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> line = '\ENGINEERING::OPERATIONS.PC_OH_BR_1_CUR_1'
IDL> newLines = BreakString( line, MAXLENGTH=25, DELIM=':' )
NOTES:
Can be used as a replacement for obsolete str_sep routine
MODIFICATION HISTORY:
31-Jan-02 bug fix and speed improvement
1-Apr-99 Written by Bill Davis, PPPL
NAME:
breaktext
PURPOSE:
break up (justify) text so lines not longer than a certain length.
CATEGORY:
strings
CALLING SEQUENCE:
IDL> newText = breakText( text )
INPUTS:
text - string array or scalar
KEYWORD PARAMETERS:
maxLength - number of characters per line (DEFAULT=72)
delim - what to break lines with (default is a line feed)
OUTPUTS:
string array returned
EXAMPLE:
text = ['This is the first line this is the second', ' ', $
'123456789 123456789 123456789 123456789 123456789 ']
wrapped = breaktext( text, delim=' ', maxlength=25 )
text = strconcat(replicate('blah ', 200)
wrapped = breaktext( text, delim=' ', maxlength=73 )
NOTE:
MODIFICATION HISTORY:
14-Aug-2008 Written by Bill Davis, PPPL
NAME:
charSize2Fit
PURPOSE:
compute charsize for a string to fit in horizontal # of pixels
CATEGORY:
strings
CALLING SEQUENCE:
IDL> charsize= charsize2fit( charstr, pixels)
INPUTS:
charstr - character string to plot
pixels - # of horizontal pixels character string must fit into
KEYWORD PARAMETERS:
nchars - overrides charstr size
OUTPUTS:
charsize - character size that can be used in call to xyouts
EXAMPLE:
IDL> pixels = 100
IDL> window,/fr, xsize=pixels, ysize=100
IDL> charstr='Hi to all you folks out there'
IDL> xyouts, 0,.5, charStr, charsize=charsize2fit( charstr, pixels )
25-Jul-2012 added nchars keyword
WRITTEN 06-Jul-2012 by Bill Davis
NAME:
delfromlist
PURPOSE:
delete ith element from a list
CATEGORY:
Strings, Lists
CALLING SEQUENCE:
newList = delfromlist( list, idel )
INPUTS:
list - string array in
idel - integer (starting at 0) of line not wanted in
idel may also be an array of indices.
KEYWORD PARAMETERS:
OUTPUTS:
newList: string array without ith line
EXAMPLE:
IDL> list=['a','b','c','d']
IDL> print,delfromlist(list,1)
a c d
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
11-Feb-2014 "list" now a reserved word, so use square brackets
09-Dec-02 Works when deletion index is an array
Written 03-Mar-99 by Bill Davis
NAME:
findAllChar
PURPOSE:
Find all appearances of a character in a scalar string
CATEGORY:
Strings
CALLING SEQUENCE:
positions = findAllChar( ST, CHAR )
INPUTS:
ST - scalar String
CHAR- Character to find
KEYWORDS
Optional:
nFound - # of occurences of CHAR
EXAMPLE:
IDL> a = "I call that 'fun'"
IDL> print, findAllChar(a, "'")
12 16
REVISIONS HISTORY
Written Bill Davis, July, 2007
NAME:
GETTOK
PURPOSE:
Function to retrieve the first part of the string
until the character char is encountered.
CATEGORY:
Strings
CALLING SEQUENCE:
token = gettok( st, char )
INPUT:
char - character separating tokens, scalar string
INPUT-OUTPUT:
st - (scalar) string to get token from (on output token is removed)
OUTPUT:
token - scalar string value is returned
EXAMPLE:
If ST is 'abc=999' then gettok(ST,'=') would return
'abc' and ST would be left as '999'
HISTORY
version 1 by D. Lindler APR,86
Remove leading blanks W. Landsman (from JKF) Aug. 1991
Add TABCHAR keyword, so token = gettok( st, '@', TABCHAR='@') will
just treat tabs as delimiters.
NAME:
GETWRD
PURPOSE:
Return the n'th word from a text string.
CATEGORY:
Strings
CALLING SEQUENCE:
wrd = getwrd(txt, n, [m])
INPUTS:
txt = text string to extract from. in
n = word number to get (first = 0 = def). in
m = optional last word number to get. in
KEYWORD PARAMETERS:
Keywords:
LOCATION = l. Return word n string location.
DELIMITER = d. Set word delimiter (def = space & tab).
/LAST means n is offset from last word. So n=0 gives
last word, n=-1 gives next to last, ...
If n=-2 and m=0 then last 3 words are returned.
/NOTRIM suppresses whitespace trimming on ends.
NWORDS=n. Returns number of words in string.
OUTPUTS:
wrd = returned word or words. out
COMMON BLOCKS:
getwrd_com
NOTES:
Note: If a NULL string is given (txt="") then the last string
given is used. This saves finding the words again.
If m > n wrd will be a string of words from word n to
word m. If no m is given wrd will be a single word.
n<0 returns text starting at word abs(n) to string end
If n is out of range then a null string is returned.
See also nwrds.
MODIFICATION HISTORY:
Ray Sterner, 6 Jan, 1985.
R. Sterner, Fall 1989 --- converted to SUN.
R. Sterner, Jan 1990 --- added delimiter.
R. Sterner, 18 Mar, 1990 --- added /LAST.
R. Sterner, 31 Jan, 1991 --- added /NOTRIM.
R. Sterner, 20 May, 1991 --- Added common and NULL string.
R. Sterner, 13 Dec, 1992 --- Made tabs equivalent to spaces.
R. Sterner, 4 Jan, 1993 --- Added NWORDS keyword.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
labelfit
PURPOSE:
determine character size to make a label fit in a space
CATEGORY:
Strings
CALLING SEQUENCE:
IDL> newCharSize= labelfit( label, width=width )
INPUTS:
width - pixels to fit label into
charsize - starting charactersize (max) Default=3
minsize - minimum character size allowed
pad - # of blank characters to allow around string (default=2)
RETURNED:
shortLabel - if charsize needs to be less than minsize to fit
everything, make a short label that fits
EXAMPLES:
IDL> print, labelfit('Hi mom', width=40, charsize=20 )
5.80002
IDL> label = 'abcdefghijklmnopqrstuvwxyz'
IDL> print, labelfit(label, width=400 )
1.65000
IDL> print, labelfit(label, width=400, minsize=2, shortLabel=shortLabel )
2.00000
IDL> help,shortlabel
SHORTLABEL STRING = '...jklmnopqrstuvwxyz'
MODIFICATION HISTORY:
15-Sep-2011 Written by Bill Davis, PPPL
NAME: lastchar PURPOSE: return last character of a string CATEGORY: Strings CALLING SEQUENCE: lastchar = lastchar( str ) INPUTS: str - scalar String KEYWORDS EXAMPLE: IDL> dir ='/u/bdavis IDL> if lastchar(dir) ne getdelim() then dir=dir+getdelim() REVISIONS HISTORY Written by Bill Davis, 11-Oct-2007
NAME: nonAlphaNum
PURPOSE: find position of first character which are not alphanumeric
(0-9, a-z, A-Z & _)
if none found, returns strlen(input)
CATEGORY:
Strings, Character Search
CALLING SEQUENCE:
pos = nonAlphaNum( mdsSigName )
MODIFICATION HISTORY:
2001 Written by Bill Davis
NAME: nonNumber
PURPOSE: find position of first character which is not a number
(0-9). if none found, returns -1.
CATEGORY:
Strings, Character Search
CALLING SEQUENCE:
pos = nonNumber( mdsSigName )
EAMPLE:
IDL> a='user/core.3889'
IDL> print,nonnumber(a,/reverse)
9
IDL> print,strmid(a,0,nonnumber(a,/reverse)+1)
user/core.
MODIFICATION HISTORY:
01-Nov-2004 Written by Bill Davis
NAME:
numberPos
PURPOSE:
find position of first character which is a number
if none found, returns strlen(input)
CATEGORY:
Strings, Character Search
CALLING SEQUENCE:
pos = numberPos( mdsSigName )
MODIFICATION HISTORY:
15-Jul-2008 Written by Bill Davis
NAME:
NWORDS
PURPOSE:
Return the number of words in the given text string or string array.
CATEGORY:
Strings
CALLING SEQUENCE:
n = nwords(txt)
INPUTS:
txt = text string to examine. in
KEYWORD PARAMETERS:
Keywords:
DELIMITER = d. Set delimiter character (def = space).
OUTPUTS:
n = number of words found. out
COMMON BLOCKS:
NOTES:
Notes: See also getwrd.
MODIFICATION HISTORY:
20-Feb-2006 if string is a Delete Character, don't count as a word.
(Sometimes returned from database apps.)
20-Apr-2004 if a non-character, return number of array elements
09-Jun-2000 do not count blank or null elements in an array
Bill Daivs, Sep. '97, made to handle string arrays
R. Sterner, 7 Feb, 1985.
Johns Hopkins University Applied Physics Laboratory.
RES 4 Sep, 1989 --- converted to SUN.
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
padstrings
PURPOSE:
pad column widths so each text field takes up same amount of
space. Remove any tabs.
CATEGORY:
Strings
CALLING SEQUENCE:
newStrArray = padstrings( strArrar, minWidth=minWidth )
INPUTS:
strArrar - Array of strings
KEYWORD PARAMETERS:
Inputs:
minWidth - minimum width of string, default to max in strArray
right - if set, will pad with blanks on right, rather than on left
OUTPUTS:
outArray - string array with smaller elements padded with blanks
EXAMPLE
IDL> in=['bbkbbk', 'dd', 'eeeeebbbbbb','dldl']
IDL> out = strArray( in )
IDL> for k=0,3 do help, out[k]
STRING = ' bbkbbk'
STRING = ' dd'
STRING = 'eeeeebbbbbb'
STRING = ' dldl'
MODIFICATION HISTORY:
Written 26-Mar-2010 by Bill Davis
NAME:
REMCHAR
PURPOSE:
Remove all appearances of character (char) from string (st)
CATEGORY:
Strings
CALLING SEQUENCE:
REMCHAR, ST, CHAR
INPUTS:
ST - String from which character will be removed.
CHAR- Character to be removed from string.
EXAMPLE:
If a = 'a,b,c,d,e,f,g' then
IDL> remchar,a, ','
will give a = 'abcdefg'
REVISIONS HISTORY
Written D. Lindler October 1986
Test if empty string needs to be returned W. Landsman Feb 1991
NAME:
REPCHR
PURPOSE:
Replace all occurrences of one character with another in a text string.
CATEGORY:
Strings
CALLING SEQUENCE:
new = repchr(old, c1, [c2])
INPUTS:
old = original text string. in
c1 = character to replace. in
c2 = character to replace it with. in
default is space.
KEYWORD PARAMETERS:
OUTPUTS:
new = edited string. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 28 Oct, 1986.
Johns Hopkins Applied Physics Lab.
RES 1 Sep, 1989 --- converted to SUN.
R. Sterner, 27 Jan, 1993 --- dropped reference to array.
Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
REPSTR
PURPOSE:
Replace all occurences of one substring by another.
CATEGORY:
Strings
EXPLANATION:
Meant to emulate the string substitution capabilities of text editors
CALLING SEQUENCE:
result = repstr( obj, in, out )
INPUT PARAMETERS:
obj = object string for editing, scalar or array
in = substring of 'obj' to be replaced, scalar
OPTIONAL INPUT PARMETER:
out = what 'in' is replaced with, scalar. If not supplied
then out = '', i.e. 'in' is not replaced by anything.
KEYWORDS:
INSENSITIVE - if set, then replace string regardless of case
("in" will go in without any case changes)
OUTPUT PARAMETERS:
Result returned as function value. Input object string
not changed unless assignment done in calling program.
PROCEDURE:
Searches for 'in', splits 'obj' into 3 pieces, reassembles
with 'out' in place of 'in'. Repeats until all cases done.
EXAMPLE:
If a = 'I am what I am' then print,repstr(a,'am','was')
will give 'I was what I was'.
MODIFICATION HISTORY:
18-Nov-2008 added keyword INSENSITIVE
14-Sep-04 made to work! Bill Davis
Converted to IDL V5.0 W. Landsman September 1997
Accept vector object strings, W. Landsman HSTX, April, 1996
Written by Robert S. Hill, ST Systems Corp., 12 April 1989.
NAME:
sqlfixspecialchars
PURPOSE:
Encapsulate special characters so they can work in SQL text insertions
The special characters are '%', '^', '$', '*', '@', '#', '(', '!', ')', '?'
CATEGORY:
Strings
CALLING SEQUENCE:
new = sqlfixspecialchars(old)
INPUTS:
old = original text string. in
c2 = character to replace it with. in
default is space.
KEYWORD PARAMETERS:
replace - if set, replace any special characters with an underscore
numerical - if set, replace numerical signs '-', '+', '*', and '/'
OUTPUTS:
new = edited string. out
EXAMPLE:
IDL> in_string = 'high $ jog $ !'
IDL> print,fixspecialchars(in_string)
high '$$' jog '$$' '!!'
COMMON BLOCKS:
NOTES:
uses repstr.pro
MODIFICATION HISTORY:
22-May-2015 BD replace numerical operators with characters.
06-Mar-2007 written by Bill Davis
NAME:
StrArraySame
PURPOSE:
Returns TRUE if two strings, or string arrays, are identical, else FALSE
CATEGORY:
Strings
CALLING SEQUENCE:
Result = StrArraySame( STRING1, STRING1 )
INPUTS:
STRING1 & STRING1
Character strings.
KEYWORD PARAMETERS:
IGNORECASE - if set then ignore case in comparison
OUTPUTS:
Returns 1 if the words in two strings, or string arrays are identical,
else 0.
e.g. 'ece1 ece2' is considered equal to ['ece1','ece2']
OPTIONAL OUTPUT PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
MODIFICATION HISTORY:
Created 19-Sep-97 by Bill Davis
NAME:
strconcat
PURPOSE:
Concatenate a string array into single string,
or a matrix of strings into a string array.
CATEGORY:
Strings
CALLING:
string = strconcat( string_array )
INPUTS:
string_array = array of strings or numbers, if numbers they
will be converted to strings before concatenating.
KEYWORD PARAMETERS:
Optional:
delim - string to insert between parts of array (default to null)
OUTPUT:
Function returns a single string.
HISTORY:
16-Nov-2004 add delim keyword
Written: Frank Varosi NASA/GSFC 1994.
NAME:
STREP
PURPOSE:
Edit a string by position. Precede, Follow, Replace, Delete.
CATEGORY:
Strings
CALLING SEQUENCE:
newstring = strep(string,cmd,p,ss,[iflg])
INPUTS:
string = string to edit. in
cmd = edit command: in
'P' = precede position p with substring ss.
'F' = follow position p with substring ss.
'R' = replace text starting at position p
with text from substring ss.
'D' = delete N characters starting at
position p. The calling sequence for
this command is slightly different:
IFLG = STREP(string,'D',p,n,[iflg])
Where n = number of characters to delete.
p = character position to use. in
0 = first char. Any number larger
than the string length = last char.
ss = substring to use. For 'D' command in
n is used instead of ss.
KEYWORD PARAMETERS:
OUTPUTS:
iflg = 0 for a successful edit, out
iflg = -1 for an error and no change to string.
newstring = edited string. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
Written by R. Sterner, 27 Dec, 1984.
Converted to SUN 13 Aug, 1989 --- R. Sterner.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1984, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
STRESS
PURPOSE:
String edit by sub-string. Precede, Follow, Delete, Replace.
CATEGORY:
Strings
CALLING SEQUENCE:
new = stress(old,cmd,n,oldss,newss,ned)
INPUTS:
old = string to edit. in
cmd = edit command: in
'P' = precede.
'F' = follow.
'D' = delete.
'R' = replace.
n = occurrence number to process (0 = all). in
oldss = reference substring. in
oldss may have any of the following forms:
1. s a single substring.
2. s... start at substring s, end at end of string.
3. ...e from start of string to substring e.
4. s...e from subs s to subs e.
5. ... entire string.
newss = substring to add. Not needed for 'D' in
KEYWORD PARAMETERS:
OUTPUTS:
ned = number of occurrences actually changed. out
new = resulting string after editing. out
COMMON BLOCKS:
NOTES:
Notes: oldss and newss may be arrays.
MODIFICATION HISTORY:
Written by R. Sterner, 6 Jan, 1985.
Johns Hopkins University Applied Physics Laboratory.
RES --- 23 May, 1988 fixed a bug in SSTYP = 2.
Converted to SUN 13 Aug, 1989 --- R. Sterner. (FOR loop change).
--- 8 Dec, 1992 added recursion so that OLDSS and NEWSS may be arrays
T.J.Harris, University of Adelaide.
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
NAME:
strmatch
PURPOSE:
check for string match to a wild card specification
CATEGORY:
Strings
USAGE:
result=strmatch(str,spec)
INPUT:
str string
spec wild card specification
OUTPUT: 1 if STR matches SPEC
0 if STR does not match SPEC
LIMITATIONS:
Currently the only wild card character is asterisk, "*"
which matches 1 or more arbitrary characters.
EXAMPLE:
print,strmatch('string','st*ng') ; => 1
print,strmatch('string','*st*ng') ; => 0
print,strmatch('string','*t*ng') ; => 1
print,strmatch('string','st*ng*') ; => 0
print,strmatch('string','st*n*') ; => 1
AUTHOR: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
NAME:
STRNUMBER
PURPOSE:
Function to determine if a string is a valid numeric value.
CATEGORY:
Strings
CALLING SEQUENCE:
result = strnumber(st,val)
INPUTS:
st - string
OUTPUTS:
1 is returned as the function value if the string st has a
valid numeric value, otherwise, 0 is returned.
OPTIONAL OUTPUT:
val - (optional) value of the string. real*8
WARNING:
Note that (as of Version 2.0.10) a blank string (e.g. " ") is not
a valid numeric value, although an empty string ("") is.
HISTORY:
version 1 By D. Lindler Aug. 1987
NAME:
STRPARSE
VERSION:
3.0
PURPOSE:
Parses the string LINE using the characters in DELIM as delimiters.
Puts individual pieces into consecutive locations in LIST.
CATEGORY:
Strings
CALLING SEQUENCE:
Result = STRPARSE( LINE, DELIM [, LIST])
INPUTS:
LINE
Character string.
DELIM
Character string. Each Character of DELIM is used as a delimiter.
OPTIONAL INPUT PARAMETERS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
Returns the number of pieces found minus one i.e. the index of the last
element of LIST if LIST is provided. If LINE is a null string or not a
string, the function returns -1l.
OPTIONAL OUTPUT PARAMETERS:
LIST
Character array. If name is provided, the pieces of LINE resulting
from the parsing process are returned in consecutive locations in LIST.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Straightforward. Using the function TYPE from MIDL.
MODIFICATION HISTORY:
11-Feb-2014 "list" now a reserved word, so use square brackets
Created 15-JUL-1991 by Mati Meron.
NAME:
strwhere
PURPOSE:
a "where" operator for strings matching a set of string
wild cards
CATEGORY:
Strings, Searching
USAGE: result = strwhere( starr, wildcard )
result = strwhere( starr, wildcard, nfound )
INPUT:
starr an array of strings
wildcard wild card specifier composed of regular and special
characters. The special characters are asterisk '*'
and vertical bar '|'. The asterisk matches any number of
characters the vertical bar indicates an "or" operation
between different wild card specifications.
KEYWORD INPUT:
orchar character used to indicate "or" wildcard operation.
(default = '|')
notequal - if set, return indices where values are NOTEQUAL
ignoreCase - if set, will ignore case
OUTPUT:
result an index array such that starr(result) = those elements of
STARR that match the wild card specification in WILDCARD
EXAMPLE:
f=findfile(/home/paul/arm/arese/bsrn/sgpbsrnC1.a1.*.cdf)
clrdays='*1018*|*1022*|*1030*'
print,f(strwhere(f,clrdays))
AUTHOR: Paul Ricchiazzi 14 Jan 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
20-Dec-04 added notEqual and ignoreCase keywords
22-Apr-03 if no matches, see if need to strip quotes from wildcard
03-Jan-03 Replace sep_str with breakstring [Bill Davis]
21-Jan-00 Make work for no matches. Add nfound. [Bill Davis]
NAME:
textlines
PURPOSE:
Form lines of text for outputing (say, in a table form). If
formats are not input, then guess about good formatting for
variables of different types.
CATEGORY:
STRINGS, Output
CALLING SEQUENCE:
IDL> lines = textlines( arg01, arg02, arg03, arg04, ... )
INPUTS:
inputs = up to 40 scalars or arrays (of same length)
KEYWORD PARAMETERS:
Optional Inputs:
formats - array of formats for each column
tabs - if =0 then will put a space between each column, rather than a tab
debug - if set, debug output will be printed
Optional Output:
getFormat
OUTPUTS:
lines - string array of formatted output
EXAMPLE:
arg01 = [1,2,3] & arg02=['a','b','c']
arg03 = [0.1,0.2,0.3] & arg04 =arg01
lines = textlines( arg01, arg02, arg03, arg04, /debug )
MODIFICATION HISTORY:
20-Dec-2007 Written by Bill Davis, PPPL
NAME:
where_arr
PURPOSE:
Return the subscripts where a given set of values equal the values
in the input array. It is basically an expansion of IDL where in
which the condition to match can be an array.
CATEGORY:
Strings, Searching
CALLING SEQUENCE:
ss = where_arr(full_arr, sub_arr)
ss = where_arr(a, b)
ss = where_arr(a, b, count)
ss = where_arr(a, b, count, /notequal) - invert sense
ss = where_arr(a, b, count, /map_ss)
INPUT:
full_arr- The complete array which is to be searched
sub_arr - The subset array of the values to search "full_arr" of
KEYWORD PARAMETERS:
notequal - if set, return indices where values are NOTEQUAL
map_ss - If set, then return the index in the "sub_arr" where
first occurance of the element exists in the "full_arr"
The length of the output is the same as "full_arr"
OUTPUT:
returns the subscripts where "sub_arr" occurrs in "full_arr". If
there are no matches, return a -1.
OPTIONAL OUTPUT:
count - The number of matches
HISTORY:
Written 30-Apr-91 by M.Morrison
1-Jul-94 (SLF) - add NOTEQUAL keyword
14-Nov-97 (MDM) - Added /MAP_SS keyword
09-Mar-98 (JSN) - change loop from integer to long
NAME:
WORDARRAY
PURPOSE:
Convert text string or string array to a 1-d array of words.
CATEGORY:
Strings
CALLING SEQUENCE:
wordarray, instring, outlist
INPUTS:
instring = string or string array to process. in
KEYWORD PARAMETERS:
Keywords:
IGNORE=string of characters to ignore (array allowed).
These characters are removed before processing.
Ex: wordarray,in,out,ignore=',;()'
wordarray,in,out,ignore=[',',';','(',')']
DELIMITERS = word delimiter characters, like IGNORE.
/WHITE means include white space (spaces,tabs) along
with the specified delimiters.
OUTPUTS:
outlist = 1-d array of words in instring. out
COMMON BLOCKS:
NOTES:
Words are assumed delimited by given delimiters
(defaults are spaces and/or tabs)
Non-delimiters are returned as part of the words.
Delimiters not needed at the front and end of the strings.
See commalist for a near inverse.
MODIFICATION HISTORY:
R. Sterner, 29 Nov, 1989
BLG --- Modified June 22,1991 to include tabs as delimiters
R. Sterner, 11 Dec, 1992 --- fixed to handle pure white space.
R. Sterner, 27 Jan, 1993 --- dropped reference to array.
R. Sterner, 1998 Apr 1 --- Added DELIMITER. Modified IGNORE.
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
Category: Utility
[List of Routines]
NAME:
arrayMask
PURPOSE:
Return an array mask where values are 1 if within the drawn polygon
and 0 if outside.
CATEGORY:
Utility
CALLING SEQUENCE:
IDL> mask=arrayMask( fullx, fully, x, y )
INPUTS:
fullx - full X array of data
fully - full y array of data
x - x coordinates of polygon to enclose
y - y coordinates of polygon to enclose
OUTPUTS:
mask - array dimensioned same as fullX and fullY containing 1's and 0's.
EXAMPLE:
IDL> fullx = findgen(65)
IDL> fully = findgen(65)
IDL> x = [10,10,20,20]
IDL> y = [10,30,30,10]
IDL> mask=arrayMask( fullx, fully, x, y )
WRITTEN 03-Dec-2009 by Bill Davis
NAME:
convangle
PURPOSE:
convert angle from one scheme to another. For example, some routines
have 0 horizontally to the left, with angles increasing in a clockwise
direction. and others have zero to the right, with angles increasing
in a counter-clockwise direction.
CATEGORY:
Utility
CALLING SEQUENCE:
IDL> angle_out = convangle(angle_in)
INPUTS:
angle_in - input angle
KEYWORD PARAMETERS:
Inputs:
degIn - if set, assume input angle is in degrees (DEFAULT)
degOut - if set, assume output angle is in degrees
(if not set, same as degIn)
radIn - if set, assume input angle is in radians
radOut - if set, assume output angle is in radians
zeroLeft - if set, zero degrees is horizontally to the left
zeroRight - if set, zero degrees is horizontally to the right
minDeg - minimum # of degrees to return, if angle < this, add 180 degrees
maxDeg - maximum # of degrees to return , if angle > this, subtract 180 degrees
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
OUTPUTS:
angle_out - converted angle, based on keywords.
EXAMPLES:
IDL> print, convangle( !PI/2, /radIn, /degOut )
90.0000
IDL> print, convangle( 45, /degIn, /InZeroLeft, /OutZeroRight )
135
IDL> print, convangle( !PI/4, /radIn, /InZeroLeft, /OutZeroRight, /degOut )
135.000
IDL> print, convangle( 110, /degIn, /InZeroLeft, /OutZeroRight )
70
IDL> print, convangle( 30, /degIn, /InZeroRight, /OutZeroLeft )
150
IDL> print, convangle( 30*!PI/180, /radIn, /InZeroRight, /OutZeroLeft, /degOut )
150.000
IDL> print, convangle( 30*!PI/180, /radIn, /InZeroRight, /OutZeroLeft )*180/!PI
150.000
IDL> print, convangle( 20, /degIn, /InZeroLeft, /OutZeroright, maxDeg=135 )
-20
IDL> print, convangle( 120, /degIn, /InZeroLeft, /OutZeroright, maxDeg=135 )
60
IDL> print, convangle( 230, /degIn, /InZeroLeft, /OutZeroright, minDeg=-45 )
130
NOTES/LIMITATIONS:
if zero degrees is to the left, assume positive angles in Clockwise dir
if zero degrees is to the right, assume positive angles in
Counter-Clockwise dir
MODIFICATION HISTORY:
06-Feb-2013 Written by Bill Davis, PPPL
NAME:
domainName
PURPOSE:
Return TCP/IP domain name from Unix systems
CATEGORY:
Utility, OS-specific
CALLING SEQUENCE:
IDL> thisDomain = domainName()
INPUTS:
None
KEYWORD PARAMETERS:
OUTPUTS:
thisDomain = e.g., pppl or gat.com (depends on system setup)
COMMON BLOCKS:
NONE
NOTES:
This can take from 0.3-0.5 seconds the first time it is called.
If called from VMS, will print a warning (once) and return
some.vms.system as the domain name.
MODIFICATION HISTORY:
26-Sep-2007 Not working for Linux, so added code
16-Apr-99 Written by Bill Davis, PPPL
NAME:
drawnstxinsides
PURPOSE:
Provide a drawnstxinsides for IDL routines to be used by others
CATEGORY:
Utility
CALLING SEQUENCE:
IDL> drawnstxinsides, shot=shot
INPUTS:
none required
KEYWORD PARAMETERS:
Inputs:
shot - if set, insides will be drawn for the corresponding shot range
OUTPUTS:
none
EXAMPLE:
IDL> window, /free, xsize=300, ysize=600
IDL> cs=mk_color(/load, table=13)
IDL> tree = 'EFIT01'
IDL> shot = 121048
IDL> mdsopen, tree, shot
IDL> zt = mdsvalue('\'+tree+'::z')
IDL> rt = mdsvalue('\'+tree+'::r')
IDL> r = rt(*,0) & z = zt(*,0)
IDL> right_aspect, r, z, POSITION=position
IDL> plot, r, z, POSITION=position, /nodata
IDL> drawnstxinsides, shot=shot
EASIER:
window,/fr
cs=mk_color(/load, table=13)
r=[0,2.15]
z=[-2.2,2.2]
right_aspect, r, z, POSITION=position
plot, r, z, POSITION=position, /nodata
drawnstxinsides
TO ZOOM IN ON LLD, FOR EXAMPLE:
drawnstxinsides, r=[0.3,1.1], z=[-2.0,-1.2]
drawnstxinsides, r=[0.4,1.0], z=[-1.8,-1.4],ystyle=1,xstyle=1
TO SEE NSTX-U geometry:
IDL> drawnstxinsides, shot=930050
MODIFICATION HISTORY
--------------------
05-Jan-2015 BD added nstxu keyword to force NSTX-U geometry
05-Jan-2015 BD added shot, so can draw NSTX-U tiles (if shot > 144500)
Devon Battaglia modified code in plot_tiles_nstxu
18-Dec-2014 BD to support NSTX-U, have another file for coil structure
26-May-2010 BD added keywords Z and Radius to allow clipping plot
12-May-2010 BD added keyword antenna (default=1) to plot RF antenna
23-Mar-2010 BD don't load colors or make window if Z buffer, so works with
Web Tools.
15-Mar-2010 BD changed name so as not to conflict with original
01-Mar-2010 Add LLD; draw plot window if !d.window = -1
17-Dec-2009 Add beam keyword (used in efitmovies.pro). Beam armor?
Written by Bill Davis
NAME:
ERROR_MESSAGE
PURPOSE:
The purpose of this function is to have a device-independent
error messaging function. The error message is reported
to the user by using DIALOG_MESSAGE if widgets are
supported and MESSAGE otherwise.
In general, the ERROR_MESSAGE function is not called directly.
Rather, it is used in a CATCH error handler. Errors are thrown
to ERROR_MESSAGE with the MESSAGE command. A typical CATCH error
handler is shown below.
Catch, theError
IF theError NE 0 THEN BEGIN
Catch, /Cancel
ok = Error_Message()
RETURN
ENDIF
Error messages would get into the ERROR_MESSAGE function by
throwing an error with the MESSAGE command, like this:
IF test NE 1 THEN Message, 'The test failed.'
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com/
CATEGORY:
Utility.
CALLING SEQUENCE:
ok = Error_Message(the_Error_Message)
INPUTS:
the_Error_Message: This is a string argument containing the error
message you want reported. If undefined, this variable is set
to the string in the !Error_State.Msg system variable.
KEYWORDS:
ERROR: Set this keyword to cause Dialog_Message to use the ERROR
reporting dialog. Note that a bug in IDL causes the ERROR dialog
to be used whether this keyword is set to 0 or 1!
INFORMATIONAL: Set this keyword to cause Dialog_Message to use the
INFORMATION dialog instead of the WARNING dialog. Note that a bug
in IDL causes the ERROR dialog to be used if this keyword is set to 0!
TITLE: Set this keyword to the title of the DIALOG_MESSAGE window. By
default the keyword is set to 'System Error' unless !ERROR_STATE.NAME
equals "IDL_M_USER_ERR", in which case it is set to "Trapped Error'.
TRACEBACK: Setting this keyword results in an error traceback
being printed to standard output with the PRINT command. Set to
1 (ON) by default. Use TRACEBACK=0 to turn this functionality off.
OUTPUTS:
Currently the only output from the function is the string "OK".
RESTRICTIONS:
The WARNING Dialog_Message dialog is used by default.
EXAMPLE:
To handle an undefined variable error:
IF N_Elements(variable) EQ 0 THEN $
ok = Error_Message('Variable is undefined')
MODIFICATION HISTORY:
Written by: David W. Fanning, 27 April 1999.
Added the calling routine's name in the message and NoName keyword. 31 Jan 2000. DWF.
Added _Extra keyword. 10 February 2000. DWF.
Forgot to add _Extra everywhere. Fixed for MAIN errors. 8 AUG 2000. DWF.
Adding call routine's name to Traceback Report. 8 AUG 2000. DWF.
Added ERROR, INFORMATIONAL, and TITLE keywords. 19 SEP 2002. DWF.
Removed the requirement that you use the NONAME keyword with the MESSAGE
command when generating user-trapped errors. 19 SEP 2002. DWF.
Added distinctions between trapped errors (errors generated with the
MESSAGE command) and IDL system errors. Note that if you call ERROR_MESSAGE
directly, then the state of the !ERROR_STATE.NAME variable is set
to the *last* error generated. It is better to access ERROR_MESSAGE
indirectly in a Catch error handler from the MESSAGE command. 19 SEP 2002. DWF.
Change on 19 SEP 2002 to eliminate NONAME requirement did not apply to object methods.
Fixed program to also handle messages from object methods. 30 JULY 2003. DWF.
Removed obsolete STR_SEP and replaced with STRSPLIT. 27 Oct 2004. DWF.
Made a traceback the default case without setting TRACEBACK keyword. 19 Nov 2004. DWF.
Added check for window connection specifically for CRON jobs. 6 May 2008. DWF.
NAME:
findDisks
PURPOSE:
return a list of disks shown in the df command on Linux
CATEGORY:
Utility
CALLING SEQUENCE:
IDL> opt = findDisks(dfcmd=dfcmd, nskip=nskip, Ignore=Ignore)
INPUTS:
none required
KEYWORD PARAMETERS:
dfcmd - command to list disks. Default = 'df'
nskip - number of lines to skip in df output, Default = 2
Ignore - disks to ignore. Default to ''
debug - if set, debug output will be printed
OUTPUTS:
opt = string array of disks
EXAMPLE:
IDL> print, findDisks( ignore=['/', '/dev/shm'] )
NOTES:
Only tested on Linux
MODIFICATION HISTORY:
19-Juln-2008 Written by Bill Davis, PPPL
Name:
FIND_FONT
Purpose:
Select a Unix hardware font for IDL graphics.
Category:
Utility, Fonts
Usage:
myfont = FIND_FONT( /courier, size=24 )
WIDGET_CONTROL, default_font=myfont
Input:
None required.
Optional Keywords:
/HELVETICA Select a Helvetica font (default)
/TIMES Select a Times font
/PALATINO Select a Palatino font
/COURIER Select a Courier font
/BOLD Select a bold font (default is no bold)
/ITALIC Select and italic font (default is no italics)
SIZE If set to a named variable, sets the font size (default=12)
NAME If set to a named variable, returns the font name selected
Revised:
04-Oct-02 Return a font, so can set in a widget program [BD]
17-OCT-1997 Liam Gumley, CIMSS/SSEC
Created
Example:
myfont = FIND_FONT( /courier, size=24 )
WIDGET_CONTROL, default_font=myfont
NAME:
monitorjob
PURPOSE:
Monitor an IDL job, and restart it if not present
CATEGORY:
Utility
CALLING SEQUENCE:
IDL> monitorjob, delay=delay, job=job
INPUTS:
none required (will be prompted for job name, if not a keyword)
KEYWORD PARAMETERS:
delay - delay in seconds between checks (default to 60)
job - name of IDL batchfile for spawning job to monitor.
For the job file, just include the call to the procedure
e.g., /u/bdavis/cvs/idl_cvs/batchmdsw.pro
OUTPUTS:
NONE
EXAMPLE:
(from the directory with batchmdsw.pro:)
IDL> monitorjob, job='batchmdsw'
MODIFICATION HISTORY:
09-Jun-2006 Written by Bill Davis, PPPL
NAME:
nodename
PURPOSE:
Return nodename on Linux computer
CATEGORY:
Utility, OS-specific
CALLING SEQUENCE:
IDL> node = nodename(parts=parts, domain=domain)
INPUTS:
none
KEYWORD PARAMETERS:
parts - parts of name between periods
domain - everything after first '.'
OUTPUTS:
nodename, e.g. sunfire16.pppl.gov
COMMON BLOCKS:
nodename_local
EXAMPLE:
IDL> opt = nodename( /HLP )
LIMITATIONS:
Just tested on Redhat Linux
NOTES:
since spawn operation is slow, save node name in common for
subsequent calls.
MODIFICATION HISTORY:
26-Sep-2007 Written by Bill Davis, PPPL
NAME:
nodesearch
PURPOSE:
Search MDS Plus Trees for a node
CATEGORY:
Utility
CALLING SEQUENCE:
IDL> result=nodesearch(searchnode, path=path])
INPUTS:
searchnode and optional variable to return an array of full paths containing
node name
KEYWORD PARAMETERS:
fullpath
OUTPUTS:
status of function
COMMON BLOCKS:
none
EXAMPLE:
IDL> result=nodesearch('xray', fullpath=path)
NOTES:
tree must be open before nodesearch can be called
will return 0 if node is found and -1 if it is not found in the current tree
MODIFICATION HISTORY:
01-Dec-00 Added capability for wildcards in search string
7-Feb-00 Written by Dana Mastrovito, PPPL
NAME:
pingplot
PURPOSE:
plot ping times to various computers (from sunfire13, probably).
CATEGORY:
Utility
CALLING SEQUENCE:
IDL> pingplot, ymax=100
INPUTS:
KEYWORD PARAMETERS:
(optional inputs)
infile - file produced by pingload.pro running from a cron job.
defaults to pingload_yyyymmdd.txt (e.g., pingload_20080218.txt)
dir - directory to find file (defaults to /u/bdavis/cvs/idl_cvs)
the following 3 all limit the y-axis:
yrange - 2-element array
ymax - scalar
limit - scalar (same as ymax)
daysAgo - how many days ago to get data to plot
host - for label of title (defaults to sunfire13)
verbose - if set, will print many informational messages
debug - if set, debug output will be printed, and will stop before exiting
OUTPUTS:
NONE
EXAMPLE:
IDL> pingplot, ymax=10
IDL> date2ymd,systime(),y,m,d, dateString=longDateString
IDL> filename = 'ping'+longDateString+'.jpg'
IDL> mk_jpeg, filename=filename
IDL> spawn, 'lpr -Pb143-x8550dt '+ filename
MODIFICATION HISTORY:
WRITTEN 08-Feb-2008 by Bill Davis
NAME:
print_path
PURPOSE:
prints component directories of an IDL path string.
CATEGORY:
Utility, Programming
CALLING SEQUENCE:
print_path, PATHS [ /NoCurrent]
INPUTS:
PATHS = A string containing one or more directory paths. The
individual paths are separated by commas, although in UNIX,
colons can also be used. In other words, PATHS has the same
format as !PATH, except that commas can be used as a separator
regardless of operating system.
IF not present, uses !PATH
A leading $ can be used in any path to signal that what follows
is an environmental variable, but the $ is not necessary. (In
VMS the $ can either be part of the path, or can signal logical
names for compatibility with Unix.) Environmental variables
can themselves contain multiple paths.
OUTPUT:
The result of the function is a string array of directories.
Unless the NOCURRENT keyword is set, the first element of the array is
always the null string, representing the current directory. All the
other directories will end in the correct separator character for the
current operating system.
OPTIONAL INPUT KEYWORD:
/NOCURRENT = If set, then the current directory (represented by
the null string) will not automatically be prepended to the
output.
PROCEDURE CALLS:
Functions: BREAK_PATH()
REVISION HISTORY:
NAME:
pwd
PURPOSE:
print the current working directory
CATEGORY:
Utility, Programming
OUTPUT:
cwd directory name string. if present in argument list
directory string is not printed to terminal.
AUTHOR: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
Name:
SELECT_FONT
Purpose:
Select a Unix hardware font for IDL graphics.
Category:
Utility, Fonts
Usage:
SELECT_FONT
Input:
None required.
Optional Keywords:
/HELVETICA Select a Helvetica font (default)
/TIMES Select a Times font
/PALATINO Select a Palatino font
/COURIER Select a Courier font
/BOLD Select a bold font (default is no bold)
/ITALIC Select and italic font (default is no italics)
SIZE If set to a named variable, sets the font size (default=12)
NAME If set to a named variable, returns the font name selected
Revised:
17-OCT-1997 Liam Gumley, CIMSS/SSEC
Created
Notes:
(1) This procedure currently only works on Unix IDL platforms.
(2) The NAME value returned by SELECT_FONT can be used to set the
default widget font by the command
Example:
!P.MULTI=[0,1,2,0,0]
PLOT,INDGEN(10)
SELECT_FONT,/BOLD
PLOT,INDGEN(10)
NOTE:
this version is only for Unix at the moment
NAME:
TEMPLATE
PURPOSE:
Provide a template for IDL routines to be used by others
CATEGORY:
Utility
CALLING SEQUENCE:
IDL> opt = template(shot)
INPUTS:
shot = NSTX shot number
KEYWORD PARAMETERS:
Inputs:
HLP - When set, help information is printed.
tree - MDSplus tree
sig - MDSplus signal to look for in current shot
xsize - horizontal size of X window
ysize - vertical size of X window
xpos - initial X position of lower left of X window in pixels
ypos - initial Y position of lower left of X window in pixels
charsize - size of characters on plot
verbose - if set, will print many informational messages
debug - if set, debug output will be printed
Outputs:
status - if odd, then success
OUTPUTS:
opt = returned value out
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> opt = TEMPLATE( /HLP )
NOTES:
When the routine is called with no parameters, or with the
keyword hlp set, help information is printed.
MODIFICATION HISTORY:
20-Oct-2015 Written by Bill Davis, PPPL
NAME:
badpar
PURPOSE: (one line)
Validate an input parameter against valid entries.
DESCRIPTION:
This is a general parameter checking function for validating input
quantities in other procedures and functions. This routine will
generate an error message indicating what is wrong with the item.
Example of use:
pro foo,array
if badpar(array,[4,5],2,CALLER='foo') then return
.
. code for foo .
.
end
This would cause an immediate return to the routine that called foo
with an error message if the input was not either floating or double
and 2 dimensional.
As of IDL v3.0, these are the recognized type codes (see 1-218 in
reference guide).
Type
Code Data Type
---- -----------------------------
0 Undefined
1 Byte
2 Integer
3 Longword integer
4 Floating point
5 Double-precision floating
6 Complex floating
7 String
8 Structure
CATEGORY:
Utility
CALLING SEQUENCE:
val = badpar(param,goodtype,goodrank)
INPUTS:
param - IDL variable to validate.
goodtype - Scalar or vector of type codes that are valid.
goodrank - Scalar or vector of valid ranks.
OPTIONAL INPUT PARAMETERS:
KEYWORD PARAMETERS:
CALLER - String identifying the calling routine.
DEFAULT - Value to return in param if undefined and undefined allowed.
DIMEN - Dimensions of variable.
NPTS - Total number of elements in variable.
RANK - Rank of variable.
TYPE - Type of variable.
OUTPUTS:
Return value is true if the parameter is bad. False if good.
COMMON BLOCKS:
SIDE EFFECTS:
using the font keywords makes resizing very slow and inaccurate
RESTRICTIONS:
PROCEDURE:
MODIFICATION HISTORY:
03-Feb-03 Added FIT, FILE, and WID keywords. Made font work [BD]
3/24/93 - Written by Marc W. Buie, Lowell Observatory.
4/27/93 - MWB, added TYPE and DEFAULT keywords.
NAME:
webdisplay
PURPOSE:
Display web pages from IDL for Help, or other purposes.
CATEGORY:
Utility
CALLING SEQUENCE:
IDL> webdisplay, url
INPUTS:
url = URL to display.
KEYWORD PARAMETERS:
OUTPUTS:
NONE
COMMON BLOCKS:
NONE
MODIFICATION HISTORY:
06-Jan-03 At PPPL, will find "hidden" netscape on Linux
16-Apr-99 Written by Bill Davis, PPPL
NAME:
WHICH
PURPOSE:
Like Unix which, prints the path of an IDL routine.
CATEGORY:
Utility
CALLING SEQUENCE:
Which, Name
INPUTS:
Name: The string containing the name of the procedure.
If no '.' in name, ".pro" is appended.
Under Unix, Name may be "*" to get information on
first routine to satisfy match.
KEYWORDS:
PRINT: If set, this keyword sends the output of WHICH to the
default printer. Under Unix, if PRINT is a string, it is
interpreted as a shell command used for output with
the documentation from WHICH providing standard input
(i.e. PRINT="cat > junk").
OUTPUT: returns full path of file found;
will return null string if none found
QUIET: If set, no printing to IDL session is done
UNIX KEYWORDS:
DIRECTORY: The directory to search. If omitted, the current directory
and !PATH are used.
MULTI: If set, this flag allows printing of more than one file if the
requested module exists in more than one directory in the path
and the current directory.
VMS KEYWORDS:
FILE: If this keyword is set, the output is left in the file
"userlib.doc", in the current directory.
PATH: An optional directory/library search path. This keyword uses
the same format and semantics as !PATH. If omitted, !PATH is
used.
OUTPUTS:
Documentation is sent to the standard output unless /PRINT
is specified.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Output is produced on terminal or printer.
RESTRICTIONS:
The DIRECTORY and MULTI keywords are ignored under VMS. The
FILE and PATH keywords are ignored under Unix.
EXAMPLE:
To obtain documentation for the User's Library function DIST, enter:
Which, 'DIST', output=fullpathname
For a graphical interface to WHICH, see the procedure XDL.
MODIFICATION HISTORY:
13-Apr-99 Allow findind files on VMS if not in libraries [BD]
Converted from IDL DOC_LIBRARY by Bill Davis, March, 1999
optionally return path in keyword OUTPUT. Added QUIET keyword.
allow extentions other than .pro
allow uppercase finds.
Written, DMS, Sept, 1982.
Added library param, Jul 1987.
Unix version, DMS, Feb, 1988.
New VMS version, DMS, Dec. 1989
Wrapper procedure to call the correct version
under Unix and VMS, AB, Jan 1990
Added support for DOS, SNG, Dec, 1990
Added support for Macintosh, DJE, Nov, 1994
NAME: writeLog PURPOSE: Provide a writeLog for IDL routines to be used by others CATEGORY: Utility CALLING SEQUENCE: IDL> writeLog, logfile, msg, logWindowID=logWindowID INPUTS: logfile - logfile for output (DEFAULT='logfile.txt') msg - string to put in log KEYWORD PARAMETERS: time - if set then add time stamp to the output message nLines - lines for each message (def=1, meaning no blank lines) verbose - if set, will echo message to screen with print command OUTPUTS: none COMMON BLOCKS: NONE EXAMPLE: IDL> writeLog, 'mylogfile.txt', 'All is well', /time, /verbose NOTES: used in some auto-restart programs for nstxops MODIFICATION HISTORY: 20-Mar-2007 print blank lines when /verbose. Write every line of msg on separate line 14-Aug-2006 just return if log file not writable 07-Dec-2005 added nLines keyword Oct-2005 Written by Bill Davis, PPPL
Category: Widgets
[List of Routines]
NAME:
CW_FIELD_BD
PURPOSE:
This widget cluster function manages a data entry field widget.
The field consists of a label and a text widget. CW_FIELD's can
be string fields, integer fields or floating-point fields. The
default is an editable string field.
CATEGORY:
Widgets
CALLING SEQUENCE:
Result = CW_FIELD_BD(Parent)
INPUTS:
Parent: The widget ID of the widget to be the field's parent.
KEYWORD PARAMETERS:
TITLE: A string containing the text to be used as the label for the
field. The default is "Input Field:".
VALUE: The initial value in the text widget. This value is
automatically converted to the type set by the STRING,
INTEGER, and FLOATING keywords described below.
UVALUE: A user value to assign to the field cluster. This value
can be of any type.
UNAME: A user supplied string name to be stored in the
widget's user name field.
FRAME: The width, in pixels, of a frame to be drawn around the
entire field cluster. The default is no frame.
RETURN_EVENTS: Set this keyword to make cluster return an event when a
is pressed in a text field. The default is
not to return events. Note that the value of the text field
is always returned when the WIDGET_CONTROL, field, GET_VALUE=X
command is used.
ALL_EVENTS: Like RETURN_EVENTS but return an event whenever the
contents of a text field have changed.
COLUMN: Set this keyword to center the label above the text field.
The default is to position the label to the left of the text
field.
ROW: Set this keyword to position the label to the left of the text
field. This is the default.
XSIZE: An explicit horizontal size (in characters) for the text input
area. The default is to let the window manager size the
widget. Using the XSIZE keyword is not recommended.
YSIZE: An explicit vertical size (in lines) for the text input
area. The default is 1.
STRING: Set this keyword to have the field accept only string values.
Numbers entered in the field are converted to their string
equivalents. This is the default.
FLOATING: Set this keyword to have the field accept only floating-point
values. Any number or string entered is converted to its
floating-point equivalent.
INTEGER: Set this keyword to have the field accept only integer values.
Any number or string entered is converted to its integer
equivalent (using FIX). For example, if 12.5 is entered in
this type of field, it is converted to 12.
LONG: Set this keyword to have the field accept only long integer
values. Any number or string entered is converted to its
long integer equivalent (using LONG).
FONT: A string containing the name of the X Windows font to use
for the TITLE of the field.
FIELDFONT: A string containing the name of the X Windows font to use
for the TEXT part of the field.
NOEDIT: Normally, the value in the text field can be edited. Set this
keyword to make the field non-editable.
OUTPUTS:
This function returns the widget ID of the newly-created cluster.
COMMON BLOCKS:
None.
PROCEDURE:
Create the widgets, set up the appropriate event handlers, and return
the widget ID of the newly-created cluster.
EXAMPLE:
The code below creates a main base with a field cluster attached
to it. The cluster accepts string input, has the title "Name:", and
has a frame around it:
base = WIDGET_BASE()
field = CW_FIELD(base, TITLE="Name:", /FRAME)
WIDGET_CONTROL, base, /REALIZE
MODIFICATION HISTORY:
01-Jun-2006 added double keyword [BD]
11-Mar-2004 Added ALIGN_CENTER & ALIGN_RIGHT [BD]
July 2001 CT, RSI, Fix bug in previous mod. If user passes in a
numeric VALUE but forgets to set the /FLOAT, we still need
to convert to a string before passing onto WIDGET_TEXT.
March 2001: CT, RSI, Pass keywords directly into WIDGET_BASE,
without assigning default values, since the defaults are
handled by WIDGET_BASE. Avoids assigning defaults if user passes
in undefined variables.
Written by: Keith R. Crosley June 1992
KRC, January 1993 -- Added support for LONG
integers.
AB, 7 April 1993, Removed state caching.
JWG, August 1993, Completely rewritten to make
use of improved TEXT widget functionality
ACY, 25 March, 1994, fix usage of FRAME keyword
KDB, May 1994, Initial value =0 would result
in a null text field. Fixed
keyword check.
NAME:
CW_FIELD
PURPOSE:
This widget cluster function manages a data entry field widget.
The field consists of a label and a text widget. CW_FIELD's can
be string fields, integer fields or floating-point fields. The
default is an editable string field.
CATEGORY:
Widgets
CALLING SEQUENCE:
Result = CW_FIELD(Parent)
INPUTS:
Parent: The widget ID of the widget to be the field's parent.
KEYWORD PARAMETERS:
TITLE: A string containing the text to be used as the label for the
field. The default is "Input Field:".
VALUE: The initial value in the text widget. This value is
automatically converted to the type set by the STRING,
INTEGER, and FLOATING keywords described below.
UVALUE: A user value to assign to the field cluster. This value
can be of any type.
UNAME: A user supplied string name to be stored in the
widget's user name field.
FRAME: The width, in pixels, of a frame to be drawn around the
entire field cluster. The default is no frame.
RETURN_EVENTS: Set this keyword to make cluster return an event when a
is pressed in a text field. The default is
not to return events. Note that the value of the text field
is always returned when the WIDGET_CONTROL, field, GET_VALUE=X
command is used.
ALL_EVENTS: Like RETURN_EVENTS but return an event whenever the
contents of a text field have changed.
COLUMN: Set this keyword to center the label above the text field.
The default is to position the label to the left of the text
field.
ROW: Set this keyword to position the label to the left of the text
field. This is the default.
XSIZE: An explicit horizontal size (in characters) for the text input
area. The default is to let the window manager size the
widget. Using the XSIZE keyword is not recommended.
YSIZE: An explicit vertical size (in lines) for the text input
area. The default is 1.
STRING: Set this keyword to have the field accept only string values.
Numbers entered in the field are converted to their string
equivalents. This is the default.
FLOATING: Set this keyword to have the field accept only floating-point
values. Any number or string entered is converted to its
floating-point equivalent.
INTEGER: Set this keyword to have the field accept only integer values.
Any number or string entered is converted to its integer
equivalent (using FIX). For example, if 12.5 is entered in
this type of field, it is converted to 12.
LONG: Set this keyword to have the field accept only long integer
values. Any number or string entered is converted to its
long integer equivalent (using LONG).
FONT: A string containing the name of the X Windows font to use
for the TITLE of the field.
FIELDFONT: A string containing the name of the X Windows font to use
for the TEXT part of the field.
NOEDIT: Normally, the value in the text field can be edited. Set this
keyword to make the field non-editable.
OUTPUTS:
This function returns the widget ID of the newly-created cluster.
COMMON BLOCKS:
None.
PROCEDURE:
Create the widgets, set up the appropriate event handlers, and return
the widget ID of the newly-created cluster.
EXAMPLE:
The code below creates a main base with a field cluster attached
to it. The cluster accepts string input, has the title "Name:", and
has a frame around it:
base = WIDGET_BASE()
field = CW_FIELD(base, TITLE="Name:", /FRAME)
WIDGET_CONTROL, base, /REALIZE
MODIFICATION HISTORY:
27-Nov-2013 trying to fix bug in CW_FIELD_SET
01-Jun-2006 added double keyword [BD]
11-Mar-2004 Added ALIGN_CENTER & ALIGN_RIGHT [BD]
July 2001 CT, RSI, Fix bug in previous mod. If user passes in a
numeric VALUE but forgets to set the /FLOAT, we still need
to convert to a string before passing onto WIDGET_TEXT.
March 2001: CT, RSI, Pass keywords directly into WIDGET_BASE,
without assigning default values, since the defaults are
handled by WIDGET_BASE. Avoids assigning defaults if user passes
in undefined variables.
Written by: Keith R. Crosley June 1992
KRC, January 1993 -- Added support for LONG
integers.
AB, 7 April 1993, Removed state caching.
JWG, August 1993, Completely rewritten to make
use of improved TEXT widget functionality
ACY, 25 March, 1994, fix usage of FRAME keyword
KDB, May 1994, Initial value =0 would result
in a null text field. Fixed
keyword check.
NAME:
DIALOG_MENU
PURPOSE:
A modal (blocking) dialog widget to display a selectable menu.
The dialog must be dismissed by selecting a menu item before
execution of the calling program can continue.
TYPE:
FUNCTION
CATEGORY:
WIDGETS
CALLING SEQUENCE:
result = DIALOG_MENU (menu_items)
INPUTS:
menu_items: STRARR of menu items
KEYWORD PARAMETERS:
TITLE: The menu title. Use STRARR for multi-line titles.
XSIZE, YSIZE: x, y size of the widget.
XPOSITION, YPOSITION: The position of the upper left corner of the
dialog, relative to the upper left corner of the screen.
SCROLL: Adds a scroll bar
X_SCROLL_SIZE: Size of x scroll region, if /SCROLL is set
Y_SCROLL_SIZE: Size of y scroll region, if /SCROLL is set
DIALOG_PARENT: Set this keyword to the widget ID of a widget over
which the message dialog should be positioned. When displayed,
the DIALOG_MENU dialog will be positioned over the specified
widget. Dialogs are often related to a non-dialog widget tree.
The ID of the widget in that tree to which the dialog is most
closely related should be specified.
If this keyword is not specified, the default placement of the
menu is the center of the screen (window manager dependent).
INDEX: Optionally return the index of the selected item instead of
the item's text. The index of the first menu_item is zero.
CANCEL: STRING label for the 'Cancel' button (default = 'Cancel')
OUTPUTS:
result: String of selected menu_item, or integer index if INDEX keyword
is used, starting at index = 0
COMMON BLOCKS:
NONE
SIDE EFFECTS:
Creates a modal widget.
RESTRICTIONS:
None known.
DEPENDENCIES:
NONE
EXAMPLES:
result = DIALOG_MENU (['Item 1', 'Item 2', 'Item3'], $
TITLE = 'Select an Item')
MODIFICATION HISTORY:
22-Jul-2009 added Alt button [BD]
15-Jul-2009 added didCancel keyword
06-Jul-2009 added Cancel button [BD]
v1.04: RSM, May 1998
Added XPOSITION, YPOSITION keywords. Removed the UL, LL, UR, LR
keywords. Changed WIDTH keyword to XSIZE, and added YSIZE
keyword. These bring the widget in line with common IDL widget
size and position keywords.
THESE CHANGES WILL BREAK OLD CODE THAT USED ANY OF THESE KEYWORDS!
v1.03: RSM, Mar 1998
If not using /SCROLL, removed the sub-base for the menu buttons
so that they span the full width of the top level base.
v1.02: RSM, Mar 1998
Changed to return selected item's text, not index (index can
now be returned with the INDEX keyword).
v1.01: RSM, Mar 1998
Fixed error when used with a modal toplevel base.
v1.0: Written, Robert.Mallozzi@msfc.nasa.gov, November 1997.
NAME:
pdsurface
PURPOSE:
This routine provides a graphical interface to the SURFACE and
SHADE_SurfRangeACE commands. Different controls are provided to change
the viewing angle and other plot parameters. The command used to
generate the resulting surface plot is shown in a text window.
CATEGORY:
Widgets.
CALLING SEQUENCE:
pdsurface, Data
INPUT PARAMETERS:
Data: The two-dimensional array to display as a wire-mesh or
shaded surface.
KEYWORD PARAMETERS:
GROUP: The widget ID of the widget that calls pdsurface. When this
keyword is specified, the death of the caller results in the
death of pdsurface.
BLOCK: Set this keyword to have XMANAGER block when this
application is registered. By default the Xmanager
keyword NO_BLOCK is set to 1 to provide access to the
command line if active command line processing is available.
Note that setting BLOCK for this application will cause
all widget applications to block, not only this
application. For more information see the NO_BLOCK keyword
to XMANAGER.
SIDE EFFECTS:
The XMANAGER is initiated if it is not already running.
RESTRICTIONS:
pdsurface does not accept any of the keywords that the IDL command
SURFACE does.
PROCEDURE:
Create and register the widget with the XMANAGER and then exit.
MODIFICATION HISTORY:
20-May-04 Better message when no analysis data, or times out-of-range
10-Feb-03 Made shaded surface the default [BD]
25-Feb-02 List shot date and time on plot [BD]
01-Feb-01 Added "Copy Plot to Tek Window" option
17-OCT-00 Added Max Power Density to plot option.
14-Sep-00 Added min & max R options & better shot buttons. [BD]
29-Aug-00 Made from RSI xsurface [BD]
Created from a template written by: Steve Richards, January, 1991.
NAME:
PickPlot
PURPOSE:
This function allows the user to interactively pick a plot file.
It will be plotted in a separate window. Postscript files (with a
"ps" extenstion will go to a gv window, and others will be
plotted with xv.
CATEGORY:
Widgets.
CALLING SEQUENCE:
pickplot
KEYWORD PARAMETERS:
FILE: A string value for setting the initial value of the
selection. Useful if there is a default file
PsPlotFILE: Name of file to copy clicked-on files to. "gv --watch"
will be looking for this file to change, so will effectively
plot the file clicked. Defaults to '~/PickPlot.ps'
PATH: The initial path to select files from. If this keyword is
not set, the current directory is used.
FILTER: A string value for filtering the files in the file list. This
keyword is used to reduce the number of files to choose from.
The user can modify the filter unless the FIX_FILTER keyword
is set. Example filter values might be "*.ps" or "*.pdf".
TITLE: A scalar string to be used for the window title. If it is
not specified, the default title is "Select File"
GROUP: The widget ID of the widget that calls PICKFILE. When this
ID is specified, a death of the caller results in the death of
the PICKFILE widget application.
OUTPUTS:
Copies selected file to ~/PickPlot.ps, which "gv --watch" is looking for
to plot.
COMMON BLOCKS:
None.
NOTES:
This probably only works on Linux/Unix.
You probably want the following line in your ~/.Xresources file:
gv.watchFileFrequency: 501
this will make gv check for file changes ever 501 ms, rather than 1000 ms.
SIDE EFFECTS:
This function initiates the XMANAGER if it is not already running.
RESTRICTIONS:
PICKFILE does not recognize symbolic links to other files in UNIX.
PickFile (probably) only works on Linux/Unix systems where gv is in the PATH.
MODIFICATION HISTORY:
Written 28-Oct-2009 by Bill Davis, PPPL. Based on BigPickPlot.pro
NAME:
strucedit
PURPOSE:
Widget to edit a structure of scalars from an IDL save file.
The names of the input fields are the names of the structure elements.
CATEGORY:
Widgets, structures
CALLING SEQUENCE:
IDL> strucedit
INPUTS:
input = whatever.
KEYWORD PARAMETERS:
Optional Keywords:
inStrc - IDL structure of variables to edit
labels - labels for input fields. If not specifie, name of variable
will be used.
savefile - name of IDL save file with initial structure
not used if inStrc input specified, if neither user
will be prompted for a file name.
title - title of widget
GROUP_LEADER - This widget is destroyed if it's GL is destroyed
OUTPUTS:
a new IDL save file is created
LIMITATIONS:
Will only work on a structure containing scalars.
Does not ask any "are you sure" type of questions.
COMMON BLOCKS:
NONE
EXAMPLE:
IDL> strucedit, savefile='/u/bdavis/SpecFit/modespecstrc.sav'
or
IDL> strucedit, instrc={a:0, b:1.0, c:'label name'}, $
labels=['Value of A', 'Value of B']
NOTES:
MODIFICATION HISTORY:
29-Apr-2005 Written by Bill Davis, PPPL
NAME:
SURF_CONTOUR
PURPOSE:
The purpose of this program is to demonstrate how to
create a shaded surface and coutour plot in the same
object graphics window. The contour plot should be
able to be translated independently of the surface.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
2642 Bradbury Court
Fort Collins, CO 80521 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Widgets, IDL 5 Object Graphics.
CALLING SEQUENCE:
SURF_CONTOUR, data, x, y
REQUIRED INPUTS:
None. Fake data will be used if no data is supplied in call.
OPTIONAL INPUTS
data: A 2D array of surface data.
x: A vector of X data values.
y: A vector of Y data values.
OPTIONAL KEYWORD PARAMETERS:
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to the surface initialization routine.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
XTITLE: A string used as the X title of the plot.
YTITLE: A string used as the Y title of the plot.
ZTITLE: A string used as the Z title of the plot.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To use this program with your data, type:
IDL> Surf_Contour, data
MODIFICATION HISTORY:
Written by David Fanning, 20 September 98.
NAME:
usingXwindows
PURPOSE:
Prompt user for switching Plot device to X.
CATEGORY:
Widgets, X-windows
CALLING SEQUENCE:
IDL> OK = usingXwindows()
COMMON BLOCKS:
NONE
USE:
Called in case a user was using Tektronix graphics, or the Postscript
device and forgot to SET_PLOT,'X' before using widgets, etc.
MODIFICATION HISTORY:
Aug-00 Written [BD]
NAME:
viewtext
PURPOSE:
View a string, or string array, of text in a scrollable text widget.
DESCRIPTION:
CATEGORY:
Widgets
CALLING SEQUENCE:
viewtext, text [, KEYWORDS]
INPUTS:
text : String (scalar, 1-D or 2-D array) of text to be displayed.
OPTIONAL INPUT PARAMETERS:
KEYWORD PARAMETERS:
EXIT = Label for exit button. Default is 'Dismiss'.
FONT = Font to use for the text. Default is '8x13'.
GROUP = Group Leader.
TITLE = Title of widget.
XSIZE = Width of text. Default is 80 characters.
YSIZE = Length of text. Default is 40 lines.
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
PROCEDURE:
MODIFICATION HISTORY:
23-Feb-2005 if LASTPRINTER in private common defined, use that.
pop dialog box on which printer HARDCOPY went to.
3-Feb-03 /FIT keyword and made resizable.
08-Jun-00 Added support for VMS (Bill Davis)
Written by Doug Loucks, Lowell Observatory, May, 1993.
1/7/94, DWL, Added Hardcopy button.
8/25/94, DWL, Minor mods.
96/07/02, MWB, changed YSIZE default to 40 lines.
NAME:
WIDGET_BOTTOM
PURPOSE:
Move a widget to the bottom of the screen or base widget.
CATEGORY:
Widgets.
CALLING SEQUENCE:
WIDGET_BOTTOM, ID
INPUTS:
ID ID of the widget to be centered.
KEYWORD PARAMETERS:
PARENT ID of an existing widget over which the input widget
should be centered.
OUTPUTS:
None.
EXAMPLE:
base = widget_base()
label = widget_label(base, value='Hello world')
WIDGET_BOTTOM, base
widget_control, base, /realize
MODIFICATION HISTORY:
Created by Bill Davis 14-Apr-06. Added yborder and xborder.
Based on WIDGET_BOTTOM Written by: Liam.Gum...@ssec.wisc.edu
NAME:
XcdEdit
PURPOSE:
A table editor modified from XVAREDIT for ppcc c.d file.
CATEGORY:
Widgets
CALLING SEQUENCE:
XcdEdit, filename
INPUTS:
filename = The file to be edited.
KEYWORD PARAMETERS:
NAME = The NAME of the variable. This keyword is overwritten with the
structure name if the variable is a structure.
GROUP = The widget ID of the widget that calls XcdEdit. When this
ID is specified, a death of the caller results in a death of
XcdEdit.
X_SCROLL_SIZE = The X_SCROLL_SIZE keyword allows you to set
the width of the scrolling viewport in columns.
Default is 4.
Y_SCROLL_SIZE = The Y_SCROLL_SIZE keyword allows you to set
the height of the scrolling viewport in rows.
Default is 4.
OUTPUTS:
VAR= The variable that has been edited, or the original when the user
Quits from the file menu.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Initiates the XManager if it is not already running.
RESTRICTIONS:
None known.
PROCEDURE:
Create and register the widget and then exit.
If the user selects "save", the values in the editor are written
to the file passed in, otherwise, they are ignored.
MODIFICATION HISTORY:
Written by: Steve Richards, February, 1991
Modified: September 96, LP - rewritten with TABLE widget
Converted from XcdEdit.pro by Bill Davis, Oct. 1998
07-Oct-98 BD Took out check for "commit" because it was always wrong.
NAME:
XCOLORS
PURPOSE:
The purpose of this routine is to interactively change color tables
in a manner similar to XLOADCT. No common blocks are used so
multiple copies of XCOLORS can be on the display at the same
time (if each has a different TITLE). XCOLORS has the ability
to notify a widget event handler, an object method, or an IDL
procedure if and when a new color table has been loaded. Brewer
color tables can also be accessed from this program, if the file
fsc_brewer.tbl can be found somewhere in your IDL path.
AUTHOR:
FANNING SOFTWARE CONSULTING
David Fanning, Ph.D.
1645 Sheely Drive
Fort Collins, CO 80526 USA
Phone: 970-221-0438
E-mail: davidf@dfanning.com
Coyote's Guide to IDL Programming: http://www.dfanning.com
CATEGORY:
Widgets, Object, Command line.
CALLING SEQUENCE:
XCOLORS
INPUTS:
None.
KEYWORD PARAMETERS:
BLOCK: If this keyword is set, the program will try to block the
IDL command line. Note that this is only possible if no other
widget program is currently blocking the IDL command line. It
is much more reliable to make XCOLORS a modal widget (see the MODAL
keyword), although this can generally only be done when XCOLORS
is called from another widget program.
BREWER: Set this keyword if you wish to use the Brewer Colors, as explained
in this reference: http://www.dfanning.com/color_tips/brewer.html. The
Brewer color table file, fsc_brewer.tbl must be found somewhere in your
IDL path for this option to be available. The file can be downloaded here.
http://www.dfanning.com/programs/fsc_brewer.tbl
Note that if this file is found, the Brewer colors are automatically added
to the program as an option. In this case, the BREWER keyword just makes sure
this is the initial user choice.
BOTTOM: The lowest color index of the colors to be changed.
COLORINFO: This output keyword will return either a pointer to
a color information structure (if the program is called in
a non-modal fashion) or a color information structure (if the program
is called in modal or blocking fashion). The color information
structure is an anonymous structure defined like this:
struct = { R: BytArr(!D.Table_Size), $ ; The current R color vector.
G: BytArr(!D.Table_Size), $ ; The current G color vector.
B: BytArr(!D.Table_Size), $ ; The current B color vector.
NAME: "", $ ; The name of the current color table.
INDEX: 0, $ ; The index number of the current color table.
TYPE: "", $ ; The type of color table (e.g, BREWER or IDL).
REVERSED: 0B } ; Set to 1 if the color table is reversed.
If a pointer to the structure is obtained, you will be responsible
for freeing it to prevent memory leakage:
XColors, ColorInfo=colorInfoPtr
Print, "Color Table Name: ", (*colorInfoPtr).Name
Ptr_Free, colorInfoPtr
Note that that Name field will be "Unknown" and the Index field will
be -1 until a color table is actually selected by the user. You are
responsible for checking this value before you use it.
When called in modal or blocking fashion, you don't have to worry about freeing
the pointer, since no pointer is involved:
XColors, /Block, ColorInfo=colorInfoData
Help, colorInfoData, /Structure
Print, "Color Table Name: ", colorInfoData.Name
DATA: This keyword can be set to any valid IDL variable. If
the variable is defined, the specified object method or notify
procedure will be passed this variable via a DATA keyword. This
keyword is defined primarily so that Notify Procedures are compatible
with the XLOADCT way of passing data. It is not strictly required,
since the _EXTRA keyword inheritance mechanism will allow passing
of *any* keyword parameter defined for the object or procedure that is
to be notified.
DRAG: Set this keyword if you want colors loaded as you drag
the sliders. Default is to update colors only when you release
the sliders. Use of this keyword is greatly discouraged.
_EXTRA: This keyword inheritance mechanism will pick up and
pass along to any method or procedure to be notified and keywords
that are defined for that procedure. Note that you should be sure
that keywords are spelled correctly. Any mis-spelled keyword will
be ignored.
FILE: A string variable pointing to a file that holds the
color tables to load. The normal colors1.tbl file is used by default.
GROUP_LEADER: The group leader for this program. When the group
leader is destroyed, this program will be destroyed.
INDEX: The index of the color table to start up. If provided, a color
table of this index number is loaded prior to display. Otherwise,
the current color table is used. Set this keyword if you wish
to have the index number of the event structure correct when
the user CANCELs out of the progam.
MODAL: Set this keyword (along with the GROUP_LEADER keyword) to
make the XCOLORS dialog a modal widget dialog. Note that NO
other events can occur until the XCOLORS program is destroyed
when in modal mode.
NCOLORS: This is the number of colors to load when a color table
is selected.
NOSLIDERS: If this keyword is set, the color stretch and color gamma
sliders are not displayed. This would be appropriate, for example,
for programs that just load pre-defined color tables.
NOTIFYID: A 2-column by n-row array that contains the IDs of widgets
that should be notified when XCOLORS loads a color table. The first
column of the array is the widgets that should be notified. The
second column contains IDs of widgets that are at the top of the
hierarchy in which the corresponding widgets in the first column
are located. (The purpose of the top widget IDs is to make it
possible for the widget in the first column to get the "info"
structure of the widget program.) An XCOLORS_LOAD event will be
sent to the widget identified in the first column. The event
structure is defined like this:
event = {XCOLORS_LOAD, ID:0L, TOP:0L, HANDLER:0L, $
R:BytArr(!D.TABLE_SIZE < 256), G:BytArr(!D.TABLE_SIZE < 256), $
B:BytArr(!D.TABLE_SIZE < 256), INDEX:0, NAME:""}
The ID field will be filled out with NOTIFYID[0, n] and the TOP
field will be filled out with NOTIFYID[1, n]. The R, G, and B
fields will have the current color table vectors, obtained by
exectuing the command TVLCT, r, g, b, /Get. The INDEX field will
have the index number of the just-loaded color table. The name
field will have the name of the currently loaded color table.
Note that XCOLORS can't initially tell *which* color table is
loaded, since it just uses whatever colors are available when it
is called. Thus, it stores a -1 in the INDEX field to indicate
this "default" value. Programs that rely on the INDEX field of
the event structure should normally do nothing if the value is
set to -1. This value is also set to -1 if the user hits the
CANCEL button. (Note the NAME field will initially be "Unknown").
Typically the XCOLORS button will be defined like this:
xcolorsID = Widget_Button(parentID, Value='Load New Color Table...', $
Event_Pro='Program_Change_Colors_Event')
The event handler will be written something like this:
PRO Program_Change_Colors_Event, event
; Handles color table loading events. Allows colors be to changed.
Widget_Control, event.top, Get_UValue=info, /No_Copy
thisEvent = Tag_Names(event, /Structure_Name)
CASE thisEvent OF
'WIDGET_BUTTON': BEGIN
; Color table tool.
XColors, NColors=info.ncolors, Bottom=info.bottom, $
Group_Leader=event.top, NotifyID=[event.id, event.top]
ENDCASE
'XCOLORS_LOAD': BEGIN
; Update the display for 24-bit displays.
Device, Get_Visual_Depth=thisDepth
IF thisDepth GT 8 THEN BEGIN
WSet, info.wid
...Whatever display commands are required go here. For example...
TV, info.image
ENDIF
ENDCASE
ENDCASE
Widget_Control, event.top, Set_UValue=info, /No_Copy
END
NOTIFYOBJ: A vector of structures (or a single structure), with
each element of the vector defined as follows:
struct = {XCOLORS_NOTIFYOBJ, object:Obj_New(), method:''}
where the Object field is an object reference, and the Method field
is the name of the object method that should be called when XCOLORS
loads its color tables.
ainfo = {XCOLORS_NOTIFYOBJ, a, 'Draw'}
binfo = {XCOLORS_NOTIFYOBJ, b, 'Display'}
XColors, NotifyObj=[ainfo, binfo]
Note that the XColors program must be compiled before these structures
are used. Alternatively, you can put this program, named
"xcolors_notifyobj__define.pro" (*three* underscore characters in this
name!) in your PATH:
PRO XCOLORS_NOTIFYOBJ__DEFINE
struct = {XCOLORS_NOTIFYOBJ, OBJECT:Obj_New(), METHOD:''}
END
Or, you can simply define this structure as it is shown here in your code.
"Extra" keywords added to the XCOLORS call are passed along to
the object method, which makes this an alternative way to get information
to your methods. If you expect such keywords, your methods should be defined
with an _Extra keyword.
If you set the /OBJECT_DATA keyword, write your XColors notification
routine with an XCOLORS_INFO keyword. This will return the same
structure defined for the COLORINFO keyword above to your object method.
NOTIFYPRO: The name of a procedure to notify or call when the color
tables are loaded. If the DATA keyword is also defined, it will
be passed to this program via an DATA keyword. But note that *any*
keyword appropriate for the procedure can be used in the call to
XCOLORS. For example, here is a procedure that re-displays and image
in the current graphics window:
PRO REFRESH_IMAGE, Image=image, _Extra=extra, WID=wid
IF N_Elements(wid) NE 0 THEN WSet, wid
TVIMAGE, image, _Extra=extra
END
This program can be invoked with this series of commands:
IDL> Window, /Free
IDL> TVImage, image, Position=[0.2, 0.2, 0.8, 0.8]
IDL> XColors, NotifyPro='Refresh_Image', Image=image, WID=!D.Window
Note that "extra" keywords added to the XCOLORS call are passed along to
your procedure, which makes this an alternative way to get information
to your procedure. If you expect such keywords, your procedure should
be defined with an _Extra keyword as illustrated above.
OBJECT_DATA: Set this keyword if you wish color information to be
supplied to your object notification method via an XCOLORS_DATA
keyword. This keyword is ignored unless the NOTIFYOBJ keyword is
also used. The color information is supplied as a structure and is
defined in the COLORINFO keyword definition above.
REVERSE: If this keyword is set, the color table is reversed and the
Reverse Color Table button is set on.
TITLE: This is the window title. It is "Load Color Tables" by
default. The program is registered with the name 'XCOLORS:' plus
the TITLE string. The "register name" is checked before the widgets
are defined. If a program with that name has already been registered
you cannot register another with that name. This means that you can
have several versions of XCOLORS open simultaneously as long as each
has a unique title or name. For example, like this:
IDL> XColors, NColors=100, Bottom=0, Title='First 100 Colors'
IDL> XColors, NColors=100, Bottom=100, Title='Second 100 Colors'
XOFFSET: This is the X offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
YOFFSET: This is the Y offset of the program on the display. The
program will be placed approximately in the middle of the display
by default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Colors are changed. Events are sent to widgets if the NOTIFYID
keyword is used. Object methods are called if the NOTIFYOBJ keyword
is used. This program is a non-blocking widget.
RESTRICTIONS:
None.
EXAMPLE:
To load a color table into 100 colors, starting at color index
50 and send an event to the widget identified at info.drawID
in the widget heirarchy of the top-level base event.top, type:
XCOLORS, NCOLORS=100, BOTTOM=50, NOTIFYID=[info.drawID, event.top]
MODIFICATION HISTORY:
Written by: David W. Fanning, 15 April 97. Extensive modification
of an older XCOLORS program with excellent suggestions for
improvement by Liam Gumley. Now works on 8-bit and 24-bit
systems. Subroutines renamed to avoid ambiguity. Cancel
button restores original color table.
23 April 1997, added color protection for the program. DWF
24 April 1997, fixed a window initialization bug. DWF
18 June 1997, fixed a bug with the color protection handler. DWF
18 June 1997, Turned tracking on for draw widget to fix a bug
in TLB Tracking Events for WindowsNT machines in IDL 5.0. DWF
20 Oct 1997, Changed GROUP keyword to GROUP_LEADER. DWF
19 Dec 1997, Fixed bug with TOP/BOTTOM reversals and CANCEL. DWF.
9 Jun 1998, Fixed bug when using BOTTOM keyword on 24-bit devices. DWF
9 Jun 1998, Added Device, Decomposed=0 for TrueColor visual classes. DWF
9 Jun 1998, Removed all IDL 4 compatibility.
21 Oct 1998, Fixed problem with gamma not being reset on CANCEL. DWF
5 Nov 1998. Added the NotifyObj keyword, so that XCOLORS would work
interactively with objects. DWF.
9 Nov 1998. Made slider reporting only at the end of the drag. If you
want continuous updating, set the DRAG keyword. DWF.
9 Nov 1998. Fixed problem with TOP and BOTTOM sliders not being reset
on CANCEL. DWF.
10 Nov 1998. Fixed fixes. Sigh... DWF.
5 Dec 1998. Added INDEX field to the XCOLORS_LOAD event structure. This
field holds the current color table index number. DWF.
5 Dec 1998. Modified the way the colorbar image was created. Results in
greatly improved display for low number of colors. DWF.
6 Dec 1998. Added the ability to notify an unlimited number of objects. DWF.
12 Dec 1998. Removed obsolete Just_Reg keyword and improved documetation. DWF.
30 Dec 1998. Fixed the way the color table index was working. DWF.
4 Jan 1999. Added slightly modified CONGRID program to fix floating divide
by zero problem. DWF
2 May 1999. Added code to work around a Macintosh bug in IDL through version
5.2 that tries to redraw the graphics window after a TVLCT command. DWF.
5 May 1999. Restore the current window index number after drawing graphics.
Not supported on Macs. DWF.
9 Jul 1999. Fixed a couple of bugs I introduced with the 5 May changes. Sigh... DWF.
13 Jul 1999. Scheesh! That May 5th change was a BAD idea! Fixed more bugs. DWF.
31 Jul 1999. Substituted !D.Table_Size for !D.N_Colors. DWF.
1 Sep 1999. Got rid of the May 5th fixes and replaced with something MUCH simpler. DWF.
14 Feb 2000. Removed the window index field from the object notify structure. DWF.
14 Feb 2000. Added NOTIFYPRO, DATA, and _EXTRA keywords. DWF.
20 Mar 2000. Added MODAL, BLOCK, and COLORINFO keywords. DWF
20 Mar 2000. Fixed a slight problem with color protection events triggering
notification events. DWF.
31 Mar 2000. Fixed a problem with pointer leakage on Cancel events, and improved
program documentation. DWF.
17 Aug 2000. Fixed a problem with CANCEL that occurred only if you first
changed the gamma settings before loading a color table. DWF.
10 Sep 2000. Removed the requirement that procedures and object methods must
be written with an _Extra keyword. DWF.
5 Oct 2000. Added the File keyword to LOADCT command, as I was suppose to. DWF.
5 Oct 2000. Now properly freeing program pointers upon early exit from program. DWF.
7 Mar 2001. Fixed a problem with the BLOCK keyword. DWF.
12 Nov 2001. Renamed Congrid to XColors_Congrid. DWF.
14 Aug 2002. Moved the calculation of NCOLORS to after the draw widget creation
to fix a problem with !D.TABLE_SIZE having a correct value when no windows had
been opened in the current IDL session. DWF.
14 Aug 2002. Fixed a documentation problem in the NOTIFYID keyword documentation
that still referred to !D.N_COLORS instead of the current !D.TABLE_SIZE. DWF.
27 Oct 2003. Added INDEX keyword. DWF.
29 July 2004. Fixed a problem with freeing colorInfoPtr if it didn't exist. DWF.
5 December 2005. Added NOSLIDERS keyword and performed some small cosmetic changes. DWF.
27 Sep 2006. Fixed a problem in which XCOLORS set device to indexed color mode. DWF.
14 May 2008. Added ability to read the Brewer Color Table file, if available. DWF
8 July 2008. Small change in how the program looks for the Brewer file. DWF.
1 October 2008. Added a button to switch from either BREWER color tables to IDL
color tables, depending upon which is showing currently. The button ONLY appears
if the file fsc_brewer.tbl can be found somewhere in the IDL distribution. DWF.
7 October 2008. Whoops! The 1 Oct change wasn't as simple as that. Fixed problems with
destroy and restarting the program with respect to keywords that are set, etc. DWF.
12 October 2008. Changed license to BSD Open Software License. DWF.
21 October 2008. Found a problem with MODAL operations that I fixed. However, that
led to problems with how I was switching from IDL to Brewer colors and visa versa,
so I changed that mechanism, too.
21 October 2008. Added OBJECT_DATA keyword so that I can get additional information
about the state of the color table tool into object methods. DWF.
12 April 2009. Add REVERSE keyword and Reverse Color Table button. DWF.
28 April 2009. In looking for a Brewer color table file, I replaced all FILE_WHICH
commands with FIND_RESOURCE_FILE commands. DWF.
NAME: XFONT_4 PURPOSE: XFONT_4 is a modal widget for selecting and viewing an X Windows font. CATEGORY: Widgets, Fonts CALLING SEQUENCE: Selected_font = XFONT_4() INPUTS: No explicit inputs. KEYWORD PARAMETERS: GROUP: The widget ID of the widget that calls XFONT_4. When this ID is specified, a death of the caller results in a death of XFONT_4. PRESERVE: If set, XFONT_4 saves the server font directory in common blocks so that subsequent calls to XFONT_4 start-up much faster. If not set, the common block is cleaned. OUTPUTS: A string containing the font name. If nothing is selected, or the CANCEL button is pressed, a null string is returned. COMMON BLOCKS: XFONT_4_COM. SIDE EFFECTS: Initiates the XManager if it is not already running. Resets the current X Window font. RESTRICTIONS: The current X window font is manipulated without being restored. PROCEDURE: Create and register the widget and then exit. MODIFICATION HISTORY: Modified from a template written by: Hans-Joachim Bothe, CreaSo GmbH, November, 1991, by DMS, RSI, November, 1992. 1 July 1995, AB, Fixed sizing of toggle buttons.
NAME:
XPC
PURPOSE:
This function allows a user to interactively pick a postscript file
from a list that can be scrolled. The file will be plotted in a
separate gv window.
CATEGORY:
Widgets, postscript
CALLING SEQUENCE:
XPC
KEYWORD PARAMETERS:
scratchDir - defaults to /u/$USER/tmpdir (or value of $TMPDIR)
programs running on different computers will have differnt
areas. This must be the same used by the plotting-control
software, setup_xpc.pro.
NODELETE - if set, files in sractchDir (from previous invocation) are
not deleted when application is started.
TITLE: A scalar string to be used for the window title.
GROUP: The widget ID of the widget that calls xpc. When this
ID is specified, a death of the caller results in the death of
the xpc widget application.
NFILES - # of files to show at one time in window (def=10)
filter - search filter for plots to show in window (def=XPC_*.ps)
psPlotFile - file with plotting application keeps plotting
(def=scratchDir+'/GV2plot.ps')
psApp - file plotting application (def="gv")
appSwitch - switch for file plotting application (def="--watch")
updateTime - time in seconds between checks to see if list needs refreshed (def=0.5)
ext - file extensions to look for (def='ps')
OUTPUTS:
Copies selected file to /GV2plot.ps, which "gv --watch" is
looking for to plot.
OPTIONAL ENVIRONMENTAL VARIABLES:
USER - username.
TMPDIR - default to '$USER/.XPC'
XPC_SCRATCH - directory for postscript files; defaults to $TMPDIR/XPC_scratch/
XPC_SCRATCH_NFILES - if not found, defaults to 10 files (these are postscript
filesand are not deleted when the program exits)
PROCEDURE:
a program that plots like:
IDL> setup_xpc
IDL> plot, indgen(111)
IDL> ...
IDL> unsetup_xpc ; graphics won't show up until this is called
setup_xpc will startup XPC, if not running, which will, in turn, startup gv
if it is not running on the same computer. Unfortunately, it is not easy to tell
if XPC is running on the same computer in another IDL process.
the postscript file written to in the above example is GV2buffer.ps (by
default). When XPC sees one of these, it copies it to GV2plot.ps, so gv
automatically replots it, and renames it to XPC_nnn.ps, where nnn is one
more than the highest number of the files XPC_*.ps.
NOTES:
You probably want the following line in your ~/.Xresources file to get the gv
program to refresh ever 1/2 second (default is every 1 second):
gv.watchFileFrequency: 501
this will make gv check for file changes ever 501 ms, rather than 1000 ms.
The Help display will tell you how to get color buttons in this widget.
RESTRICTIONS:
xpc only works on Linux/Unix systems where gv is in the PATH.
MODIFICATION HISTORY:
20-Aug-2013 exclude searches for gv that include libexec
09-Jul-2011 don't use /local, so can be used from different computers
18-Nov-2009 Written by Bill Davis for Eric Fredrickson
NAME:
XVAREDIT
PURPOSE:
This routine provides an editor for any IDL variable.
CATEGORY:
Widgets
CALLING SEQUENCE:
XVAREDIT, VAR
INPUTS:
VAR = The variable that is to be edited.
KEYWORD PARAMETERS:
NAME = The NAME of the variable. This keyword is overwritten with the
structure name if the variable is a structure.
GROUP = The widget ID of the widget that calls XVarEdit. When this
ID is specified, a death of the caller results in a death of
XVarEdit.
X_SCROLL_SIZE = The X_SCROLL_SIZE keyword allows you to set
the width of the scrolling viewport in columns.
Default is 4.
Y_SCROLL_SIZE = The Y_SCROLL_SIZE keyword allows you to set
the height of the scrolling viewport in rows.
Default is 4.
OUTPUTS:
VAR= The variable that has been edited, or the original when the user
selects the "Cancel" button in the editor.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Initiates the XManager if it is not already running.
RESTRICTIONS:
None known.
PROCEDURE:
Create and register the widget and then exit.
If the user selects "accept", the values in the editor are written
to the variable passed in, otherwise, they are ignored.
MODIFICATION HISTORY:
Written by: Steve Richards, February, 1991
Modified: September 96, LP - rewritten with TABLE widget
07-Oct-98 BD Took out check for "commit" because it was always
wrong.