This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Mon Jan 12 18:58:53 2004.
ROUTINE: tvim
USEAGE: tvim,a
tvim,a,scale=scale,range=range,xrange=xrange,yrange=yrange, $
aspect=aspect,title=title,xtitle=xtitle,ytitle=ytitle, $
noaxis=noaxis,interp=interp,colors=colors,c_map=c_map, $
stitle=stitle,rmarg=rmarg,clip=clip,labels=labels, $
pcharsize=pcharsize,lcharsize=lcharsize,nbotclr=nbotclr, $
clevels=clevels,nodata=nodata,rgb_nodata=rgb_nodata, $
barwidth=barwidth,position=position,noframe=noframe,rct=rct
PURPOSE: Display an image with provisions for
1. numbered color scale
2. plot title
3. annotated x and y axis
4. simplified OPLOT capability
5. manual or automatic scaling with smooth or discreet colors
6 special treatment of "invalid data" pixels
INPUT
a image quantity
Optional keyword input:
title
plot title
xtitle
x axis title
ytitle
y axis title
stitle
color key title (drawn to the right of color scale)
rmarg
right margin expansion factor to provide more room for extra wide
color scale annotation (default=1)
xrange
array spanning entire x axis range. (default = [0,x_dimension-1])
yrange
array spanning entire y axis range. (default = [0,y_dimension-1])
NOTE:TVIM only uses min(XRANGE), max(XRANGE), min(YRANGE) and max(YRANGE).
scale
if set draw color scale. SCALE=2 causes steped color scale
range
two or three element vector indicating physical range over which
to map the color scale. The third element of RANGE, if specified,
sets the step interval of the displayed color scale. It has no
effect when SCALE is not set. E.g., RANGE=[0., 1., 0.1] will
cause the entire color scale to be mapped between the physical
values of zero and one; the step size of the displayed color
scale will be set to 0.1.
clip
specifies a set percentage of pixels which will be left outside
the color scale. Larger values of CLIP yield images with greater
contrast. For example if clip=2 then the color scale range will
be set to include 98% of the pixels and to exclude the brightest
1% and the dimmest 1% of the pixel brightness distribution.
Keyword RANGE overides the effect of CLIP.
If CLIP is a two element vector, the upper and lower percentile
range can be specified. For example CLIP=[0,95] will exclude the
top 5%.
An alternative is to set CLIP to a single negative integer. This
causes the grey scale range to be obtained from the max and min
value of the image array after it is filtered by a 2-D median
filter. The radius of the median filter is set to -clip. Median
filtering is effective in removing "salt and pepper" noise,
(isolated high or low values). For example, setting clip=-1
causes the code to check the 9 element superpixel centered at
each pixel for median values. A single extremely large or small
value does not affect the final value of the median at each pixel
point.
aspect
the x over y aspect ratio of the output image. If not set, aspect
is set to (size_x/size_y) of the input image.
position
specifies the lower left and upper right TVIM frame position in
normal coordinates. When set POSITION overides the setting of
ASPECT.
noaxis
if set do not draw x and y numbered axis around image. Instead
just draw a box
noframe
if set no not draw anything around image, not even a box
interp
TVIM normally uses nearest neighbor sampling to resize the image
to fill the data window area. If INTERP is set the resizing
operation uses bilinear interpolation
If INTERP = 2 the interpolation range is adjusted so that there
is a half pixel border around the plot. This ensures that the
smoothed image properly represents the cell center values of the
pixels, but introduces an extrapolation on the outer edges. This
option has noticeable effects for small (<20) image arrays.
NOTE: When writing to a Postscript file the resizing operation is
accomplished by changing the pixel size. Thus the INTERP
parameter has no effect on Postscript output.
pcharsize
character size of numbers along x and y axis and the title
(default is !p.charsize if non-zero, 1 otherwise)
NOTE: The character size of the x and y-axis number scale
annotation may be independently controlled by the !x.charsize or
!y.charsize system variables. For example, the x and y axis
number scale characters may be made invisible by setting these
variables to a very small non-zero number before calling TVIM.
Remember to restore normal character sizes by setting !x.charsize
and !y.charsize to 1 or zero after the call to TVIM.
lcharsize
character size of color key number or labels (default is
!p.charsize if non-zero, 1 otherwise)
barwidth
width of color key which appears to right of image when SCALE is
set. (default=1)
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies. When the COLORS array is set TVIM
will map values of A into the color values specified in COLORS.
How physical values are assigned to color values depends on how
the RANGE parameter is set, as shown in this table:
RANGE color_value
----- -----------
1. not set COLORS(A)
2. [amin,amax] COLORS((A-amin)/dinc)
3. [amin,amax,inc] COLORS((A-amin)/inc)
where amin, amax and inc are user specified elements of RANGE
and dinc=(amax-amin)/n_elements(COLORS). In case 1, A is used
directly as a subscript into COLORS. When RANGE is not set
legend labels should be used to annotate the color values. In
case 2, A is scaled so that each color defined in COLORS
represents a proportionate fraction of the total dynamic range.
In case 3, amin and inc (and not amax) are used to control which
colors are associated with given physical values. See examples.
c_map
TVIM normally rescales the input image to span the entire color
table range. Setting C_MAP disables this automatic re-scaling.
This is useful when the image byte values correspond to a
particular color mapping that could be destroyed by the
rescaling process (E.G. a gif image).
NOTE: When the number of IDL color table entries is less than
256 some colors may be lost. Use a private color map to avoid
this. See examples.
nbotclr
number of reserved colors at the bottom of the color
table. Color values between 0 and nbotclr-1 will not
be used in the displayed image. This allows the
bottom of the table to be set to special colors which
will not be used in the displayed the image. This
keyword is disabled when either the COLORS or NODATA
options are used. (default=1)
NOTE: by default the color table indicies used within a TVIM
image is limited to the range 1 to !d.n_colors-2. In most
predefined color tables, color index 0 and !d.n_color-1
correspond to pure black and white, respectively. TVIM uses
these color indicies as background and foreground colors for
region blanking and axis annotation. Color tables which do not
define black and white in these index locatations are not good
choices for TVIM plots, unless the first and last color table
entries are redefined as black and white using TVLCT, e.g.,
tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
NOTE: the procedure DCOLORS can be used to load a set
of discreet colors in the bottom 11 color values
(0-10). The original color table is resampled to fit
between color value 11 and the !d.n_colors-1.
nodata
pixel values which are interpreted as invalid data. Pixels
containing this data value are colored with color RGB_NODATA.
rgb_nodata
an RGB value (a 3 component vector) used to color pixels filled
with invalid data. (default = [0,0,0])
NOTE: NODATA and RGB_NODATA override the effect of NBOTCLR
rct
if set, reverse direction of color table. This keyword can be
used on black & white printers to allow large field values to be
represented by dark colors. Note, this feature is implemented
by reversing the association between physical values and color.
Though it reverses the colors on the color key, it does not
affect the actual color table.
KEYWORD OUTPUT:
clevels
physical values at the color key tic marks. Use this to set
contour levels in a subsequent call to CONTOUR.
SIDE EFFECTS:
Setting SCALE=2 changes the color scale using the STEP_CT
procedure. The color scale may be returned to its original
state by the command, STEP_CT,/OFF
PROCEDURE:
TVIM first determines the size of the plot data window with a
dummy call to PLOT. When the output device is "X", CONGRID is
used to scale the image to the size of the available data
window. Otherwise, if the output device is Postscript,
scaleable pixels are used in the call to TV.
If the input image quantity is not of type byte, TVIM converts
them to byte by scaleing the input between 0 and !d.n_colors-1.
If the input is already a byte array and if either the number of
color table entries is 256 or if C_MAP is set, then no scaling
is done. This is to ensure consistency with specially defined
private color tables.
After the the image is drawn TVIM calls PLOT again to draw the x
and y axis and titles. Finally if scale is set, TVIM calls the
COLOR_KEY procedure to draw the color scale just to the right of
the data window.
RESTRICTIONS:
A stepped color scale (SCALE = 2 option) is not available when
writing to a black & white postscript file (i.e., when the
DEVICE color option is not enabled).
DEPENDENCIES: COLOR_KEY, STEP_CT, PRANK
EXAMPLES:
; Plot a GIF image with its own preset RGB
; table (perhaps from a digitized video image)
window,colors=256 ; set up a private color map
read_gif,'/home/paul/gif/el-nino.gif',im,r,g,b
tvlct,r,g,b
tvim,im,/c_map
;
;
; Plot an image with descreet greyscale values to a printer
; which has its own hard-wired color table.
im=randata(128,128,s=4)
immx=max(im) & immn=min(im)
!p.multi=[0,2,2]
tvim,im,/scale,colors=!p.color*indgen(4)/3.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(5)/4.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(8)/7.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(10)/9.,range=[immn,immx]
;
;
; Display a map of surface types (green=veg, blue=water, red=sand)
; Notice how RANGE is used to associate physical values with colors.
; (use im from the previous example)
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
tvlct,[0,0,0,255],[0,255,0,0],[0,0,255,0]
!p.multi=[0,2,2]
colors=[1,2,3] & labels=[' veg',' water',' sand']
range=[immn,immx,delim/3]
tvim,im,/scale
tvim,im,colors=colors,range=range,/scale
tvim,im,colors=colors,range=range,/scale,labels=labels,lch=2
!p.multi=0
range=[immn-.25*delim,immx+.25*delim,delim/2]
lbl=[' veg!c region 1',' water!c region 2',' sand!c region 3']
tvim,im,colors=colors,range=range,/scale,labels=lbl,lch=2,rmarg=2,pchar=1.2
;
;
; Display the image from previous example and overlay a contour plot
;
loadct,5
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
xrange=[-120,-100]
yrange=[20,50]
range=[immn,immx]
xx=findrng(xrange,128)
yy=findrng(yrange,128)
tvim,im,/scale,xrange=xrange,yrange=yrange,clevels=clevels,range=range
contour,im,xx,yy,levels=clevels,/overplot
; NOTE: You might prefer the results obtained from procedure CONFILL.
confill,im,xx,yy,/asp,levels=clevels
;
;
; Display a grey scale image and annotate certain points in color
;
loadct,0
dcolors
tvim,im,/scale,nbotclr=11 ; reserve some colors at bottom
xx=interpolate([40,80],randomu(iseed,10))
yy=interpolate([40,80],randomu(iseed,10))
plots,xx,yy,psym=2,color=1+indgen(10)
;
;
; Display a grey scale image and show nodata values in red
;
loadct,0
im=randata(100,100,s=4.5)
im(randomu(iseed,50)*9999)=-999.
tvim,im,/scale,nodata=-999.,rgb_nodata=[255,0,0]
;
;
; Postscript output with a reversed color scale. Because the
; background color is always RGB=(255,255,255) you must set the
; default color, !p.color, to a dark color if you want good contrast
; between the axis labels and the white paper. According to
; Didier's reversed color table a color index of 255 should produce
; black, but for some reason !p.color=255 doesn't work right.
; I think IDL is iterpreting !p.color=255 in some special way.
; So instead use !p.color=254; this seems to work fine.
;
toggle,/color
loadct,28
!p.color=254 ; don't use 255, don't ask me why
tvim,dist(20),/scale
toggle
;
; display data defined on a regular LAT-LON grid onto a given map
; projection. USE MAP_SET and MAP_IMAGE to create the map projection
; and to warp the image. Then use BOXPOS to position the TVIM frame
; to correctly register the map and image
IMAGE = sin(!pi*findrng(0,24,200))#sin(!pi*findrng(0,12,200))
!p.multi=[0,1,2]
map_set,45,0,/ortho,/advance,pos=boxpos(/aspect)
newimage=map_image(image,/bilin,latmin=-90,latmax=90,lonmin=-180,lonmax=180)
tvim,newimage,title='Warped data',pos=boxpos(/get),/scale
map_set,45,0,/ortho,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
tvim,image,xrange=[-180,180],yrange=[-90,90],/scale, $
title='Unwarped data',xtitle='Longitude',ytitle='Latitude'
map_set,0,0,/cyl,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
; use MAP_SET2 to mask out land areas. Note that the example below is
; unusual. MAP_SET2 doesn't always produce such nicely filled land areas.
; Typically one must run MAP_SET2 with /SAVE
; to create a ascii file containing the continental boundary lat-lon
; coordinates. Then use an editor to group the continental coordinates
; line segments to form closed contours which POLYFILL can understand
; (the call to POLYFILL is enabled by setting con_color).
;
image=randata(256,256,s=2.5)
tvim,image
map_set2,-64,-64,/cont,limit=[-65.1,-64.5,-64,-62],/ortho,con_col=100,$
pos=boxpos(/get),/noerase,/grid
;
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS:
28jan93: switched from PUT_COLOR_SCALE to COLOR_KEY
11feb93: added INTERP keyword
11feb93: added C_MAP keyword
11feb93: added STITLE keyword
20apr93: added RMARG keyword, centered image in plot window
23apr93: call COLOR_KEY before TV. Now stepped color scales copy to PS file
10sep93: deal with perfectly flat images. No more math error when a=0
14sep93: added CLIP keyword
11feb94: added PCHARSIZE,LCHARSIZE,LABELS, and COLORS keywords
18feb94: added NBOTCLR keyword
16mar94: added INTERP=2 option and adjusted centering of pixels
08Jul94: added NODATA and RGB_NODATA keywords
04Aug94: added BARWIDTH keyword
04Aug94: defaulted PCHARSIZE and LCHARSIZE to !P.CHARSIZE if non-zero
02Mar95: added POSITION keyword
31Mar95: added NOAXIS keyword
24may95: initial sizing includes allowance for PCHARSIZE > 1
06sep95: color indecies used in plot now run from 1 to !d.ncolors-2
24jul96: do a REFORM(a) to allow tvim,a(1,*,*) to work with no complaints
01sep96: added the RCT keyword
(See /home/drw/idl/esrg/2tvim.pro)
NAME:
ACOSD
PURPOSE:
Return the inverse cosine of a value, in degrees rather then radians.
CALLING SEQUENCE:
deg = acosd(x)
INPUTS:
value cosine of angle
OPTIONAL INPUTS:
OUTPUTS:
Angle in degrees returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/acosd.pro)
NAME:
ACOSD
PURPOSE:
Return the inverse cosine of a value, in degrees rather then radians.
CALLING SEQUENCE:
deg = acosd(x)
INPUTS:
value cosine of angle
OPTIONAL INPUTS:
OUTPUTS:
Angle in degrees returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/acosd.pro)
ROUTINE: addpath
PURPOSE:
USEAGE: addpath,pathname,cut=cut
INPUT:
pathname Name of new path to add to this session's directory path.
if pathname is already present in !path no action is taken.
This last feature allows addpath to be repeatedly executed
(e.g., within a script) without affecting !path after the
first invocation.
KEYWORD INPUT:
cut If set and pathname is set, the element of !path that
matches pathname is removed. If pathname is not
specified, the last element of !path is removed.
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLES:
addpath,'/home/paul/idl' ; add a path
addpath,'/local/idl/lib/wided',/cut ; remove a specific path
addpath,/cut ; remove last path element
addpath ; view !path
AUTHOR: Paul Ricchiazzi 04 Nov 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/addpath.pro)
Advance to the next frame.
USAGE: AF
OPTIONAL KEYWORDS:
/QUIET Do not print any information (default=print)
/HELP Print help information only (default=do not print)
USAGE NOTES:
(1) FSET must have been executed previously to create frame buffers.
AUTHOR: Liam Gumley, CIMSS/SSEC, 15-APR-1996 (liam.gumley@ssec.wisc.edu)
RELATED COMMANDS:
FSET Set up frames in memory
SF Show a frame and print frame information
BF Backup one frame
LF Loop frames
EXAMPLE:
; Create two graphics frames, and display an image in each
FSET,FRAMES=2
PLOT,INDGEN(20) & WAIT,2.0
AF
PLOT,-1*INDGEN(20) & WAIT,2.0
AF
(See /home/drw/idl/aux/af.pro)
ROUTINE: airmass
PURPOSE: compute airmass as a function of angle, sza, including
spherical earth effects
USEAGE: result=airmass(sza)
INPUT:
sza zenith angle
KEYWORD INPUT:
OUTPUT: relative airmass,
by definition the relative airmass = 1 for sza=0.
References:
1) Kasten, F 1966: A new table and approximate formula for relative
airmass. Arch. Meteor. Geophys. Bioklimatol. Ser. B, 14, 206-223
2) Kasten and Young, 1989: Applied Optics, 28, 4735-4738
recommended by Yankee Environmental Systems (MFRSR)
EXAMPLE:
sza=findrng(0,89.,dx=.1)
plot,sza,1./cos(sza*!dtor),yran=[1,30]
plot,sza,cos(sza*!dtor)*airmass(sza)
AUTHOR: Paul Ricchiazzi 09 Jan 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
(See /home/drw/idl/esrg/airmass.pro)
NAME : alignoffset
PURPOSE :
Determine the offsets of an image with respect to a reference image
CALIING SEQUENCE
OFFSET = alignoffset(IMAGE, REFERENCE, Cor)
INPUTS:
IMAGE the object image
REFERENCE the reference image
OUTPUT:
OFFSET a two-element array of the offset values
defined by OFFSET = (i, j) - (l, m)
where (i, j) is the object image coordinates of a feature
and (l, m), its reference image coordinates.
OPTIONAL OUTPUT:
Cor the maximum correlation coefficient
REMARK:
FFT method is used to mximize the cross-correlation
HISTORY:
1999 May, J. Chae
(See /home/drw/idl/jma/alignoffset.pro)
ROUTINE: align_cube
PURPOSE: align a series of images in a data cube to
the first image
USEAGE: align_cube, cube, aligned
INPUT: cube = array of images (x,y,t)
OUTPUT: aligned = data aligned to the first image
Example:
AUTHOR: Peter T. Gallagher, July 2001
(See /home/drw/idl/jma/align_cube.pro)
ROUTINE: align_cube2
PURPOSE: align a series of images in a data cube to
the first image
USEAGE: align_cube2, cube, aligned
INPUT: cube = array of images (x,y,t)
OUTPUT: aligned = data aligned to the first image
Example:
AUTHOR: Peter T. Gallagher, July 2001
(See /home/drw/idl/jma/align_cube2.pro)
ROUTINE: align_cube2
PURPOSE: align a series of images in a data cube to
the first image
USEAGE: align_cube2, cube, aligned, dispxy=dispxy
INPUT: cube = array of images (x,y,t)
OUTPUT: aligned = data aligned to the first image
KEYWORDS:
dispxy = the 2xN output vector containing the
offsets determined by ALIGNOFFSET
Example:
AUTHOR: Peter T. Gallagher, July 2001
expansion by David R. Williams, June 2002
(See /home/drw/idl/secis2/align_cube3.pro)
NAME: ALLSEGMENTS PURPOSE: This procedure plots the flux vs. wavelength for all four channels. CATEGORY: Analysis. CALLING SEQUENCE: ALLSEGMENTS, File, Slit, Binning INPUTS: File: Rootname of file, e.g. I9040104017. Include the path if the file is not in the current directory. If an array containing multiple filenames is used, the individual files will be averaged before display. Slit: Name of slit: 'LWRS', 'MDRS', 'HIRS' or 'PINH' Binby: Binning factor. Must be a power of 2. KEYWORD PARAMETERS: FLUXMIN:If included, use this as the minimum of the flux scale. The default is to use zero. FLUXMAX:If included, use this as the maximum of the flux scale. The default is to use the maximum value in any channel. WAVEMIN:If included, use as the minimum value of the wavelength scale. The default is 900 A. WAVEMAX:If included, use as the maximum value of the wavelength scale. The default is 1200 A. LOG: If set, use a log scale for the flux. HIST: If set, assumes the filename specifies a HIST file rather than a TTAG. CATALOG:Filename of a catalog to overplot. BRIGHTNESS: If included, convert the flux to a brightness in Rayleighs per Angstrom before plotting. This conversion assumes a filled slit. FLUXMIN and FLUXMAX will also be in these units. SUFFIX: A suffix which is added to the filenames, e.g. if the filenames are of the form I20514010001alif2ttagfcal-limb2.fit, the suffix is '-limb2' OUTPUTS: SIDE EFFECTS: Creates a plot showing flux vs. wavelength for all four channels. PROCEDURE: Straighforward. EXAMPLE: MODIFICATION HISTORY: Written by David Sahnow, 9/20/99. 28 September 1999 Added FLUXMIN keyword. 12 October 1999 Added LOG keyword. 21 November 1999 Added keyword to read HIST files. Previously assumed TTAG (in file name). 22 November 1999 Added segment labels to plots. 22 November 1999 Added automatic switch to try histogram mode if TTAG doesn't work. 23 November 1999 Now gracefully handles missing data. 8 December 1999 Added comment that rebinning doesn't properly combine errors. 23 January 2000 Added CATALOG and BRIGHTNESS keywords. 29 February 2000 Corrected positions of labels when WAVEMIN and WAVEMAX keywords are used. 2 March 2000 Corrected positions of labels when LOG keyword is used. 26 May 2000 Added SUFFIX keyword. 30 May 2000 Replaced call to SHOWFHEADER with SHOWFHEADER2. 2 June 2000 Added CATALOG keyword. 19 June 2000 Fixed bug introduced on 2 June - crashed if no catalog.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/allsegments.pro)
ratiolc is a program which calculates a ratio lightcurve
check lab book (27/09/01) for furthur details
Lightcurve value = (bp - bg)/(bp +bg)
remember to check bin size and set it to appropriate level
INPUTS cubein:a cube of images
needs a lot of work on the commenting side of things
OUTPUTS lc :the lightcurve
bg :array of background levels
bp :array of bright point levels
nbg:number of pixels at bg level
nbp:number of pixels at bp level
EXAMPLE ratiolc,net1_cak,lc_net1_cak,bgcak,bpcak,nbgcak,nbpcak
ratiols,net1_0,lc_net1_0
NEW CALLING PROCEDURE
ratiolc,cube,lightcurve,threshold,wander_limit,num_of_pixels_included,background_level
check bin size
AUTHORS R.T.James McAteer, David R. Williams Sept '01
ALTERATIONS: loads and loads, too many to list, at least version 5 or 6 by now.
mainly to incorporate new methods of creation of the lightcurve
final version now uses DRW & JMA 'getstuff' function
(See /home/drw/idl/vtt/post_bbso/alt_ratiolc.pro)
PRO anicontour,data,contours
contour,data(*,*,0)
sizer=tvrd()
s=size(sizer)
d=size(data)
contours=bytarr(s(1),s(2),d(3))
FOR i=0,d(3)-1 DO BEGIN
contour,data(*,*,i)
contours(*,*,i)=tvrd()
ENDFOR
END
(See /home/drw/idl/secis/anicontour.pro)
PRO anisurf,data,surph
tvim,data(*,*,0)
sizer=tvrd()
s=size(sizer)
d=size(data)
surph=bytarr(s(1),s(2),d(3))
FOR i=0,d(3)-1 DO BEGIN
tvim,data(*,*,i)
surph(*,*,i)=tvrd()
ENDFOR
END
(See /home/drw/idl/secis/anisurf.pro)
PRO anicontour,data,contours
contour,data(*,*,0)
sizer=tvrd()
s=size(sizer)
d=size(data)
contours=bytarr(s(1),s(2),d(3))
FOR i=0,d(3)-1 DO BEGIN
contour,data(*,*,i)
contours(*,*,i)=tvrd()
ENDFOR
END
(See /home/drw/idl/secis/anisurface.pro)
NAME:
ARG_PRESENT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Determine whether output parameter has been passed (IDL4 compatibility)
CALLING SEQUENCE:
PRESENT = ARG_PRESENT(ARG)
DESCRIPTION:
ARG_PRESENT tests whether an argument to a function or procedure
can be used as an output parameter. The behavior of this function
is identical to that of the built-in ARG_PRESENT function in IDL
version 5 or greater, and is meant to give the same functionality
to programs in IDL 4.
An IDL procedure or function can use ARG_PRESENT to decide whether
the value of a positional or keyword parameter will be returned to
the calling procedure. Generally, if the caller did not pass the
parameter then there is no need to compute the value to be
returned.
To be a valid output parameter, the caller must have passed a
named variable into which the result is stored. If the caller
passed the parameter by value (e.g., an expression or a
subscripted array) the value cannot be returned and ARG_PRESENT
returns 0.
INPUTS:
ARG - the parameter to be tested. It can be either a positional
or a keyword parameter. Passing a normal local variable
(i.e., not a passed parameter) will cause ARG_PRESENT to
return zero.
RETURNS:
Returns a value of 1 if ARG is a valid output parameter, and a
value of 0 otherwise.
EXAMPLE:
Consider the following procedure:
PRO TESTARG, ARG1
print, ARG_PRESENT(ARG1)
END
This procedure will print 1 when an ARG1 can be used as an output
parameter. Here are some examples of the results of TESTARG.
IDL> testarg
0
IDL> testarg, x
1
IDL> testarg, findgen(10)
0
In the first case, no argument is passed, so ARG1 cannot be a
return variable. In the second case, X is undefined, but it is
still a legal named variable capable of receiving an output
parameter. In the third case, FINDGEN(10) is an expression which
cannot receive an output parameter.
SEE ALSO:
ARG_PRESENT in IDL version 5
MODIFICATION HISTORY:
Written, CM, 13 May 2000
Small documentation and bug fixes, CM, 04 Jul 2000
(See /home/drw/idl/aux/markwardt/arg_present.pro)
NAME:
ARG_PRESENT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Determine whether output parameter has been passed (IDL4 compatibility)
CALLING SEQUENCE:
PRESENT = ARG_PRESENT(ARG)
DESCRIPTION:
ARG_PRESENT tests whether an argument to a function or procedure
can be used as an output parameter. The behavior of this function
is identical to that of the built-in ARG_PRESENT function in IDL
version 5 or greater, and is meant to give the same functionality
to programs in IDL 4.
An IDL procedure or function can use ARG_PRESENT to decide whether
the value of a positional or keyword parameter will be returned to
the calling procedure. Generally, if the caller did not pass the
parameter then there is no need to compute the value to be
returned.
To be a valid output parameter, the caller must have passed a
named variable into which the result is stored. If the caller
passed the parameter by value (e.g., an expression or a
subscripted array) the value cannot be returned and ARG_PRESENT
returns 0.
INPUTS:
ARG - the parameter to be tested. It can be either a positional
or a keyword parameter. Passing a normal local variable
(i.e., not a passed parameter) will cause ARG_PRESENT to
return zero.
RETURNS:
Returns a value of 1 if ARG is a valid output parameter, and a
value of 0 otherwise.
EXAMPLE:
Consider the following procedure:
PRO TESTARG, ARG1
print, ARG_PRESENT(ARG1)
END
This procedure will print 1 when an ARG1 can be used as an output
parameter. Here are some examples of the results of TESTARG.
IDL> testarg
0
IDL> testarg, x
1
IDL> testarg, findgen(10)
0
In the first case, no argument is passed, so ARG1 cannot be a
return variable. In the second case, X is undefined, but it is
still a legal named variable capable of receiving an output
parameter. In the third case, FINDGEN(10) is an expression which
cannot receive an output parameter.
SEE ALSO:
ARG_PRESENT in IDL version 5
MODIFICATION HISTORY:
Written, CM, 13 May 2000
Small documentation and bug fixes, CM, 04 Jul 2000
(See /home/drw/idl/aux/markwardt/cmarg_present.pro)
ROUTINE: armbasetime
PURPOSE: The base_time variable provided by ARM net_cdf files is the
number of seconds since jan 1, 1970 00:00:00 UTC. This
procedure converts base_time to the current date in yymmdd
format, and the number of hours since the most recent
Grenich midnight (00:00:00 UTC).
USEAGE: armbasetime,base_time,time,yymmdd,file=file
INPUT:
bt number of seconds since jan 1, 1970 00:00:00 UTC.
KEYWORD_INPUT
file name arm net_cdf file. If this quantity is set the value
of bt is set from the value read from the file.
OUTPUT:
time time since Grenich midnight of the current day
yymmdd date string in yymmdd format
EXAMPLE:
file='/home/paul/arm/iop_97/mfrsr/sgpmfrsrC1.a1.970915.000000.cdf'
armbasetime,file=file,bt,time,yymmdd
print,bt,time," ",hms(3600*time)," ",yymmdd
AUTHOR: Paul Ricchiazzi 05 Jun 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/armbasetime.pro)
NAME: ARRAYPS PURPOSE: This procedure takes an array array(Xdim,Ydim,Rows,Columns) and displays it in a Postscript plot. CATEGORY: Plotting. CALLING SEQUENCE: ARRAYPS, Array, Xdim, Ydim, Rows, Columns INPUTS: Array: The input array to display. The array may have two (Xdim,Ydim), three (Xdim,Ydim,nnn) dimensions. Xdim:: Size of first dimension of Array. Ydim: Size of second dimension of Array. Rows: Number of rows of plots. Columns:Number of columns of plots. KEYWORD PARAMETERS: MTITLE: A string array containing the titles for each column of plots. mtitle(columns). XTITLE: The title for each row of plots. YTITLE: The y axis label (not recommended if Columns > 1). MINC: Minimum value of array to scale to. MAXC: Maximum value of array to scale to. XSCALE: A vector of size Xdim which contains the coordinates for each x pixel. It must be a linear scale. May also be a two dimensional vector, with size (Xdim,Rows*Columns). In this case, each plot can have its own x scale. YSCALE: A vector of size Ydim which contains the coordinates for each y pixel. It must be a linear scale. May also be a two dimensional vector, with size (Xdim,Rows*Columns). In this case, each plot can have its own y scale. COLORBAR: If set and nonzero, a color bar will be plotted. COLORPS:If set, generate a color PostScript file. If set to an [N,3] vector, use the three axes as R, G, and B; otherwise use the default color table (probably loaded using TVLCT). Does not reverse like in the B&W case. as is (previous SQUARE: If square=1, square pixels are used. If square is not set, or square=0, the axes are scaled according to XSCALE and YSCALE if they are included. (Square pixels are the default if XSCALE and YSCALE are not used.) Square pixels should be used for plotting spatial vs. wavelength plots. If SQUARE=2, then the page is filled with the plot. LANDSCAPE: Print as a landscape file. Default is 8.5 x 11. XPSIZE: Sets the x paper size to this value. YPSIZE: Sets the y paper size to this value. XMIN: Minimum x value to display. XMAX: Maximum x value to display. YMIN: Minimum y value to display. YMAX: Maximum y value to display. LOG: If set and nonzero, a logarithmic scale rather than a linear scale will be used. VERBOSE:If set, extra information is printed while the procedure is running. ENCAPSULATED: If present and nonzero, print a smaller image for encapsulation. BLINE: Wavelength vector of lines to identify at the bottom of the plot. BTEXT1: String array of text to be used to annotate lines in BLINE. Must be included if BLINE is included. BPOS: Y position of data labelled by BLINE. If nonzero, line from label will extend to this position. BFONTSIZE: Font size of bottom labels TLINE: Wavelength vector of lines to identify at the top of the plot. TTEXT1: String array of text to be used to annotate lines in TLINE. Must be included if TLINE is included. TPOS: Y position of data labelled by TLINE. If nonzero, line from label will extend to this position. TFONTSIZE: Font size of top labels FITLABEL: Set if labels font should be adjusted to fit. SEPSCALE: If set, separately scale each subplot in Z between zero and the maximum of the subplot before plotting. + all keywords accepted by PLOT. SIDE EFFECTS: Sends data to a PostScript file. Note that the file must be opened and closed outside of this function. PROCEDURE: EXAMPLE: MODIFICATION HISTORY: Written by David Sahnow. 9 August 1992 Moved colorbar to before image so overplot will work. 8 April 1994 Corrected bug if not called with encapsulated or colorbar. 27 May 1996 Added square=2 option. 11 February 1997 Added labelling of lines using DSLINEID_PLOT. Still not using all features of that procedure, however. 11 February 1997 Modified to allow XSCALE to be multidimensional. 14 February 1997 Changed colorbar so that it has discrete steps for integer input arrays. 21 February 1997 Added XPSIZE, YPSIZE keywords. 31 March 1997 Added scaled XRBORD to ensure it equals 1.0 if XPSIZE = 72.0. 18 June 1997 Added automatic setting of font size, depending on page size. Forced [XYZ]CHARSIZE to 1.0. 18 June 1997 Added _extra keyword to pass keywords to oplot. 1 October 1997 Added BPOS, TPOS keywords, and added extend keyword in call to dslineid_plot. Added BFONTSIZE, TFONTSIZE keywords. 3 October 1997 Added FITLABEL keyword. 7 November 1997. Changed XRBORD constant. 14 November 1997 Changed some of the KEYWORD_SET calls to N_ELEMENTS() to avoid problems with the keyword being zero (meaning KEYWORD_SET assumes that the keyword was not passed. 21 November 1997 Added COLORPS keyword, requiring modification of MYSCALE. 23 February 1998 Changed XSIZE and YSIZE for encapsulated PostScript in order to make the bounding box a reasonable size. 25 November 1998 Added SEPSCALE keyword. 27 November 1998 Changed YSCALE to match XSCALE and be multidimensional. 14 December 1998 Changed SEPSCALE so it doesn't override COLORBAR. 8 July 1999 Changed YPAPER to include effects of multiple columns when using /ENCAPSULATED. 8 September 2000 Modified printing of the color bar, which was incorrect if the MINC or MAXC keywords were set. 12 October 2000 Modified to ensure XPFRACT = YPFRACT, i.e. scaling due to labels, etc. is the same in both directions.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/arrayps.pro)
NAME:
ARRDELETE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Remove a portion of an existing array.
CALLING SEQUENCE:
NEWARR = ARRDELETE(INIT, [AT=POSITION,] [LENGTH=NELEM])
DESCRIPTION:
ARRDELETE will remove or excise a portion of an existing array,
INIT, and return it as NEWARR. The returned array will never be
larger than the initial array.
By using the keywords AT and LENGTH, which describe the position
and number of elements to be excised respectively, any segment of
interest can be removed. By default the first element is removed.
INPUTS:
INIT - the initial array, which will have a portion deleted. Any
data type, including structures, is allowed. Regardless of
the dimensions of INIT, it is treated as a one-dimensional
array. If OVERWRITE is not set, then INIT itself is
unmodified.
KEYWORDS:
AT - a long integer indicating the position of the sub-array to be
deleted. If AT is non-negative, then the deleted portion
will be NEWARR[AT:AT+LENGTH-1]. If AT is negative, then it
represents an index counting from then *end* of INIT,
starting at -1L.
Default: 0L (deletion begins with first element).
LENGTH - a long integer indicating the number of elements to be
removed.
OVERWRITE - if set, then INIT will be overwritten in the process of
generating the new array. Upon return, INIT will be
undefined.
COUNT - upon return, the number of elements in the resulting array.
If all of INIT would have been deleted, then -1L is
returned and COUNT is set to zero.
EMPTY1 - if set, then INIT is assumed to be empty (i.e., to have
zero elements). The actual value passed as INIT is
ignored.
RETURNS:
The new array, which is always one-dimensional. If COUNT is zero,
then the scalar -1L is returned.
SEE ALSO:
STORE_ARRAY in IDL Astronomy Library
MODIFICATION HISTORY:
Written, CM, 02 Mar 2000
Added OVERWRITE and EMPTY1 keyword, CM 04 Mar 2000
$Id: arrdelete.pro,v 1.2 2001/03/25 18:10:41 craigm Exp $
(See /home/drw/idl/aux/markwardt/arrdelete.pro)
NAME:
ARRINSERT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Insert one array into another
CALLING SEQUENCE:
NEWARR = ARRINSERT(INIT, INSERT, [AT=POSITION] )
DESCRIPTION:
ARRINSERT inserts the contents of one array (INSERT) into
another (INIT), and returns the new array (NEWARR).
ARRINSERT will handle empty lists, which are represented as
undefined variables. If both input arrays are empty, then the
scalar -1L is returned, and the keyword COUNT is set to 0L.
INPUTS:
INIT - the initial array, into which INSERT will be inserted. Any
data type, including structures, is allowed. Regardless of
the dimensions of INIT, it is treated as a one-dimensional
array. If OVERWRITE is not set, then INIT itself is
unmodified.
INSERT - the array to be inserted into INIT, which must be of the
same or similar type to INIT. If INSERT is empty, then
INIT is returned unchanged. Regardless of the dimensions
of INSERT, it is treated as a one-dimensional array.
KEYWORDS:
AT - a long integer indicating the position of the newly inserted
sub-array. If AT is non-negative, then INSERT will appear
at NEWARR[AT]. If AT is negative, then INSERT will appear
at NEWARR[AT + (N+1)] where N is the number of elements in
INIT, which is to say if AT is negative, it indexes from the
end side of the array rather than the beginning.
Default: 0L (INSERT appears at beginning of INIT)
OVERWRITE - if set, then the initial array INIT will be
overwritten by the new array. Upon exit INIT becomes
undefined.
COUNT - upon return, the number of elements in the resulting
array.
EMPTY1, EMPTY2 - if set, then INIT (for EMPTY1) or INSERT (for
EMPTY2) are assumed to be empty (i.e., to have
zero elements). The actual values passed as INIT
or INSERT are then ignored.
RETURNS:
The new array, which is always one-dimensional. If COUNT is zero,
then the scalar -1L is returned.
SEE ALSO:
ARRDELETE, STORE_ARRAY in IDL Astronomy Library
MODIFICATION HISTORY:
Written, CM, 02 Mar 2000
Added OVERWRITE and EMPTY keywords, CM, 04 Mar 2000
Improved internal docs, and AT keyword docs, CM, 28 Sep 2000
Doc clarifications, CM, 29 Sep 2001
$Id: arrinsert.pro,v 1.3 2001/09/30 03:17:06 craigm Exp $
(See /home/drw/idl/aux/markwardt/arrinsert.pro)
NAME: arZOOM.PRO PURPOSE: To pick out the Active Region in WL during the first hour. CALLING SEQUENCE: arzoom,data INPUTS: data - image sequence cube HISTORY: D. Williams 4/6/99, similar to zoom1, which only works on images from an indexed datacube.
(See /home/drw/idl/bin/arzoom.pro)
NAME:
ASCII_TEMPLATE
PURPOSE:
Generate a template that defines an ASCII file format.
CATEGORY:
Input/Output.
CALLING SEQUENCE:
template = ASCII_TEMPLATE( [file] )
INPUTS:
file - Name of file to base the template on.
Default = use DIALOG_PICKFILE to get the file.
INPUT KEYWORD PARAMETERS:
browse_lines - Number of lines to read in at a time via the
GUI's browse button. Default = 50.
OUTPUT KEYWORD PARAMETERS:
cancel - Boolean indicating if the user canceled
out of the interface (1B = canceled).
OUTPUTS:
The function returns a template (structure) defining ASCII files
of the input file's format. Such templates may be used as inputs
to function READ_ASCII. (0 is returned if the user canceled.)
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
See DESCRIPTION.
DESCRIPTION:
This routine presents a graphical user interface (GUI) that assists
the user in defining a template.
ASCII files handled by this routine consist of an optional header
of a fixed number of lines, followed by columnar data. Files may
also contain comments, which exist between a user-specified comment
string and the corresponding end-of-line.
One or more rows of data constitute a "record." Each data element
within a record is considered to be in a different column, or "field."
Adjacent fields may be "grouped" into multi-column fields.
The data in one field must be of, or promotable to, a single
type (e.g., FLOAT).
EXAMPLES:
; Generating a template to be used later, maybe on a set of files.
template = ASCII_TEMPLATE()
; Same as above, but immediately specifying which file to use.
template = ASCII_TEMPLATE(file)
; Same as above, but returning flag if the user canceled.
template = ASCII_TEMPLATE(file, CANCEL=cancel)
; Generating and using a template in place for reading data.
data = READ_ASCII(file, TEMPLATE=ASCII_TEMPLATE(file))
DEVELOPMENT NOTES:
- see ???,!!!,xxx in the code
- errors preserving state when switch pages with 'back/next'
- make NaN default missing value as in reader ?
MODIFICATION HISTORY:
AL & RPM, 8/96 - Written.
(See /home/drw/idl/bin/ascii_template.pro)
usage: asd_mean, tag,wvl,spec,sigma,view=view
keyword input:
tag string used to match a certain subset of scan files listed
an index file, 'asd_scan_list', which is read from the current
working directory.
Each record in 'asd_scan_list' consists of three fields
separated by white space: the name of an asd scan file,
the utc time in hours, and the tag name, for example:
spectrum.001 15.003 scan1
spectrum.002 15.102 scan1
spectrum.003 15.233 scan2
spectrum.004 15.312 scan2
setting tag to 'scan1' whould select spectrum.001 and
spectrum.002, setting tag to ' ' or 'scan' would select
all four files. Since tag is compared to the whole record
you can also select a single file by setting tag to a
particular file name or time.
view make a plot of the scan
view=f makes an overplot with color=f*(!d.n_colors-1)
output:
wvl wavelength values
spec averaged spectra
sigma standard deviation of spectral scans (same size as spec)
example:
;;
w8x11
!p.multi=[0,2,2]
asd_mean,tag='60_NE',wvl,s60ne
asd_mean,tag='zenith',wvl,s0
asd_mean,tag='60_SW',wvl,s60sw
plot,wvl,s0
oplot,wvl,s60ne
oplot,wvl,s60sw
;; dont know tag name, use menu to find the one you want
asd_mean,wvl,s00
;;
(See /home/drw/idl/esrg/asd_mean.pro)
NAME:
ASIND
PURPOSE:
Return the inverse sine of a value, in degrees rather then radians.
CALLING SEQUENCE:
deg = asind(x)
INPUTS:
value sine of angle
OPTIONAL INPUTS:
OUTPUTS:
Angle in degrees returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/asind.pro)
NAME:
ASIND
PURPOSE:
Return the inverse sine of a value, in degrees rather then radians.
CALLING SEQUENCE:
deg = asind(x)
INPUTS:
value sine of angle
OPTIONAL INPUTS:
OUTPUTS:
Angle in degrees returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/asind.pro)
NAME:
ASPECT
PURPOSE:
This function calculates and returns the normalized position
coordinates necessary to put a plot with a specified aspect ratio
into the currently active graphics window. It works on the display
output window as well as in a PostScript output 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
CALLING SEQUENCE:
position = ASPECT(aspectRatio)
INPUTS:
aspectRatio: A floating point value that is the desired aspect
ratio (ratio of heigth to width) of the plot in the current
graphics output window. If this parameter is missing, an aspect
ratio of 1.0 (a square plot) is assumed.
KEYWORD PARAMETERS:
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.
WINDOWASPECT: The aspect ratio of the target window. If not provided,
the value is obtained from the current graphics window.
OUTPUTS:
position: A four-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.
EXAMPLE:
To create a plot with an aspect ratio of 1:2 and a margin of
0.10 around the edge of the output window, do this:
plotPosition = ASPECT(0.5, Margin=0.10)
PLOT, Findgen(11), POSITION=plotPosition
Notice this can be done in a single IDL command, like this:
PLOT, Findgen(11), POSITION=ASPECT(0.5, Margin=0.10)
MODIFICATION HISTORY:
Written by: David Fanning, November 1996.
Added better error checking, 18 Feb 1997, DWF.
Added WindowAspect keyword. 10 Feb 2000. DWF
(See /home/drw/idl/aux/aspect.pro)
NAME:
ATV
PURPOSE:
Interactive display of 2-D images.
CATEGORY:
Image display.
CALLING SEQUENCE:
atv [,array_name OR fits_file] [,min = min_value] [,max=max_value]
[,/autoscale] [,/linear] [,/log] [,/histeq]
REQUIRED INPUTS:
None. If atv is run with no inputs, the window widgets
are realized and images can subsequently be passed to atv
from the command line or from the pull-down file menu.
OPTIONAL INPUTS:
array_name: a 2-D data array to display
OR
fits_file: a fits file name, enclosed in single quotes
KEYWORDS:
min: minimum data value to be mapped to the color table
max: maximum data value to be mapped to the color table
autoscale: set min and max to show a range of data values
around the median value
linear: use linear stretch
log: use log stretch
histeq: use histogram equalization
OUTPUTS:
None.
COMMON BLOCKS:
atv_state: contains variables describing the display state
atv_images: contains the internal copies of the display image
atv_color: contains colormap vectors
atv_pdata: contains plot and text annotation information
RESTRICTIONS:
Requires IDL version 5.1 or greater.
Requires the GSFC IDL astronomy library routines,
for fits input.
For a current list of atv's bugs and weirdnesses, go to
http://cfa-www.harvard.edu/~abarth/atv/atv.html
SIDE EFFECTS:
Modifies the color table.
EXAMPLE:
To start atv running, just enter the command 'atv' at the idl
prompt, either with or without an array name or fits file name
as an input. Only one atv window will be created at a time,
so if one already exists and another image is passed to atv
from the idl command line, the new image will be displayed in
the pre-existing atv window.
MODIFICATION HISTORY:
Written by Aaron J. Barth, first release 17 December 1998.
Modified 26 Jul 1999 by D. Schlegel to add overplotting via
the routines ATVPLOT, ATVXYOUTS, ATVCONTOUR, and ATVERASE.
At present, these overplots are only in the main draw window.
The arguments C_ORIENTATION and C_SPACING are not supported.
The default color for all overplots is 'red'.
This version is 1.0b5, last modified 24 August 1999.
For the most current version, revision history, instructions,
and further information, go to:
http://cfa-www.harvard.edu/~abarth/atv/atv.html
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/ftv.pro)
ROUTINE: autorange
PURPOSE: given a range of values find a good tick mark interval
and return a properly formatted tick label. This routine
can be used with the axis procedure to add additional
axis which are not linearly related to the original
axis (see example)
USEAGE: autorange,range,ntick,tickv,tickl,ntickmax=ntickmax,$
cv=cv,log=log,colors=colors
INPUT:
range array of values
keyword input
ntickmax maximum allowed number of tick marks (default=10)
cv if present and non-zero, the tick values will cover a bit
less than the full range. Otherwise tick values cover a
bit more than the full range. Set CV when you want exactly
NTICK contour levels to appear on a contour plot.
OUTPUT:
ntick number of tick marks
tickv array of tick values
tickl formatted tick labels
KEYWORD OUTPUT
colors vector of color values covering full color range and having
one less element than ntick
; EXAMPLE:
autorange,[.011,.022],tickv,ntick,tickl & print,tickl
0.010 0.012 0.014 0.016 0.018 0.020
; plot solar spectrum with wavenumber on the lower x axis
; and wavelength on the upper x-axis
solar,wn,f
plot,wn,f,xstyle=5,xrange=[10000,40000],ymargin=[4,4]
axis,xaxis=0,xstyle=1,xtitle='Wavenumber (cm-1)'
autorange,1.e7/!x.crange,tickv,ntick,tickl
axis,xaxis=1,xticks=ntick-1,xtitle='Wavelength (nm)',$
xtickv=1.e7/tickv,xtickname=tickl
REVISIONS:
author: Paul Ricchiazzi mar94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/autorange.pro)
ROUTINE: autorange
PURPOSE: given a range of values find a good tick mark interval
and return a properly formatted tick label. This routine
can be used with the axis procedure to add additional
axis which are not linearly related to the original
axis (see example)
USEAGE: autorange,range,ntick,tickv,tickl,ntickmax=ntickmax,$
cv=cv,log=log,colors=colors
INPUT:
range array of values
keyword input
ntickmax maximum allowed number of tick marks (default=10)
cv if present and non-zero, the tick values will cover a bit
less than the full range. Otherwise tick values cover a
bit more than the full range. Set CV when you want exactly
NTICK contour levels to appear on a contour plot.
OUTPUT:
ntick number of tick marks
tickv array of tick values
tickl formatted tick labels
KEYWORD OUTPUT
colors vector of color values covering full color range and having
one less element than ntick
; EXAMPLE:
autorange,[.011,.022],ntick,tickv,tickl & print,tickl
0.010 0.012 0.014 0.016 0.018 0.020
; plot solar spectrum with wavenumber on the lower x axis
; and wavelength on the upper x-axis
solar,wn,f
plot,wn,f,xstyle=5,xrange=[10000,40000],ymargin=[4,4]
axis,xaxis=0,xstyle=1,xtitle='Wavenumber (cm-1)'
autorange,1.e7/!x.crange,ntick,tickv,tickl
axis,xaxis=1,xticks=ntick-1,xtitle='Wavelength (nm)',$
xtickv=1.e7/tickv,xtickname=tickl
REVISIONS:
author: Paul Ricchiazzi mar94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/autorange.pro)
FUNCTION: This procedure computes the AVERAGE of a the nk
fields stored in the array tab (nbcol,nblign,nk).
INPUTS : tab --> 3 dimensional array (nbcol x nblign x nk)
OUTPUTS : moy --> average of the fields (nbcol x nblign)
stdv --> standard deviation (nbcol x nblign)
nb --> number of points used in the average
USE : vertaver, array1, array2, outaver,outstdc,outelmts
CONTACT : Didier JOURDAN didier@esrg.ucsb.edu
(See /home/drw/idl/esrg/average.pro)
FUNCTION: This procedure computes the AVERAGE of a the nk
fields stored in the array tab (nbcol,nblign,nk).
INPUTS : tab --> 3 dimensional array (nbcol x nblign x nk)
OUTPUTS : moy --> average of the fields (nbcol x nblign)
stdv --> standard deviation (nbcol x nblign)
nb --> number of points used in the average
USE : vertaver, array1, array2, outaver,outstdc,outelmts
CONTACT : Didier JOURDAN didier@esrg.ucsb.edu
(See /home/drw/idl/old.esrg/average.pro)
PROJECT: TRACE NAME: avlight (new EUV average lightcurve) PURPOSE: A rountine to make an TOTAL (over all chosen pixels) lightcurve for 1024x1024 EUV images. CALLING SEQUENCE: newlight, data, curve, background, expo INPUTS: data - data cube curve - name of floating, 1-D output array to contain curve intensities background - name of floating 1-D array to contain background flux intensities HISTORY: based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by Peter Gallagher and David Williams for TRACE EUV data. part of the NEWLIGHT routine family, a version based on a *total* value summed over all pixels which are >(quiet-mean+)2*standard-deviation)
(See /home/drw/idl/bin/avlight.pro)
PROJECT: TRACE NAME: avlight2 (new EUV average lightcurve 512x512 version) PURPOSE: A rountine to make an TOTAL (over all chosen pixels) lightcurve for 1024x1024 EUV images. CALLING SEQUENCE: newlight, data, curve, background, expo INPUTS: data - data cube curve - name of floating, 1-D output array to contain curve intensities background - name of floating 1-D array to contain background flux intensities HISTORY: based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by Peter Gallagher and David Williams for TRACE EUV data. part of the NEWLIGHT routine family, a version based on a *total* value summed over all pixels which are >(quiet-mean+)2*standard-deviation)
(See /home/drw/idl/bin/avlight2.pro)
PROJECT: TRACE NAME: avlight2b (average new (UV) lightcurve), suitable for WL curves. PURPOSE: A rountine to make an TOTAL (over all chosen pixels) lightcurve for 1024x1024 EUV images. CALLING SEQUENCE: newlight2, data, curve, background, expo INPUTS: data - data cube curve - name of floating, 1-D output array to contain curve intensities background - name of floating 1-D array to contain background flux intensities HISTORY: based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by Peter Gallagher and David Williams for TRACE EUV data. AVLIGHT2B.PRO, a version based on an *average* value summed over all pixels which are >=((quiet-mean)+standard-deviation)
(See /home/drw/idl/bin/avlight2b.pro)
PROJECT: TRACE NAME: avlightb (new EUV average lightcurve) PURPOSE: A rountine to make an TOTAL (over all chosen pixels) lightcurve for 1024x1024 EUV images. CALLING SEQUENCE: newlight, data, curve, background, expo INPUTS: data - data cube curve - name of floating, 1-D output array to contain curve intensities background - name of floating 1-D array to contain background flux intensities HISTORY: based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by Peter Gallagher and David Williams for TRACE EUV data. part of the NEWLIGHT routine family, a version based on a *total* value summed over all pixels which are >(quiet-mean+)2*standard-deviation)
(See /home/drw/idl/bin/avlightb.pro)
ROUTINE: axgap,pos
PURPOSE: draw a "gap symbol" to indicate a gap in the axis number scale.
USEAGE: axgap,pos
INPUT:
pos two element vector indicating x,y data coordinates of the
axis break
KEYWORD INPUT:
one gap symbol drawn on one axis only
size size of gap symbol (default = 1, which corresponds to size
of default minor tick marks)
skew control skewness of gap symbol (default 0)
gap controls gap size (default 1)
OUTPUT:
none
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
y=smooth(randomn(iseed,100),5)
plot,y,xticks=5,xtickn=['1','2','3','4','5','20']
axgap
AUTHOR: Paul Ricchiazzi 31 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/axgap.pro)
ROUTINE: axgap,pos
PURPOSE: draw a "gap symbol" to indicate a gap in the axis number scale.
USEAGE: axgap,pos
INPUT:
pos two element vector indicating x,y data coordinates of the
axis break
KEYWORD INPUT:
one gap symbol drawn on one axis only
size size of gap symbol (default = 1, which corresponds to size
of default minor tick marks)
skew control skewness of gap symbol (default 0)
gap controls gap size (default 1)
OUTPUT:
none
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
y=smooth(randomn(iseed,100),5)
plot,y,xticks=5,xtickn=['1','2','3','4','5','20']
axgap
AUTHOR: Paul Ricchiazzi 31 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/axgap.pro)
ROUTINE: azimuth
PURPOSE: given a smoothly varying 2d field, AZIMUTH
computes the angle between the gradient direction
of the field and the y direction (angle measured
clockwise). This is is useful for computing the
satellite or solar azimuth angle when all you know
are the satellite or solar zenith angles. For
example the relative azimuth at each point in a
satellite image is given by
relaz=abs(azimuth(satzen,1,1)-azimuth(-sunzen,1,1))
which is the angle between the satellite unit
vector and the solar ray vector, both projected
onto the surface.
CALLING SEQUENCE:
result=azimuth(image,dx,dy)
INPUT:
image smoothly varying image quantity (e.g., solar zenith angle)
dx pixel spacing, x direction
dy pixel spacing, y direction
OUTPUT:
result angle between grad(image) and downward direction
(angle increases clockwise)
LIMITATION: the image is fit by a quadratic function of x and y
which is analytically differentiated to find the
gradient directions. An image which is not well
approximated by a quadratic function may produce
weird results.
EXAMPLE:
f=cmplxgen(400,400,/center)
tvim,f,/scale
f=abs(f)^2 ; should be perfectly fit by a quadratic function
a=azimuth(f,1,1)
loadct,5
tvim,a,scale=2,range=[-180,180,45]
author: Paul Ricchiazzi apr94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/azimuth.pro)
ROUTINE: azimuth
PURPOSE: given a smoothly varying 2d field, AZIMUTH
computes the angle between the gradient direction
of the field and the y direction (angle measured
clockwise). This is is useful for computing the
satellite or solar azimuth angle when all you know
are the satellite or solar zenith angles. For
example the relative azimuth at each point in a
satellite image is given by
relaz=abs(azimuth(satzen,1,1)-azimuth(-sunzen,1,1))
which is the angle between the satellite unit
vector and the solar ray vector, both projected
onto the surface.
CALLING SEQUENCE:
result=azimuth(image,dx,dy)
INPUT:
image smoothly varying image quantity (e.g., solar zenith angle)
dx pixel spacing, x direction
dy pixel spacing, y direction
OUTPUT:
result angle between grad(image) and downward direction
(angle increases clockwise)
LIMITATION: the image is fit by a quadratic function of x and y
which is analytically differentiated to find the
gradient directions. An image which is not well
approximated by a quadratic function may produce
weird results.
EXAMPLE:
f=cmplxgen(400,400,/center)
tvim,f,/scale
f=abs(f)^2 ; should be perfectly fit by a quadratic function
a=azimuth(f,1,1)
loadct,5
tvim,a,scale=2,range=[-180,180,45]
author: Paul Ricchiazzi apr94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/azimuth.pro)
ROUTINE: az_drw
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: az_drw, qlds
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(originally AZ_SA.PRO)
HISTORY:
Various modifications made by DRW to make it more suitable to the
SECIS CDS support data for the loop.
(See /home/drw/idl/secis/az_drw.pro)
ROUTINE: az_drw
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: az_drw, qlds
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(originally AZ_SA.PRO)
(See /home/drw/idl/secis/az_drw0.pro)
ROUTINE: az_drw2
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(334/353)
and SiX(353/334)
USEAGE: az_drw2, qlds
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(originally AZ_SA.PRO)
HISTORY:
Various modifications made by DRW to make it more suitable to the
SECIS CDS support data for the loop.
(See /home/drw/idl/cds/az_drw2.pro)
ROUTINE: az_sa
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: az_sa, qlds
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(See /home/drw/idl/cds/az_sa.pro)
ROUTINE: az_sa2, tweaked to run under LINUX 24-bit displays
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: az_sa, qlds
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(See /home/drw/idl/secis/az_sa2.pro)
ROUTINE: az_sa2
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: az_sa2, qlds (, /fit )
INPUT:
qlds calibrated CDS data in CDS qlds format
KEYWORDS
fit allow user to interactively define a fit
OUTPUT:
an IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
12-Dec-2000, Added fit keyword
, Routine will work with AZ_DDEP1 or AZ_DDEP2
(See /home/drw/idl/cds/az_sa2.pro)
ROUTINE: az_sa_mod
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: az_sa, qlds
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(See /home/drw/idl/secis/az_sa_mod.pro)
ROUTINE: balloon_drag
PURPOSE: compute drag on shere
USEAGE: result=balloon_drag(r,rho,v,cd)
KEYWORD INPUT:
r balloon radius in meters (default=1.0 m)
v wind velocity (mph) (default=5 m/s)
rho air density (default=1.29 kg/m3)
cd drag coefficient (default=0.2)
NOTE: 1 m/s = 3.60 km/hr = 2.23 mph = 1.94 knots
OUTPUT:
result drag force in newtons
SOURCE: Steve Robinson
NASA/MIT
stever@space.mit.edu
Drag on sphere = .5 * Cd * rho * v^2 * pi * r^2
Cd = function of sphere Reynolds number
(V*2*r)/(kinematic viscosity),
but 0.2 should be close.
EXAMPLE:
r=1. & v=10. & cd=.2
rho=rhoz(p0=1013.,t0=273.,z=1.,lr=7.)
print,balloon_drag(r,rho,v,cd)
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/balloon_drag.pro)
ROUTINE: balloon_drag
PURPOSE: compute drag on shere
USEAGE: result=balloon_drag(r,rho,v,cd)
KEYWORD INPUT:
r balloon radius in meters (default=1.0 m)
v wind velocity (mph) (default=5 m/s)
rho air density (default=1.29 kg/m3)
cd drag coefficient (default=0.2)
NOTE: 1 m/s = 3.60 km/hr = 2.23 mph = 1.94 knots
OUTPUT:
result drag force in newtons
SOURCE: Steve Robinson
NASA/MIT
stever@space.mit.edu
Drag on sphere = .5 * Cd * rho * v^2 * pi * r^2
Cd = function of sphere Reynolds number
(V*2*r)/(kinematic viscosity),
but 0.2 should be close.
EXAMPLE:
r=1. & v=10. & cd=.2
rho=rhoz(p0=1013.,t0=273.,z=1.,lr=7.)
print,balloon_drag(r,rho,v,cd)
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/balloon_drag.pro)
ROUTINE: balloon_lift
PURPOSE: compute and print lifting capacity of a helium balloon in kg
USEAGE: balloon_lift,r=r,volume=volume,alt=alt,pres=pres,temp=temp,lr=lr
KEYWORD INPUT:
r balloon radius in meters (default=1.0 m)
volume ignor r and use this value for volume (default=4.18 m3)
alt altitude in km (default=1 km)
pres pressure in mb (default=1013 mb)
temp surface temperature in K (default=273 K)
brho balloon mass density (kg/m2) (default=0.35 kg/m2)
bwt balloon weight (kg) (default=10 kg)
trho tether mass density (kg/km) (default=6.25 kg/km, dacron)
kevlar if set use kevlar tether at 2.1kg/kg
rubberized polyvinyl 0.35 kg/m2
for dacron, 2.4 mm diam, trho=6.25kg/km, 260 lb pull
for kevlar, 1.5 mm diam, trho=2.1kg/km, 750 lb pull
english if set all the above inputs are
in units of feet or pounds (pounds/sq in for pressure)
EXAMPLE: lifting capacity of a 1 m radius helium balloon at an
altitude of 1 km.
rho=rhoz(p0=1013.,t0=273.,z=1.,lr=7.)
print,balloon_lift(1.,rho)
EXAMPLE: lifting capacity of a non-stretching 1 m radius helium
balloon at an altitude of 1 km. To prevent the balloon
from bursting at high altitude the balloon should not be
filled to full capacity with helium at sealevel. Assume
the helium retains its sealevel temperature (maybe less
than ambient).
balloon_lift,r=1,alt=1
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/balloon_lift.pro)
ROUTINE: balloon_lift
PURPOSE: compute lifting capacity of a helium balloon
USEAGE: result=balloon_lift(r,rho,kg=kg)
KEYWORD INPUT:
r balloon radius in meters (default=1.0 m)
rho air density at operating alitude (defualt=1.29 kg/m3)
result lifting capacity in newtons
(if kg is set lifting capacity is in kg)
EXAMPLE: lifting capacity of a 1 m radius helium balloon at an
altitude of 1 km.
rho=rhoz(p0=1013.,t0=273.,z=1.,lr=7.)
print,balloon_lift(1.,rho)
EXAMPLE: lifting capacity of a non-stretching 1 m radius helium
balloon at an altitude of 1 km. To prevent the balloon
from bursting at high altitude the balloon should not be
filled to full capacity with helium at sealevel. Assume
the helium retains its sealevel temperature (maybe less
than ambient).
r=1
t0 = 273.
p0 = 1013.
rho1 = rhoz(p0 = p0,t0 = t0,z = 1,lr = 7.)
rho0 = rhoz(p0 = p0,t0 = t0,z = 0,lr = 7.)
p1 = p0*(rho1/rho0)*(t0-7.)/t0
rs=r*(p1/p0)^.3333
print,balloon_lift(rs,rho1)
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/balloon_lift.pro)
NAME: BAND_ANALYSE PROJECT: SECIS 99 PURPOSE: To produce average scale, scale-averaged wavelet power spectrum, and scale-averaged theoretical spectrum, as described by Torrence & Compo (1998). INPUTS: TIME - vector of time indices = SX POWER - 2-D array of scale power, versus scale and time containing power *IN A BAND* -- take the OUTPOWER output of EXTRACT_POWER_ROI SCALE - the vector of scales produced by WAVELET from the initial time series KEYWORDS: CONTAINED - the flag array containing the linear indices of all pixels deemed to be inside the contours drawn with EXTRACT_POWER_ROI OUTPUTS: average scale as a function of time scale-averaged wavelet power spectrum scale-averaged theoretical spectrum (optional) HISTORY: version 0.9: DRW @ MSSL (31/03/03) version 1.0: DRW - added a weighting to the average scale (31/03/03) TO DO: Interpolate with DSPLINE to get the exact power at SCALE_AVERAGE
(See /home/drw/idl/secis/band_analyse.pro)
ROUTINE: barplot
PURPOSE: produce a bar plot
USEAGE: barplot
INPUT:
y bar values fltarr(n)
KEYWORD INPUT:
nbar number of barplot overlays. Should only be set on the first
call to BARPLOT
over if set, overplot new bar values.
dx width of a bar (default=1). An individual bar is sized to
fill a fraction .5*DX/nn of the total plot width, where nn
is the number of elements in y. Setting DX=2 eliminates
blank space between adjacent bars.
xinc How far to move overplot bars to the left or right of the
previous bar position (in units of the bar width). Use
with NBAR and XOFF to control degree to which overplot
bars overlap previous bars. A positive value causes latter
overplots to overlap bars starting from the left and
finishing on the right. A negative value does the
opposite. (default = 0.6666)
xoff offset of bar with respect to labeled points on x-axis
(default=0). XOFF should be in the argument list and assigned
to a named variable if NBAR, DX and XINC are used to control
bar overlap in multiplots.
The xaxis labels are located at data coordinates
xlab=findgen(nn)+.5, where nn =n_elements(y)
color color index used to fill bars
xtitle string, x title of plot
ytitle string, y title of plot
title string, title of plot
xlabels vector of strings used to label bar groups
xlabvec vector of x values at which to put XLABELS.
if XLABVEC is not set, XLABELS are ploted at points
.5+findgen(n_elements(xlabels))
range of XLABVEC 0-1
grid if set, draw a y axis grid. The numerical value of grid
is used to set the grid style (1=dotted line)
yrange a two element vector specifying the y axis range
ynozero if set, y range may not include zero if all y values are
are positive.
xmargin two element vector specifies left and right margin around plot
frame in units of character width. (default = !x.margin)
ymargin two element vector specifies bottom and top margin around plot
frame in units of character height. (default = !y.margin)
OUTPUT:
DISCUSSION:
For best results try to arrange the order of overplots so that larger
values of y are ploted first. See examples.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
loadct,5
y=randomu(iseed,6)
color=[.8,.6,.3]*!d.n_colors
dx=.6
barplot,y,dx=dx,xlabels=1990+indgen(6),title='test',xtitle='Year',$
ytitle='power (Watts)',color=color(0),/grid,xoff=xoff,nbar=3
barplot,y^2,dx=dx,color=color(1),/over,xoff=xoff
barplot,y^3,dx=dx,color=color(2),/over,xoff=xoff
; A fancier example
y=randomu(iseed,5) & y=y(sort(y))
xlabels=['January','February','March','April','May']
color=[.2,.4,.6,.8]*!d.n_colors
dx=.32
barplot,y,dx=dx,xtitle='---- Month ----',$
ytitle='power (Watts)',color=color(3),yrange=[0,1.],ymargin=[5,7],$
/grid,xlabels=xlabels,charsize=1.5 ,xoff=xoff,nbar=4
barplot,y^2,dx=dx,color=color(2),/over, xoff=xoff
barplot,y^3,dx=dx,color=color(1),/over, xoff=xoff
barplot,y^4,dx=dx,color=color(0),/over, xoff=xoff
x_axis,findgen(5)+.5,1.,xtickn=(y+y^2+y^3+y^4)/4,yspace=-1.5,$
xtitle='----- Cumulative Average -----'
x_axis,findgen(5)+.5,[1,4],xtitle='Plot Title',yspace=-.5,charsize=1.2,/ext
legend,'.cSensor\\AVHRR 1\AVHRR 2\GTR-200\PSP',color=color,$
/clrbox,bg=0,/box,pos=[0.06,0.57,0.23,0.98]
; use with histogram to make nicer histogram plots
y=randomn(iseed,2000)
yy=histogram(y,binsize=.5,min=-3)
yy=yy(0:11)
xlabel=string(f='(f3.0)',findrng(-3,3,12))
;plot,findrng(-3,3,12),yy,/xsty,psym=10 ; compare to this
barplot,yy,dx=2,color=20,xlabel=['-3','-2','-1','0','1','2','3']
AUTHOR: Paul Ricchiazzi 31 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/barplot.pro)
ROUTINE: barplot
PURPOSE: produce a bar plot
USEAGE: barplot
INPUT:
y bar values
KEYWORD INPUT:
over if set, overplot new bar values
color color index used to fill bars
dx width of a bar (default=1). An individual bar is sized to
fill a fraction .5*DX/nn of the total plot width, where nn
is the number of elements in y. Setting DX=2 eliminates
blank space between adjacent bars.
xoff offset of bar with respect to labeled points on x-axis
(default=0). XOFF should be in the range +/- 1. Use this
parameter to offset bars in overplots. IF the difference in
XOFF between two calls lt DX/2, the overlayed bars will
partially cover previously ploted bars.
The xaxis labels are located at data coordinates
xlab=findgen(nn)+.5, where nn =n_elements(y)
xtitle string, x title of plot
ytitle string, y title of plot
title string, title of plot
xlabels vector of strings used to label bar groups
xlabvec vector of x values at which to put XLABELS.
if XLABVEC is not set, XLABELS are ploted at points
.5+findgen(n_elements(xlabels))/n_elements(xlabels)
range of XLABVEC 0-1
grid if set, draw a y axis grid. The numerical value of grid
is used to set the grid style (1=dotted line)
yrange a two element vector specifying the y axis range
ynozero if set, y range may not include zero if all y values are
are positive.
xmargin two element vector specifies left and right margin around plot
frame in units of character width. (default = !x.margin)
ymargin two element vector specifies bottom and top margin around plot
frame in units of character height. (default = !y.margin)
OUTPUT:
DISCUSSION:
For best results try to arrange the order of overplots so that larger
values of y are ploted first. See examples.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
loadct,5
y=randomu(iseed,6)
color=[.8,.6,.3]*!d.n_colors
dx=.6
xoff=.1
barplot,y,dx=dx,xlabels=1990+indgen(6),title='test',xtitle='Year',$
ytitle='power (Watts)',color=color(0),/grid,xoff=xoff ; right offset
barplot,y^2,dx=dx,color=color(1),/over ; no offset
barplot,y^3,dx=dx,color=color(2),/over,xoff=-xoff ; left offset
; A fancier example
y=randomu(iseed,5) & y=y(sort(y))
xlabels=['January','February','March','April','May']
color=[.2,.4,.6,.8]*!d.n_colors
xoff=.24
dx=.32
barplot,y,dx=dx,xtitle='---- Month ----',$
ytitle='power (Watts)',color=color(3),yrange=[0,1.],ymargin=[5,7],$
/grid,xlabels=xlabels,charsize=1.5 ,xoff=xoff
barplot,y^2,dx=dx,color=color(2),/over, xoff=xoff/3
barplot,y^3,dx=dx,color=color(1),/over, xoff=-xoff/3
barplot,y^4,dx=dx,color=color(0),/over, xoff=-xoff
x_axis,findgen(5)+.5,1.,xtickn=(y+y^2+y^3+y^4)/4,yspace=-1.5,$
xtitle='----- Cumulative Average -----'
x_axis,findgen(5)+.5,[1,4],xtitle='Plot Title',yspace=-.5,charsize=1.2,/ext
legend,'.cSensor\\AVHRR 1\AVHRR 2\GTR-200\PSP',color=color,$
/clrbox,bg=0,/box,pos=[0.06,0.57,0.23,0.98]
; use with histogram to make nicer histogram plots
y=randomn(iseed,2000)
yy=histogram(y,binsize=.5,min=-3)
yy=yy(0:11)
xlabel=string(f='(f3.0)',findrng(-3,3,12))
;plot,findrng(-3,3,12),yy,/xsty,psym=10 ; compare to this
barplot,yy,dx=2,color=20,xlabel=['-3','-2','-1','0','1','2','3']
AUTHOR: Paul Ricchiazzi 31 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/barplot.pro)
NAME:
bc
PURPOSE:
wall to wall cross hairs to help read numbers off of plot
axis. The graphics function is set to 6 for eXclusive OR.
This allows the cross hairs to be drawn and erased without
disturbing the contents of the window. While bc is active
pressing the mouse buttons cause the following actions:
LMB: print the current (x,y) cursor location to the terminal
MMB: same as for LMB, but also indicate selected point on plot
RMB: quit
CALLING SEQUENCE:
bc
INPUTS/OUTPUTS: none
RESTRICTIONS:
Works only with window system drivers.
CATEGORY:
Interactive graphics.
author Paul Ricchiazzi April, 1993
(See /home/drw/idl/esrg/bc.pro)
NAME:
bc
PURPOSE:
wall to wall cross hairs to help read numbers off of plot
axis. The graphics function is set to 6 for eXclusive OR.
This allows the cross hairs to be drawn and erased without
disturbing the contents of the window. Hit RMB to exit
CALLING SEQUENCE:
bc
INPUTS/OUTPUTS: none
RESTRICTIONS:
Works only with window system drivers.
CATEGORY:
Interactive graphics.
author Paul Ricchiazzi April, 1993
(See /home/drw/idl/old.esrg/bc.pro)
Backup to the previous frame.
USAGE: BF
OPTIONAL KEYWORDS:
/QUIET Do not print any information (default=print)
/HELP Print help information only (default=do not print)
USAGE NOTES:
(1) FSET must have been executed previously to create frame buffers.
AUTHOR: Liam Gumley, CIMSS/SSEC, 15-APR-1996 (liam.gumley@ssec.wisc.edu)
RELATED COMMANDS:
FSET Set up frames in memory
SF Show a frame and print frame information
AF Advance one frame
LF Loop frames
EXAMPLE:
; Create two graphics frames, and display an image in each
FSET,FRAMES=2
SF,1
MAP_SET,/MERC,/CONT & WAIT,2.0
BF
MAP_SET,/ORTH,/CONT & WAIT,2.0
BF
(See /home/drw/idl/aux/bf.pro)
ROUTINE:
BOXONMAP, derived from IDL User Library Procedure BOX_CURSOR
PURPOSE:
Emulate the operation of a variable-sized box cursor (also known as
a "marquee" selector).
CATEGORY:
Interactive graphics.
CALLING SEQUENCE:
BOXONMAP, wx0, wy0, wx1, wy1 [, INIT = init] [, FIXED_SIZE = fixed_size]
INPUTS:
No required input parameters.
OPTIONAL INPUT PARAMETERS:
wx0, wy0, wx1, and wy1 give the initial location of the lower left
(wx0, wy0) and upper right (wnx, wny) corners of the box if the
keyword INIT is set. Otherwise, the box is initially drawn in the
center of the screen. Both input and output parameters are in
Longitude (X) and Latitude (Y).
KEYWORD PARAMETERS:
INIT: If this keyword is set, wx0, wy0, wx1, and wy1 contain the
initial parameters for the box.
FIXED_SIZE: If this keyword is set, the initial parameters fix the
size of the box. This size may not be changed by the user.
MESSAGE: If this keyword is set, print a short message describing
operation of the cursor.
OUTPUTS:
wx0: X value (Lon) of lower left corner of box.
wy0: Y value (Lat) of lower left corner of box.
wx1: X value (Lon) of upper right corner of box.
wy1: Y value (Lat) of upper right corner of box.
The box is also constrained to lie entirely within the window.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A box is drawn in the currently active window. It is erased
on exit.
A window for display of numeric latitude and longitude is created.
It is destroyed on exit.
RESTRICTIONS:
Works only with window system drivers.
PROCEDURE:
The graphics function is set to 6 for eXclusive OR. This
allows the box to be drawn and erased without disturbing the
contents of the window.
Operation is as follows:
Left mouse button: Move the box by dragging.
Middle mouse button: Resize the box by dragging. The corner
nearest the initial mouse position is moved.
Right mouse button: Exit this procedure, returning the
current box parameters.
MODIFICATION HISTORY:
DMS, April, 1990.
DMS, April, 1992. Made dragging more intutitive.
NFH, March, 1993, Warp box & use map coordinates,
display Lat & Lon in text box.
PJR/ESRG, March, 1994, display lat & lon in xmessage window
(See /home/drw/idl/esrg/boxonmap.pro)
ROUTINE:
BOXONMAP, derived from IDL User Library Procedure BOX_CURSOR
PURPOSE:
Emulate the operation of a variable-sized box cursor (also known as
a "marquee" selector).
CATEGORY:
Interactive graphics.
CALLING SEQUENCE:
BOXONMAP, wx0, wy0, wx1, wy1 [, INIT = init] [, FIXED_SIZE = fixed_size]
INPUTS:
No required input parameters.
OPTIONAL INPUT PARAMETERS:
wx0, wy0, wx1, and wy1 give the initial location of the lower left
(wx0, wy0) and upper right (wnx, wny) corners of the box if the
keyword INIT is set. Otherwise, the box is initially drawn in the
center of the screen. Both input and output parameters are in
Longitude (X) and Latitude (Y).
KEYWORD PARAMETERS:
INIT: If this keyword is set, wx0, wy0, wx1, and wy1 contain the
initial parameters for the box.
FIXED_SIZE: If this keyword is set, the initial parameters fix the
size of the box. This size may not be changed by the user.
MESSAGE: If this keyword is set, print a short message describing
operation of the cursor.
OUTPUTS:
wx0: X value (Lon) of lower left corner of box.
wy0: Y value (Lat) of lower left corner of box.
wx1: X value (Lon) of upper right corner of box.
wy1: Y value (Lat) of upper right corner of box.
The box is also constrained to lie entirely within the window.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A box is drawn in the currently active window. It is erased
on exit.
A window for display of numeric latitude and longitude is created.
It is destroyed on exit.
RESTRICTIONS:
Works only with window system drivers.
PROCEDURE:
The graphics function is set to 6 for eXclusive OR. This
allows the box to be drawn and erased without disturbing the
contents of the window.
Operation is as follows:
Left mouse button: Move the box by dragging.
Middle mouse button: Resize the box by dragging. The corner
nearest the initial mouse position is moved.
Right mouse button: Exit this procedure, returning the
current box parameters.
MODIFICATION HISTORY:
DMS, April, 1990.
DMS, April, 1992. Made dragging more intutitive.
NFH, March, 1993, Warp box & use map coordinates,
display Lat & Lon in text box.
PJR/ESRG, March, 1994, display lat & lon in xmessage window
(See /home/drw/idl/old.esrg/boxonmap.pro)
ROUTINE: boxpos
USEAGE:
result=boxpos()
result=boxpos(aspect=aspect,rmarg=rmarg,xpos=xpos,ypos=ypos,$
get=get,curbox=curbox,print=print)
PURPOSE: returns the 4 element position of a properly shaped data window.
output is in normalized coordinates
INPUT:
none required
keyword input:
aspect x/y aspect ratio of map (default = 1)
rmarg the amount of margin to leave on the right side of the
box. The margin is specified in units of 10 character
widths, so merely setting the RMARG parameter provides
enough space for COLOR_KEY
get if set, retrieve the position information of the last
plot drawn.
xpos two element vector specifying x position of a multi frame
plot, the first element specifies the frame number, the
second element specifies the number of frames
ypos two element vector specifying y position of a multi frame
plot, the first element specifies the frame number, the
second element specifies the number of frames
print if set, print out the normal coordinates of the box
edges in format,
pos=[x0,y0,x1,y1]
where (x0,y0) and (x1,y1) are the normal coordiates
of the lower left and upper right corners of the box
The default value of PRINT is 1 if the CURSOR keyword
is set.
OUTPUT:
result=[x1,y1,x2,y2],
where (x1,y1) and (x2,y2) are the lower left hand
and upper right hand corner of the new data window
in normalized coordinates.
EXAMPLE: Draw a map over a TVIM image
tvim,dist(200)
map_set,0,0,/orth,/cont,/grid,pos=boxpos(/get),/noerase
Draw a map of the southern hemisphere with 2:1 aspect
ratio
map_set,-90,0,/orth,/cont,/grid,pos=boxpos(aspect=2)
now try a 1:1 aspect ratio
map_set,-90,0,/orth,/cont,/grid,pos=boxpos(/aspect)
now allow room for color key, and draw color key
map_set,-90,0,/orth,/cont,/grid,pos=boxpos(/aspect,/rmarg)
color_key
Draw a multframe plot
x=findgen(100)
plot,x,x,pos=boxpos(aspect=1,ypos=[3,3])
plot,x,x^2,pos=boxpos(aspect=1,ypos=[2,3]),/noerase
plot,x,x^3,pos=boxpos(aspect=1,ypos=[1,3]),/noerase
; NOTE: the XMULTI and YMULTI proceedures (in this directory) can
; also be used to make multiframe plots and are more flexible
; than BOXPOS for positioning the individual frames.
author: Paul Ricchiazzi 25jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/boxpos.pro)
ROUTINE: boxpos
USEAGE:
result=boxpos()
result=boxpos(aspect=aspect,rmarg=rmarg,xpos=xpos,ypos=ypos,$
get=get,curbox=curbox,print=print)
PURPOSE: returns the 4 element position of a properly shaped data window.
output is in normalized coordinates
INPUT:
none required
keyword input:
aspect x/y aspect ratio of map (default = 1)
rmarg the amount of margin to leave on the right side of the
box. The margin is specified in units of 10 character
widths, so merely setting the RMARG parameter provides
enough space for COLOR_KEY
get if set, retrieve the position information of the last
plot drawn.
xpos two element vector specifying x position of a multi frame
plot, the first element specifies the frame number, the
second element specifies the number of frames
ypos two element vector specifying y position of a multi frame
plot, the first element specifies the frame number, the
second element specifies the number of frames
print if set, print out the normal coordinates of the box
edges in format,
pos=[x0,y0,x1,y1]
where (x0,y0) and (x1,y1) are the normal coordiates
of the lower left and upper right corners of the box
The default value of PRINT is 1 if the CURSOR keyword
is set.
OUTPUT:
result=[x1,y1,x2,y2],
where (x1,y1) and (x2,y2) are the lower left hand
and upper right hand corner of the new data window
in normalized coordinates.
EXAMPLE: Draw a map over a TVIM image
tvim,dist(200)
map_set,0,0,/orth,/cont,/grid,pos=boxpos(/get),/noerase
Draw a map of the southern hemisphere with 2:1 aspect
ratio
map_set,-90,0,/orth,/cont,/grid,pos=boxpos(aspect=2)
now try a 1:1 aspect ratio
map_set,-90,0,/orth,/cont,/grid,pos=boxpos(/aspect)
now allow room for color key, and draw color key
map_set,-90,0,/orth,/cont,/grid,pos=boxpos(/aspect,/rmarg)
color_key
Draw a multframe plot
x=findgen(100)
plot,x,x,pos=boxpos(aspect=1,ypos=[3,3])
plot,x,x^2,pos=boxpos(aspect=1,ypos=[2,3]),/noerase
plot,x,x^3,pos=boxpos(aspect=1,ypos=[1,3]),/noerase
; NOTE: the XMULTI and YMULTI proceedures (in this directory) can
; also be used to make multiframe plots and are more flexible
; than BOXPOS for positioning the individual frames.
author: Paul Ricchiazzi 25jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/boxpos.pro)
NAME:
BRD_LIMB
PURPOSE:
Computation of the coordinates and radius of the lunar disk
EXPLANATION:
Computes the coordinates and radius of the lunar disk by last-squere fitting
of the visible lunar limb with the circle
CALLING SEQUENCE:
brd_limb [, XNAME=XNAME, YNAME=YNAME, RNAME=RNAME, CHINAME=CHINAME, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
XMOON=XMOON, YMOON=YMOON, RMOON=RMOON, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3 ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
XNAME = name of the output file with x-coord. of the lunar disk [def.'x_broad_step1.dat']
YNAME = name of the output file with y-coord. of the lunar disk [def.'y_broad_step1.dat']
RNAME = name of the output file with radiuses of the lunar disk [def.'r_broad_step1.dat']
CHINAME= name of the output file with chi2 of the fitting [def.'chi_broad_step1.dat']
DARKNAME=name of the fits-file with mean dark image [def.'db1.fit']
FLATNAME=name of the fits-file with mean flat image [def.'fb1.fit']
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
BEGNAME= the common part of the fits-files names of the processed images [def. 'e01b']
EXTNAME= the extension of the fits-files names of the processed images [def. '.fit']
XMOON = x-coord. of the lunar center at the first processed image
YMOON = y-coord. of the lunar center at the first processed image
RMOON = radius of the lunar disk at the first processed image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
OUTPUTS:
Four files:
File XNAME with x-coordinates of the lunar center at each image and its formal error
File YNAME with y-coordinates of the lunar center at each image and its formal error
File RNAME with radiuses of the lunar disk at each image and its formal error
File CHINAME with chi2 of the last-squere approximation of the limb with the circle
EXAMPLE
brd_limb, path1='c:\secis_2001_broad_1\', path2='c:\secis_2001_broad_2\'
(it means that images -3999 are in directory PATH1, images 4000- in directory PATH2)
PROCEDURE:
Loop over all images
MODIFICATION HISTORY:
Written, January 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/pawel/Moon_position_brd_cam_step1_YH.pro)
NAME:
BRD_LIMB
PURPOSE:
Computation of the coordinates and radius of the lunar disk
EXPLANATION:
Computes the coordinates and radius of the lunar disk by last-squere fitting
of the visible lunar limb with the circle
CALLING SEQUENCE:
brd_limb [, XNAME=XNAME, YNAME=YNAME, RNAME=RNAME, CHINAME=CHINAME, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
XMOON=XMOON, YMOON=YMOON, RMOON=RMOON, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3 ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
XNAME = name of the output file with x-coord. of the lunar disk [def.'x_broad_step1.dat']
YNAME = name of the output file with y-coord. of the lunar disk [def.'y_broad_step1.dat']
RNAME = name of the output file with radiuses of the lunar disk [def.'r_broad_step1.dat']
CHINAME= name of the output file with chi2 of the fitting [def.'chi_broad_step1.dat']
DARKNAME=name of the fits-file with mean dark image [def.'db1.fit']
FLATNAME=name of the fits-file with mean flat image [def.'fb1.fit']
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
BEGNAME= the common part of the fits-files names of the processed images [def. 'e01b']
EXTNAME= the extension of the fits-files names of the processed images [def. '.fit']
XMOON = x-coord. of the lunar center at the first processed image
YMOON = y-coord. of the lunar center at the first processed image
RMOON = radius of the lunar disk at the first processed image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
OUTPUTS:
Four files:
File XNAME with x-coordinates of the lunar center at each image and its formal error
File YNAME with y-coordinates of the lunar center at each image and its formal error
File RNAME with radiuses of the lunar disk at each image and its formal error
File CHINAME with chi2 of the last-squere approximation of the limb with the circle
EXAMPLE
brd_limb, path1='c:\secis_2001_broad_1\', path2='c:\secis_2001_broad_2\'
(it means that images -3999 are in directory PATH1, images 4000- in directory PATH2)
PROCEDURE:
Loop over all images
MODIFICATION HISTORY:
Written, January 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/secis2/Moon_position_brd_cam_step1_YH.pro)
NAME:
BRD_LIMB
PURPOSE:
Computation of the coordinates and radius of the lunar disk
EXPLANATION:
Computes the coordinates and radius of the lunar disk by last-squere fitting
of the visible lunar limb with the circle
CALLING SEQUENCE:
brd_limb [, XNAME=XNAME, YNAME=YNAME, RNAME=RNAME, CHINAME=CHINAME, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
XMOON=XMOON, YMOON=YMOON, RMOON=RMOON, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3 ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
XNAME = name of the output file with x-coord. of the lunar disk [def.'x_broad_step1.dat']
YNAME = name of the output file with y-coord. of the lunar disk [def.'y_broad_step1.dat']
RNAME = name of the output file with radiuses of the lunar disk [def.'r_broad_step1.dat']
CHINAME= name of the output file with chi2 of the fitting [def.'chi_broad_step1.dat']
DARKNAME=name of the fits-file with mean dark image [def.'db1.fit']
FLATNAME=name of the fits-file with mean flat image [def.'fb1.fit']
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
BEGNAME= the common part of the fits-files names of the processed images [def. 'e01b']
EXTNAME= the extension of the fits-files names of the processed images [def. '.fit']
XMOON = x-coord. of the lunar center at the first processed image
YMOON = y-coord. of the lunar center at the first processed image
RMOON = radius of the lunar disk at the first processed image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
OUTPUTS:
Four files:
File XNAME with x-coordinates of the lunar center at each image and its formal error
File YNAME with y-coordinates of the lunar center at each image and its formal error
File RNAME with radiuses of the lunar disk at each image and its formal error
File CHINAME with chi2 of the last-squere approximation of the limb with the circle
EXAMPLE
brd_limb, path1='c:\secis_2001_broad_1\', path2='c:\secis_2001_broad_2\'
(it means that images -3999 are in directory PATH1, images 4000- in directory PATH2)
PROCEDURE:
Loop over all images
MODIFICATION HISTORY:
Written, January 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/secis2/Moon_position_brd_cam_step1_YH_0.pro)
NAME:
BRD_LIMB_RFIX
PURPOSE:
Computation of the coordinates of the lunar disk using constant value of the lunar radius
EXPLANATION:
Computes the coordinates of the lunar disk by last-squere fitting
of the visible lunar limb with the circle of the given radius
CALLING SEQUENCE:
brd_limb_rfix, [ , XNAME=XNAME, YNAME=YNAME, CHINAME=CHINAME, RMOON=RMOON, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
XMOON=XMOON, YMOON=YMOON, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3 ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
XNAME = name of the output file with x-coord. of the lunar disk [def.'x_broad_step2_rfix.dat']
YNAME = name of the output file with y-coord. of the lunar disk [def.'y_broad_step2_rfix.dat']
CHINAME= name of the output file with chi2 of the fitting [def.'chi_broad_step2_rfix.dat']
DARKNAME=name of the fits-file with mean dark image [def.'db1.fit']
FLATNAME=name of the fits-file with mean flat image [def.'fb1.fit']
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
BEGNAME= the common part of the fits-files names of the processed images [def. 'e01b']
EXTNAME= the extension of the fits-files names of the processed images [def. '.fit']
XMOON = x-coord. of the lunar center at the first processed image
YMOON = y-coord. of the lunar center at the first processed image
RMOON = radius of the lunar disk
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
OUTPUTS:
Three files:
File XNAME with x-coordinates of the lunar center at each image and its formal error
File YNAME with y-coordinates of the lunar center at each image and its formal error
File CHINAME with chi2 of the last-squere approximation of the limb with the circle
EXAMPLE
brd_limb, path1='c:\secis_2001_broad_1\', path2='c:\secis_2001_broad_2\'
(it means that images -3999 are in directory PATH1, images 4000- in directory PATH2)
PROCEDURE:
Loop over all images
MODIFICATION HISTORY:
Written, January 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/pawel/Moon_position_brd_cam_step2_rfix_YH.pro)
NAME:
BRD_LIMB_RFIX
PURPOSE:
Computation of the coordinates of the lunar disk using constant value of the lunar radius
EXPLANATION:
Computes the coordinates of the lunar disk by last-squere fitting
of the visible lunar limb with the circle of the given radius
CALLING SEQUENCE:
brd_limb_rfix, [ , XNAME=XNAME, YNAME=YNAME, CHINAME=CHINAME, RMOON=RMOON, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
XMOON=XMOON, YMOON=YMOON, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3 ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
XNAME = name of the output file with x-coord. of the lunar disk [def.'x_broad_step2_rfix.dat']
YNAME = name of the output file with y-coord. of the lunar disk [def.'y_broad_step2_rfix.dat']
CHINAME= name of the output file with chi2 of the fitting [def.'chi_broad_step2_rfix.dat']
DARKNAME=name of the fits-file with mean dark image [def.'db1.fit']
FLATNAME=name of the fits-file with mean flat image [def.'fb1.fit']
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
BEGNAME= the common part of the fits-files names of the processed images [def. 'e01b']
EXTNAME= the extension of the fits-files names of the processed images [def. '.fit']
XMOON = x-coord. of the lunar center at the first processed image
YMOON = y-coord. of the lunar center at the first processed image
RMOON = radius of the lunar disk
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
OUTPUTS:
Three files:
File XNAME with x-coordinates of the lunar center at each image and its formal error
File YNAME with y-coordinates of the lunar center at each image and its formal error
File CHINAME with chi2 of the last-squere approximation of the limb with the circle
EXAMPLE
brd_limb, path1='c:\secis_2001_broad_1\', path2='c:\secis_2001_broad_2\'
(it means that images -3999 are in directory PATH1, images 4000- in directory PATH2)
PROCEDURE:
Loop over all images
MODIFICATION HISTORY:
Written, January 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/secis2/Moon_position_brd_cam_step2_rfix_YH.pro)
NAME:
BRD_LIMB_RFIX
PURPOSE:
Computation of the coordinates of the lunar disk using constant value of the lunar radius
EXPLANATION:
Computes the coordinates of the lunar disk by last-squere fitting
of the visible lunar limb with the circle of the given radius
CALLING SEQUENCE:
brd_limb_rfix, [ , XNAME=XNAME, YNAME=YNAME, CHINAME=CHINAME, RMOON=RMOON, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
XMOON=XMOON, YMOON=YMOON, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3 ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
XNAME = name of the output file with x-coord. of the lunar disk [def.'x_broad_step2_rfix.dat']
YNAME = name of the output file with y-coord. of the lunar disk [def.'y_broad_step2_rfix.dat']
CHINAME= name of the output file with chi2 of the fitting [def.'chi_broad_step2_rfix.dat']
DARKNAME=name of the fits-file with mean dark image [def.'db1.fit']
FLATNAME=name of the fits-file with mean flat image [def.'fb1.fit']
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
BEGNAME= the common part of the fits-files names of the processed images [def. 'e01b']
EXTNAME= the extension of the fits-files names of the processed images [def. '.fit']
XMOON = x-coord. of the lunar center at the first processed image
YMOON = y-coord. of the lunar center at the first processed image
RMOON = radius of the lunar disk
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
OUTPUTS:
Three files:
File XNAME with x-coordinates of the lunar center at each image and its formal error
File YNAME with y-coordinates of the lunar center at each image and its formal error
File CHINAME with chi2 of the last-squere approximation of the limb with the circle
EXAMPLE
brd_limb, path1='c:\secis_2001_broad_1\', path2='c:\secis_2001_broad_2\'
(it means that images -3999 are in directory PATH1, images 4000- in directory PATH2)
PROCEDURE:
Loop over all images
MODIFICATION HISTORY:
Written, January 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/secis2/Moon_position_brd_cam_step2_rfix_YH_0.pro)
NAME: build_vector PURPOSE: This routine accumulates values into a vector CATEGORY: PROG_TOOLS CALLING SEQUENCE: build_vector,vector,value INPUTS: vector : if it's present the vector which will be accumulated to value : the value which will be added to the vector OUTPUTS: vector: A vector holding value EXAMPLE: build_vector,test,5 print,test 5 MODIFICATION HISTORY: Written by: R.Bauer (ICG-1), 1998-Jun-27
(See /home/drw/idl/icglib/pro/build_vector.pro)
reads in the structure containing the calibration information for a single order in a single AXAF grid, and changes the X-data from keV 's into angstroms. Also produces an array 'ANG_BIN_MEAN' which is the mid-point of the bin in angstroms, and and array 'ang_bin_size', which is the size of each bin in angstroms. Finally, it changes the counts array into reverse order, dumping them into a new array called NEW_RESP.
(See /home/drw/idl/axaf/calib_kev2ang.pro)
CALIB_SECIS is meant to calibrate the SECIS2 data in a methodical unified way. while the BIAS is optional, the other keywords are needed. need to prepare the data using the following relation CorrectedImage = [ Exposure - (Bias+DarkCurrent) ] *______________________________________________________________ [ Flat -(Bias+DarkCurrent) ] where <> denotes the mean pixel value. so when you're dividing through by a normalised flat, it's actually only normalised to the AVERAGE intensity, not the maximum.... NAME: CALIB_SECIS PURPOSE: To calibrate a SECIS 2001 image using the method outlined above. USAGE: Result = CALIB_SECIS(image, flatf=flatf, dark=dark, bias=bias) INPUTS: IMAGE - input 2D image which from you want to remove dark current and pixel response (flat field) effects. REQUIRED KEYWORDS: FLATF - a raw flat field image, which may have been averaged with others but from which dark current has not yet been subtracted (this is important!). Must have the same dimensions as IMAGE DARK - a dark current file which, again, mauy have been averaged. Must have same dimensions as IMAGE and FLATF. OPTIONAL KEYWORDS: BIAS - an optional bias file also to be removed. Unlikely to be necessary as the dominant signal in the SECIS 2001 dark current files is the readout noise. OUTPUTS: Result - the calibrated image. CALIB_SECIS is intended to be called as part of a FOR loop, calibrating each image in a cube in turn. CALLS: AVERAGE, from the SSW distro. HISTORY: v1.0 17th September 2001, DRW @ QUB. v1.01 4th October 2001, added QUIET keyword - useful for repetitive operations (DRW). TO DO: 17th September 2001: include removal of jitter inherent in the FOV. (Waiting for PR)
(See /home/drw/idl/secis2/calib_secis.pro)
NAME: call_help PURPOSE: The result of this function is the text below CALLING SEQUENCE from a called routine CATEGORY: CASE_TOOLS CALLING SEQUENCE: result=call_help() EXAMPLE: message,call_help(),/info MODIFICATION HISTORY: Written by R.Bauer (ICG-1), 1999-Nov-06 1999-Nov-06 help added
(See /home/drw/idl/icglib/pro/call_help.pro)
ROUTINE: caption
PURPOSE: CAPTION can be used to print captions above or below a
figures. The character size is determined by the number
of characters per line.
USEAGE: caption,cap,xx,ybot=ybot,yt=ytop,nchar=nchar
INPUT:
cap string used for caption. Normally all text within CAP
is line wrapped to produce a multiline caption. All
white space within CAP is preserved in the caption.
Within CAP the character "\" can be used to force a line
break (i.e., to start a new line). Extra white space
following the "\" causes the text to be indented.
t='this is a test \ junk test test'+$
' \ junk test \ \ junk: this is a test'
caption,t
PRODUCES:
this is a test
junk test test
junk test
junk: this is a test
Note that the backslash character must be surrounded by
whitespace to be recognized
xx normal coordinates of left and right edge of caption
KEYWORD INPUT:
ytop normal coordinates of top of caption
(default=!y.window(0)-.15)
nchar number of characters per line
vspace vertical space factor, controls vertical space between
lines (default = 1)
bg_color background color
color foreground color
exdent number of character positions to indent all lines except
the first. (default=0)
nowrap if set do not line wrap the input text, instead use
embedded backslash characters to control line breaks.
KEYWORD OUTPUT:
ybot normal coordinates of bottom of caption. The value of
of ybot can be used append more text with another call
to CAPTION.
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
t1='CAPTION can be used to print captions above or below a '+$
'figures. The character size is determined by the number '+$
'of characters per line. here is a list of items: \ '+$
' 1. item 1 \ '+$
' 2. item 2 \ '+$
'END OF FIRST CAPTION
t2='BEGINNING OF SECOND CAPTION \ HERE is more text to add to '+$
'the previous text. Note how the '+$
'text starts immediately below the last line of the previous '+$
'written text. The use of ybot allows concatenation of text with '+$
'different right and left margins'
w8x11 & !p.multi=[0,1,2]
plot,dist(10)
caption,t1,nchar=80,ybot=yy
xwid=.5*(!x.window(1)-!x.window(0))
xmid=.5*(!x.window(0)+!x.window(1))
caption,t2,xwid+.5*[-xwid,xwid],nchar=40,ytop=yy
;; FILL option
t= 'HERE is more sample text to demonstrate the use of CAPTION''s, '+$
'"fill" option. Note how the text is stretched to fill the '+$
'entire width of the line. It is probably a good idea not '+$
'to force linebreaks using the backslash symbol while in this '+$
'mode. The "fill" option works best when NCHAR is large'
erase
caption,t,[.1,.9],ytop=.9,/fill,nchar=80
;; CAPTION used with READ_TEXT
caption,read_text('caption.txt','Figure 1.'),nchar=60
AUTHOR: Paul Ricchiazzi 12 Mar 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/caption.pro)
ROUTINE: caption
PURPOSE: CAPTION can be used to print captions above or below a
figures. The character size is determined by the number
of characters per line.
USEAGE: caption,cap,xx,ybot=ybot,yt=ytop,nchar=nchar
INPUT:
cap string used for caption. Normally all text within CAP
is line wrapped to produce a multiline caption. All
white space within CAP is preserved in the caption.
Within CAP the character "\" can be used to force a line
break (i.e., to start a new line). Extra white space
following the "\" causes the text to be indented.
t='this is a test \ junk test test'+$
' \ junk test \ \ junk: this is a test'
caption,t
PRODUCES:
this is a test
junk test test
junk test
junk: this is a test
Note that the backslash character must be surrounded by
whitespace to be recognized
xx normal coordinates of left and right edge of caption
KEYWORD INPUT:
ytop normal coordinates of top of caption
(default=!y.window(0)-.15)
nchar number of characters per line
vspace vertical space factor, controls vertical space between
lines (default = 1)
bg_color background color
color foreground color
exdent number of character positions to indent all lines except
the first. (default=0)
nowrap if set do not line wrap the input text, instead use
embedded backslash characters to control line breaks.
KEYWORD OUTPUT:
ybot normal coordinates of bottom of caption. The value of
of ybot can be used append more text with another call
to CAPTION.
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
t1='CAPTION can be used to print captions above or below a '+$
'figures. The character size is determined by the number '+$
'of characters per line. here is a list of items: \ '+$
' 1. item 1 \ '+$
' 2. item 2 \ '+$
'END OF FIRST CAPTION
t2='BEGINNING OF SECOND CAPTION \ HERE is more text to add to '+$
'the previous text. Note how the '+$
'text starts immediately below the last line of the previous '+$
'written text. The use of ybot allows concatenation of text with '+$
'different right and left margins'
w8x11 & !p.multi=[0,1,2]
plot,dist(10)
caption,t1,nchar=80,ybot=yy
xwid=.5*(!x.window(1)-!x.window(0))
xmid=.5*(!x.window(0)+!x.window(1))
caption,t2,xwid+.5*[-xwid,xwid],nchar=40,ytop=yy
;; FILL option
t= 'HERE is more sample text to demonstrate the use of CAPTION''s, '+$
'"fill" option. Note how the text is stretched to fill the '+$
'entire width of the line. It is probably a good idea not '+$
'to force linebreaks using the backslash symbol while in this '+$
'mode. The "fill" option works best when NCHAR is large'
erase
caption,t,[.1,.9],ytop=.9,/fill,nchar=80
;; CAPTION used with READ_TEXT
caption,read_text('caption.txt','Figure 1.'),nchar=60
AUTHOR: Paul Ricchiazzi 12 Mar 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/caption.pro)
NAME:
CCK_LOADCT
PURPOSE:
Construct a color table for viewing continuous-tone images
in false color.
CALLING SEQUENCE:
CCK_LOADCT, ru, gu, bu [, ncolors=ncolors]
EXAMPLES:
cck_loadct, 0.7, 2.8, 10 ;something like the RED TEMPERATURE table
cck_loadct, -0.7,-2.8,-10;same table, reversed.
cck_loadct, 4, 2, 0.7; blue
cck_loadct, 0.9, 1.1, 4; yellow
cck_loadct, 0.7, 1.2, 4; gold
cck_loadct, 1, 2, 4; bronze
cck_loadct, 0.5,1,2; logarithmic bronze
cck_loadct, 1, 2, 0.5 ;indigo
cck_loadct, 3, 0.9, 1.3 ;bluegrass
cck_loadct, 1, 3, 0.8; ooh, purple!
cck_loadct, 0.7, 3, 1.5; pink
INPUT PARAMETERS:
ru, gu, bu -- contrast indices for red, green, and blue
channels respectively. These are positive floating
point numbers.
METHOD:
User-specified contrast indices specify independent behavior
for the red, green, and blue channels. negative indices are
used to specify a reversed color table for that channel
rather than a negative power law.
OPTIONAL KEYWORD PARAMETERS:
NCOLORS -- number of entries in the color table (default !d.n_colors).
MODIFICATION HISTORY:
2002-Jun-06 Written by Charles Kankelborg, MSU
(See /home/drw/idl/my_tomography3/cck_loadct.pro)
ROUTINE: cdsct PURPOSE: Set up color table for CDS INT_DIST images USEAGE: IDL> cdsct INPUT: OUTPUT: AUTHOR: Peter T. Gallagher, Dec. '97
(See /home/drw/idl/bin/ptg/cdsct.pro)
ROUTINE: cds_spectra1
PURPOSE: to extract spectra from a CDS/NIS raster for
various solar_x and solar_y positions
(re-writing az_sa.pro from scratch so I have
a better understanding of what's going on
at each stage; drw)
USEAGE: cds_spectra1,filename,qlds[,wave,spectrum?]
INPUT:
FILENAME - obvious
QLDS - calibrated CDS data in CDS qlds format
OUTPUT: (we'll see how I get along!)
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(originally AZ_SA.PRO)
(See /home/drw/idl/secis/cdstest.pro)
ROUTINE: cds_proc
PURPOSE: Read, clean, and calib. CDS fits file
USEAGE: cds_proc, Filename, Qlds,(/Sav)
INPUT:
Filename String array containing CDS fits file name
OUTPUT:
Qlds The cleaned, callibrated file
KEYWORDS:
Sav If set the fitts file is read,cleaned, calib and save to
Filename.sav
AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/cds_proc.pro)
ROUTINE: cds_proc
PURPOSE: Read, clean, and calib. CDS fits file
USEAGE: cds_proc, Filename, Qlds,(/Sav)
INPUT:
Filename String array containing CDS fits file name
OUTPUT:
Qlds The cleaned, callibrated file
KEYWORDS:
Sav If set the fitts file is read,cleaned, calib and save to
Filename.sav
AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/ptg/cds_proc.pro)
PROJECT: CDS NAME: CDS_PROC PURPOSE: Generic calibration and display of a CDS window CALLING SEQUENCE: cds_proc, filename, qlds, image=image, windex=windex
(See /home/drw/idl/cds/cdsproc.pro)
ROUTINE: cds_spectra1
PURPOSE: to extract spectra from a CDS/NIS raster for
various solar_x and solar_y positions
(re-writing az_sa.pro from scratch so I have
a better understanding of what's going on
at each stage; drw)
USEAGE: cds_spectra1,filename,qlds[,wave,spectrum?]
INPUT:
FILENAME - obvious
QLDS - calibrated CDS data in CDS qlds format
OUTPUT: (we'll see how I get along!)
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(originally AZ_SA.PRO)
(See /home/drw/idl/secis/cds_spectra1.pro)
Project : SOHO - CDS
Name : CDS_UTPLOT
Purpose : To plot time series data with sensible time axis labelling.
Explanation : Uses the routine DEF_CDS_UTPLOT to manipulate the IDL plotting
variables to set up sensible time axis labels and intervals.
After the setup the data are plotted with a normal call to
the routine PLOT.
Use : IDL> cds_utplot,x,y,timerange=[], /dmy, /log + normal plot keywords.
Inputs : x - the time variable. May be either an array of CDS internal
time structures (as produced by the
routine STR2UTC, say) or...
a string array of date/times in a
format translatable by STR2UTC.
y - the data value to be plotted.
Opt. Inputs : Various keywords.
Outputs : None
Opt. Outputs: None
Keywords : timerange - a 2-element array each element is either a CDS
internal time structure or a CDS date/time string.
Note that this time range is still adjusted
slightly for actual plotting unless the keyword
xstyle=1 is specified.
dmy - if the x-variable is a list of date/time strings
this keyword must be used if they are in the
format dd-mm(m)-yyyy as opposed to the CDS
'official' format of yyyy-mm-dd
log - make plot log-linear
+ other standard plot keywords
Calls : DEF_CDS_UTPLOT
STR2UTC
UTC2SEC
SEC2UTC
VCHECK
Common : cds_utplot_com (for passing of time axis offset to cds_outplot)
Restrictions: The MJD of any dates used must be positive.
Any 2-character year specifications are translated as being
between 1950 and 2049 (use 4-characters as necessary).
The time array passed to CDS_UTPLOT must be in ascending order
of time - sort it if necessary!
Side effects: None
Category : Data display, plotting
Prev. Hist. : This is a severely trimmed version of the old UTPLOT as used on
Yohkoh and developed by Tolbert, Schwartz and Morrison.
I may have trimmed too much, please let me know.
Written : This version for CDS by C D Pike, RAL, 20-Apr-94
Modified : Version 1, C D Pike, RAL, 20-Apr-94
Version 2, William Thompson, GSFC, 14 November 1994
Modified .DAY to .MJD
Version 3, Add /log keyword. CDP, 18-Sep-95
Version 4, Fix bug when specifying <10 days timerange. 7-Dec-95
Version 5, Add xminor keyword. CDP, 25-Mar-96
Version 6, Name change. CDP, 2-Oct-96
Version : Version 6, 2-Oct-96
(See /home/drw/idl/bin/cds_utplot.pro)
NAME:
CENTERTLB
PURPOSE:
This is a utility routine to center a widget program
on the 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:
Utilities
CALLING SEQUENCE:
CenterTLB, tlb
INPUTS:
tlb: The top-level base identifier of the widget program.
PROCEDURE:
The program should be called after all the widgets have
been created, but just before the widget hierarchy is realized.
It uses the top-level base geometry along with the display size
to calculate offsets for the top-level base that will center the
top-level base on the display.
MODIFICATION HISTORY:
Written by: Dick Jackson, 12 Dec 98.
Modified to use device-independent Get_Screen_Size
function. 31 Jan 2000. DWF.
###########################################################################
LICENSE
This software is OSI Certified Open Source Software.
OSI Certified is a certification mark of the Open Source Initiative.
Copyright © 1998-2000 Fanning Software Consulting
This software is provided "as-is", without any express or
implied warranty. In no event will the authors be held liable
for any damages arising from the use of this software.
Permission is granted to anyone to use this software for any
purpose, including commercial applications, and to alter it and
redistribute it freely, subject to the following restrictions:
1. The origin of this software must not be misrepresented; you must
not claim you wrote the original software. If you use this software
in a product, an acknowledgment in the product documentation
would be appreciated, but is not required.
2. Altered source versions must be plainly marked as such, and must
not be misrepresented as being the original software.
3. This notice may not be removed or altered from any source distribution.
For more information on Open Source Software, visit the Open Source
web site: http://www.opensource.org.
###########################################################################
(See /home/drw/idl/aux/centertlb.pro)
NAME:
CENTER_STR_X
PURPOSE:
Calculates the x device coordinate to use when printing a string
centered on the current window.
CATEGORY:
text
CALLING SEQUENCE:
s = CENTER_STR_X(str [,size = size])
INPUTS:
str = the character string to be centered on the current window
KEYWORD PARAMETERS:
size (input) = character size to use when centering the string
(default is 1).
MODIFICATION HISTORY:
written by Pat Guimaraes, STX, Oct. 5, 1991
(See /home/drw/idl/wwbsrc/wplotit.pro)
NAME:
CENTER_STR_X
PURPOSE:
Calculates the y device coordinate to use when printing a string
centered on the current window
CATEGORY:
text
CALLING SEQUENCE:
a = CENTER_STR_Y(str [,size = size])
INPUTS:
str = the character string to be centered on the current window
OPTIONAL INPUT PARAMETERS:
KEYWORD PARAMETERS:
size (input) = character size to use when centering the string
(default is 1).
MODIFICATION HISTORY:
written by Amara Graps 930816
(See /home/drw/idl/wwbsrc/wplotit.pro)
NAME:
CHEBCOEF
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:
Estimate Chebyshev polynomial coefficients of a function on an interval
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
p = CHEBCOEF(FUNC, PRIVATE, FUNCTARGS=functargs, /DOUBLE, /EXPRESSION, $
PRECISION=prec, ERROR=err, NMAX=nmax, INTERVAL=interval, $
REDUCE_ALGORITHM=, STATUS=)
DESCRIPTION:
CHEBCOEF estimates the coefficients for a finite sum of Chebyshev
polynomials approximating the function FUNC(x) over an interval.
The user can choose the desired precision and maximum number of
chebyshev coefficients.
This routine is intended for functions which can be evaluated to
full machine precision at arbitrary abcissae, and which are smooth
enough to ensure that the coefficients are a decreasing sequence.
For already-tabulated or potentially noisy data, the routines
CHEBGRID or CHEBFIT should be used instead.
The function to be approximated may either be the name of an IDL
function (the default behavior), or an IDL expression (using the
/EXPRESSION keyword).
The procedure uses a modified form of the classic algorithm for
determining the coefficients, which relies the orthogonality
relation for Chebyshev polynomials. The interval [a,b] is
subdivided successively into sets of subintervals of length
2^(-k)*(b-a),(k = 0,1,2...). After each subdivision the
orthogonality properties of the Chebyshev polynomials with respect
to summation over equally-spaced points are used to compute two
sets of approximate values of the coefficients cj, one set
computed using the end-points of the subintervals, and one set
using the mid-points. Certain convergence requirements must be
met before terminating. If the routine fails to converge with 64
coefficents, then the current best-fitting coefficients are
returned, along with an error estimate in the ERROR keyword.
CHEBCOEF never returns more than 64 coefficients.
The coefficients may be further refined. If the keyword
REDUCE_ALGORITHM is set to a value of 1, then any high order
coefficients below a certain threshold are discarded. If
REDUCE_ALGORITHM is set to 2 (the default), then all coefficients
below the threshold are discarded rather than just the high order
ones. The threshold is determined by the PRECISION keyword.
INPUTS:
FUNC - a scalar string, the name of the function to be
approximated, or an IDL string containing an expression to
be approximated (if /EXPRESSION is set).
PRIVATE - any optional variable to be passed on to the function to
be integrated. For functions, PRIVATE is passed as the
second positional parameter; for expressions, PRIVATE can
be referenced by the variable 'P'. CHEBCOEF does not
examine or alter PRIVATE.
RETURNS:
An array of Chebyshev coefficients which can be passed to
CHEBEVAL. NOTE: the convention employed here is such that the
constant term in the expansion is P(0)*T0(x) (i.e., the convention
of Luke), and not P(0)/2 * T0(x).
KEYWORD PARAMETERS:
DOUBLE - if set, then computations are done in double precision
rather than single precision.
ERROR - upon return, this keyword contains an estimate of the
maximum absolute error in the approximation.
EXPRESSION - if set, then FUNC is an IDL expression to be
approximated, rather than the name of a function.
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.
INTERVAL - a 2-element vector describing the interval over which
the polynomial is to be evaluated.
Default: [-1, 1]
NMAX - a scalar, the maximum number of coefficients to be
estimated. This number may not exceed 64.
Default: 64
PRECISION - a scalar, the requested precision in the
approximation. Any terms which do not contribute
significantly, as defined by this threshold, are
discarded. If the function to be estimated is not
well-behaved, then the precision is not guaranteed to
reach the desired level. Default: 1E-7
REDUCE_ALGORITHM - a scalar integer, describes how insignificant
terms are removed from the fit. If 0, then all terms
are kept, and none are dicarded. If 1, then only
trailing terms less than PRECISION are discarded. If
2, then both trailing and intermediate terms less than
PRECISION are discarded.
Default: 2
STATUS - upon return, this keyword contains information about the
status of the approximation. A value of -1 indicates bad
input values; a value of 0 indicates the required
accuracy was not obtained; a value of 1 indicates
success.
EXAMPLE:
x = dindgen(1000)/100 ; Range of 0 to 10
p = chebcoef('COS(x)', /expr, interval=[0d, 10d]) ;; Compute coefs
y = chebeval(x, p, interval=[0d,10d]) ;; Eval Cheby poly
plot, x, y - cos(x) ; Plot residuals
REFERENCES:
Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
Functions*, 1965, U.S. Government Printing Office, Washington,
D.C. (Applied Mathematical Series 55)
CERN, 1995, CERN Program Library, Function E406
Luke, Y. L., *The Special Functions and Their Approximations*,
1969, Academic Press, New York
MODIFICATION HISTORY:
Written and documented, CM, June 2001
Copyright license terms changed, CM, 30 Dec 2001
Added usage message, CM, 20 Mar 2002
Changed docs slightly, CM, 25 Mar 2002
$Id: chebcoef.pro,v 1.6 2002/05/03 18:40:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/chebcoef.pro)
NAME:
CHEBEVAL
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:
Evaluate a Chebyshev polynomial on an interval, given the coefficients
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
y = CHEBEVAL(X, P, INTERVAL=interval, DERIVATIVE=deriv)
DESCRIPTION:
CHEBEVAL computes the values of a Chebyshev polynomial function at
specified abcissae, over the interval [a,b]. The user must supply
the abcissae and the polynomial coefficients. The function is of
the form:
N
y(x) = Sum p_n T_n(x*) x in [a,b]
i=0
Where T_n(x*) are the orthogonal Chebyshev polynomials of the
first kind, defined on the interval [-1,1] and p_n are the
coefficients. The scaled variable x* is defined on the [-1,1]
interval such that (x*) = (2*x - a - b)/(b - a), and x is defined
on the [a,b] interval.
The derivative of the function may be computed simultaneously
using the DERIVATIVE keyword.
The is some ambiguity about the definition of the first
coefficient, p_0, namely, the use of p_0 vs. the use of p_0/2.
The p_0 definition of Luke is used in this function.
INPUTS:
X - a numerical scalar or vector, the abcissae at which to
evaluate the polynomial. If INTERVAL is specified, then all
values of X must lie within the interval.
P - a vector, the Chebyshev polynomial coefficients, as returned
by CHEBFIT or CHEBCOEF.
RETURNS:
An array of function values, evaluated at the abcissae. The
numeric precision is the greater of X or P.
KEYWORD PARAMETERS:
DERIVATIVE - upon return, a vector containing the derivative of
the function at each abcissa is returned in this
keyword.
INTERVAL - a 2-element vector describing the interval over which
the polynomial is to be evaluated.
Default: [-1, 1]
EXAMPLE:
x = dindgen(1000)/100 ; Range of 0 to 10
p = chebcoef('COS(x)', /expr, interval=[0d, 10d]) ;; Compute coefs
y = chebeval(x, p, interval=[0d,10d]) ;; Eval Cheby poly
plot, x, y - cos(x) ; Plot residuals
REFERENCES:
Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
Functions*, 1965, U.S. Government Printing Office, Washington,
D.C. (Applied Mathematical Series 55)
CERN, 1995, CERN Program Library, Function E407
Luke, Y. L., *The Special Functions and Their Approximations*,
1969, Academic Press, New York
MODIFICATION HISTORY:
Written and documented, CM, June 2001
Copyright license terms changed, CM, 30 Dec 2001
Added usage message, CM, 20 Mar 2002
$Id: chebeval.pro,v 1.5 2002/03/25 06:42:50 craigm Exp $
(See /home/drw/idl/aux/markwardt/chebeval.pro)
NAME:
CHEBFIT
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 Chebyshev polynomial coefficients to a tabulated function
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
p = CHEBFIT(X, Y, ERR, INTERVAL=interval, NMAX=nmax,
PRECISION=prec, /EVEN, /ODD, REDUCE_ALGORITHM=)
DESCRIPTION:
CHEBFIT fits a series of Chebyshev polynomials to a set of
tabulated and possibly noisy data points. The functions MPFIT and
CHEBEVAL, available from the above web page, must also be in your
IDL path for this function to work properly. The user can choose
the desired precision and maximum number of chebyshev
coefficients.
This function is intended for use on already-tabulated data which
are potentially noisy. The user should never expect more than
NPOINTS terms, where NPOINTS is the number of (x,y) pairs. For
functions which can be evaluated to full machine precision at
arbitrary abcissae, the routine CHEBCOEF should be used instead.
For exact data tabulated on a regular grid, the routine CHEBGRID
should be tried.
The user can also specify that the function is even or odd, using
the keywords EVEN or ODD. This saves computation time because
certain terms in the expansion can be ignored. For the purposes
of this function even and odd refer to the symmetry about the
center of the interval.
The algorithm is employed in three steps. In the first step, the
coefficients are estimated at a crude level. In the second step,
it is determined whether certain coefficients are deemed
"ignoreable", i.e., they do not contribute significantly to the
function and are discarded. The operation of this step is
determined by the REDUCE_ALGORITHM keyword. Finally, the
remaining "good" coefficients are re-fitted to achieve the best
fit.
INPUTS:
X, Y - the x- and y- tabulated values to be fitted.
ERR - (optional) the y-error bar associated with each (x,y) pair.
Default: 1
RETURNS:
An array of Chebyshev coefficients which can be passed to
CHEBEVAL. NOTE: the convention employed here is such that the
constant term in the expansion is P(0)*T0(x) (i.e., the convention
of Luke), and not P(0)/2 * T0(x).
KEYWORD PARAMETERS:
EVEN, ODD - if set, then the fitting routine assumes the function
is even or odd, about the center of the interval.
INTERVAL - a 2-element vector describing the interval over which
the polynomial is to be evaluated.
Default: [-1, 1]
NMAX - a scalar, the maximum number of polynomial terms to be
fitted at one time.
Default: 16
PRECISION - a scalar, the requested precision in the fit. Any
terms which do not contribute significantly, as
defined by this threshold, are discarded. If the
function to be fitted is not well-behaved, then the
precision is not guaranteed to reach the desired
level.
Default: 1E-7
REDUCE_ALGORITHM - a scalar integer, describes how insignificant
terms are removed from the fit. If 0, then all terms
are kept, and none are dicarded. If 1, then only
trailing terms less than PRECISION are discarded. If
2, then both trailing and intermediate terms less than
PRECISION are discarded.
Default: 2
EXAMPLE:
x = dindgen(1000)/100 ; Range of 0 to 10
y = cos(x) + randomn(seed,1000)*0.01 ; Function with some noise
p = chebfit(x, y, interval=[0d,10d])
plot, x, y - chebeval(x,p, interval=[0d,10d])
REFERENCES:
Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
Functions*, 1965, U.S. Government Printing Office, Washington,
D.C. (Applied Mathematical Series 55)
CERN, 1995, CERN Program Library, Function E407
Luke, Y. L., *The Special Functions and Their Approximations*,
1969, Academic Press, New York
MODIFICATION HISTORY:
Written and documented, CM, June 2001
Copyright license terms changed, CM, 30 Dec 2001
Added usage message, CM, 20 Mar 2002
Slight docs change, CM, 25 Mar 2002
$Id: chebfit.pro,v 1.7 2003/07/20 05:53:44 craigm Exp $
(See /home/drw/idl/aux/markwardt/chebfit.pro)
NAME:
CHEBGRID
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:
Estimate Chebyshev polynomial coefficients of a function on a grid
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
p = CHEBGRID(T, X, [ DXDT, NPOINTS=, NPOLY=, NGRANULE= , $
RMS=, DRMS=, RESIDUALS=, DRESIDUALS= , $
XMATRIX=, DXMATRIX=, RESET=,
DERIV_WEIGHT= ] )
DESCRIPTION:
CHEBGRID estimates the coefficients for a finite sum of Chebyshev
polynomials approximating a continuous tabulated function over an
interval. The function (and optionally its derivative) must be
tabulated on a regularly sampled grid. The implementation of this
function is taken from a method described by X. X. Newhall, used
in estimating coefficients for ephemerides in the solar system.
The tabulated function is assumed to be continuous over the entire
interval. A Chebyshev series is fitted to the function over small
segments, called granules. The size of each granule, the number
of points in each granule, and the number of Chebyshev polynomials
are all configurable.
Users may specify either the function alone, or the function and
its first derivative. By also giving the tabulated derivative, a
more accurate Chebyshev polynomial can be developed. Aside from
the constraints mentioned in the next paragraph, the polynomial
that is returned is the best-fit polynomial in a least-squares
sense.
Here is a definition of terms:
GRANULE - a single continuous fitted segment. The length of the
granule, NGRANULE, is specified in units of the tabulated
grid size. Because of the continuity requirements developed
below, granules will always overlap at their endpoints.
Thus, then length of a granule should be a factor of
N_ELEMENTS(X)-1. For simple functions over short intervals,
the granule size can be equal to N_ELEMENTS(X)-1
NUMBER OF POINTS the number of points, NPOINTS, within a
granule to be fitted to the polynomial, not necessarily
equal to the granule size. The greater the number of
points, the more computation time and storage is required.
This number *must* be a factor of NGRANULE. Typically
NPOINTS is a number between 8 and 12. Because of the
single-point overlap between granules (see below), the
actual number of points per fit is NPOINTS+1.
NUMBER OF POLYNOMIALS the number of Chebyshev polynomial terms,
NPOLYNOMIAL, to be fitted per granule. The greater the
number of polynomial terms, the more computation time and
storage is required, but also the greater the approximating
precision of the fit.
The particular set of Chebyshev polynomial coefficients developed
by this function have some special properties. If both the
function and its derivative are specified, then the value and
derivative of the interpolating polynomial at the granule
endpoints will be exactly equal to the tabulated endpoint values.
This feature allows many approximations to be strung together
piecewise, and the function value and first derivative will be
continuous across granule boundaries.
If only the function value is specified, then only the function
value will be continuous at the granule endpoints, and not the
derivative.
An extensive set of statistics are computed to assess the quality
of the Chebyshev polynomial fit. The keywords RESIDUALS and
DRESIDUALS return the residuals of the fit after subtracting the
interpolation. The RMS and DRMS keywords return the root mean
squared deviations between data and model.
If the user does not know how many granules, points, or polynomial
coefficients to use, then he or she should try several
combinations and see which minimizes the r.m.s. value with the
fewest number of coefficients.
If the XMATRIX and DXMATRIX keywords are passed, then CHEBGRID
attempts to avoid recomputing several of the matrices it uses in
estimating the coefficients. If multiple calls to CHEBGRID are to
be made, some compution time savings can be made. In the first
call CHEBGRID the required matrices are computed and returned. In
subsequent calls, CHEBGRID detects the XMATRIX and DXMATRIX
keyword values and uses those values if it can.
The user can also estimate their own coefficients. The matrices
returned are (NPOINTS+1)x(NPOLYNOMIAL). The coefficients from a
NPOINTS+1 tabulation, X, are found by:
PCHEB = XMATRIX ## X + DXMATRIX ## DXDT
if derivative information is known, or
PCHEB = XMATRIX ## X
if no derivative information is known. [ Note: the matrices are
different, depending on whether derivative information is known or
not. ]
INPUTS:
T - array of regularly sampled *independent* variables. The number
of elements in T should be a multiple of NGRANULE, plus one.
X - array of regularly sampled *dependent* variables. The number
of elements in X should be equal to the number of elements in
T.
DXDT - optionally, a tabulated array of first derivatives of X
with respect to T, at the same grid points.
KEYWORD PARAMETERS:
NGRANULE - size of a "granule", in grid intervals. NGRANULE must
be at least 2, and a factor of N_ELEMENTS(T)-1.
Default: 8
NPOINTS - number of points per granule that are fitted. NPOINTS
must be at least 2, and a factor of NGRANULE.
Default: NGRANULE
NPOLYNOMIAL - number of Chebyshev polynomial terms per fit.
NPOLYNOMIAL must be at least 2 and less than
2*(NPOINTS+1), when derivative information is
specified; or less than NPOINTS+1, when no
derivative information is specified.
Default: 7
RESIDUALS - upon return, an array of size N_ELEMENTS(T), with
residuals of the tabulated function minus the
interpolated function.
DRESIDUALS - same as RESIDUALS, but for the function's first
derivative.
RMS - upon return, the root mean square of the function value
residuals.
DRMS - same as RMS, but for the function's first derivative.
XMATRIX - upon return, the matrix used to compute Chebyshev
polynomial coefficients from the function value.
Upon input, CHEBGRID determines if XMATRIX will apply to
the data, and if so, XMATRIX is reused rather than
computed. If XMATRIX cannot be reused, then it is
computed afresh, and the new value is returned in the
XMATRIX keyword.
The user should not modify the contents of this array.
DXMATRIX - same as XMATRIX, but for the function's first
derivative.
RESET - if set, force a recomputation of XMATRIX and/or DXMATRIX.
DERIV_WEIGHT - amount of weight to give to function derivative,
relative to the function value.
Default: 0.16d
RETURNS:
An array of coefficient values. The dimensions of the array are
NPOLYNOMIALxNSEGS, where NSEGS is the number of granules in the
entire interval.
EXAMPLE:
;; Estimate Chebyshev coefficients for the function SIN(X), on the
;; interval [-1,+1].
xx = dindgen(9)/4d - 1d ;; Regular grid from -1 to 1 (9 points)
yy = sin(xx) ;; Function values, sin(x), ...
dy = cos(xx) ;; ... and derivatives
;; Estimate coefficients using CHEBGRID (single granule of 8 intervals)
p = chebgrid(xx, yy, dy, npoints=8, ngranule=8, npoly=10)
xxx = dindgen(1001)/500 - 1d ;; New grid for testing
res = sin(xxx) - chebeval(xxx, p)
plot, xxx, res
;; Same as example above, except extended range to [-1, +15],
using eight granules.
xx2 = dindgen(65)/4d - 1
yy2 = sin(xx2)
dy2 = cos(xx2)
p = chebgrid(xx2, yy2, dy2, ngranule=8, npoint=8, npoly=10)
help, p
P DOUBLE = Array[10, 8]
;; (i.e., 10 polynomial coefficients over 8 granules)
REFERENCES:
Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
Functions*, 1965, U.S. Government Printing Office, Washington,
D.C. (Applied Mathematical Series 55)
Newhall, X. X. 1989, Celestial Mechanics, 45, p. 305-310
MODIFICATION HISTORY:
Written, CM, Feb 2002
Documented, CM, 24 Mar 2002
Corrected documentation, CM, 28 Apr 2002
Typo correction, CM, 10 Oct 2002
$Id: chebgrid.pro,v 1.5 2002/11/07 00:15:23 craigm Exp $
(See /home/drw/idl/aux/markwardt/chebgrid.pro)
NAME:
CHGCOLOR
PURPOSE:
The purpose of this routine is to allow the user to change
the color at a particular color index. The user is able to
mix their own color by manipulating red, green, and blue
sliders. This routine is ideal for changing axes or background
colors of a plot, for example. The routine works on 8-bit,
16-bit, and 24-bit displays.
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, Colors.
CALLING SEQUENCE:
CHGCOLOR, index
REQUIRED INPUTS:
INDEX: The color index to be changed. It must be a value
between 0 and 255.
KEYWORD PARAMETERS:
LABEL: Text that goes next to the color window. The default is
"Resulting Color".
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
NOTIFYID: A a 2 column by n row array that contains the IDs of widgets
that should be notified when CHGCOLOR changes a color. The first
column of the array contains widgets that should be notified. The
second column contains IDs of widgets that are at the top of the
hierarch 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 CHGCOLOR_LOAD event will be
sent to the widget identified in the first column. The event
structure is defined like this:
event = {CHGCOLOR_LOAD, ID:0L, TOP:0L, HANDLER:0L, $
r:(!D.N_COLORS < 256), g:(!D.N_COLORS < 256), b:(!D.N_COLORS < 256)}
The ID field will be filled out with NOTIFYID(0, n) and the TOP
field will be filled out with NOTIFYID(1, n).
TITLE: This is the window title. It is "Modify Drawing Color" by
default. The program is registered with the name "chgcolor " plus
the TITLE string. The register name is checked before the widgets
are defined. This gives you the opportunity to have multiple copies
of CHGCOLOR operating simultaneously. (For example, one will change
the background color and one will change the plotting color.)
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:
Color at the specified index is changed. Events are sent to widgets
if the NOTIFYID keyword is used.
RESTRICTIONS:
None.
EXAMPLE:
To change the background color of a plot, type:
CHGCOLOR, !P.Background
To see a more complete example, look at the program SLICE
in the Coyote Software Library:
ftp://ftp.frii.com/pub/dfanning/outgoing/idl_examples
MODIFICATION HISTORY:
Written by David Fanning, 23 April 97.
12 May 97, Fixed a bug in the way colors were loaded when
a tracking event occurred. DWF
13 May 97, Added a JUST_REGISTER keyword and set it up for
running in IDL 5.0 as a non-blocking widget.
27 Sept 98. Fixed problems caused by IDL 5.1 color changes.
27 Sept 98. Removed JUST_REGISTER keyword. Made widget non-blocking.
03 Nov 98. Modified layout and added slider ganging. DWF.
(See /home/drw/idl/aux/chgcolor.pro)
NAME:
CIndex
PURPOSE:
This is a program for viewing the current colors in the
colortable with their index numbers overlayed on each color.
On 24-bit systems you must click the cursor in the graphics window
to see the colors in the current color table.
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: CIndex
INPUTS: None.
Optional Inputs: None
OUTPUTS: None
OPTIONAL OUTPUTS: None
KEYWORD Parameters: None
COMMON BLOCKS: None
SIDE EFFECTS: None
RESTRICTIONS: Reqires XCOLORS and TVIMAGE from the Coyote Library:
http://www.dfanning.com/programs/xcolors.pro
http://www.dfanning.com/programs/xtvimage.pro
PROCEDURE:
Draws a 31x25 set of small rectangles in 256 different colors.
Writes the color index number on top of each rectangle.
MODIFICATION HISTORY: Written by David Fanning, May 1995
Widgetized and made it work in 24-bit color. Colors are
updated by clicking in window. 22 Oct 98. DWF
Replace POLYFILL with TV command to avoid underflow error in
Z-buffer. 8 March 99. DWF
Fixed a problem with 24-bit devices with color decomposition ON. 15 Feb 2000. DWF.
(See /home/drw/idl/aux/cindex.pro)
ROUTINE: CLASSIFY
FUNCTION:
Display the physical locations of points selected on the
basis of image quantities, xa and ya. An interactive
cursor box is used to select clusters of points from the
2-d scatter plot of xa vs ya. These points are drawn on a
satellite image to indicate their actual physical
location.
CALLING SEQUENCE:
classify,xa,ya,class_out,image=image,class_in=class_in,select=select, $
n_samples=n_samples,blow_up=blow_up,title=title,ytitle=ytitle, $
xtitle=xtitle,ititle=ititle
CATEGORY:
Interactive graphics
REQUIRED INPUTS:
XA First channel parameter, x-axis of scatter plot
YA Second channel parameter, y-axis of scatter plot
OPTIONAL INPUTS (keyword parameters):
IMAGE Image of a particular satellite channel over which
points are ploted. If not supplied points are ploted
over blank plot
CLASS_IN (Byte array) Pixel color class initialization. Each
element corresponds to one pixel in the sample set
(see n_samples, below). An initial run of CLASSIFY
will generate the byte array, CLASS_OUT. This can be
used in a subsequent run of CLASSIFY with
CLASS_IN=CLASS_OUT to restart CLASSIFY in its former
state. When set, CLASS_IN overrides the effect of
SELECT and N_SAMPLES, below.
N_SAMPLES 2 element vector specifying the number of samples in the
x and y directions. E.g., if N_SAMPLES=[100,150],
then the scatter plot will consist of a 100x150
element subset of the original image. If N_SAMPLES
is not set, a default number of samples in the x and
y directions is used.
SELECT Vector of pre-selected indices (longword integers).
For example, SELECT=WHERE(XX LT 10) chooses only
those sample points for which parameter xx
is less than 10.
BLOW_UP Two element vector of specifying the image size blowup factor
TITLE Title of scatter plot
XTITLE Scatter plot x-axis label
YTITLE Scatter plot y-axis label
ITITLE Plot title of satellite image
NO_COLOR don't use color, show points with unique symbols
OUTPUTS
CLASS_OUT (Byte array) Color class of each sample point. Values
between 1 - 6 indicate different selected color
classes. Greater values indicate unselected points
which can be selected with the cursor. CLASS_OUT can
be used in another call to CLASSIFY, e.g.,
CLASSIFY,XA,YA,CLASS_OUT ; followed by,
CLASSIFY,XA,YA,CLASS_IN=CLASS_OUT
COMMON BLOCKS:
none
SIDE EFFECTS:
Two windows are created to contain the scatter plot (window 0) and
the physical image (window 2). Calls TVLCT to load a customized
color table with grey scale for byte values greater than 10 and
discreet colors for byte values between 1 and 10.
RESTRICTIONS:
Works only on window system drivers
PROCEDURE:
Points which enter into the cursor box are hi-lighted and stored
for plotting on the satellite image. The left mouse button increases
the size of the cursor box while the middle mouse button decreases it
The right mouse button stops the selection process and displays a
pop-up menu with 4 options:
(n) select a new selection class (assign a new color)
(r) reset the selection set
(d) display the selection set on the satellite image
(p) save current plot to postscript file "plot.ps"
(q) clean up displays and quit
author: Paul Ricchiazzi oct92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/classify.pro)
ROUTINE: CLASSIFY
FUNCTION:
Display the physical locations of points selected on the
basis of image quantities, xa and ya. An interactive
cursor box is used to select clusters of points from the
2-d scatter plot of xa vs ya. These points are drawn on a
satellite image to indicate their actual physical
location.
CALLING SEQUENCE:
classify,xa,ya,class_out,image=image,class_in=class_in,select=select, $
n_samples=n_samples,blow_up=blow_up,title=title,ytitle=ytitle, $
xtitle=xtitle,ititle=ititle
CATEGORY:
Interactive graphics
REQUIRED INPUTS:
XA First channel parameter, x-axis of scatter plot
YA Second channel parameter, y-axis of scatter plot
OPTIONAL INPUTS (keyword parameters):
IMAGE Image of a particular satellite channel over which
points are ploted. If not supplied points are ploted
over blank plot
CLASS_IN (Byte array) Pixel color class initialization. Each
element corresponds to one pixel in the sample set
(see n_samples, below). An initial run of CLASSIFY
will generate the byte array, CLASS_OUT. This can be
used in a subsequent run of CLASSIFY with
CLASS_IN=CLASS_OUT to restart CLASSIFY in its former
state. When set, CLASS_IN overrides the effect of
SELECT and N_SAMPLES, below.
N_SAMPLES 2 element vector specifying the number of samples in the
x and y directions. E.g., if N_SAMPLES=[100,150],
then the scatter plot will consist of a 100x150
element subset of the original image. If N_SAMPLES
is not set, a default number of samples in the x and
y directions is used.
SELECT Vector of pre-selected indices (longword integers).
For example, SELECT=WHERE(XX LT 10) chooses only
those sample points for which parameter xx
is less than 10.
BLOW_UP Two element vector of specifying the image size blowup factor
TITLE Title of scatter plot
XTITLE Scatter plot x-axis label
YTITLE Scatter plot y-axis label
ITITLE Plot title of satellite image
NO_COLOR don't use color, show points with unique symbols
OUTPUTS
CLASS_OUT (Byte array) Color class of each sample point. Values
between 1 - 6 indicate different selected color
classes. Greater values indicate unselected points
which can be selected with the cursor. CLASS_OUT can
be used in another call to CLASSIFY, e.g.,
CLASSIFY,XA,YA,CLASS_OUT ; followed by,
CLASSIFY,XA,YA,CLASS_IN=CLASS_OUT
COMMON BLOCKS:
none
SIDE EFFECTS:
Two windows are created to contain the scatter plot (window 0) and
the physical image (window 2). Calls TVLCT to load a customized
color table with grey scale for byte values greater than 10 and
discreet colors for byte values between 1 and 10.
RESTRICTIONS:
Works only on window system drivers
PROCEDURE:
Points which enter into the cursor box are hi-lighted and stored
for plotting on the satellite image. The left mouse button increases
the size of the cursor box while the middle mouse button decreases it
The right mouse button stops the selection process and displays a
pop-up menu with 4 options:
(n) select a new selection class (assign a new color)
(r) reset the selection set
(d) display the selection set on the satellite image
(p) save current plot to postscript file "plot.ps"
(q) clean up displays and quit
author: Paul Ricchiazzi oct92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/classify.pro)
ROUTINE: classplt
USEAGE: classplt,xx
classplt,xx,yy,alat,alon,$
[title=title,xtitle=xtitle,ytitle=ytitle,sym=sym]
PURPOSE: Draws two seperate plots to the graphics device:
1. 2-d scatter plot of yy vs xx
2. physical position of selected classes with respect
to coastline features.
INPUT:
xx index array of selected points for a class
(class definition mode)
xx 2-D array, x quantity of scatter plot (ploting mode)
yy 2-D array, y quantity of scatter plot
alat latitude array
alon longitude array
title plot title (optional). One or two element string array
if two strings are specified the first string is used to
title the scatter plot while the second titles the mapped
plot
xtitle x title (optional)
ytitle y title (optional)
sym a vector of symbol index values. Classes are assigned symbols
in the sequence specified in SYM. (default=[1,4,7,5,6,2])
(1=+, 2=*, 3=., 4=diamond, 5=triangle, 6=square, 7=x)
PROCEDURE: At least two steps are required to make plots with CLASSPLT:
1. In class definition mode CLASSPLT is called with a single
argument one or more times to accumulate class definitions
to be used later in the ploting mode.
2. In plotting mode CLASSPLT is called with at least 4
arguments. In this mode CLASSPLT produces a scatter
plot and position plot of the previously defined classes.
EXAMPLE:
;;
alat=findrng(30,50,30)
alon=findrng(-120,100,30)
a1=randata(30,30,s=3)
a2=randata(30,30,s=2)
Here is a sequence of commands which uses the interactive graphics
procedure, INSIDE, to simplify class specifcation.
plot,a1,a2,psym=3
classplt,inside(a1,a2)
classplt,inside(a1,a2)
classplt,inside(a1,a2)
classplt,a1,a2,alat,alon
;;
COMMON BLOCKS: classblk
author: Paul Ricchiazzi oct92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/classplt.pro)
ROUTINE: classplt
USEAGE: classplt,xx
classplt,xx,yy,alat,alon,$
[title=title,xtitle=xtitle,ytitle=ytitle,sym=sym]
PURPOSE: Draws two seperate plots to the graphics device:
1. 2-d scatter plot of yy vs xx
2. physical position of selected classes with respect
to coastline features.
INPUT:
xx index array of selected points for a class
(class definition mode)
xx 2-D array, x quantity of scatter plot (ploting mode)
yy 2-D array, y quantity of scatter plot
alat latitude array
alon longitude array
title plot title (optional). One or two element string array
if two strings are specified the first string is used to
title the scatter plot while the second titles the mapped
plot
xtitle x title (optional)
ytitle y title (optional)
sym a vector of symbol index values. Classes are assigned symbols
in the sequence specified in SYM. (default=[1,4,7,5,6,2])
(1=+, 2=*, 3=., 4=diamond, 5=triangle, 6=square, 7=x)
PROCEDURE: At least two steps are required to make plots with CLASSPLT:
1. In class definition mode CLASSPLT is called with a single
argument one or more times to accumulate class definitions
to be used later in the ploting mode.
2. In plotting mode CLASSPLT is called with at least 4
arguments. In this mode CLASSPLT produces a scatter
plot and position plot of the previously defined classes.
EXAMPLE:
a4=congrid(avhrr4,40,30) ; reduce size of sample set
a3=congrid(avhrr3,40,30) ; could also use SUPERPIX
classplt,inside(a4,a3-a4,[3,6,5,3],[4,3,5,4]) ; define classes
classplt,where(a4 gt -6 and a3-a4 lt 8) ;
classplt,where(a4 gt -17 and a3-a4 gt 8) ;
classplt,a4,a3-a4,alat,alon ; make the plot
Here is a sequence of commands which uses the interactive graphics
procedure, INSIDE, to simplify class specifcation.
classplt,inside(a4,a3-a4)
classplt,inside(a4,a3-a4)
classplt,inside(a4,a3-a4)
classplt,a4,a3-a4,alat,alon
COMMON BLOCKS: classblk
author: Paul Ricchiazzi oct92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/classplt.pro)
ROUTINE: cliprange
PURPOSE: compute greyscale range for images, allowing for a fixed
percentage of the pixels to be within the greyscale range.
USEAGE: result=cliprange(qval,clip_top,clip_bot)
INPUT:
qval image array
clip_top fraction of pixels to be clipped off top of range
clip_bot fraction of pixels to be clipped off bottom of range
OUTPUT: result=[range_bot,range_top], where range_bot and range_top
are the numerical range of the color scale
EXAMPLE: compute colorscale range such that 99% of the pixels are
within the range:
range=cliprange(image,.005,.005)
author: Paul Ricchiazzi sep93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/cliprange.pro)
PROJECT: TRACE NAME: CLOSEIN.PRO PURPOSE: To pick out the region of the UV images that show the flare matter flowing. CALLING SEQUENCE: closein,cube,outputarr INPUTS: cube - input data array cube outputarr - the array into which the zoomed-in region data will go.
(See /home/drw/idl/bin/closein.pro)
PROJECT: TRACE NAME: CLOSEIN2.PRO PURPOSE: To pick out the region of the EUV images that show the flare matter flowing. CALLING SEQUENCE: closein,cube,outputarr INPUTS: cube - input data array cube outputarr - the array into which the zoomed-in region data will go.
(See /home/drw/idl/bin/closein2.pro)
ROUTINE: cloud_art
PURPOSE: draw an idealized cloud
USEAGE: cloud_art,pos,bumps=bumps
INPUT:
pos normal coordinates of cloud frame, [xll,yll,xur,yur]
where ll=lower left corner and ur=upper right corner
KEYWORD INPUT:
bumps number of bumps on upper side of cloud. (default=6)
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
w8x11
cloud_art,[.1,.8,.9,.9],bumps=8
AUTHOR: Paul Ricchiazzi 15 Mar 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/cloud_art.pro)
ROUTINE: cloud_art
PURPOSE: draw an idealized cloud
USEAGE: cloud_art,pos,bumps=bumps
INPUT:
pos normal coordinates of cloud frame, [xll,yll,xur,yur]
where ll=lower left corner and ur=upper right corner
KEYWORD INPUT:
bumps number of bumps on upper side of cloud. (default=6)
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
w8x11
cloud_art,[.1,.8,.9,.9],bumps=8
AUTHOR: Paul Ricchiazzi 15 Mar 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/cloud_art.pro)
ROUTINE: clstrshd
USEAGE: result=clstrshd(a, binsz)
result=clstrshd(a, binsz, /align, /compare)
PURPOSE: compute super pixel cluster shade statistical test
of a scene. the cluster shade is a test of skewness
in the greylevel histogram of each superpixel.
INPUT:
a image array
binsz A scalar specifying the number of horizontal and
vertical sub-pixels in one super pixel.
BINSZ must be an odd integer.
align If set, output arrays are REBINed back up to the
original size and output array cell centers are aligned
with input array cell centers.
compare if set, compare A and ABIN with the FLICK procedure
OUTPUT:
cluster shade value at superpixel cell centers.
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/esrg/clstrshd.pro)
ROUTINE: clstrshd
USEAGE: result=clstrshd(a, binsz)
result=clstrshd(a, binsz, /align, /compare)
PURPOSE: compute super pixel cluster shade statistical test
of a scene. the cluster shade is a test of skewness
in the greylevel histogram of each superpixel.
INPUT:
a image array
binsz A scalar specifying the number of horizontal and
vertical sub-pixels in one super pixel.
BINSZ must be an odd integer.
align If set, output arrays are REBINed back up to the
original size and output array cell centers are aligned
with input array cell centers.
compare if set, compare A and ABIN with the FLICK procedure
OUTPUT:
cluster shade value at superpixel cell centers.
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/old.esrg/clstrshd.pro)
NAME:
CMAPPLY
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Applies a function to specified dimensions of an array
MAJOR TOPICS:
Arrays
CALLING SEQUENCE:
XX = CMAPPLY(OP, ARRAY, DIMS, [/DOUBLE], [TYPE=TYPE])
DESCRIPTION:
CMAPPLY will apply one of a few select functions to specified
dimensions of an array. Unlike some IDL functions, you *do* have
a choice of which dimensions that are to be "collapsed" by this
function. Iterative loops are avoided where possible, for
performance reasons.
The possible functions are: (and number of loop iterations:)
+ - Performs a sum (as in TOTAL) number of collapsed dimensions
AND - Finds LOGICAL "AND" (not bitwise) same
OR - Finds LOGICAL "OR" (not bitwise) same
* - Performs a product LOG_2[no. of collapsed elts.]
MIN - Finds the minimum value smaller of no. of collapsed
MAX - Finds the maximum value or output elements
USER - Applies user-defined function no. of output elements
It is possible to perform user-defined operations arrays using
CMAPPLY. The OP parameter is set to 'USER:FUNCTNAME', where
FUNCTNAME is the name of a user-defined function. The user
defined function should be defined such that it accepts a single
parameter, a vector, and returns a single scalar value. Here is a
prototype for the function definition:
FUNCTION FUNCTNAME, x, KEYWORD1=key1, ...
scalar = ... function of x or keywords ...
RETURN, scalar
END
The function may accept keywords. Keyword values are passed in to
CMAPPLY through the FUNCTARGS keywords parameter, and passed to
the user function via the _EXTRA mechanism. Thus, while the
definition of the user function is highly constrained in the
number of positional parameters, there is absolute freedom in
passing keyword parameters.
It's worth noting however, that the implementation of user-defined
functions is not particularly optimized for speed. Users are
encouraged to implement their own array if the number of output
elements is large.
INPUTS:
OP - The operation to perform, as a string. May be upper or lower
case.
If a user-defined operation is to be passed, then OP is of
the form, 'USER:FUNCTNAME', where FUNCTNAME is the name of
the user-defined function.
ARRAY - An array of values to be operated on. Must not be of type
STRING (7) or STRUCTURE (8).
OPTIONAL INPUTS:
DIMS - An array of dimensions that are to be "collapsed", where
the the first dimension starts with 1 (ie, same convention
as IDL function TOTAL). Whereas TOTAL only allows one
dimension to be added, you can specify multiple dimensions
to CMAPPLY. Order does not matter, since all operations
are associative and transitive. NOTE: the dimensions refer
to the *input* array, not the output array. IDL allows a
maximum of 8 dimensions.
DEFAULT: 1 (ie, first dimension)
KEYWORDS:
DOUBLE - Set this if you wish the internal computations to be done
in double precision if necessary. If ARRAY is double
precision (real or complex) then DOUBLE=1 is implied.
DEFAULT: not set
TYPE - Set this to the IDL code of the desired output type (refer
to documentation of SIZE()). Internal results will be
rounded to the nearest integer if the output type is an
integer type.
DEFAULT: same is input type
FUNCTARGS - If OP is 'USER:...', then the contents of this keyword
are passed to the user function using the _EXTRA
mechanism. This way you can pass additional data to
your user-supplied function, via keywords, without
using common blocks.
DEFAULT: undefined (i.e., no keywords passed by _EXTRA)
RETURN VALUE:
An array of the required TYPE, whose elements are the result of
the requested operation. Depending on the operation and number of
elements in the input array, the result may be vulnerable to
overflow or underflow.
EXAMPLES:
Shows how CMAPPLY can be used to total the second dimension of the
array called IN. This is equivalent to OUT = TOTAL(IN, 2)
IDL> IN = INDGEN(5,5)
IDL> OUT = CMAPPLY('+', IN, [2])
IDL> HELP, OUT
OUT INT = Array[5]
Second example. Input is assumed to be an 5x100 array of 1's and
0's indicating the status of 5 detectors at 100 points in time.
The desired output is an array of 100 values, indicating whether
all 5 detectors are on (=1) at one time. Use the logical AND
operation.
IDL> IN = detector_status ; 5x100 array
IDL> OUT = CMAPPLY('AND', IN, [1]) ; collapses 1st dimension
IDL> HELP, OUT
OUT BYTE = Array[100]
(note that MIN could also have been used in this particular case,
although there would have been more loop iterations).
Third example. Shows sum over first and third dimensions in an
array with dimensions 4x4x4:
IDL> IN = INDGEN(4,4,4)
IDL> OUT = CMAPPLY('+', IN, [1,3])
IDL> PRINT, OUT
408 472 536 600
Fourth example. A user-function (MEDIAN) is used:
IDL> IN = RANDOMN(SEED,10,10,5)
IDL> OUT = CMAPPLY('USER:MEDIAN', IN, 3)
IDL> HELP, OUT
OUT FLOAT = Array[10, 10]
(OUT(i,j) is the median value of IN(i,j,*))
MODIFICATION HISTORY:
Mar 1998, Written, CM
Changed usage message to not bomb, 24 Mar 2000, CM
Signficant rewrite for *, MIN and MAX (inspired by Todd Clements
); FOR loop indices are now type
LONG; copying terms are liberalized, CM, 22, Aug 2000
More efficient MAX/MIN (inspired by Alex Schuster), CM, 25 Jan
2002
Make new MAX/MIN actually work with 3d arrays, CM, 08 Feb 2002
Add user-defined functions, ON_ERROR, CM, 09 Feb 2002
Correct bug in MAX/MIN initialization of RESULT, CM, 05 Dec 2002
$Id: cmapply.pro,v 1.5 2002/12/10 02:50:17 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmapply.pro)
NAME:
CMCONGRID
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:
Array Manipulation.
CALLING SEQUENCE:
array = 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 = 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)
$Id: cmcongrid.pro,v 1.2 2001/03/25 18:10:47 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmcongrid.pro)
ROUTINE: cmplxgen
USEAGE: result=cmplxgen(nx,ny[,/center])
INPUT:
nx,ny dimensions of output
KEYWORD INPUT:
center if set RESULT is shifted so that the (0,0) point
is the central element of the complex array
OUTPUT:
float(result) = array of column indecies
imaginary(result) = array of row indecies
EXAMPLE: r=cmplxgen(4,3)
0 1 2 3 0 0 0 0
float(r) = 0 1 2 3 imaginary(r) = 1 1 1 1
0 1 2 3 2 2 2 2
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/esrg/cmplxgen.pro)
ROUTINE: cmplxgen
USEAGE: result=cmplxgen(nx,ny[,/center])
INPUT:
nx,ny dimensions of output
KEYWORD INPUT:
center if set RESULT is shifted so that the (0,0) point
is the central element of the complex array
OUTPUT:
float(result) = array of column indecies
imaginary(result) = array of row indecies
EXAMPLE: r=cmplxgen(4,3)
0 1 2 3 0 0 0 0
float(r) = 0 1 2 3 imaginary(r) = 1 1 1 1
0 1 2 3 2 2 2 2
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/old.esrg/cmplxgen.pro)
NAME:
CMPRODUCT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
CMPRODUCT() is the multiplicative equivalent of TOTAL().
CALLING SEQUENCE:
Result = CMPRODUCT(ARRAY)
DESCRIPTION:
Calculates the product of all the elements of an array. Vector
multiplication in groups of powers of two make this operation
faster than a simple FOR loop. The number of actual
multiplications is still N_ELEMENTS(ARRAY). Double precision
should be used for the highest accuracy when multiplying many
numbers.
INPUTS:
ARRAY - Array of elements to multiply together. For instance,
ARRAY could contain the dimensions of another array--then
CMPRODUCT(ARRAY) would be the total number of elements of
that other array.
RETURNS:
The result of the function is the total product of all the elements
of ARRAY.
EXAMPLE:
SEE ALSO:
TOTAL, PRODUCT (from Astronomy User's Library)
MODIFICATION HISTORY:
Written, CM, 28 Mar 2000
(based on outline of PRODUCT by William Thompson)
$Id: cmproduct.pro,v 1.2 2001/03/25 18:10:42 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmproduct.pro)
NAME:
CMPS_FORM
PURPOSE:
This function puts up a form the user can configure a PostScript
device driver. The function result (if the user selects either the
ACCEPT or CREATE FILE buttons) can be sent directly to the DEVICE
procedure by means of its _Extra keyword. User's predefined
configurations may be retrieved from a common block.
AUTHOR:
*********** CM 19 Jan 1999 VERSION *************
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
Based almost entirely on, but a totally revamped version of, CMPS_FORM by
FANNING SOFTWARE CONSULTING (David Fanning Ph.D.) http://www.dfanning.com
MAJOR TOPICS:
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 DEVICE command are returned.
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.
HELP:
formInfo = CMPS_FORM(/Help)
CALLING SEQUENCE:
formInfo = CMPS_FORM(xoffset, yoffset, Cancel=cancelButton)
OPTIONAL INPUTS:
XOFFSET -- Optional xoffset of the top-level base of cmps_form. Default is
to try to center the form on the display.
YOFFSET -- Optional yoffset of the top-level base of cmps_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 cmps_form. It will set initial conditions. This makes
it possible to start cmps_form up again with the same values it had the
last time it was called. For example:
mysetup = cmps_form()
newsetup = cmps_form(Defaults=mysetup)
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 interrupting the user.
SELECT -- used only when INITIALIZE is set. Set SELECT to a
string which identifies the predefined configuration to
be returned by cmps_form when INITIALIZE is set. This is
a convenient way to select a predefined config
non-interactively.
LANDSCAPE -- The initial configuration of the landscape/portrait switch.
LOCALDEFAULTS -- A structure like the DEFAULTS structure. If specified,
then it is added as a predefined configuration entry called "Local".
See below for a further discussion of predefined configurations.
PREDEFINED -- An alternate way to specify predefined
configurations. Pass an array of structures to
populate the "predefined" dropbox in the
dialog. This array, if specified, overrides the the
common block technique.
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.
ASPECT -- The aspect ratio of the window (Y/X). This keyword can
substitute for one of XSIZE or YSIZE.
PRESERVE_ASPECT -- Set this keyword if you want to hold the
aspect ratio constant.
PAPERSIZE -- If set, allows user to specify the size of the paper
media to be printed on, as a scalar string. NOTE:
this specification cannot be passed to DEVICE, but
can be selected for completeness's sake. Default is
'Letter'.
MARGINSIZE -- Size of the margins on all sides. Default is 0.25 inches.
When MARGINSIZE is non-zero, a graphic cannot directly
abut the edge of the page. This is normally a good thing,
since there is often a non-printable region which borders
the page.
DEFAULTPAPER -- Default paper size to use, when it is unspecified
in a predefined, "local", or "default"
configuration. This value also overrides any
configuration from common blocks. European users
will probably set this to 'A4'.
PARENT -- if this widget is invoked by another widget program,
then this keyword parameter must be set to the top level
widget which is to serve as the group leader. Failure
to do so will result in unexpected behavior. IDL 4
programs do not need to pass this parameter. Default:
NONE.
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.
PAPERSIZE -- If set to a named variable, any newly selected paper
size is returned in that variable.
RETURN VALUE:
formInfo = { cmps_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?
isolatin1:0,$ ; Encoded with ISOLATIN1?
landscape:0 } ; Landscape or portrait mode?
USAGE:
The calling procedure for this function in a widget program will look something
like this:
info.ps_config = cmps_form(/Initialize)
formInfo = cmps_form(Cancel=canceled, Create=create, Defaults=info.ps_config)
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
info.ps_config = formInfo
ENDIF ELSE
info.ps_config = formInfo
ENDIF
MAJOR FUNCTIONS and PROCEDURES:
None. Designed to work originally in conjunction with XWindow, a
resizable graphics window. [ NOTE: this modified version of
cmps_form, by Craig Markwardt, is incompatible with the original
version of XWINDOW. ]
MODIFICATION HISTORY:
Based on cmps_form of : David Fanning, RSI, March 1995.
Major rewrite by: Craig Markwardt, October 1997.
- Drawing and updating of form and sample box are now modular
- Option of storing more than one predefined postscript configuration
- Selection of paper size by name
- Access to predfined configurations through (optional) common
block
Several additions, CM, April 1998 VERSION CM2.0
- better integration of paper sizes throughout program.
Predefined configurations now also know about paper.
- allow passing predefined configurations instead of using
common block
- addition of ISOLATIN selection, and streamlining of dialog
appearance
Fixed bug in INITIALIZE w.r.t. paper sizes, CM, Nov 1998
Added SELECT keyword, CM, 09 Dec 1998
Added Parent keyword to allow modal widgets in IDL 5, 19 Jan 1999
Added "Choose" button for filename selection, 19 Sep 1999
Added ability to program different button names, 19 Sep 1999
Added ASPECT and PRESERVE_ASPECT, based on work by Aaron Barth, 18
Oct 1999
Removed NOCOMMON documentation and logic, 19 Oct 1999, CM
COMMON BLOCKS:
The user may store frequently used or helpful configurations in a
common block, and cmps_form() will attempt to access them. This
provides a way for the user to have persistent, named,
configurations.
NOTE: this format has changed since the last version. You may
have to quit your IDL session for the changes to take effect
properly. If you have place a predefined configuration in your
startup file, you should review the new format.
COMMON CMPS_FORM_CONFIGS, cmps_form_DEFAULT_PAPERSIZE, cmps_form_STDCONFIGS
cmps_form_DEFAULT_PAPERSIZE - a string designating the default
paper size, when none is given.
The predefined configurations
offerred by this program will
respect the default value. (See
also the DEFAULTPAPER keyword.)
cmps_form_STDCONFIGS - An array of cmps_form_CONFIG structures,
each containing information about one
predefined configuration, such as its
name and size of paper. Each "config"
element is a cmps_form_INFO structure,
which contains the actual postscript
configuration.
See the IDL source code cmps_form_LOAD_CONFIGS for an example of how
to make a list of configurations. One possibility would be to
declare and populate the common block from within the user's
start-up script, allowing the same configurations to appear in
every session.
cmps_form() takes its initial list of configurations from this
common block if it exists. A default list is provided ala the
procedure cmps_form_LOAD_CONFIGS. Any modifications that take place
during the cmps_form() widget session are not transferred back to
the common block upon return. It might be useful to be able to do
this, through some form of 'save' procedure.
Also, if the PREDEFINED keyword is used, then the common block is
not consulted.
(See /home/drw/idl/aux/xfilter/cmps_form.pro)
NAME:
CMPS_FORM
PURPOSE:
This function puts up a form the user can configure a PostScript
device driver. The function result (if the user selects either the
ACCEPT or CREATE FILE buttons) can be sent directly to the DEVICE
procedure by means of its _Extra keyword. User's predefined
configurations may be retrieved from a common block.
AUTHOR:
*********** CM 01 Feb 2000 VERSION *************
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
$Id: cmps_form.pro,v 1.4 2001/12/11 20:20:37 craigm Exp $
Based almost entirely on, but a totally revamped version of, CMPS_FORM by
FANNING SOFTWARE CONSULTING (David Fanning Ph.D.) http://www.dfanning.com
MAJOR TOPICS:
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 DEVICE command are returned.
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.
HELP:
formInfo = CMPS_FORM(/Help)
CALLING SEQUENCE:
formInfo = CMPS_FORM(xoffset, yoffset, Cancel=cancelButton)
OPTIONAL INPUTS:
XOFFSET -- Optional xoffset of the top-level base of cmps_form. Default is
to try to center the form on the display.
YOFFSET -- Optional yoffset of the top-level base of cmps_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 cmps_form. It will set initial conditions. This makes
it possible to start cmps_form up again with the same values it had the
last time it was called. For example:
mysetup = cmps_form()
newsetup = cmps_form(Defaults=mysetup)
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 interrupting the user.
SELECT -- used only when INITIALIZE is set. Set SELECT to a
string which identifies the predefined configuration to
be returned by cmps_form when INITIALIZE is set. This is
a convenient way to select a predefined config
non-interactively.
LANDSCAPE -- The initial configuration of the landscape/portrait switch.
LOCALDEFAULTS -- A structure like the DEFAULTS structure. If specified,
then it is added as a predefined configuration entry called "Local".
See below for a further discussion of predefined configurations.
PREDEFINED -- An alternate way to specify predefined
configurations. Pass an array of structures to
populate the "predefined" dropbox in the
dialog. This array, if specified, overrides the the
common block technique.
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.
ASPECT -- The aspect ratio of the window (Y/X). This keyword can
substitute for one of XSIZE or YSIZE.
PRESERVE_ASPECT -- Set this keyword if you want to hold the
aspect ratio constant.
PAPERSIZE -- If set, allows user to specify the size of the paper
media to be printed on, as a scalar string. NOTE:
this specification cannot be passed to DEVICE, but
can be selected for completeness's sake. Default is
'Letter'.
MARGINSIZE -- Size of the margins on all sides. Default is 0.25 inches.
When MARGINSIZE is non-zero, a graphic cannot directly
abut the edge of the page. This is normally a good thing,
since there is often a non-printable region which borders
the page.
DEFAULTPAPER -- Default paper size to use, when it is unspecified
in a predefined, "local", or "default"
configuration. This value also overrides any
configuration from common blocks. European users
will probably set this to 'A4'.
PARENT -- if this widget is invoked by another widget program,
then this keyword parameter must be set to the top level
widget which is to serve as the group leader. Failure
to do so will result in unexpected behavior. IDL 4
programs do not need to pass this parameter. Default:
NONE.
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.
PAPERSIZE -- If set to a named variable, any newly selected paper
size is returned in that variable.
XPAGESIZE -- Size of paper in "X" dimension, in units given by
the returned config structure.
YPAGESIZE -- Size of paper in "Y" dimension, in units given by
the returned config structure.
PAGEBOX -- specifies the page rectangle relative to the plot
window, in normalized units. A 4-vector of the form
[XLL, YLL, XUR, YUR] is returned, giving the positions
of the lower left (LL) and upper right (UR) corners of
the page with respect to the plot window. Thus, the
following command:
PLOT, x, y, position=PAGEBOX
will construct a graphic whose plot region exactly
fills the page (with no margin around the edges).
Naturally, the page is usually larger than the
graphics window, so the normalized coordinates will
usually fall outside the range [0,1].
However, the bounding box constructed by the
Postscript driver includes only the graphics window.
Anything drawn outside of it may be clipped or
discarded.
RETURN VALUE:
formInfo = { cmps_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?
isolatin1:0,$ ; Encoded with ISOLATIN1?
landscape:0 } ; Landscape or portrait mode?
USAGE:
The calling procedure for this function in a widget program will
look something like this:
info.ps_config = cmps_form(/Initialize)
formInfo = cmps_form(Cancel=canceled, Create=create, $
Defaults=info.ps_config)
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
info.ps_config = formInfo
ENDIF ELSE
info.ps_config = formInfo
ENDIF
MAJOR FUNCTIONS and PROCEDURES:
None. Designed to work originally in conjunction with XWindow, a
resizable graphics window. [ NOTE: this modified version of
cmps_form, by Craig Markwardt, is incompatible with the original
version of XWINDOW. ]
MODIFICATION HISTORY:
Based on cmps_form of : David Fanning, RSI, March 1995.
Major rewrite by: Craig Markwardt, October 1997.
- Drawing and updating of form and sample box are now modular
- Option of storing more than one predefined postscript configuration
- Selection of paper size by name
- Access to predfined configurations through (optional) common
block
Several additions, CM, April 1998 VERSION CM2.0
- better integration of paper sizes throughout program.
Predefined configurations now also know about paper.
- allow passing predefined configurations instead of using
common block
- addition of ISOLATIN selection, and streamlining of dialog
appearance
Fixed bug in INITIALIZE w.r.t. paper sizes, CM, Nov 1998
Added SELECT keyword, CM, 09 Dec 1998
Added Parent keyword to allow modal widgets in IDL 5, 19 Jan 1999
Added "Choose" button for filename selection, 19 Sep 1999
Added ability to program different button names, 19 Sep 1999
Added ASPECT and PRESERVE_ASPECT, based on work by Aaron Barth, 18
Oct 1999
Removed NOCOMMON documentation and logic, 19 Oct 1999, CM
Added aspect to cmps_form_numevents (per Aaron Barth), 18 Oct 1999
Corrected small bug under Initialize keyword (inches), 18 Oct 1999
Made call to *_pscoord more consistent, 18 Oct 1999
Added XPAGESIZE, YPAGESIZE and PAGEBOX keywords, 19 Oct 1999
Small cosmetic cleanup, CM, 01 Feb 2000
Fix for IDL 5.5's handling of structures with arrays, CM, 11 Dec 2001
COMMON BLOCKS:
The user may store frequently used or helpful configurations in a
common block, and cmps_form() will attempt to access them. This
provides a way for the user to have persistent, named,
configurations.
NOTE: this format has changed since the last version. You may
have to quit your IDL session for the changes to take effect
properly. If you have place a predefined configuration in your
startup file, you should review the new format.
COMMON CMPS_FORM_CONFIGS, cmps_form_DEFAULT_PAPERSIZE, $
cmps_form_STDCONFIGS
cmps_form_DEFAULT_PAPERSIZE - a string designating the default
paper size, when none is given.
The predefined configurations
offerred by this program will
respect the default value. (See
also the DEFAULTPAPER keyword.)
cmps_form_STDCONFIGS - An array of cmps_form_CONFIG structures,
each containing information about one
predefined configuration, such as its
name and size of paper. Each "config"
element is a cmps_form_INFO structure,
which contains the actual postscript
configuration.
See the IDL source code cmps_form_LOAD_CONFIGS for an example of how
to make a list of configurations. One possibility would be to
declare and populate the common block from within the user's
start-up script, allowing the same configurations to appear in
every session.
cmps_form() takes its initial list of configurations from this
common block if it exists. A default list is provided ala the
procedure cmps_form_LOAD_CONFIGS. Any modifications that take place
during the cmps_form() widget session are not transferred back to
the common block upon return. It might be useful to be able to do
this, through some form of 'save' procedure.
Also, if the PREDEFINED keyword is used, then the common block is
not consulted.
$Id: cmps_form.pro,v 1.4 2001/12/11 20:20:37 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmps_form.pro)
NAME:
CMREPLICATE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Replicates an array or scalar into a larger array, as REPLICATE does.
CALLING SEQUENCE:
ARRAY = CMREPLICATE(VALUE, DIMS)
DESCRIPTION:
The CMREPLICATE function constructs an array, which is filled with
the specified VALUE template. CMREPLICATE is very similar to the
built-in IDL function REPLICATE. However there are two
differences:
* the VALUE can be either scalar or an ARRAY.
* the dimensions are specified as a single vector rather than
individual function arguments.
For example, if VALUE is a 2x2 array, and DIMS is [3,4], then the
resulting array will be 2x2x3x4.
INPUTS:
VALUE - a scalar or array template of any type, to be replicated.
NOTE: These two calls do not produce the same result:
ARRAY = CMREPLICATE( 1, DIMS)
ARRAY = CMREPLICATE([1], DIMS)
In the first case the output dimensions will be DIMS and
in the second case the output dimensions will be 1xDIMS
(except for structures). That is, a vector of length 1 is
considered to be different from a scalar.
DIMS - Dimensions of output array (which are combined with the
dimensions of the input VALUE template). If DIMS is not
specified then VALUE is returned unchanged.
RETURNS:
The resulting replicated array.
EXAMPLE:
x = [0,1,2]
help, cmreplicate(x, [2,2])
INT = Array[3, 2, 2]
Explanation: The 3-vector x is replicated 2x2 times.
x = 5L
help, cmreplicate(x, [2,2])
LONG = Array[2, 2]
Explanation: The scalar x is replicated 2x2 times.
SEE ALSO:
REPLICATE
MODIFICATION HISTORY:
Written, CM, 11 Feb 2000
Fixed case when ARRAY is array of structs, CM, 23 Feb 2000
Apparently IDL 5.3 can't return from execute(). Fixed, CM, 24 Feb
2000
Corrected small typos in documentation, CM, 22 Jun 2000
(See /home/drw/idl/aux/markwardt/cmreplicate.pro)
NAME:
CMRESTORE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Restore variables from an IDL SAVE file.
CALLING SEQUENCE: (various)
CMRESTORE, filename (implicit)
CMRESTORE, filename, var1, var2, ..., [, NAMES=names]
CMRESTORE, filename, DATA=pointers, NAMES=names, PASS_METHOD='POINTER'
CMRESTORE, filename, DATA=handles, NAMES=names, PASS_METHOD='HANDLE'
CMRESTORE, filename, DATA=structure, PASS_METHOD='STRUCT'
DESCRIPTION:
CMRESTORE is a replacement for the built-in IDL procedure RESTORE.
It restores variables and data from an existing IDL SAVE file,
written either by SAVE or CMSAVE. The CMSV utility library must
be installed in your IDL path to use CMSAVE and CMRESTORE.
The primary advantage to CMRESTORE is the ability to selectively
restore only certain variables from the input file (based on
name). CMRESTORE provides a number of ways to pass the data
between routines, typically using a pointer or structure, which
avoids the unsafe practice of restoring variables in the caller's
namespace. However, CMRESTORE can restore variables into the
caller's namespace, but users should be aware that this capacity
is somewhat limited in IDL versions 5.2 and below.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
COMPATIBILITY:
-- File Format --
CMRESTORE should be able to read files written by SAVE and CMSAVE
from IDL version 4 to version 5.4.
CMRESTORE cannot restore objects, pointers, compressed files, or
data sets larger than 2 gigabytes.
Data types available in newer versions of IDL, such as pointers
and long integers, will not be readable in older versions of IDL
which do not have those data types.
-- Calling Interface --
For the most part, all capabilities of CMRESTORE are available to
the user. However, it should be noted that passing variables by
positional parameter is not available under IDL 4, unless NAMES is
used to name the variables explicitly. Also, under IDL versions
5.2 and previous, it is not possible for CMRESTORE to restore
variables into the caller's name space if they are not yet
defined.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
FILENAME - the name of the SAVE file.
Default: none, this parameter must be specified.
VAR{i} - The values to be restored. By default the save name is
taken from the named variables that are passed. These
default names can be overridden by using the NAMES
keyword.
If no variables are passed as positional parameters, they
can still be saved using the DATA keyword. By invoking
CMRESTORE without positional parameters or DATA,
CMRESTORE automatically will attempt to restore the
variables to the calling routine's name space (the
"implicit" technique).
NOTE: in IDL 5.2 and below, user routines are not
allowed to *CREATE* new variables in the caller's name
space. CMRESTORE may fail if the variable in
undefined in the caller. Therefore you must define it
before calling CMRESTORE. The safer practice is to
use the VAR{i} positional parameters, or the DATA
keyword.
KEYWORDS:
FILENAME - the name of the SAVE file. The positional FILENAME
parameter takes precedence over the keyword FILENAME
parameter.
PASS_METHOD - a scalar string, describing the method of passing
data between the caller and CMRESTORE. The keyword
can take the value 'ARGUMENT', 'POINTER', 'HANDLE'
or 'STRUCT'. A value of 'ARGUMENT' indicates that
data values will be passed by command line argument,
and is the default. Other values are described
below.
DATA - A list of data elements to be restored from the output
file. The data elements can be one of the following,
depending on the value of PASS_METHOD. The means of
extracting the data, and the method of naming each
variable, are also indicated.
* PASS_METHOD='POINTER': An array of pointers to the variables
Data: pointed-to value Name: from NAMES keyword
* PASS_METHOD='HANDLE': An array of handles to the variables
Data: pointed-to value Name: from NAMES keyword
* PASS_METHOD='STRUCT': A structure containing data to be saved
Data: tag value Name: tag name
Data values are restored one by one, using the appropriate
name. Note that any variables passed as positional
parameters will cause the DATA keyword to be ignored.
CMRESTORE will allocate any pointer or handle resources.
The calling routine is responsible for deallocating any
pointer or handle resources.
NAMES - a string array, giving the names for each variable.
If the data are passed by positional parameters, the names
are assigned according to the position of the parameter in
the procedure call.
If the data are passed by an array of pointers or handles,
then the names are assigned according to the position of
the data in the array. In this case there is no other way
to supply the variable name. NAMES is required.
If the data are passed in a structure, then the names are
assigned according to the position of the data in the
structure. The values specified in the names keyword
override the tag names.
STATUS - upon return, an integer indicating the status of the
operation. A value of 1 indicates success, while 0
indicates failure. A failure condition does not
necessarily indicate that an individual variable could
not be restored; use the VARSTATUS keyword to detect such
situations.
VARSTATUS - upon return, an integer array indicating the status of
the restore operation for each variable. A value of 1
at position i in the array indicates success for the
ith variable, while a value of 0 indicates failure.
ERRMSG - upon return, a string indicating the status of the
operation. The empty string indicates success, while a
non-empty string indicates failure and describes the
error condition.
QUIET - if set, then the error message is returned to the calling
routine. By default an error condition causes execution
to stop and the message to be printed on the console.
VERBOSE - if set, then a short message is printed for each
variable.
EXAMPLE:
CMSAVE, VAR1, VAR2, FILENAME='test.sav'
CMSAVE, VAR1, VAR2, FILENAME='test.sav', NAMES=['A','B']
Save the data in VAR1 and VAR2 to the file test.sav. In the
first case the saved variable names will be VAR1 and VAR2. In
the second case the saved variable names will be A and B.
POINTERS = [ptr_new(VAR1), ptr_new(VAR2)]
CMSAVE, DATA=POINTERS, NAMES=['A','B'], FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B.
STRUCTURE = {A: VAR1, B: VAR2}
CMSAVE, DATA=STRUCTURE, FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B.
SEE ALSO:
CMSAVE, SAVE, RESTORE
MODIFICATION HISTORY:
Written, 14 May 2000
Documented, 22 Sep 2000
Restore into caller's name space now permitted, 11 Jan 2001
Documented "implicit" restore a little better, w/ errors, 01 Mar 2001
Make version checks with correct precision, 19 Jul 2001, CM
Restore with no args automatically does ALL, is this right?,
CM, 20 Aug 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmrestore.pro,v 1.18 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmrestore.pro)
NAME:
CMSAVE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Save IDL variables to a file. (IDL v5 and greater)
CALLING SEQUENCE: (various)
CMSAVE, var1, var2, ..., FILENAME=filename [, NAMES=names]
CMSAVE, DATA=pointers, NAMES=names, FILENAME=filename
CMSAVE, DATA=handles, NAMES=names, FILENAME=filename
CMSAVE, DATA=structure, FILENAME=filename
DESCRIPTION:
CMSAVE is a replacement for the built-in IDL procedure SAVE, with
more flexibility and increased capabilities.
CMSAVE produces output files that are compatible with the standard
save format of IDL versions 4 and 5 (and perhaps greater).
Variables may be restored by using either the built-in procedure
RESTORE, or CMRESTORE. The CMSV utility library must be installed
in your IDL path to use CMSAVE and CMRESTORE.
The primary advantages to CMSAVE are the ability to append
additional variables to an existing SAVE file, and several
flexible ways to pass the data and variable names to be saved.
CMSAVE also attempts to run on all IDL versions.
To append variables to an existing file, simply specify the APPEND
keyword, and the filename of an existing writable SAVE file.
Variables will be appended to the end of the file. It is possible
to append a variable with the same name as an existing variable in
a file. Both data values are stored in the file. However the
results upon restore are undefined. There is also a limitation
that only one series of heap values -- pointed-to data -- may be
saved in a file.
By the normal convention of the built-in SAVE command, both the
data and variable names to be saved are passed as parameters on
the command line. Each parameter must be a named variable; both
the name and value are saved.
This convention may be used in invoking CMSAVE as well. However,
in addition to passing the data by positional parameter, the user
can pass the data using the DATA keyword. If the DATA keyword is
used, then an array of pointers or handles may be passed, or a
structure of values may be passed. (see below) If both are
passed, then the positional parameters take precedence.
It is also possible to explicitly rename the saved variables: the
saved name does not need to be the name of the named variable.
Use the NAMES keyword to override the default name. By default
the name is drawn from any named variables, or from the structure
tag names if the DATA keyword is used with a structure. The NAMES
keyword takes precedence over these values. NOTE: Values passed
by pointer or handle are not named by default, and so will not be
saved unless the NAMES keyword is used.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
COMPATIBILITY:
-- File Format --
Files written by CMSAVE should be readable with all known versions
of IDL at the time of this writing (version 4 - version 5.4). It
is expected that this compatibility will persist.
CMSAVE cannot write objects, compressed files, or data sets larger
than 2 gigabytes.
Data types available in newer versions of IDL, such as pointers
and long integers, will not be readable in older versions of IDL
which do not have those data types.
-- Calling Interface --
For the most part, all capabilities of CMSAVE are available to the
user. However, it should be noted that passing variables by
positional parameter is not available under IDL 4, unless NAMES is
used to name the variables explicitly.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
VAR{i} - The variables to be saved. By default the save name is
taken from the named variables that are passed. These
default names can be overridden by using the NAMES
keyword.
Variables can also be specified by passing an array of
handles or pointers in the DATA keyword.
If no variables are passed as positional parameters or
using DATA, then CMSAVE will assume that *all* variables
at the caller's level should be saved (this is similar
behavior to the built-in SAVE routine). Note that system
variables cannot be saved with CMSAVE.
KEYWORDS:
ALL - for compatibility with the built-in SAVE routine. Ignored.
Note that CMSAVE cannot save system variables.
FILENAME - the name of the output file.
Default: 'cmsave.sav'
DATA - A list of data elements to be saved to the output file.
The data elements can be one of the following. The means
of extracting the data, and the method of naming each
variable, are also indicated.
* An array of pointers to the variables
Data: pointed-to value Name: from NAMES keyword
* An array of handles to the variables
Data: pointed-to value Name: from NAMES keyword
* A 1-element structure containing data to be saved.
Data: tag value Name: tag name
Data values are saved one by one, using the appropriate
name. Note that any variables passed as positional
parameters will cause the DATA keyword to be ignored.
The calling routine is responsible for deallocating any
pointer or handle resources.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
NAMES - a string array, giving the names for each variable.
If the data are passed by positional parameters, the names
are assigned according to the position of the parameter in
the procedure call. This can be especially useful to
rename local variables, and to give names to expressions.
If the data are passed by an array of pointers or handles,
then the names are assigned according to the position of
the data in the array. In this case there is no other way
to supply the variable name. NAMES is required.
If the data are passed in a structure, then the names are
assigned according to the position of the data in the
structure. The NAMES keyword values override the tag
names.
APPEND - if set, then the specified variables are appended to an
existing file.
Repeated variables will not cause an error, however they
may not be restored properly using the built-in RESTORE
procedure. It may also not be permitted to append
variables that contain heap pointers, to a save file
which already contains heap data.
STATUS - upon return, an integer indicating the status of the
operation. A value of 1 indicates success, while 0
indicates failure. A failure condition does not
necessarily indicate that an individual variable could
not be written; use the VARSTATUS keyword to detect such
situations.
VARSTATUS - upon return, an integer array indicating the status of
the save operation for each variable. A value of 1 at
position i in the array indicates success for the ith
variable, while a value of 0 indicates failure.
ERRMSG - upon return, a string indicating the status of the
operation. The empty string indicates success, while a
non-empty string indicates failure and describes the
error condition.
QUIET - if set, then the error message is returned to the calling
routine. By default an error condition causes execution
to stop and the message to be printed on the console.
VERBOSE - if set, then a short message is printed for each
variable.
XDR - for compatibility with the built-in SAVE routine. Ignored.
EXAMPLE:
CMSAVE, VAR1, VAR2, FILENAME='test.sav'
CMSAVE, VAR1, VAR2, FILENAME='test.sav', NAMES=['A','B']
Save the data in VAR1 and VAR2 to the file test.sav. In the
first case the saved variable names will be VAR1 and VAR2. In
the second case the saved variable names will be A and B.
POINTERS = [ptr_new(VAR1), ptr_new(VAR2)]
CMSAVE, DATA=POINTERS, NAMES=['A','B'], FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B. Data are passed by pointer.
STRUCTURE = {A: VAR1, B: VAR2}
CMSAVE, DATA=STRUCTURE, FILENAME='test.sav'
Save the data in VAR1 and VAR2 to the file test.sav. The saved
variable names will be A and B. Data are passed by structure.
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 14 May 2000
Documented, 22 Sep 2000
Made "more" compatible with SAVE; additional documentation, 11 Jan
2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsave.pro,v 1.14 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsave.pro)
NAME:
CMSAVEDIR
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Display a directory of the variables in an IDL SAVE file.
CALLING SEQUENCE:
CMSAVEDIR, filename [, /VERBOSE, /QUIET, ... ]
DESCRIPTION:
CMSAVEDIR will display a listing of the variables and other
objects stored in an IDL SAVE file.
For command-line users the primary function of CMSAVEDIR will be
to find out what data is stored in a file and when it was saved.
For that, they simply need to type: CMSAVEDIR, 'myfile.sav'
CMSAVEDIR also offers a number of features for programmers.
CMSAVEDIR essentially interrogates the save file and discovers the
numbers, names and types of each of the variables stored in the
file. Programmers can use that information to decide whether or
how to open a file using the other routines in the CMSVLIB.
Various keyword parameters are used return this information, as
documented below.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
COMPATIBILITY:
-- File Format --
CMSAVEDIR cannot examine compressed save files, or files larger
than 2 gigabytes.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
FILENAME - a scalar string, the name of the file to be examined.
KEYWORDS:
VERBOSE - if set, print more detailed information about the input file.
QUIET - if set, then do not print any output. Programmers can use
this keyword to allow CMSAVEDIR to return information
about the file silently.
STATUS - upon output, 1 for success, otherwise to indicate
failure.
ERRMSG - upon output, if a failure occurs, a message describing
the error condition.
N_VARIABLES - upon output, the number of variables in the file.
VAR_NAMES - upon output, contains a string array of the names of
the variables stored in the file.
TYPES - upon output, an 11xN_VARIABLES array containing the SIZE
information of each variable in the file.
N_PRO - upon output, the number of procedures stored in the file.
PRO_NAMES - upon output, the names of the procedures stored in the
file, as a string array.
N_FUNCTION - upon output, the number of functions stored in the
file.
FUNC_NAMES - upon output, the names of the functions stored in the
file, as a string array.
NAMED_STRUCTS - upon output, a string array listing any named
structures which appear in the SAVE file.
NAMED_CLASSES - upon output, a string array listing any named
class structures which appear in the SAVE file.
TIMESTAMP - upon output, contains the timestamp record information
in a structure. The fields of the structure are:
SAVE_DATE - string - date saved
SAVE_USER - string - user who saved file
SAVE_HOST - string - host name on which file
saved
VERSION - upon output, contains the version record information in
a structure. The fields of the structure are:
FORMAT_VERSION - integer - major format version
ARCH - string - saving host's !VERSION.ARCH
OS - string - saving host's !VERSION.OS
RELEASE - string - saving host's !VERSION.RELEASE
NOTICE - upon output, contains any textual notice included within
the file. The fields of the structure are:
TEXT - string - text of the notice
FORCE - if set, will force CMSAVEDIR to open the file even if it
detects a potential incompatibility.
EXAMPLE:
IDL> cmsavedir, 'int_str_intarr.sav'
** int_str_intarr.sav
** Sun Apr 9 20:28:25 2000 (craigm@beach.gsfc.nasa.gov)
** IDL v5.2 (linux)
A INT = 0
B STRING = 'hello'
C INT = Array[3]
** 3 variable(s), 0 heap value(s) and 0 procedure(s) in 1376 bytes
SEE ALSO:
CMRESTORE, CMSAVE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Documented, 12 Jan 2001, CM
Added USAGE message, 09 Jun 2001, CM
Fixed bug in printing common variables, 17 Mar 2002, CM
Added notification about RSI License, 13 May 2002, CM
Added NOTICE record type, 09 Jun 2003, CM
$Id: cmsavedir.pro,v 1.17 2003/06/28 22:21:07 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsavedir.pro)
NAME:
CMSET_OP
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Performs an AND, OR, or XOR operation between two sets
CALLING SEQUENCE:
SET = CMSET_OP(A, OP, B)
DESCRIPTION:
SET_OP performs three common operations between two sets. The
three supported functions of OP are:
OP Meaning
'AND' - to find the intersection of A and B;
'OR' - to find the union of A and B;
'XOR' - to find the those elements who are members of A or B
but not both;
Sets as defined here are one dimensional arrays composed of
numeric or string types. Comparisons of equality between elements
are done using the IDL EQ operator.
The complements of either set can be taken as well, by using the
NOT1 and NOT2 keywords. For example, it may be desireable to find
the elements in A but not B, or B but not A (they are different!).
The following IDL expressions achieve each of those effects:
SET = CMSET_OP(A, 'AND', /NOT2, B) ; A but not B
SET = CMSET_OP(/NOT1, A, 'AND', B) ; B but not A
Note the distinction between NOT1 and NOT2. NOT1 refers to the
first set (A) and NOT2 refers to the second (B). Their ordered
placement in the calling sequence is entirely optional, but the
above ordering makes the logical meaning explicit.
NOT1 and NOT2 can only be set for the 'AND' operator, and never
simultaneously. This is because the results of an operation with
'OR' or 'XOR' and any combination of NOTs -- or with 'AND' and
both NOTs -- formally cannot produce a defined result.
The implementation depends on the type of operands. For integer
types, a fast technique using HISTOGRAM is used. However, this
algorithm becomes inefficient when the dynamic range in the data
is large. For those cases, and for other data types, a technique
based on SORT() is used. Thus the compute time should scale
roughly as (A+B)*ALOG(A+B) or better, rather than (A*B) for the
brute force approach. For large arrays this is a significant
benefit.
INPUTS:
A, B - the two sets to be operated on. A one dimensional array of
either numeric or string type. A and B must be of the same
type. Empty sets are permitted, and are either represented
as an undefined variable, or by setting EMPTY1 or EMPTY2.
OP - a string, the operation to be performed. Must be one of
'AND', 'OR' or 'XOR' (lower or mixed case is permitted).
Other operations will cause an error message to be produced.
KEYWORDS:
NOT1, NOT2 - if set and OP is 'AND', then the complement of A (for
NOT1) or B (for NOT2) will be used in the operation.
NOT1 and NOT2 cannot be set simultaneously.
EMPTY1, EMPTY2 - if set, then A (for EMPTY1) or B (for EMPTY2) are
assumed to be the empty set. The actual values
passed as A or B are then ignored.
INDEX - if set, then return a list of indices instead of the array
values themselves. The "slower" set operations are always
performed in this case.
The indices refer to the *combined* array [A,B]. To
clarify, in the following call: I = CMSET_OP(..., /INDEX);
returned values from 0 to NA-1 refer to A[I], and values
from NA to NA+NB-1 refer to B[I-NA].
COUNT - upon return, the number of elements in the result set.
This is only important when the result set is the empty
set, in which case COUNT is set to zero.
RETURNS:
The resulting set as a one-dimensional array. The set may be
represented by either an array of data values (default), or an
array of indices (if INDEX is set). Duplicate elements, if any,
are removed, and element order may not be preserved.
The empty set is represented as a return value of -1L, and COUNT
is set to zero. Note that the only way to recognize the empty set
is to examine COUNT.
SEE ALSO:
SET_UTILS.PRO by RSI
MODIFICATION HISTORY:
Written, CM, 23 Feb 2000
Added empty set capability, CM, 25 Feb 2000
Documentation clarification, CM 02 Mar 2000
Incompatible but more consistent reworking of EMPTY keywords, CM,
04 Mar 2000
Minor documentation clarifications, CM, 26 Mar 2000
Corrected bug in empty_arg special case, CM 06 Apr 2000
Add INDEX keyword, CM 31 Jul 2000
Clarify INDEX keyword documentation, CM 06 Sep 2000
Made INDEX keyword always force SLOW_SET_OP, CM 06 Sep 2000
Added CMSET_OP_UNIQ, and ability to select FIRST_UNIQUE or
LAST_UNIQUE values, CM, 18 Sep 2000
Removed FIRST_UNIQUE and LAST_UNIQUE, and streamlined
CMSET_OP_UNIQ until problems with SORT can be understood, CM, 20
Sep 2000 (thanks to Ben Tupper)
Still trying to get documentation of INDEX and NOT right, CM, 28
Sep 2000 (no code changes)
$Id: cmset_op.pro,v 1.2 2001/03/25 18:10:42 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmset_op.pro)
NAME:
CMSVLIB
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Initialize the CMSVLIB save library
CALLING SEQUENCE:
VALUE = CMSVLIB(/QUERY)
DESCRIPTION:
This function initializes the CMSVLIB library to read, write and
interrogate IDL save files. Use the QUERY keyword to determine
whether the full CMSVLIB library is present.
The procedures in the library are:
High-level
CMSAVE - save variables to a save file
CMRESTORE - restore variables from a save file
CMSAVEDIR - list contents of a save file
CMSVLIB (function) - this file
Mid-level
CMSV_OPEN - open a save file for reading or writing
CMSVREAD - read non-pointer data from file
CMSVWRITE - write non-pointer data to file
Low-level
CMSV_RREC - read record from save file
CMSV_RVTYPE - read variable type information from file
CMSV_RDATA - read variable data from file
CMSV_WREC - write record to save file
CMSV_WVTYPE - write variable type information to file
CMSV_WDATA - write variable data to file
Utility
CMSV_RRAW (function) - read raw integer or string data from file
CMSV_WRAW - write raw integer or string data to file
CMSV_PTRSUM - create a heap data inventory
CMSV_TEST - test the library
TAGSIZE (function) - determine the types of all tags in a structure
HELPFORM (function) - create HELP-like string describing a variable
Users should consult
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
None
KEYWORDS:
QUERY - if set, determine whether the CMSVLIB library is
installed. Function returns 1 upon success, 0 upon
failure.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsvlib.pro,v 1.3 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsvlib.pro)
NAME:
CMSVREAD
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read a single variable from an open SAVE file
CALLING SEQUENCE:
CMSVREAD, UNIT, DATA [, NAME=NAME, /NO_DATA, VERSION=VERSION,
TIMESTAMP=TIMESTAMP ]
DESCRIPTION:
CMSVREAD reads a single IDL variable from an open IDL SAVE file.
The file should already have been opened as a normal file using
OPENR.
CMSVREAD is a simplified version of the CMSVLIB package, and as
such is not capable of reading heap data (pointers) or object
data. Strings, structures, and all array types are supported.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
UNIT - the open file unit.
DATA - a named variable, into which the new data is to be read.
KEYWORDS:
NAME - upon output, the name of the saved variable is returned in
this keyword. If a failure or end of file condition
occurs, name will be undefined upon return.
STRUCTURE_NAME - if the data to be read is a structure, upon
output, this keyword will contain the name of the
structure. A value of '' indicates an anonymous
structure.
SIZE - upon output, the SIZE type of the data is returned in this
keyword.
NO_DATA - if set, no data is read from the file, only the variable
name and type.
TIMESTAMP - after the first call to CMSVREAD on a newly opened
file, this keyword will contain the file timestamp
structure.
VERSION - after the first call to CMSVREAD on a newly opened file,
this keyword will contain the file version information,
if available.
QUIET - if set, error messages are not printed.
Default: an error causes errors to be printed with MESSAGE
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
Read all variables from a file, and print help on them.
openr, 50, 'test.sav'
name = ''
while n_elements(name) GT 0 do begin ;; EOF signalled by NAME undefined
cmsvread, 50, data, name=name
help, name, data
end
close, 50
SEE ALSO:
CMSVWRITE, CMRESTORE, CMSAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written and documented, 11 Jan 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsvread.pro,v 1.7 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsvread.pro)
NAME:
CMSVWRITE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write a single variable to an open SAVE file
CALLING SEQUENCE:
CMSVWRITE, UNIT, DATA [ , NAME=NAME, COMPATIBILITY=COMPAT ]
DESCRIPTION:
CMSVWRITE writes a single IDL variable to an open IDL SAVE file.
The file should already have been opened for writing as a normal
file using OPENW or OPENU.
CMSVWRITE is a simplified version of the CMSVLIB package, and as
such is not capable of writing heap data (pointers) or object
data, or structures that contain them. Strings, structures, and
all array types are supported.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
UNIT - the open file unit.
DATA - the data to be written.
KEYWORDS:
NAME - the optional name of the variable to be written (must be a
valid variable name).
Default: CMSVWRITE automatically creates a valid name.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5'
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
NO_END - a save file must terminate with an "end" record. By
default, CMSVWRITE will append such a record after the
variable is written, and then rewind the file pointer.
The end record must be written after the last variable,
but is optional otherwise. Set this keyword to disable
writing the end record (for performance reasons).
QUIET - if set, error messages are not printed.
Default: an error causes errors to be printed with MESSAGE
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
Write variables A, B, C and D to a file.
openw, 50, 'test.sav' ;; Add /STREAM under VMS !
cmsvwrite, 50, a, name='a'
cmsvwrite, 50, b, name='b'
cmsvwrite, 50, c, name='c'
close, 50
SEE ALSO:
CMSVREAD, CMRESTORE, CMSAVE, SAVE, CMSVLIB
MODIFICATION HISTORY:
Written and documented, 11 Jan 2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsvwrite.pro,v 1.11 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsvwrite.pro)
NAME:
CMSV_OPEN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Open IDL SAVE file for reading or writing
CALLING SEQUENCE:
CMSV_OPEN, UNIT, FILENAME, OFFSET, $
ACCESS=ACCESS, /FORCE, /GET_LUN, /REOPEN, $
COMPATIBILITY=COMPATIBILITY, $
STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_OPEN opens an IDL SAVE-formatted file for reading or writing.
The mode of operation is controlled by the ACCESS keyword, which
may be either 'R' for reading, 'W' for writing, or 'RW' for
read/write access.
'R': In the case of reading, the specified file is opened with
read-only access, and the first bytes are examined to verify that
it is indeed a valid IDL SAVE file.
'W': In the case of writing, the specified file is opened with
write access, and the initial file signature is written.
'RW': In the case of read-write access, the file must already
exist as a valid SAVE file. Users are advised that every time
they switch between reading and writing operations, they must use
POINT_LUN to flush the file buffers.
The CMSVLIB routines do not support file sizes greater than 2 GB,
nor SAVE files created with the COMPRESS option.
Upon return, the file pointer is positioned at the start of the
first valid SAVE record. The file offset is returned in OFFSET.
The user is responsible for reading or writing the remainder of
the file with other library routines.
The file unit is determined based on the following criteria. This
behavior is similar to the OPEN family of procedures, except for
the REOPEN keyword.
* If REOPEN is set then it is assumed that UNIT is an
already-open file, and FILENAME is ignored.
* If GET_LUN is set then a file unit is allocated with GET_LUN,
and upon success this unit is returned in UNIT.
* Otherwise it is asssumed that UNIT is a valid but unopened
file unit. Upon successful return, UNIT is opened.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
UNIT - a logical unit number (a scalar). In the case of GET_LUN,
a file unit will be allocated and returned in UNIT. In the
default case, or REOPEN, UNIT must be a valid file unit
upon input. For REOPEN the corresponding file must be
seekable.
FILENAME - a scalar string specifying the filename path (ignored
for REOPEN).
OFFSET - upon return, the file offset of the next available SAVE
record.
KEYWORDS:
ACCESS - a scalar string, case insensitive:
'R' - read-only access
'W' - write access (new file)
'RW' - read-write access (existing file)
Default: 'R' - read-only
GET_LUN - if set, the file unit is allocated using GET_LUN
FORCE - if set, then the file is opened despite a detected file
format inconsistency.
REOPEN - if set, then an already-opened file is manipulated. The
valid file unit must be specified by UNIT, and FILENAME
is ignored.
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Change BLOCK to STREAM to support VMS properly, 14 Feb 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_open.pro,v 1.12 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_open.pro)
NAME:
CMSV_PTRSUM
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Construct an inventory of heap data accessible to a variable
CALLING SEQUENCE:
CMSV_PTRSUM, VAR, LIST
DESCRIPTION:
This procedure constructs an inventory of heap data that is
accessible to a single variable. It searches all array elements,
recursively through structure tags, and by dereferencing pointers.
Users can use this procedure to determine all heap variables that
need to be saved to disk.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
VAR - the variable to be examined
LIST - upon output, an array of pointers, each of which points to
a heap variable accessible to VAR. If there are no heap
data pointed to by VAR, then LIST returns a NULL value.
KEYWORDS:
NULL - if set, return the null value in LIST instead of the
pointer list. VAR is ignored.
HAS_OBJECTS - upon return, the value is 1 if VAR contains or
points to an object reference, and 0 if not.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_ptrsum.pro,v 1.7 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_ptrsum.pro)
NAME:
CMSV_RDATA
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read SAVE-formatted data variable record from input block or file unit
CALLING SEQUENCE:
CMSV_RDATA, BLOCK, POINTER, SIZE, DATA, UNIT=UNIT, $
TEMPLATE=TEMPLATE, /TEMPORARY, PTR_INDEX=PTR_INDEX, $
PTR_CALLBACK=PTR_CALLBACK, PTR_OFFSETS=PTR_OFFSETS, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_RDATA reads the data portion of an IDL SAVE variable record.
An IDL variable is stored in two components: the type descriptor
which describes the name, type, and dimensions of the variable;
and the data record, which contains the raw data of the variable.
This procedure reads the raw data and returns it to the user. The
initial type portion of the record must have already been read
using the CMSV_RVTYPE procedure.
CMSV_RDATA supports the following variable types:
BYTE(1),INT(2),LONG(3) - integer types
UINT(12),ULONG(13),LONG64(14),ULONG64(15) - integer types (IDL >5.2 only)
FLOAT(4),DOUBLE(5),COMPLEX(6),DCOMPLEX(9) - float types
STRING(7) - string type
STRUCT(8) - structure type
POINTER(10) - pointer type - SEE BELOW
NOT SUPPORTED - OBJ(11) - object reference type - NOT SUPPORTED
Arrays and structures containing any of the supported types are
supported (including structures within structures).
For scalars and arrays of numeric or string types, the caller must
only supply the SIZE parameter, which specifies the type and
dimensions of the variable to be read. This information can be
obtained from the CMSV_RVTYPE routine. The data is returned in the
output parameter DATA.
For structure data, in addition to specifying the SIZE array, the
user must also supply a "template" describing the structure into
which the data will be read. This template is simply a "blank"
form of the data structure, and is returned by CMSV_RVTYPE.
Thus, a simple way to read structure, numeric or string data is
the following code (with error checking removed)
CMSV_RVTYPE, block, pointer, name, size, template=template, unit=unit
CMSV_RDATA, block, pointer, size, data, template=template, unit=unit
[ This code assumes the record header has been read with
CMSV_RREC. ]
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
POINTER DATA
Pointer data stored in IDL SAVE files are particularly difficult
to manage, because the actual heap variables are stored in
separate records which *precede* the record of interest. Thus, if
your application requires the reading of pointer data, you must
perform special processing in your own code in order to support
it. In essence, you must maintain an inventory of heap variables
as they are encountered in the file.
If these procedures are not followed then pointer data will not be
read, and a LONG integer value appears in the pointers' places.
Under IDL 4, pointer data can never be read.
This is accomplished by placing some additional logic in your file
processing loop. There are four separate components to this: (1)
loop initialization; (2) reading a HEAP_INDEX record; (3) parsing
a HEAP_DATA record; and (4) passing extra arguments to CMSV_RDATA.
The additional state information is maintained in two variables
named PTR_INDEX, which keeps track of the heap variable numbers,
and PTR_OFFSETS, which stores the file location of each variable.
(1) Loop initialization: is quite simple, use the following code:
ptr_index = [0L]
ptr_offsets = [0L]
ptr_data = [ptr_new()]
(2) Reading HEAP_INDEX, which is an array of values indicating
the heap variable numbers of each heap variables. These
values are stored in PTR_INDEX:
CMSV_RHEAP, block, pointer, index, unit=unit
ptr_index = [ptr_index, index]
ptr_offsets = [ptr_offsets, lonarr(n_elements(index))]
ptr_data = [ptr_data, ptrarr(n_elements(index))]
(3) Parse the HEAP_DATA record. Here were are interested in the
heap variable number, and the file offset.
opointer = pointer
CMSV_RVTYPE, block, pointer, vindex, /heap, unit=unit
vindex = floor(vindex(0))
wh = where(ptr_index EQ vindex)
ptr_offsets(wh(0)) = offset + opointer
Keep in mind that the file offset is OFFSET+POINTER.
(4) Pass extra parameters to CMSV_RDATA. The user simply passes
these extra variables to the CMSV_RDATA procedure, which
automatically recognizes heap data and reads it from the
appropriate location.
CMSV_RVTYPE, block, pointer, name, size, unit=unit, template=tp
CMSV_RDATA, block, pointer, size, data, template=tp, $
unit=unit, ptr_offsets=ptr_offsets, $
ptr_index=ptr_index, ptr_data=ptr_data
If this technique is used properly, only those heap variables
which are needed are read. Thus, there are never any lost or
dangling pointers. Since each bit of heap data is stored in a
variable returned to the user, it is not necessary to
PTR_FREE(ptr_data); in fact, doing so would corrupt the input
data.
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
SIZE - an array of integers describing the type and dimensions of
the variable to be read, in the format returned by the
SIZE() routine. This parameter is required.
DATA - upon output, the data variable. If any heap data is read,
the user is ultimately responsible for freeing it.
KEYWORDS:
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
TEMPLATE - for structure data (data type 8), a "blank" structure
containing the fields and data values to be read in.
This structure is returned by CMSV_RVTYPE.
This keyword is mandatory for structure data.
TEMPORARY - if set, BLOCK becomes undefined upon return.
PTR_OFFSETS - array of file offsets, as described above. Default:
pointer data is converted to an integer.
PTR_INDEX - array of heap variable indices, as described above.
Default: pointer data is converted to an integer.
PTR_DATA - array of pointers, as described above.
Default: pointer data is converted to an integer.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is used by this routine)
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added UNDEFINED data type for IDL >5.3, CM, 21 Apr 2001
Fixed bug for pointers within structures, CM, 21 Apr 2001
Add support for IDL 4 byte-compiled strings, CM, 22 Apr 2001
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_rdata.pro,v 1.10 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_rdata.pro)
NAME:
CMSV_RRAW
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read raw SAVE data from input block or file unit
CALLING SEQUENCE:
DATA = CMSV_RRAW( BLOCK, POINTER, NELT, UNIT=UNIT, $
STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG )
DESCRIPTION:
This function reads raw integer or string data from an IDL SAVE
file. This is the lowest level reading function in the library,
intended for developers who are investigating new and existing
SAVE file formats.
The primary use of this function will be to read raw integer and
string data from the input. By default, a single value is read as
a scalar; however a vector of values can be read using the NELT
parameter. Special keywords are provided for the common data
types STRING, LONG and BYTE. Other integer types can be read
using the TYPE keyword. Users who want to read the data from an
IDL variable should use CMSV_RDATA, which can handle
multidimensional data, as well as floating point and structure
data.
A secondary use of this function is to buffer the data in BLOCK.
This will ensure that BLOCK contains enough data to convert NELT
integers without reading from disk. CMSV_RRAW itself does not
convert any values so the return value should be ignored.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
NELT - optional parameter specifying the number of values to read.
If unspecified, then a scalar value is read and returned.
If specified, then a vector of NELT values is read and
returned.
KEYWORDS:
BUFFER - if set, CMSV_RRAW will ensure that BLOCK contains at
least NELT values without converting them. The return
value should be ignored. This keyword is ignored for
strings.
LONG - if set, the values are converted as LONG integers.
BYTE - if set, the values are converted as BYTEs.
STRING - if set, the values are converted as STRINGs. Each string
may be of variable length.
TYPE - if none of the above keywords is set, then values of type
TYPE are read. TYPE should be a string, one of 'BYTE',
'FIX', 'LONG', 'ULONG', 'LONG64', or 'ULONG64'.
If no type is specified then BYTEs are read.
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is used by this routine)
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_rraw.pro,v 1.6 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_rraw.pro)
NAME:
CMSV_RREC
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read SAVE-formatted record header from input block or file unit
CALLING SEQUENCE:
CMSV_RREC, BLOCK, POINTER, DATA, UNIT=UNIT, $
BLOCK_TYPE=BLOCK_TYPE, BLOCK_NAME=BLOCK_NAME, NEXT_BLOCK=NEXT_BLOCK, $
INITIALIZE=INITIALIZE, FULL=FULL, PROMOTE64=PROMOTE64, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
This procedure reads the header of an IDL SAVE record. The header
consists of four bytes at the beginning of each record which
indentifies the type and size of the record. This procedure also
additionally reads many full records as noted below.
Users can determine the block type by examining the values
returned in the BLOCK_TYPE and BLOCK_NAME keywords. The following
values are supported. Some record types contain additional data.
CMSV_RREC reads some of these record types automatically (those
entries below marked with [this procedure]). Other records do not
contain any additional data at all (those entries marked with an
[empty]), and thus require no further processing.
BLOCK_TYPE BLOCK_TYPE READ RECORD DATA WITH...
0 = 'START_MARKER' [empty]
1 = 'COMMON_BLOCK' [this procedure]
2 = 'VARIABLE' CMSV_RVTYPE / CMSV_RDATA
3 = 'SYSTEM_VARIABLE' CMSV_RVTYPE / CMSV_RDATA
6 = 'END_MARKER' [empty]
10 = 'TIMESTAMP' [this procedure]
12 = 'COMPILED' no published procedure
13 = 'IDENTIFICATION' [this procedure]
14 = 'VERSION' [this procedure]
15 = 'HEAP_INDEX' [this procedure]
16 = 'HEAP_DATA' CMSV_RVTYPE
17 = 'PROMOTE64' [empty]
19 = 'NOTICE' [this procedure]
For records that contain variable data, the external procedures
CMSV_RVTYPE and CMSV_RDATA must be used, as noted above.
Otherwise CMSV_RREC will read and convert the appropriate data
automatically and return it in the DATA positional parameter.
The offset of the next record is returned in the NEXT_BLOCK
keyword. For file input, the command, "POINT_LUN, UNIT,
NEXT_BLOCK" will position the file pointer to the next block.
Users should be aware that the SAVE files produced by IDL version
5.4 appear to have a different header format. The new header size
is five bytes, and is incompatible with the older format. In
order to activate the longer header size, the PROMOTE64 keyword
must be set.
By default the entire record is not read from the file at once.
Users that wish to operate on the entire record immediately should
set the FULL keyword.
After issuing a POINT_LUN the block cache in BLOCK must be reset
using the /INITIALIZE keyword.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
SPECIFIC RECORD TYPES
CMSV_RREC reads certain specific record types automatically and
returns the data in the positional parameter data. Users should
pass a named variable in this parameter to retrieve the return
value.
When a record of type 'VERSION' (14) is encountered, it is read,
and returned as a structure. The returned data are of the form:
{ FORMAT_VERSION: 0L, $ ; Format version number of file
ARCH: '', $ ; !VERSION.ARCH of creating host
OS: '', $ ; !VERSION.OS of creating host
RELEASE: '' } ; !VERSION.RELEASE of creating host
When a record of type 'TIMESTAMP' (10) is encountered, it is read,
and returned as a structure. The returned data are of the form:
{ SAVE_DATE: '', $ ; Date the save file was created
SAVE_USER: '', $ ; User name who created file
SAVE_HOST: '' } ; Host name that created file
Save files created by IDL version 4 do not contain a timestamp
record.
When a record of type 'IDENTIFICATION' (13) is encountered, it is
read, and returned as a structure. The returned data are of the
form:
{ AUTHOR: '', $ ; Author of SAVE file
TITLE: '', $ ; Title of SAVE file
IDCODE: '' } ; Identifying code for SAVE file
It appears that this record is not used in IDL version 5 or later.
When a record of type 'COMMON_BLOCK' (1) is encountered, it is
read and returned. A common block descriptor consists of an array
of strings whose first element is the common block name, and whose
remaining elements are the common block variable names. No
variable data are stored with the common block definition.
When a record of type 'HEAP_INDEX' (15) is encountered, it is read
and returned in DATA. The heap index specifies a list of which
heap variables are stored in the current save file. These indices
are simply numbers which identify each heap variable (i.e.,
"" would have an index of 2). Users should note that
the heap index will not necessarily be sequentially increasing,
and may have gaps.
When a record of type 'NOTICE' (19) is encountered, it is read and
returned in DATA. It is a structure with one field: {TEXT: ''},
where TEXT is the text content of the notice.
Users should consult CMSV_RDATA for instructions on how to read
heap data.
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
KEYWORDS:
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is used by this routine)
BLOCK_TYPE - upon return, the numeric record type, as described
above.
BLOCK_NAME - upon return, a scalar string specifying the record
type, as specified above.
NEXT_BLOCK - upon return, file offset of the next record in the
file.
INITIALIZE - if set, then BLOCK and POINTER are initialized to a
pristine state. All data in these two variables is
lost before reading the next record.
FULL - if set, then the entire record will be read into BLOCK.
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Fix typo for RHEAP call, CM, 21 Apr 2001
Added notification about RSI License, 13 May 2002, CM
Added NOTICE record type, 09 Jun 2003, CM
$Id: cmsv_rrec.pro,v 1.12 2003/06/28 22:21:07 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_rrec.pro)
NAME:
CMSV_RVTYPE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Read variable type information from input block or file unit
CALLING SEQUENCE:
CMSV_RVTYPE, BLOCK, POINTER, NAME, SIZE, UNIT=UNIT, $
TEMPLATE=TEMPLATE, SUFFIX=SUFFIX, $
/NO_CREATE, /NO_TYPE, /HEAP, /SYSTEM, $
STRUCTURE_NAME=STNAME, $
NAMED_STRUCTS=STRUCTS, NAMED_CLASSES=CLASSES, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_RVTYPE reads the type portion of an IDL SAVE variable record.
An IDL variable is stored in two components: the type descriptor
which describes the name, type, and dimensions of the variable;
and the data record, which contains the raw data of the variable.
This procedure reads the type descriptor returns it to the user.
This procedure can also determine the name of a variable; the heap
index number of a heap variable; and other important information.
Once the type of the data has been determined, the data portion
can be read using the CMSV_RDATA procedure.
CMSV_RVTYPE should recognize and correctly return type descriptor
information about all known IDL data types, as of this writing.
It should be noted that CMSV_RDATA will not necessarily be capable
of reading all of these data types, but the description of the
data should still be readable. Users can then use this
information to print a summary of the file contents for example.
The type information are normally returned in the SIZE parameter,
which gives the IDL variable type, and the dimensions of the
variable just as the IDL built-in function SIZE() would do.
However, in the case of structures, there is much more information
to convey. To assist the user a blank template structure is
returned in the keyword parameter TEMPLATE, which they can then
pass on to CMSV_RDATA.
Users should be aware of structure and class name clashes. The
problem arises because CMSV_RVTYPE must actually instantiate any
named structures or classes in the file. If these named
structures clash with the definitions of the structures on the
user's local computer, then an error will result. To prevent
this, the user can use the SUFFIX keyword. If the SUFFIX keyword
contains a string, then this string is appended to any structure
names discovered in the save file, before instantiation. Thus, as
long as the suffix is a unique string, there will be no clashes
with local structure definitions. Users are advised to pick a
different suffix for *each* save file that they open.
CMSV_RVTYPE also provides some diagnostic information about the
variable. Users can pass the NAMED_STRUCTS and NAMED_CLASSES
keywords in order to discover what named structures, classes and
superclasses are stored in the save file (this is especially
useful with the NO_TYPE keyword). Since the contents of
NAMED_STRUCTS and NAMED_CLASSES are not destroyed, but appended to
instead, users are advised to clear these variables when opening
each new file.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure can read data from a byte array, a file unit, or
both. In fact, this procedure is designed to implement "lazy"
reading from a file, which is to say, it normally reads from a
byte array of data. However, if the requested data goes beyond
the end of the byte array, more data is read from the file on
demand. This way the user gets the benefit of fast memory access
for small reads, but guaranteed file access for large reads.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
NAME - upon return, the identifier of the variable. For named
variables, NAME is a string. For heap variables, NAME is
an integer heap index.
SIZE - upon return, an integers array describing the variable type
and size, in the same format as returned by the built-in
function SIZE.
KEYWORDS:
TEMPLATE - upon return, if the variable is a structure, TEMPLATE
will contain a single blank template structure, which
can be used in calls to CMSV_RDATA.
NO_CREATE - if set, then do not create any template structures
(saves execution time and structure name clashes).
NO_TYPE - if set, do not read type information. CMSV_RVTYPE
returns only the variable NAME or heap index.
HEAP - if set, then read the variable type assuming it is a heap
variable (a HEAP_DATA record).
SYSTEM - if set, then read the variable type assuming it is a
system variable (a SYSTEM_VARIABLE record).
SUFFIX - a scalar string, the suffix to be appended to any
structure names to force them to be unique.
STRUCTURE_NAME - upon return, if the variable is a named
structure, STRUCTURE_NAME will contain the name
of the structure as a string.
NAMED_CLASSES /
NAMED_STRUCTS - upon input, this keyword should contain an
undefined or a string array value.
If the variable contains any named structure/class
definitions, CMSV_RVTYPE will append those names
upon return, including any enclosed structures or
superclasses.
UNIT - a file unit. If a library routine reads to the end of
BLOCK, or if BLOCK is undefined, then this file UNIT will
be accessed for more data. If undefined, then BLOCK must
contain the entire file in memory.
OFFSET - the file offset of byte zero of BLOCK. Default: 0
(OFFSET is not used by this routine at this time)
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_rvtype.pro,v 1.11 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_rvtype.pro)
NAME:
CMSV_TEST
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Test the CMSVLIB library
CALLING SEQUENCE:
CMSV_TEST, FILENAME, USER_VALUE=UVALUE
DESCRIPTION:
CMSV_TEST performs a standard test of the CMSVLIB library. It
reads and writes a save file using several different methods in an
attempt to test the different ways that the library can be used.
The test procedure can be used to verify that the library is
functioning properly.
By default, this procedure provides standard values to be written,
but the user can provide one of them with the USER_VALUE keyword.
If the user's data contains pointers, they must expect tests
listed under CMSVREAD and CMSVWRITE to fail.
By default the file is written in the current directory, but this
can be changed with the FILENAME parameter.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
INPUTS:
FILENAME - a scalar string, the output path.
Default: 'CMSVTEST.SAV' in current directory
KEYWORDS:
USER_VALUE - any IDL variable to be saved, in place of variable
"C" in the test.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Resolve all routines at start, and add VMS keyword, 14 Feb 2001, CM
Make version checks with correct precision, 19 Jul 2001, CM
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_test.pro,v 1.8 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_test.pro)
NAME:
CMSV_WDATA
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write SAVE-formatted data variable record to output block or file
CALLING SEQUENCE:
CMSV_WDATA, BLOCK, POINTER, DATA, UNIT=UNIT, TEMPORARY=TEMPORARY, $
PTR_INDEX=PTR_INDEX, PTR_DATA=PTR_DATA, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_WDATA writes the data portion of an IDL SAVE variable record.
An IDL variable is stored in two components: the type descriptor
which describes the name, type, and dimensions of the variable;
and the data record, which contains the raw data of the variable.
This procedure writes the raw data to the output. The initial
type descriptor portion of the record must have already been
writtenusing the CMSV_WVTYPE procedure.
Under normal circumstances a user will write variable or heap data
using the CMSV_WREC procedure.
CMSV_WDATA supports the following variable types:
BYTE(1),INT(2),LONG(3) - integer types
UINT(12),ULONG(13),LONG64(14),ULONG64(15) - integer types (IDL >5.2 only)
FLOAT(4),DOUBLE(5),COMPLEX(6),DCOMPLEX(9) - float types
STRING(7) - string type
STRUCT(8) - structure type
POINTER(10) - pointer type - SEE BELOW
NOT SUPPORTED - OBJ(11) - object reference type - NOT SUPPORTED
Arrays and structures containing any of the supported types are
supported (including structures within structures).
The caller must specify in the DATA parameter, the data to be
written to output. The variable passed as DATA must have the same
type and dimensions as passed to CMSV_WVTYPE.
Unlike most of the other output routines, this procedure is able
to send its output to a file rather than to the BLOCK buffer. If
the UNIT keyword is specified then output is sent to that file
UNIT, after any pending BLOCK data is first sent. Users should
note that after such operations, the BLOCK POINTER and OFFSET
parameters may be modified (ie reset to new values).
See CMSV_WREC for instructions on how to write heap data.
[ This code assumes the record header and type descriptor have
been written with CMSV_WREC and CMSV_WVTYPE. ]
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array or a file. If the UNIT
keyword is specified then file is sent to the specified unit
number rather than to the buffer BLOCK. However, the intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
DATA - the data to be written, of any save-able data type.
KEYWORDS:
TEMPORARY - if set, then the input DATA are discarded after being
written, as a memory economy provision.
PTR_INDEX - a heap index array for the data being written, if any
heap data records have been written.
Default: no pointers are written
PTR_DATA - an array of pointers, pointing to the heap values being
written.
Default: no pointers are written
UNIT - a file unit. If specified then data are directed to the
file unit rather than to the buffer BLOCK.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_wdata.pro,v 1.8 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_wdata.pro)
NAME:
CMSV_WRAW
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write raw SAVE data to output block
CALLING SEQUENCE:
CMSV_WRAW, BLOCK, POINTER, DATA, UNIT=UNIT, $
STRING=STRING, LONG=LONG, BYTE=BYTE, TYPE=TYPE, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
This procedure writes raw integer or string data to an IDL SAVE
block in memory. This is the lowest level writing function in the
library, intended for developers who are investigating new and
existing SAVE file formats.
The data to be written is specified by the DATA parameter. The
data must be of type BYTE, LONG or STRING, and the type is
determined automatically from the data itself. [ The mnemonic
STRING LONG and BYTE keywords are accepted for programming clarity
but ignored. ]
This procedure accepts but currently ignores the UNIT keyword. It
is the caller's responsibility to write the BLOCK data to disk
when appropriate.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array only. The intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be written is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be written
from BLOCK. CMSVLIB routines will automatically advance
the pointer.
DATA - the data to be written. Must of type STRING, BYTE or LONG.
KEYWORDS:
LONG - ignored (to be used for clarity)
BYTE - ignored (to be used for clarity)
STRING - ignored (to be used for clarity)
UNIT - a file unit. Currently ignored.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_wraw.pro,v 1.6 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_wraw.pro)
NAME:
CMSV_WREC
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write SAVE-formatted record header to output block or file
CALLING SEQUENCE:
CMSV_WDATA, BLOCK, POINTER, DATA, IDENT, UNIT=UNIT, $
INITIALIZE=INITIALIZE, NO_DATA=NO_DATA, $
NO_TYPE=NO_TYPE, COMPATIBILITY=COMPAT, $
BLOCK_TYPE=BLOCK_TYPE, BLOCK_NAME=BLOCK_NAME,
NEXT_BLOCK=NEXT_BLOCK, $
[ ... EXTRA KEYWORDS ... ]
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
This procedure writes most types of IDL SAVE record, including the
header and contents. The header consists of four bytes at the
beginning of each record which indentifies the type and size of
the record. This procedure also writes the contents of certain
records, as noted below.
Users can specify the block type by passing the BLOCK_TYPE or
BLOCK_NAME keywords. The values listed in the following table are
supported. CMSV_WREC writes the contents of essentially all
record types as well. Some records do not contain any contents at
all (those entries marked with an [empty]) and thus require no
further processing.
BLOCK_TYPE BLOCK_TYPE WRITE RECORD CONTENTS WITH...
0 = 'START_MARKER' [empty]
1 = 'COMMON_BLOCK' [this procedure]
2 = 'VARIABLE' [this procedure]
3 = 'SYSTEM_VARIABLE' [this procedure]
6 = 'END_MARKER' [empty]
10 = 'TIMESTAMP' [this procedure]
12 = 'COMPILED' no published procedure
13 = 'IDENTIFICATION' [this procedure]
14 = 'VERSION' [this procedure]
15 = 'HEAP_INDEX' [this procedure]
16 = 'HEAP_DATA' [this procedure]
17 = 'PROMOTE64' [empty]
19 = 'NOTICE' [this procedure]
For records that contain variable data, the external procedures
CMSV_WVTYPE and/or CMSV_WDATA may be used, however it is not
recommended, since the record header must finally be re-written by
the user. Users can write the entire record with this procedure.
After issuing a POINT_LUN, or after writing the BLOCK to disk, the
block cache in BLOCK must be reset using the /INITIALIZE keyword.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
SPECIFIC RECORD TYPES
CMSV_WREC reads certain specific record types automatically based
on data passed in the DATA parameter.
Records of type 'VARIABLE' (2), 'SYSTEM_VARIABLE' (3) and
'HEAP_DATA' (16) require both the DATA and IDENT parameters. For
the first two record types, the IDENT parameter is the name of the
variable, as a scalar string. Variable names should be valid IDL
variable names, uppercase, and have no embedded spaces. For the
'HEAP_DATA' record type, the IDENT parameter is the heap index
value, as described below. The DATA itself can be any supported
IDL variable type (as described in CMSV_WVTYPE).
For records that accept data in the form of a structure, as listed
below, the listed structure tag entries are optional. If the user
does not provide a value, then a suitable default will be computed
by this procedure (listed in parentheses).
A record of type 'VERSION' (14) has the following structure:
{ FORMAT_VERSION: 0L, $ ; Format version number of file (5)
ARCH: '', $ ; !VERSION.ARCH of creating host
OS: '', $ ; !VERSION.OS of creating host
RELEASE: '' } ; !VERSION.RELEASE of creating host
A record of type 'TIMESTAMP' (10) has the following structure:
{ SAVE_DATE: '', $ ; Date the save file was created (SYSTIME(0))
SAVE_USER: '', $ ; User name who created file ('UNKNOWN')
SAVE_HOST: '' } ; Host name that created file ('UNKNOWN')
Save files created by IDL version 4 do not contain a timestamp
record. Under Unix this procedure will attempt to discover the
user and host names automatically.
A record of type 'IDENTIFICATION' (13) has the following
structure:
{ AUTHOR: '', $ ; Author of SAVE file ('')
TITLE: '', $ ; Title of SAVE file ('')
IDCODE: '' } ; Identifying code for SAVE file ('')
It appears that this record is not used in IDL version 5 or later.
A record of type 'COMMON_BLOCK' (1) defines a named common block
and its variables. A common block descriptor consists of an array
of strings whose first element is the common block name, and whose
remaining elements are the common block variable names. Thus, a
common block descriptor must have at least two elements. No
variable data are stored with the common block definition.
When a record of type 'NOTICE' (19) defines a notice to be
included in the save file. It is a structure with one field:
{TEXT: ''}, where TEXT is the text content of the notice.
A record of type 'HEAP_INDEX' (15) defines the heap index in a
SAVE file. The heap index specifies a list of which heap
variables are stored in the current save file. These indices are
simply numbers which identify each heap variable (i.e.,
"" would have an index of 2). The heap index can use
any numbers to identify the heap data; however it is required that
all index entries have corresponding heap data values.
WRITING HEAP DATA
If your data contains heap data and/or pointers, then users must
take special care in writing their data. Writing heap data is
actually more straightforward than reading it. There are several
steps involved which can be summarized as followed: (1) take
inventory of HEAP data; (2) write HEAP_INDEX record; (3) write one
HEAP_DATA record for each heap variable; and (4) write any other
variables using the heap index.
(1) Take inventory of heap data. Before writing any data to the
SAVE file, use the CMSV_PTRSUM procedure to discover all
pointer variables in the data set, like so:
cmsv_ptrsum, var, ptrlist
PTRLIST contains an array of any heap variables pointed to by
VAR (including structures or pointed-to variables). If
multiple variables are to be written, then the inventory must
contain the union of all heap variables.
(2) Write a HEAP_INDEX record. The heap index is an array of long
integers which identify the heap variables. In principle it
doesn't matter which integers are used, however there must be
a one-to-one correspondence between the entries in the heap
index and the heap identifiers used in the next step. In this
example a simple LINDGEN is used:
index = lindgen(n_elements(ptrlist))
cmsv_wrec, block, pointer, index, block_name='HEAP_INDEX', $
offset=offset
(3) Write one HEAP_DATA record for each heap variable. Issue one
CMSV_WREC call for each entry in PTRLIST, as follows for the
ith heap variable:
cmsv_wrec, block, pointer, ptrlist(i), block_name='HEAP_DATA', $
ptr_index=index, ptr_data=ptrlist, offset=offset
Note that the PTR_INDEX and PTR_DATA keywords are required
because heap data may itself contain pointers. The PTR_INDEX
and PTR_DATA keywords enable the CMSV_WREC procedure to write
appropriate descriptors when it encounters pointers.
(4) Write remaining data. For the ith variable, use:
cmsv_wrec, block, pointer, var(i), name(i), block_name='VARIABLE',$
ptr_index=index, ptr_data=ptrlist, offset=offset
As above, using the PTR_INDEX and PTR_DATA keywords will allow
the CMSV_WREC procedure to write the appropriate data.
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array or a file. If the UNIT
keyword is specified then file is sent to the specified unit
number rather than to the buffer BLOCK. However, the intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be read is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be read
from BLOCK. CMSVLIB routines will automatically
advance the pointer.
DATA - the record contents to be written, as describe above.
IDENT - for record types 'VARIABLE' (2) and 'SYSTEM_VARIABLE' (3),
the name of the variable as a scalar string. For record
type 'HEAP_DATA' (16), the heap index identifier as a
scalar long integer.
KEYWORDS:
BLOCK_NAME - a scalar string specifying the record type, as
described above. The BLOCK_TYPE keyword takes
precedence over BLOCK_NAME.
BLOCK_TYPE - a scalar integer specifying the record type, as
described above.
NEXT_BLOCK - if specified, the file offset of the next record
location.
Default: the offset will be computed automatically.
INITIALIZE - if the keyword is set, then the BLOCK is emptied and
the POINTER is reset before any new data is written.
NO_TYPE - if set, no type descriptor or data are written for
variable records.
NO_DATA - if set, no data are written for variable records.
TEMPORARY - if set, then the input DATA are discarded after being
written, as a memory economy provision.
PTR_INDEX - a heap index array for the data being written, if any
heap data records have been written.
Default: no pointers are written
PTR_DATA - an array of pointers, pointing to the heap values being
written.
Default: no pointers are written
UNIT - a file unit. If specified then data are directed to the
file unit rather than to the buffer BLOCK.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
COMPATIBILITY - a string, which describes the format to be used in
the output file. Possible values are:
'IDL4' - format of IDL version 4;
'IDL5' - format of IDL versions 5.0-5.3;
'IDL6' - not supported yet, for versions 5.4-above;
'RIVAL1' - same as 'IDL5', plus a directory entry is
written to the file.
Note that files written in IDL5 format may still be
readable by IDL v.4.
Default: 'IDL5'
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
Added NOTICE record type, 09 Jun 2003, CM
$Id: cmsv_wrec.pro,v 1.9 2003/06/28 22:21:07 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_wrec.pro)
NAME:
CMSV_WVTYPE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Write variable type information to output block
CALLING SEQUENCE:
CMSV_WVTYPE, BLOCK, DATA, IDENT, $
HEAP=HEAP, SYSTEM=SYSTEM, UNIT=UNIT, $
OFFSET=OFFSET, STATUS=STATUS, ERRMSG=ERRMSG
DESCRIPTION:
CMSV_WVTYPE writes the type portion of an IDL SAVE variable
record. An IDL variable is stored in two components: the type
descriptor which describes the name, type, and dimensions of the
variable; and the data record, which contains the raw data of the
variable. This procedure writes the type descriptor based on a
variable passed by the user. Once the type descriptor has been
written, the data portion can be written using the CMSV_WDATA
procedure.
CMSV_WVTYPE should recognize and correctly output type descriptors
for all currently known IDL data types, except for object
references. Type information is inferred from the DATA parameter
passed by the user.
Heap data is a special case, since the data itself are stored
separately from the pointer in the SAVE file. Three steps must be
satisfied: a HEAP_INDEX record must be written; a valid HEAP_DATA
record must be written containing a type descriptor (written with
this procedure) and the heap data; and the named pointer itself
must be written.
==================================================================
Research Systems, Inc. has issued a separate license intended
to resolve any potential conflict between this software and the
IDL End User License Agreement. The text of that license
can be found in the file LICENSE.RSI, included with this
software library.
==================================================================
BLOCK, POINTER, OFFSET
This procedure writes data to a byte array only. The intent is
for users to accumulate a significant amount of data in a BLOCK
and then write it out with a single call to WRITEU. Users should
be aware that the block can be larger than the buffered data, so
they should use something like the following:
WRITEU, UNIT, BLOCK(0:POINTER-1)
When library routines do indeed write buffered BLOCK data to disk,
they will appropriately reset the BLOCK and POINTER. Namely,
BLOCK will be reset to empty, and POINTER will be reset to zero.
OFFSET will be advanced the according number of bytes.
The terminology is as follows: BLOCK is a byte array which
represents a portion of, or an entire, IDL SAVE file. The block
may be a cached portion of an on-disk file, or an entire in-memory
SAVE file. POINTER is the current file pointer within BLOCK
(i.e., the next byte to be written is BLOCK[POINTER]). Hence, a
POINTER value of 0 refers to the start of the block. OFFSET is
the file offset of the 0th byte of BLOCK; thus "POINT_LUN,
OFFSET+POINTER" should point to the same byte as BLOCK[POINTER].
The following diagram shows the meanings for BLOCK, POINTER and
OFFSET schematically:
0 <- OFFSET -> |
FILE |----------------|------*--------|--------->
BLOCK |------*--------|
0 ^ POINTER
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
BLOCK - a byte array, a cache of the SAVE file. Users will
usually not access this array directly. Users are advised
to clear BLOCK after calling POINT_LUN or writing the
block to disk.
POINTER - a long integer, a pointer to the next byte to be written
from BLOCK. CMSVLIB routines will automatically advance
the pointer.
DATA - the data to be written, of any save-able data type.
IDENT - for variables, the name of the variable as a string; for
heap data, the heap index as an integer.
KEYWORDS:
HEAP - if set, the data is treated as heap data, and IDENT must be
an integer heap index.
SYSTEM - if set, the data is assumed to be a system variable.
UNIT - a file unit. Currently ignored.
OFFSET - the file offset of byte zero of BLOCK.
Upon output, if the file pointer is advanced, OFFSET will
also be changed.
(OFFSET is not currently used by this routine)
Default: 0
STATUS - upon return, this keyword will contain 1 for success and
0 for failure.
ERRMSG - upon return with a failure, this keyword will contain the
error condition as a string.
EXAMPLE:
SEE ALSO:
CMRESTORE, SAVE, RESTORE, CMSVLIB
MODIFICATION HISTORY:
Written, 2000
Documented, 24 Jan 2001
Added notification about RSI License, 13 May 2002, CM
$Id: cmsv_wvtype.pro,v 1.13 2002/05/13 06:41:10 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsv_wvtype.pro)
NAME:
CMSYSTIME
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Compute seconds since Jan 1, 1970 and (Modified) Julian Days
CALLING SEQUENCE:
TIMEVAL1 = CMSYSTIME(TIMEVAL0, ...)
DESCRIPTION:
CMSYSTIME serves two functions. It computes the current time in a
fashion similar to the built-in IDL system function SYSTIME(). It
also can convert between various time representations and systems,
including a textual format.
The current time can be obtained by invoking CMSYSTIME with the
/NOW keyword (which is entirely equivalent to SYSTIME(1)).
The most substantial part of CMSYSTIME, which distinguishes it
from SYSTIME, is its ability to convert between different time
formats. CMSYSTIME recognizes can recognize and convert between
time in seconds (seconds since Jan 1, 1970 [ = SEC ]) and days
(Julian days [ = JDAY ] or "Modified" Julian days [ = MJD = JDAY -
2400000.5 ]). It can also recognize and convert between local and
GM time.
CMSYSTIME takes maximum care to preserve the full numerical
precision of the time values. It converts all values to double
precision and may return days and seconds with fractional parts.
CMSYSTIME can also represent any time textually, not just the
current time. The following textual formats are supported:
DOW MMM DD hh:mm:ss YYYY - (Default - same as SYSTIME)
DOW MMM DD YYYY hh:mm:ss.uuuuuu TTTTT - (/EXTENDED)
where DOW and MMM are the abbreviated day of week and month in
English, DD is the day of the month, YYYY is the year, hh:mm:ss is
the time in 24 hr military time, uuuuuu are additional
microseconds, TTTTT is the timezone offset (in +hhmm
representation).
CMSYSTIME accepts one parameter, the input time to be converted.
Unlike SYSTIME, the *function* of CMSYSTIME is governed by various
keywords, as summarized in the following table:
Converting from Converting to
--------------- -------------
JDAY - /FROM_JULIAN JDAY - /JULIAN
MJD - /FROM_MJD MJD - /MJD
SEC - (Default) SEC - /SECONDS
Current time - /NOW TEXT - (Default or /EXTENDED)
Local time - /FROM_LOCAL Local time - /LOCAL
GM time - (Default) GM time - (Default)
If no argument is specified, the default is to report the current
time textually in the GM time zone. CMSYSTIME automatically
determines the local time zone.
INPUTS:
TIMEVAL0 - input time, in seconds or days, as described above.
This value is ignored if the NOW keyword is set. Array
values are allowed.
KEYWORDS:
NOW - If set, TIMEVAL0 is ignored and the current time is used as
input.
FROM_JULIAN - If set, TIMEVAL0 is in Julian days.
FROM_MJD - If set, TIMEVAL0 is in Modified Julian days (MJD).
FROM_LOCAL - If set, TIMEVAL0 is in the local time zone.
If no FROM_ keywords are set, the input is assumed
to be seconds from Jan 1, 1970.
JULIAN - If set, the input is converted to Julian days upon output.
MJD - If set, the input is converted to MJD upon output.
SECONDS - If set, the input is converted to seconds from Jan
1, 1970 upon output.
LOCAL - If set, the input is converted to the local time zone.
If no "destination" keywords are set, the output is
converted to textual representation.
EXTENDED - Convert to a textual representation with additional
information, as noted above.
TIMEZONE - Upon output, the timezone offset is returned in this
keyword. The offset is time difference in seconds
between GM time and the local time, such that LOCALTIME
= GMTIME + TIMEZONE
RETURNS:
The resulting converted time(s), either as a double precision
number or a string.
EXAMPLE:
The equivalent to SYSTIME(0)
IDL> print, systime(0) & print, cmsystime(/now, /local)
Wed Jul 5 12:10:46 2000
Wed Jul 5 12:10:46 2000
The equivalent to SYSTIME(1)
IDL> print, systime(1) & print, cmsystime(/now,/seconds)
9.6277750e+08
9.6277750e+08
Comparison between local and GM time zones (I live in the Eastern
US, daylight savings)
IDL> print, cmsystime(/now,/extended)
Wed Jul 5 2000 16:13:15.659000 -0400
IDL> print, cmsystime(/now,/local,/extended)
Wed Jul 5 2000 12:13:15.664000 -0400
What day of the week was it 200 days ago? (Note, there are 86400
seconds in one day)
IDL> today = cmsystime(/now,/seconds)
IDL> print, cmsystime(today-86400L*200, /local)
Sat Dec 18 12:17:52 1999
SEE ALSO:
SYSTIME, JULDAY, CALDAT
MODIFICATION HISTORY:
Written, CM, 05 Jul 2000
Printed time zone is zero when LOCAL=0, CM, 21 Aug 2000
Corrected behavior of /MJD (Thanks to Marshall Perrin), 03 Jun 2002
$Id: cmsystime.pro,v 1.3 2002/06/07 15:33:39 craigm Exp $
(See /home/drw/idl/aux/markwardt/cmsystime.pro)
NAME:
COLOR24
PURPOSE:
The purpose of this function is to convert a RGB color triple
into the equivalent 24-bit long integer. The 24-bit integer
can be decomposed into the appropriate color by interpreting
the lowest 8 bits as red, the middle 8 bits as green, and the
highest 8 bits as blue.
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 = COLOR24(rgb_triple)
INPUTS:
RGB_TRIPLE: A three-element column or row array representing
a color triple. Or an N-by-three element array of color triples.
The values of the elements must be between 0 and 255.
KEYWORD PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To convert the color triple for the color YELLOW,
(255, 255, 0), to the hexadecimal value '00FFFF'x
or the decimal number 65535, type:
color = COLOR24([255, 255, 0])
This routine was written to be used with device-independent
color programs like GETCOLOR.
MODIFICATION HISTORY:
Written by: David Fanning, 3 February 96.
Completely revised the algorithm to accept color arrays. 19 October 2000. DWF.
(See /home/drw/idl/aux/color24.pro)
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:
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 1.0.
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 '(I5)'.
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.
POSITION: A four-element array of normalized coordinates in the same
form as the POSITION keyword on a plot. Default is
[0.88, 0.15, 0.95, 0.95] for a vertical bar and
[0.15, 0.88, 0.95, 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.
RIGHT: This puts the labels on the right-hand side of a vertical
color bar. It applies only to vertical color bars.
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.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Color bar is drawn in the current graphics window.
RESTRICTIONS:
The number of colors available on the display device (not the
PostScript device) is used unless the NCOLORS keyword is used.
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
COLORBAR, NCOLORS=100, POSITION=[0.15, 0.85, 0.95, 0.90]
MODIFICATION HISTORY:
Written by: David 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.
(See /home/drw/idl/aux/colorbar.pro)
NAME:
COLORBAR__DEFINE
PURPOSE:
The purpose of this routine is to implement a COLORBAR object
class. The ColorBar is rendered in the direct graphics system.
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:
colorbar = Obj_New("COLORBAR")
INPUTS:
All inputs to the program are via keyword parameters.
KEYWORD PARAMETERS:
Background: Background color. This is the color with which the colorbar is
erased. The default color is !P.Background.
Bottom: Bottom color index of colors allocated to colorbar.
Charsize: Character size of annotation. Default is 1.0.
Color: Color of annotation and outline. Default is !P.Color.
Font: Font to use for annotation. Default is -1, Hershey fonts.
Format: Format of annotation. Default is "(F8.2)".
Major: The number of major tick intervals. Default is 5.
Minor: The number of minor tick intervals. Default is 2.
MinusOne: Set this keyword to choose MinusOne keyword on the Congrid command
that resizes the colorbar into the window.
NColors: The number of colors allocated to colorbar. Default is (256 <
!D.N_Colors).
Neighbor: Set to indicate Nearest Neighbor sampling for Congrid. Default is
0 (Bilinear).
Position: The position of colorbar in normalized coordinates. Default for a
horizontal colorbar is [0.15, 0.88, 0.85, 0.95]. Default for a
vertical colorbar is [0.88, 0.15, 0.95, 0.85]. These defaults are
designed for a 400 by 400 window.
Range: The data range on colorbar. Default is [0, 255].
TickLen: The length of tick marks. Default is -0.1
TickV: Locations for the tick marks in data units. This is the same as
the [XY]TickV keyword. Default is to do what IDL would do
normally.
Vertical: Set this keyword if you want a vertical colorbar. Default is
horizontal.
XEraseBox: A five-element vector of X points (normalized) for erasing the
colorbar plot. Normally this keyword will not have to be used.
The program uses the plot REGION for erasing. But larger
character sizes can result in annotation going outside the
region enclosed by the plot. If that is the case, then use this
keyword along with YEraseBox to specify a larger-than-normal
erasure area. The points are sent to the POLYFILL command for
erasing.
POLYFILL, xEraseBox, yEraseBox, /Normal, Color=background
YEraseBox: A five-element vector of Y points (normalized) for erasing the
colorbar plot.
OBJECT METHODS:
Draw: This procedure method draws the colorbar in the display window. The
ERASE keyword to this method will erase the current colorbar (by
calling the ERASE method) before drawing the colorbar in the display
window.
colorbar->Draw
Erase: This procedure method erases the colorbar object in the window. It
accomplishes this by performing a POLYFILL in the background color.
This method is primarily useful for interactive graphics display
devices.
colorbar->Erase
GetProperty: This procedure method allows one to obtain the current state
of the object via the keyword parameters listed above.
colorbar->GetProperty, Range=currentRange, Title=currentTitle
Print, currentRange, currentTitle
SetProperty: This procedure method allows one to set the properties of the
colorbar object via the keywords described above. In addition,
a DRAW and ERASE keyword are provided so that the colorbar can
be immediately drawn when the new property is set.
colorbar->SetProperty, Range=[500, 15000], /Erase, /Draw
COMMON BLOCKS:
None.
SIDE EFFECTS:
The display window is not erased first.
RESTRICTIONS:
None.
EXAMPLE:
To create a colorbar, use it, then destroy it, type:
colorbar = Obj_New("COLORBAR", Title='Colorbar Values', Range=[0,1000],$
Format='(I4)')
Window
LoadCT, 5
colorbar->Draw
colorbar->SetProperty, Range=[0,500], /Erase, /Draw
Obj_Destroy, colorbar
MODIFICATION HISTORY:
Written by: David Fanning, Fanning Software Consulting,
26 November 1998.
Added Horizontal keyword to SetProperty method and fixed problem in
going from Vertical to Horizontal color bars. 29 Nov 1998. DWF.
Added LoadCT method and current color table index to object.
6 December 1998.
Fixed a bug dealing with nearest neighbor resampling. 30 Mar 1999. DWF.
Fixed a bug with how NCOLORS and BOTTOM keywords interacted.
29 Aug 1999. DWF.
10 Oct 99. Modified the program so that current plot and map coordinates
are saved and restored after the colorbar is drawn. DWF.
26 May 2000 Added {XY}TICKV capability to the draw method. This
required adding TickV to the object data structure, and to the
INIT, GetProperty and SetProperty methods.
Changed default tick length to -0.1. DWF (and Jack Saba)
(See /home/drw/idl/aux/colorbar__define.pro)
NAME:
COLORINFO
PURPOSE:
Get information about the color mode for the current IDL session.
CATEGORY:
Color utilities.
CALLING SEQUENCE:
RESULT = COLORINFO()
INPUTS:
None
OPTIONAL INPUTS:
None
KEYWORD PARAMETERS:
QUIET If set, no information is printed on-screen.
(default is to print the color information on-screen).
OUTPUTS:
RESULT A structure containing the color information
RESULT.NCOLORS => Total number of colors available
RESULT.TABLE_SIZE => Size of the color table
RESULT.VISUAL_NAME => Name of the current visual
RESULT.VISUAL_DEPTH => Bit depth of the current visual
RESULT.DECOMPOSED => Decomposed color flag
(0, 1, or 'Unknown')
OPTIONAL OUTPUTS:
None
COMMON BLOCKS:
None
SIDE EFFECTS:
If a window has not been created in this session, this routine
creates (and then deletes) a pixmap window.
RESTRICTIONS:
Only runs on X, Windows, and Macintosh displays.
Only runs under IDL 5.0 and higher.
EXAMPLE:
info = colorinfo()
MODIFICATION HISTORY:
Written by: Liam.Gumley@ssec.wisc.edu
$Id: colorinfo.pro,v 1.2 1999/07/16 18:47:49 gumley Exp $
(See /home/drw/idl/aux/colorinfo.pro)
NAME:
COLORS
PURPOSE:
Load sixteen graphics colors into the color table.
CATEGORY:
Startup utilities.
CALLING SEQUENCE:
COLORS
INPUTS:
None
OPTIONAL INPUTS:
None
KEYWORD PARAMETERS:
START Start index in the color table where the graphics
colors will be loaded (default = 0).
NAMES If set to a named variable, returns an array of color names.
VALUES If set to a named variable, returns an array of color index values.
OUTPUTS:
None
OPTIONAL OUTPUTS:
None
COMMON BLOCKS:
None
SIDE EFFECTS:
This routine modifies the color table.
RESTRICTIONS:
None
EXAMPLE:
; Display a greyscale image with color text overlaid.
device, decomposed=0
window, /free, xs = 500, ys = 500
colors, names=names
bottom = 16B
ncolors = !d.table_size - bottom
loadct, 0, bottom=bottom, ncolors=ncolors
tv, bytscl( dist(256), top=ncolors-1 ) + bottom
for i=1,8 do xyouts, 30*i, 30*i, names[i], /device, charsize=1.5, color=i
MODIFICATION HISTORY:
Written by: Liam.Gumley@ssec.wisc.edu
NOTES:
The color table assignments are as follows
Entry Color
----- -----
0 => Black
1 => Magenta
2 => Cyan
3 => Yellow
4 => Green
5 => Red
6 => Blue
7 => White
8 => Navy
9 => Gold
10 => Pink
11 => Aquamarine
12 => Orchid
13 => Gray
14 => Sky
15 => Beige
(See /home/drw/idl/aux/colors.pro)
NAME:
COLORSET
PURPOSE:
Select true color (24 bit) if available, or pseudo color (8 bit) visual
consistently on X, Windows, and Macintosh.
CATEGORY:
Startup utilities.
CALLING SEQUENCE:
COLORSET
INPUTS:
None
OPTIONAL INPUTS:
None
KEYWORD PARAMETERS:
RETAIN Specifies the default method used
for backing store when creating new windows.
0 => No backing store
1 => Server or window system performs backing store
2 => Make IDL perform backing store (DEFAULT)
DECOMPOSED Specifies the the way in which graphics
color index values are interpreted when using displays with
decomposed color (TrueColor or DirectColor visuals).
0 = > Color indices given by single 8 bit values (DEFAULT)
1 = > Color indices given by three 8 bit values
PSEUDOCOLOR If set, try selecting PseudoColor (8-bit) mode
(default is to try selecting TrueColor (24-bit) mode).
QUIET If set, no color information is printed
(default is to print the color table size, and number of colors).
OUTPUTS:
None
OPTIONAL OUTPUTS:
None
COMMON BLOCKS:
None
SIDE EFFECTS:
This routine changes the IDL visual for the rest of the IDL session.
RESTRICTIONS:
Only affects X, WIN, and MAC displays.
Only has an effect if run before any windows have been
created, and if no DEVICE commands have been executed.
EXAMPLE:
;Execute the following command immediately after IDL startup.
colorset
MODIFICATION HISTORY:
Written by: Liam.Gumley@ssec.wisc.edu
$Id: colorset.pro,v 1.5 1999/07/16 18:38:51 gumley Exp $
(See /home/drw/idl/aux/colorset.pro)
ROUTINE: color_bar
PURPOSE: draw a horizontal color bar
USEAGE: color_bar,levels,colors,pos=pos,subnorm=subnorm,title=title, $
labels=labels,digits=digits,stride=stride,
charsize=charsize,center=center $
INPUT:
levels
a vector of physical values (required)
colors
a vector of color values. If colors is not specified a
continuous spectrum of colors between colors values 1 and
!d.n_colors-2 are used.
KEYWORD INPUT:
pos
position of color bar in normal or subnormal coordinates
[xmin,ymin,xmax,ymax], if pos is not specified, CURBOX is
called to set the color bar position interactively.
if the CENTER keyword is set, the elements of POS are
interpreted as [xcen,ycen,xsize,ysize], where xcen,ycen
is the center coordinates of the color bar and xsize,ysize
are the horizontal and vertical size
if ymin eq ymax (or ysize=0 with CENTER keyword set) the
color portion of the color bar is not drawn. This option
is useful for producing a subordinate number scale in
addition to the standard color_bar scale. see example
digits
number of significant digits used in number scale label
digits=0 causes an integer format to be used. any positive value
causes a floating point format.
stride
if set, label only those intervals which have n mod stride eq 0,
where n is the number of intervals counting left to right.
subnorm
use subnormal coordinates to specify pos. subnormal coordinates
vary from 0 to 1 across the range of the last plotting window.
If not set, normalized coordinates are used.
labels a string array of labels for color values.
if nlabels eq nlevels ==> center labels under tick marks
if nlabels eq nlevels-1 ==> center labels between tick marks
otherwise ==> execution stops, error message issued
where nlabels=n_elements(labels) and nlevels=n_elements(levels)
title overall title for color bar, appears below labels
OUTPUT:
none
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
;; center custom labels under tick marks
loadct,5
!y.omargin=[15,0]
!p.multi=[0,2,2]
r=randata(50,50,s=4) & r=(r-min(r))
autorange,r,levels,colors=colors
confill,r,/noscale,levels=levels,colors=colors
confill,rotate(r,1),/noscale,levels=levels,colors=colors
confill,rotate(r,2),/noscale,levels=levels,colors=colors
confill,rotate(r,3),/noscale,levels=levels,colors=colors
!y.omargin=0
labels='10!a-'+strcompress(string(8-indgen(n_elements(levels)-1)),/rem)
title='ozone mass density (ug/m3)'
color_bar,levels,colors,labels=labels,title=title
;; show a subordinate scale
!y.omargin=[18,0]
!p.multi=[0,2,2]
loadct,5
r=randata(50,50,s=4) & r=(r-min(r))+1
autorange,r,levels,colors=colors
tvim,r & tvim,rotate(r,1) & tvim,rotate(r,2) & tvim,rotate(r,3)
!y.omargin=0
color_bar,levels,colors,title='Line Ratio', $
pos=[0.14,0.1,0.94,0.16]
color_bar,(levels)*100, title='Ozone amount',$
pos=[0.14,0.06,0.94,0.06]
;;
AUTHOR: Paul Ricchiazzi 09 Feb 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/color_bar.pro)
ROUTINE: color_bar
PURPOSE: draw a horizontal color bar
USEAGE: color_bar
INPUT:
levels
a vector of physical values (required)
colors
a vector of color values. If colors is not specified a
continuous spectrum of colors between colors values 1 and
!d.n_colors-2 are used.
KEYWORD INPUT:
pos
position of color bar in normal or subnormal coordinates
[xmin,ymin,xmax,ymax], if pos is not specified, CURBOX is
called to set the color bar position interactively.
digits
number of significant digits used in number scale label
digits=0 causes an integer format to be used. any positive value
causes a floating point format.
stride
if set, label only those intervals which have n mod stride eq 0,
where n is the number of intervals counting left to right.
subnorm
use subnormal coordinates to specify pos. subnormal coordinates
vary from 0 to 1 across the range of the last plotting window.
If not set, normalized coordinates are used.
labels a string array of labels for color values.
if nlabels eq nlevels ==> center labels under tick marks
if nlabels eq nlevels-1 ==> center labels between tick marks
otherwise ==> execution stops, error message issued
where nlabels=n_elements(labels) and nlevels=n_elements(levels)
title overall title for color bar, appears below labels
OUTPUT:
none
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
loadct,5
!y.omargin=[10,0]
!p.multi=[0,2,2]
r=randata(50,50,s=4) & r=(r-3)
levels=-9+indgen(10)
colors=findrng(20,!d.n_colors,9)
confill,r,/noscale,levels=levels,colors=colors
confill,rotate(r,1),/noscale,levels=levels,colors=colors
confill,rotate(r,2),/noscale,levels=levels,colors=colors
confill,rotate(r,3),/noscale,levels=levels,colors=colors
!y.omargin=0
labels='10!a-'+strcompress(string(8-indgen(9)),/rem)
title='ozone mass density (ug/m3)'
color_bar,levels,colors,labels=labels,title=title
; use a continuous spectrum of colors
!y.omargin=[10,0]
!p.multi=[0,2,2]
r=randata(50,50,s=4) & r=(r-3)
levels=-9+indgen(10)
colors=findrng(20,!d.n_colors,9)
tvim,r & tvim,rotate(r,1) & tvim,rotate(r,2) & tvim,rotate(r,3)
!y.omargin=0
color_bar,indgen(10),labels=labels,title=title
AUTHOR: Paul Ricchiazzi 09 Feb 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/color_bar.pro)
ROUTINE: color_frame
PURPOSE: draw a color background on which to overlay plots
USEAGE: result=color_frame(color,pos=pos,xmargin=xmargin,ymargin=ymargin)
INPUT:
color
the background color of the plot frame
KEYWORD INPUT:
pos
4 element vector specifying the lower left and upper right
normalized coordinates of the plot frame [xll,yll,xur,yur]
xmargin
2 element vector specifying the left and right margins in character
width units
ymargin
2 element vector specifying the lower and upper margins in character
height units
bg_color
back ground color used outside of plot frame
;
OUTPUT:
result
4 element vector specifying the lower left and upper right
normalized coordinates of the plot frame [xll,yll,xur,yur]
DISCUSSION:
COLOR_FRAME can be used to produce color backgrounds within plot
frames. Since COLOR_FRAME itself calls PLOT to obtain the
default frame position, it is necessary to include the NOERASE
keyword in the PLOT call that actually draws the plot. See examples.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
!p.multi=[0,1,2]
loadct,5
xx=findrng(-2.5,2.5,200)
yy=exp(-xx^2)
yc=cos(xx*10)
plot,xx,yy,pos=color_frame(50),/noerase
plot,xx,yc*yy,pos=color_frame(70),/noerase
plot,xx,yc^2*yy,pos=color_frame(90),/noerase
plot,xx,yc^3*yy,pos=color_frame(110),/noerase
;; multi-frame plot
loadct,5
!p.multi=[0,1,2]
plot,xx,yy,pos=color_frame(100,ymargin=ymulti(p,np=2)),/noerase
plot,xx,yc*yy,pos=color_frame(60,ymargin=ymulti(p)),/noerase
;; plot within a plot
loadct,5
!p.multi=0
plot,xx,yy*yc,pos=color_frame(50,bg=10),/noerase
plot,xx,yy,pos=color_frame(100,pos=boxpos(/cur)),/noerase
;; color in frame over a different background color
loadct,5
plot,xx,yy,pos=color_frame(100,bg=50),/noerase,color=255
AUTHOR: Paul Ricchiazzi 23 Feb 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/color_frame.pro)
ROUTINE: color_frame
PURPOSE: draw a color background on which to overlay plots
USEAGE: result=color_frame(color,pos=pos,xmargin=xmargin,ymargin=ymargin)
INPUT:
color
the background color of the plot frame
KEYWORD INPUT:
pos
4 element vector specifying the lower left and upper right
normalized coordinates of the plot frame [xll,yll,xur,yur]
xmargin
2 element vector specifying the left and right margins in character
width units
ymargin
2 element vector specifying the lower and upper margins in character
height units
bg_color
back ground color used outside of plot frame
;
OUTPUT:
result
4 element vector specifying the lower left and upper right
normalized coordinates of the plot frame [xll,yll,xur,yur]
DISCUSSION:
COLOR_FRAME can be used to produce color backgrounds within plot
frames. Since COLOR_FRAME itself calls PLOT to obtain the
default frame position, it is necessary to include the NOERASE
keyword in the PLOT call that actually draws the plot. When this
option is used new plots called with color_frame will not erase
the screen even when !p.multi(0)=0. Thus, in order to start a
new page the user must explicitly erase the page using the ERASE
command. See examples.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
!p.multi=[0,1,2]
loadct,5
xx=findrng(-2.5,2.5,200)
yy=exp(-xx^2)
yc=cos(xx*10)
plot,xx,yy,pos=color_frame(50),/noerase
plot,xx,yc*yy,pos=color_frame(70),/noerase
erase
plot,xx,yc^2*yy,pos=color_frame(90),/noerase
plot,xx,yc^3*yy,pos=color_frame(110),/noerase
;; multi-frame plot
loadct,5
!p.multi=[0,1,2]
plot,xx,yy,pos=color_frame(100,ymargin=ymulti(p,np=2)),/noerase
plot,xx,yc*yy,pos=color_frame(60,ymargin=ymulti(p)),/noerase
;; plot within a plot
loadct,5
polyfill,[0,1,1,0,0],[0,0,1,1,0],color=bg_color,/norm
!p.multi=0
plot,xx,yy*yc,pos=color_frame(50),/noerase
plot,xx,yy,pos=color_frame(100,pos=boxpos(/cur)),/noerase
AUTHOR: Paul Ricchiazzi 23 Feb 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/color_frame.pro)
ROUTINE: COLOR_KEY
PURPOSE: draws a numbered color scale.
NOTE: COLOR_KEY is intended to replace PUT_COLOR_SCALE
USEAGE:
COLOR_KEY,pos=pos,ysize=ysize,range=range,inc=inc,$
charsize=charsize,barwidth=barwidth,step=step,$
labels=labels,title=title,colors=colors,nbotclr=nbotclr
PURPOSE: Draws a numbered color scale
INPUT: no required input
OPTIONAL KEYWORD INPUT:
pos 2 element vector, x and y device coordinates of lower
left hand corner of color bar. If POS is not set the
color bar will be placed one character width to the
right of the lower right corner of the last defined
data window
xoff x offset of color bar from right edge of plot frame in
units of default character with. (default=1) xoff is
disabled when pos is set.
range array which contains full range of physical values,
The number scale limits are computed fron min(range) and
max(range). (default=0-255)
inc increment step of the number scale in physical units
If INC is not set the number scale increment is set
automatically
step if set to one, the color table is modified with STEP_CT.
The color scale is stepped at the number scale intervals.
colors a vector of discreet colors selected from the original
color table. In this case the original color table is
not modified and the number of elements of COLORS
is used to find the number scale increments. This
option should be used with devices that do not accept
user specified color tables (such as the Apple Laser
Writers). BEWARE: when the COLORS option is used with
TVIM's SCALE option care must be taken to ensure that
COLOR_KEY's number scale matches the quantity values.
Unlike the STEP option, this is not automatic (see
example below)
nbotclr number of reserved colors at the bottom of the color
table. these colors will not appear in the color key.
charsize character size on number scale
ysize vertical size of color bar in device units.
if ysize is negative, the abs of ysize is interpreted
as the normalized z coordinate of the top of the bar.
barwidth width of color bar (default=1)
labels a vector of strings used to label the color key levels
if not set the default color key number labels are
used. If the number of elements in LABELS is the same
as the number of elements in COLORS then the labels
will appear in the middle of a given color band
instead of at the boundary between colors.
title color scale title drawn to the right of the color key
slevels selected levels at which to mark vertical scale. If LABELS
is also set, the number of elements in LABELS should be
equal to either nsl, or nsl-1 where nsl is the number of
elements in SLEVELS. The SLEVELS input does not work when
COLORS is also specified.
rct if set, reverse direction of grey scale increase. This
keyword can be used on black & white printers to allow
large field values to be represented by dark colors.
KEYWORD OUTPUT
clevels physical values at the color key tic marks
SIDE EFFECTS:
if STEP is set COLOR_KEY calls STEP_CT to discreetize
the color scale. To return to original color table
enter STEP_CT,/OFF
EXAMPLE:
; on devices which allow user defined color tables:
loadct,0
TVIM,dist(200),/scale
COLOR_KEY,range=dist(200),inc=20,/step ; change the color scale
COLOR_KEY,range=dist(200),inc=40,/step ; change it again
; on devices with a single hard-wired color table:
d=dist(200)+20.
inc=step_size(d) ; finds good step size
dmin=fix(min(d)/inc)*inc
dmax=fix(max(d)/inc)*inc
nclrs=(dmax-dmin)/inc
colors=!p.color*indgen(nclrs)/(nclrs-1)
TVIM,colors((d-dmin)/inc),/scale,/c_map
color_key,range=[dmin,dmax],colors=colors
; draw one big color key which applies to all tvim images on frame
!p.multi=[0,2,2]
loadct,5
im1=randata(128,128,s=3)
im2=rotate(im1,5)
im3=rotate(im1,7)
im4=rotate(im1,2)
range=[min(im1,max=mx),mx]
!x.omargin=[0,20]
tvim,im1,range=range
tvim,im2,range=range
tvim,im3,range=range
tvim,im4,range=range
color_key,range=range,xoff=10,ysize=-.97
; logarithmic scales
im=randata(128,128)
im=abs(im) & im=3*(im/max(im) > .001)
tvim,im,/rmarg ; here we assume im is the log10 of some plot quantity.
ndec=3 ; number of decades
slevels=[1.] ; starting value
for i=0,ndec-1 do slevels=[slevels,(findgen(9)+2)*10.^i]
slevels=alog10(slevels)
labels=strarr(n_elements(slevels))
labels(indgen(ndec+1)*9)=string(f='("10!a",i1,"!b")',indgen(ndec+1))
color_key,range=im,slevels=slevels,labels=labels
AUTHOR: Paul Ricchiazzi jan93
Earth Space Research Group, UCSB
REVISIONS:
20sep93: put in LABELS option
21sep93: use pure white blankout color for postscript
22sep93: put in COLORS option
09sep96: put in SLEVELS option
(See /home/drw/idl/bin/color_key.pro)
ROUTINE: COLOR_KEY
PURPOSE: draws a numbered color scale.
NOTE: COLOR_KEY is intended to replace PUT_COLOR_SCALE
NOTE: on PCs use device,decompose=0
USEAGE:
COLOR_KEY,pos=pos,ysize=ysize,range=range,inc=inc,$
charsize=charsize,barwidth=barwidth,step=step,$
labels=labels,title=title,colors=colors,nbotclr=nbotclr
PURPOSE: Draws a numbered color scale
INPUT: no required input
OPTIONAL KEYWORD INPUT:
pos 2 element vector, x and y device coordinates of lower
left hand corner of color bar. If POS is not set the
color bar will be placed one character width to the
right of the lower right corner of the last defined
data window
xoff x offset of color bar from right edge of plot frame in
units of default character with. (default=1) xoff is
disabled when pos is set.
range array which contains full range of physical values,
The number scale limits are computed fron min(range) and
max(range). (default=0-255)
inc increment step of the number scale in physical units
If INC is not set the number scale increment is set
automatically
step if set to one, the color table is modified with STEP_CT.
The color scale is stepped at the number scale intervals.
colors a vector of discreet colors selected from the original
color table. In this case the original color table is
not modified and the number of elements of COLORS
is used to find the number scale increments. This
option should be used with devices that do not accept
user specified color tables (such as the Apple Laser
Writers). BEWARE: when the COLORS option is used with
TVIM's SCALE option care must be taken to ensure that
COLOR_KEY's number scale matches the quantity values.
Unlike the STEP option, this is not automatic (see
example below)
nbotclr number of reserved colors at the bottom of the color
table. these colors will not appear in the color key.
charsize character size on number scale
ysize vertical size of color bar in device units.
if ysize is negative, the abs of ysize is interpreted
as the normalized z coordinate of the top of the bar.
barwidth width of color bar (default=1)
labels a vector of strings used to label the color key levels
if not set the default color key number labels are
used. If the number of elements in LABELS is the same
as the number of elements in COLORS then the labels
will appear in the middle of a given color band
instead of at the boundary between colors.
title color scale title drawn to the right of the color key
slevels selected levels at which to mark vertical scale. If LABELS
is also set, the number of elements in LABELS should be
equal to either nsl, or nsl-1 where nsl is the number of
elements in SLEVELS. The SLEVELS input does not work when
COLORS is also specified.
rct if set, reverse direction of grey scale increase. This
keyword can be used on black & white printers to allow
large field values to be represented by dark colors.
KEYWORD OUTPUT
clevels physical values at the color key tic marks
SIDE EFFECTS:
if STEP is set COLOR_KEY calls STEP_CT to discreetize
the color scale. To return to original color table
enter STEP_CT,/OFF
EXAMPLE:
; on devices which allow user defined color tables:
loadct,0
TVIM,dist(200),/scale
COLOR_KEY,range=dist(200),inc=20,/step ; change the color scale
COLOR_KEY,range=dist(200),inc=40,/step ; change it again
; on devices with a single hard-wired color table:
d=dist(200)+20.
inc=step_size(d) ; finds good step size
dmin=fix(min(d)/inc)*inc
dmax=fix(max(d)/inc)*inc
nclrs=(dmax-dmin)/inc
colors=!p.color*indgen(nclrs)/(nclrs-1)
TVIM,colors((d-dmin)/inc),/scale,/c_map
color_key,range=[dmin,dmax],colors=colors
; draw one big color key which applies to all tvim images on frame
!p.multi=[0,2,2]
loadct,5
im1=randata(128,128,s=3)
im2=rotate(im1,5)
im3=rotate(im1,7)
im4=rotate(im1,2)
range=[min(im1,max=mx),mx]
!x.omargin=[0,20]
tvim,im1,range=range
tvim,im2,range=range
tvim,im3,range=range
tvim,im4,range=range
color_key,range=range,xoff=10,ysize=-.97
; logarithmic scales
im=randata(128,128)
im=abs(im) & im=3*(im/max(im) > .001)
tvim,im,/rmarg ; here we assume im is the log10 of some plot quantity.
ndec=3 ; number of decades
slevels=[1.] ; starting value
for i=0,ndec-1 do slevels=[slevels,(findgen(9)+2)*10.^i]
slevels=alog10(slevels)
labels=strarr(n_elements(slevels))
labels(indgen(ndec+1)*9)=string(f='("10!a",i1,"!b")',indgen(ndec+1))
color_key,range=im,slevels=slevels,labels=labels
AUTHOR: Paul Ricchiazzi jan93
Earth Space Research Group, UCSB
REVISIONS:
20sep93: put in LABELS option
21sep93: use pure white blankout color for postscript
22sep93: put in COLORS option
09sep96: put in SLEVELS option
(See /home/drw/idl/esrg/color_key.pro)
ROUTINE: COLOR_KEY
PURPOSE: draws a numbered color scale.
NOTE: COLOR_KEY is intended to replace PUT_COLOR_SCALE
USEAGE:
COLOR_KEY,pos=pos,ysize=ysize,range=range,inc=inc,$
charsize=charsize,barwidth=barwidth,step=step,$
labels=labels,title=title,colors=colors,nbotclr=nbotclr
PURPOSE: Draws a numbered color scale
INPUT: no required input
OPTIONAL KEYWORD INPUT:
pos 2 element vector, x and y device coordinates of lower
left hand corner of color bar. If POS is not set the
color bar will be placed one character width to the
right of the lower right corner of the last defined
data window
xoff x offset of color bar from right edge of plot frame in
units of default character with. (default=1) xoff is
disabled when pos is set.
range array which contains full range of physical values,
The number scale limits are computed fron min(range) and
max(range). (default=0-255)
inc increment step of the number scale in physical units
If INC is not set the number scale increment is set
automatically
step if set to one, the color table is modified with STEP_CT.
The color scale is stepped at the number scale intervals.
colors a vector of discreet colors selected from the original
color table. In this case the original color table is
not modified and the number of elements of COLORS
is used to find the number scale increments. This
option should be used with devices that do not accept
user specified color tables (such as the Apple Laser
Writers). BEWARE: when the COLORS option is used with
TVIM's SCALE option care must be taken to ensure that
COLOR_KEY's number scale matches the quantity values.
Unlike the STEP option, this is not automatic (see
example below)
nbotclr number of reserved colors at the bottom of the color
table. these colors will not appear in the color key.
charsize character size on number scale
ysize vertical size of color bar in device units.
if ysize is negative, the abs of ysize is interpreted
as the normalized z coordinate of the top of the bar.
barwidth width of color bar (default=1)
labels a vector of strings used to label the color key levels
if not set the default color key number labels are
used. If the number of elements in LABELS is the same
as the number of elements in COLORS then the labels
will appear in the middle of a given color band
instead of at the boundary between colors.
title color scale title drawn to the right of the color key
slevels selected levels at which to mark vertical scale. If LABELS
is also set, the number of elements in LABELS should be
equal to either nsl, or nsl-1 where nsl is the number of
elements in SLEVELS. The SLEVELS input does not work when
COLORS is also specified.
rct if set, reverse direction of grey scale increase. This
keyword can be used on black & white printers to allow
large field values to be represented by dark colors.
KEYWORD OUTPUT
clevels physical values at the color key tic marks
SIDE EFFECTS:
if STEP is set COLOR_KEY calls STEP_CT to discreetize
the color scale. To return to original color table
enter STEP_CT,/OFF
EXAMPLE:
; on devices which allow user defined color tables:
loadct,0
TVIM,dist(200),/scale
COLOR_KEY,range=dist(200),inc=20,/step ; change the color scale
COLOR_KEY,range=dist(200),inc=40,/step ; change it again
; on devices with a single hard-wired color table:
d=dist(200)+20.
inc=step_size(d) ; finds good step size
dmin=fix(min(d)/inc)*inc
dmax=fix(max(d)/inc)*inc
nclrs=(dmax-dmin)/inc
colors=!p.color*indgen(nclrs)/(nclrs-1)
TVIM,colors((d-dmin)/inc),/scale,/c_map
color_key,range=[dmin,dmax],colors=colors
; draw one big color key which applies to all tvim images on frame
!p.multi=[0,2,2]
loadct,5
im1=randata(128,128,s=3)
im2=rotate(im1,5)
im3=rotate(im1,7)
im4=rotate(im1,2)
range=[min(im1,max=mx),mx]
!x.omargin=[0,20]
tvim,im1,range=range
tvim,im2,range=range
tvim,im3,range=range
tvim,im4,range=range
color_key,range=range,xoff=10,ysize=-.97
; logarithmic scales
im=randata(128,128)
im=abs(im) & im=3*(im/max(im) > .001)
tvim,im,/rmarg ; here we assume im is the log10 of some plot quantity.
ndec=3 ; number of decades
slevels=[1.] ; starting value
for i=0,ndec-1 do slevels=[slevels,(findgen(9)+2)*10.^i]
slevels=alog10(slevels)
labels=strarr(n_elements(slevels))
labels(indgen(ndec+1)*9)=string(f='("10!a",i1,"!b")',indgen(ndec+1))
color_key,range=im,slevels=slevels,labels=labels
AUTHOR: Paul Ricchiazzi jan93
Earth Space Research Group, UCSB
REVISIONS:
20sep93: put in LABELS option
21sep93: use pure white blankout color for postscript
22sep93: put in COLORS option
09sep96: put in SLEVELS option
(See /home/drw/idl/old.esrg/color_key.pro)
ROUTINE: color_pal AUTHOR: Terry Figel, ESRG, UCSB 10-21-92 CALLING SEQUENCE: color_pal PURPOSE: Displays Color palette in a seperate window
(See /home/drw/idl/esrg/color_pal.pro)
ROUTINE: color_pal AUTHOR: Terry Figel, ESRG, UCSB 10-21-92 CALLING SEQUENCE: color_pal PURPOSE: Displays Color palette in a seperate window
(See /home/drw/idl/old.esrg/color_pal.pro)
ROUTINE: compass
USEAGE compass, lat0,lon0,alat,alon,rng,az
compass, lat0,lon0,rng,az,alat,alon,/to_latlon
PURPOSE: Given the geographical coordinates of an array of points
on the on the earth's surface, compute the great-circle
distance and compass heading from the central point.
Distances and azimuth angles about the central point are
provided in KM and Degrees.
If TO_LATLON is set, convert the specified range and
azimuth values to lat, lon coordinates
INPUT:
lat0 geographic latitude (degrees) of central point
lon0 geographic longitude (degrees) of central point
INPUT/OUTPUT
alat geographic latitudes
alon geographic longitudes
rng great circle distances (km) from (lat0,lon0) to (alat,alon)
az azimuth angles (degrees), azimuth is measured clockwise
from due north (compass heading)
KEYWORD INPUT:
to_latlon if set, rng, az input converted to lat, lon
EXAMPLE:
;; plot family of great circles passing though lat,lon=(0,0)
rng=findrng(0,2*!pi*6371.2,400)
map_set,/cyl,/cont,/grid
for az=0,90,15 do begin &$
compass,0,0,rng,az,alat,alon,/to_latlon & oplot,alon,alat & endfor
;; find the range and az of Janus Island from Palmer Station
lat0=-64.767 & lon0=-64.067 & alat=-64.78 & alon=-64.11
compass,lat0,lon0,alat,alon,rng,az
compass,lat0,lon0,rng,az,nlat,nlon,/to_latlon
print,f='(6a13)','alat','alon','rng','az','nlat','nlon' &$
print,alat,alon,rng,az,nlat,nlon
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/compass.pro)
ROUTINE: compass
USEAGE compass, lat0,lon0,alat,alon,rng,az
compass, lat0,lon0,rng,az,alat,alon,/to_latlon
PURPOSE: Given the geographical coordinates of an array of points
on the on the earth's surface, compute the great-circle
distance and compass heading from the central point.
Distances and azimuth angles about the central point are
provided in KM and Degrees.
If TO_LATLON is set, convert the specified range and
azimuth values to lat, lon coordinates
INPUT:
lat0 geographic latitude (degrees) of central point
lon0 geographic longitude (degrees) of central point
INPUT/OUTPUT
alat geographic latitudes
alon geographic longitudes
rng great circle distances (km) from (lat0,lon0) to (alat,alon)
az azimuth angles (degrees), azimuth is measured clockwise
from due north (compass heading)
KEYWORD INPUT:
to_latlon if set, rng, az input converted to lat, lon
EXAMPLE:
;; plot family of great circles passing though lat,lon=(0,0)
rng=findrng(0,2*!pi*6371.2,400)
map_set,/cyl,/cont,/grid
for az=0,90,15 do begin &$
compass,0,0,rng,az,alat,alon,/to_latlon & oplot,alon,alat & endfor
;; find the range and az of Janus Island from Palmer Station
lat0=-64.767 & lon0=-64.067 & alat=-64.78 & alon=-64.11
compass,lat0,lon0,alat,alon,rng,az
compass,lat0,lon0,rng,az,nlat,nlon,/to_latlon
print,f='(6a13)','alat','alon','rng','az','nlat','nlon' &$
print,alat,alon,rng,az,nlat,nlon
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/compass.pro)
ROUTINE: confill
PURPOSE: display a contour plot with filled contours
USEAGE: confill,z,x,y,xrange=xrange,yrange=yrange,charsize=charsize,$
title=title,stitle=stitle,xtitle=xtitle,ytitle=ytitle,$
aspect=aspect,colors=colors,range=range,nlevels=nlevels,$
rmarg=rmarg,pcharsize=pcharsize,lcharsize=lcharsize,$
c_thick=c_thick,c_label=c_label,c_charsize=c_charsize,$
c_orientation=c_orientation,c_spacing=c_spacing,$
downhill=downhill,xtype=xtype,ytype=ytype,$
c_color=c_color,labels=labels,position=position,$
levels=levels,rgb_data=rgb_data,noscale=noscale
INPUT:
z
array of field values
x
one or two dimensional array of x axis points
y
one or two dimensional array of y axis points
IF z,x, and y are all one dimensional vectors and all the same
size, it is assumed that irregularly grided data is being
supplied. In this case the routine TRIANGULATE is called to get
the Delaunay triangulation of the data. The triangulation info
is then passed on to CONTOUR
KEYWORD INPUT:
title
plot title
xtitle
x axis title
ytitle
y axis title
stitle
color key title (drawn to the right of color scale)
noscale
if set, no color key will be drawn
rmarg
right margin expansion factor to provide more room for extra wide
color scale annotation (default=1)
xrange
x axis range. (default = [0,x_dimension-1])
yrange
y axis range. (default = [0,y_dimension-1])
range
two element vector indicating physical range over which
to distribute contour levels.
nlevels
maximum number of contour levels. If LEVELS is not set the
actual number of contour levels is determined automatically by
AUTORANGE. NLEVELS sets the maximum allowed number of levels,
the actual number of levels may be less.
levels
contour level values (vector). The default contour levels are
set by AUTORANGE. The automatically selected levels chosen by
AUTORANGE can be retrieved by setting LEVELS to a named variable
which is initially undefined or set to zero.
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set, the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies used to fill contours. The number of
color values should be one less than the number of levels. The
default colors are chosen to be uniformally distributed over the
full color table. The automatically selected colors chosen by
CONFILL are: colors=fix((!d.n_colors-2)*(1+findgen(nclr))/nclr),
where nclr=n_elements(levels)-1. If COLORS is set to a negative
number these automatically chosen colors are reversed so that dark
colors are used to represent high intensity areas.
NOTE: The default color indicies generated by CONFILL never
include color index 0 or !d.n_colors-1. These indicies are
reserved for the overall plot background and foreground colors.
For best results, color index 0 and !d.n_colors-1 should
correspond to pure black and white respectively, which is
usually the case in the predefined color tables supplied by RSI.
A predefined color table that doesn't follow this rule can be
redefined using TVLCT to put black and white in these slots,
without affecting any of the filled contours used in the CONFILL
plot: tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
NOTE: if more than 256 colors are available on the graphics device
this routine should be run without color decomposition, i.e.,
device,decomposed=0
tvim uses device,decomposed=1 to draw three color images, (tvim
should reset to device,decomposed=0 after its done)
c_label
integer array indicating which contour lines to label. For
example, c_label=[0,0,0,1,0,1] indicates that the contour lines
which correspond to levels(3) and levels(5) are to be labeled.
The number of C_LABELs should be the same as the number of
LEVELS. By default no contour lines are labeled.
c_thick
thickness of contour lines (may be a vector of values),
Default is 1.
c_color
color of contour lines (may be a scalor or vector of values).
If c_color is negative then the color of contour lines is chosen
to maximize contrast with adjacent fill colors. The default is
not to drawn contour lines. This keyword must be set to get
contour lines.
NOTE: The number of contour levels is determined automatically
if LEVELS is not set. Hence, it may not be possible to guess
how many values of LABELS, COLORS, C_LABEL, C_THICK or C_COLOR
should be specified. It is probably safer not to include these
parameters unless LEVELS is also specified.
c_orientation
If the FILL keyword is set, this keyword can be set to the angle,
in degrees counterclockwise from the horizontal, of the lines
used to fill contours. If neither C_ORIENTATION or C_SPACING are
specified, the contours are solid filled.
c_spacing
If the FILL keyword is set, this keyword can be used to control
the distance, in centimeters, between the lines used to fill the
contours.
xtype
Set this keyword to specify a logarithmic X axis.
ytype
Set this keyword to specify a logarithmic Y axis.
downhill
Set this keyword to label each contour with short, perpendicular
tick marks that point in the "downhill" direction, making the
direction of the grade readily apparent. If this keyword is set,
the contour following method is used in drawing the contours.
NOTE: Due to a bug in IDL_3.6, the concurrent use of C_LABEL and
DOWNHILL causes an IDL session crash. For this reason the
DOWNHILL option is disabled on IDL_3.6.
aspect
the x over y aspect ratio of the output image. If not set, the
aspect ratio is adjusted to fill the available plotting area.
position
specifies the lower left and upper right CONFILL frame position in
normal coordinates. When set POSITION overides the setting of
ASPECT.
pcharsize
character size of numbers along x and y axis and the title
(default is !p.charsize if non-zero, 1 otherwise)
NOTE: The character size of the x and y-axis number scale
annotation may be independently controlled by the !x.charsize or
!y.charsize system variables. For example, the x and y axis
number scale characters may be made invisible by setting these
variables to a very small non-zero number before calling CONFILL.
Remember to restore normal character sizes by setting !x.charsize
and !y.charsize to 1 or zero after the call to CONFILL.
lcharsize
character size of color key number or labels (default is
pcharsize if set, otherwise !p.charsize if non-zero, 1 otherwise)
barwidth
width of color key which appears to right of contour plot (default=1).
rgb_nodata
if set, regions with field values less then the minimum of LEVELS
or RANGE will be colored with the RGB values specified in
RGB_NODATA (a scalor or three element vector). Color index 1 is
used for the nodata color. When RGB_NODATA is set don't use
color index 1 in the COLORS input vector.
NOTE: RGB_NODATA has no effect unless either RANGE or LEVELS is
set. This is because the default contour levels are set so that
the minimum level is less than the minimum field value.
overplot if set, current field is super imposed over a previous
confill plot this option only works when z,x, and y are all one
dimensional vectors and all the same size, in which case it is
assumed that irregularly grided data is being supplied. In this
case the routine TRIANGULATE is called to get the Delaunay
triangulation of the data. The triangulation info is then passed
on to CONTOUR.
DEPENDENCIES: COLOR_KEY, AUTORANGE
SIDE EFFECTS: if RGB_NODATA is set the rgb value of color index 1
is modified
EXAMPLES:
;;
loadct,5
n=128
zz=randata(n,n,s=4)
xx=findrng([-120,-100],n)
yy=findrng([20,50],n)
confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
stitle='contour levels',c_color=-1
;;
confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
stitle='contour levels',c_color=-1,rgb_nodata=[100,100,100]
;; labeled regions
levels=-3+findgen(6)*2
labels=[' ocean',' rain!c forrest',' sand',$
' old!c snow',' real!c new!c snow']
confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
stitle='surface types',labels=labels,levels=levels,barwidth=.5
; contour irregularly grided data
loadct,5
w8x11
n=128
z=randata(n,n,s=4)
x=findgen(n)
y=findgen(n)
!p.multi=[0,1,2]
confill,z,x,y,title='Regularly Grided',c_color=-1
ii=randomu(iseed,200)*(n*n-1) ; random sample points
zz=z(ii) ; random samples
xx=ii mod n ; (zz,xx,yy are vectors)
yy=ii / n
confill,zz,xx,yy,title='Randomly Sampled',c_color=-1
oplot,xx,yy,psym=4,color=1,symsize=.4 ; show locations of sample points
; overlay three irregular regions in one confill plot
loadct,5
w8x11
n=128
z=randata(n,n,s=4)
ii=randomu(iseed,200)*(n*n-1) ; random sample points
zz=z(ii) ; random samples
xx=ii mod n ; (zz,xx,yy are vectors)
yy=ii / n
confill,zz,xx,yy,xrange=[0,300]
confill,zz^2,xx+150,yy/2,/overplot
confill,sqrt(zz>0),xx+150,70+yy/2,/over
AUTHOR: Paul Ricchiazzi 24 May 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/confill.pro)
ROUTINE: confill
PURPOSE: display a contour plot with filled contours
USEAGE: confill,z,x,y,xrange=xrange,yrange=yrange,charsize=charsize,$
title=title,stitle=stitle,xtitle=xtitle,ytitle=ytitle,$
aspect=aspect,colors=colors,range=range,nlevels=nlevels,$
rmarg=rmarg,pcharsize=pcharsize,lcharsize=lcharsize,$
c_thick=c_thick,c_label=c_label,c_charsize=c_charsize,$
c_orientation=c_orientation,c_spacing=c_spacing,$
downhill=downhill,xtype=xtype,ytype=ytype,$
c_color=c_color,labels=labels,position=position,$
levels=levels,rgb_data=rgb_data,noscale=noscale
INPUT:
z
array of field values
x
one or two dimensional array of x axis points
y
one or two dimensional array of y axis points
IF z,x, and y are all one dimensional vectors and all the same
size, it is assumed that irregularly grided data is being
supplied. In this case the routine TRIANGULATE is called to get
the Delaunay triangulation of the data. The triangulation info
is then passed on to CONTOUR
KEYWORD INPUT:
title
plot title
xtitle
x axis title
ytitle
y axis title
stitle
color key title (drawn to the right of color scale)
noscale
if set, no color key will be drawn
rmarg
right margin expansion factor to provide more room for extra wide
color scale annotation (default=1)
xrange
x axis range. (default = [0,x_dimension-1])
yrange
y axis range. (default = [0,y_dimension-1])
range
two element vector indicating physical range over which
to distribute contour levels.
nlevels
maximum number of contour levels. If LEVELS is not set the
actual number of contour levels is determined automatically by
AUTORANGE. NLEVELS sets the maximum allowed number of levels,
the actual number of levels may be less.
levels
contour level values (vector). The default contour levels are
set by AUTORANGE. The automatically selected levels chosen by
AUTORANGE can be retrieved by setting LEVELS to a named variable
which is initially undefined or set to zero.
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set, the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies used to fill contours. The number of
color values should be one less than the number of levels. The
default colors are chosen to be uniformally distributed over the
full color table. The automatically selected colors chosen by
CONFILL are: colors=fix((!d.n_colors-2)*(1+findgen(nclr))/nclr),
where nclr=n_elements(levels)-1
NOTE: The default color indicies generated by CONFILL never
include color index 0 or !d.n_colors-1. These indicies are
reserved for the overall plot background and foreground colors.
For best results, color index 0 and !d.n_colors-1 should
correspond to pure black and white respectively, which is
usually the case in the predefined color tables supplied by RSI.
A predefined color table that doesn't follow this rule can be
redefined using TVLCT to put black and white in these slots,
without affecting any of the filled contours used in the CONFILL
plot: tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
c_label
integer array indicating which contour lines to label. For example,
c_label=[0,0,0,1,0,1] indicates that the contour lines which correspond
to levels(3) and levels(5) are to be labeled. The number of C_LABELs
should be the same as the number of LEVELS. By default no contour
lines are labeled.
c_thick
thickness of contour lines (may be a vector of values), if c_thick
is set to 0 then no contour lines are drawn. Default is 0.
c_color
color of contour lines (may be a vector of values). A negative
value can be used to indicate a dividing line between contours
drawn in color 0 and levels drawn with !d.n_colors-1. In this
case the magnitude of C_COLORS indicates the last contour level
that should be colored with color value !d.n_colors-1 (usually
white), where the lowest contour level is numbered one. The
rest of the color levels will be colored with color 0 (usually
black). For example C_COLORS=-3 indicates that that the first
three contours should by colored with !d.ncolors-1 and the
remaining levels colored with color 0. Default is !p.color
NOTE: The number of contour levels is determined automatically
if LEVELS is not set. Hence, it may not be possible to guess
how many values of LABELS, COLORS, C_LABEL, C_THICK or C_COLOR
should be specified. It is probably safer not to include these
parameters unless LEVELS is also specified.
c_orientation
If the FILL keyword is set, this keyword can be set to the angle,
in degrees counterclockwise from the horizontal, of the lines
used to fill contours. If neither C_ORIENTATION or C_SPACING are
specified, the contours are solid filled.
c_spacing
If the FILL keyword is set, this keyword can be used to control
the distance, in centimeters, between the lines used to fill the
contours.
xtype
Set this keyword to specify a logarithmic X axis.
ytype
Set this keyword to specify a logarithmic Y axis.
downhill
Set this keyword to label each contour with short, perpendicular
tick marks that point in the "downhill" direction, making the
direction of the grade readily apparent. If this keyword is set,
the contour following method is used in drawing the contours.
NOTE: Due to a bug in IDL_3.6, the concurrent use of C_LABEL and
DOWNHILL causes an IDL session crash. For this reason the
DOWNHILL option is disabled on IDL_3.6.
aspect
the x over y aspect ratio of the output image. If not set, the
aspect ratio is adjusted to fill the available plotting area.
position
specifies the lower left and upper right CONFILL frame position in
normal coordinates. When set POSITION overides the setting of
ASPECT.
pcharsize
character size of numbers along x and y axis and the title
(default is !p.charsize if non-zero, 1 otherwise)
NOTE: The character size of the x and y-axis number scale
annotation may be independently controlled by the !x.charsize or
!y.charsize system variables. For example, the x and y axis
number scale characters may be made invisible by setting these
variables to a very small non-zero number before calling CONFILL.
Remember to restore normal character sizes by setting !x.charsize
and !y.charsize to 1 or zero after the call to CONFILL.
lcharsize
character size of color key number or labels (default is
pcharsize if set, otherwise !p.charsize if non-zero, 1 otherwise)
barwidth
width of color key which appears to right of contour plot (default=1).
rgb_nodata
if set, regions with field values less then the minimum of LEVELS
or RANGE will be colored with the RGB values specified in
RGB_NODATA (a scalor or three element vector). Color index 1 is
used for the nodata color. When RGB_NODATA is set don't use
color index 1 in the COLORS input vector.
NOTE: RGB_NODATA has no effect unless either RANGE or LEVELS is
set. This is because the default contour levels are set so that
the minimum level is less than the minimum field value.
overplot if set, current field is super imposed over a previous
confill plot this option only works when z,x, and y are all one
dimensional vectors and all the same size, in which case it is
assumed that irregularly grided data is being supplied. In this
case the routine TRIANGULATE is called to get the Delaunay
triangulation of the data. The triangulation info is then passed
on to CONTOUR.
DEPENDENCIES: COLOR_KEY, AUTORANGE
SIDE EFFECTS: if RGB_NODATA is set the rgb value of color index 1
is modified
EXAMPLES:
loadct,5
n=128
zz=randata(n,n,s=4)
xx=findrng([-120,-100],n)
yy=findrng([20,50],n)
confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
stitle='contour levels',c_color=-4
confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
stitle='contour levels',c_color=-4,rgb_nodata=!p.color/2
; labeled regions
levels=-3+findgen(6)*2
labels=[' ocean',' rain!c forrest',' sand',$
' old!c snow',' real!c new!c snow']
confill,zz,xx,yy,title='Plot title',xtitle='x-axis',ytitle='y-axis',$
stitle='surface types',labels=labels,levels=levels,barwidth=.5
; contour irregularly grided data
loadct,5
w8x11
n=128
z=randata(n,n,s=4)
x=findgen(n)
y=findgen(n)
!p.multi=[0,1,2]
confill,z,x,y,title='Regularly Grided',c_color=-5
ii=randomu(iseed,200)*(n*n-1) ; random sample points
zz=z(ii) ; random samples
xx=ii mod n ; (zz,xx,yy are vectors)
yy=ii / n
confill,zz,xx,yy,title='Randomly Sampled',c_color=-5
oplot,xx,yy,psym=4,color=1,symsize=.4 ; show locations of sample points
; overlay two irregular regions in one confill plot
loadct,5
w8x11
n=128
z=randata(n,n,s=4)
ii=randomu(iseed,200)*(n*n-1) ; random sample points
zz=z(ii) ; random samples
xx=ii mod n ; (zz,xx,yy are vectors)
yy=ii / n
confill,zz,xx,yy,xrange=[0,300]
confill,zz^2,xx+150,yy/2,/overplot
confill,sqrt(zz>0),xx+150,70+yy/2,/over
AUTHOR: Paul Ricchiazzi 24 May 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/confill.pro)
routine: connected
useage: connected,image,nstring,view=view
purpose: The bi-level image is searched for all pixels which are
are part a continous set of adjacent pixels. Those pixel
groupings which contain fewer than NSTRING "on" pixels are
set to zero.
input:
image a bi-level image array (2d)
nstring the number of "on" pixels required for a given cluster of
adjacent pixels to survive.
output:
image a bi-level image with islands composed of fewer than nstring
pixels removed.
EXAMPLE:
r=randata(128,128,s=2) gt 7
connected,r,3,/view
WARNING: this procedure can take a lot of time for large images.
for images larger than 64 x 64 computation times goes
something like
time=c * (NX x NY)^2
for a DecStation 5000/240, c=7.4e-8, and
a 256x256 image takes about 5 minutes.
author: Paul Ricchiazzi Nov93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/connected.pro)
routine: connected
useage: connected,image,nstring,view=view
purpose: The bi-level image is searched for all pixels which are
are part a continous set of adjacent pixels. Those pixel
groupings which contain fewer than NSTRING "on" pixels are
set to zero.
input:
image a bi-level image array (2d)
nstring the number of "on" pixels required for a given cluster of
adjacent pixels to survive.
output:
image a bi-level image with islands composed of fewer than nstring
pixels removed.
EXAMPLE:
r=randata(128,128,s=2) gt 7
connected,r,3,/view
WARNING: this procedure can take a lot of time for large images.
for images larger than 64 x 64 computation times goes
something like
time=c * (NX x NY)^2
for a DecStation 5000/240, c=7.4e-8, and
a 256x256 image takes about 5 minutes.
author: Paul Ricchiazzi Nov93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/connected.pro)
ROUTINE: contlev
PURPOSE: find a good set of contour levels
USEAGE: result=contlev(a)
INPUT:
a an array
KEYWORD INPUT:
maxlev maximum number of levels on the plot. Setting this keyword to,
say, 5 does not mean you will get 5 levels. It just means no
more than 5 levels will be generated.
OUTPUT:
result a vector of contour levels
EXAMPLE: contour,dist(20),levels=contlev(dist(20),maxlev=8)
author: Paul Ricchiazzi feb94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/contlev.pro)
ROUTINE: contlev
PURPOSE: find a good set of contour levels
USEAGE: result=contlev(a)
INPUT:
a an array
KEYWORD INPUT:
maxlev maximum number of levels on the plot. Setting this keyword to,
say, 5 does not mean you will get 5 levels. It just means no
more than 5 levels will be generated.
OUTPUT:
result a vector of contour levels
EXAMPLE: contour,dist(20),levels=contlev(dist(20),maxlev=8)
author: Paul Ricchiazzi feb94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/contlev.pro)
ROUTINE: contour_plot PURPOSE: Compute contours of image generated by CDS observing sequence INT_DIST and places them in a file. USEAGE: result = contour_plot(image,c_val) INPUT: image a 2D array c_val value at which contours are to be drawn OUTPUT: result contains the contour x and y values in normalised coordinates AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/old.esrg/contour_plot.pro)
NAME:
CONV_UNIX_VAX
PURPOSE:
To convert Unix IDL data types to Vax IDL data types.
EXPLANATION:
CONV_UNIX_VAX assumes the Unix IDL data type is IEEE standard in either
big-endian or little-endian format.
CALLING SEQUENCE:
CONV_UNIX_VAX, variable, [ SOURCE_ARCH = ]
PARAMETERS:
variable - The data variable to be converted. This may be a scalar
or an array. Valid datatypes are integer, longword,
floating point, and double precision. The result of the
conversion is passed back in the original variable.
OPTIONAL INPUT KEYWORD:
SOURCE_ARCH = name (string) of source architecture
if using this function on a VAX, otherwise
!VERSION.ARCH is used to determine the conversion.
**If run on a VAX, the default is to assume the source to be
a little-endian machine with IEEE floating point
(e.g. MIPSEL or Alpha***).
RESTRICTIONS:
Requires that data be from IEEE standard Unix machines
(e.g. SUN, MIPSEL, or Alpha).
EXAMPLE:
Read a 100 by 100 matrix of floating point numbers from a data
file created on a Sun. Then convert the matrix values into
VAX format.
IDL> openr,1,'vax_float.dat
IDL> data = fltarr(100,100)
IDL> forrd,1,data
IDL> CONV_UNIX_VAX,data,SOURCE_ARCH='sparc'
MODIFICATION HISTORY:
Version 1 By John Hoegy 13-Jun-88
04-May-90 - WTT: Created CONV_UNIX_VAX from VAX2SUN,
reversing floating point procedure.
Modified P. Keegstra September 1994
Implemented MIPSEL and ALPHA architecture,
distinguishing VMS and OSF
Modified P. Keegstra February 1995
Added 386 PC based architectures
If since V5.1 then VMS is always little endian June 1998
Convert to IDL V5.0 W. Landsman June 1998
(See /home/drw/idl/aux/markwardt/conv_unix_vax.pro)
NAME:
cor2d
PURPOSE:
computes the residual shifts of the images using 2d corelations
EXPLANATION:
CALLING SEQUENCE:
COR2D [ , NSTART=NSTART, NEND=NEND, NREF=NREF, $
XNAME=XNAME, YNAME=YNAME, $
NSTEP=NSTEP, SCALE=SCALE, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
DARKN=DARKN, FLATN=FLATN, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3, $
XYFLAT=XYFLAT, XYCORR=XYCORR ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
NSTART = number of the first raw image to be processed
NEND = number of the last raw image to be processed
NREF = number of the reference file
XNAME = name of the file with approx. values of shifts along X-axis
YNAME = name of the file with approx. values of shifts along y-axis
NSTEP = step between the images (normaly 1, it means all images between begname//nstart//extname and begname//nend//extname)
SCALE = megnification factor for calculations of the shifting (should be keept 20 or greater)
SHIFTNAME = name of the file with final values of of shifts along both axes
BEGNAME = prefix of the names of the raw images
EXTNAME = extension of the names of the raw images (normaly .fit)
DARKNAME= name of the averaged dark image
FLATNAME= name of the averaged flat image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
XYFLAT = X1,Y1,X2,Y2: 4-element vector of coord. of the lower-left anr upper-right corners of the flattened area [de. 1,100,480,480]
XYCORR = X1,Y1,X2,Y2: 4-element vector of coord. of the lower-left anr upper-right corners of the correlation area [de. 0,0,0,0]
OUTPUT:
File SHIFTNAME with calculated shifts for each image
MODIFICATION HISTORY:
Written, February 2002, Pawel Rudawy, IAUWr.
Modif. 24 Marz 2002 PR
added keyword xycorr
removed keywords x1flat...y2flat, instead added keyword xyflat
Modif. 26 Marz 2002 by PR
for no=nstart,nend do begin
xshift1(no)=round(xpoprs(no)*SCALE-7.0*SCALE*no/20000.0)
yshift1(no)=round(ypoprs(no)*SCALE-11.0*SCALE*no/20000.0)
endfor
instead of
for no=nstart,nend do begin
xshift1(no)=round(xpoprs(no)*SCALE-7.0*SCALE*(no-nstart)/20000.0)
yshift1(no)=round(ypoprs(no)*SCALE-11.0*SCALE*(no-nstart)/20000.0)
endfor
(See /home/drw/idl/pawel/Moon_position_brd_cam_step3_corr2d_YH.pro)
NAME:
cor2d
PURPOSE:
computes the residual shifts of the images using 2d corelations
EXPLANATION:
CALLING SEQUENCE:
COR2D [ , NSTART=NSTART, NEND=NEND, NREF=NREF, $
XNAME=XNAME, YNAME=YNAME, $
NSTEP=NSTEP, SCALE=SCALE, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
DARKN=DARKN, FLATN=FLATN, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
NSTART = number of the first raw image to be processed
NEND = number of the last raw image to be processed
NREF = number of the reference file
XNAME = name of the file with approx. values of shifts along X-axis
YNAME = name of the file with approx. values of shifts along y-axis
NSTEP = step between the images (normaly 1, it means all images between begname//nstart//extname and begname//nend//extname)
SCALE = megnification factor for calculations of the shifting (should be keept 20 or greater)
SHIFTNAME = name of the file with final values of of shifts along both axes
BEGNAME = prefix of the names of the raw images
EXTNAME = extension of the names of the raw images (normaly .fit)
DARKNAME= name of the averaged dark image
FLATNAME= name of the averaged flat image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
OUTPUT:
File SHIFTNAME with calculated shifts for each image
MODIFICATION HISTORY:
Written, February 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH.pro)
NAME:
cor2d
PURPOSE:
computes the residual shifts of the images using 2d corelations
EXPLANATION:
CALLING SEQUENCE:
COR2D [ , NSTART=NSTART, NEND=NEND, NREF=NREF, $
XNAME=XNAME, YNAME=YNAME, $
NSTEP=NSTEP, SCALE=SCALE, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
DARKN=DARKN, FLATN=FLATN, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
NSTART = number of the first raw image to be processed
NEND = number of the last raw image to be processed
NREF = number of the reference file
XNAME = name of the file with approx. values of shifts along X-axis
YNAME = name of the file with approx. values of shifts along y-axis
NSTEP = step between the images (normaly 1, it means all images between begname//nstart//extname and begname//nend//extname)
SCALE = megnification factor for calculations of the shifting (should be keept 20 or greater)
SHIFTNAME = name of the file with final values of of shifts along both axes
BEGNAME = prefix of the names of the raw images
EXTNAME = extension of the names of the raw images (normaly .fit)
DARKNAME= name of the averaged dark image
FLATNAME= name of the averaged flat image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
OUTPUT:
File SHIFTNAME with calculated shifts for each image
MODIFICATION HISTORY:
Written, February 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH_0.pro)
NAME: CORD2DIST USAGE: cord2dist,cordarray,distarray,limb=limb PURPOSE: to convert point co-ordinates along a loop to a linear distance from the first point in kilometres. INPUTS: CORDARRAY - input array of co-ordinates in Solar-X and Solar-Y as a 2xN array where cordarray[0,*] are the x co- ordinates, and cordarray[1,*] are the y co-ordinates and N is the number of points for which co-ordinates are given. OUTPUTS: DISTARRAY - 1xN vector containing the cumulative distance along the loop KEYWORDS: LIMB - if set, then return the height of the initial point ONLY above the solar limb. It's just a guide. There's no point in returning all the positions as a function of height above the limb, since they're not necessarily in a straight line. If they are, then you can just add on the initial height for yourself! HISTORY: DRW 1/2/01 LIMB keyword added 27/7/01 (DRW)
(See /home/drw/idl/secis/cord2dist.pro)
NAME: CORREL_COMP.PRO PURPOSE: To cross-correlate two SECIS prominence-area images and give the relative shift in the x- and y-directions. Under development. USAGE: correl_comp,prom,xmotion,ymotion INPUTS: PROM - 40x40 array, centred on the prominence in the SECIS white light images. OUTPUTS: XMOTION - the array storing the movement, in pixels, between the current frame and the last. YMOTION - similar. HISTORY: version 0.5 written 11/2/00
(See /home/drw/idl/secis/correl_comp.pro)
NAME: CORREL_GRAD.PRO PURPOSE: To cross-correlate two SECIS prominence-area images and give the relative shift in the x- and y-directions. Under development. Uses the gradients of these images. USAGE: correl_grad,prom,xmotion,ymotion INPUTS: PROM - 40x40 array, centred on the prominence in the SECIS white light images. OUTPUTS: XMOTION - the array storing the movement, in pixels, between the current frame and the last. YMOTION - similar. HISTORY: version 0.5 written 11/2/00
(See /home/drw/idl/secis/correl_grad.pro)
NAME:
CORREL_IMAGES
PURPOSE:
Compute the 2-D cross-correlation function of two images
EXPLANATION:
Computes the 2-D cross-correlation function of two images for
a range of (x,y) shifting by pixels of one image relative to the other.
CALLING SEQUENCE:
Result = CORREL_IMAGES( image_A, image_B,
[XSHIFT=, YSHIFT=, XOFFSET_B=, YOFFSET_B=, REDUCTION=,
MAGNIFICATION=, /NUMPIX, /MONITOR )
INPUTS:
image_A, image_B = the two images of interest.
OPTIONAL INPUT KEYWORDS:
XSHIFT = the + & - shift to be applied in X direction, default=7.
YSHIFT = the Y direction + & - shifting, default=7.
XOFFSET_B = initial X pixel offset of image_B relative to image_A.
YOFFSET_B = Y pixel offset, defaults are (0,0).
REDUCTION = optional reduction factor causes computation of
Low resolution correlation of bin averaged images,
thus faster. Can be used to get approximate optimal
(x,y) offset of images, and then called for successive
lower reductions in conjunction with CorrMat_Analyze
until REDUCTION=1, getting offset up to single pixel.
MAGNIFICATION = option causes computation of high resolution correlation
of magnified images, thus much slower.
Shifting distance is automatically = 2 + Magnification,
and optimal pixel offset should be known and specified.
Optimal offset can then be found to fractional pixels
using CorrMat_Analyze( correl_images( ) ).
/NUMPIX - if set, causes the number of pixels for each correlation
to be saved in a second image, concatenated to the
correlation image, so Result is fltarr( Nx, Ny, 2 ).
/MONITOR causes the progress of computation to be briefly printed.
OUTPUTS:
Result is the cross-correlation function, given as a matrix.
PROCEDURE:
Loop over all possible (x,y) shifts, compute overlap and correlation
for each shift. Correlation set to zero when there is no overlap.
MODIFICATION HISTORY:
Written, July,1991, Frank Varosi, STX @ NASA/GSFC
Use ROUND instead of NINT, June 1995, Wayne Landsman HSTX
Avoid divide by zero errors, W. Landsman HSTX April 1996
Remove use of !DEBUG W. Landsman June 1997
Subtract mean of entire image before computing correlation, not just
mean of overlap region H. Ebeling/W. Landsman June 1998
(See /home/drw/idl/bin/correl_images.pro)
NAME:
CORREL_IMAGES
PURPOSE:
Compute the 2-D cross-correlation function of two images
EXPLANATION:
Computes the 2-D cross-correlation function of two images for
a range of (x,y) shifting by pixels of one image relative to the other.
CALLING SEQUENCE:
Result = CORREL_IMAGES( image_A, image_B,
[XSHIFT=, YSHIFT=, XOFFSET_B=, YOFFSET_B=, REDUCTION=,
MAGNIFICATION=, /NUMPIX, /MONITOR )
INPUTS:
image_A, image_B = the two images of interest.
OPTIONAL INPUT KEYWORDS:
XSHIFT = the + & - shift to be applied in X direction, default=7.
YSHIFT = the Y direction + & - shifting, default=7.
XOFFSET_B = initial X pixel offset of image_B relative to image_A.
YOFFSET_B = Y pixel offset, defaults are (0,0).
REDUCTION = optional reduction factor causes computation of
Low resolution correlation of bin averaged images,
thus faster. Can be used to get approximate optimal
(x,y) offset of images, and then called for successive
lower reductions in conjunction with CorrMat_Analyze
until REDUCTION=1, getting offset up to single pixel.
MAGNIFICATION = option causes computation of high resolution correlation
of magnified images, thus much slower.
Shifting distance is automatically = 2 + Magnification,
and optimal pixel offset should be known and specified.
Optimal offset can then be found to fractional pixels
using CorrMat_Analyze( correl_images( ) ).
/NUMPIX - if set, causes the number of pixels for each correlation
to be saved in a second image, concatenated to the
correlation image, so Result is fltarr( Nx, Ny, 2 ).
/MONITOR causes the progress of computation to be briefly printed.
OUTPUTS:
Result is the cross-correlation function, given as a matrix.
PROCEDURE:
Loop over all possible (x,y) shifts, compute overlap and correlation
for each shift. Correlation set to zero when there is no overlap.
MODIFICATION HISTORY:
Written, July,1991, Frank Varosi, STX @ NASA/GSFC
Use ROUND instead of NINT, June 1995, Wayne Landsman HSTX
Avoid divide by zero errors, W. Landsman HSTX April 1996
Remove use of !DEBUG W. Landsman June 1997
Subtract mean of entire image before computing correlation, not just
mean of overlap region H. Ebeling/W. Landsman June 1998
(See /home/drw/idl/pawel/oprogramowanie_secis/wyznaczanie_residual_shifts.pro)
NAME:
CORREL_IMAGES
PURPOSE:
Compute the 2-D cross-correlation function of two images
EXPLANATION:
Computes the 2-D cross-correlation function of two images for
a range of (x,y) shifting by pixels of one image relative to the other.
CALLING SEQUENCE:
Result = CORREL_IMAGES( image_A, image_B,
[XSHIFT=, YSHIFT=, XOFFSET_B=, YOFFSET_B=, REDUCTION=,
MAGNIFICATION=, /NUMPIX, /MONITOR )
INPUTS:
image_A, image_B = the two images of interest.
OPTIONAL INPUT KEYWORDS:
XSHIFT = the + & - shift to be applied in X direction, default=7.
YSHIFT = the Y direction + & - shifting, default=7.
XOFFSET_B = initial X pixel offset of image_B relative to image_A.
YOFFSET_B = Y pixel offset, defaults are (0,0).
REDUCTION = optional reduction factor causes computation of
Low resolution correlation of bin averaged images,
thus faster. Can be used to get approximate optimal
(x,y) offset of images, and then called for successive
lower reductions in conjunction with CorrMat_Analyze
until REDUCTION=1, getting offset up to single pixel.
MAGNIFICATION = option causes computation of high resolution correlation
of magnified images, thus much slower.
Shifting distance is automatically = 2 + Magnification,
and optimal pixel offset should be known and specified.
Optimal offset can then be found to fractional pixels
using CorrMat_Analyze( correl_images( ) ).
/NUMPIX - if set, causes the number of pixels for each correlation
to be saved in a second image, concatenated to the
correlation image, so Result is fltarr( Nx, Ny, 2 ).
/MONITOR causes the progress of computation to be briefly printed.
OUTPUTS:
Result is the cross-correlation function, given as a matrix.
PROCEDURE:
Loop over all possible (x,y) shifts, compute overlap and correlation
for each shift. Correlation set to zero when there is no overlap.
MODIFICATION HISTORY:
Written, July,1991, Frank Varosi, STX @ NASA/GSFC
Use ROUND instead of NINT, June 1995, Wayne Landsman HSTX
Avoid divide by zero errors, W. Landsman HSTX April 1996
Remove use of !DEBUG W. Landsman June 1997
Subtract mean of entire image before computing correlation, not just
mean of overlap region H. Ebeling/W. Landsman June 1998
(See /home/drw/idl/pawel/Moon_position_brd_cam_step3_corr2d_YH.pro)
NAME:
CORREL_IMAGES
PURPOSE:
Compute the 2-D cross-correlation function of two images
EXPLANATION:
Computes the 2-D cross-correlation function of two images for
a range of (x,y) shifting by pixels of one image relative to the other.
CALLING SEQUENCE:
Result = CORREL_IMAGES( image_A, image_B,
[XSHIFT=, YSHIFT=, XOFFSET_B=, YOFFSET_B=, REDUCTION=,
MAGNIFICATION=, /NUMPIX, /MONITOR )
INPUTS:
image_A, image_B = the two images of interest.
OPTIONAL INPUT KEYWORDS:
XSHIFT = the + & - shift to be applied in X direction, default=7.
YSHIFT = the Y direction + & - shifting, default=7.
XOFFSET_B = initial X pixel offset of image_B relative to image_A.
YOFFSET_B = Y pixel offset, defaults are (0,0).
REDUCTION = optional reduction factor causes computation of
Low resolution correlation of bin averaged images,
thus faster. Can be used to get approximate optimal
(x,y) offset of images, and then called for successive
lower reductions in conjunction with CorrMat_Analyze
until REDUCTION=1, getting offset up to single pixel.
MAGNIFICATION = option causes computation of high resolution correlation
of magnified images, thus much slower.
Shifting distance is automatically = 2 + Magnification,
and optimal pixel offset should be known and specified.
Optimal offset can then be found to fractional pixels
using CorrMat_Analyze( correl_images( ) ).
/NUMPIX - if set, causes the number of pixels for each correlation
to be saved in a second image, concatenated to the
correlation image, so Result is fltarr( Nx, Ny, 2 ).
/MONITOR causes the progress of computation to be briefly printed.
OUTPUTS:
Result is the cross-correlation function, given as a matrix.
PROCEDURE:
Loop over all possible (x,y) shifts, compute overlap and correlation
for each shift. Correlation set to zero when there is no overlap.
MODIFICATION HISTORY:
Written, July,1991, Frank Varosi, STX @ NASA/GSFC
Use ROUND instead of NINT, June 1995, Wayne Landsman HSTX
Avoid divide by zero errors, W. Landsman HSTX April 1996
Remove use of !DEBUG W. Landsman June 1997
Subtract mean of entire image before computing correlation, not just
mean of overlap region H. Ebeling/W. Landsman June 1998
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH.pro)
NAME:
CORREL_IMAGES
PURPOSE:
Compute the 2-D cross-correlation function of two images
EXPLANATION:
Computes the 2-D cross-correlation function of two images for
a range of (x,y) shifting by pixels of one image relative to the other.
CALLING SEQUENCE:
Result = CORREL_IMAGES( image_A, image_B,
[XSHIFT=, YSHIFT=, XOFFSET_B=, YOFFSET_B=, REDUCTION=,
MAGNIFICATION=, /NUMPIX, /MONITOR )
INPUTS:
image_A, image_B = the two images of interest.
OPTIONAL INPUT KEYWORDS:
XSHIFT = the + & - shift to be applied in X direction, default=7.
YSHIFT = the Y direction + & - shifting, default=7.
XOFFSET_B = initial X pixel offset of image_B relative to image_A.
YOFFSET_B = Y pixel offset, defaults are (0,0).
REDUCTION = optional reduction factor causes computation of
Low resolution correlation of bin averaged images,
thus faster. Can be used to get approximate optimal
(x,y) offset of images, and then called for successive
lower reductions in conjunction with CorrMat_Analyze
until REDUCTION=1, getting offset up to single pixel.
MAGNIFICATION = option causes computation of high resolution correlation
of magnified images, thus much slower.
Shifting distance is automatically = 2 + Magnification,
and optimal pixel offset should be known and specified.
Optimal offset can then be found to fractional pixels
using CorrMat_Analyze( correl_images( ) ).
/NUMPIX - if set, causes the number of pixels for each correlation
to be saved in a second image, concatenated to the
correlation image, so Result is fltarr( Nx, Ny, 2 ).
/MONITOR causes the progress of computation to be briefly printed.
OUTPUTS:
Result is the cross-correlation function, given as a matrix.
PROCEDURE:
Loop over all possible (x,y) shifts, compute overlap and correlation
for each shift. Correlation set to zero when there is no overlap.
MODIFICATION HISTORY:
Written, July,1991, Frank Varosi, STX @ NASA/GSFC
Use ROUND instead of NINT, June 1995, Wayne Landsman HSTX
Avoid divide by zero errors, W. Landsman HSTX April 1996
Remove use of !DEBUG W. Landsman June 1997
Subtract mean of entire image before computing correlation, not just
mean of overlap region H. Ebeling/W. Landsman June 1998
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH_0.pro)
NAME: CORRMAT_ANALYZE PURPOSE: Find the optimal (x,y) offset to maximize correlation of 2 images EXPLANATION: Analyzes the 2-D cross-correlation function of two images and finds the optimal(x,y) pixel offsets. Intended for use with function CORREL_IMAGES. CALLING SEQUENCE: corrmat_analyze, correl_mat, xoffset_optimum, yoffset_optimum, max_corr, edge, plateau, [XOFF_INIT=, YOFF_INIT=, REDUCTION=, MAGNIFICATION=, PLATEAU_THRESH=, /PRINT] INPUTS: correl_mat = the cross-correlation matrix of 2 images. (as computed by function CORREL_IMAGES( imA, imB ) ). NOTE: If correl_mat(*,*,1) is the number of pixels for each correlation, (the case when /NUMPIX was specified in call to CORREL_IMAGES) then sqrt( sqrt( # pixels )) is used as correlation weighting factor. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A. YOFF_INIT = Y pixel offset, (both as specified to correl_images). REDUCTION = reduction factor used in call to CORREL_IMAGES. MAGNIFICATION = magnification factor used in call to CORREL_IMAGES, this allows determination of offsets up to fractions of a pixel. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1 /PRINT causes the result of analysis to be printed. OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. max_corr = the maximal correlation corresponding to optimal offset. edge = 1 if maximum is at edge of correlation domain, otherwise=0. plateau = 1 if maximum is in a plateua of correlation function, else=0. PROCEDURE: Find point of maximum cross-correlation and calc. corresponding offsets. If MAGNIFICATION > 1: the correl_mat is checked for plateau near maximum, and if found, the center of plateau is taken as point of maximum cross-correlation. MODIFICATION HISTORY: Written, July-1991, Frank Varosi, STX @ NASA/GSFC Use ROUND instead of NINT, June 1995 Wayne Landsman HSTX Remove use of non-standard !DEBUG system variable W.L. HSTX Converted to IDL V5.0 W. Landsman September 1997
(See /home/drw/idl/pawel/oprogramowanie_secis/wyznaczanie_residual_shifts.pro)
NAME: CORRMAT_ANALYZE PURPOSE: Find the optimal (x,y) offset to maximize correlation of 2 images EXPLANATION: Analyzes the 2-D cross-correlation function of two images and finds the optimal(x,y) pixel offsets. Intended for use with function CORREL_IMAGES. CALLING SEQUENCE: corrmat_analyze, correl_mat, xoffset_optimum, yoffset_optimum, max_corr, edge, plateau, [XOFF_INIT=, YOFF_INIT=, REDUCTION=, MAGNIFICATION=, PLATEAU_THRESH=, /PRINT] INPUTS: correl_mat = the cross-correlation matrix of 2 images. (as computed by function CORREL_IMAGES( imA, imB ) ). NOTE: If correl_mat(*,*,1) is the number of pixels for each correlation, (the case when /NUMPIX was specified in call to CORREL_IMAGES) then sqrt( sqrt( # pixels )) is used as correlation weighting factor. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A. YOFF_INIT = Y pixel offset, (both as specified to correl_images). REDUCTION = reduction factor used in call to CORREL_IMAGES. MAGNIFICATION = magnification factor used in call to CORREL_IMAGES, this allows determination of offsets up to fractions of a pixel. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1 /PRINT causes the result of analysis to be printed. OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. max_corr = the maximal correlation corresponding to optimal offset. edge = 1 if maximum is at edge of correlation domain, otherwise=0. plateau = 1 if maximum is in a plateua of correlation function, else=0. PROCEDURE: Find point of maximum cross-correlation and calc. corresponding offsets. If MAGNIFICATION > 1: the correl_mat is checked for plateau near maximum, and if found, the center of plateau is taken as point of maximum cross-correlation. MODIFICATION HISTORY: Written, July-1991, Frank Varosi, STX @ NASA/GSFC Use ROUND instead of NINT, June 1995 Wayne Landsman HSTX Remove use of non-standard !DEBUG system variable W.L. HSTX Converted to IDL V5.0 W. Landsman September 1997
(See /home/drw/idl/pawel/Moon_position_brd_cam_step3_corr2d_YH.pro)
NAME: CORRMAT_ANALYZE PURPOSE: Find the optimal (x,y) offset to maximize correlation of 2 images EXPLANATION: Analyzes the 2-D cross-correlation function of two images and finds the optimal(x,y) pixel offsets. Intended for use with function CORREL_IMAGES. CALLING SEQUENCE: corrmat_analyze, correl_mat, xoffset_optimum, yoffset_optimum, max_corr, edge, plateau, [XOFF_INIT=, YOFF_INIT=, REDUCTION=, MAGNIFICATION=, PLATEAU_THRESH=, /PRINT] INPUTS: correl_mat = the cross-correlation matrix of 2 images. (as computed by function CORREL_IMAGES( imA, imB ) ). NOTE: If correl_mat(*,*,1) is the number of pixels for each correlation, (the case when /NUMPIX was specified in call to CORREL_IMAGES) then sqrt( sqrt( # pixels )) is used as correlation weighting factor. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A. YOFF_INIT = Y pixel offset, (both as specified to correl_images). REDUCTION = reduction factor used in call to CORREL_IMAGES. MAGNIFICATION = magnification factor used in call to CORREL_IMAGES, this allows determination of offsets up to fractions of a pixel. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1 /PRINT causes the result of analysis to be printed. OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. max_corr = the maximal correlation corresponding to optimal offset. edge = 1 if maximum is at edge of correlation domain, otherwise=0. plateau = 1 if maximum is in a plateua of correlation function, else=0. PROCEDURE: Find point of maximum cross-correlation and calc. corresponding offsets. If MAGNIFICATION > 1: the correl_mat is checked for plateau near maximum, and if found, the center of plateau is taken as point of maximum cross-correlation. MODIFICATION HISTORY: Written, July-1991, Frank Varosi, STX @ NASA/GSFC Use ROUND instead of NINT, June 1995 Wayne Landsman HSTX Remove use of non-standard !DEBUG system variable W.L. HSTX Converted to IDL V5.0 W. Landsman September 1997
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH.pro)
NAME: CORRMAT_ANALYZE PURPOSE: Find the optimal (x,y) offset to maximize correlation of 2 images EXPLANATION: Analyzes the 2-D cross-correlation function of two images and finds the optimal(x,y) pixel offsets. Intended for use with function CORREL_IMAGES. CALLING SEQUENCE: corrmat_analyze, correl_mat, xoffset_optimum, yoffset_optimum, max_corr, edge, plateau, [XOFF_INIT=, YOFF_INIT=, REDUCTION=, MAGNIFICATION=, PLATEAU_THRESH=, /PRINT] INPUTS: correl_mat = the cross-correlation matrix of 2 images. (as computed by function CORREL_IMAGES( imA, imB ) ). NOTE: If correl_mat(*,*,1) is the number of pixels for each correlation, (the case when /NUMPIX was specified in call to CORREL_IMAGES) then sqrt( sqrt( # pixels )) is used as correlation weighting factor. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A. YOFF_INIT = Y pixel offset, (both as specified to correl_images). REDUCTION = reduction factor used in call to CORREL_IMAGES. MAGNIFICATION = magnification factor used in call to CORREL_IMAGES, this allows determination of offsets up to fractions of a pixel. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1 /PRINT causes the result of analysis to be printed. OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. max_corr = the maximal correlation corresponding to optimal offset. edge = 1 if maximum is at edge of correlation domain, otherwise=0. plateau = 1 if maximum is in a plateua of correlation function, else=0. PROCEDURE: Find point of maximum cross-correlation and calc. corresponding offsets. If MAGNIFICATION > 1: the correl_mat is checked for plateau near maximum, and if found, the center of plateau is taken as point of maximum cross-correlation. MODIFICATION HISTORY: Written, July-1991, Frank Varosi, STX @ NASA/GSFC Use ROUND instead of NINT, June 1995 Wayne Landsman HSTX Remove use of non-standard !DEBUG system variable W.L. HSTX Converted to IDL V5.0 W. Landsman September 1997
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH_0.pro)
NAME:
COSD
PURPOSE:
Return the cosine of an angle specified in degrees rather than radians.
CALLING SEQUENCE:
x = cosd(deg)
INPUTS:
angle angle in degrees
OPTIONAL INPUTS:
OUTPUTS:
Cosine of angle returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/cosd.pro)
NAME:
COSD
PURPOSE:
Return the cosine of an angle specified in degrees rather than radians.
CALLING SEQUENCE:
x = cosd(deg)
INPUTS:
angle angle in degrees
OPTIONAL INPUTS:
OUTPUTS:
Cosine of angle returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/cosd.pro)
NAME:
COSSCATANG
PURPOSE:
Return the scattering angle of the incident and emerging rays.
NOTE: the scattering angle is defined as 180 degrees when
sza = vza = 0 and phi = 180.
CALLING SEQUENCE:
cos_omega = cosscatang(cossza, cosvza, phi)
INPUTS:
cossza cosine of solar (or incident) zenith angle
cosvza cosine of viewing (or emergin or satellite) zenith angle
phi relative azimuth angle; this is defined as the difference
between the solar azimuth angle and the viewing azimuth
angle; when sat, sun are in the same position in
the sky, phi = 0
OPTIONAL INPUTS:
OUTPUTS:
The scattering angle is returned.
EXAMPLE:
IDL> print,acosd(cosscatang(cosd(60),cosd(60),0))
0.00000
IDL> print,acosd(cosscatang(cosd(60),cosd(60),180))
120.000
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 1/04/94
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/cosscatang.pro)
NAME:
COSSCATANG
PURPOSE:
Return the scattering angle of the incident and emerging rays.
NOTE: the scattering angle is defined as 180 degrees when
sza = vza = 0 and phi = 180.
CALLING SEQUENCE:
cos_omega = cosscatang(cossza, cosvza, phi)
INPUTS:
cossza cosine of solar (or incident) zenith angle
cosvza cosine of viewing (or emergin or satellite) zenith angle
phi relative azimuth angle; this is defined as the difference
between the solar azimuth angle and the viewing azimuth
angle; when sat, sun are in the same position in
the sky, phi = 0
OPTIONAL INPUTS:
OUTPUTS:
The scattering angle is returned.
EXAMPLE:
IDL> print,acosd(cosscatang(cosd(60),cosd(60),0))
0.00000
IDL> print,acosd(cosscatang(cosd(60),cosd(60),180))
120.000
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 1/04/94
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/cosscatang.pro)
NAME:
COYOTE_FIELD
PURPOSE:
The purpose of this compound widget is to provide an alternative
to the CW_FIELD widget offered in the IDL distribution. What has
always annoyed me about CW_FIELD is that the text widgets do not
look editable to the users on Windows platforms. This program
corrects that deficiency and adds some features that I think
would be helpful. For example, you can now assign an event handler
to the compound widget.
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:
General programming.
CALLING SEQUENCE:
fieldID = COYOTE_Field(parent, Title='X Size: ", Value=256, /IntegerValue)
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
Column -- Set this keyword to have the Label Widget above the Text Widget.
CR_Only -- Set this keyword if you only want Carriage Return events. If
this keyword is not set, all events are returned. No events
are returned unless the EVENT_PRO or EVENT_FUNC keywords are used.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
Event_Func -- Set this keyword to the name of an Event Function. If this
keyword is undefined and the Event_Pro keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
Event_Pro -- Set this keyword to the name of an Event Procedure. If this
keyword is undefined and the Event_Func keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
FieldFont -- The font name for the text in the Text Widget.
FloatValue -- Set this keyword for FLOAT values.
Frame -- Set this keyword to put a frame around the compound widget.
IntegerValue -- Set this keyword for INTEGER values.
LabelFont -- The font name for the text in the Label Widget.
LabelSize -- The X screen size of the Label Widget.
LongValue -- Set this keyword for LONG values.
Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.)
Scr_XSize -- The X screen size of the compound widget.
Scr_YSize -- The Y screen size of the compound widget.
StringValue -- Set this keyword for STRING values. (The default.)
Title -- The text to go on the Label Widget.
UValue -- A user value for any purpose.
Value -- The "value" of the compound widget.
XSize -- The X size of the Text Widget.
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
EVENT STRUCTURE:
All events are handled internally unless either the Event_Pro or Event_Func
keywords are used to assign an event handler to the compound widget. By
default all events generated by the text widget are passed to the assigned
event handler. If you wish to receive only Carriage Return events, set the
CR_Only keyword.
event = { COYOTE_FIELD, $ ; The name of the event structure.
ID: 0L, $ ; The ID of the compound widget's top-level base.
TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
Value: Ptr_New(), $ ; A pointer to the widget value.
Type:"" ; A string indicating the type of data in the VALUE field.
} ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING".
EXAMPLE:
An example program is provided at the end of the COYOTE_FIELD code. To run it,
type these commands:
IDL> .Compile COYOTE_Field
IDL> Example
MODIFICATION HISTORY:
Written by: David Fanning, 17 NOV 1999.
Added check to make float and double values finite. 18 NOV 1999. DWF.
Fixed a bug when selecting and deleting all numerical text. 19 NOV 1999. DWF.
Added DECIMAL and DIGITS keywords. 2 Jan 2000. DWF.
Added the POSITIVE keyword. 12 Jan 2000. DWF.
Fixed a few minor bugs with delete and digits. 12 Jan 2000. DWF.
Made GET_VALUE function return pointer to data, instead of data. 12 Jan 2000. DWF.
Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF.
Fixed a small problem with the Example program. 7 Oct 2000. DWF.
(See /home/drw/idl/aux/coyote_field.pro)
NAME:
CROSSPN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
A version of CROSSP for efficient vector cross products
CALLING SEQUENCE:
C = CROSSPN(A, B)
DESCRIPTION:
The function CROSSPN computes the vector cross product (outer
product). The difference between CROSSPN and the IDL library
function CROSSP, is that CROSSPN allows more than one cross
product to be computed at one time (i.e., it is vectorized).
Thus, in the expression "C = CROSSPN(A, B)" the vector cross
product is computed as C = A x B. Because CROSSPN is vectorized,
any of the following combinations are valid:
* A is a 3-vector, B is a 3-vector
==> C is the vector cross product C = A x B
* A is a 3xN array, B is a 3-vector
==> C(*,I) = A(*,I) x B (each A is crossed with B)
* A is a 3-vector, B is a 3xN array
==> C(*,I) = A x B(*,I) (A is crossed with each B)
* A is a 3xN array, B is a 3xN array
==> C(*,I) = A(*,I) x B(*,I) (component-by-component)
If both A and B are arrays then they must have the same
dimensions.
INPUTS:
A - a 3-vector or 3xN array.
B - a 3-vector or 3xN array.
RETURNS:
The vector cross product A x B, either a 3-vector or a 3xN array
depending on A and B.
SEE ALSO:
CROSSP
MODIFICATION HISTORY:
Written, CM, 10 Mar 2002
Documented, CM, 22 Mar 2002
$Id: crosspn.pro,v 1.2 2002/03/22 22:02:02 craigm Exp $
(See /home/drw/idl/aux/markwardt/crosspn.pro)
ROUTINE: crystal
PURPOSE: compute the radius of an mie-sphere with scattering
properties equivalent to a irregular crystal shape.
USEAGE: crystal,type,rsph,nsph,area,volume, $
d=d,t=t,bb=bb,bt=bt,l1=l1,l2=l2,l3=l3,a1=a1,a2=a2,a3=a3
INPUT:
type crystal type description Geom input parameters
------------ ----------- ---------------------
1 hollow column L1,a1,d
2 bullet rosette L1,a1,t
3 dendrite on plate L1,a1,bb,bt
4 capped column L1,L2,L3,a1,a2,a3
KEYWORD INPUT:
;
type 1: hollow column
L1 column length (um)
a1 hexagonal face width (um)
d cavity depth at each end of column (um)
type 2: bullet rosette
L1 column length (um)
a1 hexagonal face width (um)
t conical pyramid height on bullet rosettes (um)
type 3: dendrite on plate
L1 disk thickness (um)
a1 hexagonal face width (um)
bb base width of dendrite (um)
bt length of dendrite (um)
type 4: capped column
L1 cap thickness (um)
L2 column length (um)
L3 other cap thickness (um)
a1 cap hexagonal face width (um)
a2 hexagonal face width of column (um)
a3 other cap hexagonal face width (um)
These geometric parameters are difined in Takano and Liou, 1995:
"Radiative Transfer in Cirrus Clouds. Part III: Light
Scattering by Irregular Ice Crystals" JAS 152, No 7, April 1995
OUTPUT:
rsph radius of equivalent Mie spheres (um)
nsph number of equivalent Mie spheres
(factors into particle distribution function in mie
calculation if a distribution of crystal sizes are
computed, see example)
area area in um^2
volume volume in um^3
DISCUSSION:
According to Warren and Grenfeld, the scattering
parameters of an irregular crystal can be approximated
by those of the set of equivalent Mie spheres, such
that the both the area and volume of the set of
spheres match those of the original crystal.
Say the density of a given crystal type is N per unit volume
the extinction coefficient, kappa, (per unit distance) is
given by,
kappa = N * Q * A / 4
where Q is the unknown extinction efficiency and the factor
of 4 is to turn area into average cross-sectional area.
According to W&G, kappa is approximately given by,
kappa = N * Q_mie(rsph) * (nsph * pi rsph^2)
= N * Q_mie(rsph) * A/4
The single scattering albedo and asymmetry factor are given by,
omega = omega_mie(rsph)
g = g_mie(rsph)
EXAMPLE:
; Plot equivalent mie radius versus crystal length
l1=findrng(50,200,100)
crystal,1,rsph,nsph,l1=l1,a1=50,d=10
plot,l1,rsph
; Determine PDF of equivalent radius mie spheres given distribution
; of crystal shapes. Suppose dendrite width is fixed and the number
; of particles of a given length is given by a lognormal pdf with
; cutoffs at 10 and 500um:
;
l1=findrng(10,500,100) & sig=.3
w=exp(-alog10(l1/50.)^2/(2.*sig^2))
crystal,1,rsph,nsph,l1=l1,a1=10.,d=0
wmie=w*nsph ; pdf of equivalent mie sphere
; radius distribution
!p.multi=[0,1,2]
plot,l1,w,title='dendrite length pdf',xtitle='length'
plot,rsph,wmie,title='equivalent mie radius pdf',xtitle='radius'
REVISIONS:
AUTHOR: Paul Ricchiazzi 27 Jul 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/crystal.pro)
ROUTINE: crystal
PURPOSE: compute the radius of an mie-sphere with scattering
properties equivalent to a irregular crystal shape.
USEAGE: crystal,type,area,volumn,nsph,rsph,geom=geom
INPUT:
type crystal type description Geom parameters
------------ ----------- ----------
1 hollow column L,a,d
2 bullet rosette L,a,t
3 dendrite on plate L,a,bb,bt
4 capped column L1,L2,L3,a1,a2,a3
KEYWORD INPUT:
;
g1,g2... geometry parameters in order given above, The geometry
parameters may be an array of values, in which case the
the output is also an array.
L g1 column length (1,2) or disk thickness (3) (um)
a g2 hexagonal face width (1,2,3) (um)
d g3 cavity depth at each end of column (1) (um)
t g3 conical pyramid height on bullet rosettes (2) (um)
bb g3 base width of dendrite (3) (um)
bt g4 length of dendrite (3) (um)
L1 g1 cap thickness (4) (um)
L2 g2 column length (4) (um)
L3 g3 other cap thickness (4) (um)
a1 g4 cap hexagonal face width (4) (um)
a2 g5 hexagonal face width of column (4) (um)
a3 g6 other cap hexagonal face width (4) (um)
OUTPUT:
rsph radius of equivalent Mie spheres (um)
nsph number of equivalent Mie spheres (not required for mie
parameter calculation)
area area in um^2
volume volume in um^3
DISCUSSION:
According to Warren and Grenfeld, the scattering
parameters of an irregular the crystal can be
approximated by those of the set of equivalent Mie
spheres, such that the both the area and volume of the
set of spheres match those of the original crystal.
Say the density of a given crystal type is N per unit volume
the extinction coefficient, kappa, (per unit distance) is
given by,
kappa = N * Q * A / 4
where Q is the unknown extinction efficiency and the factor
of 4 is to turn area into average cross-sectional area.
According to W&G, kappa is approximately given by,
kappa = N * Q_mie(rsph) * (nsph * pi rsph^2)
= N * Q_mie(rsph) * A/4
The single scattering albedo and asymmetry factor are given by,
omega = omega_mie(rsph)
g = g_mie(rsph)
EXAMPLE:
;
l=findrng(50,200,100)
crystal,1,r,g1=l,g2=50,g3=50
plot,l,r
REVISIONS:
AUTHOR: Paul Ricchiazzi 27 Jul 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/crystal.pro)
NAME:
CURBOX
PURPOSE:
Emulate the operation of a variable-sized box cursor (also known as
a "marquee" selector). CURBOX can be used to select a sub-region
from a TVIM image (see example).
CATEGORY:
Interactive graphics.
CALLING SEQUENCE:
CURBOX, x1,x2,y1,y2
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,init=init,$
message=message,inc=inc, index=index,label=label, $
color=color,charsize=charsize
+
INPUTS:
x1,x2,y1,y2
coordinates of box edges. If XWIN,YWIN,XRNG,YRNG are set, then
input is in data coordinates, otherwise in normalized coordinates.
KEYWORD PARAMETERS:
init
If this keyword is set, the initial position of the cursor
is given by X1,X2,Y1,Y2
message
If this keyword is set, print a short message describing
operation of the cursor.
xwin,ywin
two element vectors giving normalized x and y coordinates of window
subregion, for example that given by !x.window or !y.window
xrng,yrng
two elements vectors giving data range of window subregion, for
example, as given by !x.crange or !y.crange. When CURBOX is used
with TVIM (and XRANGE and YRANGE are not used with TVIM), XRNG
and YRNG represent the total index range of the displayed
image. X1,X2,Y1,Y2 will then be the array subrange of the
selected region.
index
if set, the XRNG,YRNG,XWIN,YWIN parameters are set to the values of
the last data window, i.e., !x.crange,!y.crange, !x.window, and
!y.window respectively. Setting INDEX causes X1,X2,Y1,Y2 to be
interpreted as index range coordinates.
inc
increment by which to change cursor box size when right or left
mouse button is pressed. Specified in data index coordinates (i.e.,
array index coordinate) when XWIN,YWIN,XRNG,YRNG are set, otherwise
in normalized coordinates. The x and y increments may be specified
separately by providing INC as a two element array.
label
a string which is used to label the selected region. The string is
centered within the region and is sized to ensure that it fits within
the box. If LABEL is set the box is not erased after CURBOX returns
color
color used to label regions
charsize
character size used for region labels
fill
color used to fill box region, only effective when LABEL is set
OUTPUTS:
x1,x2,y1,y2
normalized coordinates coordinates of box edges. Howvever, if
xwin, ywin, xrng, and yrng are set, output is in data index
coordinates, i.e., x1,x2,y1,y2 provide the index range of the
boxed region of the image.
If xwin,ywin,xrng,yrng are set, the output range is clipped to be
within the limits of xrng and yrng.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A box is drawn in the currently active window. It is erased
on exit.
RESTRICTIONS:
Works only with window system drivers.
PROCEDURE:
The graphics function is set to 6 for eXclusive OR. This
allows the box to be drawn and erased without disturbing the
contents of the window.
Operation is as follows:
Left mouse button: reduce box size
Middle mouse button: increase box size
Right mouse button: Exit this procedure, returning the
current box parameters.
NOTE: CURBOX is designed for applications in which the aspect
ratio of the cursor box is fixed. However, if the
aspect ratio must be adjusted do the following: jam the
box against one of the window borders. If you force
the box against the left or right borders (while
keeping the cursor pointer within the window) box size
is constrained to change only in the height. Similarly
the box can be made fatter or thiner by pushing the box
against the top or bottom. As usual the LMB decreases
size and the MMB increases size.
; EXAMPLE
;
; use curbox to interactively select subregions from a TVIM image
w8x11
!p.multi=[0,1,2]
f=randata(128,128,s=3)
tvim,f,/interp
xw=!x.window & xr=!x.crange
yw=!y.window & yr=!y.crange
x1=60 & x2=80 & y1=60 & y2=80
!p.charsize=2
!p.multi=[4,2,4]
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 1'
confill,f(x1:x2,y1:y2),title='region 1'
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 2'
confill,f(x1:x2,y1:y2),title='region 2'
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 3'
confill,f(x1:x2,y1:y2),title='region 3'
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 4'
confill,f(x1:x2,y1:y2),title='region 4'
; use CURBOX to find the normalized coordinates of a window region
; of given aspect ratio
x1=.4 & x2=x1+.3 & y1=.4 & y2=y1+.1
curbox,x1,x2,y1,y2,/init,/mess
print,x1,x2,y1,y2
author Paul Ricchiazzi April, 1993
(See /home/drw/idl/esrg/curbox.pro)
NAME:
CURBOX
PURPOSE:
Emulate the operation of a variable-sized box cursor (also known as
a "marquee" selector). CURBOX can be used to select a sub-region
from a TVIM image (see example).
CATEGORY:
Interactive graphics.
CALLING SEQUENCE:
CURBOX, x1,x2,y1,y2
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,init=init,$
message=message,inc=inc, index=index,label=label, $
color=color,charsize=charsize
+
INPUTS:
x1,x2,y1,y2
coordinates of box edges. If XWIN,YWIN,XRNG,YRNG are set, then
input is in data coordinates, otherwise in normalized coordinates.
KEYWORD PARAMETERS:
init
If this keyword is set, the initial position of the cursor
is given by X1,X2,Y1,Y2
message
If this keyword is set, print a short message describing
operation of the cursor.
xwin,ywin
two element vectors giving normalized x and y coordinates of window
subregion, for example that given by !x.window or !y.window
xrng,yrng
two elements vectors giving data range of window subregion, for
example, as given by !x.crange or !y.crange. When CURBOX is used
with TVIM (and XRANGE and YRANGE are not used with TVIM), XRNG
and YRNG represent the total index range of the displayed
image. X1,X2,Y1,Y2 will then be the array subrange of the
selected region.
index
if set, the XRNG,YRNG,XWIN,YWIN parameters are set to the values of
the last data window, i.e., !x.crange,!y.crange, !x.window, and
!y.window respectively. Setting INDEX causes X1,X2,Y1,Y2 to be
interpreted as index range coordinates.
inc
increment by which to change cursor box size when right or left
mouse button is pressed. Specified in data index coordinates (i.e.,
array index coordinate) when XWIN,YWIN,XRNG,YRNG are set, otherwise
in normalized coordinates. The x and y increments may be specified
separately by providing INC as a two element array.
label
a string which is used to label the selected region. The string is
centered within the region and is sized to ensure that it fits within
the box. If LABEL is set the box is not erased after CURBOX returns
color
color used to label regions
charsize
character size used for region labels
fill
color used to fill box region, only effective when LABEL is set
OUTPUTS:
x1,x2,y1,y2
normalized coordinates coordinates of box edges. Howvever, if
xwin, ywin, xrng, and yrng are set, output is in data index
coordinates, i.e., x1,x2,y1,y2 provide the index range of the
boxed region of the image.
If xwin,ywin,xrng,yrng are set, the output range is clipped to be
within the limits of xrng and yrng.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A box is drawn in the currently active window. It is erased
on exit.
RESTRICTIONS:
Works only with window system drivers.
PROCEDURE:
The graphics function is set to 6 for eXclusive OR. This
allows the box to be drawn and erased without disturbing the
contents of the window.
Operation is as follows:
Left mouse button: reduce box size
Middle mouse button: increase box size
Right mouse button: Exit this procedure, returning the
current box parameters.
NOTE: CURBOX is designed for applications in which the aspect
ratio of the cursor box is fixed. However, if the
aspect ratio must be adjusted do the following: jam the
box against one of the window borders. If you force
the box against the left or right borders (while
keeping the cursor pointer within the window) box size
is constrained to change only in the height. Similarly
the box can be made fatter or thiner by pushing the box
against the top or bottom. As usual the LMB decreases
size and the MMB increases size.
; EXAMPLE
;
; use curbox to interactively select subregions from a TVIM image
w8x11
!p.multi=[0,1,2]
f=randata(128,128,s=3)
tvim,f,/interp
xw=!x.window & xr=!x.crange
yw=!y.window & yr=!y.crange
x1=60 & x2=80 & y1=60 & y2=80
!p.charsize=2
!p.multi=[4,2,4]
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 1'
confill,f(x1:x2,y1:y2),title='region 1'
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 2'
confill,f(x1:x2,y1:y2),title='region 2'
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 3'
confill,f(x1:x2,y1:y2),title='region 3'
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess,label='region 4'
confill,f(x1:x2,y1:y2),title='region 4'
; use CURBOX to find the normalized coordinates of a window region
; of given aspect ratio
x1=.4 & x2=x1+.3 & y1=.4 & y2=y1+.1
curbox,x1,x2,y1,y2,/init,/mess
print,x1,x2,y1,y2
author Paul Ricchiazzi April, 1993
(See /home/drw/idl/old.esrg/curbox.pro)
ROUTINE: cursim
USEAGE: cursim,a,yy,xx,range=range
PURPOSE: Use the graphics cursor to interrogate a TVIM image for
pixel values and positions.
INPUT:
a image array, same size as used in TVIM image
yy, xx 2-D arrays of "vertical" and "horizontal" position
in the geographical case these would be lat and lon arrays
If these arrays are not supplied the x and y data
coordinates are used instead.
OPTIONAL INPUT:
point if set, CURSIM will print the range and azimuth
of the cursor from this point. (Palmer = [-64.767,-64.067] )
When this option is used the lat,lon coordinates must
be available either in the data coordinates of the plot
(i.e., as specified by the XRANGE and YRANGE parameter
in the TVIM call) or explicitly as the YY and XX parameters
in CURSIM
EXAMPLE:
tvim,hanning(200,200),xrange=[-180,180],yrange=[-90,90]
map_set,0,0,/cont,/grid,pos=boxpos(/get),/noerase
cursim,hanning(200,200),point=[35,-120]
author: Paul Ricchiazzi sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/cursim.pro)
ROUTINE: cursim
USEAGE: cursim,a,yy,xx,range=range
PURPOSE: Use the graphics cursor to interrogate a TVIM image for
pixel values and positions.
INPUT:
a image array, same size as used in TVIM image
yy, xx 2-D arrays of "vertical" and "horizontal" position
in the geographical case these would be lat and lon arrays
If these arrays are not supplied the x and y data
coordinates are used instead.
OPTIONAL INPUT:
point if set, CURSIM will print the range and azimuth
of the cursor from this point. (Palmer = [-64.767,-64.067] )
When this option is used the lat,lon coordinates must
be available either in the data coordinates of the plot
(i.e., as specified by the XRANGE and YRANGE parameter
in the TVIM call) or explicitly as the YY and XX parameters
in CURSIM
EXAMPLE:
tvim,hanning(200,200),xrange=[-180,180],yrange=[-90,90]
map_set,0,0,/cont,/grid,pos=boxpos(/get),/noerase
cursim,hanning(200,200),point=[35,-120]
author: Paul Ricchiazzi sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/cursim.pro)
ROUTINE: cursx
USEAGE: cursx,xx,yy,verbose=verbose
PROCEDURE: Use the graphics cursor to find xy point on plot.
xy point is written to pop-up widget.
If a single argument is supplied (XX) it is interpreted
as an image or z value which will be evaluated when
the LMB is pressed. This option works with TVIM images
or plots drawn with CONTOUR.
if two arguments are supplied (XX and YY) they are
interpreted as the x and y values of a curve in the xy
plane. The y value of the function is evaluated when
the LMB is pressed. This option works with plots drawn
with PLOT
Hit and drag LMB to retrieve coordinates and values
Hit MMB to quit and retain pop-up display
Hit RMB to quit and destroy pop-up
INPUT:
xx x coordinate or image array
yy if present this parameter indicates CURSX should be run
in curve follow mode (CFM). In this mode the y value at a
x coordiate point is indicated with a drawn symbol. The
symbol position follows the shape of the drawn curve as
the cursor is dragged across the plot.
Keyword input
psym symbol used to mark xy point in plot follow mode.
symsize symbol size
color color of symbol
silent if set, pop up window will not contain operating instructions
interpolate if set and non-zero, interpolate between defined x and y
points in plot follow mode
EXAMPLE:
plot,dist(20)
cursx
; display value at a point
f=randata(100,100,s=3)
tvim,f,xra=[100,120],yra=[30,50],xtitle='longitude',ytitle='latitude',/scale
cursx,f
; pick values off a plot using curve follow mode
x=findgen(200)
y=randf(200,1.5)
plot,x,y
loadct,5
thick,2
cursx,x,y,psym=1,symsize=2,color=100
thick,1
author: Paul Ricchiazzi sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/cursx.pro)
ROUTINE: cursx
USEAGE: cursx,xx,yy,verbose=verbose
PROCEDURE: Use the graphics cursor to find xy point on plot.
xy point is written to pop-up widget.
If a single argument is supplied (XX) it is interpreted
as an image or z value which will be evaluated when
the LMB is pressed. This option works with TVIM images
or plots drawn with CONTOUR.
if two arguments are supplied (XX and YY) they are
interpreted as the x and y values of a curve in the xy
plane. The y value of the function is evaluated when
the LMB is pressed. This option works with plots drawn
with PLOT
Hit and drag LMB to retrieve coordinates and values
Hit MMB to quit and retain pop-up display
Hit RMB to quit and destroy pop-up
INPUT:
xx x coordinate or image array
yy if present this parameter indicates CURSX should be run
in curve follow mode (CFM). In this mode the y value at a
x coordiate point is indicated with a drawn symbol. The
symbol position follows the shape of the drawn curve as
the cursor is dragged across the plot.
Keyword input
psym symbol used to mark xy point in plot follow mode.
symsize symbol size
color color of symbol
silent if set, pop up window will not contain operating instructions
interpolate if set and non-zero, interpolate between defined x and y
points in plot follow mode
EXAMPLE:
plot,dist(20)
cursx
; display value at a point
f=randata(100,100,s=3)
tvim,f,xra=[100,120],yra=[30,50],xtitle='longitude',ytitle='latitude',/scale
cursx,f
; pick values off a plot using curve follow mode
x=findgen(200)
y=randf(200,1.5)
plot,x,y
loadct,5
thick,2
cursx,x,y,psym=1,symsize=2,color=100
thick,1
author: Paul Ricchiazzi sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/cursx.pro)
ROUTINE: cut.pro
PURPOSE: This routine allows the user to select a region interactively
having specified the number of points required and produces
a *trace* output of the region selected.
USEAGE: cut, npts, xar, yar
INPUT:
npts The number of points the user must select.
OUTPUT:
xar x array of data points
yar y array of data points
EXAMPLE: plot_image, 2D_image
cut, 60, xar, yar
window, 2
plot, xar, yar , psym = -2
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/bin/cut.pro)
ROUTINE: cut.pro
PURPOSE: This routine allows the user to select a region interactively
having specified the number of points required and produces
a *trace* output of the region selected.
USEAGE: cut, npts, xar, yar
INPUT:
npts The number of points the user must select.
OUTPUT:
xar x array of data points
yar y array of data points
EXAMPLE: plot_image, 2D_image
cut, 60, xar, yar
window, 2
plot, xar, yar , psym = -2
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/bin/ptg/cut.pro)
NAME:
CW_GETFIELDS
PURPOSE:
This compound widget function allows the user to edit a
user-defined list of fields, and returns the values entered
in the field dialog boxes.
CATEGORY:
Widgets.
CALLING SEQUENCE:
Result = CW_GETFIELDS( DEFAULTS )
INPUTS:
DEFAULTS: Array of default field values.
KEYWORD PARAMETERS:
TITLE: Label for widget dialog box.
NAMES: String array of labels for field dialog boxes.
FLOAT: Accept only floating point values in field dialog boxes,
and return result array as FLOAT type.
Default is return result array as STRING type.
LONG : Accept only long integer values in field dialog boxes,
and return result array as LONG type.
Default is to return result array as STRING type.
INTEGER: Accept only integer values in field dialog boxes,
and return result array as INTEGER type.
Default is to return result array as STRING type.
GROUP: The widget ID of the widget that calls CW_GETFIELDS.
When this ID is specified, a death of the caller results
in the death of CW_GETFIELDS.
OUTPUTS:
CW_GETFIELDS returns a STRING array containing the values
entered by the user in the field dialog boxes. If no changes
are made by the user, then the default values (DEFAULTS) are returned.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This function initiates the XMANAGER if it is not already running.
RESTRICTIONS:
None known.
PROCEDURE:
Create and register the widget and then exit, returning the
field values as a string array.
EXAMPLES:
; Input from 5 fields
; (Return string array)
result = cw_getfields( indgen( 10 ) )
print, strcompress( result )
; Size of a byte image to be read from disk
; (Return long integer array)
defaults = [ 512, 512, 0 ]
names = [ 'Number of columns', 'Number of rows', 'Header bytes to skip' ]
result = cw_getfields( defaults, title = 'Image Size', names = names, /long )
print, result
; Mixed text and numeric input
; (Return string array containing text and numeric entries)
defaults = [ 'input.dat', '100', 'y', '5,5' ]
names = [ 'File to process', 'Records', 'Flip bytes (y/n)', 'Offset (x,y)' ]
result = cw_getfields( defaults, title = 'Input Parameters', names = names )
filename = result( 0 )
nrecs = fix( result( 1 ) )
answer = result( 2 )
reads, result( 3 ), xoff, yoff
print, filename, nrecs, answer, xoff, yoff, format = '(a20,i6,1x,a1,i6,i6)'
MODIFICATION HISTORY:
Written by: Liam Gumley, CIMSS/SSEC, 9 April 1996
(See /home/drw/idl/esrg/cw_getfields.pro)
PRO dark_broad_reader,darkbroad
darkbroad = FLTARR(504,504,500)
FOR i = 0, 499, 1 DO BEGIN
PRINT,i
IF (i LE 9) THEN a = ;READFITS('/scratch/drw/secis/flats/darkbroad000'+ARR2STR(i,/Trim)+'.fit')
IF (i GT 9) AND (i LE 99)) THEN a = ;READFITS('/scratch/drw/secis/flats/darkbroad00'+ARR2STR(i,/Trim)+'.fit')
IF (i GT 99) THEN a = ;READFITS('/scratch/drw/secis/flats/darkbroad0'+ARR2STR(i,/Trim)+'.fit')
darkbroad(*,*,i) = a
;TVIM, a
ENDFOR
END
AUTHOR: DRW Tuesday January 18 15:04:41 GMT 2000
(See /home/drw/idl/secis/dark_broad_reader.pro)
NAME: DATE2MJD PURPOSE: This function converts from a date string to Modified Julian Date. CATEGORY: Time. CALLING SEQUENCE: Result = DATE2MJD(Date) INPUTS: Date: A date and timestring. Any form accepted by the APL routine DATE2JD is acceptable. KEYWORD PARAMETERS: OUTPUTS: This function returns the Modified Julian Day. PROCEDURE: Straightforward. Uses APL routines. EXAMPLE: NOTE: The date must contain the month as a name of 3 or more letters! MODIFICATION HISTORY: Written by David Sahnow, 29 September 2000.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/date2mjd.pro)
DATEIT.PRO - by David Sahnow 11 June 1991 (v2.0) Displays the current date in the lower left corner of a plot
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/dateit.pro)
purpose: return date string given year and day of year
useage: result=date_string(year,day)
EXAMPLE: print,date_string(1991,283)
October 10, 1991
(See /home/drw/idl/esrg/date_string.pro)
ROUTINE: daverage
USEAGE: daverage,lat,sza,yy
PURPOSE:
finds the daylight hour average of yy at each latitude
point. Average values are for spring or fall equinox
INPUT:
lat array of latitude points
sza solar zenith angle array
yy function of solar zenith angle
OUTPUT:
result average of yy over 12 hours (daylight)
EXAMPLE:
lat=indgen(10)*10
sza=acos((indgen(11))*.1)/!dtor
yy=90-sza
!p.multi=[0,1,2]
plot,sza,yy
plot,lat,daverage(lat,sza,yy)
procedure: At the spring or fall equinox the solar zenith angle at
a given latitude is given by,
cos(sza)=cos(lat)*cos(phi)
where phi is the phase angle of the earth's rotation
[= 2 pi*(time-12)/24)]
thus for each value of lat we have
yave=integral(phi,yv)/!pi
where,
yv=interpol(yy,mu,cos(lat*!dtor)*cos(phi*!dtor))
mu=cos(sza*!dtor)
AUTHOR: Paul Ricchiazzi 24 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/daverage.pro)
ROUTINE: daverage
USEAGE: daverage,lat,sza,yy
PURPOSE:
finds the daylight hour average of yy at each latitude
point. Average values are for spring or fall equinox
INPUT:
lat array of latitude points
sza solar zenith angle array
yy function of solar zenith angle
OUTPUT:
result average of yy over 12 hours (daylight)
EXAMPLE:
lat=indgen(10)*10
sza=acos((indgen(11))*.1)/!dtor
yy=90-sza
!p.multi=[0,1,2]
plot,sza,yy
plot,lat,daverage(lat,sza,yy)
procedure: At the spring or fall equinox the solar zenith angle at
a given latitude is given by,
cos(sza)=cos(lat)*cos(phi)
where phi is the phase angle of the earth's rotation
[= 2 pi*(time-12)/24)]
thus for each value of lat we have
yave=integral(phi,yv)/!pi
where,
yv=interpol(yy,mu,cos(lat*!dtor)*cos(phi*!dtor))
mu=cos(sza*!dtor)
AUTHOR: Paul Ricchiazzi 24 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/daverage.pro)
ROUTINE: dayave
PURPOSE: convert quantities which depend on sza to daily averages for
given values of day_of_year and latitude
USEAGE: result=dayave(doy,lat,sza,xx)
INPUT:
doy the day of year (vector)
lat latitude (vector)
sza a vector of solar zenith angles (degrees) monitonic increasing
xx a vector of a quantity which varies with SZA. If
max(sza) lt 90 then it is assumed that xx=0 when
(cos(sza) le 0). If this is not the case, then data
values for the full SZA angle range [-90,90] must be
supplied.
KEYWORD INPUT
dt averaging interval in hours (default=0.25 hours)
zenith zenith angles at each time, doy and lat (24/dt,nday,nlat)
(returned by first call of DAYAVE, see below)
if zero or absent, DAYAVE recomputes the zenith angle at
each point in the (DOY # LAT) input grid. This can be
fairly time consuming when there are lots of grid points.
By supplying a zero filled named variable to DAYAVE you
can retrieve the ZENITH grid for the next call to DAYAVE.
night if set, the interpolated value of xx is not set to zero
when sza is greater than 90. This should be used for
physical quantities which maintain non-zero values even
after sunset
OUTPUT:
result the integral of xx(t) dt for the given days and latitudes
EXAMPLE:
!p.multi=[0,1,2]
doy=findgen(365/30+1)*30
lat=findgen(90/10+1)*10
sza=findgen(90/10)*10
xx=cos(sza*!dtor)
zenith=0. ; zero filled named variable to
; retrieve zenith angle grid
yy=dayave(doy,lat,sza,xx,zenith=zenith)
tvim,yy,xrange=doy,yrange=lat,xtitle='day of year',ytitle='latitude',$
title='daily integral of sup(cos(sza),0)',/scale,/interp
xx2=xx^2
yy2=dayave(doy,lat,sza,xx2,zenith=zenith)
tvim,yy2,xrange=doy,yrange=lat,xtitle='day of year',ytitle='latitude',$
title='daily average of sup(cos(sza)!a2!n,0)',/scale,/interp
author: Paul Ricchiazzi aug94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/dayave.pro)
ROUTINE: dayave
PURPOSE: convert quantities which depend on sza to daily averages for
given values of day_of_year and latitude
USEAGE: result=dayave(doy,lat,sza,xx)
INPUT:
doy the day of year (vector)
lat latitude (vector)
sza a vector of solar zenith angles (degrees) monitonic increasing
xx a vector of a quantity which varies with SZA. If
max(sza) lt 90 then it is assumed that xx=0 when
(cos(sza) le 0). If this is not the case, then data
values for the full SZA angle range [-90,90] must be
supplied.
KEYWORD INPUT
dt averaging interval in hours (default=0.25 hours)
zenith zenith angles at each time, doy and lat (24/dt,nday,nlat)
(returned by first call of DAYAVE, see below)
if zero or absent, DAYAVE recomputes the zenith angle at
each point in the (DOY # LAT) input grid. This can be
fairly time consuming when there are lots of grid points.
By supplying a zero filled named variable to DAYAVE you
can retrieve the ZENITH grid for the next call to DAYAVE.
night if set, the interpolated value of xx is not set to zero
when sza is greater than 90. This should be used for
physical quantities which maintain non-zero values even
after sunset
OUTPUT:
result the integral of xx(t) dt for the given days and latitudes
EXAMPLE:
!p.multi=[0,1,2]
doy=findgen(365/30+1)*30
lat=findgen(90/10+1)*10
sza=findgen(90/10)*10
xx=cos(sza*!dtor)
zenith=0. ; zero filled named variable to
; retrieve zenith angle grid
yy=dayave(doy,lat,sza,xx,zenith=zenith)
tvim,yy,xrange=doy,yrange=lat,xtitle='day of year',ytitle='latitude',$
title='daily integral of sup(cos(sza),0)',/scale,/interp
xx2=xx^2
yy2=dayave(doy,lat,sza,xx2,zenith=zenith)
tvim,yy2,xrange=doy,yrange=lat,xtitle='day of year',ytitle='latitude',$
title='daily average of sup(cos(sza)!a2!n,0)',/scale,/interp
author: Paul Ricchiazzi aug94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/dayave.pro)
Project : SOHO - CDS Name : DBCLOSE Purpose : Procedure to close a data base file Explanation : Procedure to close a data base file Use : dbclose Inputs : None. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : DB_INFO Common : DB_COM Restrictions: None. Side effects: The data base files currently opened are closed Category : Utilities, Database Prev. Hist. : version 2 D. Lindler Oct. 1987 For IDL version 2 August 1990 Written : D. Lindler, GSFC/HRS, October 1987 Modified : Version 1, William Thompson, GSFC, 29 March 1994 Incorporated into CDS library Version 2, William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format Version : Version 2, 30 May 1994
(See /home/drw/idl/aux/dbclose.pro)
NAME:
DCHISQR_CVF
PURPOSE:
This function computes the cutoff value (v) such that:
Probability(X > v) = p
where X is a random variable from the Chi-square distribution
with (df) degrees of freedom.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = dchisqr_cvf(P, DF)
INPUTS:
P: A non-negative scalar, in the interval [0.0, 1.0], of type
float or double that specifies the probability of occurance
or success.
DF: A positive scalar of type integer, float or double that
specifies the degrees of freedom of the Chi-square distribution.
EXAMPLE:
Compute the cutoff value (v) such that Probability(X > v) = 0.100
from the Chi-square distribution with (DF = 3) degrees of freedom.
The result should be 6.25139
result = dchisqr_cvf(0.100, 3)
REFERENCE:
ADVANCED ENGINEERING MATHEMATICS (seventh edition)
Erwin Kreyszig
ISBN 0-471-55380-8
MODIFICATION HISTORY:
Modified by: GGS, RSI, July 1994
Minor changes to code. New documentation header.
(See /home/drw/idl/aux/dchisqr_cvf.pro)
NAME:
DCHISQR_PDF
PURPOSE:
This function computes the probabilty (p) such that:
Probability(X <= v) = p
where X is a random variable from the Chi-square distribution
with (df) degrees of freedom.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = dchisqr_pdf(V, DF)
INPUTS:
V: A scalar of type integer, float or double that specifies
the cutoff value.
DF: A positive scalar of type integer, float or double that
specifies the degrees of freedom of the Chi-square distribution.
EXAMPLES:
Compute the probability that a random variable X, from the Chi-square
distribution with (DF = 3) degrees of freedom, is less than or equal
to 6.25. The result should be 0.899939
result = chisqr_pdf(6.25, 3)
Compute the probability that a random variable X, from the Chi-square
distribution with (DF = 3) degrees of freedom, is greater than 6.25.
The result should be 0.100061
result = 1 - chisqr_pdf(6.25, 3)
REFERENCE:
ADVANCED ENGINEERING MATHEMATICS (seventh edition)
Erwin Kreyszig
ISBN 0-471-55380-8
MODIFICATION HISTORY:
Modified by: GGS, RSI, July 1994
Minor changes to code. New documentation header.
CT, RSI, March 2000: changed call from igamma_pdf to igamma
(See /home/drw/idl/aux/dchisqr_pdf.pro)
ROUTINE dcolors
USEAGE dcolors
dcolors,r=r,g=g,b=b,pickc=pickc,squeeze=squeeze,view=view
INPUT: none
Keyword input:
pickc if set, call pickc to adjust discreet colors
squeeze if set, original color table is resampled to fit
in remaining color table index space.
view if set, draw palette of discreet colors to separate window
r,g,b red, green and blue values of discreet color table.
default colors:
r = [0, 255, 0, 150, 255, 194, 125, 0, 255, 19, 0]
g = [0, 0, 255, 150, 248, 196, 255, 175, 10, 215, 0]
b = [0, 0, 0, 255, 6, 196, 185, 0, 246, 224, 255]
OUTPUT: none
PURPOSE: loads custom colors in lower part of current color
scale. If SQUEEZE is set pre-existing color scale
is squeezed to fit between color index n_elements(r)
and !d.n_colors.
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/dcolors.pro)
ROUTINE dcolors
USEAGE dcolors
dcolors,r=r,g=g,b=b,pickc=pickc,squeeze=squeeze,view=view
INPUT: none
Keyword input:
pickc if set, call pickc to adjust discreet colors
squeeze if set, original color table is resampled to fit
in remaining color table index space.
view if set, draw palette of discreet colors to separate window
r,g,b red, green and blue values of discreet color table.
default colors:
r = [ 0, 255, 0, 150, 255, 196, 3, 0, 150, 98, 0]
g = [ 0, 0, 255, 150, 2, 126, 148, 175, 0, 94, 0]
b = [ 0, 0, 0, 255, 212, 0, 186, 0, 100, 150, 255]
OUTPUT: none
PURPOSE: loads custom colors in lower part of current color
scale. If SQUEEZE is set pre-existing color scale
is squeezed to fit between color index n_elements(r)
and !d.n_colors.
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/dcolors.pro)
NAME:
DDEABM
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:
Integrate Ordinary Differential Equation with Adams-Bashford-Moulton
MAJOR TOPICS:
Numerical Analysis.
CALLING SEQUENCE:
DDEABM, FUNCT, T0, F0, TOUT, [ PRIVATE, FUNCTARGS=, STATE= , ]
[ /INIT, /INTERMEDIATE, TSTOP=, EPSREL=, EPSABS=, ]
[ TGRID=, YGRID=, YPGRID=, NGRID=, NFEV=, ]
[ STATUS=, ERRMSG= ]
DESCRIPTION:
DDEABM performs integration of a system of one or more ordinary
differential equations using a Predictor-Corrector technique. An
adaptive Adams-Bashford-Moulton method of variable order between
one and twelve, adaptive stepsize, and error control, is used to
integrate equations of the form:
DF_DT = FUNCT(T, F)
T is the independent variable, F is the (possibly vector) function
value at T, and DF_DT is the derivative of F with respect to T,
evaluated at T. FUNCT is a user function which returns the
derivative of one or more equations.
DDEABM is based on the public domain procedure DDEABM.F written by
L. F. Shampine and M. K. Gordon, and available in the DEPAC package
of solvers within SLATEC library.
DDEABM is used primarily to solve non-stiff and mildly stiff
ordinary differential equations, where evaluation of the user
function is expensive, or high precision is demanded (close to the
machine precision). A Runge-Kutta technique may be more
appropriate if lower precision is acceptable. For stiff problems
neither Adams-Bashford-Moulton nor Runge-Kutta techniques are
appropriate. DDEABM has code which detects the stiffness of the
problem and reports it.
The user can operate DDEABM in three different modes:
* the user requests one output at a time (the default), and
maintains the integrator state using the STATE keyword;
* the user requests a grid of times (by passing an array to
TOUT), and optionally maintains the integrator state for
subsequent integrations using the STATE keyword;
* the user requests output at the natural adaptive stepsizes
using the /INTERMEDIATE keyword.
When the user requests explicit output points using TOUT, it is
likely that the output will be interpolated between two natural
stepsize points.
If the user requests a grid of outputs, and the integration fails
before reaching the requested endpoint, then control returns
immediately to the user with the appropriate STATUS code.
The initial conditions are given by F0, when T = T0. The number of
equations is determined by the number of elements in F0.
Integration stops when the independent variable T reaches the final
value of TOUT. If the user wants to continue the integration, it
can be restarted with a new call to DDEABM, and a new value of
TOUT.
USER FUNCTION
The user function FUNCT must be of the following form:
FUNCTION FUNCT, T, F, PRIVATE, ...
; ... compute derivatives ...
RETURN, DF_DT
END
The function must accept at least two, but optionally three,
parameters. The first, 'T', is the scalar independent variable
where the derivatives are to be evaluated. The second, 'F', is the
vector of function values. The function must return an array of
same size as 'F'. The third positional parameter, 'PRIVATE', is a
purely optional PRIVATE parameter. FUNCT may accept more
positional parameters, but DDEABM will not use them. Any number of
keyword parameters can be passed using the FUNCTARGS keyword.
The user function FUNCT must not modify either the independent
variable 'T' or the function values 'F'.
RESTARTING THE INTEGRATOR
When restarting the integrator, the STATE keyword can be used to
save some computation time. Upon return from DDEABM the STATE
keyword will contain a structure which describes the state of the
integrator at the output point. The user need merely pass this
variable back into the next call to continue integration. The
value of T, and the function value F, must not be adjusted between
calls to DDEABM.
If T or F0 are to be adjusted, then the integrator must be
restarted afresh *without* the previous state. This can be
achieved either by reseting STATE to undefined, or by setting the
/INIT keyword to DDEABM.
ERROR CONTROL
Local error control is governed by two keywords, EPSABS and EPSREL.
The former governs the absolute error, while the latter governs the
relative or fractional error. The error test at each iteration is:
ABS(ERROR) LE EPSREL*ABS(F) + EPSABS
A scalar value indicates the same constraint should be applied to
every equation; a vector array indicates constraints should be
applied individually to each component.
Setting EPSABS=0.D0 results in a pure relative error test on that
component. Setting EPSREL=0. results in a pure absolute error test
on that component. A mixed test with non-zero EPSREL and EPSABS
corresponds roughly to a relative error test when the solution
component is much bigger than EPSABS and to an absolute error test
when the solution component is smaller than the threshold EPSABS.
Proper selection of the absolute error control parameters EPSABS
requires you to have some idea of the scale of the solution
components. To acquire this information may mean that you will
have to solve the problem more than once. In the absence of scale
information, you should ask for some relative accuracy in all the
components (by setting EPSREL values non-zero) and perhaps impose
extremely small absolute error tolerances to protect against the
danger of a solution component becoming zero.
The code will not attempt to compute a solution at an accuracy
unreasonable for the machine being used. It will advise you if you
ask for too much accuracy and inform you as to the maximum accuracy
it believes possible.
HARD LIMIT ON T
If for some reason there is a hard limit on the independent
variable T, then the user should specify TSTOP. For efficiency
DDEABM may try to integrate *beyond* the requested point of
termination, TOUT, and then interpolate backwards to obtain the
function value at the requested point. If this is not possible
because the function because the equation changes, or if there is a
discontinuity, then users should specify a value for TSTOP; the
integrator will not go past this point.
INPUTS:
FUNCT - by default, a scalar string containing the name of an IDL
function to be integrated. See above for the formal
definition of FUNCT. (No default).
T0 - scalar number, upon input the starting value of the
independent variable T. Upon output, the final value of T.
Y - vector. Upon input the starting values of the function for T =
T0. Upon output, the final (vector) value of the function.
TOUT - must be at least a scalar, but optionally a vector,
specifies the desired points of output.
If TOUT is a scalar and INTERMEDIATE is not set, then DDEABM
integrates up to TOUT. A scalar value of the function at
TOUT is returned in F.
If TOUT is a scalar and /INTERMEDIATE is set, then DDEABM
computes a grid of function values at the optimal step
points of the solution. The grid of values is returned in
TGRID, YGRID, and YPGRID. The final function value,
evaluated at the last point in TOUT, is returned in F.
If TOUT is a vector, then DDEABM computes a grid of function
values at the requested points. The grid of values is
returned in TGRID, YGRID and YPGRID. The final function
value, evaluated at the last point in TOUT, is returned in
F.
It is possible for TOUT to be less than T0, i.e., to
integrate backwards.
PRIVATE - any optional variable to be passed on to the function to
be integrated. For functions, PRIVATE is passed as the
second positional parameter. DDEABM does not examine or
alter PRIVATE.
KEYWORD PARAMETERS:
EPSABS - a scalar number, the absolute error tolerance requested
in the integral computation. If less than or equal to
zero, then the value is ignored.
Default: 0
EPSREL - a scalar number, the relative (i.e., fractional) error
tolerance in the integral computation. If less than or
equal to zero, then the value is ignored.
Default: 1e-4 for float, 1d-6 for double
ERRMSG - upon return, a descriptive error message.
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.
INIT - if set, indicates that the integrator is to be restarted
afresh.
INTERMEDIATE - if set, indicates that the integrator is to compute
at the natural step points.
NFEV - upon output, the scalar number of function evaluations.
NGRID - if /INTERMEDIATE is set, the number of points to compute
before returning.
Default: 1
STATE - upon input and return, the integrator state. Users should
not modify this structure. If the integrator is to be
restarted afresh, then the /INIT keyword should be set, in
order to clear out the old state information.
STATUS - upon output, the integer status of the integration.
1 - A step was successfully taken in the
intermediate-output mode. The code has not yet
reached TOUT.
2 - The integration to TOUT was successfully completed
(T=TOUT) by stepping exactly to TOUT.
3 - The integration to TOUT was successfully completed
(T=TOUT) by stepping past TOUT. Y(*) is obtained by
interpolation.
*** Task Interrupted ***
Reported by negative values of STATUS
-1 - A large amount of work has been expended. (500 steps
attempted)
-2 - The error tolerances are too stringent.
-3 - The local error test cannot be satisfied because you
specified a zero component in EPSABS and the
corresponding computed solution component is zero.
Thus, a pure relative error test is impossible for
this component.
-4 - The problem appears to be stiff.
*** Task Terminated ***
Reported by the value of STATUS=-33
-33 - The code has encountered trouble from which it
cannot recover. A error message is printed
explaining the trouble and control is returned to
the calling program. For example, this occurs when
invalid input is detected.
-16 - The user function returned a non-finite
TGRID - upon output, the grid of values of T for which the
integration is provided.
TSTOP - a scalar, specifies a hard limit for T, beyond which the
integration must not proceed.
Default: none, i.e., integration is allowed to
"overshoot"
YGRID - upon output, the grid of function values for which the
integration is provided.
YPGRID - upon ouptut, the grid of function derivative values at
the points where the integration is provided.
EXAMPLES:
REFERENCES:
SAND79-2374 , DEPAC - Design of a User Oriented Package of ODE
Solvers.
"Solving Ordinary Differential Equations with ODE, STEP, and INTRP",
by L. F. Shampine and M. K. Gordon, SLA-73-1060.
SLATEC Common Mathematical Library, Version 4.1, July 1993
a comprehensive software library containing over
1400 general purpose mathematical and statistical routines
written in Fortran 77. (http://www.netlib.org/slatec/)
MODIFICATION HISTORY:
Fix bug in TSTOP keyword, 09 May 2002, CM
Fix behavior of KSTEPS, which caused premature termination, 26
May 2002, CM
Fix two errors in the DDEABM_DINTP interpolation step, 04 Jul 2002, CM
Handle case of IMPULSES more correctly, 25 Sep 2002, CM
Handle case when INIT is not set (default to 1); detect
non-finite user function values and error out with STATUS code
-16; promote integer values to LONG integers; some internal
function renaming, 28 Jun 2003, CM
$Id: ddeabm.pro,v 1.20 2003/06/29 02:28:37 craigm Exp $
(See /home/drw/idl/aux/markwardt/ddeabm.pro)
NAME:
DEFSUBCELL
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Returns a default subcell suitable for plotting in.
CALLING SEQUENCE:
sub = defsubcell( [default] )
DESCRIPTION:
DEFSUBCELL returns a "nice" subcell, useful for plotting in. It
gives 8% margins on the left and bottom, and 5% margins on the
right and top.
A set of user-defined default values can be passed in. Any that
are negative are replaced by this function's.
INPUTS:
DEFAULT - a "default" subcell. Any elements that are negative are
replaced by DEFSUBCELL's notion of the proper margins.
This feature is used, for example, by SUBCELLARRAY to
make subcells that have special margins on certain sides
and default ones on other sides.
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
NONE
RETURNS:
The new subcell.
PROCEDURE:
EXAMPLE:
SEE ALSO:
DEFSUBCELL, SUBCELLARRAY
EXTERNAL SUBROUTINES:
MODIFICATION HISTORY:
Written, CM, 1997
(See /home/drw/idl/aux/markwardt/defsubcell.pro)
FUNCTION degrade
PURPOSE: degrade image resolution by a factor of two
USEAGE: result=degrade(array)
INPUT:
array an image array of dimension NX x NY, where both nx
ny are divisible by 2. If nx or ny are not divisible by
2 a subimage is extracted that leaves off the last row
or column and is divisible by 2 in both directions.
KEYWORD INPUT:
min if set the returned value for each superpixel is the min
of each of the four subpixels
max if set the returned value for each superpixel is the max
of each of the four subpixels
output:
result image array of dimension NX/2 x NY/2 composed of 2 x 2
superpixel averages of u (except if MIN or MAX keyword is
set, see above)
AUTHOR: Paul Ricchiazzi 26 May 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/degrade.pro)
FUNCTION degrade
PURPOSE: degrade image resolution by a factor of two
USEAGE: result=degrade(array)
INPUT:
array an image array of dimension NX x NY, where both nx
ny are divisible by 2. If nx or ny are not divisible by
2 a subimage is extracted that leaves off the last row
or column and is divisible by 2 in both directions.
KEYWORD INPUT:
min if set the returned value for each superpixel is the min
of each of the four subpixels
max if set the returned value for each superpixel is the max
of each of the four subpixels
output:
result image array of dimension NX/2 x NY/2 composed of 2 x 2
superpixel averages of u (except if MIN or MAX keyword is
set, see above)
AUTHOR: Paul Ricchiazzi 26 May 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/degrade.pro)
ROUTINE dens2d,x,y,g,nbins=nbins,xrange=xrange,yrange=yrange,$
title=title,xtitle=xtitle,ytitle=ytitle,psym=psym,$
grid=grid,tvim=tvim,scale=scale,contur=contur
PURPOSE Compute and/or display the density function of a 2-d scatter
of points with coordinate x and y
INPUTS:
x array of values
y array of values (same size as x)
OUTPUTS:
g 2-d histogram array of size nbins(0) x nbins(1)
OPTIONAL INPUTS (keyword parameters):
nbins 1 or 2 element vector, number of bins in x and y direction
default is (20,20)
xrange 2 element vector, binning range in x direction
yrange 2 element vector, binning range in y direction
charsize character size
title plot title
xtitle x axis label
ytitle y axis label
psym symbol used for scatter plot, if negative don't plot points
grid if set, show binning grid
contur if set, draw in density contours (default)
confill if set, use CONFILL is used to draw contours
tvim if set, use TVIM to display the point density function
if tvim is set to 1 image is smoothed
if tvim is set to 2 image is not smoothed
scale if set, draw in a color scale
0=> no color scale
1=> regular color scale (default)
2=> stepped color scale
EXAMPLE
x=randomn(is,2000)
y=4*randomn(is,2000) + x^3
dens2d,x,y,g,/tvim,/grid
dens2d,x,y,/tvim,/contur
dens2d,x,y,psym=-1,/contur
AUTHOR: Paul Ricchiazzi, Earth Space Research Group, sep92
(See /home/drw/idl/esrg/dens2d.pro)
ROUTINE dens2d,x,y,g,nbins=nbins,xrange=xrange,yrange=yrange,$
title=title,xtitle=xtitle,ytitle=ytitle,psym=psym,$
grid=grid,tvim=tvim,scale=scale,contur=contur
PURPOSE Compute and/or display the density function of a 2-d scatter
of points with coordinate x and y
INPUTS:
x array of values
y array of values (same size as x)
OUTPUTS:
g 2-d histogram array of size nbins(0) x nbins(1)
OPTIONAL INPUTS (keyword parameters):
nbins 1 or 2 element vector, number of bins in x and y direction
default is (20,20)
xrange 2 element vector, binning range in x direction
yrange 2 element vector, binning range in y direction
charsize character size
title plot title
xtitle x axis label
ytitle y axis label
psym symbol used for scatter plot, if negative don't plot points
grid if set, show binning grid
contur if set, draw in density contours (default)
confill if set, use CONFILL is used to draw contours
tvim if set, use TVIM to display the point density function
if tvim is set to 1 image is smoothed
if tvim is set to 2 image is not smoothed
scale if set, draw in a color scale
0=> no color scale
1=> regular color scale (default)
2=> stepped color scale
EXAMPLE
x=randomn(is,2000)
y=4*randomn(is,2000) + x^3
dens2d,x,y,g,/tvim,/grid
dens2d,x,y,/tvim,/contur
dens2d,x,y,psym=-1,/contur
AUTHOR: Paul Ricchiazzi, Earth Space Research Group, sep92
(See /home/drw/idl/old.esrg/dens2d.pro)
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: DENS_PLOTTER
PURPOSE:
A widget-based routine to allow the analysis of density sensitive
ratios.
EXPLANATION:
DENS_PLOTTER computes line emissivities for an ion (specified
on the command line) at the T_max of the ion and at a number of
densities. The routine then allows line ratios relative to a
particular line (called the `denominator line') to be viewed. One
can either choose a particular numerator, or one can simply view
all ratios within a specified wavelength range (see the button widget
just above the main plot window).
In the former case, the numerator line can be chosen either from the
strongest lines, or from all lines within a specified wavelength range.
A wavelength range is selected via the sliders at the lower left of
the main widget.
When a particular numerator line has been selected, observed
intensities (and error bars) for both the denominator and numerator
can be input, and the derived density (plus error bars) can be seen
on the plot, or in a text widget (see the `SHOW DERIVED DENSITIES'
button).
The accuracy of the derived density is limited by the density
intervals in the emissivity calculation. The starting interval
is 0.5. To obtain improved accuracies, go to the upper portion of
the main widget, and select a new density interval of 0.1 with the
button widget. Clicking on `Calculate emissivity' will recalculate
the emissivities, and the plot updated
Also with the emissivity widget, one can select new density limits
(with the sliders), input a new temperature, and also photoexcitation
to be included in the level balance. For the latter, a non-zero
dilution factor should be input.
CALLING SEQUENCE:
DENS_PLOTTER, IZ, ION [ , EM, PATH=PATH ]
EXAMPLES:
DENS_PLOTTER, 26, 13 ; Fe XIII
DENS_PLOTTER, 10, 6 ; Ne VI
DENS_PLOTTER, 26, 13, PATH='/home/new_chianti_data'
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
OPT. INPUTS:
EM: Save the displayed emissivities to structure EM. This
structure is simply the structure EMISS_SELECT used in
the routine.
PATH: Data in the CHIANTI format that is not in the CHIANTI
database can be read by specifying the directory in which
it lies through PATH.
CALLS:
EMISS_CALC, READ_IONEQ, EMISS_SELECT
HISTORY:
Ver.1: PRY, 15-SEP-97.
Ver.2: PRY, 6-JUL-98, added EM and PATH
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/dens_plotter.pro)
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: DENS_PLOTTER
PURPOSE:
A widget-based routine to allow the analysis of density sensitive
ratios.
EXPLANATION:
DENS_PLOTTER computes line emissivities for an ion (specified
on the command line) at the T_max of the ion and at a number of
densities. The routine then allows line ratios relative to a
particular line (called the `denominator line') to be viewed. One
can either choose a particular numerator, or one can simply view
all ratios within a specified wavelength range (see the button widget
just above the main plot window).
In the former case, the numerator line can be chosen either from the
strongest lines, or from all lines within a specified wavelength range.
A wavelength range is selected via the sliders at the lower left of
the main widget.
When a particular numerator line has been selected, observed
intensities (and error bars) for both the denominator and numerator
can be input, and the derived density (plus error bars) can be seen
on the plot, or in a text widget (see the `SHOW DERIVED DENSITIES'
button).
The accuracy of the derived density is limited by the density
intervals in the emissivity calculation. The starting interval
is 0.5. To obtain improved accuracies, go to the upper portion of
the main widget, and select a new density interval of 0.1 with the
button widget. Clicking on `Calculate emissivity' will recalculate
the emissivities, and the plot updated
Also with the emissivity widget, one can select new density limits
(with the sliders), input a new temperature, and also photoexcitation
to be included in the level balance. For the latter, a non-zero
dilution factor should be input.
CALLING SEQUENCE:
DENS_PLOTTER, IZ, ION [ , EM, PATH=PATH ]
EXAMPLES:
DENS_PLOTTER, 26, 13 ; Fe XIII
DENS_PLOTTER, 10, 6 ; Ne VI
DENS_PLOTTER, 26, 13, PATH='/home/new_chianti_data'
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
OPT. INPUTS:
EM: Save the displayed emissivities to structure EM. This
structure is simply the structure EMISS_SELECT used in
the routine.
PATH: Data in the CHIANTI format that is not in the CHIANTI
database can be read by specifying the directory in which
it lies through PATH.
CALLS:
EMISS_CALC, READ_IONEQ, EMISS_SELECT
HISTORY:
Ver.1: PRY, 15-SEP-97.
Ver.2: PRY, 6-JUL-98, added EM and PATH
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/ptg/dens_plotter.pro)
The point? To fit the line profiles at the bottom of the loop i.e. at points (809,548) & (905,607), and to do these separately so that we're not trying to fit an average of the line profiles at these 2 points, and applying this generic fit to each in turn. Rather, it's better to sort out each fit for each point separately so we can get a better idea of the idealised Gaussians and see if the various density-sensitive lines vary as they should do PARAMETERS NEEDED: both fits AND spectra at the top and footpoint
(See /home/drw/idl/cds/den_diff_loop.pro)
ROUTINE: den_loop
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: den_loop,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(See /home/drw/idl/cds/den_loop.pro)
ROUTINE: den_loop2
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: den_loop,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(See /home/drw/idl/cds/den_loop2.pro)
ROUTINE: den_loop3
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: den_loop3,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
modified to den_loop3 by DRW for SECIS-relevant
data.
(See /home/drw/idl/cds/den_loop3.pro)
ROUTINE: den_loop3
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: den_loop3,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
modified to den_loop3 by DRW for SECIS-relevant
data.
(See /home/drw/idl/cds/den_loop4.pro)
ROUTINE: den_subloop
PURPOSE: work out the densities for the plasma _bounded_
(or beneath) the 1st SECIS loop.
USEAGE: den_subloop,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
modified to den_loop3 & den_subloop by DRW for
SECIS-relevant data.
(See /home/drw/idl/cds/den_subloop.pro)
ROUTINE: den_superloop
PURPOSE: work out the densities for the plasma around
(or `above') the 1st SECIS loop.
USEAGE: den_subloop,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
modified to den_loop3 & den_subloop by DRW for
SECIS-relevant data.
(See /home/drw/idl/cds/den_superloop.pro)
ROUTINE: den_upper3
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347) (upper raster to take in our loop)
USAGE: den_loop3,qldsu,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
modified to den_loop3 by DRW for SECIS-relevant
data.
(See /home/drw/idl/cds/den_upper3.pro)
Project:
SOHO - SUMER
Name:
destretch
Purpose:
Apply distortion correction to sumer data
Use:
data_out = destretch(data,slit,RefPix,detector)
Inputs
Data - data to be destretched. 1 2-d array
Slit - Number of Slit used
RefPix - Refernce Pixel for the wavelength. Should be either
the actual reference pixel or the reference co-pixel +1
(the latter is in the binary fits header)
Det - Detector type, 'a' or 'b'
Keyword Input:
Quiet - supress the general information printed out at start of program
Keyword Output:
delta - the delta arrray
Output
Data_Out - destretched data
Restrictions:
This program should NOT be used on data which has been binned or
subject to compression schemes 6 and up.
The delta x and y files must be in a directory called by the logical
name 'sumer_calib'.
For example, to set the logical name from within IDL,
IDL> setenv,'SUMER_CALIB = files_directory ' , where the delta files are
contained in files_directory.
Written:
Tom Moran, July 15, 1996
Changes Oct, 3 1996:
Corrected in case where full 1024 pixels used
Comon block added & some of file reading logic changed
Quiet keyword introduced
Changes Dec 3, 1996:
Program can now destretch data from either detector A or B
Files called by Destretch must now be in directory defined
by logical SUMER_CALIB. These files are:
del_x_at.dat, del_x_bt.dat, del_y_at.dat, del_y_bt.dat,
size_fac.dat
Deals correctly with cases in which 120" slit is
used with 360 Y-direction formats
Zarro, 22-Dec-1998 -- removed har-w
(See /home/drw/idl/anaidl/destretchn.pro)
Project:
SOHO - SUMER
Name:
destretch
Purpose:
Apply distortion correction to sumer data
Use:
data_out = destretch(data,slit,RefPix,detector)
Inputs
Data - data to be destretched. 1 2-d array
Slit - Number of Slit used
RefPix - Refernce Pixel for the wavelength. Should be either
the actual reference pixel or the reference co-pixel +1
(the latter is in the binary fits header)
Det - Detector type, 'a' or 'b'
Keyword Input:
Quiet - supress the general information printed out at start of program
Keyword Output:
delta - the delta arrray
Output
Data_Out - destretched data
Restrictions:
This program should NOT be used on data which has been binned or
subject to compression schemes 6 and up.
The delta x and y files must be in a directory called by the logical
name 'sumer_calib'.
For example, to set the logical name from within IDL,
IDL> setenv,'SUMER_CALIB = files_directory ' , where the delta files are
contained in files_directory.
Written:
Tom Moran, July 15, 1996
Changes Oct, 3 1996:
Corrected in case where full 1024 pixels used
Comon block added & some of file reading logic changed
Quiet keyword introduced
Changes Dec 3, 1996:
Program can now destretch data from either detector A or B
Files called by Destretch must now be in directory defined
by logical SUMER_CALIB. These files are:
del_x_at.dat, del_x_bt.dat, del_y_at.dat, del_y_bt.dat,
size_fac.dat
Deals correctly with cases in which 120" slit is
used with 360 Y-direction formats
Zarro, 22-Dec-1998 -- removed har-w
(See /home/drw/idl/anaidl/linux/destretchn.pro)
Project:
SOHO - SUMER
Name:
destretch
Purpose:
Apply distortion correction to sumer data
Use:
data_out = destretch(data,slit,RefPix,detector)
Inputs
Data - data to be destretched. 1 2-d array
Slit - Number of Slit used
RefPix - Refernce Pixel for the wavelength. Should be either
the actual reference pixel or the reference co-pixel +1
(the latter is in the binary fits header)
Det - Detector type, 'a' or 'b'
Keyword Input:
Quiet - supress the general information printed out at start of program
Keyword Output:
delta - the delta arrray
Output
Data_Out - destretched data
Restrictions:
This program should NOT be used on data which has been binned or
subject to compression schemes 6 and up.
The delta x and y files must be in a directory called by the logical
name 'sumer_calib'.
For example, to set the logical name from within IDL,
IDL> setenv,'SUMER_CALIB = files_directory ' , where the delta files are
contained in files_directory.
Written:
Tom Moran, July 15, 1996
Changes Oct, 3 1996:
Corrected in case where full 1024 pixels used
Comon block added & some of file reading logic changed
Quiet keyword introduced
Changes Dec 3, 1996:
Program can now destretch data from either detector A or B
Files called by Destretch must now be in directory defined
by logical SUMER_CALIB. These files are:
del_x_at.dat, del_x_bt.dat, del_y_at.dat, del_y_bt.dat,
size_fac.dat
Deals correctly with cases in which 120" slit is
used with 360 Y-direction formats
Zarro, 22-Dec-1998 -- removed har-w
(See /home/drw/idl/aux/destretchn.pro)
PROJECT:
CHROMOSPHERIC OSCILLATIONS, QUB
NAME:
DIGIFILT
PURPOSE:
To filter a time series (either high , low or band) and return
the filtered time series. It carries this out by convolving the time series
with a bessel shaped kernel. The kernel is created by digital_filter
"/usr/local/rsi/idl/lib/digital_filter.pro"
The convolution is carried out by convol, an inbuilt IDL routine
By default prints out the power of peaks in the filtered power spectrum
USEAGE:
digifilt,timeseries,filtered_timeseries
INPUTS:
timeseries - the original unfiltered time series
KEYWORD INPUTS:
num - the number of peaks in the power spectrum you wish to pick
out. Set this to a maximum of half the number of points in
time series. this will print out the peaks in order of
power, defaults to 5
delta - the cadence of the time series, defaults to 45 seconds
nodisp - turns off the display of the FFT's
profile - shows the filter profile
def_prof- presents the user with an opportunity to input filter
profile parameters. Best used with profile keyword
fish - prints out the fish g-factor
OUTPUTS:
filtered_timeseries - the filtered time series
PROGRAM INPUT DEFAULTS
num - number of peaks printed out
delta - the time seperation of the time series, default 45
f_hi - the high frequency cutoff, default nyquist frequency
f_lo - the low frequency cutoff, default 0.0005
a - input to digital_filter
in effect increasing this smoothes of the edge of the
filter.(i.e. it falls less sharp)
it also decreases the number of 'wiggles' after the edge
nt - input to digital_filter
in effect increasing this makes the filter edge more abrupt
also increases the number of wiggles after the filter
For a pictorial explanation run this batch file
/home/jma/idl/vtt/post_bbso/test_filt.bat
TO DO: 1)possible furthur increases to generic use
HISTORY:
v1.0 - written by James McAteer and Peter Gallagher in Big Bear, CA
(08/01) in its original filt.pro
/home/jma/idl/vtt/jma/filt.pro
v2.0 - Changed to /home/jma/idl/vtt/post_bbso/filt2.pro
Adjustments and alteration by JMA to make it more generic (09/01)
v2.1 - JMA added in SIGNIF keyword after signif.pro (09/01)
v2.2 - JMA added des_power,signif_fts,fish,origpeaks,num
and removed the 'time' input from the call line (09/01)
v3.0 - JMA and David Williams finally understand exactly what filtering is
doing
fts = convol( ts, kernel, /edge_truc ) changed to
fts = convol( ts, kernel, /edge_wrap ).
Filtering can be checked by dividing filtered power spectrum by the
original power spectrum. Also now understand what a and nt are
doing
Best to maximise nt and a (although this increases computational
time) (11/01)
v3.1 - JMA added in ,/nodisp and ,/profile keywords (01/02)
v4.0 - Changed to /home/jma/idl/vtt/post_bbso/digifilt.pro
extinct keywords removed and input keywords created to increase
generic use.
user can now change profile shape with def_prof
Calls program fourier.pro instead of pgfft.pro
(See /home/drw/idl/vtt/post_bbso/digifilt.pro)
PROJECT:
CHROMOSPHERIC OSCILLATIONS, QUB
NAME:
DIGIFILT
PURPOSE:
To filter a time series (either high , low or band) and return
the filtered time series. It carries this out by convolving the time series
with a bessel shaped kernel. The kernel is created by digital_filter
"/usr/local/rsi/idl/lib/digital_filter.pro"
The convolution is carried out by convol, an inbuilt IDL routine
By default prints out the power of peaks in the filtered power spectrum
USEAGE:
digifilt,timeseries,filtered_timeseries
INPUTS:
timeseries - the original unfiltered time series
KEYWORD INPUTS:
num - the number of peaks in the power spectrum you wish to pick
out. Set this to a maximum of half the number of points in
time series. this will print out the peaks in order of
power, defaults to 5
delta - the cadence of the time series, defaults to 45 seconds
nodisp - turns off the display of the FFT's
profile - shows the filter profile
def_prof- presents the user with an opportunity to input filter
profile parameters. Best used with profile keyword
fish - prints out the fish g-factor
OUTPUTS:
filtered_timeseries - the filtered time series
PROGRAM INPUT DEFAULTS
num - number of peaks printed out
delta - the time seperation of the time series, default 45
f_hi - the high frequency cutoff, default nyquist frequency
f_lo - the low frequency cutoff, default 0.0005
a - input to digital_filter
in effect increasing this smoothes off the edge of the
filter
it also decreases the number of 'wiggles' after the edge
nt - input to digital_filter
in effect increasing this makes the filter edge more abrupt
also increases the number of wiggles after the filter
For a pictorial explanation run this batch file
/home/jma/idl/vtt/post_bbso/test_filt.bat
TO DO: 1)possible furthur increases to generic use
HISTORY:
v1.0 - written by James McAteer and Peter Gallagher in Big Bear, CA
(08/01) in its original filt.pro
/home/jma/idl/vtt/jma/filt.pro
v2.0 - Changed to /home/jma/idl/vtt/post_bbso/filt2.pro
Adjustments and alteration by JMA to make it more generic (09/01)
v2.1 - JMA added in SIGNIF keyword after signif.pro (09/01)
v2.2 - JMA added des_power,signif_fts,fish,origpeaks,num
and removed the 'time' input from the call line (09/01)
v3.0 - JMA and David Williams finally understand exactly what filtering is
doing
fts = convol( ts, kernel, /edge_truc ) changed to
fts = convol( ts, kernel, /edge_wrap ).
Filtering can be checked by dividing filtered power spectrum by the
original power spectrum. Also now understand what a and nt are
doing
Best to maximise nt and a (although this increases computational
time) (11/01)
v3.1 - JMA added in ,/nodisp and ,/profile keywords (01/02)
v4.0 - Changed to /home/jma/idl/vtt/post_bbso/digifilt.pro
extinct keywords removed and input keywords created to increase
generic use.
user can now change profile shape with def_prof
Calls program fourier.pro instead of pgfft.pro
(See /home/drw/idl/jma/digifilt.pro)
ROUTINE: digitize
PURPOSE: digitize hardcopy graphical information.
USEAGE: digitize,x,y
INPUT: none
KEYWORD INPUT:
xr x axis range of hardcopy plot, prompted for if not supplied
yr y axis range of hardcopy plot, prompted for if not supplied
OUTPUT:
x vector of x coordinate values
y vector of y coordinate values
PROCEDURE: 1. make a photo copy of the graph on tranparency film.
2. IDL> DIGITIZE,x,y,xr=xr,yr=yr
where xr and yr are the x and y axis range.
3. align the hard copy graph onto the axis drawn by DIGITIZE
and use scotch tape to stick the film onto your screen
4. click with LMB on the axis end points (will prompt)
5. trace over the plot with cursor, LMB adds points, MMB
erases points and RMB exits the program
NOTE: Because the outer glass surface of the screen is not
on the same plane as the displayed image their is a
slight parallax effect between the tranparency and the
DIGITIZE grid. The parallax error is minimized by
keeping your line of sight normal to the screen.
EXAMPLE:
digitize,x,y ; try it
plot,x,y
REVISIONS:
author: Paul Ricchiazzi sep93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/digitize.pro)
ROUTINE: digitize
PURPOSE: digitize hardcopy graphical information.
USEAGE: digitize,x,y
INPUT: none
KEYWORD INPUT:
xr x axis range of hardcopy plot, prompted for if not supplied
yr y axis range of hardcopy plot, prompted for if not supplied
OUTPUT:
x vector of x coordinate values
y vector of y coordinate values
PROCEDURE: 1. make a photo copy of the graph on tranparency film.
2. run DIGITIZE and enter the x and y axis range.
3. align the hard copy graph onto the axis drawn by DIGITIZE
and use scotch tape to stick the film onto your screen
4. click with LMB on the axis end points (will prompt)
5. trace over the plot with cursor, LMB adds points, MMB
erases points and RMB exits the program
NOTE: Because the outer glass surface of the screen is not
on the same plane as the displayed image their is a
slight parallax effect between the tranparency and the
DIGITIZE grid. The parallax error is minimized by
keeping your line of sight normal to the screen.
EXAMPLE:
digitize,x,y ; try it
plot,x,y
REVISIONS:
author: Paul Ricchiazzi sep93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/digitize.pro)
ROUTINE: disp
USEAGE: disp,a
disp,a,scale=scale,range=range,xrange=xrange,yrange=yrange,$
aspect=aspect,title=title,xtitle=xtitle,ytitle=ytitle,$
noaxis=noaxis,interp=interp,colors=colors,c_map=c_map,$
stitle=stitle,rmarg=rmarg,clip=clip,labels=labels,$
pcharsize=pcharsize,lcharsize=lcharsize,nbotclr=nbotclr,&
clevels=clevels,nodata=nodata,rgb_nodata=rgb_nodata,$
barwidth=barwidth,position=position,noframe=noframe,rct=rct
PURPOSE: Display an image with provisions for
1. numbered color scale
2. plot title
3. annotated x and y axis
4. simplified OPLOT capability
5. manual or automatic scaling with smooth or discreet colors
6 special treatment of "invalid data" pixels
INPUT
a image quantity
Optional keyword input:
title
plot title
xtitle
x axis title
ytitle
y axis title
stitle
color key title (drawn to the right of color scale)
rmarg
right margin expansion factor to provide more room for extra wide
color scale annotation (default=1)
xrange
array spanning entire x axis range. (default = [0,x_dimension-1])
yrange
array spanning entire y axis range. (default = [0,y_dimension-1])
NOTE:TVIM only uses min(XRANGE), max(XRANGE), min(YRANGE) and max(YRANGE).
scale
if set draw color scale. SCALE=2 causes steped color scale
range
two or three element vector indicating physical range over which
to map the color scale. The third element of RANGE, if specified,
sets the step interval of the displayed color scale. It has no
effect when SCALE is not set. E.g., RANGE=[0., 1., 0.1] will
cause the entire color scale to be mapped between the physical
values of zero and one; the step size of the displayed color
scale will be set to 0.1.
clip
specifies a set percentage of pixels which will be left outside
the color scale. Larger values of CLIP yield images with greater
contrast. For example if clip=2 then the color scale range will
be set to include 98% of the pixels and to exclude the brightest
1% and the dimmest 1% of the pixel brightness distribution.
Keyword RANGE overides the effect of CLIP.
If CLIP is a two element vector, the upper and lower percentile
range can be specified. For example CLIP=[0,95] will exclude the
top 5%.
An alternative is to set CLIP to a single negative integer. This
causes the grey scale range to be obtained from the max and min
value of the image array after it is filtered by a 2-D median
filter. The radius of the median filter is set to -clip. Median
filtering is effective in removing "salt and pepper" noise,
(isolated high or low values). For example, setting clip=-1
causes the code to check the 9 element superpixel centered at
each pixel for median values. A single extremely large or small
value does not affect the final value of the median at each pixel
point.
aspect
the x over y aspect ratio of the output image. If not set, aspect
is set to (size_x/size_y) of the input image.
position
specifies the lower left and upper right TVIM frame position in
normal coordinates. When set POSITION overides the setting of
ASPECT.
noaxis
if set do not draw x and y numbered axis around image. Instead
just draw a box
noframe
if set no not draw anything around image, not even a box
interp
TVIM normally uses nearest neighbor sampling to resize the image
to fill the data window area. If INTERP is set the resizing
operation uses bilinear interpolation
If INTERP = 2 the interpolation range is adjusted so that there
is a half pixel border around the plot. This ensures that the
smoothed image properly represents the cell center values of the
pixels, but introduces an extrapolation on the outer edges. This
option has noticeable effects for small (<20) image arrays.
NOTE: When writing to a Postscript file the resizing operation is
accomplished by changing the pixel size. Thus the INTERP
parameter has no effect on Postscript output.
pcharsize
character size of numbers along x and y axis and the title
(default is !p.charsize if non-zero, 1 otherwise)
NOTE: The character size of the x and y-axis number scale
annotation may be independently controlled by the !x.charsize or
!y.charsize system variables. For example, the x and y axis
number scale characters may be made invisible by setting these
variables to a very small non-zero number before calling TVIM.
Remember to restore normal character sizes by setting !x.charsize
and !y.charsize to 1 or zero after the call to TVIM.
lcharsize
character size of color key number or labels (default is
!p.charsize if non-zero, 1 otherwise)
barwidth
width of color key which appears to right of image when SCALE is
set. (default=1)
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies. When the COLORS array is set TVIM
will map values of A into the color values specified in COLORS.
How physical values are assigned to color values depends on how
the RANGE parameter is set, as shown in this table:
RANGE color_value
----- -----------
1. not set COLORS(A)
2. [amin,amax] COLORS((A-amin)/dinc)
3. [amin,amax,inc] COLORS((A-amin)/inc)
where amin, amax and inc are user specified elements of RANGE
and dinc=(amax-amin)/n_elements(COLORS). In case 1, A is used
directly as a subscript into COLORS. When RANGE is not set
legend labels should be used to annotate the color values. In
case 2, A is scaled so that each color defined in COLORS
represents a proportionate fraction of the total dynamic range.
In case 3, amin and inc (and not amax) are used to control which
colors are associated with given physical values. See examples.
c_map
TVIM normally rescales the input image to span the entire color
table range. Setting C_MAP disables this automatic re-scaling.
This is useful when the image byte values correspond to a
particular color mapping that could be destroyed by the
rescaling process (E.G. a gif image).
NOTE: When the number of IDL color table entries is less than
256 some colors may be lost. Use a private color map to avoid
this. See examples.
nbotclr
number of reserved colors at the bottom of the color
table. Color values between 0 and nbotclr-1 will not
be used in the displayed image. This allows the
bottom of the table to be set to special colors which
will not be used in the displayed the image. This
keyword is disabled when either the COLORS or NODATA
options are used. (default=1)
NOTE: by default the color table indicies used within a TVIM
image is limited to the range 1 to !d.n_colors-2. In most
predefined color tables, color index 0 and !d.n_color-1
correspond to pure black and white, respectively. TVIM uses
these color indicies as background and foreground colors for
region blanking and axis annotation. Color tables which do not
define black and white in these index locatations are not good
choices for TVIM plots, unless the first and last color table
entries are redefined as black and white using TVLCT, e.g.,
tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
NOTE: the procedure DCOLORS can be used to load a set
of discreet colors in the bottom 11 color values
(0-10). The original color table is resampled to fit
between color value 11 and the !d.n_colors-1.
nodata
pixel values which are interpreted as invalid data. Pixels
containing this data value are colored with color RGB_NODATA.
rgb_nodata
an RGB value (a 3 component vector) used to color pixels filled
with invalid data. (default = [0,0,0])
NOTE: NODATA and RGB_NODATA override the effect of NBOTCLR
rct
if set, reverse direction of color table. This keyword can be
used on black & white printers to allow large field values to be
represented by dark colors.
KEYWORD OUTPUT:
clevels
physical values at the color key tic marks. Use this to set
contour levels in a subsequent call to CONTOUR.
SIDE EFFECTS:
Setting SCALE=2 changes the color scale using the STEP_CT
procedure. The color scale may be returned to its original
state by the command, STEP_CT,/OFF
PROCEDURE:
TVIM first determines the size of the plot data window with a
dummy call to PLOT. When the output device is "X", CONGRID is
used to scale the image to the size of the available data
window. Otherwise, if the output device is Postscript,
scaleable pixels are used in the call to TV.
If the input image quantity is not of type byte, TVIM converts
them to byte by scaleing the input between 0 and !d.n_colors-1.
If the input is already a byte array and if either the number of
color table entries is 256 or if C_MAP is set, then no scaling
is done. This is to ensure consistency with specially defined
private color tables.
After the the image is drawn TVIM calls PLOT again to draw the x
and y axis and titles. Finally if scale is set, TVIM calls the
COLOR_KEY procedure to draw the color scale just to the right of
the data window.
RESTRICTIONS:
A stepped color scale (SCALE = 2 option) is not available when
writing to a black & white postscript file (i.e., when the
DEVICE color option is not enabled).
DEPENDENCIES: COLOR_KEY, STEP_CT, PRANK
EXAMPLES:
; Plot a GIF image with its own preset RGB
; table (perhaps from a digitized video image)
window,colors=256 ; set up a private color map
read_gif,file,im,r,g,b
tvlct,r,g,b
tvim,im,/c_map
;
;
; Plot an image with descreet greyscale values to a printer
; which has its own hard-wired color table.
im=randata(128,128,s=4)
immx=max(im) & immn=min(im)
!p.multi=[0,2,2]
tvim,im,/scale,colors=!p.color*indgen(4)/3.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(5)/4.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(8)/7.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(10)/9.,range=[immn,immx]
;
;
; Display a map of surface types (green=veg, blue=water, red=sand)
; Notice how RANGE is used to associate physical values with colors.
; (use im from the previous example)
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
tvlct,[0,0,0,255],[0,255,0,0],[0,0,255,0]
!p.multi=[0,2,2]
colors=[1,2,3] & labels=[' veg',' water',' sand']
range=[immn,immx,delim/3]
tvim,im,/scale
tvim,im,colors=colors,range=range,/scale
tvim,im,colors=colors,range=range,/scale,labels=labels,lch=2
!p.multi=0
range=[immn-.25*delim,immx+.25*delim,delim/2]
lbl=[' veg!c region 1',' water!c region 2',' sand!c region 3']
tvim,im,colors=colors,range=range,/scale,labels=lbl,lch=2,rmarg=2,pchar=1.2
;
;
; Display the image from previous example and overlay a contour plot
;
loadct,5
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
xrange=[-120,-100]
yrange=[20,50]
range=[immn,immx]
xx=findrng(xrange,128)
yy=findrng(yrange,128)
tvim,im,/scale,xrange=xrange,yrange=yrange,clevels=clevels,range=range
contour,im,xx,yy,levels=clevels,/overplot
; NOTE: You might prefer the results obtained from procedure CONFILL.
confill,im,xx,yy,/asp,levels=clevels
;
;
; Display a grey scale image and annotate certain points in color
;
loadct,0
dcolors
tvim,im,/scale,nbotclr=11
xx=interpolate([40,80],randomu(iseed,10))
yy=interpolate([40,80],randomu(iseed,10))
plots,xx,yy,psym=2,color=1+indgen(10)
;
;
; Display a grey scale image and show nodata values in red
;
loadct,0
im=randata(100,100,s=4.5)
im(randomu(iseed,50)*9999)=-999.
tvim,im,/scale,nodata=-999.,rgb_nodata=[255,0,0]
;
;
; Postscript output with a reversed color scale. Because the
; background color is always RGB=(255,255,255) you must set the
; default color, !p.color, to a dark color if you want good contrast
; between the axis labels and the white paper. According to
; Didier's reversed color table a color index of 255 should produce
; black, but for some reason !p.color=255 doesn't work right.
; I think IDL is iterpreting !p.color=255 in some special way.
; So instead use !p.color=254; this seems to work fine.
;
toggle,/color
loadct,28
!p.color=254 ; don't use 255, don't ask me why
tvim,dist(20),/scale
toggle
;
; display data defined on a regular LAT-LON grid onto a given map
; projection. USE MAP_SET and MAP_IMAGE to create the map projection
; and to warp the image. Then use BOXPOS to position the TVIM frame
; to correctly register the map and image
IMAGE = sin(!pi*findrng(0,24,200))#sin(!pi*findrng(0,12,200))
!p.multi=[0,1,2]
map_set,45,0,/ortho,/advance,pos=boxpos(/aspect)
newimage=map_image(image,/bilin,latmin=-90,latmax=90,lonmin=-180,lonmax=180)
tvim,newimage,title='Warped data',pos=boxpos(/get),/scale
map_set,45,0,/ortho,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
tvim,image,xrange=[-180,180],yrange=[-90,90],/scale, $
title='Unwarped data',xtitle='Longitude',ytitle='Latitude'
map_set,0,0,/cyl,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
; use MAP_SET2 to mask out land areas. Note that the example below is
; unusual. MAP_SET2 doesn't always produce such nicely filled land areas.
; Typically one must run MAP_SET2 with /SAVE
; to create a ascii file containing the continental boundary lat-lon
; coordinates. Then use an editor to group the continental coordinates
; line segments to form closed contours which POLYFILL can understand
; (the call to POLYFILL is enabled by setting con_color).
;
image=randata(256,256,s=2.5)
tvim,image
map_set2,-64,-64,/cont,limit=[-65.1,-64.5,-64,-62],/ortho,con_col=100,$
pos=boxpos(/get),/noerase,/grid
;
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS:
28jan93: switched from PUT_COLOR_SCALE to COLOR_KEY
11feb93: added INTERP keyword
11feb93: added C_MAP keyword
11feb93: added STITLE keyword
20apr93: added RMARG keyword, centered image in plot window
23apr93: call COLOR_KEY before TV. Now stepped color scales copy to PS file
10sep93: deal with perfectly flat images. No more math error when a=0
14sep93: added CLIP keyword
11feb94: added PCHARSIZE,LCHARSIZE,LABELS, and COLORS keywords
18feb94: added NBOTCLR keyword
16mar94: added INTERP=2 option and adjusted centering of pixels
08Jul94: added NODATA and RGB_NODATA keywords
04Aug94: added BARWIDTH keyword
04Aug94: defaulted PCHARSIZE and LCHARSIZE to !P.CHARSIZE if non-zero
02Mar95: added POSITION keyword
31Mar95: added NOAXIS keyword
24may95: initial sizing includes allowance for PCHARSIZE > 1
06sep95: color indecies used in plot now run from 1 to !d.ncolors-2
24jul96: do a REFORM(a) to allow tvim,a(1,*,*)
(See /home/drw/idl/old.esrg/disp.pro)
ROUTINE: dist
PURPOSE: finds the cross-over points/closest points of two arrays
USEAGE: result = dist(x1,x2)
INPUT:
x1 1-D array
x2 1-D array of same dimension as x1
OUTPUT: result is an array giving the point(s) of intersection of
the two arrays.
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/old.esrg/dist.pro)
NAME: DISTANG PURPOSE: Give the distance between two points and the angle their connecting line makes with the horizontal. More useful than clever, this one. USAGE: distang,x1,y1,x2,y2,distance=distance,angle=angle
(See /home/drw/idl/gen/distang.pro)
ROUTINE: dockey
PURPOSE: display help documententation of file headers which
contain matches for specified keywords
USEAGE: dockey,'name',keyword=keyword,all=all,minmatch=minmatch
INPUT:
keywords keyword string. Keywords withing the KEYWORDS must be
separated by blanks.
KEYWORD_INPUT
minmatch the minimum number of keyword hits required for a procedure
to be listed in the hit-list menu.
PROCEDURE: DOCKEY searches through the helpfiles in subdirectory
/local/idl/help, trying to find matches for the keywords.
If more than one file match is found a menu of procedure
names is displayed from which the desired procedure
can be selected. The parenthisized number next to each
procedure name is the number of keyword matches, which
can vary between one to the total number of keywords in
KEYWORDS.
MAN_PROC is used to display the text
EXAMPLE:
dockey,'simpson rule integration'; pick group 'numerical'
dockey,'polar orthographic' ; pick group 'esrg'
dockey,'color key image',m=2 ; pick group 'color'
;
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/dockey.pro)
ROUTINE: dockey
PURPOSE: display help documententation of file headers which
contain matches for specified keywords
USEAGE: dockey,'name',keyword=keyword,all=all,minmatch=minmatch
INPUT:
keywords keyword string. Keywords withing the KEYWORDS must be
separated by blanks.
KEYWORD_INPUT
minmatch the minimum number of keyword hits required for a procedure
to be listed in the hit-list menu.
PROCEDURE: DOCKEY searches through the helpfiles in subdirectory
/local/idl/help, trying to find matches for the keywords.
If more than one file match is found a menu of procedure
names is displayed from which the desired procedure
can be selected. The parenthisized number next to each
procedure name is the number of keyword matches, which
can vary between one to the total number of keywords in
KEYWORDS.
MAN_PROC is used to display the text
EXAMPLE:
dockey,'simpson rule integration'; pick group 'numerical'
dockey,'polar orthographic' ; pick group 'esrg'
dockey,'color key image',m=2 ; pick group 'color'
;
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/dockey.pro)
ROUTINE: doc
PURPOSE: find and display help for a named procedure
USEAGE: doc,'name'
INPUT:
name name of idl .pro file. Asterisk characters, "*", in NAME
specify wild card matches to 1 or more arbitrary characters.
PROCEDURE: DOC searches through the files /local/idl/help/*.help
trying to find matches for the file specification, NAME.
if there are no matches a brief failure message is displayed
and control returns to the terminal
if 1 match is found, help for the specified procedure is
displayed and control returns to the terminal
if 2 or more matches are found a menu is generated
from which selections can be made. Control returns to
the terminal when the DONE button of the MENUW widget
is pressed.
EXAMPLE:
doc,'legend' ; exact match found in ESRG_LOCAL
doc,'tv*' ; many matches found, browse through
; choices. Notice that all procedure
; libraries are searched
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/doc.pro)
ROUTINE: doc
PURPOSE: find and display help for a named procedure
USEAGE: doc,'name'
INPUT:
name name of idl .pro file. Asterisk characters, "*", in NAME
specify wild card matches to 1 or more arbitrary characters.
PROCEDURE: DOC searches through the files /local/idl/help/*.help
trying to find matches for the file specification, NAME.
if there are no matches a brief failure message is displayed
and control returns to the terminal
if 1 match is found, help for the specified procedure is
displayed and control returns to the terminal
if 2 or more matches are found a menu is generated
from which selections can be made. Control returns to
the terminal when the DONE button of the MENUW widget
is pressed.
EXAMPLE:
doc,'legend' ; exact match found in ESRG_LOCAL
doc,'tv*' ; many matches found, browse through
; choices. Notice that all procedure
; libraries are searched
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/doc.pro)
NAME:
dplot_nar
PURPOSE:
To plot positions of NOAA Active Regions on a heliocentric
grid (modified by DRW to allow printing to file).
CALLING SEQUENCE:
plot_nar, roadmap(i)
plot_nar, index(i)
plot_nar, '30-oct-91'
INPUT:
ref_item - The reference time to which all feature coordinates
will be differentially rotated before plotting on the grid.
Form can be:
(1) structure with a .time and .day field,
(2) standard 7-element external representation,
or (3) a string of the format "hh:mm dd-mmm-yy"
If no date is entered, the current date is used.
The year is not required, but if entered should be
of the form 1-Oct-91 style. The date should be entered
in string style with date first.
OPTIONAL INPUT:
st_item - The start time to search NOAA active region list for
regions. If not passed, only the time entries nearest to
REF_ITEM are plotted.
en_item - The end time to search NOAA active region list for
regions. If not passed, the NOAA data base is searched for
entries between ST_ITEM and REF_ITEM.
OPTIONAL KEYWORD INPUT:
hc - If set, write the results to a temporary file, print
it and delete it.
text - If set, list active region parameters
OUTPUT:
HISTORY:
Written 26-Mar-93 by G. L. Slater
10-may-93 (slf) added pfi_color, pfi_lstyle keywords
1-Jun-93 (MDM) Added correction for the placement of the SXT
PFI window.
21-jun-93 (gal) quick bug fix for case where frontpts are
undefined [e.g. frontpts=where(x_coord ge 0)].
14-Jul-93 (MDM) Added draw_grid common block
16-Oct-93 (MDM) Removed call to GET_SUNCENTER and replaced with
a call to SXT_CEN
3-Jul-94 (SLF) Fix bug in pfi resolution, only do 'uniq' pfis
since pfi code is slow
4-Jul-94 (SLF) use gt_corner_cmd
14-Jul-94 (SLF) Clean up, allow z-buffer, use savesys,restsys
18-Jul-94 (SLF) do uniq pfi outside this routine
29-Mar-96 (GLS) Added /nosavrest to DRAW_GRID call
Corrected wset problem
QUESTIONS, PROBLEMS, THINGS TO DO:
- Properly position window at creation, using screen size
(See /home/drw/idl/gen/dplot_nar.pro)
NAME:
DRAWCOLORS
FILENAME:
drawcolors__define.pro
PURPOSE:
The purpose of this object program is provide a flexible way
to handle and select drawing colors. The program combines
features of two previous programs: GetColor and PickColor,
as well as adding features of its own. Sixteen original
colors are supplied, but users can create any color they
wish using the tools provided.
By default, these 16 colors are defined: Black, Magenta, Cyan, Yellow,
Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal, Gray, White.
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:
General programming.
CALLING SEQUENCE:
colors = Obj_New('DRAWCOLORS')
OPTIONAL INPUT PARAMETERS:
IDL> colors = Obj_New('DRAWCOLORS', red, green, blue, names)
RED -- A 16-element byte vector of red values for the drawing colors.
GREEN -- A 16-element byte vector of green values for the drawing colors.
BLUE -- A 16-element byte vector of blue values for the drawing colors.
NAMES -- A 16-element string vector of names for the drawing colors.
By default, these colors are defined: Black, Magenta, Cyan, Yellow,
Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal, Gray, White.
COMMON BLOCKS:
None.
RESTRICTIONS:
If you are going to use the XCOLORS method, you will need
the XColors program from the Coyote library:
http://www.dfanning.com/programs/xcolors.pro
The program is set up to handle 16 drawing colors. You may
modify the program to have a different number, but you will
have to modify the code in two places: (1) in the drawcolors__define
module and (2) in the INIT method.
FUNCTION METHODS:
COLOR24 ***************************************************************************
Purpose:
Turns a color triple into the equivalent 24-bit color integer value that
can be decomposed into the color.
Definition:
FUNCTION DrawColors::Color24, theColor
Parameters:
theColor -- A 3-element vector, representing a color triple.
Example:
yellow = colors->GetColor("yellow")
yellow24 = colors->Color24(yellow)
GETCOLOR ***************************************************************************
Purpose:
Returns the color triple, color index number, or the
24-bit integer representation, of the asked for color. In
normal operation, the colors are: Black, Magenta, Cyan, Yellow,
Green, Red, Blue, Navy, Aqua, Pink, Orchid, Sky, Beige, Charcoal,
Gray, and White.
Definition:
FUNCTION DrawColors::GetColor, theColor, startIndex, INDEXNUMBER=indexnumber, $
TRUECOLOR=truecolor, AutoDetermine=autodetermine
Parameters:
theColor -- A string representing the "name" of the color. If the name
can't be resolved or found, the first color is returned.
startIndex -- If present, and INDEXNUMBER is set, the colors are loaded at
this index number. Otherwise, the self.startIndex is used.
Keywords:
AUTODETERMINE -- If this keyword is set. the state of DECOMPOSITION is
determined (IDL 5.2 and higher) and either the INDEXNUMBER or
TRUECOLOR keyword is set appropriately. If the decomposition state
cannot be determined, the INDEXNUMBER keyword is set.
INDEXNUMBER -- If this keyword is set the colors are loaded and the
index number of the color is returned.
TRUECOLOR -- If this keyword is set, the color triple is converted into
a 24-bit integer before being returned. This keyword is ignored
if the INDEXNUMBER keyword is set.
Examples:
drawColor = colors->GetColor("yellow")
drawColor = colors->GetColor("blue", /Indexnumber)
drawColor = colors->GetColor("sky", /Truecolor)
GETCOLORS **************************************************************************
Purpose:
Returns the color triples, the color index numbers of, or the
24-bit integer representations of, all the colors.
Definition:
FUNCTION DrawColors::GetColors, startindex, INDEXNUMBER=indexnumber, $
TRUECOLOR=truecolor, Structure=structure
Parameters:
startIndex -- If present, and INDEXNUMBER is set, the colors are loaded at
this index number. If absent, startIndex = self.startIndex.
Keywords:
INDEXNUMBER -- If this keyword is set the colors are loaded and the
index numbers of all the colors are returned.
STRUCTURE -- If this keyword is set, the return value is a structure,
where each field of the structure is a color name and the value
of each field is either a color triple, an index number, or a
24-bit color value, depending upon the state of other keywords.
TRUECOLOR -- If this keyword is set, the color triples are converted to
24-bit integers before being returned. This keyword is ignored
if the INDEXNUMBER keyword is set.
Examples:
drawColors = colors->GetColors() ; drawColors is a 16-by-3 byte array.
drawColors = colors->GetColors(/IndexNumber) ; drawColors is a 16-element array of color indices.
drawColors = colors->GetColors(/TrueColor) ; drawColors is a 16-element array of 24-bit integers.
drawColors = colors->GetColors(/IndexNumber, /Structure) ; drawColors is a structure of index numbers.
Plot, data, Color=drawColors.yellow, Background=drawColors.charcoal
SELECT **************************************************************************
Purpose:
Puts up a blocking or modal widget dialog, allowing the user to select
from one of the 16 predefined colors available, or to mix their own color.
The user-defined color triple is returned as a result of the function.
Definition:
FUNCTION DrawColors::Select, Color=currentColor, StartIndex=startIndex, $
Title=title, Group_Leader=groupLeader, Cancel=cancelled, TrueColor=truecolor
Keywords:
CANCEL -- An output keyword that will return a value of 1 if the CANCEL
button is selected or if program operation is interrupted in any way.
COLOR -- The index number in the color table, where the current color
will be mixed. In other words, this color index will change when
the program is on the display. It will be restored to its previous
or entry color when the program exits.
GROUP_LEADER -- The group leader for the program. This keyword *must*
be set if calling this method from within a widget program if you
expect MODAL program operation.
NAME -- If this keyword is set, the return value of the function is
the "name" of the color.
STARTINDEX -- This is the starting index in the color table where the
16 predetermined colors will be loaded. The original colors will
be restored when the program exits. By default, this is set to
!D.Table-Size - (NCOLORS + 1).
TITLE -- The title of the program. By default: "Pick a Color"
TRUECOLOR -- If this keyword is set, the return value of the function
is a 24-bit eqivalent integer rather than the color triple.
Examples:
newColor = colors->Select() ; A blocking widget.
newColor = color->Select(Group_Leader=event.top, Cancel=cancelled)
IF NOT cancelled THEN TVLCT, newColor, info.dataColor
PROCEDURE METHODS:
GETPROPERTY ***********************************************************************
Purpose:
Allows the user to obtain the current properties of the object.
Definition:
PRO DrawColors::GetProperty, NAMES=names, RED=red, GREEN=green, BLUE=blue, $
STARTINDEX=startindex, NCOLORS=ncolors
Keywords:
NAMES -- Returns the current names of the colors as a string array.
RED -- Returns the current red values of the colors.
GREEN -- Returns the current green values of the colors.
BLUE -- Returns the current blue values of the colors.
STARTINDEX -- Returns the current starting index in the color table.
NCOLORS -- Returns the number of colors.
Example:
colors->GetProperty, Names=colorNames
Print, colorNames
LOADCOLORS ************************************************************************
Purpose:
Loads the predefined colors at a starting index.
Definition:
PRO DrawColors::LoadColors, startindex
Parameters:
STARTINDEX -- The starting color index in the color table. If not provided,
is set to !D.Table_Size - (self.ncolors + 1).
Example:
colors->LoadColors, 16
ORIGINALCOLORS *********************************************************************
Purpose:
Reloads the original 16 colors and their names
Definition:
PRO DrawColors::OriginalColors
Parameters:
None
Example:
colors->OriginalColors
REFRESH ***************************************************************************
Purpose:
Refreshes the modal GUI with the current drawing colors.
Definition:
PRO DrawColors::Refresh
Parameters:
None
Example:
colors->Refresh
SETPROPERTY ***********************************************************************
Purpose:
Allows the user to set the current properties of the object.
Definition:
PRO DrawColors::SetProperty, NAMES=names, RED=red, GREEN=green, BLUE=blue, $
STARTINDEX=startindex, NCOLORS=ncolors
Keywords:
NAMES -- The current names of the colors as a string array.
RED -- The current red values of the colors.
GREEN -- The current green values of the colors.
BLUE -- The current blue values of the colors.
STARTINDEX -- The current starting index in the color table.
NCOLORS -- The number of colors.
Example:
colorNames = 'Color ' + StrTrim(SIndGen(16),2)
colors->SetProperty, Names=colorNames
XCOLORS ***************************************************************************
Purpose:
Allows the user to select 16 new colors for the program by
using the XCOLORS program. The XColors program must be
somewhere in your !PATH.
Definition:
PRO DrawColors::XColors
Parameters:
None
Example:
colors->XColors
TUTORIAL:
Here is a short tutorial in how this object can be used. Note
that this doesn't exhaust all the possibilities.
1. Create the object.
IDL> colors = Obj_New("DrawColors")
2. Find out what colors it knows about.
IDL> colors->GetProperty, Names=colorNames
IDL> Print, colorNames
3. Ask for a color by name and load it at a color
index. Draw a plot in that color.
IDL> yellow = colors->GetColor("yellow")
IDL> TVLCT, yellow, 200
IDL> Device, Decomposed=0
IDL> Plot, Findgen(11), Color=200
4. Do the same thing, but in DECOMPOSED color.
IDL> Device, Decomposed=1
IDL> green = colors->GetColor("green", /TrueColor)
IDL> Plot, Findgen(11), Color=green
5. Find the color index number of the sky blue color.
IDL> Device, Decomposed=0
IDL> skyIndex = colors->GetColor("sky", /IndexNumber)
IDL> Plot, Findgen(11), Color=skyIndex
6. Load all 16 drawing colors at color index 32.
IDL> colors->LoadColors, 32
IDL> CIndex ; If them, if you have CINDEX from my library.
7. Get a structure of colors, with each field set to
the appropriate index number of its associated color.
IDL> Device, Decomposed=0
IDL> col = colors->GetColors(/IndexNumber, /Structure)
IDL> Plot, Findgen(11), Color=col.yellow, Background=col.charcoal
8. Allow the user to select a color from a GUI, then
load it and use it.
IDL> Device, Decomposed=0
IDL> theColor = colors->Select(Cancel=cancelled)
IDL> IF NOT cancelled THEN TVLCT, theColor, 10
IDL> Plot, Findgen(11), Color=10
9. Allow the user to choose 16 new drawing colors.
(Requires my XCOLORS program.)
IDL> colors->XColors
IDL> theseColors = colors->Select()
10. Let the object decide according to the device decomposition
state whether to return an index number or 24-bit value
for the color.
IDL> Plot, Findgen(11), Color=colors->GetColor('beige', /Autodetermine)
11. Call the GUI from within a widget program and load the
new color.
newcolor = info.colors->Select(Group_Leader=event.top, $
Cancel=cancelled)
IF NOT cancelled THEN TVLCT, newcolor, info.drawColor
12. Destroy the object.
IDL> Obj_Destroy, colors
MODIFICATION HISTORY:
Written by: David Fanning, 9 NOV 1999.
Added AUTODETERMINE keyword to the GetColor method. 10 NOV 1999. DWF.
Added NAME keyword to SELECT method. 18 MAR 2000. DWF.
Fixed a small bug in choosing the current color. 20 April 2000. DWF.
(See /home/drw/idl/aux/drawcolors__define.pro)
ROUTINE: DRWPHASE PURPOSE: Calculate the phase as a function of (+ve) frequency for a timeseries USEAGE: result = drwphase(time,flux) INPUT: TIME - Time array in seconds FLUX - Flux array OUTPUT: RESULT - The phase spectrum AUTHOR: Peter T. Gallagher, Mar. '99 Altered by R.T. James McAteer & David R. Williams according to http://cires.colorado.edu/geo_data_anal/assign/assign4.html Oct' 01
(See /home/drw/idl/secis2/drwphase.pro)
Name:
drw_circle
Purpose:
Draw a circle, and DON'T GO PAST THE DATA REGION!!
Calling Sequence:
draw_circle, x0, y0, radius [, npts=npts]
Input Parameters:
x0 = Central x coordinate
y0 = Central y coordinate
radius = Radius
Optional input keywords:
Npts = Number of points (default = 10000)
device = If set, plots will assume device coordinates
data = If set, plots will assume data coordinates
psym = Plot symbol
color = Color
linestyle = Line style
THESE KEYWORDS DUMPED for handiness:
= If set, call poly_fill
= If noclip=0, circles will be clipped (read the IDL
manual on plots to find out why its this way).
Modification History:
Written, 26-feb-92, J. R. Lemen
2-feb-95, JRL, Added thick keyword
11-apr-96, S.L.Freeland, Add FILL keyword and function
25-apr-96, JRL, Added the NOCLIP keyword
22-Apr-2001, Kim Tolbert. In theta calculation, divide by npts-1 so
circle is closed.
26-Aug-2003, Dave Williams. AFTER RENAMING, a second change allows
the user to grab the `vertices` of the circle in XX and YY, which
won't go past the data region.
(See /home/drw/idl/gen/drw_circle.pro)
NAME: drw_draw_boxcorn PURPOSE: To draw a box on the screen in either data or device coordinates SAMPLE CALLING SEQUENCE: draw_boxcorn, x0, y0, x1, y1 INPUT: x0 - The lower left x coordinate y0 - The lower left y coordinate x1 - The upper right x coordinate y1 - The upeer right y coordinate OPTIONAL INPUT: nxparts - Draw this many x grid marks nyparts - Draw this many y grid marks nytot - screen size excluding lines at the bottom to skip nyskip - number of lines to skip a the bottom (for color bar) label - optional label to be put in lower left corner lab_siz - size of the label lab_dir - orientation of the label lab_col - color of the label OPTIONAL KEYWORD INPUT: device - If set, use device coordinates (DEFAULT) data - If set, use data coordinates color - If set, use that color HISTORY: Written Oct-91 by M.Morrison 18-Jun-93 (MDM) - Added COLOR option and documentation header modified by DRW to add LINESTYLE keyword
(See /home/drw/idl/secis2/drw_draw_boxcorn.pro)
Project : TRACE (now!)
Name : drw_timePLOT
Purpose : To plot time series data with sensible time axis labelling.
Explanation : Uses the routine DEF_CDS_UTPLOT to manipulate the IDL plotting
variables to set up sensible time axis labels and intervals.
After the setup the data are plotted with a normal call to
the routine PLOT.
Use : IDL> drw_timeplot,x,y,timerange=[], /dmy, /log + normal plot keywords.
Inputs : x - the time variable. May be either an array of CDS internal
time structures (as produced by the
routine STR2UTC, say) or...
a string array of date/times in a
format translatable by STR2UTC.
y - the data value to be plotted.
Opt. Inputs : Various keywords.
Outputs : None
Opt. Outputs: None
Keywords : timerange - a 2-element array each element is either a CDS
internal time structure or a CDS date/time string.
Note that this time range is still adjusted
slightly for actual plotting unless the keyword
xstyle=1 is specified.
dmy - if the x-variable is a list of date/time strings
this keyword must be used if they are in the
format dd-mm(m)-yyyy as opposed to the CDS
'official' format of yyyy-mm-dd
log - make plot log-linear
+ other standard plot keywords
Calls : DEF_CDS_UTPLOT
STR2UTC
UTC2SEC
SEC2UTC
VCHECK
Common : cds_utplot_com (for passing of time axis offset to cds_outplot)
Restrictions: The MJD of any dates used must be positive.
Any 2-character year specifications are translated as being
between 1950 and 2049 (use 4-characters as necessary).
The time array passed to CDS_UTPLOT must be in ascending order
of time - sort it if necessary!
Side effects: None
Category : Data display, plotting
Prev. Hist. : This is a severely trimmed version of the old UTPLOT as used on
Yohkoh and developed by Tolbert, Schwartz and Morrison.
I may have trimmed too much, please let me know.
Written : This version for CDS by C D Pike, RAL, 20-Apr-94
Modified : Version 1, C D Pike, RAL, 20-Apr-94
Version 2, William Thompson, GSFC, 14 November 1994
Modified .DAY to .MJD
Version 3, Add /log keyword. CDP, 18-Sep-95
Version 4, Fix bug when specifying <10 days timerange. 7-Dec-95
Version 5, Add xminor keyword. CDP, 25-Mar-96
Version 6, Name change. CDP, 2-Oct-96
Version : Version 6, 2-Oct-96
(See /home/drw/idl/bin/drw_timeplot.pro)
NAME:
dsCHECK_FITS
PURPOSE:
Given a FITS array IM, and a associated FITS or STSDAS header HDR, this
procedure will check that
(1) HDR is a string array, and IM is defined and numeric
(2) The NAXISi values in HDR are appropiate to the dimensions
of IM
(3) The BITPIX value in HDR is appropiate to the datatype of IM
If HDR contains a DATATYPE keyword (as in STSDAS files), then this is
also checked against the datatype of of IM
If the UPDATE keyword is present, then FITS header will be modified, if
necessary, to force agreement with the image array
CALLING SEQUENCE:
check_FITS, im, hdr, [ dimen, idltype, /UPDATE, /NOTYPE, /SDAS ]
INPUTS:
IM - FITS or STSDAS array, (e.g. as read by SXREAD or READFITS )
HDR - FITS or STSDAS header (string array) associated with IM
OPTIONAL OUTPUTS:
dimen - vector containing actual array dimensions
idltype- data type of the FITS array as specified in the IDL SIZE
function (1 for BYTE, 2 for INTEGER*2, 3 for INTEGER*4, etc.)
OPTIONAL KEYWORD INPUTS:
/NOTYPE - If this keyword is set, then only agreement of the array
dimensions with the FITS header are checked, and not the
data type.
/UPDATE - If this keyword is set then the BITPIX, NAXIS and DATATYPE
FITS keywords will be updated to agree with the array
/SDAS - If this keyword is set then the header is assumed to be from
an SDAS (.hhh) file. CHECK_FITS will then ensure that (1)
a DATATYPE keyword is included in the header and (2) BITPIX
is always written with positive values.
/FITS - If this keyword is present then CHECK_FITS assumes that it is
dealing with a FITS header and not an SDAS header, see notes
below.
SYSTEM VARIBLE:
If there is a fatal problem with the FITS array or header then !ERR is
set to -1. ( If the UPDATE keyword was supplied, and the header could
be fixed then !ERR = 0.)
PROCEDURE:
Program checks the NAXIS1 and NAXIS2 parameters in the header to
see if they match the image array dimensions.
NOTES:
An important distinction between an STSDAS header and a FITS header
is that the BITPIX value in an STSDAS is always positive, e.g. BITPIX=32
for REAL*4 data. Users should use either the /SDAS or the /FITS
keyword if it is important whether the STSDAS or FITS convention for
REAL*4 data is used. Otherwise, CHECK_FITS assumes that if a
DATATYPE keyword is present then it is dealing with an STSDAS header.
MODIFICATION HISTORY:
Written, December 1991 W. Landsman Hughes/STX to replace CHKIMHD
No error returned if NAXIS=0 and IM is a scalar W. Landsman Feb 93
Fixed bug for REAL*8 STSDAS data W. Landsman July 93
Make sure NAXIS agrees with NAXISi W. Landsman October 93
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/dscheck_fits.pro)
PURPOSE: to return a grid of vectors indicating the relative
displacements that most closely match images and .
ARGUMENTS:
: the reference image, two-dimensional.
: the image for which displacements are derived; must have
the same dimensions as .
: the output grid size. If a scalar, then the output grid
has dimensions by . If an array, then the output
grid has dimensions by .
: (optional) the side (in pixels) of the square subwindows
that are compared to yield a vector on each grid point.
"Adjacent" subwindows may overlap. Defaults to 1.25 times
.
: (optional) the full width at half maximum (in pixels) of
the Gaussian apodization function that is applied to the
data within the subwindows. Defaults to twice the greater
dimension of the "standard" subwindow (with the standard
subwindows defined as covering the whole image without
overlap).
: (optional) the greatest allowed displacement in
either dimension, in pixels. If no match is found at
smaller displacements, then a bad match is declared and a
zero vector is returned.
CALLING SEQUENCE:
result = DSGRID2(m1,m2,n,nwin,ngwin,[stretch_clip],kol=kol,$
in_verts=in_verts,out_verts,gx=gx,gy=gy)
EXAMPLE:
result = dsgrid2(refimage,testimage,6, spacing, 1.25*spacing,3,kol=255,$
in_verts=iv,out_verts=ov)
AUTHORS: Richard A. Shine, Lockheed Martin ATC (ANA version)
Louis H. Strous, Lockheed Martin ATC (port to IDL, with
minor enhancements)
.....
Modifications by DRW@MSSL/UCL (July 2002) to add VELOVECT
plots to show displacements for each cell, as well as to return
the input and output vertices, and the displacement arrays, if so desired,
in the form of keywords IN_VERTS, OUT_VERTS, GX and GY.
(See /home/drw/idl/secis2/dsgrid2.pro)
NAME: DSINTEGRAL PURPOSE: Find the element of an array for which the integral is equal to an input value. CATEGORY: Arrays. CALLING SEQUENCE: Result = DSINTEGRAL(Vector,Percent) INPUTS: Vector: The vector to integrate. Percent:The percent included. OUTPUTS: This function integrates the input vector and returns the element at which the integral equals Percent percent of the total. PROCEDURE: Straightforward. EXAMPLE: MODIFICATION HISTORY: Written by David Sahnow, 16 June 1997. 20 November 1998 Renamed from INTEGRAL to DSINTEGRAL.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/dsintegral.pro)
NAME:
DXBREAK
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Sets an IDL breakpoint
CALLING SEQUENCE:
DXBREAK, LINE ; current procedure (OR)"
DXBREAK, 'PROCNAME', LINE ; named procedure (OR)"
DXBREAK, 'path/procname.pro', LINE ; procedure path (OR)"
DXBREAK, PROCNAME, LINE ; without quotes"
DESCRIPTION:
DXBREAK is a convenience routine for setting IDL breakpoints.
The benefits over the built-in IDL procedure BREAKPOINT are:
* fewer characters to type;
* full pathname not required, just a procedure name; and
* for breakpoints within the current procedure, the file name
is not needed.
To clear breakpoints, use either DXCLEAR or BREAKPOINT, /CLEAR.
INPUTS:
LINE - the line number where the breakpoint is to be set. This
value is required.
PROCNAME - the procedure name in which the breakpoint is to be
set. Note that IDL requires that a procedure be
compiled on disk -- console-compiled or .RUN files
cannot have breakpoints set.
The name is one of:
* the procedure or function name;
* the full path to the procedure or function; OR
* an unquoted procedure or function name.
DXBREAK will search your path to find the correct
procedure. The first file found will be used.
KEYWORDS:
ONCE - if set, then the breakpoint will only occur once. The same
as the ONCE keyword to BREAKPOINT.
IS_FUNCTION - if set, and there is an ambiguity between whether
PROCNAME is a procedure or a function, then DXBREAK
will assume that it is a function.
EXAMPLE:
dxbreak, 'myfunc', 50
Set breakpoint in MYFUNC at line 50.
SEE ALSO:
BREAKPOINT, DXCLEAR
MODIFICATION HISTORY:
Written, 15 Apr 2000
Addition of NOCATCH keyword for internal testing, 21 Sep 2000, CM
Made mostly compatible with IDL v4, 21 Sep 2000, CM
Added AFTER keyword, 13 Dec 2000, CM
Removed AFTER, use _EXTRA instead, 08 Apr 2001, CM
$Id: dxbreak.pro,v 1.4 2001/04/08 16:59:55 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxbreak.pro)
NAME: DXCLEAR AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Clears an IDL breakpoint CALLING SEQUENCE: DXCLEAR, INDEX DESCRIPTION: DXBREAK is a convenience routine for clearing IDL breakpoints. Its primary benefits are that it is symmetric with DXBREAK, and it requires fewer characters to type. INPUTS: INDEX - the breakpoint number, as listed by HELP, /BREAKPOINT. EXAMPLE: dxclear, 0 Clear breakpoint number 0 SEE ALSO: BREAKPOINT, DXBREAK MODIFICATION HISTORY: Written, 15 Apr 2000 $Id: dxclear.pro,v 1.2 2001/02/09 04:57:15 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxclear.pro)
NAME: DXCOMMON AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Defines DEBUG_LEVEL common block (INTERNAL) DESCRIPTION: This code fragment defines the DEBUG_LEVEL common block. This common is internal to the debugging procedures. $Id: dxcommon.pro,v 1.2 2001/02/09 04:57:15 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxcommon.pro)
NAME:
DXDOWN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Move the debugging focus deeper down the IDL call stack
CALLING SEQUENCE:
DXDOWN [ , NLEVELS ]
DESCRIPTION:
DXDOWN moves the debugging "focus" deeper down the IDL call stack.
By using this procedure and DXUP, one can navigate up and down an
existing call stack, and examine and set variables at various
levels.
While IDL always keeps the command line at the deepest call level
(i.e., where the breakpoint occurred), DXDOWN and its related
debugging procedures maintain a separate notion of which part of
the call stack they are examining -- the debugging "focus."
DXDOWN moves the debugging focus deeper by at least one level, but
never beyond the deepest level.
INPUTS:
NLEVELS - option number of levels to move. Default (and minimum)
value is 1.
EXAMPLE:
dxdown
Move the debugging focus down one level.
SEE ALSO:
DXUP, DXDOWN, DXGET, DXSET
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxdown.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxdown.pro)
NAME:
DXFINISH
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Sets an IDL breakpoint to stop upon return of the current procedure
CALLING SEQUENCE:
DXFINISH [ , NLEVELS ]
DESCRIPTION:
DXFINISH is a convenience routine for setting IDL breakpoints.
DXFINISH sets a breakpoint so that when the current procedure
finishes, execution will stop. Often when debugging one wants to
let the current procedure complete but stop at the next level.
DXFINISH does exactly that.
DXFINISH examines the state of the current IDL call stack,
determines at what point the current procedure will return, and
sets a breakpoint there. Note that the procedure in which the
breakpoint is set must be compiled and on disk.
By default the breakpoint is set with the ONCE keyword.
INPUTS:
NLEVELS - Number of call levels up to set breakpoint. Default is
1.
KEYWORDS:
ONCE - if set, then the breakpoint will only occur once. Default
value is SET, so ONCE=0 must be passed explicitly to
disable this function.
EXAMPLE:
dxfinish
Set breakpoint in calling procedure.
SEE ALSO:
BREAKPOINT, DXBREAK, DXCLEAR
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxfinish.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxfinish.pro)
NAME:
DXGET
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Gets IDL variable from a different IDL call level
CALLING SEQUENCE:
RESULT = DXGET('NAME') ; quoted variable name (OR)
RESULT = DXGET(NAME) ; unquoted variable name
DESCRIPTION:
DXGET retrieves a variable value from any point in the IDL call
stack. The DXGET and DXSET routines allow any variable at any
level to be examined and changed.
The call level to be examined is determined by the current
debugging "focus." By default this is the deepest level in the
call stack -- where the breakpoint occurred. However, this level
can be changed by using the DXUP and DXDOWN procedures.
If the variable doesn't exist, then an error message is reported.
INPUTS:
NAME - the name of the variable, either quoted or unquoted.
KEYWORDS:
LEVEL - the call level to be examined, if not the current
debugging focus.
EXAMPLE:
value = dxget('a')
Retrieve the value of the variable A from the debugged call level.
SEE ALSO:
DXGET, DXSET, DXUP, DXDOWN
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxget.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxget.pro)
NAME:
DXHELP
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Perform HELP equivalent at any point in IDL call stack
CALLING SEQUENCE:
DXHELP, X0, X1, ..., [ LEVEL=LEVEL ]
DESCRIPTION:
DXHELP performs the equivalent of HELP for the variables at any
level in the IDL call stack.
The call level to be examined is determined by the current
debugging "focus." By default this is the deepest level in the
call stack -- where the breakpoint occurred. However, this level
can be changed by using the DXUP and DXDOWN procedures.
If the ALL keyword is set, then all variables are examined.
INPUTS:
Xi - variables to be examined, either quoted or unquoted.
Non-string expressions are diagnosed, but of course refer to
the deepest call level. If the ALL keyword is set then the
Xi parameters are ignored.
KEYWORDS:
LEVEL - the call level to be examined, if not the current
debugging focus.
ALL - if set, then all variables at the current focus level are
examined.
EXAMPLE:
dxhelp
Print all variables at current debugging focus level
SEE ALSO:
DXUP, DXDOWN, DXHELP, DXPRINT
MODIFICATION HISTORY:
Written, 15 Apr 2000
Added ALL keyword; changed N_PARAMS() EQ 0 behavior, CM 17 Apr
2000
DXHELP_VALUE now prints correct string and byte values, CM 23 Apr
2000
Add support for printing structures with FULL_STRUCT, CM 08 Feb
2001
Added forward_function for DXHELPFORM, CM 08 Apr 2001
Print more info about POINTER type, CM 30 Apr 2001
$Id: dxhelp.pro,v 1.5 2001/04/30 15:26:53 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxhelp.pro)
NAME: DXLRESET AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Reset the current debugging focus level (INTERNAL) CALLING SEQUENCE: DXLRESET DESCRIPTION: DXLRESET resets the current debugging focus level, if it has changed. This routine is internal to the debugging procedures. SEE ALSO: DXUP, DXDOWN, DXGET, DXSET MODIFICATION HISTORY: Written, 15 Apr 2000 $Id: dxlreset.pro,v 1.2 2001/02/09 04:57:16 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxlreset.pro)
NAME: DXPLEVEL AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Print the current call stack (INTERNAL) CALLING SEQUENCE: DXPLEVEL DESCRIPTION: DXLRESET prints the current call stack, and highlights the debugging focus level.This routine is internal to the debugging procedures. SEE ALSO: DXUP, DXDOWN, DXGET, DXSET MODIFICATION HISTORY: Written, 15 Apr 2000 $Id: dxplevel.pro,v 1.2 2001/02/09 04:57:17 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxplevel.pro)
NAME:
DXPRINT
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Perform HELP equivalent at any point in IDL call stack
CALLING SEQUENCE:
DXPRINT, X0, X1, ... [, LEVEL=LEVEL, FORMAT=FORMAT ]
DESCRIPTION:
DXPRINT prints the values of variables from any level in the IDL
call stack.
The call level to be examined is determined by the current
debugging "focus." By default this is the deepest level in the
call stack -- where the breakpoint occurred. However, this level
can be changed by using the DXUP and DXDOWN procedures.
INPUTS:
Xi - variables to be printed, unquoted. Non-string expressions
are printed, but of course refer to the deepest call level.
KEYWORDS:
LEVEL - the call level to be examined, if not the current
debugging focus.
FORMAT - format string to be applied to data values.
EXAMPLE:
dxprint, a, b
Print A and B from the current debugging focus level
SEE ALSO:
DXUP, DXDOWN, DXHELP, DXPRINT
MODIFICATION HISTORY:
Written, 15 Apr 2000
Corrected FORMAT statement, 30 Jun 2001
$Id: dxprint.pro,v 1.3 2001/06/30 19:56:04 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxprint.pro)
NAME: DXPTRACE AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Parse the current call stack (INTERNAL) CALLING SEQUENCE: RESULT = DXPTRACE(STRING) DESCRIPTION: DXPTRACE is a function which parses the call stack, as returned by HELP, /CALL. It is internal to the debugging routines. SEE ALSO: DXUP, DXDOWN, DXGET, DXSET MODIFICATION HISTORY: Written, 15 Apr 2000 $Id: dxptrace.pro,v 1.2 2001/02/09 04:57:17 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxptrace.pro)
NAME:
DXSET
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Sets IDL variable in a different IDL call level
CALLING SEQUENCE:
DXSET, 'NAME', VALUE ; quoted variable name (OR)
DXSET, NAME, VALUE ; unquoted variable name
DESCRIPTION:
DXSET sets a variable value at any point in the IDL call stack.
The DXGET and DXSET routines allow any variable at any level to be
examined and changed.
The call level to be examined is determined by the current
debugging "focus." By default this is the deepest level in the
call stack -- where the breakpoint occurred. However, this level
can be changed by using the DXUP and DXDOWN procedures.
If the variable doesn't exist, then an error message is reported,
and the variable is not set.
INPUTS:
NAME - the name of the variable, either quoted or unquoted.
VALUE - the new value of the variable.
KEYWORDS:
LEVEL - the call level to be examined, if not the current
debugging focus.
EXAMPLE:
dxset, 'a', 5
Set the value of the variable A to 5 in the currently debugged
call level.
SEE ALSO:
DXGET, DXSET, DXUP, DXDOWN
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxset.pro,v 1.2 2001/02/09 04:57:18 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxset.pro)
NAME:
DXUP
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Move the debugging focus higher up the IDL call stack
CALLING SEQUENCE:
DXUP [ , NLEVELS ]
DESCRIPTION:
DXUP moves the debugging "focus" higher up the IDL call stack. By
using this procedure and DXDOWN, one can navigate up and down an
existing call stack, and examine and set variables at various
levels.
While IDL always keeps the command line at the deepest call level
(i.e., where the breakpoint occurred), DXUP and its related
debugging procedures maintain a separate notion of which part of
the call stack they are examining -- the debugging "focus."
DXUP moves the debugging focus higher by at least one level, but
never beyond the "root" $MAIN$ level.
INPUTS:
NLEVELS - option number of levels to move. Default (and minimum)
value is 1.
EXAMPLE:
dxup
Move the debugging focus up one level.
SEE ALSO:
DXUP, DXDOWN, DXGET, DXSET
MODIFICATION HISTORY:
Written, 15 Apr 2000
$Id: dxup.pro,v 1.2 2001/02/09 04:57:18 craigm Exp $
(See /home/drw/idl/aux/markwardt/dxup.pro)
ROUTINE: dydx
PURPOSE: compute numerical derivative accurate to second order.
In most cases this should be more accurate than the
IDL userlib procedure DERIV.
USEAGE: dydx(x,y)
INPUT:
x vector of independent variable (monitonic)
y vector of dependent variable
KEYWORD INPUT:
lin_end if set, use a one sided linear approximation for end points
OUTPUT: numerical derivative dy/dx
EXAMPLE:
!p.multi=[0,1,2]
x=[0.,1.,3.,8.,10.,13.,17.,19.,22.,25.]
y=x*(25-x) & yp=25-2*x & labels=['analytic','dydx','deriv']
plot,x,y,title='quadratic [dydx(x,y) is exact in this case]'
plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.5,0.7,0.75,0.98]
x=[0.0,0.5,1.5,2.,3.,3.6,4.0,5.,6.,6.3]
y=sin(x) & yp=cos(x)
plot,x,y,title='sin(x)'
plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.25,0.7,0.50,0.98]
x=[-2.,-1.,-.7,-.3,-.1,0.,.1,.3,.7,1.,2]
y=exp(-x^2) & yp=-2*x*y
plot,x,y,title='gausian'
plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.5,0.7,0.75,0.98]
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/dydx.pro)
ROUTINE: dydx
PURPOSE: compute numerical derivative accurate to second order.
In most cases this should be more accurate than the
IDL userlib procedure DERIV.
USEAGE: dydx(x,y)
INPUT:
x vector of independent variable (monitonic)
y vector of dependent variable
KEYWORD INPUT:
lin_end if set, use a one sided linear approximation for end points
OUTPUT: numerical derivative dy/dx
EXAMPLE:
!p.multi=[0,1,2]
x=[0.,1.,3.,8.,10.,13.,17.,19.,22.,25.]
y=x*(25-x) & yp=25-2*x & labels=['analytic','dydx','deriv']
plot,x,y,title='quadratic [dydx(x,y) is exact in this case]'
plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.5,0.7,0.75,0.98]
x=[0.0,0.5,1.5,2.,3.,3.6,4.0,5.,6.,6.3]
y=sin(x) & yp=cos(x)
plot,x,y,title='sin(x)'
plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.25,0.7,0.50,0.98]
x=[-2.,-1.,-.7,-.3,-.1,0.,.1,.3,.7,1.,2]
y=exp(-x^2) & yp=-2*x*y
plot,x,y,title='gausian'
plot,x,yp & oplot,x,dydx(x,y),psym=2 & oplot,x,deriv(x,y),psym=4
legend,labels,li=[0,0,0],psym=[0,2,4],pos=[0.5,0.7,0.75,0.98]
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/dydx.pro)
NAME:
EARTHDIST
PURPOSE:
Calculate the great circle distance (in km) based on lats and lons.
CALLING SEQUENCE:
dist = earthdist(lat1,lon1,lat2,lon2)
INPUTS:
lat1 latitude of first point
lon1 longitude of first point
lat2 latitude of second point
lon2 longitude of second point
KEYWORD INPUTS:
OPTIONAL INPUTS:
OUTPUTS:
Distance along great circle returned.
OPTIONAL OUTPUTS:
EXAMPLE:
print,earthdist(0,0,0,1)
111.189
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 4/05/94
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/earthdist.pro)
NAME:
EARTHDIST
PURPOSE:
Calculate the great circle distance (in km) based on lats and lons.
CALLING SEQUENCE:
dist = earthdist(lat1,lon1,lat2,lon2)
INPUTS:
lat1 latitude of first point
lon1 longitude of first point
lat2 latitude of second point
lon2 longitude of second point
KEYWORD INPUTS:
OPTIONAL INPUTS:
OUTPUTS:
Distance along great circle returned.
OPTIONAL OUTPUTS:
EXAMPLE:
print,earthdist(0,0,0,1)
111.189
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 4/05/94
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/earthdist.pro)
NAME:
ECLIPS3
USAGE:
eclips3,curve,freek,sigg,t0=t0,print=print,init=initialframe,$
pc=pc,title=title,nocon=nocon,pwoer=power,$
f_inver=f_inver,time=time,coi_inver=coi_inver,$
signif=signif,scale=scale
e.g. eclips3,curve,15,0.99,title='Wavelet Plot',/print,pc=255
INPUT:
SERIES - input time series
FREEK - upper cut-off frequency for low-pass frequency domain filtering
SIGG - significance level (percentage) e.g. 0.99 = 99%
KEYWORDS:
T0 - the starting time of the sequence. Useful for plots.
PRINT - set if you want to print to postscript after
setting the device as PostScript
NOCON - set to avoid plotting the significance contours and
cone-of-influence hatching
PC - print colour, from 0 (black) to 255 (white) in the case
most colour tables
TITLE - the title for the main wavelet transform panel
CALLS:
The wavelet routines WAVELET and WAVE_SIGNIF, as well as TVIM and
ECLIPS_FILTER.
HISTORY:
A modification of ECLIPSE, originally written by Eoghan O'Shea,
modified and maintained by David Williams.
(See /home/drw/idl/secis/eclips3.pro)
NAME: ECLIPS4 USAGE: ECLIPS4,series,freek,sigg,t0=t0,print=print,pc=pc,title=title,nocon=nocon e.g. ECLIPS4,curve,0.99,title='Wavelet Plot',/print,pc=255 INPUT: SERIES - input time series FREEK - upper cut-off frequency for low-pass frequency domain filtering SIGG - significance level (percentage) e.g. 0.99 = 99% KEYWORDS: T0 - the starting time of the sequence. Useful for plots. PRINT - set if you want to print to postscript after setting the device as PostScript NOCON - set to avoid plotting the significance contours and cone-of-influence hatching PC - print colour, from 0 (black) to 255 (white) in the case most colour tables TITLE - the title for the main wavelet transform panel CALLS: The wavelet routines WAVELET and WAVE_SIGNIF, as well as TVIM and ECLIPS_FILTER. HISTORY: A modification of ECLIPSE, originally written by Eoghan O'Shea, modified and maintained by David Williams.
(See /home/drw/idl/secis/eclips4.pro)
PRO eclipse_movie,data
Data = FLTARR(504,504,100)
;FOR i = 0, 5999, 60 DO BEGIN
FOR i = 0, 99, 1 DO BEGIN
PRINT,i
IF (i LE 9) THEN a = ;READFITS('broadband/broad000'+ARR2STR(i,/Trim)+'.fit')
IF ((i GT 9) AND (i LE 99)) THEN a = ;READFITS('broadband/broad00'+ARR2STR(i,/Trim)+'.fit')
;IF ((i GT 99) AND (i LE 999)) THEN a = READFITS('secis/broad0'+ARR2STR(i,/Trim)+'.fit')
;IF ((i GT 999)) THEN a = READFITS('secis/broad'+ARR2STR(i,/Trim)+'.fit')
Data(*,*,i) = a
;TVIM, a
ENDFOR
END
(See /home/drw/idl/secis/eclipse_movie.pro)
PRO eclipse_movie2,data
Data = FLTARR(504,504,100)
;FOR i = 0, 5999, 60 DO BEGIN
FOR i = 0, 99, 1 DO BEGIN
PRINT,i
IF (i LE 9) THEN a = ;READFITS('narrowband/narrow000'+ARR2STR(i,/Trim)+'.fit')
IF ((i GT 9) AND (i LE 99)) THEN a = ;READFITS('narrowband/narrow00'+ARR2STR(i,/Trim)+'.fit')
;IF ((i GT 99) AND (i LE 999)) THEN a = READFITS('secis/broad0'+ARR2STR(i,/Trim)+'.fit')
;IF ((i GT 999)) THEN a = READFITS('secis/broad'+ARR2STR(i,/Trim)+'.fit')
Data(*,*,i) = a
;TVIM, a
ENDFOR
END
(See /home/drw/idl/secis/eclipse_movie2.pro)
PRO eclipse_movie2,data
Data = FLTARR(504,504,100)
;FOR i = 0, 5999, 60 DO BEGIN
FOR i = 0, 99, 1 DO BEGIN
PRINT,i
IF (i LE 9) THEN a = ;READFITS('broadband/broad000'+ARR2STR(i,/Trim)+'.fit')
IF ((i GT 9) AND (i LE 99)) THEN a = ;READFITS('broadband/broad00'+ARR2STR(i,/Trim)+'.fit')
;IF ((i GT 99) AND (i LE 999)) THEN a = READFITS('secis/broad0'+ARR2STR(i,/Trim)+'.fit')
;IF ((i GT 999)) THEN a = READFITS('secis/broad'+ARR2STR(i,/Trim)+'.fit')
Data(*,*,i) = a
;TVIM, a
ENDFOR
END
(See /home/drw/idl/secis/eclipse_movie3.pro)
PRO eclipse_movie2,data
Data = FLTARR(504,504,100)
;FOR i = 0, 5999, 60 DO BEGIN
FOR i = 0, 99, 1 DO BEGIN
PRINT,i
IF (i LE 9) THEN a = ;READFITS('broadband/broad000'+ARR2STR(i,/Trim)+'.fit')
IF ((i GT 9) AND (i LE 99)) THEN a = ;READFITS('broadband/broad00'+ARR2STR(i,/Trim)+'.fit')
;IF ((i GT 99) AND (i LE 999)) THEN a = READFITS('secis/broad0'+ARR2STR(i,/Trim)+'.fit')
;IF ((i GT 999)) THEN a = READFITS('secis/broad'+ARR2STR(i,/Trim)+'.fit')
Data(*,*,i) = a
;TVIM, a
ENDFOR
END
(See /home/drw/idl/secis/eclipse_movie3a.pro)
PRO eclipse_movie_narrow,data
Data = FLTARR(504,504,100)
;FOR i = 0, 5999, 60 DO BEGIN
FOR i = 0, 99, 1 DO BEGIN
PRINT,i
IF (i LE 9) THEN a = ;READFITS('narrowband/narrow000'+ARR2STR(i,/Trim)+'.fit')
IF ((i GT 9) AND (i LE 99)) THEN a = ;READFITS('narrowband/narrow00'+ARR2STR(i,/Trim)+'.fit')
IF ((i GT 99) AND (i LE 999)) THEN a = READFITS('secis/broad0'+ARR2STR(i,/Trim)+'.fit')
IF ((i GT 999)) THEN a = READFITS('secis/broad'+ARR2STR(i,/Trim)+'.fit')
Data(*,*,i) = a
;TVIM, a
ENDFOR
END
(See /home/drw/idl/secis/eclipse_movie_narrow.pro)
NAME: eclipsfilter PURPOSE: perform digital filtering in the frequency domain via FFT CATEGORY: Time-series/Spectral analysis CALLING SEQUENCE: result = eclipsfilter(time_series, /TIME, $ lowperiod_cutoff, highperiod_cutoff, /BANDPASS) result = eclipsfilter(time_series, /FREQ, $ lowfreq_cutoff, highfreq_cutoff, /BANDPASS) result = eclipsfilter(time_series, /FREQ, $ lowfreq_cutoff, highfreq_cutoff, /NOTCH) result = eclipsfilter(time_series, maxperiod, /LOWPASS) result = eclipsfilter(time_series, $ highfreq_cutoff, /FREQ, /LOWPASS) result = eclipsfilter(time_series, $ lowfreq_cutoff, /FREQ, /HIGHPASS) result = eclipsfilter(time_series, /FREQ, WTS = wts) INPUTS: time_series = input time series to filter low_cutoff, high_cutoff = the limits (either in frequency or time, dependent on the keyword usage) for the filter. Only one paramter is required if the filter is one-sided (LOWPASS or HIGHPASS). These paramters are ignored if the WTS keyword is used KEYWORD PARAMETERS: FREQ, TIME = signals how the cutoff parameters will be interpretted. Either as PERIODS in the time domain or FREQUENCIES in the frequency domain. Default is /TIME These paramters are ignored if the WTS keyword is used LOWPASS = low-pass filter. Use the first cutoff parameter as the step function cutoff value HIGHPASS = high-pass filter. Use the first cutoff parameter as the step function cutoff value BANDPASS = band-pass filter. Use both cutoff parameters as the limits of the rectangular pass window. NOTCH = notch filter. Use both cutoff parameters as the limits of the rectangular rejection window. WTS = independently set the window weights in the frequency domain. This will override all other parameters. TYPE = can have 1 of four values (case insensitive). "LOWPASS", "HIGHPASS", "NOTCH", "FREQ_FILTER_WTS" OUTPUTS: result = filtered time series COMMON BLOCKS: none. SIDE EFFECTS: none. MODIFICATION HISTORY: Written by: R.A.Vincent, Physics Dept., University of Adelaide, Early 1989. Enhanced: T.J.Harris, Physics Dept., University of Adelaide, Late 1989. Name changed from FILTER.PRO to ECLIPSFILTER.PRO by David Williams, to avoid clashes with another routine of the same name.
(See /home/drw/idl/secis/eclipsfilter.pro)
PROJECT:
SECIS 2001
NAME:
ECWAVE
PURPOSE:
Wavelet transforms of eclipse feature lightcurves, outputting the time
series, the wavelet power transform, the global wavelet transform and
a test against multiple randomised data series.
SYNTAX:
ECWAVE,series,
ecwave,curve,print=print,pc=pc,title=title,nocon=nocon,delt=delt,$
mother=mother
INPUTS:
CURVE - a 1-D time series, e.g. a light curve
INTERACTIVE INPUTS DURING EXECUTION:
The user is first asked for a maximum value for the low-pass filter
called by WAVE_EXAMPLE. For the SECIS data, an unfiltered time series
will be analysed by specifying half the data sampling rate of 44.2 Hz
(i.e. 22.1 Hz).
The second parameter requested is the significance (confidence)
level which the WAVELET function will calculate as a set of contours
in the power transform. Concentrations of power enclosed within these
contours will be significant to that level. E.g., if the user specifies
a value of 0.99 (i.e. 99%) then there is a 1% chance that the power
within the contours is due to noise.
KEYWORDS:
PRINT - if set, then set parameters applicable to printing to a
postscript file. NOTE: Does not actually set the display
to the PostScript device - this must be done manually with
e.g. TOGGLE (recommended).
PC - the plot colour for the contours and cone-of-influence
boundary and cross-hatching. This is a value from 0 to
255. In a monochromatic colour table (e.g. loadct,3 for
red temperature) 0 will be black, 255 will be white, and
any other colours will be somewhere in between (e.g.
scale linearly for colour tables 0,1,3, & 8;
logarithmically for colour table 9).
TITLE - a string, specifying the title over the wavelet transform
part of the display output.
NOCON - if set, then do not display either contours or the
cone-of-influence calculated by the WAVELET routine
OUTPUTS:
None, except for the display of the wavelet transform etc. to
either X windows (the default) or (optionally) the PostScript device.
EXAMPLES:
IDL> ecwave,series,title='Wavelet Transform for our series thing'
to write the output to an Encapsulated PostScript file:
IDL> set_plot,'PS'
IDL> DEVICE,/encapsul,/color,filename='test1.eps',xsize=5,ysize=5
IDL> ecwave,series,title='Another Title',/print,pc=0
IDL> DEVICE,/close
IDL> SET_PLOT,'X'
or, if you have TOGGLE.PRO in your path:
IDL> TOGGLE,filename='wavelet.ps',/landscape,/color
IDL> ecwave,series,title='Another Title',/print,pc=0
IDL> TOGGLE
CALLS:
JFILT.PRO, WAVELET.PRO, WAVE_SIGNIF.PRO, FOURIER.PRO,
SIGNIF_CONF.PRO, RANDOMWAVE.PRO, SECIS2UTC.PRO, COLORBAR.PRO
TODO:
Use SECIS2UTC and get rid of the need to input the UTIN array for
the UT times. Change it so that, instead, you give the number of the
first frame. It`ll then work out the frame range from the number in
the series, and then you can add in the frame numbers at the top, so
that the plot displays the UT time, the time in seconds from the
beginning of the input series, AND the frame number, all on parallel
axes. Helps to reduce confusion.
HISTORY:
v0.9 - Based on STELLARWAVE.PRO & STELLARWAVE2.PRO by DRW@QUB (03/02).
v1.0 - Tidied and modified by DRW @ MSSL/UCL. for the SECIS 2001
eclipse data (27/06/02).
v2.0 - DRW added a lot of new features (to be described) (28/06/02).
(See /home/drw/idl/secis2/ecwave.pro)
Project : EIS
Name : EIS_DBASE
Purpose : install EIS Database
Category : system
Inputs : None
Outputs : None
Keywords : USER = set to user defined ZDBASE
TYPE = type selected = OFFICIAL or USER
History : 28-Jan-2003, D.M. Zarro (EER/GSFC) Written
Contact : DZARRO@SOLAR.STANFORD.EDU
(See /home/drw/idl/eis/eis_dbase.pro)
Project : EIS
Name : EIS_LIST_MAIN
Purpose : List entries in EIS main catalog. Checks for local
copy of catalog in ZDBASE. If not available, accesses
remote copy via socket call.
Category : utility sockets
Inputs : TSTART, TEND = start/end times for list
Outputs : OBS = main observation structure
COUNT = number of elements found
Keywords : SEARCH = search string
SAVE_FILE = save file in which OBS is saved
History : 29-Aug-2002, D.M. Zarro (LAC/GSFC) Written
Contact : DZARRO@SOLAR.STANFORD.EDU
(See /home/drw/idl/eis/eis_list_main.pro)
Project : EIS
Name : EIS_STARTUP
Purpose : Load EIS software and databases
Category : system
Inputs : None
Outputs : None
Keywords : QUIET = set for no output
History : 31-Jan-2003, D.M. Zarro (EER/GSFC) Written
Contact : DZARRO@SOLAR.STANFORD.EDU
(See /home/drw/idl/eis/eis_startup.pro)
NAME:
EI
PURPOSE:
Set the system variable to allow for large pasting of data using
X. Only necessary for the alphas. This has the side effect of
not allowing use of the editing (arrow) keys. This procedure
toggles this ability on and off. NOTE: This is probably a bug
in IDL and therefore the need for this procedure will disappear in
the near future.
CALLING SEQUENCE:
ei
INPUTS:
OPTIONAL INPUTS:
OUTPUTS:
EXAMPLE:
ei
... paste in large amts of data ...
ei
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 1/04/94
MODIFICATION HISTORY:
Added change of prompt Jeff Hicke 05/20/94
(See /home/drw/idl/esrg/ei.pro)
NAME:
EI
PURPOSE:
Set the system variable to allow for large pasting of data using
X. Only necessary for the alphas. This has the side effect of
not allowing use of the editing (arrow) keys. This procedure
toggles this ability on and off. NOTE: This is probably a bug
in IDL and therefore the need for this procedure will disappear in
the near future.
CALLING SEQUENCE:
ei
INPUTS:
OPTIONAL INPUTS:
OUTPUTS:
EXAMPLE:
ei
... paste in large amts of data ...
ei
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 1/04/94
MODIFICATION HISTORY:
Added change of prompt Jeff Hicke 05/20/94
(See /home/drw/idl/old.esrg/ei.pro)
PROJECT: TRACE NAME: elight (euv lightcurve) PURPOSE: A rountine to make an average[-per-pixel] lightcurve for 1024x1024 EUV images. CALLING SEQUENCE: elight, data, curve, background INPUTS: data - data cube curve - name of floating, 1-D output array to contain curve intensities background - name of floating 1-D array to contain background flux intensities expo - the 1-D array of the exposure time (in seconds) for each frame. ( expo(i)=index(i).sht_mdur ) HISTORY: based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by Peter Gallagher and David Williams for TRACE EUV data. Currently takes the top 20% of pixel values and averages their value, placing it in the CURVE array. To be superseded by NEWLIGHT.PRO, a version based on a *total* value summed over all pixels which are >((quiet-mean+)2*standard-deviation)
(See /home/drw/idl/bin/elight.pro)
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: EMISS_CALC
PURPOSE:
To compute the emissivities of all lines of a specified ion over
given ranges of temperature and density.
CATEGORY:
Scientific analysis
EXPLANATION:
This routine calculates:
hc
-- * N_j * A_ji
lamb
where hc = 1.986 * 10^-8 erg AA, and lamb is in angstroms.
The emissivities are stored in a structure called EMISS that also
holds the wavelength of the transition, the level numbers i and j
and also a 'flag', which is set to -1 if the wavelength is negative.
The temperature and density ranges can be specified directly using
the TEMP and DENS keywords. Setting TMAX to the log T_max of the
ion, gives emissivities for 3 temperatures: log T_max +- 0.15.
If DENS is not set, then it is set to 8 to 12 in 0.5 dex intervals.
STDENS allows the start density (of 8) to be changed to some other
value; ND allows the number of densities to be varied (default 9);
DINT allows the density interval to be varied (default 0.5).
CALLING SEQUENCE:
EMISS=EMISS_CALC (IZ, ION, [ TEMP=TEMP, DENS=DENS, RADT=RADT, $
DIL=DIL, PATH=PATH, /NO_DE)
EXAMPLES:
EMISS=EMISS_CALC(26,13)
EMISS=EMISS_CALC(26,13,temp=[6.2],dens=findgen(5)+8)
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
OPTIONAL INPUTS:
TEMP: Direct specification of the temperature range.
DENS: Direct specification of the density range.
RADT: Specify background radiation temperature (default: 6000 K)
DIL: Specify radiation dilution factor (default: 0.0)
PATH: If specified, the routine will look for the atomic data in
the PATH directory, rather than in the CHIANTI database
KEYWORDS:
NO_DE: Drops the hc/lambda factor in the computation of the
emissivities. Useful for emission measure analyses involving
photon fluxes
COMMON BLOCKS:
ELVL, WGFA, UPSILON, RADIATIVE
CALLS:
READ_ELVLC, READ_WGFA2, READ_SPLUPS, POPULATE_PRY,
ZION2NAME, ZION2FILENAME, ZION2SPECTROSCOPIC, READ_IONEQ
HISTORY:
Ver 1, PRY 28-Jun-97
Ver 2, PRY 26-Jul-97 - corrected problem with size of emiss
Ver 3, PRY 22-Sep-97 - allowed photo-excitation to be included
Ver 4, PRY 6-Jul-98 - added PATH
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/emiss_calc.pro)
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: EMISS_CALC
PURPOSE:
To compute the emissivities of all lines of a specified ion over
given ranges of temperature and density.
CATEGORY:
Scientific analysis
EXPLANATION:
This routine calculates:
hc
-- * N_j * A_ji
lamb
where hc = 1.986 * 10^-8 erg AA, and lamb is in angstroms.
The emissivities are stored in a structure called EMISS that also
holds the wavelength of the transition, the level numbers i and j
and also a 'flag', which is set to -1 if the wavelength is negative.
The temperature and density ranges can be specified directly using
the TEMP and DENS keywords. Setting TMAX to the log T_max of the
ion, gives emissivities for 3 temperatures: log T_max +- 0.15.
If DENS is not set, then it is set to 8 to 12 in 0.5 dex intervals.
STDENS allows the start density (of 8) to be changed to some other
value; ND allows the number of densities to be varied (default 9);
DINT allows the density interval to be varied (default 0.5).
CALLING SEQUENCE:
EMISS=EMISS_CALC (IZ, ION, [ TEMP=TEMP, DENS=DENS, RADT=RADT, $
DIL=DIL, PATH=PATH, /NO_DE)
EXAMPLES:
EMISS=EMISS_CALC(26,13)
EMISS=EMISS_CALC(26,13,temp=[6.2],dens=findgen(5)+8)
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
OPTIONAL INPUTS:
TEMP: Direct specification of the temperature range.
DENS: Direct specification of the density range.
RADT: Specify background radiation temperature (default: 6000 K)
DIL: Specify radiation dilution factor (default: 0.0)
PATH: If specified, the routine will look for the atomic data in
the PATH directory, rather than in the CHIANTI database
KEYWORDS:
NO_DE: Drops the hc/lambda factor in the computation of the
emissivities. Useful for emission measure analyses involving
photon fluxes
COMMON BLOCKS:
ELVL, WGFA, UPSILON, RADIATIVE
CALLS:
READ_ELVLC, READ_WGFA2, READ_SPLUPS, POPULATE_PRY,
ZION2NAME, ZION2FILENAME, ZION2SPECTROSCOPIC, READ_IONEQ
HISTORY:
Ver 1, PRY 28-Jun-97
Ver 2, PRY 26-Jul-97 - corrected problem with size of emiss
Ver 3, PRY 22-Sep-97 - allowed photo-excitation to be included
Ver 4, PRY 6-Jul-98 - added PATH
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/ptg/emiss_calc.pro)
NAME:
ENDPS
PURPOSE:
close postscript file, reopen display
CALLING SEQUENCE:
ENDPS
INPUTS:
KEYWORD INPUTS:
notime don't timestamp
OPTIONAL INPUTS:
OUTPUTS:
OPTIONAL OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 9/22/92
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/endps.pro)
NAME:
ENDPS
PURPOSE:
close postscript file, reopen display
CALLING SEQUENCE:
ENDPS
INPUTS:
KEYWORD INPUTS:
notime don't timestamp
OPTIONAL INPUTS:
OUTPUTS:
OPTIONAL OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 9/22/92
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/endps.pro)
NAME:
EOPDATA
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:
Read and interpolate tabulated earth orientation parameters
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
EOPDATA, JDUTC, PMX, PMY, UT1_UTC, DPSI, DEPS, $
/RESET, FILENAME=, ANGUNITS=, TBASE=
DESCRIPTION:
The procedure EOPDATA reads, interpolates and returns Earth
orientation parameters used for precision earth-base astronomy
applications.
** NOTE: The user is responsible for downloading and maintaining an
up-to-date file of earth orientation parameters from the
International Earth Rotation Service. See below. **
This interface is somewhat provisional. See OPEN QUESTIONS below.
The values returned are described below. These descriptions are
taken from the Explanatory Supplement to IERS Bulletins A and B.
* PMX and PMY, the coordinates of the Celestial Ephemeris Pole
(CEP) relative to the earth-fixed International Reference Pole
(IRP). The x-axis is in the direction of the IERS Reference
Meridian (IRM), the y-axis is in the direction 90 degrees West
longitude. The time series of PMX and PMY is referred to as
"polar motion."
These are the coordinates of the earth rotation pole, as seen
in an *earth-fixed* coordinate system. A station whose
coordinates are given in earth-fixed coordinates referred to
the ITRS can be transformed to the earth-fixed coordinates
referred to the true rotation pole of date using the following
matrix transformation:
R_TRUE = RX(PMY) ## RY(PMX) ## R_ITRS
where the matrices RX and RY are defined below.
* UT1, the the rotation angle about the pole. It is related to
the Greenwich mean sidereal time (GMST) by a conventional
relationship (Aoki et al., 1982). It gives access to the
direction of the International Reference Meridian IRM in the
ICRS, reckoned around the CEP axis. It is expressed as the
difference UT1-UTC. Thus, the value of UT1 is computed as:
UT1 = UT1_UTC + UTC
where UTC is the UTC time, expressed in seconds.
* DPSI and DEPS are the offsets in longitude and obliquity of the
celestial pole with respect to its direction defined using the
conventional IAU precession/nutation theory. An a priori
correction model is available in the IERS Conventions (1996),
(McCarthy, 1996). The expressions to compute the nutation
angles are:
DEPS_TRUE = DEPS_1980 + DEPS ;; Nutation in obliquity
DPSI_TRUE = DPSI_1980 + DPSI ;; Nutation in longitude
where DPSI_1980 and DEPS_1980 are the nutation values
determined from the IAU 1980 Nutation Theory; and DPSI_TRUE and
DEPS_TRUE are the nutations to be used as arguments to further
precession and nutation computations.
For requested times which are between tabular values, a linear
interpolation is performed. This is not exactly the correct
procedure, and can result in errors of +/- 0.1 mas in the earth
polar motion and 1 usec in UT1 (see McCarthy & Gambis 1997).
DATA FILES and MAINTENANCE
The user is responsible for downloading and maintaining the earth
orientation parameters file as supplied by the IERS. The format
of the files is the "Final" EOP data ASCII format. They can be
downloaded here:
ftp://maia.usno.navy.mil/ser7/finals.all ;; from May 1976-present
ftp://maia.usno.navy.mil/ser7/finals.data ;; from Jan 1992-present
The user must place this file in a known location, and in *at
least the first call*, this filename must be passed using the
FILENAME keyword.
EOPDATA will load the data once on the first call, and keep a
cached copy for subsequent calls. On a daily basis the file will
be reloaded in case the quantities have been updated from the
server. A reload of data can be forced using the RESET keyword.
ROTATION MATRICES
The rotation matrices RX(T) and RY(T) mentioned above in relation
to polar motion are:
RX(T) =EQ= [[1,0,0], [0,cos(T),sin(T)], [0,-sin(T),cos(T)]]
RY(T) =EQ= [[cos(T),0,-sin(T)], [0,1,0], [sin(T),0,cos(T)]]
RZ(T) =EQ= [[cos(T),sin(T),0], [-sin(T),cos(T),0], [0,0,1]]
and are meant to be applied to a vector R as, RX(T) ## R.
OPEN QUESTIONS
How will the transition to a new IERS EOP series be accomplished?
Using a keyword?
Should there be a quality flag? The EOP file contains a
"predicted" flag, and also there are rows which contain no value
at all. These should probably be flagged somehow.
INPUTS:
JDUTC - a vector or scalar, the UTC time for which earth
orientation parameters are requested, expressed in Julian
Days. The value of the keyword TBASE is added to this
quantity to arrive at the actual Julian date.
OUTPUTS:
PMX, PMY - the earth-fixed angular coordinates of the celestial
ephemeris pole, measured in ANGUNITS units.
UT1_UTC - the value of UT1 - UTC, expressed in seconds.
DPSI, DEPS - the corrections to the IAU 1980 theory of Nutation,
for nutation in longitude and obliquity, expressed in
ANGUNITS units.
KEYWORD PARAMETERS:
FILENAME - scalar string, on the first call, the name of the file
from which earth orientation parameters will be read.
Default value: (none)
TBASE - a fixed epoch time (Julian days) to be added to each value
of JDUTC. Since subtraction of large numbers occurs with
TBASE first, the greatest precision is achieved when TBASE
is expressed as a nearby julian epoch, JDUTC is expressed
as a small offset from the fixed epoch.
Default: 0
ANGUNITS - scalar string, output units of angular parameters.
Possible values are 'ARCSEC' or 'RADIAN'.
Default value: 'RADIAN'
RESET - if set, forces EOP file to be re-read.
EXAMPLE:
SEE ALSO:
HPRNUTANG, TAI_UTC (Markwardt Library)
PRECESS, PREMAT, JPRECESS, BPRECESS (IDL Astronomy Library)
REFERENCES:
Aoki, S., Guinot, B., Kaplan, G.H., Kinoshita, H., McCarthy, D.D.,
Seidelmann, P.K., 1982: Astron. Astrophys., 105, 359-361.
McCarthy, D. D. (ed.) 1996: IERS Conventions, IERS T.N. 21.
http://maia.usno.navy.mil/conventions.html
McCarthy, D. \& Gambis, D. 1997, "Interpolating the IERS Earth
Orientation Data," IERS Gazette No. 13,
http://maia.usno.navy.mil/iers-gaz13
Instructions for high precision EOP data interpolation, not done
in this procedure.
Ray, J. & Gambis, D. 2001, "Explanatory Supplement to IERS
Bulletins A and B,"
http://hpiers.obspm.fr/iers/bul/bulb/explanatory.html
Explains meanings of earth orientation parameters used and
returned by this procedure.
Definition of Final EOP data format
ftp://maia.usno.navy.mil/ser7/readme.finals
MODIFICATION HISTORY:
Written, 30 Jan 2002, CM
Documented, 14 Feb 2002, CM
Add default message, 01 Mar 2002, CM
More robust handling of input file, 10 Mar 2002, CM
$Id: eopdata.pro,v 1.4 2002/03/17 18:46:16 craigm Exp $
(See /home/drw/idl/aux/markwardt/eopdata.pro)
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.
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:
NONAME: If this keyword is set the name of the calling routine
is not printed along with the message.
TRACEBACK: Setting this keyword results in an error traceback
being printed to standard output with the PRINT command.
In addition, any keyword appropriate for the MESSAGE or DIALOG_MESSAGE
routines can also be used.
OUTPUTS:
Currently the only output from the function is the string "OK".
RESTRICTIONS:
The "Warning" Dialog_Message dialog is used by default. Use keywords
/ERROR or /INFORMATION to select other dialog behaviors.
EXAMPLE:
To handle an undefined variable error:
IF N_Elements(variable) EQ 0 THEN $
ok = Error_Message('Variable is undefined', /Traceback)
MODIFICATION HISTORY:
Written by: David 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.
Switched default value for Dialog_Message to "Error" from "Warning". 7 OCT 2000. DWF.
(See /home/drw/idl/aux/error_message.pro)
routine: plotsym
usage: plotsym,x,y,xsym,ysym
purpose: overlays plot symbols on the last data window. A single
call can create symbols of varying size, fill color, and
outline color and thickness. Symbols of arbitrary shape
can be created. Note that the symbols may be filled
with a different color then the outline color. This can
dramatically unclutter the appearance of densely packed
scatter plots. See example.
input:
x x coordinates of symbol centers on plot
y y coordinates of symbol centers on plot
xsym x coordinantes of symbol outline with respect to symbol center
ysym y coordinantes of symbol outline with respect to symbol center
NOTE: if TYPE or XSYM and YSYM are not supplied a circular symbol
is assumed
keyword input:
ocolor outline color of symbol
fcolor fill color of symbol
thick line thickness of symbol outline
size symbol size multiplier
nsym number of symbols on plot, when then number of elements
of x and y are large drawn symbols will overlap and look
too cluttered. use NSYM parameter to reduce the
number of symbols actually drawn. For example if x,y has
10000 elements and nsym=10 then symbol is drawn once
every 1000 points.
type symbol type, a string matching one of
'DIAMOND', 'PENTAGON', 'CLOVER', 'PACMAN',
'SPIRAL', 'BIGX', 'CIRCLE', 'SQUARE',
'TRIANGLE', 'STAR', 'HEXAGON', 'HEART',
'SPADE', 'CLUB'
NOTE: OCOLOR, FCOLOR, THICK and SIZEE may be specified as
single values or vector of values, one for each element
of x and y
device if set, coordinates are in device units
normal if set, coordinates are in normalized units
data if set, coordinates are in data units (default)
NOTE:
the OCOLOR, FCOLOR, THICK and SIZE parameters may be specified as
vectors quantities, one value for each point on the plot
SIDE EFFECTS:
changes the shape of user-defined plot symbol (accessed with psym=8).
EXAMPLE:
;;
x=randomu(iseed,400)
y=randomu(iseed,400)
z=1.-x-y
fcolor=bytscl(z,top=!p.color)
ocolor=5*!p.color
loadct,5
plot,x,y,/nodata
plotsym,x,y,type='square',fcolor=fcolor,ocolor=ocolor,thick=1,size=1.5
;; In this example note how PLOTSYM unclutters the scatter plot
!p.multi=[0,1,2]
x=randomn(iseed,400)
y=randomn(iseed,400)
plot,x,y,/nodata
plotsym,x,y,size=2
plot,x,y,psym=8
;;; In this example use nsym to unclutter the plot
!p.multi=[0,1,2]
x=findgen(400)
y=randf(400,4)
plot,x,y
plotsym,x,y,type='diamond',nsym=10
;;
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/esrgplotsym.pro)
NAME:
EULER
PURPOSE:
Transform between galactic, celestial, and ecliptic coordinates.
Use the procedure ASTRO to use this routine interactively
CALLING SEQUENCE:
EULER,AI,BI,AO,BO,[SELECT]
INPUTS:
AI - Input Longitude in DEGREES, scalar or vector. If only two parameters
are supplied, then AI and BI will be modified to contain the output
longitude and latitude.
BI - Input Latitude in DEGREES
OPTIONAL INPUT:
SELECT - Integer (1-6) specifying type of coordinate transformation.
SELECT From To | SELECT From To
1 RA-DEC(1950) GAL.(ii) | 4 ECLIPTIC RA-DEC
2 GAL.(ii) RA-DEC | 5 ECLIPTIC GAL.(ii)
3 RA-DEC ECLIPTIC | 6 GAL.(ii) ECLIPTIC
If omitted, program will prompt for the value of SELECT
OUTPUTS:
AO - Output Longitude in DEGREES
BO - Output Latitude in DEGREES
REVISION HISTORY:
Written W. Landsman, February 1987
Adapted from Fortran by Daryl Yentis NRL
(See /home/drw/idl/icur/euler.pro)
ROUTINE: expint
PURPOSE: compute the exponential integral of x.
the exponential integral of index n is given by
integral( exp(-tx)/x^n dx)
range of integration is 1 to infinity
USEAGE: result=expint(ind,x)
INPUT:
ind order of exponential integral, for example use ind=1
to get first exponential integral, E1(x)
x argument to exponential integral ( 0 < x < infinity)
OUTPUT:
result exponential integral
SOURCE: Approximation formula from Abromowitz and Stegun (p 231)
author: Paul Ricchiazzi 9DEC92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/expint.pro)
ROUTINE: expint
PURPOSE: compute the exponential integral of x.
the exponential integral of index n is given by
integral( exp(-tx)/x^n dx)
range of integration is 1 to infinity
USEAGE: result=expint(ind,x)
INPUT:
ind order of exponential integral, for example use ind=1
to get first exponential integral, E1(x)
x argument to exponential integral ( 0 < x < infinity)
OUTPUT:
result exponential integral
SOURCE: Approximation formula from Abromowitz and Stegun (p 231)
author: Paul Ricchiazzi 9DEC92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/expint.pro)
NAME:
EXTAST
PURPOSE:
Extract astrometry parameters from a FITS image header.
The astrometry in the header can be in either CD (Coordinate
description) format, or CROTA and CDELT (AIPS-type) format.
However, the output astrometry will always be in CD format.
CALLING SEQUENCE:
EXTAST, hdr, [ astr, noparams ]
INPUT:
HDR - variable containing the FITS header (string array)
OUTPUTS:
ASTR - Anonymous structure containing astrometry info from the FITS
header ASTR always contains the following tags (even though
some projections do not require all the parameters)
.CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2
in DEGREES/PIXEL CD2_1 CD2_2
.CDELT - 2 element vector giving physical increment at reference pixel
.CRPIX - 2 element vector giving X and Y coordinates of reference pixel
(def = NAXIS/2)
.CRVAL - 2 element double precision vector giving R.A. and DEC of
reference pixel in DEGREES
.CTYPE - 2 element string vector giving projection types, default
['RA---TAN','DEC--TAN']
.LONGPOLE - scalar longitude of north pole (default = 180)
.PROJP1 - Scalar parameter needed in some projections
.PROJP2 - Scalar parameter needed in some projections
NOPARAMS - Scalar indicating the results of EXTAST
-1 = Failure - Header missing astrometry parameters
0 = Success - Header contains CD00n00m + CDELT* astrometry
1 = Success - Header contains CROTA + CDELT (AIPS-type) astrometry
2 = Success - Header contains CDn_m astrometry
PROCEDURE
EXTAST checks for astrometry parameters in the following order:
(1) the CD matrix CD1_1,CD1_2... plus CRPIX and CRVAL.
(2) the CD matrix CD001001,CD001002...plus CRPIX and CRVAL
(3) CROTA2 (or CROTA1) and CDELT plus CRPIX and CRVAL.
See the Memo: Representations of Celestial Coordinates in FITS by
Griesen and Calabretta, available at fits.cv.nrao.edu
NOTES:
(1) An anonymous structure is created to avoid structure definition
conflicts. This is needed because some projection systems
require additional dimensions (i.e. spherical cube
projections require a specification of the cube face).
PROCEDURES CALLED:
FITS_CD_FIX, GSSSEXTAST, SXPAR(), ZPARCHECK
REVISION HISTORY
Written by B. Boothman 4/15/86
Accept CD001001 keywords 1-3-88
Accept CD1_1, CD2_1... keywords W. Landsman Nov. 92
Recognize GSSS FITS header W. Landsman June 94
REBIN keyword added 11/99 by FWM to deal with rebinned images
(See /home/drw/idl/icur/extast.pro)
ROUTINE: extract_cube PURPOSE: Extract data cube from CDS data file. When run the code prompts the user to select a line USEAGE: extract_cube, qlds, cube INPUT: qlds The QLDS OUTPUT: cube data cube of line selected with dim (dispersion, Solar_x,Solar_y) EXAMPLE: EXTRACT_CUBE, qlds, Cube AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/extract_cube.pro)
ROUTINE: extract_cube PURPOSE: Extract data cube from CDS data file. When run the code prompts the user to select a line USEAGE: extract_cube, qlds, cube INPUT: qlds The QLDS OUTPUT: cube data cube of line selected with dim (dispersion, Solar_x,Solar_y) EXAMPLE: EXTRACT_CUBE, qlds, Cube AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/ptg/extract_cube.pro)
ROUTINE: extract_line PURPOSE: Extract line flux and correct wavelength scale for NIS data USEAGE: EXTRACT_LINE, qlds, wave, flux, Lab_Wav INPUT: qlds The qlds. OUTPUT: wave Wavelength array for the selected ion. flux Flux array for the selected ion. Lab_Wav The Kelly list line wavelength AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/extract_line.pro)
ROUTINE: extract_line PURPOSE: Extract line flux and correct wavelength scale for NIS data USEAGE: EXTRACT_LINE, qlds, wave, flux, Lab_Wav INPUT: qlds The qlds. OUTPUT: wave Wavelength array for the selected ion. flux Flux array for the selected ion. Lab_Wav The Kelly list line wavelength AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/ptg/extract_line.pro)
NAME: EXTRACT_POWER_ROI HISTORY: v1.0: DRW @ MSSL, 23/01/03 TO DO: Use DSPLINE to smoothly pick out the time/scale boundary from the contour, looks a bit jagged-edged as it stands (31/03/03)
(See /home/drw/idl/secis/extract_power_roi.pro)
ROUTINE: extract_spectrum
PURPOSE: Display an INT_DIST image, allow user to select region and
then distplay the average spectrum for the region
USEAGE: extract_spectum, qlds, Wave, Flux
INPUT:
qlds The INT_DIST qlds
OUTPUT:
Wave Spectrum wavelength
Flux Spectrum flux
EXAMPLE: EXTRACT_SPECTRUM, QLDS, Wavelength, Flux
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/extract_spectrum.pro)
ROUTINE: extract_spectrum
PURPOSE: Display an INT_DIST image, allow user to select region and
then distplay the average spectrum for the region
USEAGE: extract_spectum, qlds, Wave, Flux
INPUT:
qlds The INT_DIST qlds
OUTPUT:
Wave Spectrum wavelength
Flux Spectrum flux
EXAMPLE: EXTRACT_SPECTRUM, QLDS, Wavelength, Flux
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/ptg/extract_spectrum.pro)
ROUTINE: eye
PURPOSE: draw an eye symbol to show observer position and look direction
USEAGE: eye,x0,y0,angle=angle,size=size,color=color,icolor=icolor,$
data=data,device=device
INPUT:
x0,y0 coordinates of eye symbol position (normal coordinates by default)
KEYWORD INPUT:
angle angle of symbol wrt due right alignment
size symbol size
color color index used to draw eye outline
icolor color index used to draw iris
data if set, x0,y0 in data coordinates
device if set, x0,y0 in device coordinates
EXAMPLE:
plot,[0,1],/nodata
arrow,0,1,.5,.5,/data
eye,.55,.45,/data,size=3,angle=135
; here is a interactive method to place the eye symbol
!err=0 & angle=0 & x=.5 & y=.5
tvcrs,.5,.5,/norm & while !err ne 4 do begin &$
!err=0 &$
eye,x,y,angle=angle,size=5,color=0 &$
cursor,x,y,/norm,/nowait &$
if !err eq 1 then angle=angle-5 &$
if !err eq 2 then angle=angle+5 &$
eye,x,y,angle=angle,size=5 &$
wait,.05 &$
endwhile
cmdstr=string(f='("eye,",2(g10.3,","),"angle=",g10.3)',x,y,angle)
print,strcompress(cmdstr,/remove_all)
AUTHOR: Paul Ricchiazzi 10 Dec 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/eye.pro)
NAME: fe12ct PURPOSE: Set up an EIT Fe XII-like colour table USAGE: fe12ct PARAMETERS:None AUTHOR: Dave Williams (drw@mssl.ucl.ac.uk) 11 July 03
(See /home/drw/idl/gen/fe12ct.pro)
ROUTINE: ff
PURPOSE: Locate CDS file
USEAGE: ff, Filename, Directory
INPUT:
Filename String containing name of file to be located.
OUTPUT:
Directory Srting containing name of directory
Example: FF, 's7038r00.fits', Dir
PRINT, Dir
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/ff.pro)
ROUTINE: ff
PURPOSE: Locate CDS file
USEAGE: ff, Filename, Directory
INPUT:
Filename String containing name of file to be located.
OUTPUT:
Directory Srting containing name of directory
Example: FF, 's7038r00.fits', Dir
PRINT, Dir
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/ptg/ff.pro)
ROUTINE: figlet
PURPOSE: write a figure letter
USEAGE: figlet,x,y,charsize=charsize,font=font
INPUT:
x subnormal coordinates of letter (default = .04)
y subnormal coordinates of letter (default = 1.-.6*ychsz)
where
charsize*!d.y_ch_size
ychsz= --------------------------------------
!d.y_vsize*(!y.window(1)-!y.window(0))
KEYWORD INPUT:
charsize character size (size is halved if more than 2 plots are
ganged in either horizontal or vertical)
font vector drawn font (default = 17)
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
!p.multi=[0,2,3]
plot,indgen(9) & figlet
plot,indgen(9) & figlet
plot,indgen(9) & figlet
plot,indgen(9) & figlet
plot,indgen(9) & figlet,-.05
plot,indgen(9) & figlet,-.05
AUTHOR: Paul Ricchiazzi 13 Oct 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/figlet.pro)
routine: fignum
useage: fignum,fig=fig,charsize=charsize,font=font
input: none
keyword input:
fig
if FIG is set to an integer greater than zero figure numbering
is enabled and the initial figure number is set to FIG. If FIG
is set to zero figure numbering is disabled. If FIG is set to a
string scalar then that string will be appended to "Figure" and
written to as usual. For example fignum,fig="4a" writes "Figure 4a".
output: none
PURPOSE:
automatical increment a figure number index and draw the number
on a sequence of plots.
COMMON BLOCKS: fignum_blk
EXAMPLE:
plot,dist(20)
fignum,fig=1,font='!3',charsize=2
for i=1,4 do begin & plot,dist(20) & fignum & pause & end
author: Paul Ricchiazzi 22sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/fignum.pro)
routine: fignum
useage: fignum,fig=fig,charsize=charsize,font=font
input: none
keyword input:
fig
if FIG is set to an integer greater than zero figure numbering
is enabled and the initial figure number is set to FIG. If FIG
is set to zero figure numbering is disabled. If FIG is set to a
string scalar then that string will be appended to "Figure" and
written to as usual. For example fignum,fig="4a" writes "Figure 4a".
output: none
PURPOSE:
automatical increment a figure number index and draw the number
on a sequence of plots.
COMMON BLOCKS: fignum_blk
EXAMPLE:
plot,dist(20)
fignum,fig=1,font='!3',charsize=2
for i=1,4 do begin & plot,dist(20) & fignum & pause & end
author: Paul Ricchiazzi 22sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/fignum.pro)
NAME:
FILETYPE
PURPOSE:
Returns the type of file from the DATA_FMT keyword (UCB data),
the INSTMODE keyword (OPUS data), or the INSTRUME keyword
(FES data). Used to determine what program should be used to
read the file.
CALLING SEQUENCE:
Result = FILETYPE(Filename)
INPUT:
Filename: Scalar or vector string giving the name of the FITS file.
KEYWORD PARAMETERS:
SILENT: If included, suppress informative messages.
EXAMPLE:
Display the file type of the FITS files 'temp.fit' in the current
directory
IDL> result = filetype('temp.fit')
PROCEDURES USED:
MODIFICATION HISTORY:
3 November 1998 Rewritten from scratch by David Sahnow. Previously,
a modified version of FITS_INFO was used.
6 November 1998 Modified to handle files that have been processed by
the pipeline (IMAGE_COR keyword is COMPLETE).
15 November 1998 Changed call to NUMEXT to NUM_EXT.
14 December 1998 Added calls to FREE_LUN to deallocated lun1. Fixed
typo in OPUS/INITIAL section.
8 April 1999 Modified to handle pipeline calibration files (CALFTYPE
type).
11 June 1999 Modified to handle FES files (FES type).
29 September 1999 Modified to allow the IMAG_COR keyword to be
'PERFORM' (partially processed throught the pipeline)
30 May 2000 Added SILENT keyword.
19 June 2000 Modified to allow TTGD files to return 'PIPELINE.'
6 October 2000 Added 'ONED' type for calibrated 1D data.
4 November 2000 Added call to EXPAND_TILDE for input filename.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/filetype.pro)
NAME:
file_exist
PURPOSE:
The result of this function is 1 if a file exist and 0 if not
CATEGORY:
DATAFILES
CALLING SEQUENCE:
Result=file_exist(file_name,[valid=valid])
INPUTS:
file_name: The name of the File or an array of file_names
KEYWORD PARAMETERS:
valid: if arg_present the valid indices are returned in valid
OUTPUTS:
This function returns 1 if the file exist and 0 if not
EXAMPLE:
result=file_exist('otto.nc')
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1998-May-18
1999-June-29: searching of multiple files now possible
2001-Jun-22 : idl bug removed if the filename is longer than 319 sign. (idl5.4 crahes)
(See /home/drw/idl/icglib/pro/file_exist.pro)
ROUTINE: fillvec
PURPOSE:
USEAGE: fillvec,vec,tol
INPUT:
vec vector with some bad points
tol index array of good points
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 11 Sep 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/fillvec.pro)
ROUTINE: fill_arr
USEAGE: fill_arr,a,ii
fill_arr,a,ii,niter=niter,omega=omega,tol=tol,po=po
PURPOSE: fill in undefined regions of a 2-d array by interpolation
INPUT:
a array with some undefined points
ii index array of good image points,
E.G., ii=where(aa ne 999)
KEYWORD INPUT
tol maximum tolerance to achieve before stopping iteration
(default=0.001)
niter number of smoothing iterations (default=100)
po if set print diagnostic print out every PO iterations
OUTPUT:
a image array with initially undefined points replaced
with values that vary smoothly in all dimensions
Initially defined points are unchanged.
PROCEDURE: repeat this sequence
asave=a(ii)
a=smooth(a,3)
a(ii)=asave
AUTHOR Paul Ricchiazzi 29oct92
Earth Space Research Group UCSB
(See /home/drw/idl/esrg/fill_arr.pro)
ROUTINE: fill_arr
USEAGE: fill_arr,a,ii
fill_arr,a,ii,niter=niter,omega=omega,tol=tol,po=po
PURPOSE: fill in undefined regions of a 2-d array by interpolation
INPUT:
a array with some undefined points
ii index array of good image points,
E.G., ii=where(aa ne 999)
KEYWORD INPUT
tol maximum tolerance to achieve before stopping iteration
(default=0.001)
niter number of smoothing iterations (default=100)
po if set print diagnostic print out every PO iterations
OUTPUT:
a image array with initially undefined points replaced
with values that vary smoothly in all dimensions
Initially defined points are unchanged.
PROCEDURE: repeat this sequence
asave=a(ii)
a=smooth(a,3)
a(ii)=asave
AUTHOR Paul Ricchiazzi 29oct92
Earth Space Research Group UCSB
(See /home/drw/idl/old.esrg/fill_arr.pro)
NAME:
FILL_CONT
PURPOSE:
Returns a byte array with filled contours.
CATEGORY:
CALLING SEQUENCE:
img = fill_cont(z)
INPUTS:
z = 2-d array to contour. in
KEYWORD PARAMETERS:
Keywords:
LEVELS=lv Array of contour levels. Default
is 8 contours from array min to max. First value
in LEVELS should be the minimum of the first contour
range, and the last should be the maximum of the
last contour range. For example, for 3 contour
ranges from 23 to 130 LEVEL should be:
23.0000 58.6667 94.3333 130.00
N_LEVELS=n Number of evenly spaced levels to contour
from array min to max. Only if LEVELS not given.
COLORS=clr Array of contour colors. Default
is enough colors to handle LEVELS
spaced from 0 to !d.table_size-1. Number of colors
is 1 less than the number in LEVELS.
OUTPUTS:
img = output image. out
Same size as input array.
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 22 Jan, 1993
R. Sterner, 1998 Jan 15 --- Dropped use of !d.n_colors.
Copyright (C) 1993, 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.
(See /home/drw/idl/gen/fill_cont.pro)
ROUTINE: fill_image
USEAGE: fill_image,a,ii
PURPOSE: fill in undefined regions of a 2-d array by interpolation
INPUT:
a image array with some undefined points
ii index array of bad image points,
E.G., ii=where(aa eq 999)
keyword input
extrapolate if set extrapolation is used to fill in bad values outside
of region covered by convex hull of good points.
OUTPUT:
a image array with initially undefined points replaced
with values that vary smoothly in both the horizontal and
vertical directions. Initially defined points are
unchanged.
PROCEDURE: Use TRIANGULATE and TRIGRID to establish a linear
interpolation function which is used to fill in
the undefined regions. The points used to
generate the triangulation are immediately
adjacent to the undefined regions. "Good data" regions
are unchanged. Execution time is increased if a
large fraction of the image is undefined.
EXAMPLE:
a=fltarr(16,16)
x=[4,11,4,11]
y=[4,4,11,11]
a(x,y)=[1,2,4,3.]
fill_image,a,where(a eq 0.),/extra
tvim,a,/scale
print,a(x,y)
; create a test pattern, splatter on some "no data"
; and fix it back up with FILL_IMAGE
; compare original data with fixed up data
w8x11
!p.multi=[0,2,2]
loadct,5
a=randata(256,256,s=3) & a=a-min(a) & aa=a
tvim,a>0,/scale,title='Original Data',clev=clev
contour,a>0,/overplot,levels=clev
a(where(smooth(randomu(iseed,256,256),21) gt .51))=-999.; bad values
tvim,a>0,/scale,title='Missing Data'
fill_image,a,where(a eq -999)
tvim,a>0,/scale,title='Restored data'
contour,a>0,/overplot,levels=clev
confill,aa-a,levels=[-1,-.1,-.01,.01,.1,1],title='Difference',/asp,c_thic=0
AUTHOR Paul Ricchiazzi 29oct92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/fill_image.pro)
ROUTINE: fill_image
USEAGE: fill_image,a,ii
PURPOSE: fill in undefined regions of a 2-d array by interpolation
INPUT:
a image array with some undefined points
ii index array of bad image points,
E.G., ii=where(aa eq 999)
OUTPUT:
a image array with initially undefined points replaced
with values that vary smoothly in both the horizontal and
vertical directions. Initially defined points are
unchanged.
PROCEDURE: Use TRIANGULATE and TRIGRID to establish a linear
interpolation function which is used to fill in
the undefined regions. The points used to
generate the triangulation are immediately
adjacent to the undefined regions. "Good data" regions
are unchanged. Executiona time is increased if a
large fraction of the image is undefined.
EXAMPLE:
; create a test pattern, splatter on some "no data"
; and fix it back up with FILL_IMAGE
; compare original data with fixed up data
w8x11
!p.multi=[0,2,2]
loadct,5
a=randata(256,256,s=3) & a=a-min(a) & aa=a
tvim,a>0,/scale,title='Original Data',clev=clev
contour,a>0,/overplot,levels=clev
a(where(smooth(randomu(iseed,256,256),21) gt .51))=-999.; bad values
tvim,a>0,/scale,title='Missing Data'
fill_image,a,where(a eq -999)
tvim,a>0,/scale,title='Restored data'
contour,a>0,/overplot,levels=clev
confill,aa-a,levels=[-1,-.1,-.01,.01,.1,1],title='Difference',/asp,c_thic=0
AUTHOR Paul Ricchiazzi 29oct92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/fill_image.pro)
(See /home/drw/idl/jma/filt.pro)
PROJECT:
CHROMOSPHERIC OSCILLATIONS, QUB (NB several parameters specfic to this useage
should be changed for other projects)
NAME:
FILT2EC
PURPOSE:
To filter a time series (either high , low or band) and return
the filtered time series. It carries this out by convolving the time series
with a bessel shaped kernel. The kernel is created by digital_filter
"/usr/local/rsi/idl/lib/digital_filter.pro"
The convolution is carried out by convol, an inbuilt IDL routine
By default prints out the power of peaks in the filtered power spectrum
USEAGE:
filt2,timeseries,filtered_timeseries,num_peaks,$
des_power,signif_fts,signif_fts2,frequency_array,/origpeaks,/fish
INPUTS:
timeseries - the original unfiltered time series
OPTIONAL INPUTS:
num_peaks - the number of peaks in the power spectrum you wish to pick out
OUTPUTS:
filtered_timeseries - the filtered time series
OPTIONAL OUTPUTS:
des_power - a (2 * numpeaks) array created by sort_powers
/home/jma/idl/vtt/post_bbso/sort_powers.pro
signif_fts - the 99% confidence level created by signif_conf
/home/jma/idl/vtt/post_bbso/signif_conf.pro
signif_fts2 - the 95% confidence level created by signif_conf
freq_fts - the frequency array
KEYWORDS:
origpeaks - prints out power of peaks in the original power spectrum
fish - prints out the fish g-factor
/home/jma/idl/vtt/post_bbso/fish_signif.pro
signal - plots on the signal /noise seperation
usually found from /home/jma/idl/vtt/jma/powerlaw1.pro
PROGRAM INPUTS
delta - the time seperation of the time series, default 45
f_hi - the high frequency cutoff, default nyquist frequency
f_lo - the low frequency cutoff, default 0.0005
a - input to digital_filter
in effect increasing this smoothes off the edge of the filter
it also decreases the number of 'wiggles' after the edge
nt - input to digital_filter
in effect increasing this makes the filter edge more abrupt
also increases the number of wiggles after the filter
For a pictorial explanation run this batch file
/home/jma/idl/vtt/post_bbso/test_filt.bat
TO DO:
Make the program more generic by changing the PROGRAM INPUTS to actual inputs
This can be acheived by IF NOT KEYWORD_SET (....) THEN READ,'....',input
Add in a ,/no_display keyword
HISTORY:
Adapted in the clumsiest way possible from FILT2 -- se its documentation for details.
v1.0 - written by James McAteer and Peter Gallagher in Big Bear, CA (08/01) in its original filt.pro
/home/jma/idl/vtt/jma/filt.pro
v2.0 - Adjustments and alteration by JMA to make it more generic (09/01)
v2.1 - JMA added in SIGNIF keyword after signif.pro (09/01)
v2.2 - JMA added des_power,signif_fts,fish,origpeaks,num
and removed the 'time' input from the call line (09/01)
v3.0 - JMA and David Williams finally understand exactly what filtering is doing
fts = convol( ts, kernel, /edge_truc ) changed to
fts = convol( ts, kernel, /edge_wrap ).
Filtering can be checked by dividing filtered power spectrum by the original
power spectrum. Also now understand what a and nt are doing
Best to maximise nt and a (although this increases computational time) (11/01)
(See /home/drw/idl/secis/filt2ec.pro)
PROJECT: CHROMOSPHERIC OSCILLATIONS, QUB (NB several parameters specfic to this useage should be changed for other projects) NAME: FILT2 PURPOSE: To filter a time series (either high , low or band) and return the filtered time series. It carries this out by convolving the time series with a bessel shaped kernel. The kernel is created by digital_filter "/usr/local/rsi/idl/lib/digital_filter.pro" The convolution is carried out by convol, an inbuilt IDL routine By default prints out the power of peaks in the filtered power spectrum USEAGE: filt2,timeseries,filtered_timeseries,num_peaks,$ des_power,signif_fts,signif_fts2,frequency_array,/origpeaks,/fish INPUTS: timeseries - the original unfiltered time series OPTIONAL INPUTS: num_peaks - the number of peaks in the power spectrum you wish to pick out. set this to a maximum of half the number of points in time series. this will print out the peaks in order of power OUTPUTS: filtered_timeseries - the filtered time series OPTIONAL OUTPUTS: des_power - a (2 * numpeaks) array created by sort_powers /home/jma/idl/vtt/post_bbso/sort_powers.pro signif_fts - the 99% confidence level created by signif_conf /home/jma/idl/vtt/post_bbso/signif_conf.pro signif_fts2 - the 95% confidence level created by signif_conf freq_fts - the frequency array KEYWORDS: origpeaks - prints out power of peaks in the original power spectrum fish - prints out the fish g-factor /home/jma/idl/vtt/post_bbso/fish_signif.pro signal - plots on the signal /noise seperation usually found from /home/jma/idl/vtt/jma/powerlaw1.pro nodisp - turns off the display of the FFT's profile - shows the filter profile PROGRAM INPUTS delta - the time seperation of the time series, default 45 f_hi - the high frequency cutoff, default nyquist frequency f_lo - the low frequency cutoff, default 0.0005 a - input to digital_filter in effect increasing this smoothes off the edge of the filter it also decreases the number of 'wiggles' after the edge nt - input to digital_filter in effect increasing this makes the filter edge more abrupt also increases the number of wiggles after the filter For a pictorial explanation run this batch file /home/jma/idl/vtt/post_bbso/test_filt.bat TO DO: 1)Make the program more generic by changing the PROGRAM INPUTS to actual inputs This can be acheived by IF NOT KEYWORD_SET (....) THEN READ,'....',input 2) replace pgfft by fourier.pro, take out some extince signif keywords HISTORY: v1.0 - written by James McAteer and Peter Gallagher in Big Bear, CA (08/01) in its original filt.pro /home/jma/idl/vtt/jma/filt.pro v2.0 - Adjustments and alteration by JMA to make it more generic (09/01) v2.1 - JMA added in SIGNIF keyword after signif.pro (09/01) v2.2 - JMA added des_power,signif_fts,fish,origpeaks,num and removed the 'time' input from the call line (09/01) v3.0 - JMA and David Williams finally understand exactly what filtering is doing fts = convol( ts, kernel, /edge_truc ) changed to fts = convol( ts, kernel, /edge_wrap ). Filtering can be checked by dividing filtered power spectrum by the original power spectrum. Also now understand what a and nt are doing Best to maximise nt and a (although this increases computational time) (11/01) v3.1 - JMA added in ,/nodisp and ,/profile keywords (01/02)
(See /home/drw/idl/vtt/post_bbso/filt2.pro)
PROJECT: CHROMOSPHERIC OSCILLATIONS, QUB (NB several parameters specfic to this useage should be changed for other projects) NAME: FILT2 PURPOSE: To filter a time series (either high , low or band) and return the filtered time series. It carries this out by convolving the time series with a bessel shaped kernel. The kernel is created by digital_filter "/usr/local/rsi/idl/lib/digital_filter.pro" The convolution is carried out by convol, an inbuilt IDL routine By default prints out the power of peaks in the filtered power spectrum USEAGE: filt2,timeseries,filtered_timeseries,num_peaks,$ des_power,signif_fts,signif_fts2,frequency_array,/origpeaks,/fish INPUTS: timeseries - the original unfiltered time series OPTIONAL INPUTS: num_peaks - the number of peaks in the power spectrum you wish to pick out. set this to a maximum of half the number of points in time series. this will print out the peaks in order of power OUTPUTS: filtered_timeseries - the filtered time series OPTIONAL OUTPUTS: des_power - a (2 * numpeaks) array created by sort_powers /home/jma/idl/vtt/post_bbso/sort_powers.pro signif_fts - the 99% confidence level created by signif_conf /home/jma/idl/vtt/post_bbso/signif_conf.pro signif_fts2 - the 95% confidence level created by signif_conf freq_fts - the frequency array KEYWORDS: origpeaks - prints out power of peaks in the original power spectrum fish - prints out the fish g-factor /home/jma/idl/vtt/post_bbso/fish_signif.pro signal - plots on the signal /noise seperation usually found from /home/jma/idl/vtt/jma/powerlaw1.pro nodisp - turns off the display of the FFT's profile - shows the filter profile PROGRAM INPUTS delta - the time seperation of the time series, default 45 f_hi - the high frequency cutoff, default nyquist frequency f_lo - the low frequency cutoff, default 0.0005 a - input to digital_filter in effect increasing this smoothes off the edge of the filter it also decreases the number of 'wiggles' after the edge nt - input to digital_filter in effect increasing this makes the filter edge more abrupt also increases the number of wiggles after the filter For a pictorial explanation run this batch file /home/jma/idl/vtt/post_bbso/test_filt.bat TO DO: 1)Make the program more generic by changing the PROGRAM INPUTS to actual inputs This can be acheived by IF NOT KEYWORD_SET (....) THEN READ,'....',input 2) replace pgfft by fourier.pro, take out some extince signif keywords HISTORY: v1.0 - written by James McAteer and Peter Gallagher in Big Bear, CA (08/01) in its original filt.pro /home/jma/idl/vtt/jma/filt.pro v2.0 - Adjustments and alteration by JMA to make it more generic (09/01) v2.1 - JMA added in SIGNIF keyword after signif.pro (09/01) v2.2 - JMA added des_power,signif_fts,fish,origpeaks,num and removed the 'time' input from the call line (09/01) v3.0 - JMA and David Williams finally understand exactly what filtering is doing fts = convol( ts, kernel, /edge_truc ) changed to fts = convol( ts, kernel, /edge_wrap ). Filtering can be checked by dividing filtered power spectrum by the original power spectrum. Also now understand what a and nt are doing Best to maximise nt and a (although this increases computational time) (11/01) v3.1 - JMA added in ,/nodisp and ,/profile keywords (01/02)
(See /home/drw/idl/jma/filt2.pro)
NAME: FILTER_IMAGE PURPOSE: Identical to MEDIAN or SMOOTH but handle edges and allow iterations. 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 options 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
(See /home/drw/idl/bin/filter_image.pro)
ROUTINE: findex
PURPOSE: Compute "floating point index" into a table for use with
INTERPOLATE.
USEAGE: result = findex(u,v)
INPUT:
u a monitically increasing or decreasing 1-D grid
v a scalor, or array of values
OUTPUT:
result Floating point index. Integer part of RESULT(i) gives
the index into to U such that V(i) is between
U(RESULT(i)) and U(RESULT(i)+1). The fractional part
is the weighting factor
V(i)-U(RESULT(i))
---------------------
U(RESULT(i)+1)-U(RESULT(i))
DISCUSSION:
This routine is used to expedite one dimensional
interpolation on irregular 1-d grids. Using this routine
with INTERPOLATE is much faster then IDL's INTERPOL
procedure because it uses a binary instead of linear
search algorithm. The speedup is even more dramatic when
the same independent variable (V) and grid (U) are used
for several dependent variable interpolations.
EXAMPLE:
; In this example I found the FINDEX + INTERPOLATE combination
; to be about 1000 times faster then INTERPOL.
x=randomu(iseed,10000) & x=x(sort(x)) & y=x^2-x
xx=randomu(iseed,1000)
t=systime(1) & y1=interpolate(y,findex(x,xx)) & t1=systime(1)-t
t=systime(1) & y2=interpol(y,x,xx) & t2=systime(1)-t
!p.multi=[0,1,2]
plot,xx,y1,title=string('findex cpu time=',t1),psym=3
plot,xx,y2,title=string('interpol cpu time=',t2),psym=3
AUTHOR: Paul Ricchiazzi 21 Feb 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/findex.pro)
useage: findrng,x1,x2,x3
purpose: generates x3 floating point numbers
spanning range x1 to x2
KEYWORD
dx if set ignor x3 and compute number of elements with 1+(x2-x1)/dx
where dx is the increment
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/findrng.pro)
useage: findrng,x1,x2,x3
purpose: generates x3 floating point numbers
spanning range x1 to x2
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/findrng.pro)
NAME: FIND_BOXFFT PURPOSE: To extract a lightcurve from a given area on the SECIS sequence, supplied as a data cube, and find its FFT spectrum, using PG_FFT. CALLING SEQUENCE: FIND_BOXFFT,CUBE,CURVE,$ HC=HC,RS=RS,UT=UT
(See /home/drw/idl/secis2/find_boxfft.pro)
NAME:
FIND_MOMENTS
PURPOSE:
Find moments in lambda as a function of x in an image[x,lambda].
If a restricted range in lambda is desired, the simplest approach
is to send FIND_MOMENTS only the desired subset of the image.
Wavelength is measured in pixels, with zero at the bottom of the
image.
INPUT PARAMETERS:
IMAGE -- 2D array of intensities as a function of x and lambda.
SIDE EFFECTS:
Any negative elements in IMAGE are set to zero.
HISTORY:
Written by CCK, 20030608
(See /home/drw/idl/my_tomography3/find_moments.pro)
NAME:
FIND_QUARTILES
PURPOSE:
Find quartiles in lambda as a function of x in an image[x,lambda].
If a restricted range in lambda is desired, the simplest approach
is to send FIND_QUARTILES only the desired subset of the image.
Wavelength is measured in pixels, with zero at the bottom of the
image. Note that the cumulative distribution is interpolated
linearly to allow crude sub-pixel resolution of quartiles.
Note that the cumulative distribution can also be returned.
INPUT PARAMETERS:
IMAGE -- 2D array of intensities as a function of x and lambda.
SIDE EFFECTS:
Any negative elements in IMAGE are set to zero.
HISTORY:
Written by CCK, 20030608
(See /home/drw/idl/my_tomography3/find_quartiles.pro)
Project : SOHO - CDS
Name :
FIND_WITH_DEF()
Purpose :
Searches for files with a default path and extension.
Explanation :
Finds files using default paths and extensions, similar to using the
DEFAULT keyword with the OPEN statement in VMS. Using this routine
together with environment variables allows an OS-independent approach
to finding files.
Use :
Result = FIND_WITH_DEF( FILENAME, PATHS [, EXTENSIONS ] )
FILENAME = ''
READ, 'File to open: ', FILENAME
FILE = FIND_WITH_DEF( FILENAME, 'SERTS_DATA', '.fix' )
IF FILE NE '' THEN ...
Inputs :
FILENAME = Name of file to be searched for. It may either be a
complete filename, or the path or extension could be left
off, in which case the routine will attempt to find the
file using the default paths and extensions.
PATHS = One or more default paths to use in the search in case
FILENAME does not contain a path itself. 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. The current
directory is always searched first, unless the keyword
NOCURRENT is set.
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.
RESET = The FIND_WITH_DEF routine supports paths which are
preceeded with the plus sign to signal that all
subdirectories should also be searched. Often this is
used with logical names. It can be rather slow to search
through these subdirectories. The /RESET keyword can be
used to redefine an environment variable so that
subsequent calls don't need to look for the
subdirectories.
To use /RESET, the PATHS parameter must contain the name
of a *single* environment variable. For example
setenv,'FITS_DATA=+/datadisk/fits'
file = find_with_def('test.fits','FITS_DATA',/reset)
Opt. Inputs :
EXTENSIONS = One or more extensions to append to end of filename if the
filename does not contain one (e.g. ".dat"). The period
is optional. Multiple extensions can be separated by
commas or colons.
Outputs :
The result of the function is the name of the file if successful, or
the null string if unsuccessful.
Opt. Outputs:
None.
Keywords :
NOCURRENT = If set, then the current directory is not searched.
Calls :
STR_SEP, BREAK_PATH, FIND_ALL_DIR
Common :
None.
Restrictions:
None.
Side effects:
None.
Category :
Utilities, Operating_system
Prev. Hist. :
None, but influenced by TEST_OPENR by William Thompson, and CONCAT_DIR
by M. Morrison.
Written :
William Thompson, GSFC, 5 April 1993.
Modified :
Version 1, William Thompson, GSFC, 3 May 1993.
Removed trailing / and : characters.
Fixed bugs
Allow for commas within values of logical names.
Added keyword NOCURRENT.
Changed to call BREAK_PATH
Version 2, William Thompson, GSFC, 3 November 1994
Made EXTENSIONS optional.
Version 3, William Thompson, GSFC, 30 April 1996
Call FIND_ALL_DIR to resolve any plus signs.
Version 4, S.V. Haugan, UiO, 5 June 1996
Using OPENR,..,ERROR=ERROR to avoid an IDL 3.6
internal nesting error.
Version 5, R.A. Schwartz, GSFC, 11 July 1996
Use SPEC_DIR to interpret PATH under VMS
Version 6, William Thompson, GSFC, 5 August 1996
Took out call to SPEC_DIR (i.e., reverted to version 4). The
use of SPEC_DIR was required to support logical names defined
via SETLOG,/CONFINE. However, it conflicted with the ability
to use logical names with multiple values. Removing the
/CONFINE made it unnecessary to call SPEC_DIR in this routine.
Version 7, William Thompson, GSFC, 6 August 1996
Added keyword RESET
Version 8, D. Zarro (SAC/GSFC) 23 March 1998
Trimmed blanks in input FILENAME
Version : Version 8
(See /home/drw/idl/aux/find_with_def.pro)
FUNCTION finterp
USEAGE result=finterp(table,uvar)
PURPOSE: Compute the floating point interpolation index of
UVAR(i,j,k...) into TABLE(*,i,j,k...) or TABLE(*).
For example, if uvar(i,j) is half way between
table(4,i,j) and table(5,i,j) then result(i,j)=4.5.
NOTE: If TABLE is a vector the action of FINTERP is
the same as INTERPOL(findgen(n),TABLE,UVAR). However,
FINTERP should be much faster whenever UVAR is large
and the number of TABLE values (first dimension of
TABLE) is small.
INPUT
table A matrix or vector. If TABLE is not a vector, the
first dimension of TABLE is interpreted as a vector
of values that correspond to each element of UVAR.
If TABLE is a vector, the action of FINTERP is the
same as INTERPOL(findgen(n),TABLE,UVAR)
uvar a matrix of field values.
OUTPUT:
result the floating point interpolation index of UVAR(i,j,k...)
into TABLE(*,i,j,k,...).
; EXAMPLE:
a=[[5.1,8.4],[6.7,3.1]]
tbl=fltarr(5,2,2)
tbl(*,0,0)=3+findgen(5)
tbl(*,1,0)=4+findgen(5)
tbl(*,0,1)=4+findgen(5)*2
tbl(*,1,1)=findgen(5)
fi=finterp(tbl,a)
print,f='(8a9)',' ','UVAR','/---','----','TBL','----','---\','FI' &$
print,f='(a9,7f9.2)','(0,0):',a(0,0),tbl(*,0,0),fi(0,0) &$
print,f='(a9,7f9.2)','(1,0):',a(1,0),tbl(*,1,0),fi(1,0) &$
print,f='(a9,7f9.2)','(0,1):',a(0,1),tbl(*,0,1),fi(0,1) &$
print,f='(a9,7f9.2)','(1,1):',a(1,1),tbl(*,1,1),fi(1,1)
; EXAMPLE:
Map surface albedo over some area, given satellite
radiance measurement on a 2d grid. Assumptions:
1. ff(m,i,j) = irradiance predictions at each point
in a 2d grid. The m index is over different
values of surface albedo. The table values vary
from point-to point (the i and j indecies) due to
changes in satellite and solar viewing angles as
well as surface albedo.
2. salb(m) = a vector of different surface albedos
used in the model caculations.
3. aa(i,j) = actual measured values of radiance
on the same grid.
To retrieve the optical surface albedo at each point
in the image use INTERPOLATE to compute the surface
albedo at each point:
salb_map=interpolate(salb,finterp(ff,aa))
or if logrithmic interpolation is desired
fndx=finterp(ff,aa)
salb_map=interpolate(alog(salb_map+1),fndx)
salb_map=exp(salb_map)-1.
PROCEDURE: uses WHERE to identify regions for interpolation.
a separate call to WHERE is used for each table interval.
The floating point index may extrapolate beyond the
limits of the TABLE. Hence UVAR values less-to or
greater-than the corresponding TABLE entries will
produce return values which are outside the TABLE
subscript range (INTERPOLATE knows how to handle this).
RESTRICTIONS: Table entries (first index of TABLE) must be monitonically
increasing. If the table is not monitonically increasing
FINTERP only finds solutions for that part of the table
which is monitonically increasing. In this case, the return
value for UVAR elements less than the relative minimum of
TABLE is set to -9999.
author: Paul Ricchiazzi apr93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/finterp.pro)
FUNCTION finterp
USEAGE result=finterp(table,uvar)
PURPOSE: Compute the floating point interpolation index of
UVAR(i,j,k...) into TABLE(*,i,j,k...) or TABLE(*).
For example, if uvar(i,j) is half way between
table(4,i,j) and table(5,i,j) then result(i,j)=4.5.
NOTE: If TABLE is a vector the action of FINTERP is
the same as INTERPOL(findgen(n),TABLE,UVAR). However,
FINTERP should be much faster whenever UVAR is large
and the number of TABLE values (first dimension of
TABLE) is small.
INPUT
table A matrix or vector. If TABLE is not a vector, the
first dimension of TABLE is interpreted as a vector
of values that correspond to each element of UVAR.
If TABLE is a vector, the action of FINTERP is the
same as INTERPOL(findgen(n),TABLE,UVAR)
uvar a matrix of field values.
OUTPUT:
result the floating point interpolation index of UVAR(i,j,k...)
into TABLE(*,i,j,k,...).
; EXAMPLE:
a=[[5.1,8.4],[6.7,3.1]]
table=fltarr(5,2,2)
table(*,0,0)=3+findgen(5)
table(*,1,0)=4+findgen(5)
table(*,0,1)=4+findgen(5)*2
table(*,1,1)=findgen(5)
fi=finterp(table,a)
print,f='(8a9)',' ','UVAR','/---','----','TABLE','----','---\','FI' &$
print,f='(a9,7f9.2)','(0,0):',a(0,0),table(*,0,0),fi(0,0) &$
print,f='(a9,7f9.2)','(1,0):',a(1,0),table(*,1,0),fi(1,0) &$
print,f='(a9,7f9.2)','(0,1):',a(0,1),table(*,0,1),fi(0,1) &$
print,f='(a9,7f9.2)','(1,1):',a(1,1),table(*,1,1),fi(1,1)
; EXAMPLE:
Map surface albedo over some area, given satellite
radiance measurement on a 2d grid. Assumptions:
1. ff(m,i,j) = irradiance predictions at each point
in a 2d grid. The m index is over different
values of surface albedo. The table values vary
from point-to point (the i and j indecies) due to
changes in satellite and solar viewing angles as
well as surface albedo.
2. salb(m) = a vector of different surface albedos
used in the model caculations.
3. aa(i,j) = actual measured values of radiance
on the same grid.
To retrieve the optical surface albedo at each point
in the image use INTERPOLATE to compute the surface
albedo at each point:
salb_map=interpolate(salb,finterp(ff,aa))
or if logrithmic interpolation is desired
findex=finterp(ff,aa)
salb_map=interpolate(alog(salb_map+1),findex)
salb_map=exp(salb_map)-1.
PROCEDURE: uses WHERE to identify regions for interpolation.
a separate call to WHERE is used for each table interval.
The floating point index may extrapolate beyond the
limits of the TABLE. Hence UVAR values less-to or
greater-than the corresponding TABLE entries will
produce return values which are outside the TABLE
subscript range (INTERPOLATE knows how to handle this).
RESTRICTIONS: Table entries (first index of TABLE) must be monitonically
increasing. If the table is not monitonically increasing
FINTERP only finds solutions for that part of the table
which is monitonically increasing. In this case, the return
value for UVAR elements less than the relative minimum of
TABLE is set to -9999.
author: Paul Ricchiazzi apr93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/finterp.pro)
FISH -- performs a modified FISHER test based on Shimshoni (1971). INPUTS: the Fourier power spectrum (fspec) and what the level is that you wish to work out the probability for.
(See /home/drw/idl/vtt/post_bbso/fish.pro)
FISH -- performs a modified FISHER test based on Shimshoni (1971). INPUTS: the Fourier power spectrum (fspec) and what the level is that you wish to work out the probability for.
(See /home/drw/idl/gen/fish.pro)
FISH_SIGNIF -- calculates the relative power of peaks and orders them. INPUTS: the Fourier power spectrum (fspec) and number of peaks required OUTPUTS: the ordered power peaks and corresponding frequencies BASED on fish.pro by D.WIlliams & R.T.J McAteer NOTES only returns the 'num' largest peaks
(See /home/drw/idl/vtt/post_bbso/fish_signif.pro)
FISH_SIGNIF -- calculates the relative power of peaks and orders them. INPUTS: the Fourier power spectrum (fspec) and number of peaks required OUTPUTS: the ordered power peaks and corresponding frequencies BASED on fish.pro by D.WIlliams & R.T.J McAteer NOTES only returns the 'num' largest peaks
(See /home/drw/idl/jma/fish_signif.pro)
NAME: FIX_BBSO_HEADER PURPOSE: Add CRPIXn values to the BBSO Ca II K FITS headers. USAGE: fix_bbso_header, header CALLS: SXADDPAR HISTORY: v1.0 - DRW@MSSL, 8-Sep-03
(See /home/drw/idl/misc/fix_bbso_header.pro)
NAME: FIX_BBSO_HEADER PURPOSE: Add CRPIXn values to the BBSO Ca II K FITS headers. USAGE: fix_bbso_header, header CALLS: SXADDPAR HISTORY: v1.0 - DRW@MSSL, 8-Sep-03 am v1.1 - now has facility to add in pixel scale information, also missing, through the PIXSCALE keyword
(See /home/drw/idl/gen/fix_bbso_header.pro)
NAME:
FLAREWAVE
PURPOSE:
Calculate and display the wavelet (power) transform of a time series
(CURVE) with the time series above the plot for comparison with the
transform, and also show the global wavelet spectrum to the right,
since it represents the summation of the power transform over time,
and is therefore analogous to the Fourier transform of the series.
CALLING SEQUENCE:
flarewave,curve,print=print,pc=pc,title=title,nocon=nocon
INPUTS:
CURVE - a 1-D time series, e.g. a light curve
INTERACTIVE INPUTS DURING EXECUTION:
The user is first asked for a maximum value for the low-pass filter
called by WAVE_EXAMPLE. For the SECIS data, an unfiltered time series
will be analysed by specifying half the data sampling rate of 44.2 Hz
(i.e. 22.1 Hz).
The second parameter requested is the significance (confidence)
level which the WAVELET function will calculate as a set of contours
in the power transform. Concentrations of power enclosed within these
contours will be significant to that level. E.g., if the user specifies
a value of 0.99 (i.e. 99%) then there is a 1% chance that the power
within the contours is due to noise.
KEYWORDS:
PRINT - if set, then set parameters applicable to printing to a
postscript file. NOTE: Does not actually set the display
to the PostScript device - this must be done manually.
PC - the plot colour for the contours and cone-of-influence
boundary and cross-hatching. This is a value from 0 to
255. In a monochromatic colour table (e.g. loadct,3 for
red temperature) 0 will be black, 255 will be white, and
any other colours will be somewhere in between (e.g.
scale linearly for colour tables 0,1,3, & 8;
logarithmically for colour table 9).
TITLE - a string, specifying the title over the wavelet transform
part of the display output.
NOCON - if set, then do not display either contours or the
cone-of-influence calculated by the WAVELET routine
OUTPUTS:
None, except for the display of the wavelet transform etc. to
either X windows (the default) or (optionally) the PostScript device.
EXAMPLES:
IDL> wave_example,series,title='Wavelet Transform for our series thing'
to write the output to an Encapsulated PostScript file:
IDL> set_plot,'PS
IDL> DEVICE,/encapsul,/color,filename='test1.eps',xsize=5,ysize=5
IDL> wave_example,series,title='Another Title',/print,pc=0
IDL> DEVICE,/close
IDL> SET_PLOT,'X'
or, if you have TOGGLE.PRO in your path:
IDL> TOGGLE,filename='wavelet.ps',/landscape,/color
IDL> wave_example,series,title='Another Title',/print,pc=0
IDL> TOGGLE
CALLS:
ECLIPSFILTER.PRO, WAVELET.PRO, WAVE_SIGNIF.PRO
HISTORY:
Based on ECLIPSE.PRO by Eoghan O'Shea, QUB, 2000
Modified in stages by D. Williams for the SECIS eclipse data
(See /home/drw/idl/secis/flarewaveold.pro)
NAME:
FLICKER
PURPOSE:
Flicker between two output images
CATEGORY:
Image display, animation.
CALLING SEQUENCE:
FLICKER, A, B
INPUTS:
A: Byte image number 1, scaled from 0 to 255.
B: Byte image number 2, scaled from 0 to 255.
if a and b are not supplied FLICKER will enter interactive mode
wherin the user will be asked to select two windows (by a LMB
click inside the chosen window). These two windows will be read
using tvrd() and compared.
KEYWORD PARAMETERS:
None.
OUTPUTS:
No explicit outputs.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Sunview: Modifies the display, changes the write mask.
X and Windows: uses two additional pixmaps.
RESTRICTIONS:
None.
PROCEDURE:
SunView:
Image A is written to the bottom 4 bits of the display.
Image B is written to the top 4 bits.
Two color tables are created from the current table, one that
shows the low 4 bits using 16 of the original colors, and one
that shows the high 4 bits. The color table is changed to
switch between images.
Other window systems:
two off screen pixmaps are used to contain the images.
on exit image A is left on the display
MODIFICATION HISTORY:
DMS, 3/ 88.
DMS, 4/92, Added X window and MS window optimizations.
PJR/ESRG, 1/94, "flicker" control by mouse
PJR/ESRG, 1/94, put in tvrd() of windows for interactive use
EXAMPLE:
plot,sin(dist(10)) & a=tvrd()
plot,sin(dist(10)+.05) & b=tvrd()
flicker,a,b
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/flicker.pro)
NAME:
FLICKER
PURPOSE:
Flicker between two output images
CATEGORY:
Image display, animation.
CALLING SEQUENCE:
FLICKER, A, B
INPUTS:
A: Byte image number 1, scaled from 0 to 255.
B: Byte image number 2, scaled from 0 to 255.
if a and b are not supplied FLICKER will enter interactive mode
wherin the user will be asked to select two windows (by a LMB
click inside the chosen window). These two windows will be read
using tvrd() and compared.
KEYWORD PARAMETERS:
None.
OUTPUTS:
No explicit outputs.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Sunview: Modifies the display, changes the write mask.
X and Windows: uses two additional pixmaps.
RESTRICTIONS:
None.
PROCEDURE:
SunView:
Image A is written to the bottom 4 bits of the display.
Image B is written to the top 4 bits.
Two color tables are created from the current table, one that
shows the low 4 bits using 16 of the original colors, and one
that shows the high 4 bits. The color table is changed to
switch between images.
Other window systems:
two off screen pixmaps are used to contain the images.
on exit image A is left on the display
MODIFICATION HISTORY:
DMS, 3/ 88.
DMS, 4/92, Added X window and MS window optimizations.
PJR/ESRG, 1/94, "flicker" control by mouse
PJR/ESRG, 1/94, put in tvrd() of windows for interactive use
EXAMPLE:
window,0,xs=200,ys=200 & plot,sin(dist(10))
window,1,xs=200,ys=200 & plot,sin(dist(10)+.05)
window,2,xs=200,ys=200 & plot,sin(dist(10)+.1)
window,3,xs=200,ys=200 & plot,sin(dist(10)+.15)
flicker ; choose two windows to compare
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/flicker.pro)
ROUTINE: flight_angle
PURPOSE: compute zenith and azimuth of a unit vector pointing "up"
in coordinate system attached to an aircraft.
USEAGE: flight_angle,pitch,roll,heading,zenith,azimuth
INPUT:
pitch pitch angle (degrees) positive values indicate nose up
roll roll angle (degrees) positive values indicate right wing down
heading compass direction aircraft is pointed. Positive values
represent clockwise, with respect to true North. NOTE:
This heading is the direction the airplane is pointed, not
the direction it is moving
KEYWORD_INPUT
radians if set all input and output angles are in radians
OUTPUT:
zenith zenith angle of "up" unit vector
azimuth azimuth angle of "up" unit vector. Positive values
represent clockwise, with respect to true North.
EXAMPLE:
; compute the solar zenith angle of a airbourne sensor given
; (roll,pitch,heading) = (2,3,45) degrees at 10 am today
doy=julday()-julday(1,0,1994)
zensun,doy,12,34.456,-119.813,z,a,/local
print,f='(6a13)','z','a','sunzen','sunaz','sunmu','corrected'
flight_angle,2.,2.,45.,zen,az
print,zen,az,z,a,cos(z*!dtor),muslope(z,a,zen,az)
flight_angle,2.,-2.,45.,zen,az
print,zen,az,z,a,cos(z*!dtor),muslope(z,a,zen,az)
flight_angle,2.,0.,0.,zen,az
print,zen,az,z,a,cos(z*!dtor),muslope(z,a,zen,az)
AUTHOR: Paul Ricchiazzi 25 Feb 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/flight_angle.pro)
FMEDIAN : variant of Gmedian
*NAME:
GMEDIAN (General IDL Library 01) May 20, 1980
*CLASS:
Smoothing
*CATEGORY:
*PURPOSE:
To perform a median filter on an one-dimensional array. The type of the
array is not converted to BYTE (as in the IDL MEDIAN), but is left the
same as the input type.
*CALLING SEQUENCE:
out=GMEDIAN(IN,M)
*PARAMETERS:
IN (REQ) (I) (1) (I L F D)
Required input vector containing the data which are to be filtered.
If OUT is omitted from the calling sequence, the filtered data are
returned in IN.
M (REQ) (I) (0) (I)
Length of the median filter
OUT (OPT) (O) (1) (I L F D)
Output median-filtered vector.
*EXAMPLE:
To median filter a data vector BKG:
GMEDIAN,BKG,63,FBKG ;63 point filter
*SYSTEM VARIABLES USED:
None.
*INTERACTIVE INPUT:
None.
*SUBROUTINES CALLED:
PARCHECK
*FILES USED:
IUER_USERDATA:GMEDIAN.TMP -temporary scratch data set
*SIDE EFFECTS:
You may not execute this procedure from two or more simultaneous
sessions in your account. There will be conflicts over the .TMP
file.
*RESTRICTIONS:
None
*NOTES:
Fortran Task IUER_SOFTDISK:[IUERDAF.PRODUCTION]GMEDIAN.EXE is
called to do the median filter.
The fortran task forces the filter with to be odd.
Widths less than 2 result in no filtering.
The data array is truncated to 4096 points in length.
The first and last M/2 points are copied from the
input to the output arrays with no filtering.
*PROCEDURE:
The length of the filter and the input array are copied
to a temporary file GMEDIAN.TMP and the task GMEDIAN.EXE
called.
For I = M/2 to N - M/2 - 1 where N is the length
of IN the median is computed by:
OUT(I) = Median value of (IN(J),J=I-M/2 to I+M/2)
Points for I=0, M/2 - 1 and I=N-M/2,N OUT(I) = IN(I)
The fortran task writes the sizes and the filtered results
to the file GMEDIAN.TMP and exits with a stop.
The procedure reads the lengths and the filtered results.
If errors arose, a message is output.
*MODIFICATION HISTORY:
Jul 31 1980 D. Lindler initial version
Sep 13 1982 FHS3 GSFC CR#047 increase vector sizes to 4096 points.
Apr 15 1985 RWT GSFC name changed to GMEDIAN to make routine
compatible with XIDL.
Jun 8 1987 RWT GSFC add PARCHECK, use N_ELEMENTS, and make OUT
optional.
Jun 22 1987 RWT GSFC fix error with N not being defined
Mar 10 1988 CAG GSFC add VAX RDAF-style prolog, and print
statement if the procedure is executed
without parameters.
(See /home/drw/idl/icur/fmedian.pro)
ROUTINE: fonts
userage: fonts,greek=greek,math=math,gothic=gothic,script=script,$
italic=italic,all=all
PURPOSE: display available fonts in a new window
INPUTS: none
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/fonts.pro)
ROUTINE: fonts
userage: fonts,greek=greek,math=math,gothic=gothic,script=script,$
italic=italic,all=all
PURPOSE: display available fonts in a new window
INPUTS: none
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/fonts.pro)
ROUTINE: fordata
USEAGE: fordata,name,v,format=format,margin=margin,ng=ng
PURPOSE: print a fortran data statement to file "junk"
defining variable NAME with data values v
input:
name name of variable or string to placed between the fortran
"data" and "/" keywords, as in
data NAME / ...
v vector of values
keyword input
format format specifier (string) of the form
x# or x## x#.# x##.# where x = { i, g, f, e }
and # is a digit (default = 'g10.4'). Note that
the format string does not include parenthesis.
margin number of leading blanks (margin=0 starts at column 7)
(default=2)
ng number of elements written in an implied fortran loop
for example ng=5 in the following snippit of fortran
data (v(i),i=1,5)/10,12,24,11,22/
data (v(i),i=6,10)/13,44,45,22,33/
The default value is chosen to produce 20 fortran
continuation statements. pick a smaller value if
the number of continuations allowed on your fortran
compiler is less than 20. Set ng to a large number
if no implied loops are desired.
output: none
EXAMPLE:
saveout
v=sin(findgen(200))
fordata,'(v(i),i=1,100)',v(0:99),f='f12.6'
fordata,'(v(i),i=101,200)',v(100:199),f='f12.6'
saveout,'junk.dat'
; automatically put in fortran implied do list to avoid an excessive
; number of continuation statements
fordata,'v',v,f='f10.6'
fordata,'v',v,f='f12.6'
author: Paul Ricchiazzi jun92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/fordata.pro)
ROUTINE: fordata
USEAGE: fordata,name,v,format=format,lun=lun,margin=margin
PURPOSE: print a fortran data statement defining variable NAME
with data values v
input:
name name of variable or string to placed between the fortran
"data" and "/" keywords, as in
data NAME / ...
v vector of values
keyword input
format format specifier (string) of the form
x# or x## x#.# x##.# where x = { i, g, f, e }
and # is a digit (default = 'g10.4'). Note that
the format string does not include parenthesis.
lun logical unit number for output, if not specified output is
directed to standard out.
margin number of leading blanks (margin=0 starts at column 7)
(default=2)
output: none
EXAMPLE:
v=sin(findgen(200))
openw,lun,'junk.f',/get_lun
fordata,'(v(i),i=1,200)',v,f='f12.6',lun=lun
close,lun
author: Paul Ricchiazzi jun92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/fordata.pro)
ROUTINE: fordatin
PURPOSE: read fortran data statements
USEAGE: result=fordatin(file,varname)
INPUT:
file name of fortran source file containing target
data statement (string)
varname name of fortran variable initialized in data statement
(string)
KEYWORD INPUT:
tag a unique string which appears in the fortran program immediately
before the desired data statement. This parameter is used to
identify which data statement to read. Its usually adequate
to use the name of the program unit as an unambiguating string.
example
tag='subroutine foo'
help print this documentation header
OUTPUT:
result array of initial values of variable VARNAME.
PROCEDURE: FORDATIN first searches through the fortran source file
for a program unit matching TAG (if this optional
parameter is provided). Next it looks for a line
containing the keywords DATA and the variable name
VARNAME. It reads all the following characters until it
finds two matching forward slashes (/). All characters
between the matching slashes are scanned and turned into
either an integer or float array as appropriate.
RESTRICTIONS:
this routine is designed to extract the part of the data
block following a typical array initialization such as
data varname/ 1,2,3,4,5,5
& 7,8,9/
if the data statement looks like
data (varname(i),i=1,3) /1,2,3/
data (varname(i),i=4,6) /3,2,4/
you can read the data as
v1=fordatin('file.f','(varname(i),i=1,3)')
v2=fordatin('file.f','(varname(i),i=4,6)')
v=[v1,v2]
but beware, FORDATIN will read all the numbers between
slashes in a multi-variable data statement such as
data v1,v2,v3/12,24,25/
EXAMPLE:
; plot temperature profile of TROPICAL standard atmosphere
z1=fordatin('/home/paul/rtmodel/atms.f','z1')
t1=fordatin('/home/paul/rtmodel/atms.f','t1')
plot,z1,t1
; plot coalbedo of ice particles as a function of wavelength
wl=.29*(333.33/.29)^(findgen(400)/399)
w=fordatin('/home/paul/rtmodel/cloudpar.f','(ww(i,14),i=1,mxwv)')
plot,wl,1.-w,xrange=[0,4]
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/fordatin.pro)
ROUTINE: fordatin
PURPOSE: read fortran data statements
USEAGE: result=fordatin(file,varname)
INPUT:
file name of fortran source file containing target
data statement (string)
varname name of fortran variable initialized in data statement
(string)
KEYWORD INPUT:
pu the name of the program unit which contains the data
initialization. Specify enough of the leading
characters of the program unit name to make it
unique. White space and case are ignored. For example
pu='subroutine foo'
pu=' subroutine foobar'
pu='SUBROUTINE FOOBAR(x1,'
all match
subroutine foobar(x1,x2,x3) ! a comment
help print this documentation header
OUTPUT:
result array of initial values of variable VARNAME.
PROCEDURE: FORDATIN first searches through the fortran source file
for a program unit matching PU (if this optional
parameter is provided). Next it looks for a line
containing the keywords DATA and the variable name
VARNAME. It reads all the following characters until it
finds two matching forward slashes (/). All characters
between the matching slashes are scanned and turned into
either an integer or float array as appropriate.
RESTRICTIONS:
this routine is designed to extract the part of the data
block following a typical array initialization such as
data varname/ 1,2,3,4,5,5
& 7,8,9/
if the data statement looks like
data (varname(i),i=1,3) /1,2,3/
data (varname(i),i=4,6) /3,2,4/
you can read the data as
v1=fordatin('file.f','(varname(i),i=1,3)')
v2=fordatin('file.f','(varname(i),i=4,6)')
v=[v1,v2]
but beware, FORDATIN will read all the numbers between
slashes in a multi-variable data statement such as
data v1,v2,v3/12,24,25/
EXAMPLE:
; plot temperature profile of TROPICAL standard atmosphere
z1=fordatin('/home/paul/rtmodel/atms.f','z1')
t1=fordatin('/home/paul/rtmodel/atms.f','t1')
plot,z1,t1
; plot coalbedo of ice particles as a function of wavelength
wl=.29*(333.33/.29)^(findgen(400)/399)
w=fordatin('/home/paul/rtmodel/cloudpar.f','(ww(i,14),i=1,mxwv)')
plot,wl,1.-w,xrange=[0,4]
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/fordatin.pro)
routine write a form feed (ascii 12) to file connected to LUN useage form_feed,lun input lun unit number
(See /home/drw/idl/esrg/form_feed.pro)
routine write a form feed (ascii 12) to file connected to LUN useage form_feed,lun input lun unit number
(See /home/drw/idl/old.esrg/form_feed.pro)
ROUTINE: Fourier PURPOSE: To calculate the phase and power spectrum USEAGE: result = Fourier (Time,Flux) INPUT: Time Time array in seconds Flux Flux array OPTIONAL KEYWORD: ,/rad stops the phase defaulting to degrees OUTPUT: result The power and phase spectrum TO DO: i)could print out the two resulting graphs using a keyword ii)could introduce a keyword, which inputs a frequency, then calculates the longest portion of the original flux to use to have a frequency exactly at this frequency. this would just be (Nyquist/(length /2) EQ chosen frequency) and then maximise length iii)a shut up keyword would be handy AUTHOR: V1.0 Based on pgfft by Peter T. Gallagher, Mar. '99, which was furthur altered by R.T. James McAteer & David R. Williams according to http://cires.colorado.edu/geo_data_anal/assign/assign4.html Oct' 01 V2.0 R.T.James McAteer & David R. Williams , QUB, Jan '02 fourier.pro which also calculates the phase and creates a 3 column array of frequency, power and phase
(See /home/drw/idl/vtt/post_bbso/fourier.pro)
ROUTINE: Fourier PURPOSE: To calculate the phase and power spectrum USEAGE: result = Fourier (Time,Flux) INPUT: Time Time array in seconds Flux Flux array OPTIONAL KEYWORD: ,/rad stops the phase defaulting to degrees OUTPUT: result The power and phase spectrum TO DO: i)could print out the two resulting graphs using a keyword ii)could introduce a keyword, which inputs a frequency, then calculates the longest portion of the original flux to use to have a frequency exactly at this frequency. this would just be (Nyquist/(length /2) EQ chosen frequency) and then maximise length ; AUTHOR: V1.0 Based on pgfft by Peter T. Gallagher, Mar. '99, which was furthur altered by R.T. James McAteer & David R. Williams according t0 http://cires.colorado.edu/geo_data_anal/assign/assign4.html Oct' 01 V2.0 R.T.James McAteer & David R. Williams , QUB, Jan '02 fourier.pro which also calculates the phase and creates a 3 column array ; of frequency, power and phase
(See /home/drw/idl/jma/fourier.pro)
ROUTINE: free_all
PURPOSE: free up all logical units
USEAGE: free_all
OUTPUT: none
DISCUSSION:
Produces a list of all open files. For each item in the
list the user may enter one of the following reponses:
quit -- do not close this file, quit free_all
view -- do not close this file, view list of remaining open files
all -- close this file and all remaining open files
yes -- close this file
no -- do not close this file
Note: only the first letter of the response is actually used in
free_all.
SIDE EFFECTS:
closes open files
EXAMPLE:
IDL> openw,/get_lun,lun1,'junk1'
IDL> openw,/get_lun,lun2,'junk2'
IDL> openw,/get_lun,lun3,'junk3'
IDL> openw,/get_lun,lun4,'junk4'
IDL> openw,/get_lun,lun5,'junk5'
IDL> free_all
Close junk1, logical unit 101 (quit,view/all/yes/no)?: y
Close junk2, logical unit 102 (quit,view/all/yes/no)?: y
Close junk3, logical unit 103 (quit,view/all/yes/no)?: a
Close junk4, logical unit 104
Close junk5, logical unit 105
AUTHOR: Paul Ricchiazzi 17 Mar 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/free_all.pro)
PURPOSE:
Restore a set of FSET frames from a portable XDR file created by FSAVE.
USAGE:
FRESTORE,FILE
ARGUMENTS:
FILE Name of file containing frame information (created by FSAVE)
OPTIONAL KEYWORDS:
/INTERPOLATE If set, interpolate color tables (default=no interpolation)
/HELP Print help information only (default=do not print)
USAGE NOTES:
(1) The file created by FSAVE is in XDR format, and thus is *portable*
between different IDL platforms. Each platform must however run
the same version of IDL (e.g. FSAVE files created in IDL 5.0
cannot be read in IDL 4.0.1).
(2) The following items are stored for each frame:
- The contents of the graphics window,
- The plot-related system variables (!P,!X,!Y,!Z,!MAP),
- The color table.
This means that the frames can be restored later (in another IDL
session, or even on another platform), and all overplotting commands
(e.g. OPLOT, PLOTS) will work normally. Map overplotting commands may
also be used on restored frames (e.g. MAP_GRID), as long as
.COMPILE MAP_SET
is done before the map overplotting commands are executed.
AUTHOR: Liam Gumley, CIMSS/SSEC, 19-SEP-1997 (liam.gumley@ssec.wisc.edu)
Added color table interpolation keyword INTERPOLATE
RELATED COMMANDS:
FSET Set up frames in memory
FSAVE Save frames created with FSET
EXAMPLE:
Create four frames with a graphic in each, save the frames to a file,
exit IDL, and then restore the frames and start looping.
FSET
LOADCT,13 & TV,BYTSCL(DIST(256),TOP=!D.TABLE_SIZE-1) & AF
PLOT,INDGEN(10) & AF
CONTOUR,DIST(32) & AF
LOADCT,30 & MAP_SET,/CONTINENTS
FSAVE,FILE='test.xdr'
EXIT
;(restart IDL)
FRESTORE,'test.xdr'
LF
(See /home/drw/idl/aux/frestore.pro)
PURPOSE:
Save a set of FSET frames to a portable XDR file that can be restored
later using FRESTORE.
USAGE:
FSAVE
OPTIONAL KEYWORDS:
FILE Name of file name to contain frame information
(default='fsave??.xdr', where ?? starts at 01 and increments)
/HELP Print help information only (default=do not print)
USAGE NOTES:
(1) FSET must have been executed previously to create frame buffers.
(2) The file created by FSAVE is in XDR format, and thus is *portable*
between different IDL platforms. Each platform must however run
the same version of IDL (e.g. FSAVE files created in IDL 5.0
cannot be read in IDL 4.0.1).
(3) The following items are stored for each frame:
- The contents of the graphics window,
- The plot-related system variables (!P,!X,!Y,!Z,!MAP),
- The color table.
This means that the frames can be restored later (in another IDL
session, or even on another platform), and all overplotting commands
(e.g. OPLOT, PLOTS) will work normally. Map overplotting commands may
also be used on restored frames (e.g. MAP_GRID), as long as
.COMPILE MAP_SET
is done before the map overplotting commands are executed.
AUTHOR: Liam Gumley, CIMSS/SSEC, 19-SEP-1997 (liam.gumley@ssec.wisc.edu)
29-SEP-1997 Fixed problem with color table for first frame
RELATED COMMANDS:
FSET Set up frames in memory
FRESTORE Restore frames saved with FSAVE
EXAMPLE:
Create four frames with a graphic in each, save the frames to a file,
exit IDL, and then restore the frames and start looping.
FSET
LOADCT,13 & TV,BYTSCL(DIST(256),TOP=!D.TABLE_SIZE-1) & AF
PLOT,INDGEN(10) & AF
CONTOUR,DIST(32) & AF
LOADCT,30 & MAP_SET,/CONTINENTS
FSAVE,FILE='test.xdr'
EXIT
;(restart IDL)
FRESTORE,'test.xdr'
LF
(See /home/drw/idl/aux/fsave.pro)
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 88
color names and values are supplied from the program. These
were obtained from the file rgb.txt, found on most X-Window
distributions. Representative colors were chose from across
the color spectrum. To see a list of colors available, type:
Print, FSC_Color(/Names).
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:
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
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:
Almond Antique White Aquamarine Beige Bisque Black
Blue Blue Violet Brown Burlywood Charcoal Chartreuse
Chocolate Coral Cornsilk Cyan Dark Goldenrod Dark Gray
Dark Green Dark Khaki Dark Orchid Dark Salmon 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 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 Gray Snow Spring Green
Steel Blue Tan Thistle Tomato Turquoise Violet
Violet Red Wheat White Yellow
The color WHITE 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:
Print, FSC_COLOR(/Names)
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.
RETURN VALUE:
The value that is returned by FSC_COLOR depends upon the keywords
used to call it and on the version of IDL you are using. 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.
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.
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.
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)
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 either a color name or the color
table index number. The program will figure out what you want.
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 88 by default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
ADDITIONAL PROGRAMS REQUIRED:
PICKCOLORNAME: This file can be found in the Coyote Library:
http://www.dfanning.com/programs/pickcolorname.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)
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.
(See /home/drw/idl/aux/fsc_color.pro)
NAME:
FSC_DROPLIST
PURPOSE:
The purpose of this compound widget is to provide an alternative
to the DROPLIST widget offered in the IDL distribution. What has
always annoyed me about a droplist is that you can't get the current
"value" of a droplist easily. This compound widget makes this and
other tasks much easier.
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:
General programming.
CALLING SEQUENCE:
droplistObj = FSC_Droplist(parent, Title='Animals: ", Value=['Dog'. 'Cat', 'Coyote'], Index=2)
The return value of the FSC_Droplist (droplistObj in this example) is
an object reference. Interaction with the droplist will occur through
object methods.
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
Any keyword that is appropriate for the Widget_Droplist function can be used.
In addition, these keywords are explicitly defined.
EVENT_FUNC -- Set this keyword to the name of an Event Handler Function.
EVENT_PRO -- Set this keyword to the name of an Event Handler Procedure.
FORMAT -- A format specifier for the "format" of the values in the droplist.
INDEX -- The index number of the current selection.
SPACES -- A two-element array that indicates the number of blank spaces to be added
to the the beginning and end of the formatted values. If a single number
is provided, this number of blank spaces is added to both the beginning
and the end of the value.
TITLE -- The title of the droplist widget.
UNAME -- The user name of the droplist widget. (Only available in IDL 5.2 and higher.)
UVALUE -- The normal "user value" of the droplist.
VALUE -- An array of the droplist "selections". May be any data type.
COMMON BLOCKS:
None.
DEPENDENCIES:
Requires ERROR_MESSAGE from the Coyote Library..
EVENT STRUCTURE:
An event is returned each time the droplist value is changed. The event structure
is defined like this:
event = { FSC_DROPLIST_EVENT, $ ; The name of the event structure.
ID: 0L, $ ; The ID of the compound widget's top-level base.
TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
INDEX: 0L, $ ; The index number of the current selection.
SELECTION:Ptr_New() $ ; A pointer to the current selection "value".
SELF:Obj_New() } ; The object reference of the compound widget.
PUBLIC OBJECT METHODS:
GetID -- A function with no arguments that returns the widget identifier
of the droplist widget.
droplistID = droplistObj->GetID()
GetIndex -- A function with no arguments that returns the index
number of the current droplist selection.
currentIndex = droplistObj->GetIndex()
GetSelection -- A function with no arguments that returns the current
droplist selection.
currentSelection = droplistObj->GetSelection()
GetUValue -- A function with no arguments that returns the "user value"
of the compound widget i.e., the value set with the UVALUE keyword).
myUValue = droplistObj->GetUValue()
GetValues -- A function with no arguments that returns the "values" or
"selections" for the droplist.
possibleSelections = droplistObj->GetValues()
Resize -- A procedure that sets the X screen size of the droplist. It is
defined like this:
PRO Resize, newSize, ParentSize=parentSize
The "newSize" keyword is the new X screen size. If this argument is
missing, the screen X size of the compound widget's parent is used.
The parentSize keyword is an output keyword that returns the X screen
size of the compound widget's parent.
droplistObj->Resize, 400
Note that not all devices (e.g., X Windows devices) support droplist resizing.
SetIndex -- A procedure that sets the current droplist selection based on
the given index. This is equivalent to Widget_Control, droplistID, Set_Droplist_Select=newIndex
droplistObj->SetIndex, newIndex
SetSelection -- Whereas a regular droplist widget can only be set by index
number, this compound widget can also be set by a "selection". The new selection
can be any data type and corresponds to one of the "values" of the droplist.
droplistObj->SetSelection, newSelection
EXAMPLE:
An example program is provided at the end of the FSC_DROPLIST code. To run it,
type these commands:
IDL> .Compile FSC_DROPLIST
IDL> Example
MODIFICATION HISTORY:
Written by: David Fanning, 17 Jan 2000. DWF.
Added FORMAT and SPACES keywords 28 April 2000. DWF.
(See /home/drw/idl/aux/fsc_droplist.pro)
NAME:
FSC_FIELD
PURPOSE:
The purpose of this compound widget is to provide an alternative
to the CW_FIELD widget offered in the IDL distribution. One weakness
of the CW_FIELD compound widget is that the text widgets do not
look editable to the users on Windows platforms. This program
corrects that deficiency and adds some features that I think
will be helpful. For example, you can now assign an event handler
to the compound widget, ask for positive numbers only, and limit
the number of digits in a number, or the number of digits to the
right of a decimal point. The program is written as a widget object,
which allows the user to call object methods directly, affording
even more flexibility in use. This program replaces the earlier
programs FSC_INPUTFIELD and COYOTE_FIELD.
The program consists of a label widget next to a one-line text widget.
The "value" of the compound widget is shown in the text widget. If the
value is a number, it will not be possible (generally) to type
alphanumeric values in the text widget. String values behave like
strings in any one-line text widget.
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:
General programming.
TYPICAL CALLING SEQUENCE:
fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
COLUMN Set this keyword to have the Label widget above the Text widget.
The default is to have the Label widget in a row with the Text widget.
CR_ONLY Set this keyword if you only want Carriage Return events returned to
your event handler. If this keyword is not set, all events are returned.
Setting this keyword has no effect unless either the EVENT_PRO or
EVENT_FUNC keyword is used.
DECIMAL Set this keyword to the number of digits to the right of the decimal
point in floating point or double precision numbers. Ignored for STRING values.
DIGITS Set this keyword to the number of digits permitted in integer numbers.
EVENT_FUNC Set this keyword to the name of an event handler function. If this
keyword is undefined and the Event_Pro keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
EVENT_PRO Set this keyword to the name of an event handler procedure. If this
keyword is undefined and the Event_Func keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
FIELDFONT The font name for the text in the text widget.
FRAME Set this keyword to put a frame around the compound widget.
LABEL_LEFT Set this keyword to align the text on the label to the left.
LABEL_RIGHT Set this keyword to align the text on the label to the right.
LABELFONT The font name for the text in the label widget.
LABELSIZE The X screen size of the label widget.
NAME A string containing the name of the object. The default is ''.
NOEDIT Set this keyword to allow no user editing of the input text widget.
NONSENSITIVE Set this keyword to make the input text widget non-sensitive.
POSITIVE Set this keyword if you want only positive numbers allowed.
SCR_XSIZE The X screen size of the compound widget.
SCR_YSIZE The Y screen size of the compound widget.
TITLE The string text placed on the label widget.
UNDEFINED Set this keyword to the value to use for "undefined" values. If
not set, then !Value.F_NAN is used for numerical fields and a
NULL string is used for string fields. This applies to values
obtained with the GET_VALUE method or the GET_VALUE function.
UVALUE A user value for any purpose.
VALUE The "value" of the compound widget. Any type of integer, floating, or string
variable is allowed. The data "type" is determined automatically from the
value supplied with this keyword. Be sure you set the type appropriately for
your intended use of the value.
XSIZE The X size of the text widget in the usual character units.
OUTPUT KEYWORDS:
OBJECT Set this keyword to a named variable to receive the compound widget's
object reference. This is required if you wish to call methods on the object.
Note that the object reference is also available in the event structure
generated by the widget object. Note that the object reference will be
necessary if you want to get or set values in the compound widget.
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
EVENT STRUCTURE:
All events are handled internally unless either the Event_Pro or Event_Func
keywords are used to assign an event handler to the compound widget. By
default all events generated by the text widget are passed to the assigned
event handler. If you wish to receive only Carriage Return events, set the
CR_Only keyword.
event = { FSC_FIELD_EVENT, $ ; The name of the event structure.
ID: 0L, $ ; The ID of the compound widget's top-level base.
TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
OBJECT: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
VALUE: Ptr_New(), $ ; A pointer to the widget value.
TYPE:"" ; A string indicating the type of data in the VALUE field.
}
Note that if the field is "empty", the VALUE will be a pointer
to an undefined variable. You should check this value before you
use it. You code will look something like this:
IF N_Elements(*event.value) EQ 0 THEN $
Print, 'Current Value UNDEFINED.' ELSE $
Print, 'Current Value: ', *event.value
GETTING and SETTING VALUES:
Almost all the properties of the widget can be obtained or set via
the object's GetProperty and SetProperty methods (described below).
Traditional compound widgets have the ability to get and set the "value"
of the compound widget identifier (e.g., fieldID in the calling
sequence above). Unfortunately, it is impossible to retreive a variable
in this way when the variable is undefined. In practical terms, this
means that the undefined variable must be set to *something*. You can
determine what that something is with the UNDEFINED keyword, or I will set
it to !VALUES.F_NAN for numerical fields and to the null string for string
fields. In any case, you will have to check for undefined variables before
you try to do something with the value. For a numerical field, the code
might look something like this:
fieldID = FSC_FIELD(parent, Title="X Size:", Value=256, Object=fieldObject, Digits=3)
currentValue = fieldObject->Get_Value()
IF Finite(currentValue) EQ 0 THEN Print, 'Value is Undefined' ELSE Print, currentValue
Additional examples are provided in the numerical example fields in Example Program below.
Setting the value of the compound widget is the same as calling the Set_Value
method on the object reference. In other words, these two statements are equivalent.
fieldObject->Set_Value, 45.4
Widget_Control, fieldID, Set_Value=45.4
The data type of the value is determined from the value itself. Be sure you set it appropriately.
OBJECT PROCEDURE METHODS:
GetProperty -- This method allows various properties of the widget to be
returned via output keywords. The keywords that are available are:
CR_Only -- A flag, if set, means only report carriage return events.
DataType -- The data type of the field variable.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
Event_Func -- The name of the event handler function.
Event_Pro -- The name of the event handler function.
Name -- A scalar string name of the object.
NoEdit -- A 1 means the widget is non-editable.
NonSensitive -- A 1 means the widget is non-sensitive.
NonSensitive -- Set this keyword to make the widget non-sensitive.
Positive -- Indicates if the Positive number flag is set (1) or not (0).
UValue -- The user value assigned to the compound widget.
Value -- The "value" of the compound widget.
MoveTab -- This method moves the focus to the widget identified in the "next" field,
which must be set with the SetTabNext method. No parameters. Called automatically
when a TAB character is typed in the text widget.
Resize -- This method allows you to resize the compound widget's text field.
The value parameter is an X screen size for the entire widget. The text
widget is sized by using the value obtained from this value minus the
X screen size of the label widget.
objectRef->Resize, screen_xsize_value
Set_Value -- This method allows you to set the "value" of the field. It takes
one positional parameter, which is the value.
objectRef->Set_Value, 5
SetEdit -- This procedure turns editing on (value of 1) or off (value of 0).
SetProperty -- This method allows various properties of the widget to be
set via input keywords. The keywords that are available are:
CR_Only -- Set this keyword if you only want Carriage Return events.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
Event_Func -- Set this keyword to the name of an Event Function.
Event_Pro -- Set this keyword to the name of an Event Procedure.
LabelSize -- The X screen size of the Label Widget.
Name -- A scalar string name of the object. (default = '')
NoEdit -- Set this keyword to make the widget non-editable.
NonSensitive -- Set this keyword to make the widget non-sensitive.
Positive -- Set this keyword to indicate only positive numbers are allowed.
Scr_XSize -- The X screen size of the text widget.
Scr_YSize -- The Y screen size of the text widget.
Title -- The text to go on the Label Widget.
UValue -- A user value for any purpose.
Value -- The "value" of the compound widget.
XSize -- The X size of the Text Widget.
SetSensitive -- This procedure turns text widget sensitivity on (value of 1) or off (value of 0).
OBJECT FUNCTION METHODS:
Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
if a "number" field is blank. Should be checked before using:
IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()
GetID -- Returns the widget identifier of the compound widget's top-level base.
(The first child of the parent widget.) No parameters.
GetLabelSize -- Returns the X screen size of the label widget. No parameters.
GetTextID -- Returns the widget identifier of the compound widget's text widget.
No parameters.
GetTextSize -- Returns the X screen size of the text widget. No parameters.
PRIVATE OBJECT METHODS:
Although there is really no such thing as a "private" method in IDL's
object implementation, some methods are used internally and not meant to
be acessed publicly. Here are a few of those methods. I list them because
it may be these private methods are ones you wish to override in subclassed
objects.
MoveTab -- This method moves the cursor to end of the text in the widget identified
by the nexttab field. (This will be set with the SetTabNext method.)
Text_Events -- The main event handler method for the compound widget. All
text widget events are processed here.
ReturnValue -- This function method accepts a string input value and converts
it to the type of data requested by the user.
Validate -- This function method examines all text input and removes unwanted
characters, depending upon the requested data type for the field. It makes it
impossible, for example, to type alphanumeric characters in an INTEGER field.
EXAMPLE:
An example program is provided at the end of the FSC_FIELD code. To run it,
type these commands:
IDL> .Compile FSC_Field
IDL> Example
MODIFICATION HISTORY:
Written by: David Fanning, 18 October 2000. Based heavily on an earlier
FSC_INPUTFIELD program and new ideas about the best way to write
widget objects.
Added LABEL_LEFT, LABEL_RIGHT, and UNDEFINED keywords. 29 Dec 2000. DWF.
Modified the way the value is returned in the GET_VALUE method and the
GET_VALUE function. Modified Example program to demonstrate. 30 Dec 2000. DWF.
Added NOEDIT and NONSENSITIVE keywords, with corresponding SETEDIT and SETSENNSITIVE
methods. 19 Jan 2001. DWF.
Actually followed through with the changes I _said_" I made 29 Dec 2000. (Don't ask....) 13 June 2001. DWF.
Added GetTextSize and GetLabelSize methods for obtaining the X screen
size of the text and label widgets, respectively. 21 July 2001. DWF.
(See /home/drw/idl/aux/fsc_field.pro)
NAME:
FSC_FILESELECT
PURPOSE:
The purpose of this compound widget is to provide a means
by which the user can type or select a file name. The
program is written as an "object widget", meaning that
the guts of the program is an object of class FSC_FILESELECT.
This is meant to be an example of the obvious advantages of
writing compound widget programs as objects.
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:
General programming.
CALLING SEQUENCE:
filenameID = FSC_FileSelect(parent)
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
Event_Pro -- The event handler procedure for this compound widget.By default: "".
Event_Func -- The event handler function for this compound widget. By default: "".
If neither EVENT_PRO or EVENT_FUNC is defined, program events are handled internally by the compound widget.
DirectoryName -- The initial name of the directory. By defaut: current directory.
Filename -- The initial file name in the filename text widget.
Filter -- The file filter. By default: "*".
Frame -- Set this keyword for a frame around the compound widget.
LabelFont -- The font for the label widget. By default: "".
LabelName -- The text on the label widgt. By default: "Filename: ".
LabelSize -- The X screen size of the label widget. By default: 0.
MustExist -- A flag that indicates selected files must exist. By default: 0.
NoMaxSize -- A flag to prohibit automatic text widget sizing. By default: 0.
If this keyword is not set, the compound widget will automatically resize itself to
the largest widget in its parent base widget. It will do this by changing the size of
the text widgets holding the file and directory names.
Read -- Set this keyword to have file selection for reading a file. By default: 1.
SelectDirectory -- The default directory for file selection. In other words, this is the
default directory for DIALOG_PICKFILE, which is accessed via the BROWSE buttons.
SelectFont -- The font for the "Browse" button. By default: "".
SelectTitle -- The title bar text on the file selection dialog. By default: "Select a File...".
TextFont -- The font for the filename text widget. By default: "".
UValue -- User value for any purpose.
Write -- Set this keyword to open a file for writing. By default: 0.
XSize -- The X size of the text widget holding the filename. By default: StrLen(filename) * 1.5 > 40.
OUTPUT KEYWORDS:
ObjectRef -- Assign this keyword to an output variable that will hold the internal object reference.
With the object reference you can call object methods to easily change many properties of
the compound widget.
COMMON BLOCKS:
None.
RESTRICTIONS:
Probably doesn't work correctly on VMS systems :-( If you can help, please
contact me. I don't have a VMS system to test on.
EVENT STRUCTURE:
All events are handled internally unless either the Event_Pro or Event_Func
keywords are used to assign an event handler to the compound widget. All events
generated by the text widgets are passed to the assigned event handler.
event = { CW_FILESELECT, $ ; The name of the event structure.
ID: 0L, $ ; The ID of the compound widget's top-level base.
TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
Basename: "", $ ; The base filename without directory specifiers.
Filename: "", $ ; The fully qualified filename.
Filter: ::, $ ; The currently active file filter.
Directory: "", $ ; The name of the current file directory.
}
EXAMPLE:
An example program is provided at the end of the FSC_FILESELECT code. To run it,
type these commands:
IDL> .Compile fsc_fileselect
IDL> Example
Or, if you want to obtain the object reference, type this:
IDL> Example, theObject
Now you can call the object's methods. For example:
IDL theObject->SetProperty, XSize=150
GETTING and SETTING VALUES:
So as not to disrupt the accepted paradigm in using compound widgets, you
can use the return value of the FSC_FILESELECT function with WIDGET_CONTROL to
get and set the "value" of the widget.
Widget_Control, filenameID, Set_Value='C:\RSI\IDL52\DATA\cyclone.dat'
The program will automatically separate the file name portion of the value
from the directory portion and put things in the correct text widgets.
Similarly, you can get the "value" of the widget:
Widget_Control, filenameID, Set_Value=theValue
Print, theValue
C:\RSI\IDL52\DATA\cyclone.dat
The return value is the fully qualified file path to the file.
USING OBJECT METHODS to CHANGE PROGRAM PROPERTIES:
If you obtain the object reference, you have a great deal more control
over the properties of the compound widget. You obtain the object reference
by calling the function like this:
filenameID = FSC_FILESELECT(parent, ObjectRef=theObject)
OBJECT PROCEDURE METHODS:
GetProperty -- This method allows various properties of the widget to be
returned via output keywords. The keywords that are available are:
DirectoryName -- The current directory.
Event_Func -- The name of the event handler function for this compound widget.
Event_Pro -- The name of the event handler procedure for this compound widget.
Filename -- The current base filename.
Filter -- The current file filter.
LabelName -- The text on the label widget.
LabelSize -- The X screen size of the label widget.
MustExist -- A flag that indicates selected files must exist to be selected.
Parent -- The parent widget of the compound widget.
Read=read -- The file selection for reading flag.
SelectTitle -- The title bar text on the file selection dialog.
TLB -- The top-level base of the compound widget.
UValue -- The user value of the compound widget.
Write -- The file selection for writing flag.
XSize -- The X size of the text widget holding the filename.
LabelSize -- This method makes sure that the directory name and file name labels
are the same size. Normally, this procedure is called internally. No parameters.
MatchSize -- This method resizes the compound widget so that it is as long as the
the longest widget in the parent base widget. This is done automatically upon
realization unless the NOMAXSIZE keyword is set. The method aids in writing
resizeable widget programs.
SetProperty -- This method allows various properties of the widget to be
set via input keywords. The keywords that are available are:
DirectoryName -- The current directory.
Event_Func -- The name of the event handler function for this compound widget.
Event_Pro -- The name of the event handler procedure for this compound widget.
Filename -- The current base filename.
Filter -- The current file filter.
LabelName -- The text on the label widget.
LabelSize -- The X screen size of the label widget.
MustExist -- A flag that indicates selected files must exist to be selected.
Read -- The file selection for reading flag.
SelectTitle -- The title bar text on the file selection dialog.
UValue -- The user value of the compound widget.
Write -- The file selection for writing flag.
XSize -- The X size of the text widget holding the filename.
OBJECT FUNCTION METHODS:
GetFileName -- Returns the fully qualified filename. No parameters.
GetTLB -- Returns the top-level base ID of the compound widget. No Parameters.
Inspect_DirectoryName -- Inspects the directory name for correctness. Requires one positional parameter.
directoryName -- The name of the directory from the directory text widget.
textSelection -- The current text selection position.
At the moment all this does is remove any blank characters from either
end of the directory name and makes sure the last character of the directory
name does not end in a subdirectory specifier (except for VMS).
Inspect_Filename -- Inspects the file name for correctness. Requires one positional parameter.
filename -- The name of the file from the filename text widget.
textSelection -- The current text selection position.
At the moment all this does is remove any blank characters from either
end of the file name
MODIFICATION HISTORY:
Written by: David Fanning, 21 NOV 1999.
Fixed bug in File Name selection button. 18 MAR 2000. DWF.
Fixed an error in which directory the Browse buttons should start
searching. 29 SEP 2000. DWF.
Previously returned events only for typing in text widgets. Now
Browse button events are also returned. 29 SEP 2000. DWF.
Fixed a bug in setting the file filter. 29 SEP 2000. DWF.
(See /home/drw/idl/aux/fsc_fileselect.pro)
NAME:
FSC_INPUTFIELD
PURPOSE:
The purpose of this compound widget is to provide an alternative
to the CW_FIELD widget offered in the IDL distribution. What has
always bothered me about CW_FIELD is that the text widgets do not
look editable to the users on Windows platforms. This program
corrects that deficiency and adds some features that I think
would be helpful. For example, you can now assign an event handler
to the compound widget. The program is written entirely as an object.
A companion program, COYOTE_FIELD, has much the same functionality,
but is written as a traditional compound widget. The point of writing
the same program in two different ways is to give you the opportunity
to compare and contrast the two methods. I personally think there
is no substitute for the power of object programs. :-)
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:
General programming.
CALLING SEQUENCE:
objectRef = FSC_INPUTFIELD(parent, Title='X Size: ", Value=256, /IntegerValue)
INPUT PARAMETERS:
parent -- The parent widget ID of the compound widget. Required.
INPUT KEYWORDS:
Column -- Set this keyword to have the Label Widget above the Text Widget.
CR_Only -- Set this keyword if you only want Carriage Return events. If
this keyword is not set, all events are returned. No events
are returned unless the EVENT_PRO or EVENT_FUNC keywords are used.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
Event_Func -- Set this keyword to the name of an Event Function. If this
keyword is undefined and the Event_Pro keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
Event_Pro -- Set this keyword to the name of an Event Procedure. If this
keyword is undefined and the Event_Func keyword is undefined,
all compound widget events are handled internally and not
passed on to the parent widget.
FieldFont -- The font name for the text in the Text Widget.
FloatValue -- Set this keyword for FLOAT values.
Frame -- Set this keyword to put a frame around the compound widget.
IntegerValue -- Set this keyword for INTEGER values.
LabelFont -- The font name for the text in the Label Widget.
LabelSize -- The X screen size of the Label Widget.
LongValue -- Set this keyword for LONG values.
Name -- A scalar string name of the object. (default = '')
Positive -- Set this keyword if you want only positive numbers allowed.
Row=row -- Set this keyword to have the Label beside the Text Widget. (The default.)
Scr_XSize -- The X screen size of the compound widget.
Scr_YSize -- The Y screen size of the compound widget.
StringValue -- Set this keyword for STRING values. (The default.)
Title -- The text to go on the Label Widget.
UValue -- A user value for any purpose.
Value -- The "value" of the compound widget.
XSize -- The X size of the Text Widget.
COMMON BLOCKS:
None.
RESTRICTIONS:
None.
EVENT STRUCTURE:
All events are handled internally unless either the Event_Pro or Event_Func
keywords are used to assign an event handler to the compound widget. By
default all events generated by the text widget are passed to the assigned
event handler. If you wish to receive only Carriage Return events, set the
CR_Only keyword.
event = { FSC_FIELD, $ ; The name of the event structure.
ID: 0L, $ ; The ID of the compound widget's top-level base.
TOP: 0L, $ ; The widget ID of the top-level base of the hierarchy.
HANDLER: 0L, $ ; The event handler ID. Filled out by IDL.
ObjRef: Obj_New(), $ ; The "self" object reference. Provided so you can call methods.
Value: Ptr_New(), $ ; A pointer to the widget value.
Type:"" ; A string indicating the type of data in the VALUE field.
} ; Values are "INT", "LONG", "FLOAT", "DOUBLE", or "STRING".
GETTING and SETTING VALUES:
Almost all the properties of the widget can be obtained or set via
the object's GetProperty and SetProperty methods (described below).
But since traditional compound widgets have the ability to get and
set the value of the compound widget, this capability is implemented
as special methods.
To get the value of the field, do this: value = objectRef->Get_Value()
To set the value of the field, so this: objectRef->Set_Value, value, /IntegerValue
The proper keyword should be used to set the data type of the value. If a keyword
is not used, the data type is determined from the value itself.
OBJECT PROCEDURE METHODS:
GetProperty -- This method allows various properties of the widget to be
returned via output keywords. The keywords that are available are:
CR_Only -- A flag, if set, means only report carriage return events.
DataType -- The data type of the field variable.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
Event_Func -- The name of the event handler function.
Event_Pro -- The name of the event handler function.
Positive -- Indicates if the Positive number flag is set (1) or not (0).
UValue -- The user value assigned to the compound widget.
Value -- The "value" of the compound widget.
Name -- A scalar string name of the object.
MoveTab -- This method moves the focus to the widget identified in the "next" field,
which must be set with the SetTabNext method. No parameters. Called automatically
when a TAB character is typed in the text widget.
Resize -- This method allows you to resize the compound widget's text field.
The value parameter is an X screen size for the entire widget. The text
widget is sized by using the value obtained from this value minus the
X screen size of the label widget.
objectRef->Resize, screen_xsize_value
Set_Value -- This method allows you to set the "value" of the field. It takes
one positional parameter, which is the value.
objectRef->Set_Value, 5
Keywords available are these to set the type of the data. If keywords
are not used, the data type is determined from the value.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
FloatValue -- Set this keyword for FLOAT values.
IntegerValue -- Set this keyword for INTEGER values.
LongValue -- Set this keyword for LONG values.
StringValue -- Set this keyword for STRING values. (The default.)
SetProperty -- This method allows various properties of the widget to be
set via input keywords. The keywords that are available are:
CR_Only -- Set this keyword if you only want Carriage Return events.
Decimal -- Set this keyword to the number of digits to the right of the decimal
point in FLOATVALUE and DOUBLEVALUE numbers.
Digits -- Set this keyword to the number of digits permitted in INTERGERVALUE and LONGVALUE numbers.
DoubleValue -- Set this keyword if you want DOUBLE values returned.
Event_Func -- Set this keyword to the name of an Event Function.
Event_Pro -- Set this keyword to the name of an Event Procedure.
FloatValue -- Set this keyword for FLOAT values.
IntegerValue -- Set this keyword for INTEGER values.
LabelSize -- The X screen size of the Label Widget.
LongValue -- Set this keyword for LONG values.
Name -- A scalar string name of the object. (default = '')
Positive -- Set this keyword to indicate only positive numbers are allowed.
Scr_XSize -- The X screen size of the text widget.
Scr_YSize -- The Y screen size of the text widget.
StringValue -- Set this keyword for STRING values. (The default.)
Title -- The text to go on the Label Widget.
UValue -- A user value for any purpose.
Value -- The "value" of the compound widget.
XSize -- The X size of the Text Widget.
OBJECT FUNCTIONS METHODS:
Get_Value -- Returns the "value" of the field. No parameters. Will be undefined
if a "number" field is blank. Should be checked before using:
IF N_Elements(objectRef->Get_Value()) NE 0 THEN Print, Value is: ', objectRef->Get_Value()
GetID -- Returns the widget identifier of the compound widget's top-level base.
(The first child of the parent widget.) No parameters.
GetTextID -- Returns the widget identifier of the compound widget's text widget.
No parameters.
PRIVATE OBJECT METHODS:
Although there is really no such thing as a "private" method in IDL's
object implementation, some methods are used internally and not meant to
be acessed publicly. Here are a few of those methods. I list them because
it may be these private methods are ones you wish to override in subclassed
objects.
MoveTab -- This method moves the cursor to end of the text in the widget identified
by the nexttab field. (This will be set with the SetTabNext method.)
Text_Events -- The main event handler method for the compound widget. All
text widget events are processed here.
ReturnValue -- This function method accepts a string input value and converts
it to the type of data requested by the user.
Validate -- This function method examines all text input and removes unwanted
characters, depending upon the requested data type for the field. It makes it
impossible, for example, to type alphanumeric characters in an INTEGER field.
EXAMPLE:
An example program is provided at the end of the FSC_INPUTFIELD code. To run it,
type these commands:
IDL> .Compile FSC_InputField
IDL> Example
MODIFICATION HISTORY:
Written by: David Fanning, 23 NOV 1999.
Added DECIMAL and DIGITS keywords, 2 Jan 2000, DWF.
Changed the calling sequence to that of a function rather than an object
creation call. This is more familiar to users of compound widgets. 4 Jan 00. DWF.
Added GetID and Resize methods. 7 Jan 00. DWF.
Added the Positive keyword and functionality. 12 Jan 00. DWF
Modified (slightly) the behavior on deleting characters. 12 Jan 00. DWF.
If a number field is blank, the Get_Value method will now return an undefined variable.
Be sure you check this value before you use it for something! 17 Jan 00. DWF.
Fixed a small typo: "aveDecimal" to "haveDecimal". 10 March 2000. DWF.
Added the ability to tab between FSC_INPUTFIELD widgets with the SetTabNext,
MoveTab, and GetTextID methods. 31 July 2000. DWF.
Added NAME field property, a scalar string name for the object 2 AUG 2000 BT
Added ObjRef field to the FSC_FIELD event structure and added field selection
for the TAB events added 31 July. 7 AUG 2000. DWF
(See /home/drw/idl/aux/fsc_inputfield.pro)
NAME: FSC_PLOTWINDOW PURPOSE: The purpose of this compound widget is to create a resizeable "plot window" inside a larger "page window". I'm not sure it has any value except as a utility routine for the PostScript configuration object FSC_PSCONFIG__DEFINE, but it's a neat program anyway. :-) 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 routine for FSC_PSCONFIG__DEFINE. MODIFICATIONS: Written by David Fanning, 31 January 2000. Fixed a small bug that prevented it working on Macintosh computers. 26 Sept 2000. DWF.
(See /home/drw/idl/aux/fsc_plotwindow.pro)
NAME:
FSC_PSCONFIG__DEFINE
PURPOSE:
The purpose of this program is to implement an object that
can keep track of--and allow the user to change--the current
configuration of the PostScript device.
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:
General programming.
DOCUMENTATION:
Complete documentation for the FSC_PSCONFIG object, including
keyword and method descriptions, and example programs using the object
can be found on the Coyote's Guide to IDL Programming web page:
http://www.dfanning.com/programs/docs/fsc_psconfig.html
EXAMPLE:
A simple sequence of using the object would look something like this:
psObject = Obj_New("FSC_PSCONFIG")
psObject->GUI
psKeywords = psObject->GetKeywords()
thisDevice = !D.Name
Set_Plot, 'PS'
Device, _Extra=psKeywords
TVImage, image
Device, /Close_File
Set_Plot, thisDevice
Obj_Destroy, psObject
Note that the object can also be called from the PS_CONFIG interface:
psKeywords = PSConfig()
OTHER PROGRAMS NEEDED:
The following programs are required to run this one:
fsc_droplist.pro
fsc_fileselect.pro
fsc_inputfield.pro
fsc_plotwindow
MODIFICATIONS:
Written by David Fanning, 31 January 2000.
Added capability to call GUI methods when the current graphics device
doesn't support windows. Device is restored when the GUI exits. 11 May 2000. DWF.
Changed the default value for the Color keyword to 1. 16 May 2000. DWF.
Fixed a bug where filename changed when switching Setups. 8 AUG 2000. DWF.
Fixed a bug when saving setup in Landscape mode. 8 AUG 2000. DWF.
Added the ability to Get and Set the object's name via the SetProperty
and a very abbreviated GetProperty method. Also added a GetName method. 26 SEP 2000. DWF.
Fixed a problem in which the proper configuration was not restored if in Landscape mode. 20 Nov 2000. DWF.
(See /home/drw/idl/aux/fsc_psconfig__define.pro)
NAME:
FSC_SURFACE
PURPOSE:
The purpose of this program is to demonstrate how to
create a rotating surface using object graphics.
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 Graphics.
CALLING SEQUENCE:
FSC_SURFACE, 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:
COLORTABLE: Set this keyword to a number between 0 and 40 to select one
of the pre-selected IDL color tables for elevation shading.
ELEVATION_SHADING: Set this keyword to put elevation shading into effect.
EXACT: Set this keyword to a one-, two-,or three-element array to set exact axis
scaling for the X, Y, and Z axes, respectively. If Exact is a one-element array,
all three axes are set to the same value. For example, to set the X axis to
exact scaling and the Y and Z axes to normal scaling, type:
IDL> FSC_Surface, Exact=[1,0,0]
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to the IDLgrSURFACE initialization routine.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
LANDSCAPE: Set this keyword if you are printing in landscape mode. The
default is Portrait mode. The Landscape keyword on the PRINTER object
is set, but not all printers will honor this keyword setting. If yours
does not, set Landscape mode in the Printer Setup dialog.
SHADED: Set this keyword to set up a shaded surface plot rather than a wire
mesh surface, which is the default.
TITLE: A string used as the title of the plot.
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.
DEPENDENCIES:
This program requires the following additional files from the Coyote Library:
error_message.pro
fsc_droplist.pro
getcolor.pro
loaddata.pro
pickcolor.pro
xcolors.pro
EXAMPLE:
To use this program with your data, type:
IDL> FSC_Surface, data
MODIFICATION HISTORY:
Written by David Fanning, 8 June 97.
Made axis scaling more robust. 17 Sept 97. DWF.
Minor modifications to incorporate better understanding
of how objects work. 4 Oct 97. DWF.
Fixed error cleaning up all of my created objects. 12 Feb 98. DWF.
Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
Fixed mis-spelling of HELVETICA14. 29 June 98. DWF.
Added the EXACT keyword to the X and Y axes to force axis ranging. 27 July 98. DWF
Added the ability to select rendering "drag" quality for faster operation. 22 Aug 98. DWF.
Added ability to get non-exact axis scaling. 12 May 99. DWF.
Improved documentation and readability of code. 12 May 99. DWF.
Added VECTOR and LANDSCAPE keywords and improved printing capability. 16 Feb 2000. DWF.
Added different lights and a Light Controller option. 28 April 2000. DWF.
Added elevation shading. 8 May 2000. DWF.
Removed VECTOR keyword. Replaced with VECTOR/BITMAP/COLOR Print buttons. 8 May 2000. DWF.
Added HIDDEN_LINE keyword. 8 May 2000. DWF.
Added EXACT keyword extensions and changed name from XSURFACE to FSC_SURFACE. 11 May 2000. DWF.
(See /home/drw/idl/aux/fsc_surface.pro)
NAME:
FSC_WINDOW
PURPOSE:
This routine implements a "smart" resizeable graphics window.
It is used as a wrapper for built-in IDL graphics procedures
such as SURFACE, CONTOUR, PLOT, SHADE_SURF, etc. In additon,
it can be used to display any user-written graphics procedure
so long as that procedure follows three simple rules: (1) It
does not open it's own graphics windows, (2) It is defined with
no more than three positional arguments (an unlimited number
of keyword arguments are allowed), and (3) It uses no device-
specific commands, such as "WSet", "Device, Decomposed=1", etc.
Keyword arguments permit the window to have its own portion
of a color table and to be able to change the colors loaded in
that portion of the color table. Colors are updated
automatically on both 8-bit and 24-bit color displays. In
addition, the window colors will "protect" themselves. I mean
by this that the window will re-load its own colors into the
color table when the window gains keyboard focus. This
prevents other applications from changing the colors used to
display data in this window. (This is an issue mainly in
IDL 5 applications where widget applications can run
concurrently with commands from the IDL command line.)
Keyword arguments also permit the window to create output
files of its contents. These files can be color and
gray-scale PostScript, and color BMP, GIF, JPEG, PICT, PNG,
TIFF, or JPEG files. Output can also be sent directly to
the default printer.
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, Graphics.
CALLING SEQUENCE:
FSC_WINDOW, command, P1, P2, P3
REQUIRED INPUTS:
COMMAND: The graphics procedure command to be executed. This parameter
must be a STRING and the the command must be a procedure. Examples
are 'SURFACE', 'CONTOUR', 'PLOT', etc.
OPTIONAL INPUTS:
P1: The first positional parameter appropriate for the graphics
command.
P2: The second positional parameter appropriate for the graphics
command.
P3: The third positional parameter appropriate for the graphics
command.
INPUT KEYWORD PARAMETERS:
WBACKGROUND: The background color index for the window. Setting this color
along with the WERASEIT keyword causes the window to be erased with
this color. Set to !P.Background by default.
WERASEIT: Setting this keyword "erases" the contents of the current
graphics window before re-executing the graphics command. For example,
this keyword might need to be set if the graphics "command" is TVSCL.
The default is to NOT erase the display before reissuing the graphics
command.
_EXTRA: This keyword forms an anonymous structure of any unrecognized
keywords passed to the program. The keywords must be appropriate
for the graphics command being executed.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
WTITLE: This is the window title. It is the string "COMMAND Window (1)"
by default, where COMMAND is the input parameter. And the number
(1 in this case) is the window index number of the draw widget.
WXPOS: This is the initial X offset of the window. Default is to
position the window in the approximate middle of the display.
WYPOS: This is the initial Y offset of the window. Default is to
position the window in the approximate middle of the display.
WPOSTSCRIPT: Set this keyword to 1 to include a PostScript File button under
the Save As button. This keyword is set automatically on 24-bit display
devices. To turn the button OFF on 24-bit devices, set the keyword value to 0.
There is no guaranteed way to create perfect PostScript output when the program
is run on 8-bit displays. This will depend entirely on how the "graphics command"
is written. Hence the button is turned off automatically on 8-bit devices.
WPRINT: Set this keyword to 1 to include a Print button under the File button.
This keyword is set automatically on 24-bit display devices. To turn the
button OFF on 24-bit devices, set the keyword value to 0. There is no
guaranteed way to print output correctly when the program is run on
8-bit displays. This will depend entirely on how the "graphics command"
is written. Hence the button is turned off automatically on 8-bit devices.
WXSIZE: This is the initial X size of the window. Default is 400
pixels.
WYSIZE: This is the initial Y size of the window. Default is 400
pixels.
WCOLORS: Using this keyword adds a "Colors..." button to the
"File" menu. Set this keyword to the number of colors available
in the window and the starting index of the first color. For example,
to allow the window access to 100 colors, starting at color index 50
(i.e., color indices 50 to 149), use WColors=[100, 50]. If you use the
keyword syntax "/WColors", all the colors available will be used, not just
one color. If the keyword is set to a scalar value greater than 1, the
starting color index is set to 0. The default value for this keyword
is [(!D.Table_Size, 0].
COMMON BLOCKS:
None.
RESTRICTIONS:
This program requires additional programs from the Fanning
Software Consulting library:
CENTERTLB.PRO
ERROR_MESSAGE.PRO
FSC_PSCONFIG__DEFINE.PRO
FSC_DROPLIST.PRO
FSC_FILESELECT.PRO
FSC_INPUTFIELD.PRO
FSC_PLOTWINDOW.PRO
PSCONFIG.PRO
PSWINDOW.PRO
TVREAD.PRO
XCOLORS.PRO
If the "command" program requires keywords that are also keywords
to FSC_WINDOW, then you must use the keyword twice on the command line.
EXAMPLE:
If the program is called with no parameters whatsoever, it will load
example data.
IDL> FSC_WINDOW
MODIFICATION HISTORY:
Written by: David Fanning, Sept 2000. Based on previous XWINDOW program.
Whoops! Left out the line to resize draw widgets on UNIX machines. Fixed. 12 Oct 2000, DWF.
(See /home/drw/idl/aux/fsc_window.pro)
Create a visible window and a corresponding buffer of frames in memory.
Color tables and plotting system variables (!x,!y,!z,!p)
are saved for each frame. Optional scroll bars may be used.
USAGE: FSET
OPTIONAL KEYWORDS:
FRAMES Number of frames to create (default=4)
XSIZE Horizontal frame size in pixels (default=640)
YSIZE Vertical frame size in pixels (default=480)
COLORS Number of colors to use
(Only has an effect when set for first window
created in an IDL session)
X_SCROLL_SIZE Viewable window horizontal size in pixels (default=no scroll)
Y_SCROLL_SIZE Viewable window vertical size in pixels (default=no scroll)
/PORTRAIT Creates a window sized like an 8.5x11" portrait page
/LANDSCAPE Creates a window sized like an 11x8.5" landscape page
/QUIET Do not print frame setup information (default=print)
/HELP Print help information only (default=do not print)
USAGE NOTES:
(1) Only one set of frame buffers created by FSET may be active at one time.
If a set of frame buffers exists, executing FSET will destroy the old
frame buffers and create a new set.
(2) Other graphics windows may be created while FSET frame buffers are in use.
Just use WINDOW,/FREE, and then examine !D.WINDOW to find the id of the
newly created window. Draw widgets may also be created while FSET
frame buffers are in use.
(3) To find the window ID for the FSET visible window, just type SF.
(4) Odd behavior may occur when COLORS=256 is specified.
AUTHOR: Liam Gumley, CIMSS/SSEC, 15-APR-1996 (liam.gumley@ssec.wisc.edu)
15-MAY-1996 Added /PORTRAIT and /LANDSCAPE keywords.
27-AUG-1996 Report number of colors allocated.
15-OCT-1996 It seems to work in 24 bit mode as well.
19-SEP-1997 Made FSET compatible with FSAVE and FRESTORE,
Added !MAP to state variables.
29-JAN-1998 Decreased size of portrait and landscape windows.
RELATED COMMANDS:
SF Show a frame and print frame information
AF Advance one frame
BF Backup one frame
LF Loop frames
EXAMPLE:
; Create 2 frames, display a different kind of graphic in each (with
; different color tables), overplot an array of values in each frame
; using the data coordinates defined for each frame, and then loop
; through the frames.
FSET,FRAMES=2
LOADCT,20 & PLOT,INDGEN(20),PSYM=2 & WAIT,1.0 & AF
LOADCT,30 & MAP_SET,/CONT & WAIT,1.0 & AF
FOR F=0,1 DO BEGIN & SF,F & OPLOT,INDGEN(20),PSYM=4 & WAIT,1.0 & ENDFOR
LF,DELAY=1.0
(See /home/drw/idl/aux/fset.pro)
NAME: FSPLOT
PURPOSE:
Plots light curves of BATSE data using the detectors, channels,
and sample averages specified by the operator.
CATEGORY: BATSE
CALLING SEQUENCE:
Fsplot
CALLS:
HXRBS_FORMAT, FIND_DBFILE, FSOC, FS_ACC, FS_GEN_ARR, FS_ACC_CONT,
FS_ACC_DISCSP, FS_ACC_GOES, FS_GRAPH, FS_OVERLAY, GET_UTBASE,
SETUT, ATIME, FS_AUTO_LOG, TEK_PRINT, FS_PRINT, FILELIST,
SHOW_FLARE, FLIST, TYPE_FLARE, FSELECT, FINDFILE, FS_ARCHIVE_RW,
FS_ARCHIVE_DRAW, PLOT_FLARE, READ_SEQFILE, CONCAT_DIR, MAILFILE,
FILE2FLARE, CHKLOG, USER_CHOOSE, SPECTRA2FITS, YOHKOH_FORMAT
INPUTS:
None
OUTPUTS:
Information saved in file *.out
OPTIONAL OUTPUTS:
Save fits file, ascii file or plot mailed to given address.
KEYWORDS:
WPLOT: If WPLOT is set and IFLARE is a flare number, then the 4 panel
figure is plotted and the program returns
IFLARE: A flare number used with WPLOT
INCOMMANDS: A buffer of command strings to be executed sequentially
COMMON BLOCKS:
FSCOM, FS_SAVEPLOT, FS_SAVEACCUM, SCALECOM
MODIFICATION HISTORY:
Written by: Shelby Kennard 30Jan1991
Mod. by Amy Skowronek 8/18/94 to use getenv instead of trnlog
Mod. by AES 8/24/94 to save cont_cos8 for cont data and sp_cos8
for discsp data rather than trying to save cos8.
Mod. by AES 8/29/94 to change variable global in scalecom
for multiple plots so characters remain readable.
Mod. by AES 8/30/94 to make a large screen if the user chooses "all4"
as a data option, so the words on the plot remain legible. The
user has the option of disabling this automatic resizing of the
plot window, using a menu command, autosize.
Mod. by AES 10/13/94 to *not* replace long size window with standard
size window when leaving fsplot.
Mod. by AES 10/24/94 to allow fsplot to be called with a flare
parameter. If called with iflare=number and /wplot, it
will display all four data types for that flare number, without
asking questions, and then exit fsplot.
Mod. by AES 11/1/94 to call window with retain=2 so windows don't get
lost.
Mod. by AES 1/17/95 to reset variable global to 1 before exiting to
main menu, so type size is reset after using the dat,all4
option.
Mod. by AES 4/6/95 to allow for FITS save - however as software is not
completely ready, asking for fits save reroutes to XDR.
Mod. by AES 4/11/95 to save livetime in SAVE option
Mod. by AES 4/27/95 to save BATSE user's files to anonymous.input.batse,
and only the required segment of the livetime array. Also save
files with flare number in name, e.g. discla_299.sav
Mod. by AES 5/23/95 to save plot in .gif format using command MakeGif
Mod. by AES 6/28/95 to check for architecture before printing filename.
Mod. by RCJ 12/04/95 to make global=1 when entering ARC command.
Mod. by RCJ 02/23/95 to save correct livetimes for cont and discsp data.
Mod. by RAS 16-apr-1996 to add input buffer command processing, also
defaults are no longer reset.
Mod. by RCJ 05/06/97 to save arrays in binary fits table using
spectra2fits. Also update documentation.
Version 21, RAS, 7-jun-1997, minor changes using loc_file to replace concat_dir
VERSION 22, richard.schwartz@gsfc.nasa.gov, 26-aug-1997,
used loc_file with path_dir('batse') to locate help files.
(See /home/drw/idl/bin/fsplot.pro)
*NAME:
FS_FITS_WRITE
*PURPOSE:
To write a FITS primary data unit or extension for CALFUSE which
is very picky about the order of the keywords
*CATEGORY:
INPUT/OUTPUT
*CALLING SEQUENCE:
FITS_WRITE, filename_or_fcb, data, [header_in]
*INPUTS:
FILENAME_OR_FCB: name of the output data file or the FITS control
block returned by FITS_OPEN (called with the /WRITE or
/APPEND) parameters.
*OPTIONAL INPUTS:
DATA: data array to write. If not supplied or set to a scalar, a
null image is written.
HEADER_IN: FITS header keyword. If not supplied, a minimal basic
header will be created. Required FITS keywords, SIMPLE,
BITPIX, XTENSION, NAXIS, ... are added by FITS_WRITE and
do not need to be supplied with the header. If supplied,
thier values will be updated as necessary to reflect DATA.
*KEYWORD PARAMETERS:
XTENSION: type of extension to write (Default="IMAGE"). If not
supplied, it will be taken from HEADER_IN. If not in either
place, the default is "IMAGE". This parameter is ignored
when writing the primary data unit.
EXTNAME: EXTNAME for the extension. If not supplied, it will be taken
from HEADER_IN. If not supplied and not in HEADER_IN, no
EXTNAME will be written into the output extension.
EXTVER: EXTVER for the extension. If not supplied, it will be taken
from HEADER_IN. If not supplied and not in HEADER_IN, no
EXTVER will be written into the output extension.
EXTLEVEL: EXTLEVEL for the extension. If not supplied, it will be taken
from HEADER_IN. If not supplied and not in HEADER_IN, no
EXTLEVEL will be written into the output extension.
NaNvalue: data value in DATA to be replaced with IEEE NaN in the output
file.
/NO_ABORT: Set to return to calling program instead of a RETALL
when an I/O error is encountered. If set, the routine will
return with !err=-1 and a message in the keyword MESSAGE.
If not set, FITS_READ will print the message and issue a RETALL
MESSAGE: value of the error message for use with /NO_ABORT
HEADER: actual output header written to the FITS file.
/NO_DATA: Set if you only want FITS_WRITE to write a header. The
header supplied will be written without modification and
the user is expected to write the data using WRITEU to unit
FCB.UNIT. When FITS_WRITE is called with /NO_DATA, the user is
responsible for the validity of the header, and must write
the correct amount and format of the data. When FITS_WRITE
is used in this fashion, it will pad the data from a previously
written extension to 2880 blocks before writting the header.
*NOTES:
If the first call to FITS_WRITE is an extension, FITS_WRITE will
automatically write a null image as the primary data unit.
Keywords and history in the input header will be properly separated
into the primary data unit and extension portions when constructing
the output header (See FITS_READ for information on the internal
Header format which separates the extension and PDU header portions).
*EXAMPLES:
Write an IDL variable to a FITS file with the minimal required header.
FITS_WRITE,'newfile.fits',ARRAY
Write the same array as an image extension, with a null Primary data
unit.
FITS_WRITE,'newfile.fits',ARRAY,xtension='IMAGE'
Write 4 image extensions to the same file.
FITS_OPEN,'newfile.fits',fcb
FITS_WRITE,fcb,data1,extname='FLUX',extver=1
FITS_WRITE,fcb,err1,extname'ERR',extver=1
FITS_WRITE,fcb,data2,extname='FLUX',extver=2
FITS_WRITE,fcb,err2,extname='ERR',extver=2
FITS_CLOSE,FCB
*PROCEDURES USED:
FITS_OPEN, SXADDPAR, SXDELPAR, SXPAR()
*HISTORY:
Written by: D. Lindler August, 1995
Work for variable length extensions W. Landsman August 1997
Converted to IDL V5.0 W. Landsman September 1997
Lindler, Nov. 1999, changed position of TFIELDS keyword in output
header
(See /home/drw/idl/fuse/fs_fits_write.pro)
NAME: FTV_GETFILE
PURPOSE:
Widget to select, specify, and load data from a FITS file into
FTV. The binary tables associated with FUSE photon lists
are first converted to images. 2D images located in
arbitary FITS extensions can be also be accessed.
CATEGORY:
Widgets: file selection.
CALLING SEQUENCE:
FTV_GETFILE
INPUTS:
None.
KEYWORD PARAMETERS:
None.
OUTPUTS:
None.
COMMON BLOCKS:
ftv_state, ftv_images, ftv_filselect (defined here)
SIDE EFFECTS:
This widget permits the user to select a FITS file, $
specify its format ("Photon List" or "Image"), specify the extension
in which the desired image resides, and load the data
into FTV for analysis.
RESTRICTIONS:
The maximum HDU that can be selected is 19, where the PDU = 0.
OTHER ROUTINES CALLED:
Including calls made in the associated event handler, FTV_GETFILE_EVENT
IDL Astro User's Library: mrdfits
David Sahnow's Library: readit
FTV suite: ftv_getstats, ftv_scale_image, ftv_makepan,
ftv_refresh
PROCEDURE:
Straightforward use of native IDL widgets and auxiliary file
reading routines.
MODIFICATION HISTORY
1999-06-10: Written by Alex Fullerton (FUSE / JHU).
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
Define the common blocks
COMMON ftv_state
COMMON ftv_images
COMMON ftv_filselect, fval
Define the base widget
base = WIDGET_BASE( title = 'File Selection Menu', /COLUMN )
Define a labelled field to indicate the current file selection.
Although this field can be editted, it will usually be populated
via the "pickfile" dialog box, which is activated by the
"File->Readfits" menu.
clab = WIDGET_LABEL( base, VALUE='Selection:', /ALIGN_CENTER )
cfile = WIDGET_TEXT( base, XSIZE = 26, /SCROLL, /EDITABLE, $
VALUE = ' No current selection ', $
UVALUE = 'fselect' )
Create a droplist widget to toggle between file formats.
The default is "Photon List", which will be read by Dave Sahnow's
"readit" procedure.
fval = ['Photon List', 'Image ']
ftype = WIDGET_DROPLIST( base, VALUE = fval, $
TITLE = 'Format: ', $
UVALUE = 'filetype' )
Create a droplist widget to specify the extension number to be read.
This information will only be used when reading "IMAGE" formats.
eval = STRTRIM( STRING( INDGEN( 20 ) ), 2)
enum = WIDGET_DROPLIST( base, VALUE = eval, $
TITLE = 'FITS HDU: ', $
UVALUE = 'extnum' )
Create a button to enable the "dialog_pickfile" browser.
sbut = WIDGET_BUTTON( base, $
VALUE = 'Select File', $
UVALUE = 'sel_file' )
Create a button to load the specified extension of the selected
file into ftv. If the file type is "TTAG", then an image version
of the photon list will be created first.
lbut = WIDGET_BUTTON( base, $
VALUE = 'Load Selection', $
UVALUE= 'load_file' )
Define a structure that contains the widget identifiers associated with
each of the fields/buttons. This will be passed to the event handler.
sstate = { cfile:cfile, $
ftype:ftype, $
enum: enum, $
sbut: sbut, $
lbut: lbut }
Realize the widget and initialize the current file selection window.
WIDGET_CONTROL, base, /REALIZE, SET_UVALUE = sstate, $
TLB_SET_XOFFSET = 5
Disable the extension specification if the file type is "Photon List".
fnum = WIDGET_INFO( ftype, /DROPLIST_SELECT )
IF ( fnum EQ 0 ) THEN WIDGET_CONTROL, enum, SENSITIVE = 0, $
SET_DROPLIST_SELECT = 1
Hand off control to the XMANAGER.
XMANAGER, 'ftv_getfile', base, GROUP_LEADER = state.base_id
END
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/ftv.pro)
fuse_analysis_common
if n_elements(ps) eq 0 then ps=0
erase any overlay
if ps eq 0 then fuse_analysis_rmoverlay,state
determine plot to produce
widget_control, widget.plot_select, get_value=isel
get wavelength range
widget_control, widget.wmin_field, get_value=wmin
widget_control, widget.wmax_field, get_value=wmax
wmin = double(wmin(0))
wmax = double(wmax(0))
update data mins and maxs if range change
wrange_change = 0
if (wmax le wmin) then begin
if wmin eq widget.wrange(0) then wmin = wmax - options.wrange $
else wmax = wmin + options.wrange
widget_control, widget.wmin_field, set_value=wmin
widget_control, widget.wmax_field, set_value=wmax
wrange_change = 1
end
if (abs(float(wmin)-widget.wrange(0)) gt 0.01) or $
(abs(float(wmax)-widget.wrange(1)) gt 0.01) then begin
wrange_change = 1
widget.wrange = [wmin,wmax]
end
update plot y-ranges
if (wrange_change eq 1) and (not keyword_set(keep_yrange)) then begin
fuse_anal_pminmax,widget.wrange,spec_sic1a,spec_sic1b,min0,max0,np0
fuse_anal_pminmax,widget.wrange,spec_sic2a,spec_sic2b,min1,max1,np1
fuse_anal_pminmax,widget.wrange,spec_lif1a,spec_lif1b,min2,max2,np2
fuse_anal_pminmax,widget.wrange,spec_lif2a,spec_lif2b,min3,max3,np3
fmins = [min0,min1,min2,min3]
fmaxs = [max0,max1,max2,max3]
n = [np0,np1,np2,np3]
if max(n) gt 0 then begin
good = where(n gt 0)
plotpar(0).datamin = min(fmins(good))
plotpar(0).datamax = max(fmaxs(good))
endif
plotpar([1,2,3,4]).datamin=fmins
plotpar([1,2,3,4]).datamax=fmaxs
plotpar.ymin = 0
plotpar.ymax = 0
end
if ps eq 0 then begin
wset,widget.plot_id
set_viewport,0.1,0.98,0.05,0.80
end else begin
set up postscript plots
file = dialog_pickfile(file='idl.ps',filter='*.ps',/write, $
dialog_parent=widget.base)
if file eq '' then return ;no file selected
device = !d.name
set_plot,'ps'
if ps eq 3 then color=1 else color=0
device,/port,xoff=0.5,yoff=0.45,xsize=7.5,ysize=10,/inches,bits=8, $
color=color,file=file
if ps eq 3 then tvlct,rsave,gsave,bsave
set_viewport,0.1,0.98,0.4,0.82
end
case isel of
0: begin
yoff = plotpar(0).yoffset
yrange = [plotpar(0).ymin,plotpar(0).ymax]
if max(abs(yrange)) eq 0.0 then begin
yrange = [plotpar(0).datamin,plotpar(0).datamax]
yrange(1) = yrange(1) + yoff*3
yrange(0) = yrange(0) - (yrange(1)-yrange(0))*0.05
end
over = 0
fuse_anal_plot1,widget,spec_sic1a,plotpar(1),linetab, $
yrange=yrange,yoff=yoff*3,over=over,ps=ps
fuse_anal_plot1,widget,spec_sic1b,plotpar(1),linetab, $
over=over,yoff=yoff*3,ps=ps
fuse_anal_plot1,widget,spec_sic2a,plotpar(2),linetab, $
over=over,yoff=yoff*2,ps=ps
fuse_anal_plot1,widget,spec_sic2b,plotpar(2),linetab, $
over=over,yoff=yoff*2,ps=ps
fuse_anal_plot1,widget,spec_lif1a,plotpar(3),linetab, $
over=over,yoff=yoff,ps=ps
fuse_anal_plot1,widget,spec_lif1b,plotpar(3),linetab, $
over=over,yoff=yoff,ps=ps
fuse_anal_plot1,widget,spec_lif2a,plotpar(4),linetab, $
over=over,yoff=0.0,ps=ps
fuse_anal_plot1,widget,spec_lif2b,plotpar(4),linetab, $
over=over,yoff=0.0,ps=ps
endcase
1: begin
over = 0
fuse_anal_plot1,widget,spec_sic1a,plotpar(1),over=over, $
ps=ps,linetab
fuse_anal_plot1,widget,spec_sic1b,plotpar(1),over=over, $
ps=ps,linetab
end
2: begin
over = 0
fuse_anal_plot1,widget,spec_sic2a,plotpar(2),linetab, $
ps=ps,over=over
fuse_anal_plot1,widget,spec_sic2b,plotpar(2),linetab,over=over
end
3: begin
over = 0
fuse_anal_plot1,widget,spec_lif1a,plotpar(3),linetab, $
ps=ps,over=over
fuse_anal_plot1,widget,spec_lif1b,plotpar(3),linetab, $
ps=ps,over=over
end
4: begin
over = 0
fuse_anal_plot1,widget,spec_lif2a,plotpar(4),linetab, $
ps=ps,over=over
fuse_anal_plot1,widget,spec_lif2b,plotpar(4),linetab, $
ps=ps,over=over
end
5: erase
6: fuse_anal_plot1,widget,sp1,plotpar(6),linetab, $
ps=ps,title=sp1.title
7: fuse_anal_plot1,widget,sp2,plotpar(7),linetab, $
ps=ps,title=sp2.title
8: fuse_anal_plot1,widget,sp3,plotpar(8),linetab, $
ps=ps,title=sp3.title
9: fuse_anal_plot1,widget,sp4,plotpar(9),linetab, $
ps=ps,title=sp4.title
else:
endcase
if wrange_change or (ps gt 0) then $
fuse_analysis_dispall,ps ;display with new wrange
if ps gt 0 then begin
set_viewport,0,1,0,1
color=5
!p.font=0
if ps eq 3 then color=5 else color=0
xyouts,0.5,0.985,widget.rootname,/norm,charsize=1.4, $
color=color,align=0.5
device,/close
set_plot,device
!p.font=-1
end
eturn
nd
(See /home/drw/idl/fuse/fuse_analysis_plot.pro)
FUSE_LINEFIND Routine to find line postions for wavelength calibration CALLING SEQUENCE: fuse_linefind or fuse_linefind,wave,flux,x,header,filename INPUT: wave - wavelength vector flux - flux vector x - vector of pixel positions header - FITS header for the data filename - name of the file that the data was read from HISTORY: version 1, D. Lindler, 1999 Oct 2000, added line library wavelength shift buttons.
(See /home/drw/idl/fuse/fuse_linefind.pro)
FUSE_SCAN
Routine to interactively examine raw FUSE data files
CALLING SQUENCE:
fuse_scan
or
fuse_scan,data,header
OPTIONAL INPUTS:
data - data array
header - FITS header
INTERACTIVE INPUT:
Image Windows:
lower - display of whole image rebinned to 1024 x 128 size
upper left - scrollable display of whole image without any
rebinning.
upper right - zoomed image display
To select region viewed in upper right image use the scroll bars
to the botton and right of the image or place cursor in bottom image
and push any mouse button.
To select region for the zoomed image. Place cursor in the upper
left window and push any mouse button.
MENU BUTTONS:
FILE/READ - to specify and read a FUSE fits file
FILE/PS output - to write postscript file of screen contents
FILE/EXIT - to exit the program
COLORS - to change color table
CONTRAST - to change intensity scaling function (linear, log, square
root, or histogram equalization)
IMAGE/SET_REGION - use to manually set regions displayed in the
big window or the zoom window
IMAGE/HISTOGRAM - to plot histogram of data values
IMAGE/Display Header - to display the image's header
STATS - to generate statistics of selected region. To generate
statistics for a box or draw region, follow directions
given above upper left window.
PLOT - to plot rows, columns, row sums, column sums, or cross
sectional plots. After selecting type of plot, follow the
directions given above the upper left window. If a second
plot is made without closing the first plot window, it will
be overplotted on the existing plot.
OVERLAY/Wavelength scale - to display approximate wavelength scale
overlay
OVERLAY/Clear Overlay- to clear overlay lines written on the image
Time-Tag - time tag processing, plots/movies/good time editing
Zoom Image/GAUSSFIT - to fit gaussians in both directions to zoomed
region
Zoom Image/SURFACE - to generate surface plot of zoomed region
Zooom Image/CONTOUR - to generate a contour plot of the zoomed region
ZOOM Factor- to change the zoom factor of the zoom window
TEXT Boxes
Freeze Min/Max - to Freeze the values of the Min and Max used for
image scaling.
Min - image minimum - used to set background level for display and
for computing statistics of selected regions
Max - image maximum - used to set maximum for image scaling
Reset Min/Max - sets Min and Max to the original image Min/Max
X - displays x position of cursor in image pixel coordinates
y - displays y position of cursor in image pixel coordinates
Val - displays data value for the pixel at the specified x/y
HISTORY:
version 1 D. Lindler, Sept, 1999
Oct. 2000: modified to update goodtimes in output time-tag file,
added wavelength scale overlay, Modified menu bar
button positions.
(See /home/drw/idl/fuse/fuse_scan.pro)
ROUTINE: fwhm PURPOSE: Calculate the FWHM in wavelengths USEAGE: result = fwhm(wave,flux) INPUT: wave Wavelength array flux Flux array OUTPUT: result The FWHM in wavelength units. NOTE: standard deviation = FWHM / 2.3548 (approx.) 1/e width = FWHM / 0.832 (approx.) AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/fwhm.pro)
ROUTINE: fwhm PURPOSE: Calculate the FWHM in wavelengths USEAGE: result = fwhm(wave,flux) INPUT: wave Wavelength array flux Flux array OUTPUT: result The FWHM in wavelength units. NOTE: standard deviation = FWHM / 2.3548 (approx.) 1/e width = FWHM / 0.832 (approx.) AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/ptg/fwhm.pro)
NAME:
FXGCLOSE
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:
Closes a generic resource
MAJOR TOPICS:
File I/O, Pipes, URLs, FITS
CALLING SEQUENCE:
FXGCLOSE, UNIT
DESCRIPTION:
FXGCLOSE closes a generic resource originally opened by FXGOPEN.
All associated system resources are freed.
You must use the specialized 'FXG' style functions to read, write
and seek on file units opened with FXGOPEN:
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
INPUTS:
UNIT - the unit number of the currently open resource. The unit
must have been previously opened by FXGOPEN.
MODIFICATION HISTORY:
Written, 1999, CM
Documented, 02 Oct 1999, CM
Changed copyright notice, 21 Sep 2000, CM
$Id: fxgclose.pro,v 1.2 2001/03/25 18:10:45 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxgclose.pro)
NAME:
FXGFILTERED
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:
Determine if a unit has been opened by FXGOPEN.
MAJOR TOPICS:
File I/O, Pipes, URLs, FITS
CALLING SEQUENCE:
Q = FXGFILTERED(UNIT)
DESCRIPTION:
FXGFILTERED is a function which determines whether a UNIT has been
opened by FXGOPEN and requires special handling.
In principle, only 'FXG' procedures should be used to access file
units returned by FXGOPEN. However, if the unit turns out to be a
normal file then special treatment is not required. User programs
can use the FXGFILTERED function to find out this information.
If FXGFILTERED returns 0, then normal file-access procedures (such
as READU, WRITEU, CLOSE, and POINT_LUN) can be used. Otherwise,
the 'FXG' routines must be used.
INPUTS:
UNIT - Any file LUN.
RETURNS:
0 - resource is a normal file.
1 - resource is not a normal file.
EXAMPLE:
if fxgfiltered(unit) EQ 0 then begin
;; If zero then can use standard IDL routines
point_lun, unit, position
readu, unit, buffer
close, unit
endif
MODIFICATION HISTORY:
Written, 1999, CM
Documented, 02 Oct 1999, CM
Changed copyright notice, 21 Sep 2000, CM
TODO:
* Add more protocols
* Make more windows friendly
$Id: fxgfiltered.pro,v 1.2 2001/03/25 18:10:45 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxgfiltered.pro)
NAME:
FXGOPEN
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:
Open generic resource as a seekable file.
MAJOR TOPICS:
File I/O, Pipes, URLs, FITS
CALLING SEQUENCE:
FXGOPEN, UNIT, RESOURCE, ACCESS=ACCESS, ERRMSG=ERRMSG
DESCRIPTION:
FXGOPEN opens a generic "resource" for reading or writing. A
"resource" can be a file or a Unix pipe, and eventually it is
hoped to add support for generic URLs (i.e., Internet locators
such as http, FTP), shared files, and an in-memory file system.
Readable resources are fully random access. You are permitted to
perform seek operations on both files and streams such as Unix
pipes. In the case of a stream, the stream is read upon demand
and saved to an on-disk cache.
FXGOPEN also automatically recognizes some standard Unix file
extensions and operates on them. For example, files ending with
'.gz' are recognized as being compressed with gzip, and are passed
through gzcat to uncompress them. You can display existing
filename extension mappings and add new ones using the FXMAKEMAP
procedure.
The UNIT number is allocated using GET_LUN; however, the internal
implementation may allocate more LUNs. Therefore you must use
FXGCLOSE to close the LUN and be sure that all resources are
deallocated.
You must use the specialized 'FXG' style functions to read, write
and seek on the resulting unit number:
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
INPUTS:
UNIT - FXGOPEN will return a LUN in this variable. It should be
subsequently read and written with FXGREAD, FXGWRITE, and
closed with FXGCLOSE.
RESOURCE - a string, describing the resource to be opened.
FXGOPEN will automatically determine how to open it
according to:
* If a filename the suffix may be mapped according to
FXMAKEMAP. In that case the appropriate pipe command
is opened as a Unix pipe with FXPOPENR.
* If a string beginning with "|" then the remaining
part of the string is interpretted as a Unix pipe
command, to be opened with FXPOPENR.
* If a URL (uniform resource locator), then it is
accessed. Currently supported protocols are:
file - a local file
That's all! I would like to support FTP at least, and
also some sort of in-memory files, probably with a
"mem" protocol.
KEYWORD PARAMETERS:
ACCESS - a string, set to the access privileges of the resource.
Possible values are:
'R' - read-only
'W' - write/create
'RW' - write/update
Not all protocols support writing.
DEFAULT: 'R'
ERRMSG - If a named variable is passed with this keyword, an error
message is returned: the empty string indicates success;
a non-empty string indicates failure. If a named
variable is not passed, and the ERROR keyword is not
used, then execution is stopped upon an error.
ERROR - If a named variable is passed with this keyword, the error
status is returned: a zero indicates success; non-zero
indicates failure. If a named variable is not passed, and
the ERRMSG keyword is not used, then execution is stopped
upon an error.
SUFFIX - Force a particular file type by specifying the suffix.
Default is to extract the suffix from the file name
itself.
EXAMPLE:
fxgopen, unit, 'myfile.gz', errmsg=errmsg
if errmsg NE '' then do_error_message
bb = bytarr(1000) ;; Read 1000 bytes
fxgread, unit, bb
fxgclose, unit
This example opens the file myfile.gz using FXGOPEN. It is
automatically gunzip'ed on demand as the request for a 1000-byte
read is made.
MODIFICATION HISTORY:
Written, 1999, CM
Documented, 02 Oct 1999, CM
Added correct ERROR keyword behavior, 04 Oct 1999, CM
Changed copyright notice, 21 Sep 2000, CM
Modified to use ARG_PRESENT for ERRMSG and ERROR, 21 Sep 2000, CM
Added SUFFIX keyword, 31 Oct 2000, CM
TODO:
* Add more protocols
* Make more windows friendly
$Id: fxgopen.pro,v 1.2 2001/03/25 18:10:45 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxgopen.pro)
NAME:
FXGREAD
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 an unformatted read on a generic resource.
MAJOR TOPICS:
File I/O, Pipes, URLs, FITS
CALLING SEQUENCE:
FXGREAD, UNIT, BUFFER, TRANSFER_COUNT=TC
DESCRIPTION:
FXGREAD performs an unformatted read on the unit UNIT. The UNIT
must have previously been opened by FXGOPEN.
Currently only unformatted reads are permitted because the precise
number of bytes to read must be known ahead of time.
In other respects, this procedure is similar to the READU built-in
IDL procedure.
You must use the specialized 'FXG' style functions to read, write
and seek on file units opened with FXGOPEN:
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
INPUTS:
UNIT - the unit number to operate on. The unit must have been
previously opened by FXGOPEN.
BUFFER - an array of the desired type and size is passed upon
input to FXGREAD. Only basic types are permitted. Upon
output, the array will have been filled with data from
the resource. The full extent of the transfer can be
determined by examining the TRANSFER_COUNT.
KEYWORD PARAMETERS:
TRANSFER_COUNT - upon output, contains the number of elements
transferred to BUFFER.
MODIFICATION HISTORY:
Written, 1999, CM
Documented, 02 Oct 1999, CM
Changed copyright notice, 21 Sep 2000, CM
$Id: fxgread.pro,v 1.2 2001/03/25 18:10:45 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxgread.pro)
NAME:
FXGSEEK
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 a seek operation on a generic resource.
MAJOR TOPICS:
File I/O, Pipes, URLs, FITS
CALLING SEQUENCE:
FXGSEEK, UNIT, POSITION ;; Sets the current file position
FXGSEEK, -UNIT, POSITION ;; Queries the current file position
DESCRIPTION:
FXGSEEK performs a seek on the selected resource. Depending on
the sign of UNIT, the current file position is either queried or
set, in much the same manner as the built-in IDL procedure
POINT_LUN.
If the resource is a stream, the seek operation does not
necessarily force a read until FXGREAD is called (i.e., reads are
"lazy").
You must use the specialized 'FXG' style functions to read, write
and seek on file units opened with FXGOPEN:
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
INPUTS:
UNIT - the unit number to operate on. The unit must have been
previously opened by FXGOPEN. The operation of FXGSEEK
depends on the sign of UNIT. If UNIT is positive, then the
current file position of file UNIT is set to POSITION. If
UNIT is negative, then the current file position of file
|UNIT| is placed in the variable POSITION.
POSITION - Depending on the sign of UNIT, the behavior is
different. When UNIT is positive, POSITION is an input
variable containing the new file position. When UNIT
is negative, POSITION is an output variable to contain
the file's current file position.
MODIFICATION HISTORY:
Written, 1999, CM
Documented, 02 Oct 1999, CM
Changed copyright notice, 21 Sep 2000, CM
$Id: fxgseek.pro,v 1.2 2001/03/25 18:10:45 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxgseek.pro)
NAME:
FXGWRITE
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 an unformatted write to a generic resource.
MAJOR TOPICS:
File I/O, Pipes, URLs, FITS
CALLING SEQUENCE:
FXWRITE, UNIT, BUFFER, TRANSFER_COUNT=TC
DESCRIPTION:
FXGWRITE performs an unformatted write to the unit UNIT. The UNIT
must have previously been opened by FXGOPEN with write access.
Currently only unformatted reads are permitted because the precise
number of bytes to written must be known ahead of time.
In other respects, this procedure is similar to the WRITEU
built-in IDL procedure.
You must use the specialized 'FXG' style functions to read, write
and seek on file units opened with FXGOPEN:
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
INPUTS:
UNIT - the unit number to operate on. The unit must have been
previously opened by FXGOPEN.
BUFFER - the array to be written. Only basic types are permitted.
The actual number of bytes transferred can be determined
by examining the TRANSFER_COUNT.
KEYWORD PARAMETERS:
TRANSFER_COUNT - upon output, contains the number of elements
transferred from BUFFER.
MODIFICATION HISTORY:
Written, 1999, CM
Documented, 02 Oct 1999, CM
Changed copyright notice, 21 Sep 2000, CM
$Id: fxgwrite.pro,v 1.2 2001/03/25 18:10:45 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxgwrite.pro)
NAME:
FXMAKEMAP
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:
Change configuration of FXG - FXFILTER'ed behavior
MAJOR TOPICS:
File I/O, Pipes, URLs, FITS
CALLING SEQUENCE:
FXMAKEMAP, SUFFIX, COMMAND or
FXMAKEMAP, /INFO or
FXMAKEMAP, [SCRATCH_DIR=scratch,] [BUFFER_MAX=bufmax,]
[BUFFER_GRAN=bufgran,] [RM_COMMAND=rmcommand,] [/GET]
DESCRIPTION:
FXMAKEMAP queries or sets the behavior of the FXFILTER family of
functions (FXGOPEN, FXGREAD, FXGWRITE, FXGSEEK, and FXGCLOSE).
To add a new file extension mapping, which associates a filename
suffix with a particular Unix pipe command, use the first form of
the command.
To print the current settings, including the file extension maps,
use the /INFO form of the command.
To set an individual parameter, call FXMAKEMAP with the
appropriate keyword argument.
To query an individual parameter, call FXMAKEMAP with /GET and the
appropriate keyword argument.
INPUTS:
SUFFIX - the trailing suffix of the filename to be associated,
*without* the period. For example, for a gzipped file,
the suffix is 'gz'
COMMAND - an IDL-style format command which specifies how the
filename should be converted into a Unix pipe command.
The actual command is constructed by passing the
filename to STRING() with this format string. For
example, to convert a gzip file the proper format string
is, '("gzip -dc ",A0)'.
KEYWORD PARAMETERS:
INFO - print the current settings and return.
GET - if this keyword is set, then the following keyword commands
cause the current setting to be returned in the specified
keyword. Otherwise the default is to assert a new setting.
BUFFER_GRAN - the buffer granularity in bytes. I/O operations on
pipes and streams are performed in multiples of this
size. Default: 4096 bytes.
BUFFER_MAX - the maximum allowed buffer size in bytes. I/O
operations on pipes and streams are performed with at
most this many bytes. Default: 32 kbytes.
RM_COMMAND - the Unix command used to delete files.
Default: '/bin/rm'
SCRATCH_DIR - the scratch directory where cache files are stored.
When operations on Unix pipes or streams are
performed, the data are stored in individual files
in this directory.
MODIFICATION HISTORY:
Written, 1999, CM
Documented, 02 Oct 1999, CM
Changed copyright notice, 21 Sep 2000, CM
$Id: fxmakemap.pro,v 1.2 2001/03/25 18:10:46 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxmakemap.pro)
NAME:
FXPBUFFR
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:
Internal routine to read data from the pipe and store it in a
cache file.
DESCRIPTION:
See the following procedures for appropriate documentation.
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
PARAMETERS
unit - LUN of the pipe, *not* the cache file.
newlen - the new desired length of the file. After a successful
call to FXPBUFFR, the length of the cache file will be at
least this long.
Side Effects
The pipe is read and the cache increases in size.
MODIFICATION HISTORY:
Changed copyright notice, 21 Sep 2000, CM
$Id: fxpbuffr.pro,v 1.2 2001/03/25 18:10:46 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxpbuffr.pro)
NAME:
FXPCLOSE
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:
Internal routine to close a pipe file.
DESCRIPTION:
See the following procedures for appropriate documentation.
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
PARAMETERS
unit - LUN of the pipe, *not* the cache file.
Side effects
The pipe is closed.
The cache file is closed and deleted.
MODIFICATION HISTORY:
Changed copyright notice, 21 Sep 2000, CM
$Id: fxpclose.pro,v 1.2 2001/03/25 18:10:46 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxpclose.pro)
NAME:
FXPOPENR
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:
Internal routine to open a Unix pipe command for read access.
DESCRIPTION:
See the following procedures for appropriate documentation.
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
Usage: FXPOPENR, UNIT, COMMAND, ERRMSG=ERRMSG
PARAMETERS
unit - FXPOPENR returns the pipe LUN, created by GET_LUN in this
parameter. The LUN should not be "pre-opened".
Unformatted reads on this LUN should be performed with
FXPREAD.
command - a scalar string, the pipe command to execute. The
standard output of the command is redirected into UNIT.
Standard error is not redirected.
A failure of the command can only be discovered upon
trying to read from the LUN with FXPREAD.
Keywords
errmsg - If set to defined value upon input, an error message is
returned upon output. If no error occurs then ERRMSG is
not changed. If an error occurs and ERRMSG is not
defined, then FXPOPENR issues a MESSAGE.
Side Effects
The pipe command is opened with SPAWN, and an additional cache file
is opened with read/write access.
The FXFILTER family of commons is updated.
MODIFICATION HISTORY:
Changed copyright notice, 21 Sep 2000, CM
$Id: fxpopenr.pro,v 1.2 2001/03/25 18:10:46 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxpopenr.pro)
NAME:
FXPREAD
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:
Internal routine to read from a Unix pipe.
DESCRIPTION:
See the following procedures for appropriate documentation.
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
PARAMETERS
unit - LUN of the pipe command, *not* the cache file.
buffer - the buffer to accept the data. Data is read in
*unformatted*.
Side Effects
The pipe is read as needed and the cache is populated.
The file pointer advances.
MODIFICATIONS
Corrected error message, 21 Sep 2000, CM
Changed copyright notice, 21 Sep 2000, CM
$Id: fxpread.pro,v 1.2 2001/03/25 18:10:46 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxpread.pro)
NAME:
FXPSEEK
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:
Internal routine to perform seek on a Unix Pipe.
DESCRIPTION:
See the following procedures for appropriate documentation.
FXGOPEN - open resource
FXGCLOSE - close resource
FXGREAD - read from resource
FXGWRITE - write to resource
FXGSEEK - seek on resource (i.e., perform POINT_LUN)
FXGFILTERED - determine if resource is a normal file.
PARAMETERS
unit - the pipe LUN. If positive, then the file pointer is moved
to POSITION in the pipe output. [ In reality the file
pointer is moved in the cache file. ] If negative, then
the file pointer of the file unit -LUN is returned in
POSITION.
position - the file pointer, either passed or returned as defined
by UNIT.
Side Effects
The file pointer may be updated.
Actual file accesses are postponed until needed (ie, when FXPREAD
is called).
MODIFICATION HISTORY:
Changed copyright notice, 21 Sep 2000, CM
$Id: fxpseek.pro,v 1.2 2001/03/25 18:10:47 craigm Exp $
(See /home/drw/idl/aux/markwardt/fxpseek.pro)
NAME:
GAUSS1P
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Compute Gaussian curve given the mean, sigma and area (procedure).
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
GAUSS1, XVALS, [MEAN, SIGMA, AREA], YVALS, SKEW=skew
DESCRIPTION:
This routine computes the values of a Gaussian function whose
X-values, mean, sigma, and total area are given. It is meant to be
a demonstration for curve-fitting.
XVALS can be an array of X-values, in which case the returned
Y-values are an array as well. The second parameter to GAUSS1
should be an array containing the MEAN, SIGMA, and total AREA, in
that order.
INPUTS:
X - Array of X-values.
[MEAN, SIGMA, AREA] - the mean, sigma and total area of the
desired Gaussian curve.
YVALS - returns the array of Y-values.
KEYWORD PARAMETERS:
SKEW - You may specify a skew value. Default is no skew.
EXAMPLE:
p = [2.2D, 1.4D, 3000.D]
x = dindgen(200)*0.1 - 10.
gauss1p, x, p, y
Computes the values of the Gaussian at equispaced intervals
(spacing is 0.1). The gaussian has a mean of 2.2, standard
deviation of 1.4, and total area of 3000.
REFERENCES:
MODIFICATION HISTORY:
Transcribed from GAUSS1, 13 Dec 1999, CM
Added copyright notice, 25 Mar 2001, CM
$Id: gauss1p.pro,v 1.2 2001/03/25 18:55:12 craigm Exp $
(See /home/drw/idl/aux/markwardt/gauss1p.pro)
NAME:
GAUSS1P
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Compute Gaussian curve given the mean, sigma and area (procedure).
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
GAUSS1, XVALS, [MEAN, SIGMA, AREA], YVALS, SKEW=skew
DESCRIPTION:
This routine computes the values of a Gaussian function whose
X-values, mean, sigma, and total area are given. It is meant to be
a demonstration for curve-fitting.
XVALS can be an array of X-values, in which case the returned
Y-values are an array as well. The second parameter to GAUSS1
should be an array containing the MEAN, SIGMA, and total AREA, in
that order.
INPUTS:
X - Array of X-values.
[MEAN, SIGMA, AREA] - the mean, sigma and total area of the
desired Gaussian curve.
YVALS - returns the array of Y-values.
KEYWORD PARAMETERS:
SKEW - You may specify a skew value. Default is no skew.
EXAMPLE:
p = [2.2D, 1.4D, 3000.D]
x = dindgen(200)*0.1 - 10.
gauss1p, x, p, y
Computes the values of the Gaussian at equispaced intervals
(spacing is 0.1). The gaussian has a mean of 2.2, standard
deviation of 1.4, and total area of 3000.
REFERENCES:
MODIFICATION HISTORY:
Transcribed from GAUSS1, 13 Dec 1999, CM
Added copyright notice, 25 Mar 2001, CM
$Id: gauss1p.pro,v 1.2 2001/03/25 18:55:12 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/gauss1p.pro)
NAME:
GAUSS1
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Compute Gaussian curve given the mean, sigma and area.
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
YVALS = GAUSS1(XVALS, [MEAN, SIGMA, AREA], SKEW=skew)
DESCRIPTION:
This routine computes the values of a Gaussian function whose
X-values, mean, sigma, and total area are given. It is meant to be
a demonstration for curve-fitting.
XVALS can be an array of X-values, in which case the returned
Y-values are an array as well. The second parameter to GAUSS1
should be an array containing the MEAN, SIGMA, and total AREA, in
that order.
INPUTS:
X - Array of X-values.
[MEAN, SIGMA, AREA] - the mean, sigma and total area of the
desired Gaussian curve.
INPUT KEYWORD PARAMETERS:
SKEW - You may specify a skew value. Default is no skew.
PEAK - if set then AREA is interpreted as the peak value rather
than the area under the peak.
RETURNS:
Returns the array of Y-values.
EXAMPLE:
p = [2.2D, 1.4D, 3000.D]
x = dindgen(200)*0.1 - 10.
y = gauss1(x, p)
Computes the values of the Gaussian at equispaced intervals
(spacing is 0.1). The gaussian has a mean of 2.2, standard
deviation of 1.4, and total area of 3000.
REFERENCES:
MODIFICATION HISTORY:
Written, Jul 1998, CM
Correct bug in normalization, CM, 01 Nov 1999
Optimized for speed, CM, 02 Nov 1999
Added copyright notice, 25 Mar 2001, CM
Added PEAK keyword, 30 Sep 2001, CM
$Id: gauss1.pro,v 1.4 2001/10/13 17:41:48 craigm Exp $
(See /home/drw/idl/aux/markwardt/gauss1.pro)
NAME:
GAUSS1
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Compute Gaussian curve given the mean, sigma and area.
MAJOR TOPICS:
Curve and Surface Fitting
CALLING SEQUENCE:
YVALS = GAUSS1(XVALS, [MEAN, SIGMA, AREA], SKEW=skew)
DESCRIPTION:
This routine computes the values of a Gaussian function whose
X-values, mean, sigma, and total area are given. It is meant to be
a demonstration for curve-fitting.
XVALS can be an array of X-values, in which case the returned
Y-values are an array as well. The second parameter to GAUSS1
should be an array containing the MEAN, SIGMA, and total AREA, in
that order.
INPUTS:
X - Array of X-values.
[MEAN, SIGMA, AREA] - the mean, sigma and total area of the
desired Gaussian curve.
INPUT KEYWORD PARAMETERS:
SKEW - You may specify a skew value. Default is no skew.
PEAK - if set then AREA is interpreted as the peak value rather
than the area under the peak.
RETURNS:
Returns the array of Y-values.
EXAMPLE:
p = [2.2D, 1.4D, 3000.D]
x = dindgen(200)*0.1 - 10.
y = gauss1(x, p)
Computes the values of the Gaussian at equispaced intervals
(spacing is 0.1). The gaussian has a mean of 2.2, standard
deviation of 1.4, and total area of 3000.
REFERENCES:
MODIFICATION HISTORY:
Written, Jul 1998, CM
Correct bug in normalization, CM, 01 Nov 1999
Optimized for speed, CM, 02 Nov 1999
Added copyright notice, 25 Mar 2001, CM
Added PEAK keyword, 30 Sep 2001, CM
$Id: gauss1.pro,v 1.4 2001/10/13 17:41:48 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/gauss1.pro)
NAME: GAUSS2 AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Compute Gaussian curve given the mean, sigma and area. MAJOR TOPICS: Curve and Surface Fitting CALLING SEQUENCE: YVALS = GAUSS2(X, Y, [XCENT, YCENT, SIGMA, PEAK]) DESCRIPTION: This routine computes the values of a Gaussian function whose X-values, mean, sigma, and total area are given. It is meant to be a demonstration for curve-fitting. XVALS can be an array of X-values, in which case the returned Y-values are an array as well. The second parameter to GAUSS1 should be an array containing the MEAN, SIGMA, and total AREA, in that order. INPUTS: X - 2-dimensional array of "X"-values. Y - 2-dimensional array of "Y"-values. XCENT - X-position of gaussian centroid. YCENT - Y-position of gaussian centroid. SIGMA - sigma of the curve (X and Y widths are the same). PEAK - the peak value of the gaussian function. RETURNS: Returns the array of Y-values. 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.) z = gauss2(x, y, p) Computes the values of the Gaussian at equispaced intervals in X and Y (spacing is 0.1). The gaussian has a centroid position of (2.2, -0.7), standard deviation of 1.4, and peak value of 3000. REFERENCES: MODIFICATION HISTORY: Written, 02 Oct 1999, CM Added copyright notice, 25 Mar 2001, CM $Id: gauss2.pro,v 1.2 2001/03/25 18:55:13 craigm Exp $
(See /home/drw/idl/aux/markwardt/gauss2.pro)
NAME: GAUSS2 AUTHOR: Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770 craigm@lheamail.gsfc.nasa.gov PURPOSE: Compute Gaussian curve given the mean, sigma and area. MAJOR TOPICS: Curve and Surface Fitting CALLING SEQUENCE: YVALS = GAUSS2(X, Y, [XCENT, YCENT, SIGMA, PEAK]) DESCRIPTION: This routine computes the values of a Gaussian function whose X-values, mean, sigma, and total area are given. It is meant to be a demonstration for curve-fitting. XVALS can be an array of X-values, in which case the returned Y-values are an array as well. The second parameter to GAUSS1 should be an array containing the MEAN, SIGMA, and total AREA, in that order. INPUTS: X - 2-dimensional array of "X"-values. Y - 2-dimensional array of "Y"-values. XCENT - X-position of gaussian centroid. YCENT - Y-position of gaussian centroid. SIGMA - sigma of the curve (X and Y widths are the same). PEAK - the peak value of the gaussian function. RETURNS: Returns the array of Y-values. 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.) z = gauss2(x, y, p) Computes the values of the Gaussian at equispaced intervals in X and Y (spacing is 0.1). The gaussian has a centroid position of (2.2, -0.7), standard deviation of 1.4, and peak value of 3000. REFERENCES: MODIFICATION HISTORY: Written, 02 Oct 1999, CM Added copyright notice, 25 Mar 2001, CM $Id: gauss2.pro,v 1.2 2001/03/25 18:55:13 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/gauss2.pro)
NAME:
GAUSSFIT
PURPOSE:
Fit the equation y=f(x) where:
F(x) = A0*EXP(-z^2/2) + A3 + A4*x + A5*x^2
and
z=(x-A1)/A2
A0 = height of exp, A1 = center of exp, A2 = sigma (the width).
A3 = constant term, A4 = linear term, A5 = quadratic term.
The parameters A0, A1, A2, A3 are estimated and then CURVEFIT is
called.
CATEGORY:
?? - fitting
CALLING SEQUENCE:
Result = GAUSSFIT(X, Y [, A])
INPUTS:
X: The independent variable. X must be a vector.
Y: The dependent variable. Y must have the same number of points
as X.
OUTPUTS:
The fitted function is returned.
OPTIONAL OUTPUT PARAMETERS:
A: The coefficients of the fit. A is a six-element vector as
described under PURPOSE.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The peak or minimum of the Gaussian must be the largest
or smallest point in the Y vector.
PROCEDURE:
If the (MAX-AVG) of Y is larger than (AVG-MIN) then it is assumed
that the line is an emission line, otherwise it is assumed there
is an absorbtion line. The estimated center is the MAX or MIN
element. The height is (MAX-AVG) or (AVG-MIN) respectively.
The width is found by searching out from the extrema until
a point is found less than the 1/e value.
MODIFICATION HISTORY:
DMS, RSI, Dec, 1983.
FMW - to adjust background components and to pass A
(See /home/drw/idl/icur/gaussfit.pro)
gaussint_fit Computes least squares Gaussian integrated to the pixel size. Useful to fitting Gaussians to undersampled data. CALLING SEQUENCE: fit = gaussint_fit(x,y,a,sigma) INPUTS: x - positions of the data points) y - flux values OPTIONAL KEYWORD INPUTS: pixel_size - size of the pixels (default = 1.0) I.E. the extent of the input region integrated for each pixel. estimates - intial guess for the coefficients with NTERMS elements in same order as output A vector. If not supplied the program will generate a guess. weights - vector of weights for the input data. nterms - number of terms to fit between 3 and 6 (default = 6) nterms = 3 - no background nterms = 4 - constant background nterms = 5 - linear background nterms = 6 - quadratic background /absorption - to fit guassion with negative maximum (inverted) OUTPUTS: a - coefficients of the fit a(0) = peak of the Gaussian a(1) = center a(2) = sigma a(3) = constant term of linear background a(4) = linear term of the background a(5) = quadratic term of the background sigma - sigmas of the coefficients generated by CURVEFIT fit - fitted data values NOTES: If !debug is non-zero then the routine will generate a plot with the original data plotted as a solid histogram plot, The fitted integrated Gaussian as a dashed histogram plot, the Gaussian computed using the intial guess of the coeficients as a dotted line, the computed background as a dashed line, and the unintegrated Gaussian as a solid line. If an initial guess is not supplied, then the guess is determined by: Background guess is a polynomial fit to the first 20% and last 20% of the data points. The peak of the Gaussian is the maximum value after subtracting the background guess. The center of the Gaussian is the position of the peak data point after subtraction of the background guess. The width of the Gaussian is set to 0.5 times the range covered by The data points with a data value greater than 1/2 the peak value (after subtracting the estimated background) EXAMPLE: ; Create some test data, rebin it, add noise and fit it. xorig = findgen(100)/10.0 gauss, xorig, 5.2, 0.4, 100.0, yorig ;center=5.2, sigma=0.4, peak=100 yorig = yorig + 20.0 + 1.2*xorig ;linear baseline x = rebin(xorig,10) ;rebin to pixel size y = rebin(yorig,10) y = y + randomn(12345,10) ;add random noise fit = gaussint_fit(x,y,a) print,a HISTORY: version 1 D. Lindler Sept. 1998 July 21, 1999, Lindler, Added ABSORPTION keyword
(See /home/drw/idl/fuse/gaussint_fit.pro)
*NAME:
GAUSSX (General IDL Library 01) Aug 19, 1979
*CLASS:
numerical function
*CATEGORY:
*PURPOSE:
TO CALCULATE A GAUSSIAN FUNCTION
*CALLING SEQUENCE:
GAUSS,X,X0,DX,YMAX,Y
*PARAMETERS:
X (REQ) (I) (0 1) (I L F D)
required scalar or vector containing the independent variable(s)
X0 (REQ) (I) (0) (F D)
required scalar giving the center of the Gaussian function
This parameter must have the same units as X.
DX (REQ) (I) (0) (F D)
required scalar giving the one sigma width of the distribution
This parameter must have the same units as X.
YMAX (REQ) (I) (0) (F D)
the Gaussian value at the peak of the distribution
Y (REQ) (O) (0 1) (F D)
required output scalar or vector giving the calculated value
of the gaussian from the expression:
Y = YMAX * EXP (-0.5 * ((X-X0)/DX)^2)
*EXAMPLES:
To calculate a gaussian with center at 1545 A, sigma of 2 A, using the
wavelength scale derived from an IUE spectrum, with amplitude 1.0,
GAUSSX,WAVE,1545.,2.,1.0,Y
*SYSTEM VARIABLES USED:
*INTERACTIVE INPUT:
*SUBROUTINES CALLED:
PARCHECK
PCHECK
*FILES USED:
*SIDE EFFECTS:
*RESTRICTIONS:
*NOTES:
Values for which (X-X0)/DX > 9 are set to zero.
If DX = 0, the delta function is returned.
tested with IDL Version 2.1.0 (sunos sparc) 25 Jun 91
tested with IDL Version 2.1.0 (ultrix mispel) N/A
tested with IDL Version 2.1.0 (vms vax) 25 Jun 91
*PROCEDURE:
GAUSSX is similiar to Bevingtons program PGAUSS (p.45)
*MODIFICATION HISTORY:
Aug 19 1979 I. Ahmad initial program
Jul 7 1984 RWT GSFC updated documentation
Sep 25 1984 RWT GSFC changed limit from 12 sigma to 9 sigma due to
problems in WFIT. Also compiles PCHECK.
Apr 13 1987 RWT GSFC add PARCHECK
Aug 19 1987 RWT GSFC add procedure call listing
Mar 9 1988 CAG GSFC add VAX RDAF-style prolog
Jun 25 1991 PJL GSFC cleaned up; lowercase; tested on SUN and VAX;
updated prolog
Jan 23 1995 JKF Adapted IUE RDAF updated version(req'd for GAUSSFITS).
(See /home/drw/idl/fuse/gaussx.pro)
NAME: GAUSS_GEN PROJECT: EIS/Solar-B PURPOSE: To generate a 1-D gaussian shape which can be used as a convolution kernel SYNTAX: gofx = GAUSS_GEN(xarr, x0, width [,/normalise] [,/fwhm]) INPUTS: XARR - vector of input X values for which the gaussian Y values are required. X0 - central X co-ordinate of the gaussian kernel. WIDTH - width of the kernel (defaults to being expressed as a sigma for the gaussian shape -- i.e. the half-width at 1/SQRT(e) of the maximum (see also FWHM keyword). OPTIONAL INPUT KEYWORDS: NORMALISE - set to 1 to ensure that the are under the kernel is normalised to 1. FWHM - set to 1 to supply the width as a FWHM value, rather than a sigma value. OUTPUTS GOFX - the gaussian kernel as a vector, with values corresponding to the vector of input X values. HISTORY: DRW @ MSSL: 25/02/03 TODO a 2-D (& 3-D?) version.
(See /home/drw/idl/gen/gauss_gen.pro)
ROUTINE gengrid
USEAGE gengrid,a0,a1,a2,a3,a4
PURPOSE convert the input quantities from vectors to arrays
of dimension (nn0,nn1,nn2,nn3,nn4) where nn0=n_elements(a0),
etc.
a0(i) => a0(i,*,*,*,*) for i=0,nn0-1
a1(i) => a1(*,i,*,*,*) for i=0,nn1-1
a2(i) => a2(*,*,i,*,*) for i=0,nn2-1
a3(i) => a3(*,*,*,i,*) for i=0,nn3-1
a4(i) => a4(*,*,*,*,i) for i=0,nn4-1
INPUT:
a0 input vector or scalor array size of the first index
a1 input vector or scalor array size of the second index
a2 input vector or scalor array size of the third index
a3 input vector or scalor array size of the fourth index
a4 input vector or scalor array size of the fifth index
if one of these arguments is set to a scalor, then that
value is used to set the dimension of corresponding
array subscript
EXAMPLE:
a0=[1,2,3,4,5]
a1=[10,20,30]
gengrid,a0,a1
print,a0
1 2 3 4 5
1 2 3 4 5
1 2 3 4 5
print,a1
10 10 10 10 10
20 20 20 20 20
30 30 30 30 30
here are some other examples:
;turn a 5 element vector into a 5x6 array
x=findgen(3)
gengrid,x,6
print,x
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
;turn a 5 element vector into a 6x5 array
x=findgen(3)
gengrid,4,x
print,x
0.00000 0.00000 0.00000 0.00000
1.00000 1.00000 1.00000 1.00000
2.00000 2.00000 2.00000 2.00000
author: Paul Ricchiazzi mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/gengrid.pro)
ROUTINE gengrid
USEAGE gengrid,a0,a1,a2,a3,a4
PURPOSE convert the input quantities from vectors to arrays
of dimension (nn0,nn1,nn2,nn3,nn4) where nn0=n_elements(a0),
etc.
a0(i) => a0(i,*,*,*,*) for i=0,nn0-1
a1(i) => a1(*,i,*,*,*) for i=0,nn1-1
a2(i) => a2(*,*,i,*,*) for i=0,nn2-1
a3(i) => a3(*,*,*,i,*) for i=0,nn3-1
a4(i) => a4(*,*,*,*,i) for i=0,nn4-1
INPUT:
a0 input vector or scalor array size of the first index
a1 input vector or scalor array size of the second index
a2 input vector or scalor array size of the third index
a3 input vector or scalor array size of the fourth index
a4 input vector or scalor array size of the fifth index
if one of these arguments is set to a scalor, then that
value is used to set the dimension of corresponding
array subscript
EXAMPLE:
a0=[1,2,3,4,5]
a1=[10,20,30]
gengrid,a0,a1
print,a0
1 2 3 4 5
1 2 3 4 5
1 2 3 4 5
print,a1
10 10 10 10 10
20 20 20 20 20
30 30 30 30 30
here are some other examples:
;turn a 5 element vector into a 5x6 array
x=findgen(3)
gengrid,x,6
print,x
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
0.00000 1.00000 2.00000
;turn a 5 element vector into a 6x5 array
x=findgen(3)
gengrid,4,x
print,x
0.00000 0.00000 0.00000 0.00000
1.00000 1.00000 1.00000 1.00000
2.00000 2.00000 2.00000 2.00000
author: Paul Ricchiazzi mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/gengrid.pro)
ROUTINE: GEN_COASTLINE
USEAGE: gen_coastline
gen_coastline,alat,alon,file=file,image=image
PURPOSE: generate coastal outline map for satellite images
INPUTS: ALAT 2-D array of image latitude values (one value for
each image pixel)
ALON 2-D array of image longitude values
if ALON and ALAT are not provided,
GEN_COASTLINE assumes a linear mapping of lat
and lon to the current x and y ploting range.
FILE Name of map coordinate data file. If FILE is
not provided, GEN_COASTLINE queries for an
output file name. FILE is written in portable
XDR binary format which can be read by the
companion procedure COASTLINE.
OPTIONAL KEYWORD INPUT:
image Image from which to infer coastal outline.
If an image array is not provided, it is assumed
that an image has already been displayed using
the TVIM procedure.
SIDE EFFECT: writes map file in current working directory
PROCEDURE:
Before entering input mode the following pop-up menu appears,
1. DEFINE AN OPEN CURVE Start a new coastal outline segment
2. DEFINE A CLOSED CURVE Start an island outline segment
3. QUIT Flush buffers and quit.
After option 1 or 2 is selected, coastline coordinates are input by
using the mouse to click on coastal features from an image in the
default window. The mouse buttons perform the following actions:
LMB: left mouse button connects points along coastline
MMB: middle mouse erases most recent point(s)
RMB: right mouse button finishes a coastline segment.
If a coastal outline is intended to represent an island (option 2),
pressing the RMB causes the last point on the curve to be connected
to the first.
The collection of [latitude, longitude] coordinates are written to the
file FILE. This map data file can be used as input for the companion
procedure, COASTLINE.PRO which plots the coast line data onto arbitrarily
oriented image files.
EXAMPLE:
x=findgen(128)
y=findgen(128)
gengrid,x,y
d=randata(128,128,s=4)
d=d gt 3
gen_coastline,y,x,file='junk.dat',image=d
coastline,file='junk.dat',/view
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS
29oct92: accomodate TRACE revision of 29oct92
(See /home/drw/idl/esrg/gen_coastline.pro)
ROUTINE: GEN_COASTLINE
USEAGE: gen_coastline
gen_coastline,alat,alon,file=file,image=image
PURPOSE: generate coastal outline map for satellite images
INPUTS: ALAT 2-D array of image latitude values (one value for
each image pixel)
ALON 2-D array of image longitude values
if ALON and ALAT are not provided,
GEN_COASTLINE assumes a linear mapping of lat
and lon to the current x and y ploting range.
FILE Name of map coordinate data file. If FILE is
not provided, GEN_COASTLINE queries for an
output file name. FILE is written in portable
XDR binary format which can be read by the
companion procedure COASTLINE.
OPTIONAL KEYWORD INPUT:
image Image from which to infer coastal outline.
If an image array is not provided, it is assumed
that an image has already been displayed using
the TVIM procedure.
SIDE EFFECT: writes map file in current working directory
PROCEDURE:
Before entering input mode the following pop-up menu appears,
1. DEFINE AN OPEN CURVE Start a new coastal outline segment
2. DEFINE A CLOSED CURVE Start an island outline segment
3. QUIT Flush buffers and quit.
After option 1 or 2 is selected, coastline coordinates are input by
using the mouse to click on coastal features from an image in the
default window. The mouse buttons perform the following actions:
LMB: left mouse button connects points along coastline
MMB: middle mouse erases most recent point(s)
RMB: right mouse button finishes a coastline segment.
If a coastal outline is intended to represent an island (option 2),
pressing the RMB causes the last point on the curve to be connected
to the first.
The collection of [latitude, longitude] coordinates are written to the
file FILE. This map data file can be used as input for the companion
procedure, COASTLINE.PRO which plots the coast line data onto arbitrarily
oriented image files.
EXAMPLE:
x=findgen(128)
y=findgen(128)
gengrid,x,y
d=randata(128,128,s=4)
d=d gt 3
gen_coastline,y,x,file='junk.dat',image=d
coastline,file='junk.dat',/view
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS
29oct92: accomodate TRACE revision of 29oct92
(See /home/drw/idl/old.esrg/gen_coastline.pro)
NAME:
GETCOLOR
PURPOSE:
The original purpose of this function was to enable the
user to specify one of the 16 colors supported by the
McIDAS color map by name. Over time, however, the function
has become a general purpose function for handling and
supporting drawing colors in a device-independent way.
In particular, I have been looking for ways to write color
handling code that will work transparently on both 8-bit and
24-bit machines. On 24-bit machines, the code should work the
same where color decomposition is turned on or off. The program
now supports 88 colors.
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:
result = GETCOLOR(color, index)
OPTIONAL INPUT PARAMETERS:
COLOR: A string with the "name" of the color. Valid names are:
black
magenta
cyan
yellow
green
red
blue
navy
pink
aqua
orchid
sky
beige
charcoal
gray
white
The color YELLOW is returned if the color name can't be resolved.
Case is unimportant.
If the function is called with just this single input parameter,
the return value is either a 1-by-3 array containing the RGB values of
that particular color, or a 24-bit integer that can be "decomposed" into
that particular color, depending upon the state of the TRUE keyword and
upon whether color decomposition is turned on or off. The state of color
decomposition can ONLY be determined if the program is being run in
IDL 5.2 or higher.
INDEX: The color table index where the specified color should be loaded.
If this parameter is passed, then the return value of the function is the
index number and not the color triple. (If color decomposition is turned
on AND the user specifies an index parameter, the color is loaded in the
color table at the proper index, but a 24-bit value is returned to the
user in IDL 5.2 and higher. This assumes the INDEXED keyword is NOT set.)
If no positional parameter is present, then the return value is either a 16-by-3
byte array containing the RGB values of all 16 colors or it is a 16-element
long integer array containing color values that can be decomposed into colors.
The 16-by-3 array is appropriate for loading color tables with the TVLCT command:
Device, Decomposed=0
colors = GetColor()
TVLCT, colors, 100
INPUT KEYWORD PARAMETERS:
NAMES: If this keyword is set, the return value of the function is
a 16-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)
INDEXED: If this keyword is set, the return value is always an index
into the color table. In the absence of a color table INDEX
parameter, the color is loaded at !P.COLOR < (!D.Table_Size-1).
LOAD: If this keyword is set, all 16 colors are automatically loaded
starting at the color index specified by the START keyword.
Note that setting this keyword means that the return value of the
function will be a structure, with each field of the structure
corresponding to a color name. The value of each field will be
an index number (set by the START keyword) corresponding to the
associated color, or a 24-bit long integer value that creates the
color on a true-color device. What you have as the field values is
determined by the TRUE keyword or whether color decomposition is on
or off in the absense of the TRUE keyword. It will either be a 1-by-3
byte array or a long integer value.
START: The starting color index number if the LOAD keyword is set. This keyword
value is ignored unless the LOAD keyword is also set. The keyword is also
ignored if the TRUE keyword is set or if color decomposition in on in
IDL 5.2 and higher. The default value for the START keyword is
!D.TABLE_SIZE - 17.
TRUE: If this keyword is set, the specified color triple is returned
as a 24-bit integer equivalent. The lowest 8 bits correspond to
the red value; the middle 8 bits to the green value; and the
highest 8 bits correspond to the blue value. In IDL 5.2 and higher,
if color decomposition is turned on, it is as though this keyword
were set.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
The TRUE keyword causes the START keyword to be ignored.
The NAMES keyword causes the COLOR, INDEX, START, and TRUE parameters to be ignored.
The COLOR parameter is ignored if the LOAD keyword is used.
On systems where it is possible to tell the state of color decomposition
(i.e., IDL 5.2 and higher), a 24-bit value (or values) is automatically
returned if color decomposition is ON.
EXAMPLE:
To load a yellow color in color index 100 and plot in yellow, type:
yellow = GETCOLOR('yellow', 100)
PLOT, data, COLOR=yellow
or,
PLOT, data, COLOR=GETCOLOR('yellow', 100)
To do the same thing on a 24-bit color system with decomposed color on, type:
PLOT, data, COLOR=GETCOLOR('yellow', /TRUE)
or in IDL 5.2 and higher,
DEVICE, Decomposed=1
PLOT, data, COLOR=GETCOLOR('yellow')
To load all 16 colors into the current color table, starting at
color index 200, type:
TVLCT, GETCOLOR(), 200
To add the color names to a list widget:
listID = Widget_List(baseID, Value=GetColor(/Names), YSize=16)
To load all 16 colors and have the color indices returned in a structure:
DEVICE, Decomposed=0
colors = GetColor(/Load, Start=1)
HELP, colors, /Structure
PLOT, data, COLOR=colors.yellow
To get the direct color values as 24-bit integers in color structure fields:
DEVICE, Decomposed=1
colors = GetColor(/Load)
PLOT, data, COLOR=colors.yellow
Note that the START keyword value is ignored if on a 24-bit device,
so it is possible to write completely device-independent code by
writing code like this:
colors = GetColor(/Load)
PLOT, data, Color=colors.yellow
MODIFICATION HISTORY:
Written by: David Fanning, 10 February 96.
Fixed a bug in which N_ELEMENTS was spelled wrong. 7 Dec 96. DWF
Added the McIDAS colors to the program. 24 Feb 99. DWF
Added the INDEX parameter to the program 8 Mar 99. DWF
Added the NAMES keyword at insistence of Martin Schultz. 10 Mar 99. DWF
Reorderd the colors so black is first and white is last. 7 June 99. DWF
Added automatic recognition of DECOMPOSED=1 state. 7 June 99. DWF
Added LOAD AND START keywords. 7 June 99. DWF.
Replaced GOLD with CHARCOAL color. 28 Oct 99. DWF.
Added INDEXED keyword to force indexed color mode. 28 Oct 99. DWF.
Fixed problem of "aqua" and "pink" being mixed up. 18 Mar 00. DWF.
Changed ON_ERROR from 1 to 2, and improved error handling. 2 Aug 00. DWF.
Increased the known colors from 16 to 88. 19 October 2000. DWF.
(See /home/drw/idl/aux/getcolor.pro)
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:
Widgets, File I/O.
CALLING SEQUENCE:
image = GETIMAGE(filename)
OPTIONAL INPUTS:
filename: The name of the file to open for reading.
OPTIONAL 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.
CATCH: Set this keyword to 0 if you wish to turn error catching OFF.
DIRECTORY: The name of the directory the file is located in. By
default the program looks in the "coyote" 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 in order
to make this program a MODAL 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.
Added COYOTE_FIELD, improved appearance. 19 NOV 99. DWF.
Updated with latest version of COYOTE_FIELD. 18 FEB 2000. DWF.
Added CATCH keyword so the program will break when I want
it to. :-) 18 MAR 2000. DWF.
Added GROUP_LEADER keyword, which is synonymous with PARENT. 31 MAR 2000. DWF.
(See /home/drw/idl/aux/getimage.pro)
ROUTINE: getnamelist
PURPOSE: grab values from a namelist input file
USEAGE: getnamelist,file,name,value
INPUT:
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 14 Aug 00
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/getnamelist.pro)
PROJECT:
CHROMOSPHERIC OSCILLATIONS, QUB
NAME:
GETSTUFF
PURPOSE:
To provide the pixel indices contained only within the contour
around the maximum intensity. This is designed to grab only
spatially coherent network bright points, and not the little
blips which may appear around from random fluctuations.
USAGE:
result=getstuff(image,threshold,imagemax=imagemax,quiet=quiet)
The function is normally called by JMA's "RATIOLC"
INPUTS:
IMAGE - the input image in which you want to draw contours (2D array)
THRESH - the level of the contours (FLOAT or INTEGER),in terms of pixel value
KEYWORD INPUTS:
IMAGEMAX - a cheat, to change WHERE(image eq MAX(image)) to the
pixel index you want. Most useful for ignoring a maximum that
occurs too far away from the maximum in the previous image.
OUTPUTS:
RESULT - the list of pixel indices (a flag array) which correspond
to points in IMAGE which are inside the contour surrounding
the maximum pixel value.
TO DO:
Make the function more bulletproof by:
a) accounting for times when not every Y value contains
two contour co-ordinates;
b) coping with the situation where the two pixels in the
image have the maximum pixel value.
c) discounting pixels below the threshold in U or n shaped contours
since the X-range doesn't take account of this (use a WHERE flag)
d) don't let the point with the maximum pixel value wander too far
from where it was in the last image
KNOWN BUGS:
This is really more to do with CONTOUR, which we can't hack directly.
There's a problem with the /CLOSE keyword to CONTOUR, which means
that it doesn't always close the contour, so GETSTUFF crashed out as it cannot find the start and end
x points to run the loop.
HISTORY:
v1.0 - Written by David Williams & James McAteer, QUB (30/10/01) after
much blood, sweat & tears....
v1.1 - JMA added IMAGEMAX keyword for RATIOLC usability (31/10/01)
v1.2 - DRW added QUIET keyword to shut the thing up during looped
use (2/11/01).
v1.3 - JMA added ability to return value of -1 if the contours can't be
drawn, OR if the threshold is too large. Stops the programme from
bombing out (5/11/01).
v1.4 - JMA added in loop to return valur of -1 and explain why: when the threshold
is too large the previous addition (v1.3) was confusing.
Also added added in a loop (line 178) which corrects
for the fact that every value of y between mny and mxy may not be taken
(See /home/drw/idl/vtt/post_bbso/getstuff.pro)
PROJECT: CHROMOSPHERIC OSCILLATIONS, QUB NAME: GETSTUFF PURPOSE: To provide the pixel indices contained only within the contour around the maximum intensity. This is designed to grab only spatially coherent network bright points, and not the little blips which may appear around from random fluctuations.
(See /home/drw/idl/vtt/post_bbso/getstuff.old.pro)
PROJECT:
CHROMOSPHERIC OSCILLATIONS, QUB
NAME:
GETSTUFF
PURPOSE:
To provide the pixel indices contained only within the contour
around the maximum intensity. This is designed to grab only
spatially coherent network bright points, and not the little
blips which may appear around from random fluctuations.
USAGE:
result=getstuff(image,threshold,imagemax=imagemax,quiet=quiet)
The function is normally called by JMA's "RATIOLC"
INPUTS:
IMAGE - the input image in which you want to draw contours (2D array)
THRESH - the level of the contours (FLOAT or INTEGER),in terms of pixel value
KEYWORD INPUTS:
IMAGEMAX - a cheat, to change WHERE(image eq MAX(image)) to the
pixel index you want. Most useful for ignoring a maximum that
occurs too far away from the maximum in the previous image.
OUTPUTS:
RESULT - the list of pixel indices (a flag array) which correspond
to points in IMAGE which are inside the contour surrounding
the maximum pixel value.
TO DO:
Make the function more bulletproof by:
a) accounting for times when not every Y value contains
two contour co-ordinates;
b) coping with the situation where the two pixels in the
image have the maximum pixel value.
c) discounting pixels below the threshold in U or n shaped contours
since the X-range doesn't take account of this (use a WHERE flag)
d) don't let the point with the maximum pixel value wander too far
from where it was in the last image
KNOWN BUGS:
This is really more to do with CONTOUR, which we can't hack directly.
There's a problem with the /CLOSE keyword to CONTOUR, which means
that it doesn't always close the contour, so GETSTUFF
HISTORY:
v1.0 - Written by David Williams & James McAteer, QUB (30/10/01) after
much blood, sweat & tears....
v1.1 - JMA added IMAGEMAX keyword for RATIOLC usability (31/10/01)
v1.2 - DRW added QUIET keyword to shut the thing up during looped
use (2/11/01).
v1.3 - JMA added ability to return value of -1 if the contours can't be
drawn, OR if the threshold is too large. Stops the programme from
bombing out (5/11/01).
v1.4 - JMA added in loop to return valur of -1 and explain why: when the threshold is too large
the previous addition (v1.3) was confusing. Also added added in a loop (line 178) which corrects
for the fact that every value of y between mny and mxy may not be taken
getstuff2, a variation on getstuff which looks for minimum value of image, to be used when the
image is taken in a wavelength is in absorbtion.
(See /home/drw/idl/vtt/post_bbso/getstuff2.pro)
PROJECT:
CHROMOSPHERIC OSCILLATIONS, QUB
NAME:
GETSTUFF
PURPOSE:
To provide the pixel indices contained only within the contour
around the maximum intensity. This is designed to grab only
spatially coherent network bright points, and not the little
blips which may appear around from random fluctuations.
USAGE:
result=getstuff(image,threshold,imagemax=imagemax,quiet=quiet)
The function is normally called by JMA's "RATIOLC"
INPUTS:
IMAGE - the input image in which you want to draw contours (2D array)
THRESH - the level of the contours (FLOAT or INTEGER),in terms of pixel value
KEYWORD INPUTS:
IMAGEMAX - a cheat, to change WHERE(image eq MAX(image)) to the
pixel index you want. Most useful for ignoring a maximum that
occurs too far away from the maximum in the previous image.
OUTPUTS:
RESULT - the list of pixel indices (a flag array) which correspond
to points in IMAGE which are inside the contour surrounding
the maximum pixel value.
TO DO:
Make the function more bulletproof by:
a) accounting for times when not every Y value contains
two contour co-ordinates;
b) coping with the situation where the two pixels in the
image have the maximum pixel value.
c) discounting pixels below the threshold in U or n shaped contours
since the X-range doesn't take account of this (use a WHERE flag)
d) don't let the point with the maximum pixel value wander too far
from where it was in the last image
KNOWN BUGS:
This is really more to do with CONTOUR, which we can't hack directly.
There's a problem with the /CLOSE keyword to CONTOUR, which means
that it doesn't always close the contour, so GETSTUFF crashed out as it cannot find the start and end
x points to run the loop.
HISTORY:
v1.0 - Written by David Williams & James McAteer, QUB (30/10/01) after
much blood, sweat & tears....
v1.1 - JMA added IMAGEMAX keyword for RATIOLC usability (31/10/01)
v1.2 - DRW added QUIET keyword to shut the thing up during looped
use (2/11/01).
v1.3 - JMA added ability to return value of -1 if the contours can't be
drawn, OR if the threshold is too large. Stops the programme from
bombing out (5/11/01).
v1.4 - JMA added in loop to return valur of -1 and explain why: when the threshold
is too large the previous addition (v1.3) was confusing.
Also added added in a loop (line 178) which corrects
for the fact that every value of y between mny and mxy may not be taken
(See /home/drw/idl/jma/getstuff.pro)
PROJECT:
CHROMOSPHERIC OSCILLATIONS, QUB
NAME:
GETSTUFF
PURPOSE:
To provide the pixel indices contained only within the contour
around the maximum intensity. This is designed to grab only
spatially coherent network bright points, and not the little
blips which may appear around from random fluctuations.
USAGE:
result=getstuff(image,threshold,imagemax=imagemax,quiet=quiet)
The function is normally called by JMA's "RATIOLC"
INPUTS:
IMAGE - the input image in which you want to draw contours (2D array)
THRESH - the level of the contours (FLOAT or INTEGER),in terms of pixel value
KEYWORD INPUTS:
IMAGEMAX - a cheat, to change WHERE(image eq MAX(image)) to the
pixel index you want. Most useful for ignoring a maximum that
occurs too far away from the maximum in the previous image.
OUTPUTS:
RESULT - the list of pixel indices (a flag array) which correspond
to points in IMAGE which are inside the contour surrounding
the maximum pixel value.
TO DO:
Make the function more bulletproof by:
a) accounting for times when not every Y value contains
two contour co-ordinates;
b) coping with the situation where the two pixels in the
image have the maximum pixel value.
c) discounting pixels below the threshold in U or n shaped contours
since the X-range doesn't take account of this (use a WHERE flag)
d) don't let the point with the maximum pixel value wander too far
from where it was in the last image
KNOWN BUGS:
This is really more to do with CONTOUR, which we can't hack directly.
There's a problem with the /CLOSE keyword to CONTOUR, which means
that it doesn't always close the contour, so GETSTUFF
HISTORY:
v1.0 - Written by David Williams & James McAteer, QUB (30/10/01) after
much blood, sweat & tears....
v1.1 - JMA added IMAGEMAX keyword for RATIOLC usability (31/10/01)
v1.2 - DRW added QUIET keyword to shut the thing up during looped
use (2/11/01).
v1.3 - JMA added ability to return value of -1 if the contours can't be
drawn, OR if the threshold is too large. Stops the programme from
bombing out (5/11/01).
v1.4 - JMA added in loop to return valur of -1 and explain why: when the threshold is too large
the previous addition (v1.3) was confusing. Also added added in a loop (line 178) which corrects
for the fact that every value of y between mny and mxy may not be taken
getstuff2, a variation on getstuff which looks for minimum value of image, to be used when the
image is taken in a wavelength is in absorbtion.
(See /home/drw/idl/jma/getstuff2.pro)
PROJECT: CHROMOSPHERIC OSCILLATIONS, QUB NAME: GETSTUFF PURPOSE: To provide the pixel indices contained only within the contour around the maximum intensity. This is designed to grab only spatially coherent network bright points, and not the little blips which may appear around from random fluctuations.
(See /home/drw/idl/gen/getstuff0.pro)
PROJECT:
CHROMOSPHERIC OSCILLATIONS, QUB
NAME:
GETSTUFF
PURPOSE:
To provide the pixel indices contained only within the contour
around the maximum intensity. This is designed to grab only
spatially coherent network bright points, and not the little
blips which may appear around from random fluctuations.
USAGE:
RESULT = GETSTUFF(IMAGE,THRESHOLD,quiet=quiet,nodisp=nodisp,lim=lim)
The function is normally called by JMA's "RATIOLC"
INPUTS:
IMAGE - the input image in which you want to draw contours (2D array)
THRESH - the level of the contours (FLOAT or INTEGER)
KEYWORD INPUTS:
QUIET - prevents messages being echoed to the terminal
LIM - (see below)
NODISP - prevents display of the image and its numbered contours
(therefore speeds things up, and causes less epilepsy)
OUTPUTS:
RESULT - the list of pixel indices (a flag array) which correspond
to points in IMAGE which are inside the contour surrounding
the maximum pixel value, and within LIM pixels of the
TO DO:
Make the function more bulletproof by:
a) accounting for times when not every Y value contains
two contour co-ordinates;
b) coping with the situation where the two pixels in the
image have the maximum pixel value.
c) discounting pixels below the threshold in U or n shaped contours
since the X-range doesn't take account of this (use a WHERE flag)
d) don't let the point with the maximum pixel value wander too far
from where it was in the last image
KNOWN BUGS:
This is really more to do with CONTOUR, which we can't hack directly.
There's a problem with the /CLOSE keyword to CONTOUR, which means
that it doesn't always close the contour, so GETSTUFF
HISTORY:
v1.0 - Written by David Williams & James McAteer, QUB (30/10/01) after
much blood, sweat & tears....
v1.1 - JMA added IMAGEMAX keyword for RATIOLC usability (31/10/01)
v1.2 - DRW added QUIET keyword to shut the thing up during looped
use (2/11/01)
v2.0 - Much shennanigans in trying to get around the problem of
rogue bright points outshining the bright point we want to monitor,
so now it takes the bright point's location as being the brightest
point within LIM pixels of the image centre, where LIM is the limit
of how far the bright point can wander.
ALSO: 1) JMA removed IMAGEMAX keyword because of this
2) DRW added in NODISP keyword to speed things up
by not displaying the image and its numbered contours
3) and a LIM keyword to set the range over which the point
can wander
A very long Friday afternoon.... (2/11/01)
(See /home/drw/idl/gen/getstuff1.pro)
PROJECT:
CHROMOSPHERIC OSCILLATIONS, QUB
NAME:
GETSTUFF
PURPOSE:
To provide the pixel indices contained only within the contour
around the maximum intensity. This is designed to grab only
spatially coherent network bright points, and not the little
blips which may appear around from random fluctuations.
USAGE:
result=getstuff(image,threshold,imagemax=imagemax,quiet=quiet)
The function is normally called by JMA's "RATIOLC"
INPUTS:
IMAGE - the input image in which you want to draw contours (2D array)
THRESH - the level of the contours (FLOAT or INTEGER)
KEYWORD INPUTS:
IMAGEMAX - a cheat, to change WHERE(image eq MAX(image)) to the
pixel index you want. Most useful for ignoring a maximum that
occurs too far away from the maximum in the previous image.
OUTPUTS:
RESULT - the list of pixel indices (a flag array) which correspond
to points in IMAGE which are inside the contour surrounding
the maximum pixel value.
TO DO:
Make the function more bulletproof by:
a) accounting for times when not every Y value contains
two contour co-ordinates;
b) coping with the situation where the two pixels in the
image have the maximum pixel value.
c) discounting pixels below the threshold in U or n shaped contours
since the X-range doesn't take account of this (use a WHERE flag)
d) don't let the point with the maximum pixel value wander too far
from where it was in the last image
KNOWN BUGS:
This is really more to do with CONTOUR, which we can't hack directly.
There's a problem with the /CLOSE keyword to CONTOUR, which means
that it doesn't always close the contour, so GETSTUFF
HISTORY:
v1.0 - Written by David Williams & James McAteer, QUB (30/10/01) after
much blood, sweat & tears....
v1.1 - JMA added IMAGEMAX keyword for RATIOLC usability (31/10/01)
v1.2 - DRW added QUIET keyword to shut the thing up during looped
use (2/11/01).
v1.3 - JMA added ability to return value of -1 if the contours can't be
drawn, or if the threshold is too large. Stops the programme from
bombing out (5/11/01).
(See /home/drw/idl/gen/getstuff2.pro)
PROJECT:
GENERIC
NAME:
GETWEEK
PURPOSE:
obtain the current week of the year, using a
SPAWN to the UNIX `date` command.
USAGE:
result = getweek()
INPUTS:
None necessary, but if a date is supplied in an ANYTIM-
compatible format, it will be translated into the week
of the year given.
OPTIONAL KEYWORDS:
FULL - set this switch to return the year, followed by
an underscore, followed by the week number, i.e.
'1998_27' in the fourth example below.
EXAMPLE:
print,getweek()
result = getweek()
result = getweek('21-Jul-02')
result = getweek('1998-077-04T18:09:03.000',/full)
CALLS: ANYTIME2WEEKINFO
HISTORY:
v1.0: Dave Williams (drw@mssl.ucl.ac.uk), 8-Jul-2002
v1.1: DRW - added ability to insert an optional date
of your choosing, rather than today`s date
v1.2: DRW - added FULL keyword.
(See /home/drw/idl/gen/getweek.pro)
based on az_sa.pro, but written again to make things a bit clearer just for myself
(See /home/drw/idl/secis/get_emission.pro)
NAME:
get_template_one_value
PURPOSE:
The result of this function is a string with template information
CATEGORY:
CASE_TOOLS
CALLING SEQUENCE:
result=get_template_one_value(file_name,attribute,[/declaration])
INPUTS:
file_name: the name of the idl source file
attribute: the attribute of the template to read
KEYWORD PARAMETERS:
declaration: the attribute to add to the output string
translate_description_to_purpose: some external authors are using DESCRIPTION: instead of PURPOSE:.
if this key is set DESCRIPTION: is translated to PURPOSE:
translate_routine_to_name: some external authors are using ROUTINE: instead of NAME:.
if this key is set ROUTINE: is translated to NAME:
OUTPUTS:
result: the readed template information behind the attribute
EXAMPLE:
print,get_template_one_value('get_template_one_value','CALLING SEQUENCE')
result=get_template_one_value(file_name,attribute,[/declaration])
MODIFICATION HISTORY:
Written by R.Bauer (ICG-1), 1998-Aug-30
1998-Oct-26 mistake removed for using the last declaration before ; -
1999-Nov-6 a bit smaller now
embedded bytes2strarr,arr2string,filesize
2000-Jan-23 : attribute could be an array now
2000-Feb-08 : translate_description_to_purpose and translate_routine_to_name added
2000-Feb-25 : def_strings implemented, free search of : disabled
2000-Apr-04 : file_name could be an array now
(See /home/drw/idl/icglib/pro/get_template_one_value.pro)
NAME:
ghostview
PURPOSE:
Call ghostview to view a file.
CALLING SEQUENCE:
gv ;Prompt for filename
gv, File
INPUTS:
File = Name of file to view
OUTPUTS:
None.
COMMON BLOCKS:
LASTFILE -- Contains the single variable FILENAME.
same common block is used for filename in notepad.pro and edit.pro
PROCEDURE:
spawn is used to call ghostview.
MODIFICATION HISTORY:
Written by P. T. Gallagher, QUB, Dec., '97
(See /home/drw/idl/bin/gv.pro)
NAME:
ghostview
PURPOSE:
Call ghostview to view a file.
CALLING SEQUENCE:
gv ;Prompt for filename
gv, File
INPUTS:
File = Name of file to view
OUTPUTS:
None.
COMMON BLOCKS:
LASTFILE -- Contains the single variable FILENAME.
same common block is used for filename in notepad.pro and edit.pro
PROCEDURE:
spawn is used to call ghostview.
MODIFICATION HISTORY:
Written by P. T. Gallagher, QUB, Dec., '97
(See /home/drw/idl/bin/ptg/gv.pro)
ROUTINE: gif_read
PURPOSE: copy image on current window to a gif image file
USEAGE: gif_read,file
INPUT:
file gif file name
KEYWORD INPUT:
view if set display the image
OUTPUT:
im image array
r,g,b color vectors
SIDE EFFECTS: if VIEW is set, the color table is altered to match the
RGB settings read from the file
EXAMPLE:
loadct,5
window,0
tvim,sin(hanning(200,200))
gif_write,'test_image.gif'
wdelete,0
gif_read,'test_image.gif',/view
author: Paul Ricchiazzi feb94
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/esrg/gif_read.pro)
ROUTINE: gif_write
PURPOSE: create a gif image file from an image appearing in the
currently selected idl graphics window.
USEAGE: gif_write,file
INPUT:
file name of output gif file
EXAMPLE:
loadct,5
window,0
tvim,sin(20*hanning(200,200)*dist(200)),title='GIF test image',/sc
gif_write,'test_image.gif'
xv test_image.gif
DISCUSSION:
gif_write reads the image from the currently selected
graphics window using tvrd(). Note that this copying
operation will produce incorrect results if the selected
window is obscurred by other windows. The image data along
with the current color table is written to the named file
using write_gif.
NOTE: the procedure PICKC is useful for touching up the
color table before creating the output file.
author: Paul Ricchiazzi feb94
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/esrg/gif_write.pro)
ROUTINE globe_image
AUTHOR: Terry Figel, ESRG, UCSB 10-21-92
USEAGE: globe_image,image
globe_image,image,animation,title=title,limits=limits,$
windowsize=windowsize
PURPOSE: Display an image on a rotating globe
INPUT input image quantity
Optional keyword input:
title plot title
windowsize Controls the size of the window, Directly responsible
for memory usage
limits 4 item array [min lat,min lon,max lat,max lon] of
input image, if omitted presumed global
coverage [-90,0,90,360]
whole treats image as whole world for map_image
SIDE EFFECTS: Uses a LOT of MEMORY ~30-50 MEGS, takes a few minutes
to set up animation
If windowsize left at 300 approx 13 megs used on DEC
PROCEDURE GLOBE_IMAGE first map an image to a globe
Then it saves the image, rotates 10 degrees and repeats
Then it animates the saved images
LOCAL PROCEDURES: None
(See /home/drw/idl/esrg/globe_image2.pro)
ROUTINE globe_image
AUTHOR: Terry Figel, ESRG, UCSB 10-21-92
USEAGE: globe_image,image
globe_image,image,animation,title=title,limits=limits,$
windowsize=windowsize
PURPOSE: Display an image on a rotating globe
INPUT input image quantity
Optional keyword input:
title plot title
windowsize Controls the size of the window, Directly responsible
for memory usage
limits 4 item array [min lat,min lon,max lat,max lon] of
input image, if omitted presumed global
coverage [-90,0,90,360]
whole treats image as whole world for map_image
SIDE EFFECTS: Uses a LOT of MEMORY ~30-50 MEGS, takes a few minutes
to set up animation
If windowsize left at 300 approx 13 megs used on DEC
PROCEDURE GLOBE_IMAGE first map an image to a globe
Then it saves the image, rotates 10 degrees and repeats
Then it animates the saved images
LOCAL PROCEDURES: None
(See /home/drw/idl/old.esrg/globe_image2.pro)
ROUTINE globe_image
AUTHOR: Terry Figel, ESRG, UCSB 10-21-92
USEAGE: globe_image,image
globe_image,image,animation,title=title,limits=limits,$
windowsize=windowsize
PURPOSE: Display an image on a rotating globe
INPUT input image quantity
OUTPUT output 3d array containg output images for animation
Optional keyword input:
title plot title
windowsize Controls the size of the window, Directly responsible
for memory usage
limits 4 item array [min lat,min lon,max lat,max lon] of
input image, if omitted presumed global
coverage [-90,0,90,360]
whole treats image as whole world for map_image
SIDE EFFECTS: Uses a LOT of MEMORY ~30-50 MEGS, takes a few minutes
to set up animation
If windowsize left at 300 approx 13 megs used on DEC
PROCEDURE GLOBE_IMAGE first map an image to a globe
Then it saves the image, rotates 10 degrees and repeats
Then it animates the saved images
LOCAL PROCEDURES: None
(See /home/drw/idl/esrg/globe_image.pro)
ROUTINE globe_image
AUTHOR: Terry Figel, ESRG, UCSB 10-21-92
USEAGE: globe_image,image
globe_image,image,animation,title=title,limits=limits,$
windowsize=windowsize
PURPOSE: Display an image on a rotating globe
INPUT input image quantity
OUTPUT output 3d array containg output images for animation
Optional keyword input:
title plot title
windowsize Controls the size of the window, Directly responsible
for memory usage
limits 4 item array [min lat,min lon,max lat,max lon] of
input image, if omitted presumed global
coverage [-90,0,90,360]
whole treats image as whole world for map_image
SIDE EFFECTS: Uses a LOT of MEMORY ~30-50 MEGS, takes a few minutes
to set up animation
If windowsize left at 300 approx 13 megs used on DEC
PROCEDURE GLOBE_IMAGE first map an image to a globe
Then it saves the image, rotates 10 degrees and repeats
Then it animates the saved images
LOCAL PROCEDURES: None
(See /home/drw/idl/old.esrg/globe_image.pro)
*NAME:
GMEDIAN (General IDL Library 01) May 20, 1980
*CLASS:
Smoothing
*CATEGORY:
*PURPOSE:
To perform a median filter on an one-dimensional array. The type of the
array is not converted to BYTE (as in the IDL MEDIAN), but is left the
same as the input type.
*CALLING SEQUENCE:
GMEDIAN,IN,M,OUT
*PARAMETERS:
IN (REQ) (I) (1) (I L F D)
Required input vector containing the data which are to be filtered.
If OUT is omitted from the calling sequence, the filtered data are
returned in IN.
M (REQ) (I) (0) (I)
Length of the median filter
OUT (OPT) (O) (1) (I L F D)
Output median-filtered vector.
*EXAMPLE:
To median filter a data vector BKG:
GMEDIAN,BKG,63,FBKG ;63 point filter
*SYSTEM VARIABLES USED:
None.
*INTERACTIVE INPUT:
None.
*SUBROUTINES CALLED:
PARCHECK
*FILES USED:
IUER_USERDATA:GMEDIAN.TMP -temporary scratch data set
*SIDE EFFECTS:
You may not execute this procedure from two or more simultaneous
sessions in your account. There will be conflicts over the .TMP
file.
*RESTRICTIONS:
None
*NOTES:
Fortran Task IUER_SOFTDISK:[IUERDAF.PRODUCTION]GMEDIAN.EXE is
called to do the median filter.
The fortran task forces the filter with to be odd.
Widths less than 2 result in no filtering.
The data array is truncated to 4096 points in length.
The first and last M/2 points are copied from the
input to the output arrays with no filtering.
*PROCEDURE:
The length of the filter and the input array are copied
to a temporary file GMEDIAN.TMP and the task GMEDIAN.EXE
called.
For I = M/2 to N - M/2 - 1 where N is the length
of IN the median is computed by:
OUT(I) = Median value of (IN(J),J=I-M/2 to I+M/2)
Points for I=0, M/2 - 1 and I=N-M/2,N OUT(I) = IN(I)
The fortran task writes the sizes and the filtered results
to the file GMEDIAN.TMP and exits with a stop.
The procedure reads the lengths and the filtered results.
If errors arose, a message is output.
*MODIFICATION HISTORY:
Jul 31 1980 D. Lindler initial version
Sep 13 1982 FHS3 GSFC CR#047 increase vector sizes to 4096 points.
Apr 15 1985 RWT GSFC name changed to GMEDIAN to make routine
compatible with XIDL.
Jun 8 1987 RWT GSFC add PARCHECK, use N_ELEMENTS, and make OUT
optional.
Jun 22 1987 RWT GSFC fix error with N not being defined
Mar 10 1988 CAG GSFC add VAX RDAF-style prolog, and print
statement if the procedure is executed
without parameters.
(See /home/drw/idl/icur/gmedian.pro)
ROUTINE: gray
PURPOSE: provide a nicely distributed color table index for
line plot colors, works best for the standard gray scale
color table, since direction of color variation is reversed
when output goes to postscript device.
USEAGE: gray,n,i,minclr=minclr
INPUT:
n total number of colors
i index of a chosen color, i=0,1,2 ... n-1,
if not supplied a vector of all colors [i=indgen(n)] is returned
KEYWORD INPUT:
minclr fraction of total color range not used, for example if minclr
is .1 then the darkest 1/10 of the color table indices are not
used, i.e., 0-25 not used for a 0-255 table. default=.3
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
;;
loadct,0
x=indgen(20) & y=fltarr(20,4)
y[*,0]=x & y[*,1]=.9*x & y[*,2]=.8*x & y[*,3]=.7*x
plot,x,y[*,0],/nodata
for j=0,3 do oplot,x,y[*,j],color=gray(4,j)
legend,'y1\y2\y3\y4',spos='tl',color=gray(4)
;;
AUTHOR: Paul Ricchiazzi 05 Jan 01
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/gray.pro)
NAME: GRID_IMAGE PURPOSE: to calculate a regular grid for an image in pixels co-ordinates and output the X and Y vectors of the grid vertices. CALLING SEQUENCE: GRID_IMAGE,image,nx=nx,ny=ny,xp=xp,yp=yp,xspace=xspace,yspace=yspace NX - the number of points to be generated in the X direction NY - the number of points to be generated in the Y direction XP - the output vector of X co-ordinates YP - the output vector of X co-ordinates Alternatively, you can specify how far apart the co-ordinates should be
(See /home/drw/idl/secis2/grid_image.pro)
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: G_OF_T
PURPOSE:
To compute DE * F(T) * n_j * A_ji / N_e for selected emission lines.
Option to also multiply by abundance.
CATEGORY:
Atomic data analysis
EXPLANATION:
Calls EMISS_CALC to calculate DE*n_j*A_ji for a range of temps and
folds it with the ionisation balance, F(T). The resulting function
is returned. Note that this function is tabulated over 4<=logT<=8
in 0.1 intervals.
When the ABUND keyword is given, the function is multiplied by the
element abundance, relative to H.
If you want the G-of-T function to be tabulated at smaller
temperature intervals than 0.1, see the routine ION_INTERP.PRO
CALLING SEQUENCE:
EXAMPLES:
RESULT=G_OF_T(26,13)
RESULT=G_OF_T(26,13,WRANGE=[200,205],/ABUND,/CHOOSE)
INPUTS:
IZ: The atomic number of the ion (e.g., 26 = Fe)
ION: The spectroscopic number of the ion (e.g., 12 = XII)
WRANGE: Wavelength range from which lines are required. If not
specified, then the 10 strongest lines are displayed.
OPTIONAL INPUTS:
DENS: The density at which the emissivities are calculated
(default=10.)
KEYWORDS:
CHOOSE: By default, the routine uses Arnaud and Raymond (1992) for
the iron ions and Arnaud and Rothenflug (1985) for all
other ions. This keyword allows you to choose the ion
balance calculations via a widget. Similarly, if the ABUND
keyword has been set, CHOOSE will allow you to pick an
abundance file
ABUND: Multiply function by the abundance of the element (relative
to H). The abundance file is selected from the CHIANTI
database. The default is `photospheric_may97.abund', but
giving the CHOOSE keyword allows you to choose any of the
CHIANTI abundance files.
ADD: Add the G-of-T function to the goft_list.
(**To be added at a later date!**)
CALLS:
EMISS_CALC, READ_ABUND, READ_IONEQ
HISTORY:
Ver.1, PRY 28-Jul-97.
Ver.2, PRY 22-Jun-98, added CHOOSE keyword and removed RAY
CONTACT:
Peter Young, Cambridge University (P.R.Young@damtp.cam.ac.uk)
(See /home/drw/idl/bin/g_of_t.pro)
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: G_OF_T
PURPOSE:
To compute DE * F(T) * n_j * A_ji / N_e for selected emission lines.
Option to also multiply by abundance.
CATEGORY:
Atomic data analysis
EXPLANATION:
Calls EMISS_CALC to calculate DE*n_j*A_ji for a range of temps and
folds it with the ionisation balance, F(T). The resulting function
is returned. Note that this function is tabulated over 4<=logT<=8
in 0.1 intervals.
When the ABUND keyword is given, the function is multiplied by the
element abundance, relative to H.
If you want the G-of-T function to be tabulated at smaller
temperature intervals than 0.1, see the routine ION_INTERP.PRO
CALLING SEQUENCE:
EXAMPLES:
RESULT=G_OF_T(26,13)
RESULT=G_OF_T(26,13,WRANGE=[200,205],/ABUND,/CHOOSE)
INPUTS:
IZ: The atomic number of the ion (e.g., 26 = Fe)
ION: The spectroscopic number of the ion (e.g., 12 = XII)
WRANGE: Wavelength range from which lines are required. If not
specified, then the 10 strongest lines are displayed.
OPTIONAL INPUTS:
DENS: The density at which the emissivities are calculated
(default=10.)
KEYWORDS:
CHOOSE: By default, the routine uses Arnaud and Raymond (1992) for
the iron ions and Arnaud and Rothenflug (1985) for all
other ions. This keyword allows you to choose the ion
balance calculations via a widget. Similarly, if the ABUND
keyword has been set, CHOOSE will allow you to pick an
abundance file
ABUND: Multiply function by the abundance of the element (relative
to H). The abundance file is selected from the CHIANTI
database. The default is `photospheric_may97.abund', but
giving the CHOOSE keyword allows you to choose any of the
CHIANTI abundance files.
ADD: Add the G-of-T function to the goft_list.
(**To be added at a later date!**)
CALLS:
EMISS_CALC, READ_ABUND, READ_IONEQ
HISTORY:
Ver.1, PRY 28-Jul-97.
Ver.2, PRY 22-Jun-98, added CHOOSE keyword and removed RAY
CONTACT:
Peter Young, Cambridge University (P.R.Young@damtp.cam.ac.uk)
(See /home/drw/idl/bin/ptg/g_of_t.pro)
routine: h2osat
purpose: compute saturated density of water vapor
useage: result=h2osat(t)
input:
temp air temperature in kelvin
output:
result water vapor density at 100% saturation (g/m3)
if keyword vp is set result is saturated water
vapor pressure (mb).
NOTE: h2osat(t)=h2osat(t,/vp)/Mkt
where M is the molecular mass of h2o, and k
is boltzman's constant.
reference: Here is how I came up with the polynomial fit you see below
1. copy out table of saturated water vapor pressure
vs temparature from Handbook of Chemistry and Physics
2. find a polynomial fit of log(P) vs (1/t)
(Clausius-Clapeyron equation has P = Po exp(-to/t))
3. convert vapor pressure to density using the molecular mass
of H2O (standard isotope mix)
EXAMPLE:
; compute water density at a relative humidity of 50% and
; an air temperature of 25 C.
k=1.38e-23 & rh=.5 & t=25.0+273.15 & p=101325.
wdens=h2osat(25.0+273.15)
wden=rh*wdens/(1.-k*t*wdens*(1.-rh)/p)
; at pressures greater than ~300mb this is well approximated by
wden=rh*wdens
; compute water density (g/m3) corresponding to a dew point
; temperature of 10 C and ambient temperature of 25 C.
; The dew point is the temperature to which air must be
; cooled at constant pressure and constant mixing ratio to
; reach 100% saturation with respect to a plane water surface
;
; by definition mixing ratio ~ Nw/(N-Nw) = SVP(Tdew)/(P-SVP(Tdew))
;
; Nw kT/(P-Nw kT) = SVP(Tdew)/(P-SVP(Tdew))
;
; Nw = SVP(Tdew)/kT
;
; where SVP is the saturated vapor pressure
tdew=10.+273.15
t=25+273.15
Pvap=h2osat(tdew)
wden=h2osat(tdew)*tdew/t ; mass density (g/m3)
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/h2osat.pro)
routine: h2osat
purpose: compute saturated density of water vapor
useage: result=h2osat(t)
input:
temp air temperature in kelvin
output:
result water vapor density at 100% saturation (g/m3)
if keyword vp is set result is saturated water
vapor pressure (mb).
NOTE: h2osat(t)=h2osat(t,/vp)/Mkt
where M is the molecular mass of h2o, and k
is boltzman's constant.
reference: Here is how I came up with the polynomial fit you see below
1. copy out table of saturated water vapor pressure
vs temparature from Handbook of Chemistry and Physics
2. find a polynomial fit of log(P) vs (1/t)
(Clausius-Clapeyron equation has P = Po exp(-to/t))
3. convert vapor pressure to density using the molecular mass
of H2O (standard isotope mix)
EXAMPLE:
; compute water density at a relative humidity of 50% and
; an air temperature of 25 C.
k=1.38e-23 & rh=.5 & t=25.0+273.15 & p=101325.
wdens=h2osat(25.0+273.15)
wden=rh*wdens/(1.-k*t*wdens*(1.-rh)/p)
; at pressures greater than ~300mb this is well approximated by
wden=rh*wdens
; compute water density (g/m3) corresponding to a dew point
; temperature of 10 C and ambient temperature of 25 C.
; The dew point is the temperature to which air must be
; cooled at constant pressure and constant mixing ratio to
; reach 100% saturation with respect to a plane water surface
;
; by definition mixing ratio ~ Nw/(N-Nw) = SVP(Tdew)/(P-SVP(Tdew))
;
; Nw kT/(P-Nw kT) = SVP(Tdew)/(P-SVP(Tdew))
;
; Nw = SVP(Tdew)/kT
;
; where SVP is the saturated vapor pressure
tdew=10.+273.15
t=25+273.15
Pvap=h2osat(tdew)
wden=h2osat(tdew)*tdew/t ; mass density (g/m3)
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/h2osat.pro)
NAME:
HCOLORBAR
FILENAME:
hcolorbar__define.pro
;
PURPOSE:
The purpose of this program is to create a horizontal
colorbar object to be used in conjunction with other
IDL 5 graphics objects.
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:
IDL 5 Object Graphics.
CALLING SEQUENCE:
thisColorBar = Obj_New('HColorBar')
REQUIRED INPUTS:
None.
INIT METHOD KEYWORD PARAMETERS:
COLOR: A three-element array representing the RGB values of a color
for the colorbar axes and annotation. The default value is
white: [255,255,255].
NAME: The name associated with this object.
NCOLORS: The number of colors associated with the colorbar. The
default is 256.
MAJOR: The number of major tick divisions on the colorbar axes.
The default is 5.
MINOR: The number of minor tick marks on the colorbar axes.
The default is 4.
PALETTE: A palette object for the colorbar. The default palette
is a gray-scale palette object.
POSITION: A four-element array specifying the position of the
colorbar in normalized coordinate space. The default position
is [0.10, 0.90, 0.90, 0.95].
RANGE: The range associated with the colorbar axis. The default
is [0, NCOLORS].
TEXT: A text object. Colorbar axis annotation will use this text
object to set its properties. The default is a text object
using a 8 point Helvetica font in the axis color.
TITLE: A string containing a title for the colorbar axis
annotation. The default is a null string.
OTHER METHODS:
GetProperty (Procedure): Returns colorbar properties in keyword
parameters as defined for the INIT method. Keywords allowed are:
COLOR
MAJOR
MINOR
NAME
PALETTE
POSITION
RANGE
TEXT
TITLE
TRANSFORM
SetProperty (Procedure): Sets colorbar properties in keyword
parameters as defined for the INIT method. Keywords allowed are:
COLOR
MAJOR
MINOR
NAME
PALETTE
POSITION
RANGE
TEXT
TITLE
TRANSFORM
SIDE EFFECTS:
A HColorBar structure is created. The colorbar INHERITS IDLgrMODEL.
Thus, all IDLgrMODEL methods and keywords can also be used. It is
the model that is selected in a selection event, since the SELECT_TARGET
keyword is set for the model.
RESTRICTIONS:
None.
EXAMPLE:
To create a colorbar object and add it to a plot view object, type:
thisColorBarObject = Obj_New('HColorBar')
plotView->Add, thisColorBarObject
plotWindow->Draw, plotView
MODIFICATION HISTORY:
Written by David Fanning, from VColorBar code, 20 Sept 98. DWF.
Changed a reference to _Ref_Extra to _Extra. 27 Sept 98. DWF.
Fixed bug when adding a text object via the TEXT keyword. 9 May 99. DWF.
Fixed the same bug when getting the text using the TEXT keyword. :-( 16 Aug 2000. DWF.
Fixed a bug with getting the text object via the TEXT keyword. 16 Aug 2000. DWF.
Added the TRANSFORM keyword to GetProperty and SetProperty methods. 16 Aug 2000. DWF.
Added RECOMPUTE_DIMENSIONS=2 to text objects. 16 Aug 2000. DWF.
Added a polygon object around the image object. This allows rotation in 3D space. 16 Aug 2000. DWF.
(See /home/drw/idl/aux/hcolorbar__define.pro)
ROUTINE: hdf_info
PURPOSE: displays Raster,SD,MSDS and Vset information about filename,
in tabular format
USEAGE: hdf_info,name,outfile=outfile
INPUT:
name name of hdf file
KEYWORD INPUT:
outfile name of output file (is set terminal input is disabled)
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 24 May 00
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/hdf_info.pro)
NAME:
HDF_READ
PURPOSE:
HDF_READ provides a point-and-click interface for reading a single SDS
from a HDF3.3r4 file. The user interactively selects which portion of
the SDS is to be read.
CATEGORY:
HDF.
CALLING SEQUENCE:
HDF_READ, FILE, DATA, $
SDS = SDS, INFO = INFO, START = START, COUNT = COUNT, $
LONG_NAME = LONG_NAME, UNITS = UNITS, SCALE = SCALE, OFFSET = OFFSET, $
READ_ALL = READ_ALL
INPUTS:
FILE: Name of HDF file to read.
DATA: Named variable to hold returned SDS array data.
KEYWORD PARAMETERS:
SDS: Set this keyword to the name of a specific SDS to read.
The default is for the user to select a SDS name from a
widget list.
INFO: Set this keyword to print SDS information - no data is read.
The default is to not print any SDS information.
START: Set this keyword to a vector containing the start position
in the array to be read. The default is [0,0,...,0].
COUNT: Set this keyword to a vector containing the number of items
in the array to be read. The default is to read all items.
LONG_NAME: Set this keyword to a named variable in which the SDS
long_name attribute is returned. The SDS name is returned
if the long_name attribute is not defined.
UNITS: Set this keyword to a named variable in which the SDS
units attribute is returned. "no units" is returned
if the units attribute is not defined.
SCALE: Set this keyword to a named variable in which the SDS
scale attribute is returned. 1.0 is returned if the scale
attribute is undefined.
OFFSET: Set this keyword to a named variable in which the SDS
offset attribute is returned. 0.0 is returned if the offset
attribute is undefined.
READ_ALL: Read all the data in the SDS (START and COUNT not required).
COMMON BLOCKS:
None.
SIDE EFFECTS:
This function initiates the XMANAGER if it is not already running.
RESTRICTIONS:
None known.
PROCEDURE:
Get SDS name, then read SDS.
LIBRARY CALLS:
XLIST (JHU APL library, ftp://fermi.jhuapl.edu/pub/idl)
CW_GETFIELDS (Liam Gumley, liam.gumley@ssec.wisc.edu)
HDF_GET_INFO (Liam Gumley, liam.gumley@ssec.wisc.edu)
SDS_GET_INFO (Liam Gumley, liam.gumley@ssec.wisc.edu)
EXAMPLES:
; Create a simple HDF SDS file (256x256 float array)
sd_id = hdf_sd_start( 'image.hdf', /create )
sds_id = hdf_sd_create( sd_id, 'image', [256,256], /float )
hdf_sd_adddata, sds_id, dist(256)
hdf_sd_endaccess, sds_id
hdf_sd_end, sd_id
; Read the image in interactive mode and display it
hdf_read, pickfile(), image
help, image
tvscl, image
; Read rows 128-257 of the image in non-interactive mode
hdf_read, 'image.hdf', image, sds = 'image', $
start = [ 0, 128 ], count = [ 256, 128 ]
help, image
MODIFICATION HISTORY:
Written by: Liam Gumley, CIMSS/SSEC, 1 July 1996
LG, 7 August 1996
- added non-interactive read option via SDS keyword
- added START and COUNT keywords
- added print information option via INFO keyword
LG, 27 September 1996
- added READ_ALL keyword to read whole SDS
LG, 03 December 1996
- fixed problem with START and COUNT keywords
PR, may00,
- added print out of equivalent non-interactive command
(See /home/drw/idl/esrg/hdf_read.pro)
ROUTINE: head PURPOSE: Print Header to CDS QLDS USEAGE: HEAD,QLDS INPUT: qlds CDS INT_DIST Quick Look Data Structure. OUTPUT: Example: AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/head.pro)
ROUTINE: head PURPOSE: Print Header to CDS QLDS USEAGE: HEAD,QLDS INPUT: qlds CDS INT_DIST Quick Look Data Structure. OUTPUT: Example: AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/ptg/head.pro)
NAME:
HELPFORM
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Generate a descriptive string in IDL HELP format
CALLING SEQUENCE:
STRINGS = HELPFORM(NAME, VALUE, [/SHORTFORM,] [/SINGLE,] [WIDTH=width])
DESCRIPTION:
The HELPFORM function converts an IDL data value into a
representation very similar to the format produced by the built-in
command HELP. Programmers can thus present data types and values
to users in a format they are familiar with.
For example, if the variable A is defined in the following manner,
and HELP is called, then the following transcript will result:
IDL> a = [1,2]
IDL> help, a
A INT = Array[2]
The same result can be achieved with the HELPFORM function:
IDL> print, helpform('A', a)
A INT = Array[2]
The benefit is that the output of HELPFORM is a string that can be
outputted or reformatted. This capability is not available in all
versions of IDL.
HELPFORM actually produces *two* forms of output. The above
output is considered the "long" form, as it appears in the IDL
HELP command, and is the default. A "short" form can also be
produced, and is very similar to the information that appears in
certain terse IDL error messages. It is activated by setting the
SHORTFORM keyword.
If the variable name is too long, the HELPFORM may be forced to be
two lines long to have consistent formatting. In that case a
two-element string is returned. If a single line is desired, use
the SINGLE keyword, but this comes at the expense of consistent
output formatting.
INPUTS:
NAME - A scalar string containing the name of the IDL variable.
An empty string is permitted. The name is ignored if the
SHORTFORM keyword is set.
VALUE - Any IDL value to be examined. VALUE is optional if the
SIZE keyword is passed and uniquely describes the data.
VALUE should be passed for scalars and structures, since
the help form for these values requires additional
information beyond the SIZE.
KEYWORDS:
SIZE - the IDL SIZE descriptor for the value to be printed.
Default: information is taken from VALUE.
SINGLE - if set, then output which would normally
appear on two lines for consistent formatting, appears on
one single line instead.
FULL_STRUCT - if set, then a detailed output is printed for
structures, similar to HELP, VALUE, /STRUCTURE.
SHORTFORM - set this keyword for a shorter output format that can
be used in error messages.
WIDTH - the width of the terminal in characters (used for
formatting).
Default: 80
RETURNS:
An array of strings containing the HELPFORM output, which may have
more than one element depending on the length of NAME, SHORTFORM
and SINGLE. The helpforms of pointer- and object-typed values
does not include the sequence number, but are otherwise correct.
EXAMPLE:
IDL> print, helpform('A', size=[1,2,1,2])
A BYTE = Array[2]
;; Do not pass VALUE and instead use SIZE to specify the type
IDL> print, helpform('A', size=[1,2,1,2], /shortform)
BYTE (Array[2])
;; Compare to the short form, which is meant to be placed in
;; error messages
IDL> print, helpform('fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk',a)
fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk
INT = Array[2]
IDL> print, helpform('fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk',a,/single)
fjsldkfjsldfkjslkdfjslkdfjslkdfjsldkfjk INT = Array[2]
;; Compare the long and short forms
SEE ALSO:
INPUTFORM, HELP
MODIFICATION HISTORY:
Written, CM, 13 May 2000
Documented, 04 Jul 2000
Improved output for objects, CM, 11 Jan 2001
Added support for full structure output, CM 08 Feb 2001
Added forward_function declaration for safety, CM 08 Apr 2001
Print more info about POINTER type, CM 08 Apr 2001
$Id: helpform.pro,v 1.5 2001/04/11 00:43:54 craigm Exp $
(See /home/drw/idl/aux/markwardt/helpform.pro)
FUNCTION: This procedure
- select values according to a user defined criterion
- display the selected values.
- display the histogram of the selected values in the
array tab.
INPUTS : tab1 --> 2 or 3 dimensional array (NO DEFAULT)
: thresmin --> minimum value for which the value
is selected (NO DEFAULT if use - see OPTIONS)
: thresmax --> maximum value for which the value
is selected (NO DEFAULT if use - see OPTIONS)
OPTIONS : select --> if thresmin and thresmax are ommitted
allows to specify the criterion based on a
different array features.
binsize --> defines the size of the bin for the
histogram (DEFAULT = 1.)
USE : HILIGHT, ARRAY1, 10., 20., BINSIZE=1 :
select and display on the the values in arrray1
between 10. and 20.
HILIGHT, ARRAY1, SELECT=WHERE(ARRAY2 LE 5.43) :
select and display the values in the array1 where
array2 is less or equal than 5.43
CONTACT : Didier JOURDAN didier@esrg.ucsb.edu
(See /home/drw/idl/esrg/hilight.pro)
FUNCTION: This procedure
- select values according to a user defined criterion
- display the selected values.
- display the histogram of the selected values in the
array tab.
INPUTS : tab1 --> 2 or 3 dimensional array (NO DEFAULT)
: thresmin --> minimum value for which the value
is selected (NO DEFAULT if use - see OPTIONS)
: thresmax --> maximum value for which the value
is selected (NO DEFAULT if use - see OPTIONS)
OPTIONS : select --> if thresmin and thresmax are ommitted
allows to specify the criterion based on a
different array features.
binsize --> defines the size of the bin for the
histogram (DEFAULT = 1.)
USE : HILIGHT, ARRAY1, 10., 20., BINSIZE=1 :
select and display on the the values in arrray1
between 10. and 20.
HILIGHT, ARRAY1, SELECT=WHERE(ARRAY2 LE 5.43) :
select and display the values in the array1 where
array2 is less or equal than 5.43
CONTACT : Didier JOURDAN didier@esrg.ucsb.edu
(See /home/drw/idl/old.esrg/hilight.pro)
ROUTINE: hilite,im,select
EXAMPLE: hilite,avhrr1,where(avhrr3-avhrr4 lt 5.)
PURPOSE: To hilite a region which satifies a specified set of
conditions
INPUT: im 2-D image array (any type but string)
select Index array of points to hilite. These may be
generated with the WHERE proceedure.
rate rate of flicker
KEYWORD INPUT:
keep do not destroy window on exit
zoom 2 element vector which specifies zoom factor
in x and y direction
OUTPUT: NONE
COMMON BLOCKS: NONE
SIDE EFFECTS: Creates and uses a new window
PROCEEDURE: Selected region is hilighted by use of the FLICK proceedure.
EXAMPLE
c=cmplxgen(100,100,/cent)/20
s=sin(float(c+c^2))
mve,c
hilite,s,where(float(c+c^4) gt 1. and imaginary(c+c^4) lt 1.),zoom=2
author: Paul Ricchiazzi sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/hilite.pro)
ROUTINE: hilite,im,select
EXAMPLE: hilite,avhrr1,where(avhrr3-avhrr4 lt 5.)
PURPOSE: To hilite a region which satifies a specified set of
conditions
INPUT: im 2-D image array (any type but string)
select Index array of points to hilite. These may be
generated with the WHERE proceedure.
rate rate of flicker
KEYWORD INPUT:
keep do not destroy window on exit
zoom 2 element vector which specifies zoom factor
in x and y direction
OUTPUT: NONE
COMMON BLOCKS: NONE
SIDE EFFECTS: Creates and uses a new window
PROCEEDURE: Selected region is hilighted by use of the FLICK proceedure.
EXAMPLE
c=cmplxgen(100,100,/cent)/20
s=sin(float(c+c^2))
mve,c
hilite,s,where(float(c+c^4) gt 1. and imaginary(c+c^4) lt 1.),zoom=2
author: Paul Ricchiazzi sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/hilite.pro)
NAME:
HIST2D
PURPOSE:
Plot a 2-dimensional histogram.
CALLING SEQUENCE:
hist2d,x_values,y_values
INPUTS:
x_variable self-explanatory
y_variable self-explanatory
KEYWORD INPUTS:
bindim number of bins on one side
tvim plot image rather than contour
xtitle title for x axis
ytitle title for y axis
title title for plot
nlevels number of levels for contouring
follow keyword to contour to select algorithm allowing labeling
c_charsize contour charsize
OPTIONAL INPUTS:
OUTPUTS:
OPTIONAL OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 3/15/94
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/hist2d.pro)
NAME:
HIST2D
PURPOSE:
Plot a 2-dimensional histogram.
CALLING SEQUENCE:
hist2d,x_values,y_values
INPUTS:
x_variable self-explanatory
y_variable self-explanatory
KEYWORD INPUTS:
bindim number of bins on one side
tvim plot image rather than contour
xtitle title for x axis
ytitle title for y axis
title title for plot
nlevels number of levels for contouring
follow keyword to contour to select algorithm allowing labeling
c_charsize contour charsize
OPTIONAL INPUTS:
OUTPUTS:
OPTIONAL OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 3/15/94
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/hist2d.pro)
NAME: HIST2HIST PURPOSE: Reads FITS file with histogram data in the primary data unit (or any extension in the EXTENSION keyword). Differs from mrdfits only in the ability to handle the same keywords used by LIST2HIST. Usually called from READIT rather then run directly. CATEGORY: FITS CALLING SEQUENCE: result = HIST2HIST(Filename) INPUTS: Filename: Input FITS file with histogram data in the primary data unit. KEYWORD PARAMETERS: NOTE: DO NOT change these without also modifying LIST2HIST. TRANGE: A two element vector containing the start and ending times to include in the array. XRANGE: A two element vector containing the range of x to include in the array. YRANGE: A two element vector containing the range of y to include in the array. PRANGE: A two element vector containing the range of pulse height to include in the array. SCALE: Scale factor for array. Can be set to make the resultant array a reasonable size. A scale size of n bins the image n x n. PHD: The returned pulse height distribution. FHEADER:The returned FITS header. BHEADER:A null string. Included for compatibility with LIST2HIST. EXTENSION: Extension where the data is found. If not present, assumes the data is in the primardy data unit. EXPAND: If present, scale the number of x and y pixels by SPECBINX and SPECBINY. Flux in each pixel is spread evenly over the new smaller pixels. SILENT: If included, suppress informative messages. COMMON BLOCKS: LAMSPACE:for IMAGE.PRO. MODIFICATION HISTORY: Written by David Sahnow, 12 August 1997. 14 November 1997 Changed to return an empty string for BHEADER. 6 November 1998 Added EXTENSION keyword. 8 April 1999 Added FSCALE keyword to MRDFITS call. 30 January 2000 Added EXPAND keyword to scale input array by SPECBINX and SPECBINY and restore original pixel ratio. 19 April 2000 Added defaults values of SPECBINX, SPECBINY. 30 May 2000 Added SILENT keyword. 20 June 2000 Modified fheader to return the primary header, even if another extension is being read, and bheader to return the header of the extension being read.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/hist2hist.pro)
FUNCTION: This procedure displays the histogram of
the array tab1.
INPUTS : tab1 --> array
: mini --> minimum value
: maxi --> maximum value
: bin --> size of bin
OUTPUTS : diplay
keyword Input:
default --> percentage
/abs --> compute the histogram in number of values
/cumul --> compute the cumulative histogram
/overplot --> overplot the histogram
title --> title of plot
xtitle --> xtitle of plot
ytitle --> ytitle of plot
xrange --> xrange of plot
yrange --> yrange of plot
USE : histo, array1,0,500,1, /cumul
CONTACT : Didier JOURDAN didier@esrg.ucsb.edu
(See /home/drw/idl/esrg/histo.pro)
FUNCTION: This procedure displays the histogram of
the array tab1.
INPUTS : tab1 --> array
: mini --> minimum value
: maxi --> maximum value
: bin --> size of bin
OUTPUTS : diplay
keyword Input:
default --> percentage
/abs --> compute the histogram in number of values
/cumul --> compute the cumulative histogram
/overplot --> overplot the histogram
title --> title of plot
xtitle --> xtitle of plot
ytitle --> ytitle of plot
xrange --> xrange of plot
yrange --> yrange of plot
USE : histo, array1,0,500,1, /cumul
CONTACT : Didier JOURDAN didier@esrg.ucsb.edu
(See /home/drw/idl/old.esrg/histo.pro)
NAME:
HIST
PURPOSE:
call histo procedure to plot a histogram with
correct values along the x-axis. Calculates min, max for you.
If binsz is set, uses it, otherwise = 1.
CALLING SEQUENCE:
hist,variable
INPUTS:
arr array to be plotted
KEYWORD INPUTS:
OPTIONAL INPUTS:
binsz bin size of histogram
/abs --> compute the histogram in number of values
/cumul --> compute the cumulative histogram
/overplot --> overplot the histogram
OUTPUTS:
OPTIONAL OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 9/22/92
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/hist.pro)
NAME:
HIST
PURPOSE:
call histo procedure to plot a histogram with
correct values along the x-axis. Calculates min, max for you.
If binsz is set, uses it, otherwise = 1.
CALLING SEQUENCE:
hist,variable
INPUTS:
arr array to be plotted
KEYWORD INPUTS:
OPTIONAL INPUTS:
binsz bin size of histogram
/abs --> compute the histogram in number of values
/cumul --> compute the cumulative histogram
/overplot --> overplot the histogram
OUTPUTS:
OPTIONAL OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 9/22/92
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/hist.pro)
NAME: HIST_COMBINE PURPOSE: This function adds multiple HIST or TTAG exposures with the option of shifting each exposure. The result is a histogram. CATEGORY: Data. CALLING SEQUENCE: Result = HIST_COMBINE(Filenames [, Xshifts, Yshifts, Scale]) INPUTS: Filenames: An array of filenames which contain the data to add. These should be valid FUSE HIST or TTAG files containing INTEGER or LONG arrays. OPTIONAL INPUTS: Xshifts:An array of pixel shifts (one for each Filename) to apply to the x dimension before adding. Positive shifts shift an array to the right. Note that shifts wrap at the ends of the array. If it is not an integer, it is rounded before being applied. Yshifts:Same as Xshifts, but in the y dimension. Scale: A scaling factor to apply to each spectrum. This can be a floating point value, but the saved spectrum will be converted to an int or long before returning. KEYWORD PARAMETERS: OUTFILE:Filename to save the results to. This filename is a standard FUSE FITS histogram file. SILENT: If included, suppress informative messages. FTYPE: Set this to a type of image to override file type returned by filetype(). Valid types include: TTAG OPUS time tag HIST OPUS spectral image mode PIPELINE Science pipeline image XYP_LIST UCB GSE photon list COUNT_IMAGE UCB GSE histogram GAIN_IMAGE UCB GSE gain histogram TXYP_LIST UCB GSE photon list with time FES FES file TTGD TTGD file from pipeline FLOAT: If included, write the combined data as a float (or long) rather than an integer. This will generate a warning in WFUSEHIST, because the data must be an integer to run the pipeline. OUTPUTS: This function returns the sum of the histograms, and optionally writes it to a file. SIDE EFFECTS: Optionally writes a file containing the summed histogram. PROCEDURE: Straightforward. EXAMPLE: In order to add the histograms for files named file1.fit, file2.fit, and file3.fit, with shifts of 0, -6, and +13 pixels, and save the results in a file called summed.fit, do the following: Files = ['file1.fit','file2.fit','file3.fit'] Shifts = [0,-6,13] Sum = HIST_COMBINE(Files,Shifts,outfile='summed.fit') MODIFICATION HISTORY: Written by David Sahnow, 31 January 2000. 2 February 2000 Fixed error in print statement. 2 February 2000 Added the ability to shift in Y as well as X. 4 February 2000 Modified to use WFUSEHIST rather than WHISTFITS on output, so file can be read by READIT. Added optional scaling. 7 February 2000 Now converts to long when adding data to avoid overflow. Converts back to an integer at the end if possible. 17 February 2000 Added rounding of shifts before applying to data. 22 February 2000 Now checks that scaling factor is the same for all input files. Now save output as in integer array so the pipeline doesn't choke. Added scaling of pixels outside active area if they are too large for an int, and truncating inside the active area. 2 May 2000 Added screening for fill data, which has a value of 21865. 23 May 2000 Fixed bug introduced on May 2 in cases when no bad data. 26 May 2000 Modified header of output file to correctly report EXPSTART, EXPEND, EXPTIME, PLANTIME, NEVENTS, DATEOBS, TIMEOBS. Changed output EXP_ID to 999. 30 May 2000 Added SILENT keyword. 5 June 2000 Added warning if FPA positions differ by more than FPAMOVE between exposures. 7 June 2000 Changed FPA warning to use EXP_ID instead of just file no. 14 June 2000 Changed output EXP_ID to 000. Removed warning about exposure times being incorrect. Modified counters to correctly report sum of all input exposures, and times of first and last engineering snapshot. 15 June 2000 Modified comments in output FITS file to allow longer filenames to fit. 20 June 2000 Added FTYPE keyword. 22 June 2000 Added FLOAT keyword. 16 August 2000 Now modified keywords FILETYPE and INSTMODE in output FITS file so that combining TTAG files creates a proper HIST file. 6 September 2000 Removed changes from 8/16 and put them in WFUSEHIST.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/hist_combine.pro)
NAME: hms
PURPOSE: convert time in seconds to a time string in hh:mm:ss format
USEAGE: time_string=hms(time)
INPUTS: time (seconds)
RESTRICTIONS time must be positive
KEYWORDS: none
OUTPUTS: return time string
AUTHOR: Paul Ricchiazzi 4jan94
Earth Space Research Group, UC Santa Barabara
(See /home/drw/idl/esrg/hms.pro)
NAME: hms
PURPOSE: convert time in seconds to a time string in hh:mm:ss format
USEAGE: time_string=hms(time)
INPUTS: time (seconds)
RESTRICTIONS time must be positive
KEYWORDS: none
OUTPUTS: return time string
AUTHOR: Paul Ricchiazzi 4jan94
Earth Space Research Group, UC Santa Barabara
(See /home/drw/idl/old.esrg/hms.pro)
ROUTINE: horline2
PURPOSE: Draw a horizontal line through a given data point
USEAGE: horline2,y
INPUT:
y y-coord of point through which line is to be drawn
OUTPUT:
Example: CURSOR,x,y,/data,/down
HORLINE2,y
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/horline2.pro)
ROUTINE: horline
PURPOSE: Draw a horizontal line through a given data point
USEAGE: horline,y
INPUT:
y y-coord of point through which line is to be drawn
OUTPUT:
Example: CURSOR,x,y,/data,/down
HORLINE2,y
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/horline.pro)
ROUTINE: horline
PURPOSE: Draw a horizontal line through a given data point
USEAGE: horline,y
INPUT:
y y-coord of point through which line is to be drawn
OUTPUT:
Example: CURSOR,x,y,/data,/down
HORLINE,y
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/ptg/horline.pro)
ROUTINE: horzline
PURPOSE: Draw a horizontal line through a given data point
USEAGE: horzline,y
INPUT:
y y-coord of point through which line is to be drawn
OUTPUT:
Example: CURSOR,x,y,/data,/down
HORLINE,y
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/jma/horzline.pro)
NAME:
HPRNUTANG
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:
Compute high precision earth precession, nutation and orientation angles
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
HPRNUTANG, JDTT, ZETA, THETA, Z, DPSI, DEPS, $
POLAR_X=PMX, POLAR_Y=PMY, JD_UT1=JD_UT1, /USE_EOPDATA, $
TBASE=, FIXED_EPOCH=, FIXED_BASE=, $
/JPL, /NO_UT1, $
MEAN_OBLIQUITY=EPS0, TRUE_OBLIQUITY=EPS, $
GMS_TIME=GMST, GAS_TIME=GAST, EQ_EQUIONOX=EQEQ
DESCRIPTION:
The procedure HPRNUTANG computes values of the earth
orientation-related angles, including precession and nutation,
which are used for high precision earth-based astronomy
applications.
It is the goal of this procedure to provide all angles relevant in
determining the position of an earth station, as measured in an
earth-fixed coordinate system, and converting to space-fixed
coordinates. This is useful in applications where observations by
a station in the earth-fixed frame are taken of an astrophysical
object which is in the non-rotating space-fixed frame.
This routine potentially depends on the following external
procedures, which also themselves depend on external data files:
EOPDATA - estimates Earth orientation parameters (if
USE_EOPDATA keyword is set), depends on earth
orientation data file.
TAI_UTC - computes time difference TAI - UTC (leap seconds),
depends on leap seconds file.
This interface is somewhat provisional. See OPEN QUESTIONS below.
The user requests the quantities for a particular set of epoch
times, as measured in Julian days, in the system of Terrestrial
Dynamical Time ( = TDT = TT ).
HPRNUTANG returns several quantities. It is not possible to
describe each of these quantities in full detail in this
documentation. The user is referred to the Explanatory Supplement
to the Astronomical Almanac (Sec 3.2) for more complete
descriptions. The quantities are:
* ZETA, THETA, Z, which are euler angles representing the
precession of the mean celestial ephemeris pole with respect to
the space-fixed coordinate system defined by the FIXED epoch.
For a vector R_MEAN_OFDATE, whose space-fixed coordinates are
referred to the mean pole of date, the transformation to
space-fixed coordinates referred to the mean pole of the fixed
epoch is:
R_FIXED = qtvrot(R_MEAN_OFDATE, $
qteuler(['z','y','z'], -zeta, +theta, -z))
By default the "fixed" epoch is J2000.0. [ See below for
definitions of QTVROT and QTEULER. ]
* DPSI, DEPS, which are the angles representing the nutation in
longitude and obliquity of the true of-date celestial ephemeris
pole with respect to the mean pole of date. For a vector
R_TRUE_OFDATE, whose space-fixed coordinates are referred to
the true pole of date, the transformation to space-fixed
coordinates referred to the mean pole of date is:
R_MEAN_OFDATE = qtvrot(R_TRUE_OFDATE, $
qteuler(['x','z','x'], $
+eps0, -dpsi, -eps0-deps)
where EPS and EPS0 are defined below.
* EPS0, which is the mean obliquity of the ecliptic plane,
referred to the mean equator of date, at the requested epoch.
For a vector, R_ECL_OFDATE, whose space-fixed coordinates are
referred to the mean ecliptic and equinox of date, the
transformation to space-fixed coordinates referred to the mean
equator and equinox of date is:
R_MEAN_OFDATE = qtvrot(R_ECL_OFDATE, $
qteuler(['x'], eps0)
* EPS, which is the true obliquity of the ecliptic plane,
referred to the mean equator of date, at the requested epoch.
* GMST, GAST, which are the mean and apparent Greenwich Sidereal
Times at the requested epoch. For a vector R_TRUE_EARTHFIXED,
whose earth-fixed coordinates are referred to the true pole of
date, the transformation to space-fixed coordinates referred to
the true pole of date are:
R_TRUE_OFDATE = qtvrot(R_TRUE_EARTHFIXED, $
qteuler(['z'], +gast))
* EQEQ, the equation of the equinoxes at the requested epoch.
This quantity may be more commonly known as the "precession of
the equinox."
* PMX, PMY, the coordinates of the celestial ephemeris pole as
measured in the earth-fixed coordinate system (set to zero if
the USE_EOPDATA keyword is not set). For a vector
R_MEAN_EARTHFIXED, whose earth-fixed coordinates are referred
to the International Reference Pole, the transformation to
earth-fixed coordinates referred to the true pole of date are:
R_TRUE_EARTHFIXED = qtvrot(R_MEAN_EARTHFIXED, $
qteuler(['x','y'], -pmy, -pmx))
The vector R_MEAN_EARTHFIXED, could be for example, the
coordinates of a station on the earth, as determined from its
geodetic latitude and longitude.
* JD_UT1, the UT1 time (expressed in Julian days) (set to UTC if
the USE_EOPDATA keyword is not set or if NO_UT1 is set).
Users may select different techniques to compute some of these
quantities. See keywords JPL and USE_EOPDATA.
OPEN QUESTIONS
How will the transition to a new IERS EOP series be accomplished?
Using a keyword? How can users select different nutation series?
How can users select different fundamental arguments for the
planets.
VERIFICATION
The precession and nutation quantities were compared against those
produced by the SLALIB telescope pointing library.
For the epoch JD 2450449 (TT), the precession quantities of
HPRNUTANG agree numerically with SLALIB SLA_PREC to within 0.1
microarcseconds, and the nutation quantities agree SLALIB SLA_NUTC
to within 6 microarcseconds (and 54 microarcseconds in the mean
obliquity). The GMST values agree with SLALIB SLA_GMSTA to better
than 1 nanosecond. Of course this says nothing about the accuracy
of the IAU 1976/1980 precession and nutation models with respect
to the true precession and nutations.
The precession and nutation quantities computed in this procedure
-- ZETA, THETA, Z, DPSI and DEPS -- were also used to compute the
space-fixed coordinates of the Goldstone DSS-63 deep space network
tracking station. These values were compared against values
produced by JPL Horizons ephemeris generator. Agreement was found
at the 60 cm level. Accuracy at that level is probably limited by
the JPL DE406 earth ephemeris used by Horizons.
Polar motion values were estimated at the same epoch using
EOPDATA, and applied to three orthogonal unit vectors. The above
quaternion transformation produces the same coordinate values,
when compared against SLALIB_POLMO.
QTEULER and QTVROT
The functions QTEULER and QTVROT are functions from the Markwardt
quaternion library. QTEULER composes a chain of Euler-like
rotations into a single quaternion. QTVROT applies a quaternion
rotation to a 3-vector.
The user need not use these functions. Any function which
constructs a set of Euler-like rotations, and then applies them to
3-vectors will work fine.
INPUTS:
JDTT - a vector or scalar, the TT epoch time(s) for which high
precision values are to be computed.
For reference, JDTT = JDTAI + 32.184/86400d, where JDTAI is
the international atomic time measured in days. The value
of the keyword TBASE is added to JDTT to arrive at the
actual Julian date.
OUTPUTS:
ZETA, THETA, Z - Euler angles of precession of the mean celestial
ephemeris pole, expressed in ANGUNITS units.
DPSI, DEPS - the nutation angles in longitude and obliquity of the
true pole with respect to the mean pole, expressed in
ANGUNITS units. By default the values are based on
the IAU 1980 theory of nutation. The user can select
JPL to interpolate the JPL nutation ephemerides.
When USE_EOPDATA is set, the nutation angles are
augmented by the offset correction terms supplied in
the EOP file.
KEYWORD PARAMETERS:
TBASE - a fixed epoch time (Julian days) to be added to each value
of JDTT. Since subtraction of large numbers occurs with
TBASE first, the greatest precision is achieved when TBASE
is expressed as a nearby julian epoch, JDTT is expressed
as a small offset from the fixed epoch.
Default: 0
FIXED_EPOCH - a scalar or vector number, the fixed epoch (in TT
Julian Days) against which the precession angles of
the mean pole are referred.
Default: JD 2451545.0 TT ( = J2000.0 )
FIXED_BASE - a fixed epoch time to be added to FIXED_EPOCH, in
much the same way that TBASE is added to JDTT.
Default: 0
POLAR_X, POLAR_Y - upon return, the quantities PMX and PMY, in
ANGUNITS units, if USE_EOPDATA is set. If
USE_EOPDATA is not set then zero is returned
for both PMX and PMY.
JD_UT1 - upon return, the time in the UT1 system at the requested
epoch, if the USE_EOPDATA keyword is set. If the
USE_EOPDATA keyword is not set, or if NO_UT1 is set, then
the time in UTC is returned (which is guaranteed to be
within +/- 0.9 seconds of UT1).
MEAN_OBLIQUITY - upon return, the quantity EPS0, in ANGUNITS
units.
TRUE_OBLIQUITY - upon return, the quantity EPS, in ANGUNITS units.
GMS_TIME - upon return, the quantity GMST in radians.
GAS_TIME - upon return, the quantity GAST in radians.
EQ_EQUINOX - upon return, the quantity EQEQ in ANGUNITS units.
ANGUNITS - scalar string, output units of angular parameters.
Possible values are 'ARCSEC' or 'RADIAN'.
Default value: 'RADIAN'
JPL - if set, then use the JPL nutation ephemeris to determine the
nutation angle quantities.
NO_UT1 - if set, then do not compute UT1, but use UTC instead.
USE_EOPDATA - if set, use the EOPDATA procedure to determine earth
orientation parameters at the requested epoch.
These include polar motion values, corrections to
the 1980 IAU nutation theory, and the UT1
correction.
EXAMPLE:
Need an example converting topocentric to/from J2000.0
Need an example converting station position earth-fixed
coordinates to/from space-fixed coordinates.
SEE ALSO:
HPRNUTANG, TAI_UTC (Markwardt Library)
PRECESS, NUTATE, PREMAT, JPRECESS, BPRECESS (IDL Astronomy Library)
REFERENCES:
Aoki, S., Guinot, B., Kaplan, G.H., Kinoshita, H., McCarthy, D.D.,
Seidelmann, P.K., 1982: Astron. Astrophys., 105, 359-361.
HORIZONS, JPL Web-based ephemeris calculator (Ephemeris DE406)
http://ssd.jpl.nasa.gov/horizons.html
McCarthy, D. D. (ed.) 1996: IERS Conventions, IERS T.N. 21.
http://maia.usno.navy.mil/conventions.html
Seidelmann, P.K. 1992, *Explanatory Supplement to the Astronomical
Almanac*, ISBN 0-935702-68-7
MODIFICATION HISTORY:
Written, 30 Jan 2002, CM
Documented, 15 Feb 2002, CM
Added docs about ecliptic; added default of 'RADIAN' to code; 01
Mar 2002, CM
Corrected equation of equinoxes (had DPSI*COS(EPS0), when it
should be DPSI*COS(EPS)), 01 Mar 2002, CM
Added default message, 04 Mar 2002, CM
Added more logic to detect JPL ephemeris file, 17 Mar 2002, CM
Corrected discussion of geodetic coordinates, 26 May 2002, CM
$Id: hprnutang.pro,v 1.12 2002/05/26 16:09:57 craigm Exp $
(See /home/drw/idl/aux/markwardt/hprnutang.pro)
NAME:
HPRSTATN
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:
Compute high precision earth station positions in inertial coordinates
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
HPRSTATN, JDTT, R_ITRF, R_ECI, V_ECI, $
[ /JPL, /USE_EOP, /NO_UT1, TBASE= ]
DESCRIPTION:
The procedure HPRSTATN computes the coordinates and velocities of
an earth station in J2000 equatorial earth-centered inertial
coordinates (ECI). This may be useful in any application where an
earthbound observatory is used to collect data on a non-terrestrial
phenomenon.
The user must have the following routines involved: HPRNUTANG;
Markwardt Quaternion Library; JPLEPHREAD and JPLEPHINTERP (if JPL
keyword is used); EOPDATA (if USE_EOP keyword is set); and TAI_UTC.
Also, the appropriate data files for TAI-UTC and Earth Orientation
Parameters must be installed.
The user must specify the position of the earth station in
earth-centered, earth-fixed, cartesian coordinates of the ITRF.
The Z-axis points to terrestrial north, the X-axis lies in the
terrestrial equator pointing towards the Greenwich meridian, and
the Y-axis forms the right handed coordinate system. Any
positional units may be specified.
For the highest precision, the preferred method is to know the
coordinates from a direct IRTF reduction, i.e., via VLBI. A
procedure for estimating cartesian coordinates based on geodetic
coordinates (lat, lon) referred to the WGS84 ellipsoid is given
below.
The values returned are the earth-centered inertial J2000
coordinates and velocities of the station. All the effects of
earth rotation, precession, nutation, and polar motion are
potentially included. The user has a choice of the kinds of
transformations that are included (see JPL, USE_EOP and NO_UT1
keywords).
The returned positional units are the same as the input units. The
returned velocity units are (units of input) PER SECOND.
It is possible specify more than one time, or more than one station
position, or both. If both more than one time and position are
specified, then there must be an equal quantity of both.
CARTESIAN COORDINATES FROM GEODETIC COORDINATES
For example, for a station whose geodetic latitude LAT, longitude
LON (where positive is east) and elevation H specified relative to
the ellipsoid, the cartesian coordinates are:
R_ITRF = [ (A*C + H)*COS(LAT)*COS(LON), $
(A*C + H)*COS(LAT)*SIN(LON), $
(A*S + H)*SIN(LAT) ]
where for the WGS84 reference ellipsoid, the equatorial radius is
set to A = 6378.137 km, and the flattening factor F =
1/298.257223563, and
C = SQRT(COS(LAT)^2 + (1 - F)^2*SIN(LAT)^2)
S = (1 - F)^2 * C
INPUTS:
JDTT - a scalar or N-vector, the TT epoch time(s) for which
station coordinates are to be computed.
For reference, JDTT = JDTAI + 32.184/86400d, where JDTAI is
the international atomic time measured in days. The value
of the keyword TBASE is added to JDTT to arrive at the
actual Julian date.
R_ITRF - cartesian coordinates of earth station. Either a
3-vector, or a 3xN array. Units can be any positional
units.
OUTPUTS:
R_ECI - upon output, the coordinates of the station at the given
time(s), referred to the earth-centered J2000 coordinate
system. Either a 3-vector or 3xN array depending on the
input. Units are the same as for R_ITRF.
V_ECI - upon output, the velocities of the station at the given
time(s), referred to the earth-centered J2000 coordinate
system. Either a 3-vector or 3xN array depending on the
input. Units are (units of R_ITRF) PER SECOND.
KEYWORD PARAMETERS:
TBASE - a fixed epoch time (Julian days) to be added to each value
of JDTT. Since subtraction of large numbers occurs with
TBASE first, the greatest precision is achieved when TBASE
is expressed as a nearby julian epoch, JDTT is expressed
as a small offset from the fixed epoch.
Default: 0
JPL - if set, then the JPL ephemeris is used to compute nutation
angles. Otherwise the series representation of HPRNUTANG is
used.
USE_EOP - if set, then use earth orientation parameters, returned
by EOPDATA, to further refine the station coordinates.
Otherwise, only precession and nutation are used.
NO_UT1 - if set, then do not use the UT1-UTC conversion.
EXAMPLE:
;; ITRF coordinates of Deep Space Network Antenna 63 (METERS)
R_DSN63 = [+4849092.647d, -0360180.569d, +4115109.113d]
;; Time: 2000/01/01 01:30 TT
JDTT = jday(2000d,1,1) + 1.5/24
;; Compute position of antenna in J2000 coordinate system using
;; full Earth Orientation Parameters.
HPRSTATN, JDTT, R_DSN63, R_ECI, V_ECI, /USE_EOP
SEE ALSO:
HPRNUTANG, TAI_UTC (Markwardt Library)
EOPDATA, JPLEPHREAD, JPLEPHINTERP
REFERENCES:
McCarthy, D. D. (ed.) 1996: IERS Conventions, IERS T.N. 21.
http://maia.usno.navy.mil/conventions.html
Seidelmann, P.K. 1992, *Explanatory Supplement to the Astronomical
Almanac*, ISBN 0-935702-68-7
MODIFICATION HISTORY:
Written, 6 May 2002, CM
Documented, 12 May 2002, CM
Corrected discussion of geodetic coordinates, 26 May 2002, CM
$Id: hprstatn.pro,v 1.3 2002/05/26 16:10:48 craigm Exp $
(See /home/drw/idl/aux/markwardt/hprstatn.pro)
ROUTINE: hull
PURPOSE: return the index array of all boundary points of a square array
USEAGE: result=hull(nx,ny)
INPUT:
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 31 Aug 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/hull.pro)
NAME:
IEEE_TO_HOST
PURPOSE:
Translate an IDL variable from IEEE-754 to host representation
EXPLANATION:
The variable is translated from IEEE-754 (as used, for
example, in FITS data ), into the host machine architecture.
CALLING SEQUENCE:
IEEE_TO_HOST, data, [ IDLTYPE = , ]
INPUT-OUTPUT PARAMETERS:
data - any IDL variable, scalar or vector. It will be modified by
IEEE_TO_HOST to convert from IEEE to host representation. Byte
and string variables are returned by IEEE_TO_HOST unchanged
OPTIONAL KEYWORD INPUTS:
IDLTYPE - scalar integer (1-15) specifying the IDL datatype according
to the code given by the SIZE function. This keyword
is usually when DATA is a byte array to be interpreted as
another datatype (e.g. FLOAT).
EXAMPLE:
A 2880 byte array (named FITARR) from a FITS record is to be
interpreted as floating and converted to the host representaton:
IDL> IEEE_TO_HOST, fitarr, IDLTYPE = 4
METHOD:
The BYTEORDER procedure is called with the appropriate keyword
MODIFICATION HISTORY:
Written, W. Landsman Hughes/STX May, 1992
Converted to IDL V5.0 W. Landsman September 1997
Under VMS check for IEEE -0.0 values January 1998
VMS now handle -0.0 values under IDL V5.1 July 1998
Added new integer datatypes C. Markwardt/W. Landsman July 2000
Post-V5.1 version, no VMS negative zero check W. Landsman July 2001
Use size(/type) W. Landsman December 2002
(See /home/drw/idl/aux/markwardt/ieee_to_host.pro)
NAME:
IGAMMA
PURPOSE:
This function computes the incomplete gamma function, Px(a).
CATEGORY:
Special Functions.
CALLING SEQUENCE:
Result = Igamma(a, x)
INPUTS:
A: A positive scalar or array of type integer, float or double that
specifies the parametric exponent of the integrand.
X: A positive scalar or array of type integer, float or double that
specifies the upper limit of integration.
KEYWORD PARAMETERS:
DOUBLE = Set this keyword to force the computation to be done
in double precision.
EPS = relative accuracy, or tolerance. The default tolerance
is 3.0e-7 for single precision, and 3.0d-12 for double
precision.
ITER = Set this keyword equal to a named variable that will contain
the actual number of iterations performed.
ITMAX = Set this keyword to specify the maximum number of iterations.
The default value is 100.
METHOD: Use this keyword to specify a named variable which returns
the method used to compute the incomplete gamma function.
A value of 0 indicates that a power series representation
was used. A value of 1 indicates that a continued fractions
method was used.
EXAMPLE:
Compute the incomplete gamma function for the corresponding elements
of A and X.
Define the parametric exponents.
A = [0.10, 0.50, 1.00, 1.10, 6.00, 26.00]
Define the the upper limits of integration.
X = [0.0316228, 0.0707107, 5.00000, 1.04881, 2.44949, 25.4951]
Compute the incomplete gamma functions.
result = Igamma(A, X)
The result should be:
[0.742026, 0.293128, 0.993262, 0.607646, 0.0387318, 0.486387]
PROCEDURE:
IGAMMA computes the incomplete gamma function, Px(a), using either
a power series representation or a continued fractions method. If X
is less than or equal to A+1, the power series representation is used.
If X is greater than A+1, the continued fractions method is used.
The result will be NaN if the algorithm failed to converge
after the designated number of iterations.
REFERENCE:
Numerical Recipes, The Art of Scientific Computing (Second Edition)
Cambridge University Press
ISBN 0-521-43108-5
MODIFICATION HISTORY:
Written by: GGS, RSI, September 1994
IGAMMA is based on the routines: gser.c, gcf.c, and
gammln.c described in section 6.2 of Numerical Recipes,
The Art of Scientific Computing (Second Edition), and is
used by permission.
Modified: GGS, RSI, January 1996
Corrected the case of IGAMMA(a, 0) for a > 0.
DMS, Sept, 1999, Added arrays, and more accurate
results for double.
CT, March 2000, added DOUBLE, ITER keywords.
(See /home/drw/idl/priority/igamma.pro)
NAME:
IGAMMA
PURPOSE:
This function computes the incomplete gamma function, Px(a).
CATEGORY:
Special Functions.
CALLING SEQUENCE:
Result = Igamma(a, x)
INPUTS:
A: A positive scalar or array of type integer, float or double that
specifies the parametric exponent of the integrand.
X: A positive scalar or array of type integer, float or double that
specifies the upper limit of integration.
KEYWORD PARAMETERS:
DOUBLE = Set this keyword to force the computation to be done
in double precision.
EPS = relative accuracy, or tolerance. The default tolerance
is 3.0e-7 for single precision, and 3.0d-12 for double
precision.
ITER = Set this keyword equal to a named variable that will contain
the actual number of iterations performed.
ITMAX = Set this keyword to specify the maximum number of iterations.
The default value is 100.
METHOD: Use this keyword to specify a named variable which returns
the method used to compute the incomplete gamma function.
A value of 0 indicates that a power series representation
was used. A value of 1 indicates that a continued fractions
method was used.
EXAMPLE:
Compute the incomplete gamma function for the corresponding elements
of A and X.
Define the parametric exponents.
A = [0.10, 0.50, 1.00, 1.10, 6.00, 26.00]
Define the the upper limits of integration.
X = [0.0316228, 0.0707107, 5.00000, 1.04881, 2.44949, 25.4951]
Compute the incomplete gamma functions.
result = Igamma(A, X)
The result should be:
[0.742026, 0.293128, 0.993262, 0.607646, 0.0387318, 0.486387]
PROCEDURE:
IGAMMA computes the incomplete gamma function, Px(a), using either
a power series representation or a continued fractions method. If X
is less than or equal to A+1, the power series representation is used.
If X is greater than A+1, the continued fractions method is used.
The result will be NaN if the algorithm failed to converge
after the designated number of iterations.
REFERENCE:
Numerical Recipes, The Art of Scientific Computing (Second Edition)
Cambridge University Press
ISBN 0-521-43108-5
MODIFICATION HISTORY:
Written by: GGS, RSI, September 1994
IGAMMA is based on the routines: gser.c, gcf.c, and
gammln.c described in section 6.2 of Numerical Recipes,
The Art of Scientific Computing (Second Edition), and is
used by permission.
Modified: GGS, RSI, January 1996
Corrected the case of IGAMMA(a, 0) for a > 0.
DMS, Sept, 1999, Added arrays, and more accurate
results for double.
CT, March 2000, added DOUBLE, ITER keywords.
(See /home/drw/idl/gen/igamma.pro)
NAME:
IMAGE_BLEND
PURPOSE:
The purpose of this program is to demonstrate how to
use the alpha channel to blend one image into another.
The specific purpose is to see a color image on top of
a gray-scale image, with the gray-scale image showing
through behind the color image.
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, Object Graphics.
CALLING SEQUENCE:
Image_Blend
REQUIRED INPUTS:
None. The images "worldelv.dat" and "ctscan.dat" from the
examples/data directory are used.
OPTIONAL INPUTS:
backgroundImage:: A 2D image variable that will be used for the background image.
foregroundImage: A 2D image variable that will be used for the foreground image.
OPTIONAL KEYWORD PARAMETERS:
COLORTABLE: The number of a color table to use for the foreground image.
Color table 3 (red temperature) is used as a default.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None. The program XCOLORS is required from the Coyote library.
EXAMPLE:
Image_Blend, Colortable=5
MODIFICATION HISTORY:
Written by David Fanning, 30 March 99.
Fixed bug where I redefined the image parameter. Duh... 1 April 99. DWF.
(See /home/drw/idl/aux/image_blend.pro)
PROJECT:
SOHO
NAME:
IMAGE_TOOL
PURPOSE:
User interface of SOHO Pointing Tool and synoptic/summary database
CALLING SEQUENCE:
IMAGE_TOOL [, fits_file] [, point_stc=point_stc] [, start=start]
[, min=min, max=max] [, /reset] [, group=group] [,/modal]
INPUTS:
None required.
OPTIONAL INPUTS:
FITS_FILE -- String scalar or array, list of FITS image files
OUTPUTS:
None.
OPTIONAL OUTPUTS:
None.
KEYWORD PARAMETERS:
POINT_STC -- If present, it has to be a pointing structure that has
the following tags:
INSTRUME - Code specifying the instrument; e.g., 'C' for CDS
G_LABEL - Generic label for the pointing; e.g., 'RASTER'
X_LABEL - Label for X coordinate of pointing; e.g., 'INS_X'
Y_LABEL - Label for Y coordinate of pointing; e.g., 'INS_Y'
DATE_OBS - Date/time of beginning of observation, in TAI format
N_POINTINGS- Number of pointings to be performed by IMAGE_TOOL
POINTINGS - An array (with N_POINTINGS elements) of pointings to
be handled by IMAGE_TOOL. It has the following tags:
POINT_ID - A string scalar for pointing ID
INS_X - X coordinate of pointing area center in arcs
INS_Y - Y coordinate of pointing area center in arcs
WIDTH - Area width (E/W extent) in arcsec
HEIGHT - Area height (N/S extent) in arcsec
OFF_LIMB - An interger with value 1 or 0 indicating
whether or not the pointing area should
be off limb
N_RASTERS - Number of rasters for each pointing (this is
irrelevant to the SUMER)
RASTERS - A array (N_RASTERS-element) of structure that
contains raster size and pointing information
(this is irrelevant to the SUMER). It has the
following tags:
POINTING - Pointing handling code; valid
values are: 1, 0, and -1
INS_X - Together with INS_Y, the pointing to use
when user-supplied values are not
allowed. Only valid when POINTING=0
(absolute) or POINTING=-1 (relative to
1st raster).
INS_Y - ...
WIDTH - Width (E/W extent) of the raster, in arcs
HEIGHT - Height (N/S extent) of the raster, in arcs
Note that values of POINT_STC structure can be returned to the
caller of IMAGE_TOOL if the MODAL kyeword is set, or it is returned
as a UVALUE of a massenger of a calling widget.
AUTO_PLOT - Keyword used with POINT_STC. When Image Tool (and
Pointing Tool) is running and is called again with a new
POINT_STC and with AUTO_PLOT set, the
corresponding pointing area(s) will be plotted
automatically.
START -- Start time of a study, in TAI format; defaults to
current date and time. Note: If POINT_STC is passed
in and POINT_STC.DATE_OBS represents a valid TAI,
START will be overwritten by POINT_STC.DATE_OBS.
MIN -- Minimum value of the image
MAX -- Maximum value of the image
GROUP -- ID of the widget which serves as a group leader
MODAL -- Set this keyword to make IMAGE_TOOL a blocking widget program
RESET -- If set, all images saved in image stack will be removed
FOV -- A field of view (FOV) structure having the following tags:
X - array, X coordinates of the FOV, in arcsecs
Y - array, Y coordinates of the FOV, in arcsecs
COMMON BLOCKS:
@IMAGE_TOOL_COM, CROSS_HAIR
RESTRICTIONS:
Cannot be run two copies simultaneously (guaranteed by the call to
'XREGISTERED')
SIDE EFFECTS:
IDL color table may be changed or modified
CATEGORY:
Image processing, science planning
PREVIOUS HISTORY:
Written August 29, 1994, by Liyun Wang, NASA/GSFC
MODIFICATION HISTORY:
See image_tool.log
CONTACT:
Liyun Wang, NASA/GSFC (Liyun.Wang.1@gsfc.nasa.gov)
(See /home/drw/idl/aux/image_tool.pro)
NAME:
IMDISP
PURPOSE:
Display an image on the current graphics device.
IMDISP is an advanced replacement for TV and TVSCL.
- Supports WIN, MAC, X, CGM, PCL, PRINTER, PS, and Z graphics devices,
- Image is automatically byte-scaled (can be disabled),
- Custom byte-scaling of Pseudo color images via the RANGE keyword,
- Pseudo (indexed) color and True color images are handled automatically,
- 8-bit and 24-bit graphics devices are handled automatically,
- Decomposed color settings are handled automatically,
- Image is automatically sized to fit the display (can be disabled),
- The !P.MULTI system variable is honored for multiple image display,
- Image can be positioned via the POSITION keyword,
- Color table splitting via the BOTTOM and NCOLORS keywords,
- Image aspect ratio customization via the ASPECT keyword,
- Resized images can be resampled (default) or interpolated,
- Top down image display via the ORDER keyword (!ORDER is ignored),
- Selectable display channel (R/G/B) via the CHANNEL keyword,
- Background can be set to a specified color via the BACKGROUND keyword,
- Screen can be erased prior to image display via the ERASE keyword,
- Plot axes can be drawn on the image via the AXIS keyword,
- Photographic negative images can be displayed via the NEGATIVE keyword.
CATEGORY:
Image display
CALLING SEQUENCE:
IMDISP, IMAGE
INPUTS:
IMAGE Array containing image data.
Pseudo (indexed) color images must have 2 dimensions.
True color images must have 3 dimensions, in either
[3, NX, NY], [NX, 3, NY], or [NX, NY, 3] form.
OPTIONAL INPUTS:
None.
KEYWORD PARAMETERS:
RANGE For Pseudo Color images only, a vector with two elements
specifying the minimum and maximum values of the image
array to be considered when the image is byte-scaled
(default is minimum and maximum array values).
This keyword is ignored for True Color images,
or if the NOSCALE keyword is set.
BOTTOM Bottom value in the color table to be used
for the byte-scaled image
(default is 0).
This keyword is ignored if the NOSCALE keyword is set.
NCOLORS Number of colors in the color table to be used
for the byte-scaled image
(default is !D.TABLE_SIZE - BOTTOM).
This keyword is ignored if the NOSCALE keyword is set.
MARGIN A scalar value specifying the margin to be maintained
around the image in normal coordinates
(default is 0.1, or 0.025 if !P.MULTI is set to display
multiple images).
INTERP If set, the resized image will be interpolated using
bilinear interpolation
(default is nearest neighbor sampling).
DITHER If set, true color images will be dithered when displayed
on an 8-bit graphics device
(default is no dithering).
ASPECT A scalar value specifying the aspect ratio (height/width)
for the displayed image
(default is to maintain native aspect ratio).
POSITION On input, a 4-element vector specifying the position
of the displayed image in the form [X0,Y0,X1,Y1] in
in normal coordinates
(default is [0.0,0.0,1.0,1.0]).
See the examples below to display an image where only the
offset and size are known (e.g. MAP_IMAGE output).
OUT_POS On output, a 4-element vector specifying the position
actually used to display the image.
NOSCALE If set, the image will not be byte-scaled
(default is to byte-scale the image).
NORESIZE If set, the image will not be resized.
(default is to resize the image to fit the display).
ORDER If set, the image is displayed from the top down
(default is to display the image from the bottom up).
Note that the system variable !ORDER is always ignored.
USEPOS If set, the image will be sized to exactly fit a supplied
POSITION vector, over-riding ASPECT and MARGIN
(default is to honor ASPECT and MARGIN when a POSITION
vector is supplied).
CHANNEL Display channel (Red, Green, or Blue) to be written.
0 => All channels (the default)
1 => Red channel
2 => Green channel
3 => Blue channel
This keyword is only recognized by graphics devices which
support 24-bit decomposed color (WIN, MAC, X). It is ignored
by all other graphics devices. However True color (RGB)
images can be displayed on any device supported by IMDISP.
BACKGROUND If set to a positive integer, the background will be filled
with the color defined by BACKGROUND.
ERASE If set, the screen contents will be erased. Note that if
!P.MULTI is set to display multiple images, the screen is
always erased when the first image is displayed.
AXIS If set, plot axes will be drawn on the image. The default
x and y axis ranges are determined by the size of the image.
When the AXIS keyword is set, IMDISP accepts any keywords
supported by PLOT (e.g. TITLE, COLOR, CHARSIZE etc.).
NEGATIVE If set, a photographic negative of the image is displayed.
The values of BOTTOM and NCOLORS are honored. This keyword
allows True color images scanned from color negatives to be
displayed. It also allows Pseudo color images to be displayed
as negatives without reversing the color table. This keyword
is ignored if the NOSCALE keyword is set.
OUTPUTS:
None.
OPTIONAL OUTPUTS:
None
COMMON BLOCKS:
None
SIDE EFFECTS:
The image is displayed on the current graphics device.
RESTRICTIONS:
Requires IDL 5.0 or higher (square bracket array syntax).
EXAMPLE:
;- Load test data
openr, lun, filepath('ctscan.dat', subdir='examples/data'), /get_lun
ctscan = bytarr(256, 256)
readu, lun, ctscan
free_lun, lun
openr, lun, filepath('hurric.dat', subdir='examples/data'), /get_lun
hurric = bytarr(440, 330)
readu, lun, hurric
free_lun, lun
read_jpeg, filepath('rose.jpg', subdir='examples/data'), rose
help, ctscan, hurric, rose
;- Display single images
!p.multi = 0
loadct, 0
imdisp, hurric, /erase
wait, 3.0
imdisp, rose, /interp, /erase
wait, 3.0
;- Display multiple images without color table splitting
;- (works on 24-bit displays only; top 2 images are garbled on 8-bit displays)
!p.multi = [0, 1, 3, 0, 0]
loadct, 0
imdisp, ctscan, margin=0.02
loadct, 13
imdisp, hurric, margin=0.02
imdisp, rose, margin=0.02
wait, 3.0
;- Display multiple images with color table splitting
;- (works on 8-bit or 24-bit displays)
!p.multi = [0, 1, 3, 0, 0]
loadct, 0, ncolors=64, bottom=0
imdisp, ctscan, margin=0.02, ncolors=64, bottom=0
loadct, 13, ncolors=64, bottom=64
imdisp, hurric, margin=0.02, ncolors=64, bottom=64
imdisp, rose, margin=0.02, ncolors=64, bottom=128
wait, 3.0
;- Display an image at a specific position, over-riding aspect and margin
!p.multi = 0
loadct, 0
imdisp, hurric, position=[0.0, 0.0, 1.0, 0.5], /usepos, /erase
wait, 3.0
;- Display an image with axis overlay
!p.multi = 0
loadct, 0
imdisp, rose, /axis, /erase
wait, 3.0
;- Display an image with contour plot overlay
!p.multi = 0
loadct, 0
imdisp, hurric, out_pos=out_pos, /erase
contour, smooth(hurric, 10, /edge), /noerase, position=out_pos, $
xstyle=1, ystyle=1, levels=findgen(5)*40.0, /follow
wait, 3.0
;- Display a small image with correct resizing
!p.multi = 0
loadct, 0
data = (dist(8))[1:7, 1:7]
imdisp, data, /erase
wait, 3.0
imdisp, data, /interp
wait, 3.0
;- Display a true color image without and with interpolation
!p.multi = 0
imdisp, rose, /erase
wait, 3.0
imdisp, rose, /interp
wait, 3.0
;- Display a true color image as a photographic negative
imdisp, rose, /negative, /erase
wait, 3.0
;- Display a true color image on PostScript output
;- (note that color table is handled automatically)
current_device = !d.name
set_plot, 'PS'
device, /color, bits_per_pixel=8, filename='imdisp_true.ps'
imdisp, rose, /axis, title='PostScript True Color Output'
device, /close
set_plot, current_device
;- Display a pseudo color image on PostScript output
current_device = !d.name
set_plot, 'PS'
device, /color, bits_per_pixel=8, filename='imdisp_pseudo.ps'
loadct, 0
imdisp, hurric, /axis, title='PostScript Pseudo Color Output'
device, /close
set_plot, current_device
;- Display an image where only the offset and size are known
;- Read world elevation data
file = filepath('worldelv.dat', subdir='examples/data')
openr, lun, file, /get_lun
data = bytarr(360, 360)
readu, lun, data
free_lun, lun
;- Reorganize array so it spans 180W to 180E
world = data
world[0:179, *] = data[180:*, *]
world[180:*, *] = data[0:179, *]
;- Create remapped image
map_set, /orthographic, /isotropic, /noborder
remap = map_image(world, x0, y0, xsize, ysize, compress=1)
;- Convert offset and size to position vector
pos = fltarr(4)
pos[0] = x0 / float(!d.x_vsize)
pos[1] = y0 / float(!d.y_vsize)
pos[2] = (x0 + xsize) / float(!d.x_vsize)
pos[3] = (y0 + ysize) / float(!d.y_vsize)
;- Display the image
loadct, 0
imdisp, remap, pos=pos, /usepos
map_continents
map_grid
MODIFICATION HISTORY:
Liam.Gumley@ssec.wisc.edu
http://cimss.ssec.wisc.edu/~gumley
$Id: imdisp.pro,v 1.45 2000/08/28 16:17:14 gumley Exp $
Copyright (C) 1999, 2000 Liam E. Gumley
This program is free software; you can redistribute it and/or
modify it under the terms of the GNU General Public License
as published by the Free Software Foundation; either version 2
of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
(See /home/drw/idl/aux/imdisp.pro)
RUN ME TO GET THE ERRORS IN THE INHOMOGENEOUSLY-CALCULATED OPTICAL DEPTH USING THE ESCAPE PROBABILITY RATIOS INCLUDED BELOW CALLING SEQUENCE: inhom_probratio INPUTS/OUTPUTS: None KEYWORDS: None HISTORY: DRW - in a fit of panic, 5/02/02
(See /home/drw/idl/gen/inhom_probratio.pro)
NAME:
INPUTFORM
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Generates expression string from an IDL value
CALLING SEQUENCE:
STRING = INPUTFORM(VALUE, ERRMSG=ERRMSG, STATUS=STATUS, ...)
DESCRIPTION:
The INPUTFORM function converts an IDL data value into its string
representation, suitable for execution at the IDL command line or
with EXECUTE(). This is similar to the "InForm" output
representation of Mathematica, which formats output so that it can
be entered again on the command line. INPUTFORM() is a
specialized form of STRING().
For example, the value DBLARR(2,2) has the representation
'[[0,0],[0,0]]'
The formal goal of INPUTFORM is for the resulting textual
expression to be an exact represetation of the original data.
Therefore, given the original value VARIABLE, then after executing
R = EXECUTE( 'variable1 = '+INPUTFORM(variable) )
The value, type, and dimension of VARIABLE1 and VARIABLE will be
the same.
Such behavior might useful in several circumstances:
* for printing values meant to be "pasted" back into the
command line by the user;
* for constructing command arguments to be EXECUTE()'d;
* for saving values in ASCII format for later execution.
However, it should be noted that the IDL parser is not perfect.
While IDL has many data types, not all expressions are
representable as a textual string. For example, the value of
pointers cannot be printed. Examples of the parser limitation
include,
* pointers have no textual representation;
* array expressions can have no more than 90 elements;
* bracketed array notation cannot be nested too deeply;
* anonymous structure arrays have no textual representation;
Given these limitations, the user of this routine must be prepared
for failure and have contingency plans. Error messages and status
indicators are provided to facilitate this. INPUTFORM() does not
call MESSAGE, so it should never intentionally crash.
Also, consider that the textual representation can never really be
suitable for very large arrays. The internal algorithm is thus
not optimized for speed as heavily numeric routines might be, and
instead tries to make the output slightly more readable.
INPUTS:
VALUE - the IDL value to be converted. Any value which has a
legal textual representation is permitted.
KEYWORDS:
STATUS - upon return, a status indicator. A value of zero
indicates failure; one indicates success.
ERRMSG - upon return, a string message indicating the reason for a
failure, if any. The empty string ('') indicates
success.
MAX_ELEMENTS - maximum number of elements permitted in VALUE. The
conversion fails if the maximum is exceeded.
Default: any number of elements is permitted.
NOTE: the conversion may still fail if any array
dimension exceeds 90.
MAX_DIMENSIONS - maximum number of array dimensions permitted in
VALUE. The conversion fails if the maximum is
exceeded.
Default: any number of dimensions is permitted.
NOTE: IDL does not permit deep nesting, for
dimensions greater than three.
MAX_TAGS - maximum number of structure tags permitted in VALUE.
The conversion fails if the maximum is exceeded.
Default: any number of tags is permitted.
MAX_LEN - approximate maximum length of returned string. If large
string expressions exceed this size as they are being
composed internally, they will be terminated by a '...'
ellipsis and returned. This value is to be used as a
guideline by INPUTFORM(); the precise limit may not be
adhered to.
Default: 16384L
RETURNS:
The resulting converted string, if successful. Upon failure,
STATUS is set to zero and the empty string ('') is returned.
EXAMPLE:
Convert a double array to text
IDL> x = dblarr(2,2)
IDL> print, inputform(x)
[[0D,0],[0D,0]]
Convert a structure
IDL> x = create_struct('s1',5,'s2','strvalue','s3',intarr(3))
IDL> print, inputform(x)
[{S1:5,S2:'strvalue',S3:[0,0,0]}]
SEE ALSO:
STRING, PRINT, HELP, HELPFORM
MODIFICATION HISTORY:
Written, CM, 10 Apr 2000
Added HELPFORM to SEE ALSO, CM, 04 Jul 2000
Corrected case of scalar float value, CM, 13 Jul 2000
Put a space after float types like 1E or 1D to ease parsing, CM,
18 Jul 2000
(See /home/drw/idl/esrg/inputform.pro)
NAME:
INPUTFORM
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Generates expression string from an IDL value
CALLING SEQUENCE:
STRING = INPUTFORM(VALUE, ERRMSG=ERRMSG, STATUS=STATUS, ...)
DESCRIPTION:
The INPUTFORM function converts an IDL data value into its string
representation, suitable for execution at the IDL command line or
with EXECUTE(). This is similar to the "InForm" output
representation of Mathematica, which formats output so that it can
be entered again on the command line. INPUTFORM() is a
specialized form of STRING().
For example, the value DBLARR(2,2) has the representation
'[[0,0],[0,0]]'
The formal goal of INPUTFORM is for the resulting textual
expression to be an exact represetation of the original data.
Therefore, given the original value VARIABLE, then after executing
R = EXECUTE( 'variable1 = '+INPUTFORM(variable) )
The value, type, and dimension of VARIABLE1 and VARIABLE will be
the same.
Such behavior might useful in several circumstances:
* for printing values meant to be "pasted" back into the
command line by the user;
* for constructing command arguments to be EXECUTE()'d;
* for saving values in ASCII format for later execution.
However, it should be noted that the IDL parser is not perfect.
While IDL has many data types, not all expressions are
representable as a textual string. Pointers and objects can be
represented. Examples of the parser limitation include,
* array expressions can have no more than 90 elements;
* bracketed array notation cannot be nested too deeply;
* anonymous structure arrays have no textual representation;
Given these limitations, the user of this routine must be prepared
for failure and have contingency plans. Error messages and status
indicators are provided to facilitate this. INPUTFORM() does not
call MESSAGE, so it should never intentionally crash.
Also, consider that the textual representation can never really be
suitable for very large arrays. The internal algorithm is thus
not optimized for speed as heavily numeric routines might be, and
instead tries to make the output slightly more readable.
INPUTS:
VALUE - the IDL value to be converted. Any value which has a
legal textual representation is permitted.
KEYWORDS:
STATUS - upon return, a status indicator. A value of zero
indicates failure; one indicates success.
ERRMSG - upon return, a string message indicating the reason for a
failure, if any. The empty string ('') indicates
success.
MAX_ELEMENTS - maximum number of elements permitted in VALUE. The
conversion fails if the maximum is exceeded.
Default: any number of elements is permitted.
NOTE: the conversion may still fail if any array
dimension exceeds 90.
MAX_DIMENSIONS - maximum number of array dimensions permitted in
VALUE. The conversion fails if the maximum is
exceeded.
Default: any number of dimensions is permitted.
NOTE: IDL does not permit deep nesting, for
dimensions greater than three.
MAX_TAGS - maximum number of structure tags permitted in VALUE.
The conversion fails if the maximum is exceeded.
Default: any number of tags is permitted.
MAX_LEN - approximate maximum length of returned string. If large
string expressions exceed this size as they are being
composed internally, they will be terminated by a '...'
ellipsis and returned. This value is to be used as a
guideline by INPUTFORM(); the precise limit may not be
adhered to.
Default: 16384L
RETURNS:
The resulting converted string, if successful. Upon failure,
STATUS is set to zero and the empty string ('') is returned.
EXAMPLE:
Convert a double array to text
IDL> x = dblarr(2,2)
IDL> print, inputform(x)
[[0D,0],[0D,0]]
Convert a structure
IDL> x = create_struct('s1',5,'s2','strvalue','s3',intarr(3))
IDL> print, inputform(x)
[{S1:5,S2:'strvalue',S3:[0,0,0]}]
SEE ALSO:
STRING, PRINT, HELP, HELPFORM
MODIFICATION HISTORY:
Written, CM, 10 Apr 2000
Added HELPFORM to SEE ALSO, CM, 04 Jul 2000
Corrected case of scalar float value, CM, 13 Jul 2000
Put a space after float types like 1E or 1D to ease parsing, CM,
18 Jul 2000
Add ability to print INPUTFORM of pointers, CM, 09 Dec 2002
Add ability to print INPUTFORM of object pointers, CM, 01 Oct 2003
$Id: inputform.pro,v 1.4 2003/10/03 21:55:59 craigm Exp $
(See /home/drw/idl/aux/markwardt/inputform.pro)
ROUTINE: inside
USEAGE: RESULT = inside(xx,yy)
RESULT = inside(xx,yy,xpoly,ypoly,nbin=nbin)
PURPOSE: find the indices of the data quantities xx and yy which
lie inside a given polygonal region
INPUT:
xx vector of quantity x, ploted on x axis of scatter plot
yy vector of quantity y, ploted on y axis of scatter plot
OPTIONAL INPUT:
xpoly vector of x coordinates vertices of polygon
ypoly vector of y coordinates vertices of polygon
OPTIONAL KEYWORD INPUT:
psym if set, selected points are marked with symbol psym.
if psym=3, the screen is erased and a new plot is drawn.
this only works if the boundaries are specified
interactively.
nbin number of bins with which to resolve the polygon.
A two element vector may be used to specify number
in x and y directions seperately. (DEFAULT = 100)
OUTPUT:
returned value = vector of array indecies inside polygon
PROCEDURE: If xpoly and ypoly are not supplied, the operator
specifies the region using the interactive graphics
procedure, TRACE.
EXAMPLE
x=randomn(seed,20,20)
y=sin(5*x)+.8*randomn(seed,20,20)
plot,x,y,psym=3
i1=inside(x,y,psym=4) ; the indecies of the data points
i2=inside(x,y,psym=5) ; which are inside polygonal area
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/esrg/inside.pro)
ROUTINE: inside
USEAGE: RESULT = inside(xx,yy)
RESULT = inside(xx,yy,xpoly,ypoly,nbin=nbin)
PURPOSE: find the indices of the data quantities xx and yy which
lie inside a given polygonal region
INPUT:
xx vector of quantity x, ploted on x axis of scatter plot
yy vector of quantity y, ploted on y axis of scatter plot
OPTIONAL INPUT:
xpoly vector of x coordinates vertices of polygon
ypoly vector of y coordinates vertices of polygon
OPTIONAL KEYWORD INPUT:
psym if set, selected points are marked with symbol psym.
if psym=3, the screen is erased and a new plot is drawn.
this only works if the boundaries are specified
interactively.
nbin number of bins with which to resolve the polygon.
A two element vector may be used to specify number
in x and y directions seperately. (DEFAULT = 100)
OUTPUT:
returned value = vector of array indecies inside polygon
PROCEDURE: If xpoly and ypoly are not supplied, the operator
specifies the region using the interactive graphics
procedure, TRACE.
EXAMPLE
x=randomn(seed,20,20)
y=sin(5*x)+.8*randomn(seed,20,20)
plot,x,y,psym=3
i1=inside(x,y,psym=4) ; the indecies of the data points
i2=inside(x,y,psym=5) ; which are inside polygonal area
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/old.esrg/inside.pro)
*NAME:
INTEG OCTOBER 3, 1980
*CLASS:
integration
*CATEGORY:
*PURPOSE:
To numerically integrate tabulated data using the trapezoid rule.
*CALLING SEQUENCE:
INTEG,X,Y,IMIN,IMAX,SUM
*PARAMETERS:
X (REQ) (I) (1) (I L F D)
Required input vector of argument values
Y (REQ) (I) (1) (I L F D)
Required input vector of function values
IMIN (REQ) (I) (0) (F)
Required input scalar containing the effective index of the
lower limit of the integration.
IMAX (REQ) (I) (0) (F)
Required input scalar containing the effective index of the
upper limit of the integration.
SUM (REQ) (O) (0) (F)
Required output scalar parameter containing the definite
integral of Y between X(IMIN) and X(IMAX).
*EXAMPLES:
Integrate the flux of the CIV feature in a spectrum
(WAVE vs FLUX) with integration limits of 1545 and
1555 Angstroms.
TABINV,WAVE,1545.0,IMIN
TABINV,WAVE,1555.0,IMAX
INTEG,WAVE,FLUX,IMIN,IMAX,FLUXC4
*SYSTEM VARIABLES USED:
None
*INTERACTIVE INPUT:
None
*SUBROUTINES CALLED:
*FILES USED:
None
*SIDE EFFECTS:
None
*RESTRICTIONS:
None
*NOTES:
IMIN and IMAX may have non-integer values
*PROCEDURE:
The trapezoid rule is used.
*MODIFICATION HISTORY:
Jan 14 1981 I. Ahmad GSFC initial program
Jun 5 1987 RWT GSFC add PARCHECK and remove EXTRACTs
Mar 14 1988 CAG GSFC add VAX RDAF-style prolog
(See /home/drw/idl/fuse/integ.pro)
ROUTINE: integral
USEAGE: result=integral(x,y,xrange=xrange,accumulate=accumulate)
PURPOSE: integration by trapezoid rule
INPUT:
x vector of x axis points. If XRANGE is not set,
limits of integration will be from x(0) to x(n_elements(x)-1)
If XRANGE is not set, X need not be monitonic.
y vector of corresponding y axis points
KEYWORD_INPUT:
xrange 2 element vector, lower and upper limit of integration
The use of XRANGE with a non-monitonic variation in x may
produce incorrect results.
accumulate if set, return value is a vector giving the accumulated
integral at each value of x. XRANGE can't be used when
this option is set.
OUTPUT: result of integration
EXAMPLE:
; /4
; find | x dx
; /0
x=findgen(5) & y=x
print,integral(x,y)
8.00000 ; answer for linear integrand is exact
; /5.5
; find | x^2 dx
; /0
x=findgen(7) & y=x^2 &$
print," numerical analytic" &$
print,integral(x,y,xrange=[0,5.5]), 5.5^3/3
56.3750 55.4583
; use more resolution in x to improve answer
x=findgen(551)/100. & y=x^2 &$
print," numerical analytic" &$
print,integral(x,y), 5.5^3/3
55.4584 55.4583 ; much better
author: Paul Ricchiazzi 3NOV92
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
sep93: fixed error in treatment of xrange, added examples
apr96: allow use of xrange with monitonically decreasing x
(See /home/drw/idl/esrg/integral.pro)
ROUTINE: integral
USEAGE: result=integral(x,y,xrange=xrange,accumulate=accumulate)
PURPOSE: integration by trapezoid rule
INPUT:
x vector of x axis points. If XRANGE is not set,
limits of integration will be from x(0) to x(n_elements(x)-1)
If XRANGE is not set, X need not be monitonic.
y vector of corresponding y axis points
KEYWORD_INPUT:
xrange 2 element vector, lower and upper limit of integration
The use of XRANGE with a non-monitonic variation in x may
produce incorrect results.
accumulate if set, return value is a vector giving the accumulated
integral at each value of x. XRANGE can't be used when
this option is set.
OUTPUT: result of integration
EXAMPLE:
; /4
; find | x dx
; /0
x=findgen(5) & y=x
print,integral(x,y)
8.00000 ; answer for linear integrand is exact
; /5.5
; find | x^2 dx
; /0
x=findgen(7) & y=x^2 &$
print," numerical analytic" &$
print,integral(x,y,xrange=[0,5.5]), 5.5^3/3
56.3750 55.4583
; use more resolution in x to improve answer
x=findgen(551)/100. & y=x^2 &$
print," numerical analytic" &$
print,integral(x,y), 5.5^3/3
55.4584 55.4583 ; much better
author: Paul Ricchiazzi 3NOV92
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
sep93: fixed error in treatment of xrange, added examples
apr96: allow use of xrange with monitonically decreasing x
(See /home/drw/idl/old.esrg/integral.pro)
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: INTEGRAL_CALC
PURPOSE:
To compute the atomic data integral for use in column or volume
emission measure work.
CATEGORY:
Scientific analysis
EXPLANATION:
Defining
G(T) = 0.83 * Fr(T) * N_j * A_ji / N_e
where Fr(T) is the ionisation fraction (e.g., from Arnaud &
Rothenflug), N_j the relative population of level j, A_ji the
A-value for the j->i transition and N_e the electron density. The
0.83 is the ratio of hydrogen to free electrons, which is constant
above around 10^4 K. This function is sharply-peaked at a
temperature T_mem (the temperature of maximum emission, which can
be different from the temperature of maximum ionisation, T_max)
and so an oft-used approximation is to take G(T) constant in the
range log T_mem - 0.15 to log T_mem + 0.15 and zero outside. The
value of the constant, which we call C_lambda here, is then given
by
C_lambda = integral { G(T) dT }
--------------------
T_mem * (10^0.15 - 10^-0.15)
If EM(s) is the column emission measure, F the flux (erg cm-2 s-1)
in a line lambda, Ab the abundance of the element and DE (erg) the
energy for the transition, then:
F = DE * Ab * C_lambda * EM(s)
If we are dealing with intensities I (erg cm-2 s-1 sr-1) then:
4pi * I = DE * Ab * C_lambda * EM(s)
This program extracts the ionisation balance and emissivities from
the CHIANTI database and calculates C_lambda for all lines in the
specified wavelength interval WRANGE by integrating over
0.02 dex temperature intervals, using the IDL INT_TABULATED function.
The C_lambda functions for all the lines in the selected wavelength
range WRANGE are displayed as well as the temperature of maximum
emission (T_mem), DE*C_lambda and 4pi/(DE*C_lambda). These latter
two quantities are useful for the emission measure analysis.
Any combination of the displayed lines can then be blended and the
corresponding quantities for the blend will be displayed.
The function Fr(T) * N_j * A_ji can also be plotted at this stage.
CALLING SEQUENCE:
INTEGRAL_CALC, IZ, ION, WRANGE [, /RAY, DENS=DENS]
EXAMPLES:
INTEGRAL_CALC, 26, 13, [200,205], /RAY
INTEGRAL_CALC, 14, 10, [250,270], DENS=10.
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
WRANGE: Wavelength range for which C_lambda functions are calculated.
OPTIONAL INPUTS:
DENS: The density at which the emissivities are calculated
(default=10.)
KEYWORDS:
RAY: Use the Arnaud & Raymond ion balance instead of
Arnaud & Rothenflug.
OPTIONAL OUTPUTS:
TEMPI: If the G(T) function is to be plotted, then this variable will
contain the X-axis of the plot...
GOFT: ...and this will contain the Y-axis. Note that the plotted
quantity is N_j * A_ji * Fr(T).
COMMON BLOCKS:
None.
CALLS:
EMISS_CALC, READ_IONEQ
HISTORY:
Ver.1: PRY, 28-JUN-97.
Ver.2: PRY, 7-OCT-97. Added TEMPI and GOFT, for plotting.
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/integral_calc.pro)
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: INTEGRAL_CALC
PURPOSE:
To compute the atomic data integral for use in column or volume
emission measure work.
CATEGORY:
Scientific analysis
EXPLANATION:
Defining
G(T) = 0.83 * Fr(T) * N_j * A_ji / N_e
where Fr(T) is the ionisation fraction (e.g., from Arnaud &
Rothenflug), N_j the relative population of level j, A_ji the
A-value for the j->i transition and N_e the electron density. The
0.83 is the ratio of hydrogen to free electrons, which is constant
above around 10^4 K. This function is sharply-peaked at a
temperature T_mem (the temperature of maximum emission, which can
be different from the temperature of maximum ionisation, T_max)
and so an oft-used approximation is to take G(T) constant in the
range log T_mem - 0.15 to log T_mem + 0.15 and zero outside. The
value of the constant, which we call C_lambda here, is then given
by
C_lambda = integral { G(T) dT }
--------------------
T_mem * (10^0.15 - 10^-0.15)
If EM(s) is the column emission measure, F the flux (erg cm-2 s-1)
in a line lambda, Ab the abundance of the element and DE (erg) the
energy for the transition, then:
F = DE * Ab * C_lambda * EM(s)
If we are dealing with intensities I (erg cm-2 s-1 sr-1) then:
4pi * I = DE * Ab * C_lambda * EM(s)
This program extracts the ionisation balance and emissivities from
the CHIANTI database and calculates C_lambda for all lines in the
specified wavelength interval WRANGE by integrating over
0.02 dex temperature intervals, using the IDL INT_TABULATED function.
The C_lambda functions for all the lines in the selected wavelength
range WRANGE are displayed as well as the temperature of maximum
emission (T_mem), DE*C_lambda and 4pi/(DE*C_lambda). These latter
two quantities are useful for the emission measure analysis.
Any combination of the displayed lines can then be blended and the
corresponding quantities for the blend will be displayed.
The function Fr(T) * N_j * A_ji can also be plotted at this stage.
CALLING SEQUENCE:
INTEGRAL_CALC, IZ, ION, WRANGE [, /RAY, DENS=DENS]
EXAMPLES:
INTEGRAL_CALC, 26, 13, [200,205], /RAY
INTEGRAL_CALC, 14, 10, [250,270], DENS=10.
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
WRANGE: Wavelength range for which C_lambda functions are calculated.
OPTIONAL INPUTS:
DENS: The density at which the emissivities are calculated
(default=10.)
KEYWORDS:
RAY: Use the Arnaud & Raymond ion balance instead of
Arnaud & Rothenflug.
OPTIONAL OUTPUTS:
TEMPI: If the G(T) function is to be plotted, then this variable will
contain the X-axis of the plot...
GOFT: ...and this will contain the Y-axis. Note that the plotted
quantity is N_j * A_ji * Fr(T).
COMMON BLOCKS:
None.
CALLS:
EMISS_CALC, READ_IONEQ
HISTORY:
Ver.1: PRY, 28-JUN-97.
Ver.2: PRY, 7-OCT-97. Added TEMPI and GOFT, for plotting.
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/ptg/integral_calc.pro)
NAME:
INTERPOL
PURPOSE:
Linear interpolation for vectors.
Regular or irregular grid.
CATEGORY:
E1 - Interpolation
CALLING SEQUENCE:
Result = INTERPOL( V, X, U) ;Irregular grids
Result = INTERPOL( V, N) ;Regular grids
INPUTS:
V = input vector, should be one dimensional,
any type except string.
Regular grids:
N = Number of points of result, both input and
output grids are regular. Output grid
absicissa value = float(i)/N_elements(V),
for i=0,n-1.
Irregular grids:
X = Absicissae values for V. Must have same # of
elements as V. MUST be monotonic, either
ascending or descending.
U = Absicissae values for result. Result will
have same number of elements as U. U need
not be monotonic.
OPTIONAL INPUT PARAMETERS:
None.
OUTPUTS:
Result = Floating vector of N points determined
from linearly interpolating input vector.
If V is double or complex, result is double
or complex.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Result(i) = V(x) + (x-FIX(x))*(V(x+1)-V(x))
where x = i*(m-1)/(N-1) for regular grids.
m = # of elements in V, i=0 to N-1.
For irregular grids, x = U(i).
m = number of points of input vector.
MODIFICATION HISTORY:
Written, DMS, October, 1982.
Modified, Terry J. Armitage and Janet Ferguson, March 1989. Modified
counters ix and i to handle vectors larger than 32767.
(See /home/drw/idl/icur/interpol.pro)
ROUTINE: interp
PURPOSE: interpolate on a table of up to 5 dimensions
USEAGE: result=interp(table,utab,u,[vtab,v,[xtab,x,[ytab,y,[ztab,z]]]])
INPUT:
table table of values depending on upto 5 parameters
utab 1-d (monitonically increasing) table of 1st parameter
u array of values of 1st parameter
vtab 1-d (monitonically increasing) table of 2nd parameter
v array of values of 2nd parameter
xtab 1-d (monitonically increasing) table of 3rd parameter
x array of values of 3rd parameter
ytab 1-d (monitonically increasing) table of 4th parameter
y array of values of 4th parameter
ztab 1-d (monitonically increasing) table of 5th parameter
z array of values of 5th parameter
NOTE: the number of input parameters must be appropriate to
the size of the look-up table. For example for a 3-d table,
parameters ytab,y,ztab, and z should not be supplied.
KEYWORD INPUT:
GRID if set the input parameters are used to create a grid of
parameter values. In this case the input parameters need not
be all the same size but should all be vectors. If GRID is
not set all input arrays (u,v,x,y,z) and the returned value
are of the same size and dimensionality.
MISSING The value to return for ARRAY elements outside the bounds
of TABLE. If MISSING is not set return value is either
the nearest value of TABLE or an extrapolated value, depending
on how CLIP is set.
CLIP If this keyword is set, locations less than the minimum or
greater than the maximum corresponding subscript of TABLE
are set to the nearest element of TABLE. The effect of
MISSING is disabled when CLIP is set.
i1...i5
f1...f5 these keywords are used in conjunction with the use_if
keyword. If use_if is not set, the i's and f's are
calculated and returned. If use_if is set, the i's and
f's are not calculated but taken from the keywords.
This is useful when there exists multiple TABLEs based
on the same dimensions and variables, and one wishes to
improve the performance. In this case, the first time
INTERP is called, the i's and f's are specified in the
call but use_if is not set. In subsequent calls, use_if
is set.
use_if keyword to indicate that i's and f's should not be calculated
but rather are input by user
OUTPUT:
result interpolated value
PROCEDURE: FINDEX is used to compute the floating point interpolation
factors into lookup table TABLE. When the dimensionality
of TABLE is 3 or less and either CLIP or MISSING is set,
then IDL library procedure INTERPOLATE is used to perform the
actual interpolations. Otherwise the interpolations are
explicitly carried out as mono-, bi-, tri-, tetra- or
penta-linear interpolation, depending on the
dimensionality of TABLE.
EXAMPLE:
; Here is an example of how to interpolate into a large DISORT
; radiance lookup table to find radiance at given values of optical
; depth, surface albedo, relative azimuth, satellite zenith
; angle and solar zenith angle.
file='~paul/palmer/runs/0901a.dat'
readrt20,file,winf,wsup,phidw,topdn,topup,topdir,botdn,botup,botdir,$
phi,theta,rad,tau,salb,sza
phi=phi(*,0,0,0)
theta=theta(*,0,0,0)
tauv=alog(1.25^findgen(20)+1.)
taut=alog(tau+1.)
sa0=findgen(10)*.1
; rel azimuth sat_zen surface_albedo
p0=130 & t0=20 & s0=60
buf=interp(rad,phi,p0,theta,t0,taut,tauv,salb,sa0,sza,s0,/grid)
plot,exp(tauv)-1.,buf(0,0,*,9)
for i=0,8 do oplot,exp(tauv)-1.,buf(0,0,*,i)
An example for use_if:
DISORT is used to build two look up tables, RTM_bb_botdn and RTM_bb_topdn,
based on the same parameters of tau, sza, wv, and o3. Given measurements
of these variables, BOTDN and TOPDN can be interpolated. However, since
the measurements are the same, and the LUTs are built similarly, it is
redundant to calculate the i's and f's twice.
bb_botdn = interp(RTM_bb_botdn, $
RTM_bb_tau, all_tau_arr, $
RTM_bb_sza, all_sza_arr, $
RTM_bb_wv, all_wv_arr , $
RTM_bb_o3, all_o3_arr, $
i1=i1,f1=f1,i2=i2,f2=f2,i3=i3,f3=f3,i4=i4,f4=f4)
bb_topdn = interp(RTM_bb_topdn, $
RTM_bb_tau, all_tau_arr, $
RTM_bb_sza, all_sza_arr, $
RTM_bb_wv, all_wv_arr , $
RTM_bb_o3, all_o3_arr, $
i1=i1,f1=f1,i2=i2,f2=f2,i3=i3,f3=f3,i4=i4,f4=f4,/use_if)
author: Paul Ricchiazzi sep93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/interp.pro)
ROUTINE: interp
PURPOSE: interpolate on a table of up to 5 dimensions
USEAGE: result=interp(table,utab,u,[vtab,v,[xtab,x,[ytab,y,[ztab,z]]]])
INPUT:
table table of values depending on upto 5 parameters
utab 1-d (monitonically increasing) table of 1st parameter
u array of values of 1st parameter
vtab 1-d (monitonically increasing) table of 2nd parameter
v array of values of 2nd parameter
xtab 1-d (monitonically increasing) table of 3rd parameter
x array of values of 3rd parameter
ytab 1-d (monitonically increasing) table of 4th parameter
y array of values of 4th parameter
ztab 1-d (monitonically increasing) table of 5th parameter
z array of values of 5th parameter
NOTE: the number of input parameters must be appropriate to
the size of the look-up table. For example for a 3-d table,
parameters ytab,y,ztab, and z should not be supplied.
KEYWORD INPUT:
GRID if set the input parameters are used to create a grid of
parameter values. In this case the input parameters need not
be all the same size but should all be vectors. If GRID is
not set all input arrays (u,v,x,y,z) and the returned value
are of the same size and dimensionality.
MISSING The value to return for ARRAY elements outside the bounds
of TABLE. If MISSING is not set return value is either
the nearest value of TABLE or an extrapolated value, depending
on how CLIP is set.
CLIP If this keyword is set, locations less than the minimum or
greater than the maximum corresponding subscript of TABLE
are set to the nearest element of TABLE. The effect of
MISSING is disabled when CLIP is set.
i1...i5
f1...f5 these keywords are used in conjunction with the use_if
keyword. If use_if is not set, the i's and f's are
calculated and returned. If use_if is set, the i's and
f's are not calculated but taken from the keywords.
This is useful when there exists multiple TABLEs based
on the same dimensions and variables, and one wishes to
improve the performance. In this case, the first time
INTERP is called, the i's and f's are specified in the
call but use_if is not set. In subsequent calls, use_if
is set.
use_if keyword to indicate that i's and f's should not be calculated
but rather are input by user
OUTPUT:
result interpolated value
PROCEDURE: FINTERP is used to compute the floating point interpolation
factors into lookup table TABLE. When the dimensionality
of TABLE is 3 or less and either CLIP or MISSING is set,
then IDL library procedure INTERPOLATE is used to perform the
actual interpolations. Otherwise the interpolations are
explicitly carried out as mono-, bi-, tri-, tetra- or
penta-linear interpolation, depending on the
dimensionality of TABLE.
EXAMPLE:
; Here is an example of how to interpolate into a large DISORT
; radiance lookup table to find radiance at given values of optical
; depth, surface albedo, relative azimuth, satellite zenith
; angle and solar zenith angle.
file='~paul/palmer/runs/0901a.dat'
readrt20,file,winf,wsup,phidw,topdn,topup,topdir,botdn,botup,botdir,$
phi,theta,rad,tau,salb,sza
phi=phi(*,0,0,0)
theta=theta(*,0,0,0)
tauv=alog(1.25^findgen(20)+1.)
taut=alog(tau+1.)
sa0=findgen(10)*.1
; rel azimuth sat_zen surface_albedo
p0=130 & t0=20 & s0=60
buf=interp(rad,phi,p0,theta,t0,taut,tauv,salb,sa0,sza,s0,/grid)
plot,exp(tauv)-1.,buf(0,0,*,9)
for i=0,8 do oplot,exp(tauv)-1.,buf(0,0,*,i)
An example for use_if:
DISORT is used to build two look up tables, RTM_bb_botdn and RTM_bb_topdn,
based on the same parameters of tau, sza, wv, and o3. Given measurements
of these variables, BOTDN and TOPDN can be interpolated. However, since
the measurements are the same, and the LUTs are built similarly, it is
redundant to calculate the i's and f's twice.
bb_botdn = interp(RTM_bb_botdn, $
RTM_bb_tau, all_tau_arr, $
RTM_bb_sza, all_sza_arr, $
RTM_bb_wv, all_wv_arr , $
RTM_bb_o3, all_o3_arr, $
i1=i1,f1=f1,i2=i2,f2=f2,i3=i3,f3=f3,i4=i4,f4=f4)
bb_topdn = interp(RTM_bb_topdn, $
RTM_bb_tau, all_tau_arr, $
RTM_bb_sza, all_sza_arr, $
RTM_bb_wv, all_wv_arr , $
RTM_bb_o3, all_o3_arr, $
i1=i1,f1=f1,i2=i2,f2=f2,i3=i3,f3=f3,i4=i4,f4=f4,/use_if)
author: Paul Ricchiazzi sep93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/interp.pro)
ROUTINE: intersection
PURPOSE: calculate the closest 2 points in two arrays
USEAGE: result = intersection(x0, y0, x1, y1)
INPUT:
x0,x1 index for y0,index for y1
y0,y1 y values
OUTPUT: four element array containing the (x,y) values
the two closest points.
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/bin/intersection.pro)
ROUTINE: intersection
PURPOSE: calculate the closest 2 points in two arrays
USEAGE: result = intersection(x0, y0, x1, y1)
INPUT:
x0,x1 index for y0,index for y1
y0,y1 y values
OUTPUT: four element array containing the (x,y) values
the two closest points.
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/bin/ptg/intersection.pro)
NAME:
INTERSECT
PURPOSE:
Return the an array that is the intersection of the two input arrays.
CATEGORY:
Array manipulation.
CALLING SEQUENCE:
x = INTERSECT(array1, array2)
INPUTS:
Arrays The arrays to be scanned. The type and number of dimensions
of the array are not important.
OPTIONAL INPUTS:
nodata: This is the value returned if no value in the both of the
arrays. The default is -1.
xor_flag if this keyword is set, only values are returned that belong
to one array or the other, but not both,
i.e., the complement of the set of intersection.
OUTPUTS:
result = An array of the values
EXAMPLE:
x = [0,2,3,4,6,7,9]
y = [3,6,10,12,20]
; print intersection of x and y
print,intersect(x,y)
3 6
; print xor elements
print,intersect(x,y,/xor_flag)
0 2 4 7 9 10 12 20
; print values in x that are not in y
xyu=intersect(x,y,/xor_flag) & print,intersect(x,xyu)
0 2 4 7 9
COMMON BLOCKS:
None.
AUTHOR and DATE:
Jeff Hicke 12/16/92
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/intersect.pro)
NAME:
INTERSECT
PURPOSE:
Return the an array that is the intersection of the two input arrays.
CATEGORY:
Array manipulation.
CALLING SEQUENCE:
x = INTERSECT(array1, array2)
INPUTS:
Arrays The arrays to be scanned. The type and number of dimensions
of the array are not important.
OPTIONAL INPUTS:
nodata: This is the value returned if no value in the both of the
arrays. The default is -1.
xor_flag if this keyword is set, only values are returned that belong
to one array or the other, but not both,
i.e., the complement of the set of intersection.
OUTPUTS:
result = An array of the values
EXAMPLE:
x = [0,2,3,4,6,7,9]
y = [3,6,10,12,20]
; print intersection of x and y
print,intersect(x,y)
3 6
; print xor elements
print,intersect(x,y,/xor_flag)
0 2 4 7 9 10 12 20
; print values in x that are not in y
xyu=intersect(x,y,/xor_flag) & print,intersect(x,xyu)
0 2 4 7 9
COMMON BLOCKS:
None.
AUTHOR and DATE:
Jeff Hicke 12/16/92
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/intersect.pro)
NAME: INTGAUSS PURPOSE: Return the analytically-determined integral of a Gaussian profile given its width and amplitude. USAGE: intgauss,amp,width,intflux,ehw=ehw INPUTS: AMP - amplitude of the Gaussian (peak intensity) WIDTH - Full Width at Half Maximum intensity (FWHM) *unless* the /ehw switch is used, in which case the supplied width is assumed to be the 1/e half-width of the line. OUTPUT: INTFLUX - the value of the integrated flux under the line. HISTORY: DRW @ MSSL (May 2002)
(See /home/drw/idl/gen/intgauss.pro)
NAME: INTVECTOR PURPOSE: This function integrates a one dimensional vector. CATEGORY: Math. CALLING SEQUENCE: Result = INTVECTOR(Input) INPUTS: Input: The one dimensional vector to be integrated. KEYWORD PARAMETERS: SKIPZERO: If set, start the integration with element 1 instead of element 0 of the array. OUTPUTS: This function returns the integrated vector. PROCEDURE: Straightforward. EXAMPLE: A = [0,1,3,4,2,4,2] B = INTVECTOR(A) PRINT,B 0 1 4 8 10 14 16 MODIFICATION HISTORY: Written by David Sahnow, 3 April 1997. 2 June 1998 Changed istart to a long.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/intvector.pro)
ROUTINE: Ions PURPOSE: Printss ion names in any CDS qlds USEAGE: IONS, qlds, names INPUT: qlds QLDS from CDS OUTPUT: names String containing the ions in QLDS AUTHOR: Peter T. Gallagher, May '98
(See /home/drw/idl/bin/ions.pro)
ROUTINE: Ions PURPOSE: Printss ion names in any CDS qlds USEAGE: IONS, qlds, names INPUT: qlds QLDS from CDS OUTPUT: names String containing the ions in QLDS AUTHOR: Peter T. Gallagher, May '98
(See /home/drw/idl/bin/ptg/ions.pro)
EXPLANATION: When accessing ionisation balance data from the CHIANTI database, it is output at log temperature values from 4 to 8 at 0.1 intervals. For display purposes it is often nice to perform spline interpolation to give a smoother function. This interpolation should be performed on the logarithm of the data as this is more slowly varying. This routine performs such an interpolation. It is only essential to input G_T and N. Specifying T is optional (see below), while TI and G_TI are output. N gives the number of points within an interval over which interpolation is performed. INPUTS: G_T: Data for which interpolation required OPTIONAL INPUTS: T: Values at which is G_T is tabulated. If not specified, then taken as 4 to 8 in 0.1 intervals. OUTPUTS T: If not specified, then output as an array from 4 to 8 in 0.1 intervals TI: Interpolated T values. G_TI: Interpolated G_T values KEYWORDS PLOT - The interpolated data is displayed together with the original data. EXAMPLE: g_t=g_of_t(26,13,/ray) ion_interp,t,g_t,ti,g_ti,5,/plot plot,t,g_t,psym=2,xra=[5.8,6.7] oplot,ti,g_ti CALLS: SPLINE HISTORY: Ver 1, PRY 17-JUN-98 CONTACT: Peter Young, Cambridge University (P.R.Young@damtp.cam.ac.uk)
(See /home/drw/idl/bin/ion_interp.pro)
EXPLANATION: When accessing ionisation balance data from the CHIANTI database, it is output at log temperature values from 4 to 8 at 0.1 intervals. For display purposes it is often nice to perform spline interpolation to give a smoother function. This interpolation should be performed on the logarithm of the data as this is more slowly varying. This routine performs such an interpolation. It is only essential to input G_T and N. Specifying T is optional (see below), while TI and G_TI are output. N gives the number of points within an interval over which interpolation is performed. INPUTS: G_T: Data for which interpolation required OPTIONAL INPUTS: T: Values at which is G_T is tabulated. If not specified, then taken as 4 to 8 in 0.1 intervals. OUTPUTS T: If not specified, then output as an array from 4 to 8 in 0.1 intervals TI: Interpolated T values. G_TI: Interpolated G_T values KEYWORDS PLOT - The interpolated data is displayed together with the original data. EXAMPLE: g_t=g_of_t(26,13,/ray) ion_interp,t,g_t,ti,g_ti,5,/plot plot,t,g_t,psym=2,xra=[5.8,6.7] oplot,ti,g_ti CALLS: SPLINE HISTORY: Ver 1, PRY 17-JUN-98 CONTACT: Peter Young, Cambridge University (P.R.Young@damtp.cam.ac.uk)
(See /home/drw/idl/bin/ptg/ion_interp.pro)
NAME:
ISMEUV
PURPOSE
Compute the interstellar EUV optical depth
EXPLANATION:
The EUV optical depth is computed from the photoionization of
hydrogen and helium.
CALLING SEQUENCE:
tau = ISMEUV( wave, Hcol, [ HeIcol, HeIIcol, /Fano ]
INPUTS:
wave - Vector of wavelength values (in Angstroms). Useful range is
40 - 912 A; at shorter wavelengths metal opacity should be
considered, at longer wavelengths there is no photoionization.
Hcol - Scalar specifying interstellar hydrogen column density in cm-2.
Typical values are 1E17 to 1E20.
OUTPUT:
tau - Vector giving resulting optical depth, same number of elements
as wave, non-negative values. To obtain the attenuation of
an input spectrum, multiply by exp(-tau).
OPTIONAL INPUTS:
HeIcol - Scalar specifying neutral helium column density in cm-2.
Default is 0.1*Hcol (10% of hydrogen column)
HeIIcol - Scalar specifying ionized helium column density in cm-2
Default is 0 (no HeII)
OPTIONAL INPUT KEYWORDS:
/FANO - If this keyword is set and non-zero, then the 4 strongest
auto-ionizing resonances of He I are included. The shape
of these resonances is given by a Fano profile - see Rumph,
Bowyer, & Vennes 1994, AJ, 107, 2108. If these resonances are
included then the input wavelength vector should have
a fine (>~0.01 A) grid between 190 A and 210 A, since the
resonances are very narrow.
EXAMPLE:
(1) One has a model EUV spectrum with wavelength, w (in Angstroms) and
flux,f . Plot the model flux after attenuation by 1e18 cm-2 of HI,
with N(HeI)/N(HI) = N(HeII)/N(HI) = 0.05
IDL> Hcol = 1e18
IDL> plot, w, f*exp(-ismeuv(w, Hcol, .05*Hcol, .05*Hcol))
(2) Plot the cross-section of HeI from 180 A to 220 A for 1e18 cm-2
of HeI, showing the auto-ionizing resonances. This is
Figure 1 in Rumph et al. (1994)
IDL> w = 180 + findgen(40000)*0.001 ;Need a fine wavelength grid
IDL> plot, w, ismeuv(w, 0, 1e18, /Fano)
HISTORY
Written, W. Landsman October, 1994
Adapted from ism.c at anonymous ftp site cea-ftp.cea.berkeley.edu
by Pat Jelinsky, Todd Rumph & others.
Converted to IDL V5.0 W. Landsman September 1997
FROM:
http://www.astro.washington.edu/deutsch-bin/getpro/library01.html?ISMEUV
(See /home/drw/idl/aux/ismeuv.pro)
NAME:
JBEPOCH
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Compute Julian Day to/from Julian or Besselian Epoch
CALLING SEQUENCE:
EPOCH = JBEPOCH(/B, JDAY) ;; Julian Day to Besselian Epoch
EPOCH = JBEPOCH(/J, JDAY) ;; Julian Day to Julian Epoch
JDAY = JBEPOCH(/B, EPOCH, /TO_DAY) ;; Besselian Epoch to Julian Day
JDAY = JBEPOCH(/J, EPOCH, /TO_DAY) ;; Julian Epoch to Julian Day
DESCRIPTION:
The function JBEPOCH computes the Julian or Besselian Epoch year
number from a given Julian day number. Epochs of this form are
often given in the astronomical literature as B1950.0 or J2000.0,
but they can be different.
Besselian year numbers are measured in tropical years of about
365.2422 days. Julian year numbers are measured in years whose
lengths are exactly 365.25 days of 86400 second lengths. The "/J"
or "/B" keywords identify which year numbering system is being
used.
JBEPOCH also computes the inverse transformation, from Julian or
Besselian epoch to Julian Day, by specifying the /TO_DAY keyword.
The computational logic is inspired by STARLINK (P.T. Wallace).
INPUTS:
EPOCH or JDAY - If TO_DAY is set, Besselian or Julian year number.
If TO_DAY is not set, the Julian day number.
KEYWORDS:
B - if set, then year numbers (input/output) are expressed in
Besselian years.
J - if set, then year numbers (input/output) are expressed in
Julian years.
TO_DAY - if set, then convert EJ (assumed to be year number) into
Julian day number.
MJD - if set, then Julian days are expressed as "modified" Julian
Days, or Julian days minus 2400000.5d.
RETURNS:
If TO_DAY is set, then returns Julian Days.
If TO_DAY is not set, then returns year number.
REFERENCES:
Lieske, J. H. 1979, Astron & Astrophysics, 73, 282
Wallace, P. T. 1999, SLALIB Software Library (STARLINK)
http://star-www.st-and.ac.uk/starlink/
(Routines sla_EPB2D, sla_EPJ2D, sla_EPB and sla_EPJ)
SEE ALSO:
JULDAY, CALDAT
MODIFICATION HISTORY:
Written, CM, 04 Mar 2002
Documented, CM, 22 Mar 2002
$Id: jbepoch.pro,v 1.3 2002/03/22 22:02:02 craigm Exp $
(See /home/drw/idl/aux/markwardt/jbepoch.pro)
NAME:
JD2YMD
PURPOSE:
Find year, month, day from julian day number.
CATEGORY:
CALLING SEQUENCE:
jd2ymd, jd, y, m, d
INPUTS:
jd = Julian day number (like 2447000). in
KEYWORD PARAMETERS:
OUTPUTS:
y = year (like 1987). out
m = month number (like 7). out
d = day of month (like 23). out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 21 Aug, 1986.
Johns Hopkins Applied Physics Lab.
RES 18 Sep, 1989 --- converted to SUN
R. Sterner, 30 Apr, 1993 --- cleaned up and allowed arrays.
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.
(See /home/drw/idl/esrg/jd2ymd.pro)
NAME:
JD2YMD
PURPOSE:
Find year, month, day from julian day number.
CATEGORY:
CALLING SEQUENCE:
jd2ymd, jd, y, m, d
INPUTS:
jd = Julian day number (like 2447000). in
KEYWORD PARAMETERS:
OUTPUTS:
y = year (like 1987). out
m = month number (like 7). out
d = day of month (like 23). out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner. 21 Aug, 1986.
Johns Hopkins Applied Physics Lab.
RES 18 Sep, 1989 --- converted to SUN
R. Sterner, 30 Apr, 1993 --- cleaned up and allowed arrays.
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.
(See /home/drw/idl/old.esrg/jd2ymd.pro)
PROJECT: CHROMOSPHERIC OSCILLATIONS, QUB (NB several parameters specfic to this useage should be changed for other projects) NAME: JFILT (a.k.a. FILT2) PURPOSE: To filter a time series (either high , low or band) and return the filtered time series. It carries this out by convolving the time series with a bessel shaped kernel. The kernel is created by digital_filter "/usr/local/rsi/idl/lib/digital_filter.pro" The convolution is carried out by convol, an inbuilt IDL routine By default prints out the power of peaks in the filtered power spectrum USEAGE: jfilt,timeseries,filtered_timeseries,num_peaks,$ des_power,signif_fts,signif_fts2,freq_fts,/origpeaks,/fish INPUTS: timeseries - the original unfiltered time series OPTIONAL[?] INPUTS: num_peaks - the number of peaks in the power spectrum you wish to pick out. set this to a maximum of half the number of points in time series. this will print out the peaks in order of power OUTPUTS: filtered_timeseries - the filtered time series OPTIONAL OUTPUTS: des_power - a (2 * numpeaks) array created by sort_powers /home/jma/idl/vtt/post_bbso/sort_powers.pro signif_fts - the 99% confidence level created by signif_conf /home/jma/idl/vtt/post_bbso/signif_conf.pro signif_fts2 - the 95% confidence level created by signif_conf freq_fts - the frequency array KEYWORDS: origpeaks - prints out power of peaks in the original power spectrum fish - prints out the fish g-factor /home/jma/idl/vtt/post_bbso/fish_signif.pro signal - plots on the signal /noise seperation usually found from /home/jma/idl/vtt/jma/powerlaw1.pro nodisp - turns off the display of the FFT's profile - shows the filter profile PROGRAM INPUTS delta - the time seperation of the time series, default 45 f_hi - the high frequency cutoff, default nyquist frequency f_lo - the low frequency cutoff, default 0.0005 a - input to digital_filter in effect increasing this smoothes off the edge of the filter it also decreases the number of 'wiggles' after the edge nt - input to digital_filter in effect increasing this makes the filter edge more abrupt also increases the number of wiggles after the filter For a pictorial explanation run this batch file /home/jma/idl/vtt/post_bbso/test_filt.bat TO DO: 1)Make the program more generic by changing the PROGRAM INPUTS to actual inputs This can be acheived by IF NOT KEYWORD_SET (....) THEN READ,'....',input 2) replace pgfft by fourier.pro, take out some extince signif keywords HISTORY: v1.0 - written by James McAteer and Peter Gallagher in Big Bear, CA (08/01) in its original filt.pro /home/jma/idl/vtt/jma/filt.pro v2.0 - Adjustments and alteration by JMA to make it more generic (09/01) v2.1 - JMA added in SIGNIF keyword after signif.pro (09/01) v2.2 - JMA added des_power,signif_fts,fish,origpeaks,num and removed the 'time' input from the call line (09/01) v3.0 - JMA and David Williams finally understand exactly what filtering is doing fts = convol( ts, kernel, /edge_truc ) changed to fts = convol( ts, kernel, /edge_wrap ). Filtering can be checked by dividing filtered power spectrum by the original power spectrum. Also now understand what a and nt are doing Best to maximise nt and a (although this increases computational time) (11/01) v3.1 - JMA added in ,/nodisp and ,/profile keywords (01/02)
(See /home/drw/idl/secis2/jfilt.pro)
NAME:
JPLEPHINTERP
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:
Interpolate position and motion of planetary bodies (JPL Ephemeris)
MAJOR TOPICS:
Planetary Orbits, Interpolation
CALLING SEQUENCE:
JPLEPHINTERP, INFO, RAWDATA, T, X, Y, Z, [VX, VY, VZ, /EARTH, /SUN,
OBJECTNAME=, CENTER=, TBASE=, POSUNITS=, VELUNITS= ]
DESCRIPTION:
JPLEPHINTERP interpolates the JPL DE200 or DE405 planetary
ephemeris to find the positions and motions of planetary bodies.
This routine is the second stage of a two-stage process to
interpolate the JPL ephemeris. In this first stage, the file is
opened using JPLEPHREAD, and the relevant portions of the table
are read and stored into the two variables INFO and RAWDATA. In
the second stage, the user actually interpolates the ephemeris for
the desired bodies and to the desired ephemeris time using
JPLEPHINTERP.
The only independent variable which must be specified is T, the
ephemeris time. For low to moderate accuracy applications, T is
simply the conventional calendar date, expressed in Julian days.
See below for high precision applications.
Upon output, the position components of the desired body are
returned in parameters X, Y and Z, and if requested velocity
components are returned in parameters VX, VY and VZ. Coordinates
are referred to the ephemeris's coordinate system: FK5 for
JPL-DE200 and ICRS for JPL-DE405. By default, the origin of
coordinates is the solar system barycenter (SSB), unless another
origin is selected using the CENTER keyword.
Users must set the VELOCITY keyword to generate body velocities.
By default they are not generated.
Users can select the desired body by using either the EARTH or SUN
keywords, or the OBJECTNAME keyword.
By default, positions are returned in units of KM and velocities
in units of KM/DAY. However, the output units are selectable by
setting the POSUNITS and VELUNITS keywords.
High Precision Applications
If the required precision is finer than a few hundred meters, the
user must be aware that the formal definition of the ephemeris
time is the coordinate time of a clock placed at the solar system
barycenter (SSB). If the user's time is measured by a clock
positioned elsewhere, then various corrections must be applied.
Usually, the most significant correction is that from the
geocenter to the SSB (see Fairhead & Bretagnon 1990; Fukushima
1995). Not applying this correction creates an error with
amplitude ~170 nano-light-seconds ( = 50 m) on the earth's
position. (see TDB2TDT)
For high precision, the user should also specify the TBASE
keyword. TBASE should be considered a fixed epoch with respect to
which T is measured; T should be small compared to TBASE.
Internally, subtraction of large numbers occurs with TBASE first,
so truncation error is minimized by specifying TBASE.
Nutations and Librations
This routine also provides information about earth nutations and
lunar librations, which are stored in the JPL ephemeris tables.
The POSUNITS and VELUNITS keywords do not affect these
computations.
Lunar librations in the form of three Euler angles are returned in
X, Y, Z, in units of radians, and their time derivatives are
returned in VX, VY, and VZ in units of radians per day.
The earth nutation angles psi (nutation in longitude) and epsilon
(nutation in obliquity) are returned in X and Y, in units of
radians. Their time derivatives are returned in VX and VY
respectively. The quantities returned in Z and VZ are undefined.
Verification
The precision routine has been verified using JPLEPHTEST, which is
similar to the original JPL program EPHTEST. For years 1950 to
2050, JPLEPHINTERP reproduces the original JPL ephemeris to within
1.5 centimeters.
Custom Ephemerides
It is possible to make custom ephemerides using JPLEPHMAKE, or to
augmented an existing ephemeris with additional data. In the
former case JPLEPHINTERP should automatically choose the correct
object from the table and interpolate it appropriately.
For augmented ephemerides, the object can be specified by name,
which works as expected, or by number, which has a special
behavior. For augmented files only, the new objects begin at
number 100.
PARAMETERS:
INFO - structure returned by JPLEPHREAD. Users should not modify
this structure.
RAWDATA - raw data array returned by JPLEPHREAD. Users should not
modify this data array.
T - ephemeris time(s) of interest. May be a scalar or vector.
The actual time is (T+TBASE).
X, Y, Z - upon return, the x-, y- and z-components of the body
position are returned in these parameters. For
nutations and librations see above.
VX, VY, VZ - upon return, the x-, y- and z-components of the body
velocity are returned in these parameters, if the
VELOCITY keyword is set. For nutations and
librations see above.
KEYWORD PARAMETERS:
EARTH, SUN - set one of these keywords if the desired body is the
earth or the sun. One of EARTH, SUN or OBJECTNAME
must be specified.
OBJECTNAME - a scalar string or integer, specifies the planetary
body of interest. May take any one of the following
integer or string values.
1 - 'MERCURY' 9 - 'PLUTO'
2 - 'VENUS' 10 - 'MOON' (earth's moon)
3 - 'EARTH' 11 - 'SUN'
4 - 'MARS' 12 - 'SOLARBARY' (solar system barycenter)
5 - 'JUPITER' 13 - 'EARTHBARY' (earth-moon barycenter)
6 - 'SATURN' 14 - 'NUTATIONS' (see above)
7 - 'URANUS' 15 - 'LIBRATIONS' (see above)
8 - 'NEPTUNE'
For custom ephemerides, the user should specify the
object name or number.
For augmented ephemerides, the user should specify
the name. If the number is specified, then numbers
1-15 have the above meanings, and new objects are
numbered starting at 100.
CENTER - a scalar string or integer, specifies the origin of
coordinates. See OBJECTNAME for allowed values.
Default: 12 (Solar system barycenter)
VELOCITY - if set, body velocities are generated and returned in
VX, VY and VZ.
Default: unset (no velocities)
POSUNITS - a scalar string specifying the desired units for X, Y,
and Z. Allowed values:
'KM' - kilometers (default)
'CM' - centimeters
'AU' - astronomical units
'LT-S' - light seconds
VELUNITS - a scalar string specifying the desired units for VX, VY
and VZ. Allowed values:
'KM/DAY' - kilometers per day (default)
'KM/S' - kilometers per second
'CM/S' - centimeters per second
'LT-S/S' - light seconds per second
'AU/DAY' - astronomical units per day
TBASE - a scalar number, specifies a fixed epoch against wich T is
measured. The ephemeris time will be (T+TBASE). Use this
keyword for maximum precision.
EXAMPLE:
Find position of earth at ephemeris time 2451544.5 JD. Units are
in Astronomical Units.
JPLEPHREAD, 'JPLEPH.200', pinfo, pdata, [2451544D, 2451545D]
JPLEPHINTERP, pinfo, pdata, 2451544.5D, xearth, yearth, zearth, $
/EARTH, posunits='AU'
REFERENCES:
AXBARY, Arnold Rots.
ftp://heasarc.gsfc.nasa.gov/xte/calib_data/clock/bary/
HORIZONS, JPL Web-based ephermis calculator (Ephemeris DE406)
http://ssd.jpl.nasa.gov/horizons.html
Fairhead, L. & Bretagnon, P. 1990, A&A, 229, 240
Fukushima, T. 1995, A&A, 294, 895
Standish, E.M. 1982, "Orientation of the JPL Ephemerides,
DE200/LE200, to the Dynamical Equinox of J2000", Astronomy &
Astrophysics, vol. 114, pp. 297-302.
Standish, E.M.: 1990, "The Observational Basis for JPL's DE200,
the planetary ephemeris of the Astronomical Almanac", Astronomy
& Astrophysics, vol. 233, pp. 252-271.
SEE ALSO
JPLEPHREAD, JPLEPHINTERP, JPLEPHTEST, TDB2TDT, JPLEPHMAKE
MODIFICATION HISTORY:
Written and Documented, CM, Jun 2001
Corrected bug in name conversion of NUTATIONS and LIBRATIONS, 18
Oct 2001, CM
Added code to handle custom-built ephemerides, 04 Mar 2002, CM
$Id: jplephinterp.pro,v 1.12 2002/03/04 19:42:49 craigm Exp $
(See /home/drw/idl/aux/markwardt/jplephinterp.pro)
NAME:
JPLEPHMAKE
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:
Make a new ephemeris suitable for interpolation by JPLEPHINTERP
MAJOR TOPICS:
Planetary Orbits, Interpolation
CALLING SEQUENCE:
JPLEPHREAD, INFO, RAW, OBJ, T, CX, CY, CZ, $
[ POSUNITS=, AUTHOR=, DATE=, OBJECTNAME=, ]
[ KEYWORDS=, KEYVALUES=, /RESET ]
DESCRIPTION:
JPLEPHMAKE is a utility routine which forms an ephemeris table
suitable for interpolation with JPLEPHINTERP. This is a way for
users to make or augment an ephemeris of solar system bodies not
already present in the JPL planetary ephemeris. This routine only
creates new ephemerides in memory. No facility is provided to
write to disk.
The user must have already estimated the Chebyshev polynomial
coefficients for the body of interest. One way to do this is with
CHEBGRID from the Markwardt library.
The two options are either to create a new ephemeris or to augment
an existing one. Augmentation merely means that new columns are
added to an existing ephemeris table. The JPL ephemeris itself
can be augmented.
Even when creating a new ephemeris from scratch, passing an
existing INFO structure based on another epehemeris is strongly
recommended, because the structure usually contains planetary
masses, physical constants, etc. which are relevant.
PARAMETERS:
INFO - upon input, an existing INFO structure based on a known
ephemeris. Upon output, a modified INFO structure.
If INFO is undefined upon input, or the RESET keyword is
set, then the returned INFO is set to a generic header.
RAW - upon input, an existing set of Chebyshev coefficients. Upon
output, the new or augmented set of coefficients.
If RAW is undefined upon input, or if the RESET keyword is
set, then the returned RAW variable is initialized to a new
set of keywords.
OBJ - scalar string, name of the object.
T - array of times, in Julian Days (TDB), which refer to the
*start* epoch of each granule. [ In the terminology of the
JPL ephemeris and CHEBGRID, a "granule" is a single
subinterval over which a Chebyshev polynomial is fitted. ] If
an existing ephemeris is to be augmented, then T must overlap
exactly.
CX, CY, CZ - arrays of Chebyshev polynomial coefficients.
KEYWORD PARAMETERS:
POSUNITS - a scalar string, the units of position as fitted by CX,
CY, and CZ. Allowed values:
'KM' - kilometers (default)
'CM' - centimeters
'AU' - astronomical units
'LT-S' - light seconds
NSUBINTERVALS - Number of granules per time sample.
Default: 1
RESET - if set, then a new ephemeris table is created. Any
Chebyshev coefficients in RAW are overwritten.
AUTHOR - a scalar string, an identifier giving the author of the
new ephemeris.
Default: ''
DATE - a scalar string, the creation date of the ephemeris.
Default: SYSTIME(0)
KEYWORDS - an optional string array, giving any header keywords to
be added to the ephemeris (in conjunction with
KEYVALUES).
Default: (none)
KEYVALUES - an optional double array, giving any header values for
the keywords specified by KEYWORDS.
Default: (none)
EXAMPLE:
REFERENCES:
JPL Export Ephmeris FTP Site
ftp://navigator.jpl.nasa.gov/pub/ephem/export/
(ephemeris files are available here, however, they must be
converted to FITS format using the "bin2eph" utility found in
AXBARY)
SEE ALSO
JPLEPHREAD, JPLEPHINTERP, JPLEPHTEST
MODIFICATION HISTORY:
Written and Documented, CM, Mar 2002
Corrected way that ephemerides are merged, also
way that AUTHOR field is filled, 29 May 2002, CM
$Id: jplephmake.pro,v 1.4 2002/05/29 20:07:41 craigm Exp $
(See /home/drw/idl/aux/markwardt/jplephmake.pro)
NAME:
JPLEPHREAD
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:
Open and read JPL DE200 or DE405 Ephemeride FITS File
MAJOR TOPICS:
Planetary Orbits, Interpolation
CALLING SEQUENCE:
JPLEPHREAD, FILENAME, INFO, RAWDATA, JDLIMITS, STATUS=, ERRMSG=
DESCRIPTION:
JPLEPHREAD opens and reads the JPL DE200 or DE405 planetary
ephemerides, as available in FITS format. The user must have the
IDL Astronomy Library installed to use this routine.
This routine is the initialization stage of a two-stage process to
interpolate the JPL ephemeris. In this first stage, the file is
opened, and the relevant portions of the table are read and stored
into the two variables INFO and RAWDATA. In the second stage, the
user actually interpolates the ephemeris for the desired bodies
and to the desired ephemeris time using JPLEPHINTERP.
Users must decide ahead of time the approximate dates of interest,
and pass this range in the JDLIMITS parameter. Any date covered
by the ephemeris is valid.
JPLEPHREAD is able to read files of the following format:
DE200 - Chebyshev - FITS format - Note 1
DE405 - Chebyshev - FITS format - Note 1
DE200 - Taylor - FITS format - Note 2
Note 1 - Chebyshev formatted FITS files are available in the
AXBARY package by Arnold Rots, found here:
ftp://heasarc.gsfc.nasa.gov/xte/calib_data/clock/bary/
or at the Markwardt FTP site:
ftp://cow.physics.wisc.edu/pub/craigm/bary/
Note 2 - Taylor-series based ephemerides have been available for
years in the FTOOLS / LHEASOFT package produced by NASA's
Goddard Space Flight Center. The original file is
de200_new.fits, which covers the years 1959-2000,
inclusive. A newer file is named
de200_1950-2050_v2.fits, and covers the years 1959-2050.
See Markwardt FTP site for these files.
PARAMETERS:
FILENAME - name of ephemeris file (scalar string).
INFO - upon completion, information about the ephemeris data is
returned in this parameter in the form of a structure.
Users must not modify INFO, although several fields are
useful and may be accessed read-only:
TSTART/TSTOP (start and stop time of data in Julian
days);
C (speed of light in km/s);
DENUM (development ephemeris number [200 or 405])
AU (1 astronomical unit, in units of light-seconds)
RAWDATA - upon completion, raw ephemeris data is returned in this
parameter. Users are not meant to access this data
directly, but rather to pass it to JPLEPHINTERP.
JDLIMITS - a two-element vector (optional), describing the desired
time range of interest. The vector should have the
form [TSTART, TSTOP], where TSTART and TSTOP are the
beginning and ending times of the range, expressed in
Julian days.
Default: entire table is read (note, this can be
several megabytes)
KEYWORD PARAMETERS:
STATUS - upon completion, a value of 1 indicates success, and 0
indicates failure.
ERRMSG - upon completion, an error message is returned in this
keyword. If there were no errors, then the returned
value is the empty string, ''.
EXAMPLE:
Find position of earth at ephemeris time 2451544.5 JD. Units are
in Astronomical Units.
JPLEPHREAD, 'JPLEPH.200', pinfo, pdata, [2451544D, 2451545D]
JPLEPHINTERP, pinfo, pdata, 2451544.5D, xearth, yearth, zearth, $
/EARTH, posunits='AU'
REFERENCES:
AXBARY, Arnold Rots.
ftp://heasarc.gsfc.nasa.gov/xte/calib_data/clock/bary/
HORIZONS, JPL Web-based ephermis calculator (Ephemeris DE406)
http://ssd.jpl.nasa.gov/horizons.html
JPL Export Ephmeris FTP Site
ftp://navigator.jpl.nasa.gov/pub/ephem/export/
(ephemeris files are available here, however, they must be
converted to FITS format using the "bin2eph" utility found in
AXBARY)
JPL Export Ephemeris CD-ROM - Ordering Information
http://www.willbell.com/software/jpl.htm
Standish, E.M. 1982, "Orientation of the JPL Ephemerides,
DE200/LE200, to the Dynamical Equinox of J2000", Astronomy &
Astrophysics, vol. 114, pp. 297-302.
Standish, E.M.: 1990, "The Observational Basis for JPL's DE200,
the planetary ephemeris of the Astronomical Almanac", Astronomy
& Astrophysics, vol. 233, pp. 252-271.
SEE ALSO
JPLEPHREAD, JPLEPHINTERP, JPLEPHTEST
MODIFICATION HISTORY:
Written and Documented, CM, Jun 2001
Incorporated changes by W. Landsman, for error handling more
consistent with IDL Astronomy Library, Oct 2001, WL
Add ephemeris file keywords to INFO, Jan 2002, CM
Add fields to INFO to be consistent with JPLEPHMAKE, 04 Mar 2002, CM
$Id: jplephread.pro,v 1.9 2002/03/04 19:42:16 craigm Exp $
(See /home/drw/idl/aux/markwardt/jplephread.pro)
NAME:
JPLEPHTEST
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:
Test JPLEPHTEST with JPL test data set
MAJOR TOPICS:
Planetary Orbits, Interpolation
CALLING SEQUENCE:
JPLEPHTEST, EPHFILE, TESTFILE
DESCRIPTION:
JPLEPHTEST tests the JPLEPHINTERP procedure for precision. In
order to function, you must have the JPLEPHREAD and JPLEPHINTERP
procedures, as well as the IDL Astronomy Libary for reading FITS
files. In addition, you must have a JPL ephemeris test data set,
which is available by FTP.
The procedure opens and reads the test set, which contains
precomputed data. Every tenth value is printed on the screen.
Any deviations that exceed 1.5d-13 AU = 1.5 cm are reported.
The columns are labelled according to the input file, except for
the final column, which is the deviation between the input file
and the computed value.
PARAMETERS:
EPHFILE - a scalar string, specifies the name of the ephemeris
file, in FITS format.
TESTFILE - a scalar string, specifies JPL test data set to compare
against.
EXAMPLE:
Test JPL DE200 and DE405 ephemerides. Assumes files are in the
current directory.
JPLEPHTEST, 'JPLEPH.200', 'testpo.200'
JPLEPHTEST, 'JPLEPH.405', 'testpo.405'
REFERENCES:
JPL Export Ephmeris FTP Site
ftp://navigator.jpl.nasa.gov/pub/ephem/export/
(see test-data/ for test data sets)
HORIZONS, JPL Web-based ephermis calculator (Ephemeris DE406)
http://ssd.jpl.nasa.gov/horizons.html
SEE ALSO
JPLEPHREAD, JPLEPHINTERP, JPLEPHTEST
MODIFICATION HISTORY:
Written and Documented, CM, Jun 2001
Removed TRANSREAD, improved output, improved docs, CM, 9 Jul 2001
$Id: jplephtest.pro,v 1.4 2001/07/20 13:29:53 craigm Exp $
(See /home/drw/idl/aux/markwardt/jplephtest.pro)
NAME:
JUL2DAY
PURPOSE:
Convert the inputted Julian day of year to year, month, day.
CALLING SEQUENCE:
jul2day,julday,year,mon,day
INPUTS:
julday Julian day, ranges from 1-365(366)
year
KEYWORD INPUTS:
OPTIONAL INPUTS:
OUTPUTS:
mon ranges from 1-12
day ranges from 1-31
OPTIONAL OUTPUTS:
outyear output year; if different from input year (when julday
> 365/366 or < 1)
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
The input variable julday can be zero or negative. Zero indicates
the last day of the previous year (12/31), -1 indicates 12/30,
and so on.
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 10/25/92
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/jul2day.pro)
NAME:
JUL2DAY
PURPOSE:
Convert the inputted Julian day of year to year, month, day.
CALLING SEQUENCE:
jul2day,julday,year,mon,day
INPUTS:
julday Julian day, ranges from 1-365(366)
year
KEYWORD INPUTS:
OPTIONAL INPUTS:
OUTPUTS:
mon ranges from 1-12
day ranges from 1-31
OPTIONAL OUTPUTS:
outyear output year; if different from input year (when julday
> 365/366 or < 1)
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
The input variable julday can be zero or negative. Zero indicates
the last day of the previous year (12/31), -1 indicates 12/30,
and so on.
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 10/25/92
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/jul2day.pro)
routine: kernel
useage: kernel(ksize,angle)
purpose: create a digital filter to detect image streaks
oriented at angle ANGLE. The IDL procedure CONVOL
can be used to do the convolutions.
input:
ksize frame size of kernel.
angle select for streaks at angle ANGLE
EXAMPLE:
print,kernel(3,0)
0 0 0
1 1 1
0 0 0
print,kernel(5,45)
0 0 0 0 1
0 0 0 1 0
0 0 1 0 0
0 1 0 0 0
1 0 0 0 0
author: Paul Ricchiazzi oct93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/kernel.pro)
routine: kernel
useage: kernel(ksize,angle)
purpose: create a digital filter to detect image streaks
oriented at angle ANGLE. The IDL procedure CONVOL
can be used to do the convolutions.
input:
ksize frame size of kernel.
angle select for streaks at angle ANGLE
EXAMPLE:
print,kernel(3,0)
0 0 0
1 1 1
0 0 0
print,kernel(5,45)
0 0 0 0 1
0 0 0 1 0
0 0 1 0 0
0 1 0 0 0
1 0 0 0 0
author: Paul Ricchiazzi oct93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/kernel.pro)
ROUTINE: longley
PURPOSE: find TOA direct beam flux and atmospheric optical depth using
the Langley procedure. Additionally, produce Langley scatter
plot of direct beam flux vs airmass and show fit.
USEAGE: langley,sza,flx,flx0,tau,sigma,minmass=minmass,maxmass,
view=view,psym=psym,color=color,$
overplot=overplot,am=am,pm=pm,hw=hw
INPUT:
sza solar zenith angle array
flx direct normal flux (direct beam irradiance divided by cos(sza))
KEYWORD INPUT:
am if set morning hours are used in Langley regression
pm if set afternoon hours are used Langley regression
NOTE: it is assumed that data is organized in
chronological order so that morning hours are those with
decreasing sza and afternoon hours are those with
increasing sza
minmass minimum air mass limit. points with air mass less then
MINMASS are not used in regression. (default=2)
maxmass maximum air mass limit. points with air mass greater then
MAXMASS are not used in regression. (default=6)
Default limits are as suggested by Harrison and Michalsky (1994)
clrfilt if set values alog(flx)-smooth(alog(flx),n) gt CLRFILT are
removed from the regression computation
view display scatter plot and fitted regression line
psym symbol used for scatter plot
color color used for regression line
overplot if set, overplot results on existing plot frame
hw if set use histogram weighting in regression computation.
This causes the regression to weigh all increments of air
mass equally. Fractional values of HW (between 0 and 1)
causes the weighting factor to be raised to the HW
power. In some cases histogram weighting can improve the
accuracy of retrievals.
OUTPUT:
flx0 intensity at zero airmass
tau optical depth
sigma standard deviation of log (flx) from fitted line. This is
an estimate of the fractional error. For example sigma=.01
means the linear regression fits the data to within about 1%.
see example.
DISCUSSION:
use langley procedure to fit direct normal flux by an equation of form
ln(I(m)) = ln(I(0)) - tau * m
where I(m) is the direct normal flux at airmass m and tau is the
optical depth. Assumes direct beam transmission obeys Beers law.
EXAMPLE:
nn=200 & doy=281 & lat=35. & lon=0. & time=findrng(7,17,nn)
zensun,doy,time,lat,lon,sza,az
szamx=80. & sza=sza(where(sza lt szamx)) & az=az(where(sza lt szamx))
flx=(100.+randomn(iseed,nn))*exp(-.1*airmass(sza))
w8x11 & !p.multi=[0,1,3] & set_charsize,1.5
langley,sza,flx,flx0,tau,sigma,/view,title='Morning, hw=1',/hw,am=az
langley,sza,flx,flx0,tau,sigma,/view,title='Morning',am=az
langley,sza,flx,flx0,tau,sigma,/view,title='Afternoon',pm=az
AUTHOR: Paul Ricchiazzi 09 Jan 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/langley.pro)
Project : SOHO - CDS
Name :
LAPLACIAN()
Purpose :
Calculate the Laplacian of an array.
Explanation :
The numerical second derivative is calculated in the X and Y
directions, and then added together.
Use :
Result = LAPLACIAN(ARRAY)
Inputs :
ARRAY = Image to take Laplacian of.
Opt. Inputs :
None.
Outputs :
Result of function is the Laplacian of the array.
Opt. Outputs:
None.
Keywords :
MISSING = Value flagging missing pixels. Any such pixels are not
included in calculating the Laplacian. The output value for
any point with a missing pixel adjacent to it will be set to
the missing pixel value.
Calls :
GET_IM_KEYWORD
Common :
None.
Restrictions:
The image array must be two-dimensional.
In general, the SERTS image display routines use several non-standard
system variables. These system variables are defined in the procedure
IMAGELIB. It is suggested that the command IMAGELIB be placed in the
user's IDL_STARTUP file.
Some routines also require the SERTS graphics devices software,
generally found in a parallel directory at the site where this software
was obtained. Those routines have their own special system variables.
Side effects:
None.
Category :
Utilities, Image_display.
Prev. Hist. :
William Thompson, March 1991.
William Thompson, August 1992, renamed BADPIXEL to MISSING.
Written :
William Thompson, GSFC, March 1991.
Modified :
Version 1, William Thompson, GSFC, 13 May 1993.
Incorporated into CDS library.
Version :
Version 1, 13 May 1993.
(See /home/drw/idl/bin/laplacian.pro)
Project : SOHO - CDS
Name :
LAPLACIAN()
Purpose :
Calculate the Laplacian of an array.
Explanation :
The numerical second derivative is calculated in the X and Y
directions, and then added together.
Use :
Result = LAPLACIAN(ARRAY)
Inputs :
ARRAY = Image to take Laplacian of.
Opt. Inputs :
None.
Outputs :
Result of function is the Laplacian of the array.
Opt. Outputs:
None.
Keywords :
MISSING = Value flagging missing pixels. Any such pixels are not
included in calculating the Laplacian. The output value for
any point with a missing pixel adjacent to it will be set to
the missing pixel value.
Calls :
GET_IM_KEYWORD
Common :
None.
Restrictions:
The image array must be two-dimensional.
In general, the SERTS image display routines use several non-standard
system variables. These system variables are defined in the procedure
IMAGELIB. It is suggested that the command IMAGELIB be placed in the
user's IDL_STARTUP file.
Some routines also require the SERTS graphics devices software,
generally found in a parallel directory at the site where this software
was obtained. Those routines have their own special system variables.
Side effects:
None.
Category :
Utilities, Image_display.
Prev. Hist. :
William Thompson, March 1991.
William Thompson, August 1992, renamed BADPIXEL to MISSING.
Written :
William Thompson, GSFC, March 1991.
Modified :
Version 1, William Thompson, GSFC, 13 May 1993.
Incorporated into CDS library.
Version :
Version 1, 13 May 1993.
(See /home/drw/idl/bin/ptg/laplacian.pro)
NAME: LATLON PURPOSE: If the current window has map coordinates (i.e., MAP_SET has been used to set up a map projection), LATLON tracks the longitude and latitude of the mouse location and displays them in a separate window. To activate tracking, click on the left mouse button while the cursor is in the plotting window. To stop, position the cursor in the plotting window and press the right button. CATEGORY: Mapping. CALLING SEQUENCE: LATLON INPUTS: None. KEYWORD PARAMETERS: None. OUTPUTS: Latitude and longitude values are printed in a new window. COMMON BLOCKS: None. SIDE EFFECTS: A new window is created. RESTRICTIONS: The window must have map coordinates. EXAMPLE: Set up a Mercator map projection by entering the following command: MAP_SET, /MERCATOR, /GRID, /CONTINENT Invoke LATLON by entering: LATLON A new window labeled "Latitude/Longitude" should appear. Put the mouse cursor in the map window and press the left mouse button to begin tracking the position of the cursor. Press the right mouse button over the map to end LATLON. MODIFICATION HISTORY: Written by Ann Bateson, June 1990
(See /home/drw/idl/esrg/latlonrdpix.pro)
NAME: LATLON PURPOSE: If the current window has map coordinates (i.e., MAP_SET has been used to set up a map projection), LATLON tracks the longitude and latitude of the mouse location and displays them in a separate window. To activate tracking, click on the left mouse button while the cursor is in the plotting window. To stop, position the cursor in the plotting window and press the right button. CATEGORY: Mapping. CALLING SEQUENCE: LATLON INPUTS: None. KEYWORD PARAMETERS: None. OUTPUTS: Latitude and longitude values are printed in a new window. COMMON BLOCKS: None. SIDE EFFECTS: A new window is created. RESTRICTIONS: The window must have map coordinates. EXAMPLE: Set up a Mercator map projection by entering the following command: MAP_SET, /MERCATOR, /GRID, /CONTINENT Invoke LATLON by entering: LATLON A new window labeled "Latitude/Longitude" should appear. Put the mouse cursor in the map window and press the left mouse button to begin tracking the position of the cursor. Press the right mouse button over the map to end LATLON. MODIFICATION HISTORY: Written by Ann Bateson, June 1990
(See /home/drw/idl/old.esrg/latlonrdpix.pro)
ROUTINE: lct
PURPOSE: try all predefined color tables
USEAGE: lct,index
INPUT:
index if set index specifies the first color table to try
OUTPUT:
index final color table index
DISCUSSION:
With each click of the left mouse button a new color table is loaded.
The MMB scans up the list of color tables and LMB scans down the list.
The RMB exits the procedure.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
Loads new color tables
EXAMPLE:
tvim,replicate(1,2) # indgen(!p.color),/scale,range=[0,!p.color],/asp & lct
AUTHOR: Paul Ricchiazzi 30 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/lct.pro)
ROUTINE: lct
PURPOSE: try all predefined color tables
USEAGE: lct,index
INPUT:
index if set index specifies the first color table to try
OUTPUT:
index final color table index
DISCUSSION:
With each click of the left mouse button a new color table is loaded.
The MMB scans up the list of color tables and LMB scans down the list.
The RMB exits the procedure.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
Loads new color tables
EXAMPLE:
tvim,replicate(1,2) # indgen(!p.color),/scale,range=[0,!p.color],/asp & lct
AUTHOR: Paul Ricchiazzi 30 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/lct.pro)
NAME:
LEGCHEB
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:
Compute Legendre polynomial coefficents from Chebyshev coefficients
MAJOR TOPICS:
Curve and Surface Fitting, Special Functions
CALLING SEQUENCE:
b = LEGCHEB(a)
DESCRIPTION:
This routine computes the coefficients of a Legendre polynomial
expansion when the Chebyshev expansion is known.
Users can determine the Chebyshev expansion coefficients using a
routine like CHEBFIT, CHEBCOEF or CHEBGRID. Then, if the Legendre
expansion is needed instead, this conversion routine should be
used. Evaluation of the Legendre series can be performed using
the POLYLEG function in the IDL Astronomy Library.
Internally, the computational precision is double precision.
This routine relies upon the algorithm of Piessens (1974).
INPUTS:
A - a vector, the coefficients of the Chebyshev series of the
desired function.
RETURNS:
The vector B, which contains the coefficients of the Legendre
polynomial expansion. Both A and B will have the same number of
elements and data type.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
;; Compute the Chebyshev series coefficients of 1/(2-X) on [-1,1]
A = CHEBCOEF('1d/(2d - X)', /expr)
;; Convert to Legendre series coefficients
B = LEGCHEB(A)
REFERENCES:
Abramowitz, M. & Stegun, I., 1965, *Handbook of Mathematical
Functions*, 1965, U.S. Government Printing Office, Washington,
D.C. (Applied Mathematical Series 55)
Piessens, R. 1974, Comm. ACM, v. 17, p. 25 (TOMS 473)
MODIFICATION HISTORY:
Written and documented, CM, 25 Sep 2002
$Id: legcheb.pro,v 1.1 2002/09/25 21:12:35 craigm Exp $
(See /home/drw/idl/aux/markwardt/legcheb.pro)
ROUTINE: legend
PURPOSE: draws a plot legend
USEAGE: legend,labels,pos=pos,linestyle=linestyle,psym=psym,clrbox=clrbox,$
color=color,thick=thick,fg_color=fg_color,bg_color=bg_color,$
box=box,numsym=numsym,ystretch=ystretch,silent=silent,$
center=center,fill=fill,right=right,norm=norm,spos=spos
INPUT:
labels
an array of labels (required). Elements of LABELS which do not
begin with the characters ".l",".f",".c", or ".r" are treated as
legend labels. These elements are drawn to the right of a line
or symbol of given LINESTYLE, PSYM, COLOR or THICK type. The
total number of labels in LABELS (i.e., not counting legend
titles) should correspond to the number of elements in those
input parameters.
If any of the label strings start with the characters
".l",".f",".c", or ".r" that element of the LABELS array is
treated as a legend title. Legend titles appear as left
justified (".l"), filled (".f") centered (".c") or right
justified (".r") strings in the legend box and do not correspond
to elements of LINESTYLE, PSYM, COLOR or THICK. Null strings
("") or blank strings (" ") are also treated as legend
titles. Lines or symbols are not drawn to the right of legend
titles.
If none of the keywords, LINESTYPE, PSYM, COLOR or THICK are
set, then all elements of LABELS will be treated as legend
titles and will be left justified unless prepended by ".f", ".c"
or ".r". or unless one of the keywords keywords "center",
"fill" "right" are set. These keywords set the default, string
justification but may always be overridden by one of the
justification flags.
Consider,
labels=['.ctitle','1','2','.lsecond title,'a','b']
linestyle= [1,2,3,4]
In this example LABELS contains 4 legend labels and 2 legend
titles. The correspondence with the linestyle input parameter is
as follows:
labels(1) <==> linestyle(0)
labels(2) <==> linestyle(1)
labels(4) <==> linestyle(2)
labels(5) <==> linestyle(3)
To simplify input, LABELS may also be specified as a single
string with the different LABEL elements separated by
backslashes (\) (E.g., labels='.cCloud height\\1\2\3\4\5'
KEYWORD INPUT:
pos
position and size of legend area in normalized data
coordinates. Format of this four element vector is
[x0,y0,x1,y1] where x0,y0 is the position of lower
left corner and x1,y1 is the position of the upper
right corner. For example pos=[.5,.5,.9,.9] specifies
a legend in the upper right quadrant of the data
window. If the POS parameter is not set or if POS is
set to zero, then the CURBOX procedure is called to
set the legend position interactively.
NOTE: the value of POS can be retrieved by setting POS
to a named variable which has an initial value of zero.
linestyle
an array of linestyle types, one for each label in LABELS
psym
an array of symbol types, one for each label in LABELS.
PSYM can be either a integer or string array. If PSYM is a
string array then the library routine USERSYMBOL is used to
create the symbols. In this case if the symbol specifier is
appended with '_f' then a filled symbol will be generated
clrbox
if set, a color-filled box appears to the left of each
legend label. The number of boxes drawn can be changed with
NUMSYM.
color
an array of color indices, one for each label in LABELS.
Any elements of COLOR set to -1 causes the default color,
!P.COLOR, to be used.
thick
an array of line thicknesses, one for each label in LABELS
(default=!p.thick)
numsym
number of symbol nodes used to indicate linestyle or symbol
type. The length of the line is measured in units of 4
character widths so that the length of the line
= 4*(NUMSYM-1) * X_CHARSIZE
(default=2 when linestyle set, otherwise default=1)
fg_color
color of box and legend titles (default=!P.COLOR)
bg_color
background color. Setting BG_COLOR erases the area covered by
the legend (filling it with color BG_COLOR) prior to writing the
legend. If both BG_COLOR and !p.color are zero then the
background color is reset to 255 to gaurantee a readability.
box
if set draw a box around the legend text
ystretch
factor by which to increase vertical spacing of legend
entries. (default = 1)
NOTE: the aspect ratio of the legend box can be
modified on the fly by shoving the cursor box against
one of the window boundaries and pressing the middle
button.
silent
if not set, print box position string to the terminal
and show popup help on the CURBOX cursor routine
silent=1 don't print position string
silent=2 don't print position string, don't show help widget
center
if set, default action is to center legend labels
fill
if set, default action is to fill legend labels
right
if set, default action is to right justify labels
norm
if set, normalized coordinates are used to specify POS both
on input and printed output. This option allows placement
of the legend outside of a plot region.
spos
string value which specifies legend position to one of a set of
standard positions. if spos is set, it supercedes the value of pos
'bl' = bottom left
'br' = bottom right
'tl' = top left
'tr' = top right
'top'= top center
'bot'= bottom center
OUTPUT: none
PROCEDURE:
When called without the POS keyword, the legend position and size
is set with the CURBOX routine. The legend is positioned by
dragging the box where you want the legend to appear. The size
of the legend area can be decreased/increased by the left/middle
mouse buttons. When the right mouse button is pressed the legend
is drawn and a numerical positioning string giving the current
value of the POS keyword is written to the terminal (nothing
printed if SILENT is set). You can run LEGEND in batch mode by
pasting this value of POS into the LEGEND command line. The best
way to get good-looking legends on your hardcopies is to size
your graphics window to the approximate shape of the output
media. For example a plot which is to be printed in landscape
mode should be previewed on a window which is approximately 1.4
times as wide as it is tall.
NOTE: The values returned for the POS keyword are based on a
computation of the length of the text strings in your legend. If
you change the contents of the legend titles or if you change the
default text font, you must rerun LEGEND in interactive mode to
determine new values for the POS paramter.
; EXAMPLE interactive mode (put the box anywhere you want and press
; the right mouse button)
dcolors
plot,6*randf(20,3),/nodata
for i=1,6 do oplot,i*randf(20,3),li=i-1,color=i
lb='.cFirst bunch\\First\Second\Third\\.cSecond bunch\\forth\fifth\sixth'
legend,lb,li=[0,1,2,3,4,5],/box,bg=0,color=[1,2,3,4,5,6]
; EXAMPLE interactive mode. retrieve the value of POS for later calls:
!p.multi=[0,1,2]
plot,[0,.4],yrange=[0,1],li=0 & oplot,[0,.6],li=2 & oplot,[0,.9],li=3
legpos=0
lb=['.cLegend Demo','','one','two','three']
legend,lb,pos=legpos,li=[0,2,3]
plot,[0,.4],yrange=[0,1],li=0 & oplot,[0,.6],li=2 & oplot,[0,.9],li=3
legend,lb,pos=legpos,li=[0,2,3]
!p.multi=0
; EXAMPLE use fill mode to print a figure caption
w11x8
!p.multi=[0,1,2]
plot,dist(20)
t=$
'When called without the POS keyword, the legend position and size is\'+$
'set with the CURBOX routine. The legend is positioned by dragging the\'+$
'box where you want the legend to appear. The size of the legend area\'+$
'can be decreased/increased by the left/middle mouse buttons. When the\'+$
'right mouse button is pressed the legend is drawn and a numerical\'+$
'positioning string giving the current value of the POS keyword is\'+$
'written to the terminal (nothing printed if SILENT is set). You can\'+$
'run LEGEND in batch mode by pasting this value of POS into the LEGEND\'+$
'command line. The best way to get good-looking legends on your\'+$
'hardcopies is to size your graphics window to the approximate shape of\'+$
'the output media. For example a plot which is to be printed in\'+$
'landscape mode should be previewed on a window which is approximately\'+$
'1.4 times as wide as it is tall.'
legend,t,bg=0,pos=[0.02,-0.9,0.43,-0.25] ; default left justified
legend,t,bg=0,/fill,pos=[0.55,-0.9,0.97,-0.25] ; filled legend
; NOTE: procedure PFILL provides more elaborate text formatting capability
; EXAMPLE batch mode:
plot,[-50,50],[0,1.5],/nodata & x=findgen(101)-50.
li=indgen(6) & pos=[0.66,0.54,0.91,0.89]
for i=0,5 do oplot,x,1./(1.+(x/(i+2))^2),li=li(i)
labels='.cPlot Key\\First\Second\Third\Fourth\Fifth\Sixth'
legend,' ',bg=80,pos=pos+.02,/box
legend,labels,li=li,pos=pos,bg=40,/box
; EXAMPLE batch mode with symbols generated by USERSYMBOL:
plot,[-50,50],[0,1.5],/nodata & x=findgen(101)-50.
psym=['TRIANGLE','DIAMOND','PENTAGON','CIRCLE','SQUARE','SPADE']
pos=[0.66,0.54,0.91,0.89]
for i=0,5 do begin &$
usersymbol,psym(i) &$
oplot,x,1./(1.+(x/(i+2))^2),psym=8,symsize=2 &$
endfor
labels='.cPlot Key\\First\Second\Third\Fourth\Fifth\Sixth'
legend,' ',bg=4,pos=pos+.02,/box
legend,labels,psym=psym,pos=pos,bg=10,/box
author: Paul Ricchiazzi 4dec92
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS
15dec92: added legend titles, and CHARSIZE parameter
11jan93: added numsym parameter
20jan93: added thick parameter
2feb93: fixed positioning bug legend titles
25mar93: removed the NOBOX option, now you set BOX to get a box
29mar93: added the bg_color option to blank out legend area before writing
8apr93: use CURBOX for cursor control and LENSTR for exact string size
27apr93: improved alignment symbol and label (ylab=yy-.3*charsize*cnvrty)
9jun93: center legend labels when legend titles are longer (see dxcen)
17jun93: added ystretch option to increase vertical spacing
17jun93: default line thickness read from !p.thick
30sep93: .l implied when LINESTYLE, PSYM, COLOR, THICK not set. see NOLINES
28Jun94: LABELS is now normal input param, not a keyword.
28Jun94: legend "titles" don't correspond to LINESTYLE, PSYM, COLOR, THICK
vector elements; no need to put in dummy values. see examples
18Aug94: added USYM option
28Jun95: added the .f format option
8Sep95: added CLRBOX option
5oct95: added charsize adjustment for Y axis
sep96: added spos keyword, numsym defaults to 1 when linestyle not set
(See /home/drw/idl/old.esrg/legend.pro)
ROUTINE: legend
PURPOSE: draws a plot legend
USEAGE: legend,labels,pos=pos,linestyle=linestyle,psym=psym,clrbox=clrbox,$
color=color,thick=thick,fg_color=fg_color,bg_color=bg_color,$
box=box,numsym=numsym,ystretch=ystretch,silent=silent,$
center=center,fill=fill,right=right,norm=norm,spos=spos
INPUT:
labels
an array of labels (required). Elements of LABELS which do not
begin with the characters ".l",".f",".c", or ".r" are treated as
legend labels. These elements are drawn to the right of a line
or symbol of given LINESTYLE, PSYM, COLOR or THICK type. The
total number of labels in LABELS (i.e., not counting legend
titles) should correspond to the number of elements in those
input parameters.
If any of the label strings start with the characters
".l",".f",".c", or ".r" that element of the LABELS array is
treated as a legend title. Legend titles appear as left
justified (".l"), filled (".f") centered (".c") or right
justified (".r") strings in the legend box and do not correspond
to elements of LINESTYLE, PSYM, COLOR or THICK. Null strings
("") or blank strings (" ") are also treated as legend
titles. Lines or symbols are not drawn to the right of legend
titles.
If none of the keywords, LINESTYPE, PSYM, COLOR or THICK are
set, then all elements of LABELS will be treated as legend
titles and will be left justified unless prepended by ".f", ".c"
or ".r". or unless one of the keywords keywords "center",
"fill" "right" are set. These keywords set the default, string
justification but may always be overridden by one of the
justification flags.
Consider,
labels=['.ctitle','1','2','.lsecond title,'a','b']
linestyle= [1,2,3,4]
In this example LABELS contains 4 legend labels and 2 legend
titles. The correspondence with the linestyle input parameter is
as follows:
labels(1) <==> linestyle(0)
labels(2) <==> linestyle(1)
labels(4) <==> linestyle(2)
labels(5) <==> linestyle(3)
To simplify input, LABELS may also be specified as a single
string with the different LABEL elements separated by
backslashes (\) (E.g., labels='.cCloud height\\1\2\3\4\5'
KEYWORD INPUT:
pos
position and size of legend area in normalized data
coordinates. Format of this four element vector is
[x0,y0,x1,y1] where x0,y0 is the position of lower
left corner and x1,y1 is the position of the upper
right corner. For example pos=[.5,.5,.9,.9] specifies
a legend in the upper right quadrant of the data
window. If the POS parameter is not set or if POS is
set to zero, then the CURBOX procedure is called to
set the legend position interactively.
NOTE: the value of POS can be retrieved by setting POS
to a named variable which has an initial value of zero.
linestyle
an array of linestyle types, one for each label in LABELS
psym
an array of symbol types, one for each label in LABELS.
PSYM can be either a integer or string array. If PSYM is a
string array then the library routine USERSYMBOL is used to
create the symbols. In this case if the symbol specifier is
appended with '_f' then a filled symbol will be generated
clrbox
if set, a color-filled box appears to the left of each
legend label. The number of boxes drawn can be changed with
NUMSYM.
color
an array of color indices, one for each label in LABELS.
Any elements of COLOR set to -1 causes the default color,
!P.COLOR, to be used.
thick
an array of line thicknesses, one for each label in LABELS
(default=!p.thick)
numsym
number of symbol nodes used to indicate linestyle or symbol
type. The length of the line is measured in units of 4
character widths so that the length of the line
= 4*(NUMSYM-1) * X_CHARSIZE
(default=2 when linestyle set, otherwise default=1)
fg_color
color of box and legend titles (default=!P.COLOR)
bg_color
background color. Setting BG_COLOR erases the area covered by
the legend (filling it with color BG_COLOR) prior to writing the
legend. If both BG_COLOR and !p.color are zero then the
background color is reset to 255 to gaurantee a readability.
box
if set draw a box around the legend text
ystretch
factor by which to increase vertical spacing of legend
entries. (default = 1)
NOTE: the aspect ratio of the legend box can be
modified on the fly by shoving the cursor box against
one of the window boundaries and pressing the middle
button.
silent
if not set, print box position string to the terminal
and show popup help on the CURBOX cursor routine
silent=1 don't print position string
silent=2 don't print position string, don't show help widget
center
if set, default action is to center legend labels
fill
if set, default action is to fill legend labels
right
if set, default action is to right justify labels
norm
if set, normalized coordinates are used to specify POS both
on input and printed output. This option allows placement
of the legend outside of a plot region.
spos
string value which specifies legend position to one of a set of
standard positions. if spos is set, it supercedes the value of pos
'bl' = bottom left
'br' = bottom right
'tl' = top left
'tr' = top right
'top'= top center
'bot'= bottom center
OUTPUT: none
PROCEDURE:
When called without the POS keyword, the legend position and size
is set with the CURBOX routine. The legend is positioned by
dragging the box where you want the legend to appear. The size
of the legend area can be decreased/increased by the left/middle
mouse buttons. When the right mouse button is pressed the legend
is drawn and a numerical positioning string giving the current
value of the POS keyword is written to the terminal (nothing
printed if SILENT is set). You can run LEGEND in batch mode by
pasting this value of POS into the LEGEND command line. The best
way to get good-looking legends on your hardcopies is to size
your graphics window to the approximate shape of the output
media. For example a plot which is to be printed in landscape
mode should be previewed on a window which is approximately 1.4
times as wide as it is tall.
NOTE: The values returned for the POS keyword are based on a
computation of the length of the text strings in your legend. If
you change the contents of the legend titles or if you change the
default text font, you must rerun LEGEND in interactive mode to
determine new values for the POS paramter.
; EXAMPLE interactive mode (put the box anywhere you want and press
; the right mouse button)
dcolors
plot,6*randf(20,3),/nodata
for i=1,6 do oplot,i*randf(20,3),li=i-1,color=i
lb='.cFirst bunch\\First\Second\Third\\.cSecond bunch\\forth\fifth\sixth'
legend,lb,li=[0,1,2,3,4,5],/box,bg=0,color=[1,2,3,4,5,6]
; EXAMPLE interactive mode. retrieve the value of POS for later calls:
!p.multi=[0,1,2]
plot,[0,.4],yrange=[0,1],li=0 & oplot,[0,.6],li=2 & oplot,[0,.9],li=3
legpos=0
lb=['.cLegend Demo','','one','two','three']
legend,lb,pos=legpos,li=[0,2,3]
plot,[0,.4],yrange=[0,1],li=0 & oplot,[0,.6],li=2 & oplot,[0,.9],li=3
legend,lb,pos=legpos,li=[0,2,3]
!p.multi=0
; EXAMPLE use fill mode to print a figure caption
w11x8
!p.multi=[0,1,2]
plot,dist(20)
t=$
'When called without the POS keyword, the legend position and size is\'+$
'set with the CURBOX routine. The legend is positioned by dragging the\'+$
'box where you want the legend to appear. The size of the legend area\'+$
'can be decreased/increased by the left/middle mouse buttons. When the\'+$
'right mouse button is pressed the legend is drawn and a numerical\'+$
'positioning string giving the current value of the POS keyword is\'+$
'written to the terminal (nothing printed if SILENT is set). You can\'+$
'run LEGEND in batch mode by pasting this value of POS into the LEGEND\'+$
'command line. The best way to get good-looking legends on your\'+$
'hardcopies is to size your graphics window to the approximate shape of\'+$
'the output media. For example a plot which is to be printed in\'+$
'landscape mode should be previewed on a window which is approximately\'+$
'1.4 times as wide as it is tall.'
legend,t,bg=0,pos=[0.02,-0.9,0.43,-0.25] ; default left justified
legend,t,bg=0,/fill,pos=[0.55,-0.9,0.97,-0.25] ; filled legend
; NOTE: procedure PFILL provides more elaborate text formatting capability
; EXAMPLE batch mode:
plot,[-50,50],[0,1.5],/nodata & x=findgen(101)-50.
li=indgen(6) & pos=[0.66,0.54,0.91,0.89]
for i=0,5 do oplot,x,1./(1.+(x/(i+2))^2),li=li(i)
labels='.cPlot Key\\First\Second\Third\Fourth\Fifth\Sixth'
legend,' ',bg=80,pos=pos+.02,/box
legend,labels,li=li,pos=pos,bg=40,/box
; EXAMPLE batch mode with symbols generated by USERSYMBOL:
plot,[-50,50],[0,1.5],/nodata & x=findgen(101)-50.
psym=['TRIANGLE','DIAMOND','PENTAGON','CIRCLE','SQUARE','SPADE']
pos=[0.66,0.54,0.91,0.89]
for i=0,5 do begin &$
usersymbol,psym(i) &$
oplot,x,1./(1.+(x/(i+2))^2),psym=8,symsize=2 &$
endfor
labels='.cPlot Key\\First\Second\Third\Fourth\Fifth\Sixth'
legend,' ',bg=4,pos=pos+.02,/box
legend,labels,psym=psym,pos=pos,bg=10,/box
author: Paul Ricchiazzi 4dec92
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS
15dec92: added legend titles, and CHARSIZE parameter
11jan93: added numsym parameter
20jan93: added thick parameter
2feb93: fixed positioning bug legend titles
25mar93: removed the NOBOX option, now you set BOX to get a box
29mar93: added the bg_color option to blank out legend area before writing
8apr93: use CURBOX for cursor control and LENSTR for exact string size
27apr93: improved alignment symbol and label (ylab=yy-.3*charsize*cnvrty)
9jun93: center legend labels when legend titles are longer (see dxcen)
17jun93: added ystretch option to increase vertical spacing
17jun93: default line thickness read from !p.thick
30sep93: .l implied when LINESTYLE, PSYM, COLOR, THICK not set. see NOLINES
28Jun94: LABELS is now normal input param, not a keyword.
28Jun94: legend "titles" don't correspond to LINESTYLE, PSYM, COLOR, THICK
vector elements; no need to put in dummy values. see examples
18Aug94: added USYM option
28Jun95: added the .f format option
8Sep95: added CLRBOX option
5oct95: added charsize adjustment for Y axis
sep96: added spos keyword, numsym defaults to 1 when linestyle not set
(See /home/drw/idl/old.esrg/legend2.pro)
ROUTINE: legendre
PURPOSE: compute legendre polynomial
USEAGE: result=legendre(x,n)
INPUT:
x argument of polynomial
n order of polynomial
DISCUSSION:
use recursion relation to compute legendre polynomial
for orders greater than 2:
n*P(n,x)=(2n-1)*x*P(n-1,x)-(n-1)*P(n-2,x)
P(0,x)=1. P(1,x)=x
EXAMPLE:
x=findrng(-1,1,10000)
f=legendre(x,20)
plot,x,f
; find phase function for a given set of legendre moments
awk='/pmaer/,/eof/ { gsub(/pmaer=/,"",$0); print $0}'
readbuf,'/home/paul/arm/iop_97/mie/mieout_1.0_1.33_0.00',b,awk=awk,nc=40
x=findrng(-1,1,10000)
p=[1,reform(b(0,*))]&f=0&for i=0,20 do f=f+.5*(2*i+1)*p(i)*legendre(x,i)&plot_io,x,f
; find zeroes of legendre polynomial
r=roots(f,0.) & xxx=interpolate(x,r) & fff=interpolate(f,r)
oplot,xxx,fff,psym=2
print,xxx
; print zeroes of rescaled legendre polynomial n=10,20,2
for n=10,20,2 do begin & f=legendre(x,n) & r=roots(f,0.) & print,n,min(abs(cos(!dtor*39.)-(interpolate(x,r)+1.)/2.)) & endfor
AUTHOR: Paul Ricchiazzi 06 Apr 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/legendre.pro)
ROUTINE: legend
PURPOSE: draws a plot legend
USEAGE: legend,labels,pos=pos,linestyle=linestyle,psym=psym,clrbox=clrbox,$
color=color,thick=thick,fg_color=fg_color,bg_color=bg_color,$
box=box,numsym=numsym,ystretch=ystretch,silent=silent,$
center=center,fill=fill,right=right,norm=norm,spos=spos,$
charsize=charsize
INPUT:
labels
an array of labels (required). Elements of LABELS which do not
begin with the characters ".l",".f",".c", or ".r" are treated as
legend labels. These elements are drawn to the right of a line
or symbol of given LINESTYLE, PSYM, COLOR or THICK type. The
total number of labels in LABELS (i.e., not counting legend
titles) should correspond to the number of elements in those
input parameters.
If any of the label strings start with the characters
".l",".L",".f",".c", or ".r" that element of the LABELS array is
treated as a legend title. Legend titles appear as left
justified (".l"), left justified in label field (".L"), filled
(".f") centered (".c") or right justified (".r") strings in the
legend box and do not correspond to elements of LINESTYLE, PSYM,
COLOR or THICK. Null strings ("") or blank strings (" ") are
also treated as legend titles. Lines or symbols are not drawn to
the right of legend titles.
If none of the keywords, LINESTYPE, PSYM, COLOR or THICK are
set, then all elements of LABELS will be treated as legend
titles and will be left justified unless prepended by ".f", ".c"
or ".r". or unless one of the keywords keywords "center",
"fill" "right" are set. These keywords set the default, string
justification but may always be overridden by one of the
justification flags.
Consider,
labels=['.ctitle','1','2','.lsecond title,'a','b']
linestyle= [1,2,3,4]
In this example LABELS contains 4 legend labels and 2 legend
titles. The correspondence with the linestyle input parameter is
as follows:
labels(1) <==> linestyle(0)
labels(2) <==> linestyle(1)
labels(4) <==> linestyle(2)
labels(5) <==> linestyle(3)
To simplify input, LABELS may also be specified as a single
string with the different LABEL elements separated by
backslashes (\) (E.g., labels='.cCloud height\\1\2\3\4\5'
KEYWORD INPUT:
pos
position and size of legend area in normalized data
coordinates. Format of this four element vector is
[x0,y0,x1,y1] where x0,y0 is the position of lower
left corner and x1,y1 is the position of the upper
right corner. For example pos=[.5,.5,.9,.9] specifies
a legend in the upper right quadrant of the data
window. If the POS parameter is not set or if POS is
set to zero, then the CURBOX procedure is called to
set the legend position interactively.
NOTE: the value of POS can be retrieved by setting POS
to a named variable which has an initial value of zero.
linestyle
an array of linestyle types, one for each label in LABELS
psym
an array of symbol types, one for each label in LABELS.
PSYM can be either a integer or string array. If PSYM is a
string array then the library routine USERSYMBOL is used to
create the symbols. In this case if the symbol specifier is
appended with '_f' then a filled symbol will be generated
clrbox
if set, a color-filled box appears to the left of each legend
label. The number of boxes drawn can be changed with NUMSYM.
If clrbox is set to 2, a color-filled circle appears to the left
of each legend label.
color
an array of color indices, one for each label in LABELS.
Any elements of COLOR set to -1 causes the default color,
!P.COLOR, to be used.
thick
an array of line thicknesses, one for each label in LABELS
(default=!p.thick)
numsym
number of symbol nodes used to indicate linestyle or symbol
type. The length of the line is measured in units of LENFAC
character widths so that the length of the line
= LENFAC*(NUMSYM-1) * X_CHARSIZE
(default=2 when linestyle, color or thick set, otherwise default=1)
lenfac
factor which controls length of line between symbols (see numsym)
(default=5)
fg_color
color of box and legend titles (default=!P.COLOR)
bg_color
background color. Setting BG_COLOR erases the area covered by
the legend (filling it with color BG_COLOR) prior to writing the
legend. If both BG_COLOR and !p.color are zero then the
background color is reset to 255 to gaurantee a readability.
box
if set draw a box around the legend text
silent
if not set, print box position string to the terminal
and show popup help on the CURBOX cursor routine
silent=1 don't print position string
silent=2 don't print position string, don't show help widget
center
if set, default action is to center legend labels
fill
if set, default action is to fill legend labels
right
if set, default action is to right justify labels
norm
if set, normalized coordinates are used to specify POS both
on input and printed output. This option allows placement
of the legend outside of a plot region.
ystretch
factor by which to increase vertical spacing of legend
entries. This parameter is particularly useful when used
with the SPOS keyword. (default = 1)
NOTE: the aspect ratio of the legend box can be
modified on the fly by pushing the cursor box against
one of the window boundaries and pressing the middle
button.
spos
string value which specifies legend position to one of a set of
standard positions. if spos is set, it supercedes the value of pos
'bl' = bottom left
'br' = bottom right
'tl' = top left
'tr' = top right
'top'= top center
'bot'= bottom center
charsize
character size used when legend position specified with SPOS.
CHARSIZE has no effect when POS is used to set position.
OUTPUT: none
PROCEDURE:
When called without the POS keyword, the legend position and size
is set with the CURBOX routine. The legend is positioned by
dragging the box where you want the legend to appear. The size
of the legend area can be decreased/increased by the left/middle
mouse buttons. When the right mouse button is pressed the legend
is drawn and a numerical positioning string giving the current
value of the POS keyword is written to the terminal (nothing
printed if SILENT is set). You can run LEGEND in batch mode by
pasting this value of POS into the LEGEND command line. The best
way to get good-looking legends on your hardcopies is to size
your graphics window to the approximate shape of the output
media. For example a plot which is to be printed in landscape
mode should be previewed on a window which is approximately 1.4
times as wide as it is tall.
NOTE: The values returned for the POS keyword are based on a
computation of the length of the text strings in your legend. If
you change the contents of the legend titles or if you change the
default text font, you must rerun LEGEND in interactive mode to
determine new values for the POS paramter.
;; EXAMPLE interactive mode (put the box anywhere you want and press
;; the right mouse button)
dcolors
plot,6*randf(20,3),/nodata
for i=1,6 do oplot,i*randf(20,3),li=i-1,color=i
lb='.cFirst bunch\\First\Second\Third\\.cSecond bunch\\forth\fifth\sixth'
legend,lb,li=[0,1,2,3,4,5],/box,bg=0,color=[1,2,3,4,5,6]
;; EXAMPLE interactive mode. retrieve the value of POS for later calls:
!p.multi=[0,1,2]
plot,[0,.4],yrange=[0,1],li=0 & oplot,[0,.6],li=2 & oplot,[0,.9],li=3
legpos=0
lb=['.cLegend Demo','','one','two','three']
legend,lb,pos=legpos,li=[0,2,3]
plot,[0,.4],yrange=[0,1],li=0 & oplot,[0,.6],li=2 & oplot,[0,.9],li=3
legend,lb,pos=legpos,li=[0,2,3]
!p.multi=0
;; EXAMPLE use fill mode to print a figure caption
w11x8
!p.multi=[0,1,2]
plot,dist(20)
t=$
'When called without the POS keyword, the legend position and size is\'+$
'set with the CURBOX routine. The legend is positioned by dragging the\'+$
'box where you want the legend to appear. The size of the legend area\'+$
'can be decreased/increased by the left/middle mouse buttons. When the\'+$
'right mouse button is pressed the legend is drawn and a numerical\'+$
'positioning string giving the current value of the POS keyword is\'+$
'written to the terminal (nothing printed if SILENT is set).'
legend,t,bg=0,pos=[0.00,-0.52,0.47,-0.18] ; default left justified
legend,t,bg=0,/right,pos=[0.53,-0.52,1.00,-0.18] ; right justified
legend,t,bg=0,/center,pos=[0.27,-1.00,0.74,-0.66] ; centered
; NOTE: procedure PFILL provides more elaborate text formatting capability
;; EXAMPLE batch mode:
plot,[-50,50],[0,1.5],/nodata & x=findgen(101)-50.
li=indgen(6) & pos=[0.66,0.54,0.91,0.89]
for i=0,5 do oplot,x,1./(1.+(x/(i+2))^2),li=li(i)
labels='.cPlot Key\\First\Second\Third\Fourth\Fifth\Sixth'
legend,' ',bg=80,pos=pos+.02,/box
legend,labels,li=li,pos=pos,bg=40,/box
;; EXAMPLE batch mode with symbols generated by USERSYMBOL:
plot,[-50,50],[0,1.5],/nodata & x=findgen(101)-50.
psym=['TRIANGLE','DIAMOND','PENTAGON','CIRCLE','SQUARE','SPADE']
pos=[0.66,0.54,0.91,0.89]
for i=0,5 do begin &$
usersymbol,psym(i) &$
oplot,x,1./(1.+(x/(i+2))^2),psym=8,symsize=2 &$
endfor
labels='.cPlot Key\\First\Second\Third\Fourth\Fifth\Sixth'
legend,' ',bg=4,pos=pos+.02,/box
legend,labels,psym=psym,pos=pos,bg=10,/box
;;
author: Paul Ricchiazzi 4dec92
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS
15dec92: added legend titles, and CHARSIZE parameter
11jan93: added numsym parameter
20jan93: added thick parameter
2feb93: fixed positioning bug legend titles
25mar93: removed the NOBOX option, now you set BOX to get a box
29mar93: added the bg_color option to blank out legend area before writing
8apr93: use CURBOX for cursor control and LENSTR for exact string size
27apr93: improved alignment symbol and label (ylab=yy-.3*charsize*cnvrty)
9jun93: center legend labels when legend titles are longer (see dxcen)
17jun93: added ystretch option to increase vertical spacing
17jun93: default line thickness read from !p.thick
30sep93: .l implied when LINESTYLE, PSYM, COLOR, THICK not set. see NOLINES
28Jun94: LABELS is now normal input param, not a keyword.
28Jun94: legend "titles" don't correspond to LINESTYLE, PSYM, COLOR, THICK
vector elements; no need to put in dummy values. see examples
18Aug94: added USYM option
28Jun95: added the .f format option
8Sep95: added CLRBOX option
5oct95: added charsize adjustment for Y axis
sep96: added spos keyword, numsym default = 1 unless linestyle or color set
nov96: CLRBOX=2 yields filled circles instead of boxes
(See /home/drw/idl/esrg/legend_esrg.pro)
ROUTINE: lenstr
USEAGE: result=lenstr(str)
input:
str a single string or string array.
output:
result length of the string(s) in normalized units
the number of elements of RESULT matches the number of
elements of STRING.
procedure:
This function returns the physical length of the
string on the output device, not the number of
characters. This is done by first switching to 'X'
and writing the string(s) with XYOUTS in graphics
mode 5, which disables display to the screen but
does not interfere with operation of XYOUTS. The
WIDTH keyword parameter of XYOUTS is used to
retrieve the physical length of the string(s).
Example:
;;
for i=(byte(' '))[0],(byte('z'))[0] do print,string(i),lenstr(string(i))
;;
author: Paul Ricchiazzi 7apr93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/lenstr.pro)
ROUTINE: lenstr
USEAGE: result=lenstr(str)
input:
str a single string or string array.
output:
result length of the string(s) in normalized units
the number of elements of RESULT matches the number of
elements of STRING.
procedure:
This function returns the physical length of the
string on the output device, not the number of
characters. This is done by first switching to 'X'
and writing the string(s) with XYOUTS in graphics
mode 5, which disables display to the screen but
does not interfere with operation of XYOUTS. The
WIDTH keyword parameter of XYOUTS is used to
retrieve the physical length of the string(s).
author: Paul Ricchiazzi 7apr93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/lenstr.pro)
ROUTINE: letter
PURPOSE: write a letter for figure numbering
USEAGE: letter,x,y,charsize=charsize,font=font
INPUT:
x subnormal coordinates of letter (default = .05)
y subnormal coordinates of letter (default = .95)
KEYWORD INPUT:
charsize character size (size is halved if more than 2 plots are
ganged in either horizontal or vertical)
font vector drawn font (default = 17)
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 13 Oct 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/letter.pro)
Loop over frames in memory created by FSET.
The user may optionally specify the first and last frames (default is
to use all frames), the time delay between each frame (default is 0.5 sec),
the direction of looping (default is increasing frame number), and whether
to pause at the last frame (default is no pause). The user hits any key
to end looping.
USAGE: LF
OPTIONAL KEYWORDS:
FIRST First frame (default=current frame)
LAST Last frame (default=frame preceding current frame)
DELAY Time delay between frame updates in seconds (default=0.5)
/BACKWARD Loop over decreasing frame numbers (defualt=increasing)
/PAUSE Pause at last frame for 2.0*DELAY seconds
/QUIET Do not print any information (default=print)
/HELP Print help information only (default=do not print)
USAGE NOTES:
(1) FSET must have been executed previously to create frame buffers.
AUTHOR: Liam Gumley, CIMSS/SSEC, 15-APR-1996 (liam.gumley@ssec.wisc.edu)
RELATED COMMANDS:
FSET Set up frames in memory
SF Show a frame and print frame information
AF Advance one frame
BF Backup one frame
EXAMPLE:
; Create 4 frames, display a graphic in each, and then loop.
FSET,FRAMES=4,XSIZE=512,YSIZE=512
FOR I=4,7 DO BEGIN & TVSCL,REBIN(DIST(2^I),512,512,/SAMPLE) & LOADCT,39 & AF & ENDFOR
LF
(See /home/drw/idl/aux/lf.pro)
lineplot Widget line plot tool. If widget is already active, the routine will over plot the new x,y on the existing plot. CALLING SEQUENCE: lineplot,x,y or lineplot,y INPUTS x - input x vector y - input y vector OPTIONAL INPUT PARAMETERS ptitle - main plot title title - title of the plot or overplot vectors xtitle - title for the xaxis ytitle - title for the yaxis xrange - initial xrange for the plot yrange - initial yrange for the plot group - group id of calling widget INTERACTIVE INPUTS: In addition to the widget parameters controlled by buttons and text field inputs: 1) Use the left mouse button to measure a feature location in the plot. 2) Push the center mouse button and hold it down to define two corners of a region to be zoomed. The large text box containing the history may be edited before writing to a file HISTORY: version 1 D. Lindler Aug 1999
(See /home/drw/idl/fuse/lineplot.pro)
line_edit Widget plot edit tool for FUSE_SCAN CALLING SEQUENCE: line_edit,x,y,mask INPUTS x - input x vector y - input y vector mask - mask of good data (1=good, 0=bad) OPTIONAL INPUT PARAMETERS ptitle - main plot title title - title of the plot or overplot vectors xtitle - title for the xaxis ytitle - title for the yaxis xrange - initial xrange for the plot yrange - initial yrange for the plot group - group id of calling widget modal - modal (set to make modal widget) INTERACTIVE INPUTS: In addition to the widget parameters controlled by buttons and text field inputs: 1) Use the left mouse button to measure a feature location in the plot. 2) Push the center mouse button and hold it down to define two corners of a region to be zoomed. The large text box may be edited before writing to a file HISTORY: version 1 D. Lindler Sept 1999
(See /home/drw/idl/fuse/line_edit.pro)
line_eqwidth
Widget to measure the essential attributes of a spectral feature
including equivalent width
CALLING SEQUENCE:
line_eqwidth,wave,flux,results
INPUTS:
wave - wavelength vector of region containing the line
flux - flux vector of region containing the line
OUTPUTS:
results - vector of results
results(0)= the original value for W0.
results(1)= short wavelength limit to integration
results(2)= extremum of spectral line
results(3)= long wavelength limit to integration
results(4)= radial velocity for short wavelength limit
to integration.
results(5)= radial velocity for extremum of spectral line
results(6)= radial velocity for the long wavelength limit
to integration.
results(7)= flux at the short wavelength limit to the
integration.
results(8)= flux at the spectral line extremum
results(9)= flux at the long wavelength limit to the
integration.
results(10)=continuum flux
results(11)=residual flux at extremum
results(12)=equivalent width
results(13)=total flux in the feature.
results(14)=flux weighted wavelength for feature.
results(15)=flux weighted sigma, which for a
gaussian profile can be related to the full
width at half maximum.
results(16)=net flux in feature
results(17)=flux weighted wavelength, with continuum
not included
results(18)=flux weighted sigma for net flux only.
OPTIONAL KEYWORD INPUTS:
wrest - Rest wavelength for the spectral line
lineid - Text line identification for output plot annotation
title - Title (e.g. filename)
wmin - minimum wavelength to plot
wmax - maximum wavelength to plot
fmin - minimum flux to plot
fmax - maximum flux to plot
NOTES:
Uses the same computation as the old IUE FEATURE.PRO
HISTORY
version 1 D. Lindler Feb. 2000
(See /home/drw/idl/fuse/line_eqwidth.pro)
ROUTINE: line_fit PURPOSE: Perform least squares fit to x and y ordered data USEAGE: line_fit,x,y,fit,m,c INPUT: x abscissa array y ordinate array OUTPUT: fit fit array of y values m Line slope c Line intercept AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/line_fit.pro)
ROUTINE: line_fit PURPOSE: Perform least squares fit to x and y ordered data USEAGE: line_fit,x,y,fit,m,c INPUT: x abscissa array y ordinate array OUTPUT: fit fit array of y values m Line slope c Line intercept AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/ptg/line_fit.pro)
ROUTINE: calc_flux
PURPOSE: Given the FWHM, and Io of a line the routine will
calculate the total line flux
USEAGE: CALC_FLUX, Io, FWHM, LineFlux
INPUT:
Io Float contianing the peak intensity
FWHM The FWHM in Angstroms
OUTPUT:
LineFlux The total line flux in whatever units Io was in.
AUTHOR: Peter T. Gallagher, March '98.
(See /home/drw/idl/bin/line_flux.pro)
ROUTINE: calc_flux
PURPOSE: Given the FWHM, and Io of a line the routine will
calculate the total line flux
USEAGE: CALC_FLUX, Io, FWHM, LineFlux
INPUT:
Io Float contianing the peak intensity
FWHM The FWHM in Angstroms
OUTPUT:
LineFlux The total line flux in whatever units Io was in.
AUTHOR: Peter T. Gallagher, March '98.
(See /home/drw/idl/bin/ptg/line_flux.pro)
ROUTINE: line_id PURPOSE: Allows user to click on a line in the current window and then checks Kelly for line ID. USEAGE: line_id INPUT: None OUTPUT: None AUTHOR: Peter T. Gallagher, Jan. '98
(See /home/drw/idl/bin/line_id.pro)
ROUTINE: line_id PURPOSE: Allows user to click on a line in the current window and then checks Kelly for line ID. USEAGE: line_id INPUT: None OUTPUT: None AUTHOR: Peter T. Gallagher, Jan. '98
(See /home/drw/idl/bin/ptg/line_id.pro)
line_norm Widget to interactively normalize a spectrum CALLING SEQUENCE: line_norm,x,y,ynorm,norm INPUTS x - input x vector y - input y vector OUTPUTS: ynorm - normalized spectrum norm - continuum used for normalization OPTIONAL INPUT PARAMETERS ptitle - main plot title title - title of the plot or overplot vectors xtitle - title for the xaxis ytitle - title for the yaxis xrange - initial xrange for the plot yrange - initial yrange for the plot group - group id of calling widget modal - modal (set to make modal widget) INTERACTIVE INPUTS: In addition to the widget parameters controlled by buttons and text field inputs: 1) Use the left mouse button to move/drag a control point 2) Use the right button to add a new control point 3) Use center button to zoom. (Select one corner, hold down and drag to opposite corner of region to be zoomed) HISTORY: version 1 D. Lindler Sept 1999
(See /home/drw/idl/fuse/line_norm.pro)
NAME:
LINKEDLIST
FILENAME:
linkedlist__define.pro
PURPOSE:
The purpose of this program is to implement a list that
is linked in both the forward and backward directions. There
is no restriction as to what can be stored in a linked list
node. The linked list is implemented as an object.
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:
General programming.
CALLING SEQUENCE:
mylist = Obj_New('LINKEDLIST', item)
OPTIONAL INPUTS:
item: The first item added to the list. Items can be any
valid IDL variable type.
COMMON BLOCKS:
Are you kidding?!
RESTRICTIONS:
Be sure to destroy the LINKEDLIST object when you are finished
with it: Obj_Destroy, mylist
Node index numbers start at 0 and go to n-1, where n is the
number of items in the list.
PUBLIC METHODS:
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::ADD, item, index, AFTER=after, BEFORE=before
The ADD method adds a data item to the list.
Parameters:
item: The data item to be added to the list. Required.
index: The location in the list where the data item is
to be added. If neither the AFTER or BEFORE keyword is
set, the item is added AFTER the item at the index location.
If index is missing, the index points to the last item in
the list. Optional.
Keywords:
AFTER: If this keyword is set, the item is added after the
item at the current index.
BEFORE: If this keyword is set, the item is added before the
item at the current index.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::DELETE, index, ALL=all
The DELETE method deletes an item from the list.
Parameters:
index: The location in the list where the data item is
to be delete. If index is missing, the index points to
the last item in the list. Optional.
Keywords:
ALL: If this keyword is set, all items in the list are deleted.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::GET_COUNT
The GET_COUNT method returns the number of items in the list.
Return Value: The number of items stored in the linked list.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::GET_ITEM, index
The GET_ITEM method returns a pointer to the specified data
item from the list.
Parameters:
index: The location in the list from which the data item is
to be retrieved. If not present, the last item in the list
is retrieved. Optional.
Return Value: A pointer to the specified data item stored
in the list.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
FUNCTION LINKEDLIST::GET_NODE, index
The GET_NODE method returns a pointer to the specified node
from the list.
Parameters:
index: The location in the list from which the data node is
to be retrieved. If not present, the last node in the list
is retrieved. The node is a structure with three fields:
Previous is a pointer to the previous node in the list.
Next is a pointer to the next node in the list. A null pointer
in the previous field indicates the first node on the list. A
null pointer in the next field indicates the last node on the
list. The item field is a pointer to the item stored in the
node. Optional.
Return Value: A pointer to the specified node structure in
the linked list.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::HELP, PRINT=print
The HELP method performs a HELP command on each item
in the linked list.
Keywords:
PRINT: If this keyword is set, the PRINT command is used
instead of the HELP command on the items in the list.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
PRO LINKEDLIST::MOVE_NODE, nodeIndex, location, BEFORE=before
The MOVE_NODE method moves a list node from one location to another.
Parameters:
nodeIndex: The location in the list of the node you are moving.
Required.
location: The location (index) you are moving the node to. If
location is missing, the location points to the node at the
end of the list.
Keywords:
BEFORE: If this keyword is set, the node is added to the
list before the location node. Otherwise, it is added after
the location node.
;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
EXAMPLE:
mylist = Obj_New("LINKEDLIST", 5)
mylist->Add, 10
mylist->Add, 7.5, 1, /Before
mylist->Add, 12.5
mylist->Help
mylist->Delete
mylist->Help, /Print
MODIFICATION HISTORY:
Written by: David Fanning, 25 August 98.
25 August 99. Fixed several errors in various methods dealing with
moving nodes from one place to another. DWF.
(See /home/drw/idl/aux/linkedlist__define.pro)
ROUTINE: linterp
PURPOSE: extend IDL's interpolate procedure to handle up
to 8 dimensions
USEAGE: result=linterp(table,f1,f2,f3,f4,f5,f6,f7,f8)
INPUT:
tab table of values depending on upto 8 parameters
f1,f2.. floating index parameters.
NOTE: the number of input parameters must be appropriate to
the size of the look-up table. For example for a 3-d table,
specify f1,f2,f3
KEYWORD INPUT:
GRID if set the input parameters are used to create a grid of
parameter values. In this case the input parameters
need not be all the same size. If GRID is not set all
input arrays (f1,f2...) and the returned value are of
the same size and dimensionality. If GRID is set the
f parameters may be scalars or vectors, but not arrays.
CLIP If this keyword is set, locations less than the minimum or
greater than the maximum corresponding subscript of TABLE
are set to the nearest element of TABLE. The effect of
MISSING is disabled when CLIP is set.
OUTPUT:
result interpolated value
EXAMPLE:
tab=findgen(5,5,5,5)
print,linterp(tab,1.2,3.2,1.1,2.2)
author: Paul Ricchiazzi sep93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/linterp.pro)
NAME: LIST2HIST PURPOSE: Reads FITS file with binary table extensions (as saved by CREATELIST or created by detector EGSE). Can read either XYP or TXYP files. Usually called from READIT rather than run directly. CATEGORY: FITS CALLING SEQUENCE: result = LIST2HIST(Filename) INPUTS: Filename: Input FITS file with photon list data in a binary table extension. KEYWORD PARAMETERS: NOTE: DO NOT change these without also modifying LIST2LIST, HIST2HIST and OPUS2HIST. NOTE: THE RANGE values are passed via the _EXTRA keyword to LIST2LIST. TRANGE: An [N,2] element matrix containing the start and ending times of N intervals to include in the array. If N = 1, a simple two element vector, [tstart,tend] may be used. XRANGE: A two element vector containing the range of x to include in the array. YRANGE: A two element vector containing the range of y to include in the array. PRANGE: A two element vector containing the range of pulse height to include in the array. SCALE: Scale factor for array. Can be set to make the resultant array a reasonable size. A scale size of n bins the image n x n. PHD: The returned pulse height distribution. FHEADER:The returned FITS header. BHEADER:The returned FITS header from the binary table extension. NOTE: The following keyword is only in this routine. PHOTONS:Read only this number of photons from the file. If it is greater than the number of events, read all of the data. GOODTIMES:If included, and nonzero, and there is a second binary extension containing good time intervals (such as those created by OPUS), then use only the good times listed. SILENT: If included, suppress informative messages. XSCALED,YSCALED: If these keywords are present, on return they will contain the value of x and y scaling that was applied to the data. They are probably the values of SPECBINX and SPECBINY or 1,1. COMMON BLOCKS: LAMSPACE:for IMAGE.PRO. MODIFICATION HISTORY: Written by David Sahnow, 4 October 1996. 10 October 1996 Changed to a function which returns image. 27 November 1996 Added keywords, and common block for IMAGE.PRO. 6 February 1997 Replaced image(0) = q with REFORM command for turning 1D histogram into 2D image. 28 March 1997 Modified to read UCB XYP files in addition to JHU TXYP. Added PHD keyword 8 April 1997 Modified to be backward compatible with old TXYP format. 16 May 1997 Forced image to be an integer rather than the long that HISTOGRAM returns. 22 May 1997 Added keywords BHEADER, FHEADER 13 August 1997 Modified to always calculate PHD. Previously only calculated it if KEYWORD_SET(PHD), which was zero if called with an empty array. Modified xsegsize, ysegsize if scale != 1. 3 October 1997 Added verbose variable. Modified logic used in checking xrange so that rangekeys > 0 only if at least one of the range keywords requires removing some photons. Commented out the second call to mrdfits because it doesn't seem to be necessary. 11 November 1997 Added the ability to read UCB XYPT files. 14 November 1997 Added oldstyle = 2 option for very old XYP files. 2 December 1997 Modified to work with files containing zero photons. 10 January 1998 Fixed bug in xrange,yrange,prange checks. 30 Septempber 1998 Added ability to read OPUS TTAG files. This has oldstyle=3. 4 October 1998 Added check that data_fmt is an integer before concluding that the DATA_FMT keyword doesn't exist. 13 November 1998 Added PHOTONS keyword. 8 April 1999 Added FSCALE keyword to MRDFITS calls. 21 August 1999 Now doesn't bomb if no good photons found. 12 September 1999 Added GOODTIMES keyword. 18 September 1999 Modified TRANGE keyword to allow multiple ranges. 8 December 1999 Simplified substantially by using LIST2LIST for reading the file, and screening for xrange, etc. 30 May 2000 Added SILENT keyword. 3 July 2000 Added XSCALED, YSCALED keywords.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/list2hist.pro)
NAME: LIST2LIST PURPOSE: Reads FITS file with binary table extensions (as saved by CREATELIST or created by detector EGSE). Can read either XYP or TXYP files. Usually called from READIT rather than run directly. Returns a structure containing the data. CATEGORY: FITS CALLING SEQUENCE: result = LIST2LIST(Filename) INPUTS: Filename: Input FITS file with photon list data in a binary table extension. KEYWORD PARAMETERS: NOTE: DO NOT change these without also modifying HIST2HIST and OPUS2HIST, and LIST2HIST. TRANGE: An [N,2] element matrix containing the start and ending times of N intervals to include in the array. If N = 1, a simple two element vector, [tstart,tend] may be used. XRANGE: A two element vector containing the range of x to include in the array. YRANGE: A two element vector containing the range of y to include in the array. PRANGE: A two element vector containing the range of pulse height to include in the array. SCALE: Scale factor for array. Can be set to make the resultant array a reasonable size. A scale size of n bins the image n x n. PHD: The returned pulse height distribution. FHEADER:The returned FITS header. BHEADER:The returned FITS header from the binary table extension. NOTE: The following keyword is not in all routines. PHOTONS:Read only this number of photons from the file. If it is greater than the number of events, read all of the data. OLDSTYLE:Variable used to determine what the form of the structure is. XSEGSIZE:Segment size, as determined from the header. YSEGSIZE:Segment size, as determined from the header. SILENT: If included, suppress informative messages. XSCALED,YSCALED: If these keywords are present, on return they will contain the value of x and y scaling that was applied to the data. They are probably the values of SPECBINX and SPECBINY or 1,1. COMMON BLOCKS: LAMSPACE:for IMAGE.PRO. MODIFICATION HISTORY: Written by David Sahnow, based on HIST2LIST, 15 August 1999. 18 September 1999 Modified TRANGE keyword to allow multiple ranges. 22 October 1999 Fixed a bug which caused all photons to be returned if a time/x/y/pha range containing no photons was selected. 8 December 1999 Added OLDSTYLE, XSEGSIZE, YSEGSIZE keywords for use by the modified LIST2HIST. 30 May 2000 Added SILENT keyword. 3 July 2000 Added XSCALED, YSCALED (used by READIT). These are set equal to SPECBINX/Y if they exist. Otherwise, they are 1.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/list2list.pro)
NAME:
LITMSOL
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:
Solve the light-time equation between two moving bodies
MAJOR TOPICS:
Geometry, Physics
CALLING SEQUENCE:
LITMSOL, T1, X1, Y1, Z1, T2, INFO2, RAW2, OBJ2, INFOSUN, RAWSUN, $
/RECEIVER, TBASE=, TOLERANCE=, POSUNITS=, MAXITER=, $
/NO_SHAPIRO
DESCRIPTION:
The procedure LITMSOL solves the light time equation between two
moving bodies in the solar system. Given the time and position of
reception or transmission of a photon, this equation determines the
time of transmission or reception at the other solar system body.
Since both bodies may be moving, the equation must be solved
iteratively.
The trajectories of solar system bodies must be described by either
a JPL ephemeris, or by a JPL-like ephemeris generated by
JPLEPHMAKE. This routine calls JPLEPHINTERP.
The user specifies the known time and position of interaction as
T1, X1, Y1 and Z1, in units of POSUNITS. The time of interaction
at the other body -- the solution to the light time equation -- is
returned as T2. If the photon was *received* at time T1, then the
RECEIVER keyword should be set (in which case the transmission must
have occurred in the past).
Since the solution is iterative, the user may specify a solution
tolerance, and a maximum number of iterations.
If users wish to include the Shapiro time delay, which has a
maximum amplitude of approximately 250 usec, they must specify the
ephemeris of the Sun (INFOSUN, RAWSUN). The Shapiro delay is the
extra general relativistic delay caused by the Sun's potential.
INPUTS:
T1 - epoch of interaction, in Julian days, in the TDB timescale.
(scalar or vector)
X1, Y1, Z1 - coordinates of interaction, referred to the solar
system barycenter, in J2000 coordinates. Units are
described by POSUNITS. (scalar or vector)
INFO2, RAW2 - ephemeris of other solar system body, returned by
JPLEPHREAD or JPLEPHMAKE.
INFOSUN, RAWSUN - ephemeris of at least the Sun, as returned by
JPLEPHREAD. Only used of NO_SHAPIRO is not set.
OUTPUTS:
T2 - upon output, epoch of interaction at the second solar system
body, in Julian days, in the TDB timescale.
KEYWORD PARAMETERS:
RECEIVER - if set, then the epoch T1 is a reception of a photon.
Otherwise T1 is the epoch of transmission of a photon.
TBASE - a fixed epoch time (Julian days) to be added to each value
of T1. Since subtraction of large numbers occurs with
TBASE first, the greatest precision is achieved when TBASE
is expressed as a nearby julian epoch, T1 is expressed
as a small offset from the fixed epoch.
Default: 0
POSUNITS - the units for positions, one of 'CM', 'KM', 'LT-S' or
'AU'.
Default: 'CM'
TOLERANCE - the solution tolerance, expressed in POSUNITS.
Default: 1000 CM
ERROR - upon return, a vector giving the estimated error in the
solution for each point, expressed in POSUNITS. This
quantity should be less than TOLERANCE unless the number
of iterations exceeded MAXITER.
MAXITER - maximum number of solution iterations to be taken.
Default: 5
NO_SHAPIRO - if set, then the Shapiro delay will not be accounted
for. If NO_SHAPIRO is set, then INFOSUN and RAWSUN
do not need to be supplied.
EXAMPLE:
SEE ALSO:
JPLEPHREAD, JPLEPHINTERP
MODIFICATION HISTORY:
Written, 6 May 2002, CM
Documented, 12 May 2002, CM
Added TGUESS keyword, 29 May 2002, CM
Added ERROR and X/Y/ZOFF keywords, 25 Sep 2002, CM
$Id: litmsol.pro,v 1.4 2002/09/25 21:19:45 craigm Exp $
(See /home/drw/idl/aux/markwardt/litmsol.pro)
NAME:
LOADDATA
PURPOSE:
The purpose of this function is to read a selection of standard
data sets that are found in the normal IDL distribution in the
subdirectory $IDL_DIR/examples/data. At least 17 data sets are
available in all categories of data. The user selects one of the
possible data sets with the mouse.
CATEGORY:
File I/O.
CALLING SEQUENCE:
If calling from the IDL command line:
data = LoadData()
If calling from within a widget program:
data = LoadData(Cancel=cancelled, Group_Leader=event.top)
If you know which data set you want, you can load it directly:
data = LoadData(7)
OPTIONAL INPUTS:
selection : The number of the data selection. Values start at 1,
and go up to the number of data sets available (currently 17).
KEYWORD PARAMETERS:
CANCEL : An output keyword that is 1 of the use clicked the CANCEL
button and 0 otherwise.
data = Loaddata(Cancel=cancelled)
IF cancelled THEN RETURN
GROUP_LEADER: The group leader of the widget. This keyword
is required if you wish LOADDATA to be a modal widget program.
(Which you *always* do when calling it from a widget program.)
IMAGES: Set this keyword if you only want to select 2D image
data sets. Note that the selection number does *not* change
just because fewer data sets are available in the selection
widget.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To load the world elevation data set:
image = LoadData(7)
MODIFICATION HISTORY:
Written by: David Fanning, 5 March 1999.
Added some additonal random data capability. 29 April 99. DWF
Added IMAGES keyword. 31 March 2000. DWF.
(See /home/drw/idl/aux/loaddata.pro)
NAME: LOCATESPECTRUM PURPOSE: This procedure finds the x and y extents of the chosen spectrum. CATEGORY: Data. CALLING SEQUENCE: LOCATESPECTRUM, Channel, Slit, Xledge, Xredge, Ybot, Ytop, Xpixsize, Ypixsize INPUTS: Channel:Channel name, e.g. 'LiF1A' Slit: Slit name: 'HIRS', 'MDRS', 'LWRS', or 'PINH' OUTPUTS: Xledge: Position of left edge of spectrum, in pixels. Xredge: Position of right edge of spectrum, in pixels. Ybot: Position of bottom edge of spectrum, in pixels. Ytop: Position of top edge of spectrum, in pixels. Xpixsize, Ypixsize: X and Y pixel size in um for the input segment. PROCEDURE: Straightforward. EXAMPLE: To find the location of the LiF1A MDRS data: IDL> locatespectrum,'LiF1A','MDRS',Xledge,Xredge,Ybot,Ytop MODIFICATION HISTORY: Originally part of STRABSORB.PRO. Created LOCATESPECTRUM on 9 June 2000. 3 July 2000 Removed 'Segment' input. Now gets segment from 'Channel.' Changed so that all inputs are case insensitive. 13 September 2000 Added Xpixsize, Ypixsize.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/locatespectrum.pro)
ROUTINE: locate
USEAGE: locate,lat,lon,alat,alon,x,y
PURPOSE:
This routine is used by COASTLINE to find the array indices
of a given geographical point within irregular latitude and
longitude arrays. Given the coordinate arrays alat(i,j) and
alon(i,j), LOCATE finds the "floating point" indices x,y such
that,
interpolate(alat,x,y)=lat
interpolate(alon,x,y)=lon
Stated more abstractly, LOCATE solves two simultaneous non-linear
equations of the form
f(x,y)=u
g(x,y)=v
where the functions f and g are actually arrays of values
indexed by x and y.
INPUT:
lat a vector of geographic latitudes
lon a vector of geographic longitudes
alat array of image latitudes
alon array of image longitudes
OUTPUT:
x,y "floating point" array indicies such that
lat=interpolate(alat,x,y)
lon=interpolate(alon,x,y)
EXAMPLE:
c=(cmplxgen(100,100)+complex(20,20))/50 & c=c+c^2+c^3
alon=imaginary(c) & alat=float(c)
!p.multi=[0,1,2]
xo=fix(54+(20+25*(findgen(21) mod 2))*cos(2*!pi*findgen(21)/20))
yo=fix(54+(20+25*(findgen(21) mod 2))*sin(2*!pi*findgen(21)/20))
lon=alon(xo,yo) & lat=alat(xo,yo)
plot,alon,alat,/noda,ytit='latitude',xtit='longitude',/xstyle,/ystyle
oplot,alon,alat,psym=3
oplot,lon,lat,psym=-4
delvar,x,y
locate,lat,lon,alat,alon,x,y
contour,alat,levels=contlev(alat,maxlev=30),/follow,c_color=150
contour,alon,levels=contlev(alon,maxlev=30),/follow,/over,c_color=80
oplot,x,y,psym=-4
table,lat,interpolate(alat,x,y),lon,interpolate(alon,x,y),x,xo,y,yo
DISCUSSION:
LOCATE uses Newton-Raphson iteration of the linearized equations
for latitude and longitude. The equation is itereated repeatedly
only for those elements of the input vectors which have not
satisfied the convergence criterion,
(lat-alati)^2+(lon-aloni)^2 lt (.001)^2
where alati and aloni are the values of ALAT and ALON interpolated
to the current estimates of X and Y. This procedure will probably
fail if the gradients of ALAT and ALON arrays do not form linearly
independent vector fields. You have trouble if somewhere in
the grid grad(ALAT) is proportional to grad(alon)
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS:
27oct92 Provide default initial guesses for x and y. This allows the
user to call LOCATE without pre-defining x and y.
12jun95 allow LOCATE to accept a vectors of LAT-LON points, improves speed
(See /home/drw/idl/esrg/locate.pro)
ROUTINE: locate
USEAGE: locate,lat,lon,alat,alon,x,y
PURPOSE:
This routine is used by COASTLINE to find the array indices
of a given geographical point within irregular latitude and
longitude arrays. Given the coordinate arrays alat(i,j) and
alon(i,j), LOCATE finds the "floating point" indices x,y such
that,
interpolate(alat,x,y)=lat
interpolate(alon,x,y)=lon
Stated more abstractly, LOCATE solves two simultaneous non-linear
equations of the form
f(x,y)=u
g(x,y)=v
where the functions f and g are actually arrays of values
indexed by x and y.
INPUT:
lat a vector of geographic latitudes
lon a vector of geographic longitudes
alat array of image latitudes
alon array of image longitudes
OUTPUT:
x,y "floating point" array indicies such that
lat=interpolate(alat,x,y)
lon=interpolate(alon,x,y)
EXAMPLE:
c=(cmplxgen(100,100)+complex(20,20))/50 & c=c+c^2+c^3
alon=imaginary(c) & alat=float(c)
!p.multi=[0,1,2]
xo=fix(54+(20+25*(findgen(21) mod 2))*cos(2*!pi*findgen(21)/20))
yo=fix(54+(20+25*(findgen(21) mod 2))*sin(2*!pi*findgen(21)/20))
lon=alon(xo,yo) & lat=alat(xo,yo)
plot,alon,alat,/noda,ytit='latitude',xtit='longitude',/xstyle,/ystyle
oplot,alon,alat,psym=3
oplot,lon,lat,psym=-4
delvar,x,y
locate,lat,lon,alat,alon,x,y
contour,alat,levels=contlev(alat,maxlev=30),/follow,c_color=150
contour,alon,levels=contlev(alon,maxlev=30),/follow,/over,c_color=80
oplot,x,y,psym=-4
table,lat,interpolate(alat,x,y),lon,interpolate(alon,x,y),x,xo,y,yo
DISCUSSION:
LOCATE uses Newton-Raphson iteration of the linearized equations
for latitude and longitude. The equation is itereated repeatedly
only for those elements of the input vectors which have not
satisfied the convergence criterion,
(lat-alati)^2+(lon-aloni)^2 lt (.001)^2
where alati and aloni are the values of ALAT and ALON interpolated
to the current estimates of X and Y. This procedure will probably
fail if the gradients of ALAT and ALON arrays do not form linearly
independent vector fields. You have trouble if somewhere in
the grid grad(ALAT) is proportional to grad(alon)
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS:
27oct92 Provide default initial guesses for x and y. This allows the
user to call LOCATE without pre-defining x and y.
12jun95 allow LOCATE to accept a vectors of LAT-LON points, improves speed
(See /home/drw/idl/old.esrg/locate.pro)
NAME LOCMAX PURPOSE To find the local maximum in a series, given a WIDTH window to look in. CALLING SEQUENCE: result = locmax(series,width) HISTORY: Written by Craig Markwardt at Wisconsin, and pulled from the COMP.LANG.IDL-PVWAVE newsgroup.
(See /home/drw/idl/aux/locmax.pro)
ROUTINE: loopind
PURPOSE: evaluate a sequence of nested indicies
USEAGE: loopind,ii,n1,i1,n2,i2,n3,i3,n4,i4,n5,i5,n6,i6
INPUT:
n1 number of elements in first dimension
n2 number of elements in second dimension
etc
keyword input:
ind one dimensional index. If this keyword is set, evaluate
i1,i2... only for the elements contained in IND
OUTPUT:
i1 index for first dimension
i2 index for second dimension
etc
EXAMPLE:
loopind,4,i1,5,i2,2,i3
f=randomn(iseed,4,5,2)
table,i1,i2,i3,f
AUTHOR: Paul Ricchiazzi 22 Sep 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/loopind.pro)
ROUTINE: loopind
PURPOSE: evaluate a sequence of nested indicies
USEAGE: loopind,ii,n1,i1,n2,i2,n3,i3,n4,i4,n5,i5,n6,i6
INPUT:
n1 number of elements in first dimension
n2 number of elements in second dimension
etc
keyword input:
ind one dimensional index. If this keyword is set, evaluate
i1,i2... only for the elements contained in IND
OUTPUT:
i1 index for first dimension
i2 index for second dimension
etc
EXAMPLE:
loopind,4,i1,5,i2,2,i3
f=randomn(iseed,4,5,2)
table,i1,i2,i3,f
AUTHOR: Paul Ricchiazzi 22 Sep 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/loopind.pro)
PROJECT: TRACE NAME: LOOPLENGTH PURPOSE: to determine the approximate length, in pixels, of a loop, based on Pythagoras' theorem. Ten points are selected along the loop, and the routine determines the intermediate distances, sums them and prints them to the X window; both pixel length and approximate real-length in kilometres are given assuming: a) that the loop is in the plane of the image b) that the angular diameter of a pixel is 0.5 arcseconds c) that 1.0 arcsec in TRACE's FOV is equivalent to 720km on the Sun. CALLING SEQUENCE: looplength,pix=pix,npoints INPUTS: PIX - the size of the pixels in arcseconds NPOINTS - the number of points in the path you want to choose EXAMPLE: looplength,pix=3.04,7 CALLS: PICK.PRO, by P.T. Gallagher to get X & Y values for each mouse click. HISTORY: PIXLOOPLENGTH.PRO originally by David Williams, 4/6/99 Modified to allow the user to set the number of points chosen (e.g. 10) and saved as LOOPLENGTH.PRO - DRW, 31/10/00
(See /home/drw/idl/bin/looplength.pro)
NAME: LOOPZOOM.PRO PURPOSE: To enlarge the P-F loop area of a 1024x1024 TRACE image CALLING SEQUENCE: loopzoom,frame INPUTS: frame - image HISTORY: D. Williams 4/6/99, similar to zoom1, which only works on images from an indexed datacube.
(See /home/drw/idl/bin/loopzoom.pro)
NAME: LOOPZOOM2.PRO PURPOSE: To enlarge the P-F loop area of a 1024x1024 TRACE image CALLING SEQUENCE: loopzoom,frame INPUTS: frame - image HISTORY: D. Williams 4/6/99, similar to zoom1, which only works on images from an indexed datacube.
(See /home/drw/idl/bin/loopzoom2.pro)
NAME: LOOPZOOM3.PRO PURPOSE: To enlarge the P-F loop area of a 512x512 TRACE image CALLING SEQUENCE: loopzoom,frame INPUTS: frame - image HISTORY: D. Williams 4/6/99, similar to zoom1, which only works on images from an indexed datacube.
(See /home/drw/idl/bin/loopzoom3.pro)
NAME: LOOP_EM DESCRIPTION: LOOP_EM USAGE: loop_em,qlds,quick=quick,upper=upper,outer=outer INPUTS: qlds - the QLDS to be used OPTIONAL INPUTS: quick - loop_emission calibrates the QLDS by default; set this switch to skip the lengthy calibration procedure upper - use the (later) upper raster 's17197r00' outer - fit line emission on a pre-determined, non-loop region for comparison with any variation in N_e found in the loop OUTPUTS: generates output files according to the options set above: loop_emission_out.sav, loop_emission_out_upper.sav, or loop_emission_out_outer.sav. PROCESSING: As stated above, in order to process the output from LOOP_EMISSION, a second routine must be run under SSW: LOOP_EMISSION_NE reads the loop_emission_out*.sav file and produces a second output file containing the line ratios and corresponding densities. See the documentation header for this routine for details.
(See /home/drw/idl/cds/loop_em.pro)
NAME: LOOP_EM2 DESCRIPTION: LOOP_EM2 USAGE: loop_em,qlds,quick=quick,upper=upper,outer=outer INPUTS: qlds - the QLDS to be used OPTIONAL INPUTS: quick - loop_emission calibrates the QLDS by default; set this switch to skip the lengthy calibration procedure upper - use the (later) upper raster 's17197r00' outer - fit line emission on a pre-determined, non-loop region for comparison with any variation in N_e found in the loop OUTPUTS: generates output files according to the options set above: loop_emission_out.sav, loop_emission_out_upper.sav, or loop_emission_out_outer.sav. PROCESSING: As stated above, in order to process the output from LOOP_EMISSION, a second routine must be run under SSW: LOOP_EMISSION_NE reads the loop_emission_out*.sav file and produces a second output file containing the line ratios and corresponding densities. See the documentation header for this routine for details.
(See /home/drw/idl/cds/loop_em2.pro)
NAME: LOOP_EMISSION DESCRIPTION: LOOP_EMISSION is based on PTG & SA's 'AZ_SA' routine for fitting specific lines from a CDS/NIS raster. AZ_SA was designed to measure the radial & azimuthal variation of density around the solar limb. LOOP_EMISSION has been modified to look at two specific rasters which were taken on 11-Aug-1999 under the title 'Eclipse Support'. They are actually part of a sequence called STRE4W, looking at streamers. The AZ_DDEP1 & 2 sequences contained planned observations under the title 'SECIS Support', but didn't turn out as planned, having only one window each, and are therefore relatively useless for determining N_e in the active region we concentrate on (AR 8651 on the NW limb). In keeping with how AZ_SA and its companion routines were written, LOOP_EMISSION relies on its output being interpreted by another routine, LOOP_EMISSION_NE, which must (at QUB) be currently run under SSW as it relies on READCOL, which fails under 'CDS'. USAGE: loop_emission,qldsu,quick=quick,upper=upper,outer=outer INPUTS: qldsu - the QLDS to be used OPTIONAL INPUTS: quick - loop_emission calibrates the QLDS by default; set this switch to skip the lengthy calibration procedure upper - use the (later) upper raster 's17197r00' outer - fit line emission on a pre-determined, non-loop region for comparison with any variation in N_e found in the loop OUTPUTS: generates output files according to the options set above: loop_emission_out.sav, loop_emission_out_upper.sav, or loop_emission_out_outer.sav. PROCESSING: As stated above, in order to process the output from LOOP_EMISSION, a second routine must be run under SSW: LOOP_EMISSION_NE reads the loop_emission_out*.sav file and produces a second output file containing the line ratios and corresponding densities. See the documentation header for this routine for details.
(See /home/drw/idl/cds/loop_emission.pro)
NAME: LOOP_EMISSION DESCRIPTION: LOOP_EMISSION is based on PTG & SA's 'AZ_SA' routine for fitting specific lines from a CDS/NIS raster. AZ_SA was designed to measure the radial & azimuthal variation of density around the solar limb. LOOP_EMISSION has been modified to look at two specific rasters which were taken on 11-Aug-1999 under the title 'Eclipse Support'. They are actually part of a sequence called STRE4W, looking at streamers. The AZ_DDEP1 & 2 sequences contained planned observations under the title 'SECIS Support', but didn't turn out as planned, having only one window each, and are therefore relatively useless for determining N_e in the active region we concentrate on (AR 8651 on the NW limb). In keeping with how AZ_SA and its companion routines were written, LOOP_EMISSION relies on its output being interpreted by another routine, LOOP_EMISSION_NE, which must (at QUB) be currently run under SSW as it relies on READCOL, which fails under 'CDS'. USAGE: loop_emission,qldsu,quick=quick,upper=upper,outer=outer INPUTS: qldsu - the QLDS to be used OPTIONAL INPUTS: quick - loop_emission calibrates the QLDS by default; set this switch to skip the lengthy calibration procedure upper - use the (later) upper raster 's17197r00' outer - fit line emission on a pre-determined, non-loop region for comparison with any variation in N_e found in the loop OUTPUTS: generates output files according to the options set above: loop_emission_out.sav, loop_emission_out_upper.sav, or loop_emission_out_outer.sav. PROCESSING: As stated above, in order to process the output from LOOP_EMISSION, a second routine must be run under SSW: LOOP_EMISSION_NE reads the loop_emission_out*.sav file and produces a second output file containing the line ratios and corresponding densities. See the documentation header for this routine for details.
(See /home/drw/idl/cds/loop_emission.bak.pro)
NAME: LOOP_EMISSION DESCRIPTION: LOOP_EMISSION is based on PTG & SA's 'AZ_SA' routine for fitting specific lines from a CDS/NIS raster. AZ_SA was designed to measure the radial & azimuthal variation of density around the solar limb. LOOP_EMISSION has been modified to look at two specific rasters which were taken on 11-Aug-1999 under the title 'Eclipse Support'. They are actually part of a sequence called STRE4W, looking at streamers. The AZ_DDEP1 & 2 sequences contained planned observations under the title 'SECIS Support', but didn't turn out as planned, having only one window each, and are therefore relatively useless for determining N_e in the active region we concentrate on (AR 8651 on the NW limb). In keeping with how AZ_SA and its companion routines were written, LOOP_EMISSION relies on its output being interpreted by another routine, LOOP_EMISSION_NE, which must (at QUB) be currently run under SSW as it relies on READCOL, which fails under 'CDS'. USAGE: loop_emission,qldsu,quick=quick,upper=upper,outer=outer INPUTS: qldsu - the QLDS to be used OPTIONAL INPUTS: quick - loop_emission calibrates the QLDS by default; set this switch to skip the lengthy calibration procedure upper - use the (later) upper raster 's17197r00' outer - fit line emission on a pre-determined, non-loop region for comparison with any variation in N_e found in the loop OUTPUTS: generates output files according to the options set above: loop_emission_out.sav, loop_emission_out_upper.sav, or loop_emission_out_outer.sav. PROCESSING: As stated above, in order to process the output from LOOP_EMISSION, a second routine must be run under SSW: LOOP_EMISSION_NE reads the loop_emission_out*.sav file and produces a second output file containing the line ratios and corresponding densities. See the documentation header for this routine for details.
(See /home/drw/idl/cds/loop_emission_multi.pro)
NAME: LOOP_EM_ARC DESCRIPTION: LOOP_EM_ARC USAGE: loop_em_arc,qlds,quick=quick,upper=upper,outer=outer INPUTS: qlds - the QLDS to be used OPTIONAL INPUTS: quick - loop_emission calibrates the QLDS by default; set this switch to skip the lengthy calibration procedure upper - use the (later) upper raster 's17197r00' outer - fit line emission on a pre-determined, non-loop region for comparison with any variation in N_e found in the loop OUTPUTS: generates output files according to the options set above: loop_emission_out.sav, loop_emission_out_upper.sav, or loop_emission_out_outer.sav. PROCESSING: As stated above, in order to process the output from LOOP_EMISSION, a second routine must be run under SSW: LOOP_EMISSION_NE reads the loop_emission_out*.sav file and produces a second output file containing the line ratios and corresponding densities. See the documentation header for this routine for details.
(See /home/drw/idl/cds/loop_em_ang.pro)
NAME: LOOP_EM_ARC DESCRIPTION: LOOP_EM_ARC USAGE: loop_em_arc,qlds,quick=quick,upper=upper,outer=outer INPUTS: qlds - the QLDS to be used OPTIONAL INPUTS: quick - loop_emission calibrates the QLDS by default; set this switch to skip the lengthy calibration procedure upper - use the (later) upper raster 's17197r00' outer - fit line emission on a pre-determined, non-loop region for comparison with any variation in N_e found in the loop OUTPUTS: generates output files according to the options set above: loop_emission_out.sav, loop_emission_out_upper.sav, or loop_emission_out_outer.sav. PROCESSING: As stated above, in order to process the output from LOOP_EMISSION, a second routine must be run under SSW: LOOP_EMISSION_NE reads the loop_emission_out*.sav file and produces a second output file containing the line ratios and corresponding densities. See the documentation header for this routine for details.
(See /home/drw/idl/cds/loop_em_arc.pro)
routine ls
useage: ls
ls,filt,array=array
input:
filt a valid unix filename specification or wild card (not required)
keyword input:
array if set files are listed as comma separated, quoted strings
appropriate for inclusing in an idl string array
purpose print files in current working directory
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/ls.pro)
routine ls
useage: ls
ls,filt
input:
filt a valid unix filename specification or wild card (not required)
purpose print files in current working directory
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/ls.pro)
ROUTINE magneto PURPOSE create magnetogram from sac peak data USEAGE magneto,cube,cube1,cube2,no INPUT cube1,cube2,number of files wanted output cube OUTPUT cube(900,930,number of files) of magnetograms tvim of contoured magnetogram EXAMPLE magneto,m94131,cube594131,cube694131,36 AUTHOR J McAteer qub (1/12/00) uses elements of magnet(P Gallagher) HISTORY Version 1 -read in fits files Version 2 -reads in reduced files from cubes possible additions -tvim zoom in facility -specify contour seperation Version 3 -uses destretch.pro(T.Berger) to detstretch image r with respect to image ; l, to remove seeing effects. Hence no need for cross_corr. Might carry ; out a running avergae, to furthur remove seeing. also removed the reverse ; rotate fundtion. Hence the output image can be compared to other sac peak data. ; But direct comparison with space based images cannot be made.
(See /home/drw/idl/secis2/magneto.pro)
NAME:
MAKE_AVERAGE_CALIB.PRO
PURPOSE:
To read in a set of SECIS 2001 flats, despike them and get the average image.
CALLS:
AVG_WO_CR, a SOHO solarsoft package routine. Should be bundled with
other SECIS routines.Be careful to average over no less
than three images, however, as AVG_WO_CR doesn't seem to
like it otherwise.
GET_UTC, to print the start and end time of the routine, as
it can take hours to run through all 500 flats/darks.
USAGE:
MAKE_AVERAGE_CALIB,AV_FLAT[,/despike,/old]
INPUTS:
AV_FLAT - the output average.
(also asks for path to directory containing the flats
as well as the type of flat, e.g. flat1narrow.)
KEYWORDS:
despike (no longer used)
- this option despikes the images, but it is deprecated,
since AVG_WO_CR flags all abnormal pixel values and ignores them.
OLD - for use with the old SECIS '99 data.
HISTORY:
Written 26/1/2000 (version 1.0)
Version 1.01 - despike option added
Version 1.02 - breaks down the averaging into
smaller, 100-image chunks to conserve memory (in progress), 27/1/2000
Version 1.1 - changed the mechanism to break up the array into
chunks of 4 (125), then 5 (25), then 5 (5) again before making
AV_FLAT the average of these five. The same array (flat_arr)
is kept all the time, with all but the first four/five images kept
in this. This will hopefully conserve memory.
Version 1.11 - included a time-printing to let the user know how
long the process takes. (3/2/2000).
Version 1.2 - Fixed a problem spotted by J. Chan (RAL) where the
averaged frame at each stage wasn't going in the right place. Also
included REFORM in all loops -- previously was just zeroing the
unused frames in the 500-frame sequences. (23/10/2001)
Version 1.3 - Added the OLD keyword to take care of SECIS 99 data
with their slightly more random file paths and the 504x504 format
(12/11/01)
AUTHOR:
David Williams, QUB.
d.williams@qub.ac.uk
(See /home/drw/idl/secis2/make_average_calib.pro)
NAME: MAKE_AVERAGE_FLAT.PRO PURPOSE: To read in a set of SECIS flats, despike them and get the average image. CALLS: AVG_WO_CR, a SOHO solarsoft package routine. Should be bundled with other SECIS routines.Be careful to average over no less than three images, however, as AVG_WO_CR doesn't seem to like it otherwise. GET_UTC, to print the start and end time of the routine, as it can take hours to run through all 500 flats/darks. USAGE: MAKE_AVERAGE_FLAT,AV_FLAT[,/despike] INPUTS: AV_FLAT - the output average. (also asks for path to directory containing the flats as well as the type of flat, e.g. flat1narrow.) KEYWORDS: despike - this option despikes the images, but it is deprecated, since AVG_WO_CR flags all abnormal pixel values and ignores them. HISTORY: Written 26/1/2000 (version 1.0) Version 1.01 - despike option added Version 1.02 - breaks down the averaging into smaller, 100-image chunks to conserve memory (in progress), 27/1/2000 Version 1.1 - changed the mechanism to break up the array into chunks of 4 (125), then 5 (25), then 5 (5) again before making AV_FLAT the average of these five. The same array (flat_arr) is kept all the time, with all but the first four/five images kept in this. This will hopefully conserve memory. Version 1.11 - included a time-printing to let the user know how long the process takes. (3/2/2000). AUTHOR: David Williams, QUB. d.williams@qub.ac.uk
(See /home/drw/idl/secis/make_average_flat.pro)
NAME: MAKE_AVERAGE_FLAT.PRO PURPOSE: To read in a set of SECIS flats, despike them and get the average image. CALLS: AVG_WO_CR, a SOHO solarsoft package routine. Should be bundled with other SECIS routines.Be careful to average over no less than three images, however, as AVG_WO_CR doesn't seem to like it otherwise. GET_UTC, to print the start and end time of the routine, as it can take hours to run through all 500 flats/darks. USAGE: MAKE_AVERAGE_FLAT,AV_FLAT[,/despike] INPUTS: AV_FLAT - the output average. (also asks for path to directory containing the flats as well as the type of flat, e.g. flat1narrow.) KEYWORDS: despike - this option despikes the images, but it is deprecated, since AVG_WO_CR flags all abnormal pixel values and ignores them. HISTORY: Written 26/1/2000 (version 1.0) Version 1.01 - despike option added Version 1.02 - breaks down the averaging into smaller, 100-image chunks to conserve memory (in progress), 27/1/2000 Version 1.1 - changed the mechanism to break up the array into chunks of 4 (125), then 5 (25), then 5 (5) again before making AV_FLAT the average of these five. The same array (flat_arr) is kept all the time, with all but the first four/five images kept in this. This will hopefully conserve memory. Version 1.11 - included a time-printing to let the user know how long the process takes. (3/2/2000). AUTHOR: David Williams, QUB. d.williams@qub.ac.uk
(See /home/drw/idl/secis/make_average_flat.bakkup.pro)
NAME: MAKE_AVERAGE_FLAT_OLD.PRO PURPOSE: To read in a set of SECIS flats, despike them and get the average image. CALLS: AVG_WO_CR, a SOHO solarsoft package routine. Should be bundled with other SECIS routines. USAGE: MAKE_AVERAGE_FLAT,AV_FLAT[,/despike] INPUTS: AV_FLAT - the output average. (also asks for path to directory containing the flats as well as the type of flat, e.g. flat1narrow. HISTORY: Written 26/1/2000 (version 1.0) version 1.01 - despike option added version 1.02 - breaks down the averaging into smaller, 100-image chunks to conserve memory (in progress), 27/1/2000
(See /home/drw/idl/secis/make_average_flat_old.pro)
ROUTINE: make_profile.pro
PURPOSE: This routine allows the user to select an intensity cut across an
image and then extract the intensity profile.
USEAGE: make_profile, image, profile, xar, yar
INPUT:
image 2D image
OUTPUT:
profile intensity cut across 2D image.
xar 2 element array containing the x vlues of the 2 selected points
yar 2 element array containing the x vlues of the 2 selected points
EXAMPLE:
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/bin/make_profile.pro)
ROUTINE: make_profile.pro
PURPOSE: This routine allows the user to select an intensity cut across an
image and then extract the intensity profile.
USEAGE: make_profile, image, profile, xar, yar
INPUT:
image 2D image
OUTPUT:
profile intensity cut across 2D image.
xar 2 element array containing the x vlues of the 2 selected points
yar 2 element array containing the x vlues of the 2 selected points
EXAMPLE:
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/bin/ptg/make_profile.pro)
ROUTINE: map_cities
PURPOSE: plot city locations and print city names form cities.dat database
USEAGE: map_cities
INPUT: none
KEYWORD INPUT:
file
city data base file, each record contains tab delimited values
of latitude, longitude and city_name.
;
charsize
character size (a multiplier of !p.charsize)
color
color used to draw city mark and name
OUTPUT: none
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
;
dcolors
map_set3,0,-94.8814,/cyl,/cont,limit=[16.75,-130.05,56.95,-59.71],$
/usa,s_color=4
map_cities,color=1
AUTHOR: Paul Ricchiazzi 25 Apr 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/map_cities.pro)
ROUTINE: map_cities
PURPOSE: plot city locations and print city names form cities.dat database
USEAGE: map_cities
INPUT: none
KEYWORD INPUT:
file
city data base file, each record contains tab delimited values
of latitude, longitude and city_name.
;
charsize
character size (a multiplier of !p.charsize)
color
color used to draw city mark and name
OUTPUT: none
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
;
dcolors
map_set3,0,-94.8814,/cyl,/cont,limit=[16.75,-130.05,56.95,-59.71],$
/usa,s_color=4
map_cities,color=1
AUTHOR: Paul Ricchiazzi 25 Apr 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/map_cities.pro)
routine: map_fill
useage: map_fill
map_fill,ccolor=ccolor,fcolor=fcolor,mapfile=mapfile
input: none required
DISCUSSION:
MAP_FILL has two main purposes. In batch mode MAP_FILL
reads the map save file, MAPFILE (defaulted to
coastline) produced by the MAP_SET3 SAVE option. It
plots continental coastlines and fill regions over an
existing map plotting region.
In interactive mode MAP_FILL is used to fixup the saved
map boundary file produced by MAP_SET3 SAVE option.
Coastline segments which do not produce nice closed
polygonal regions are manipulated with a set of line
segment editing commands. MAP_FILL first draws the map
coastline using different colors to indicate distinct
coastline segments. The map segments are adjusted
so that a given land/ocean area is properly enclosed by a
closed polygon. MAP_FILL provides 7 menu options to
allow map segment editing:
JOIN Join together several colored line segments which together
form a continuous coastline. see example 1
SPLIT Divide a closed polygonal region into two parts using
mouse to trace a path connecting one part of the coastal
segment to another point on the same segment.
DELETE Remove a line segment
FILL Preview filled regions. Temporarilly fill map polygons.
REVERT Abandon current edits, revert back to original map data
or to the last SAVEd version.
SAVE Replace contents of MAPFILE with current screen.
SAVE_AS Save current screen to a file name _n where the
root bane is MAPFILE and n is a number between 0 and 9
selected by the user. Use this command together with
SAVE and REVERT to save different regions to different
files.
KEYWORD INPUT:
mapfile name of input file (defaults to coastline).
This file may be overwritten by a "SAVE" while in
interactive mode.
ccolor color of continental outlines. if this parameter is set
map_fill operates in non-interactive mode, reading the
input MAPFILE and oploting map outlines. If FCOLOR is set
but CCOLOR is not, only region fill is produced.
fcolor color used to fill continental outlines. if this
parameter is set MAP_FILL operates in non-interactive
mode. Filling outlines are read from MAPFILE. If CCOLOR
is set but FCOLOR is not, only map outlines will be
oploted
EXAMPLE
; fill antarctic Anvers island with color
limit=[-70,-74,-62,-58] ; antarctic penninsula
map_set3,0,0,/cont,limit=limit,/cyl,/save
map_fill,fcolor=100
; notice that the antarctic penninsula is not properly filled
map_fill ; 1. click "JOIN"
; 2. gather together all segments which make up a
; a continuous stretch of coastline. The LMB blinks
; the coastline segment without capturing it. The
; MMB adds the selected segment to the last segment.
; The RMB stops the gathering process.
; 3. click "SAVE" to save your edits
; 4. click "DONE" to quit
;
; now view the finished map:
map_set3,0,0,limit=limit,/cyl
map_fill,ccolor=190,fcolor=100
; fill in south coast map
limit=[33,-120,35,-118] ; channel islands
map_set3,0,0,limit=limit,/cyl,/save,/cont
map_fill,fcolor=100
; notice that land areas are not POLYFILLed correctly
map_fill ; 1. click "CIRCUIT"
; 2. use mouse to trace a closed path connecting NW and
; SE ends. Close the circuit outside (up and around)
; the rectangular viewing area. (Each LMB click adds
; a segment to the path).
; 3. click "SAVE"
; 4. click "DONE"
;
; after you're done try map_fill again, try the fixed up coastline
; file with a different map projection:
; here is an example with the channel islands
limit=[31,-122,36,-115] ; channel islands
map_set3,0,-120,limit=limit,/orth,/save,/cont
map_fill
map_set3,0,-120,limit=limit,/orth,/cont
map_fill,cc=200,fc=100,file='coastline_0'
map_fill,cc=200,fc=0,file='coastline_1'
map_set3,0,0,/cont,/save
map_fill
; you can make arbitririly shaped masking regions with
; the following commands
plot,[0,10],[0,10],/nodata
openw,lu,/get_lun,'coastline',/xdr,/stream
writeu,lu,!y.crange([0,1]),!x.crange([0,1])
trace,xv,yv & writeu,lu,n_elements(xv) & writeu,lu,transpose([[xv],[yv]])
free_lun,lu
LIMITATIONS:
MAP_FILL will not fill map regions which contain the north
or south pole.
MAP_FILL may not work on X-terminals. It uses the IDL routine
POLYFILL, which in turn calls an Xwindow system procedure for
filling polygons. Though the Xwindow fill routine is
accessible to any xterminal, the procedure may demand more
local memory than your terminal has. Unfortunately, running
out of video memory also crashes your IDL session. The
solution is to run your application on a workstation.
AUTHOR: Paul Ricchiazzi 01 Mar 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
(See /home/drw/idl/esrg/map_fill.pro)
ROUTINE: map_lambert
PURPOSE: transformation into lambert azimuthal map projection
USEAGE: map_lambert,lat0,lon0,lat,lon,u,v
INPUT:
lat0 latitude of tangent point
lon0 longitude of tangent point
lat array of latitudes
lon array of longitues
OUTPUT:
u horizontal projection coordinates (km)
v vertical projection coordinates (km)
EXAMPLE:
lat=[ 23.5837576, 22.4793919, 46.7048989, 48.4030555]
lon=[ -119.9722899, -75.4163527, -65.3946489, -128.5300591]
map_lambert,45,-100,lat,lon,u,v
print,u,v
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/map_lambert.pro)
ROUTINE: map_lambert
PURPOSE: transformation into lambert azimuthal map projection
USEAGE: map_lambert,lat0,lon0,lat,lon,u,v
INPUT:
lat0 latitude of tangent point
lon0 longitude of tangent point
lat array of latitudes
lon array of longitues
OUTPUT:
u horizontal projection coordinates (km)
v vertical projection coordinates (km)
EXAMPLE:
lat=[ 23.5837576, 22.4793919, 46.7048989, 48.4030555]
lon=[ -119.9722899, -75.4163527, -65.3946489, -128.5300591]
map_lambert,45,-100,lat,lon,u,v
print,u,v
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/map_lambert.pro)
ROUTINE: map_limit
PURPOSE: set map_limit
USEAGE: map_limit
INPUT:
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
limit=map_limit()
loadct,5
map_set3,/cont,/pol,/riv,/us,/grid,r_color=50,p_color=150,$
c_color=200,limit=limit,lores=0
AUTHOR: Paul Ricchiazzi 02 Feb 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/map_limit.pro)
NAME:
MATCHDELIM
PURPOSE:
Match open/close delimiters in a string.
CATEGORY:
text/strings
CALLING SEQUENCE:
position = matchdelim( strn, [openpos])
INPUTS:
strn -- a string containing an open in
delimiter (e.g. '{') in which you
want to find the matching closing
delimiter (e.g. '}')
KEYWORD PARAMETERS:
OPEN_DELIM -- A single character containing the opening in
delimiter (e.g. '('). Default is '{'
CLOSE_DELIM -- A single character containing the closing in
delimiter (e.g. ')'). Default is '}'
OUTPUTS:
position -- returns the position in strn of the out
closing delimiter, -1 if no closing found.
openpos -- Set to a named variable to receive the out
position of the first opening delimiter.
Optional.
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
- Any pair of (nonidentical) characters can be used as
delimiters.
EXAMPLE:
matchdelim('{one{two}}three') returns 9, the character just
before 'three'.
MODIFICATION HISTORY:
$Id: matchdelim.pro,v 1.3 1996/06/14 20:00:27 mcraig Exp $
$Log: matchdelim.pro,v $
Revision 1.3 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.2 1996/05/09 00:22:17 mcraig
Removed restriction that open delim must be first char. Added argument
to allow for return of position of open delim.
Revision 1.1 1996/01/31 18:41:06 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/matchdelim.pro)
NAME:
MCHOLDC
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Modified Cholesky Factorization of a Symmetric Matrix
MAJOR TOPICS:
Linear Systems
CALLING SEQUENCE:
MCHOLDC, A, D, E [, /OUTFULL, /SPARSE, /PIVOT, TAU=TAU, $
PERMUTE=PERMUTE, INVPERMUTE=INVPERMUTE ]
DESCRIPTION:
Given a symmetric matrix A, the MCHOLDC procedure computes the
factorization:
A + E = TRANSPOSE(U) ## D ## U
where A is the original matrix (optionally permuted if the PIVOT
keyword is set), U is an upper triangular matrix, D is a diagonal
matrix, and E is a diagonal error matrix.
The standard Cholesky factorization is only defined for a positive
definite symmetric matrix. If the input matrix is positive
definite then the error term E will be zero upon output. The user
may in fact test the positive-definiteness of their matrix by
factoring it and testing that all terms in E are zero.
If A is *not* positive definite, then the standard Cholesky
factorization is undefined. In that case we adopt the "modified"
factorization strategy of Gill, Murray and Wright (p. 108), which
involves adding a diagonal error term to A in order to enforce
positive-definiteness. The approach is optimal in the sense that
it attempts to minimize E, and thus disturbing A as little as
possible. For optimization problems, this approximate
factorization can be used to find a direction of descent even when
the curvature is not positive definite.
The upper triangle of A is modified in place. By default, the
lower triangle is left unchanged, and the matrices D and E are
actually returned as vectors containing only the diagonal terms.
However, if the keyword OUTFULL is set then full matrices are
returned. This is useful when matrix multiplication will be
performed at the next step.
The modified Cholesky factorization is most stable when pivoting is
performed. If the keyword PIVOT is set, then pivoting is performed
to place the diagonal terms with the largest amplitude in the next
row. The permutation vectors returned in PERMUTE and INVPERMUTE
can be used to apply and reverse the pivoting.
[ i.e., (U(PP,*))(*,PP) applies the permutation and
(U(IPP,*))(*,IPP) reverses it, where PP and IPP are the
permutation and inverse permutation vectors. ]
If the matrix to be factored is very sparse, then setting the
SPARSE keyword may improve the speed of the computations. SPARSE
is more costly on a dense matrix, but only grows as N^2, where as
the standard computation grows as N^3, where N is the rank of the
matrix.
If the CHOLSOL keyword is set, then the output is slightly
modified. The returned matrix A that is returned is structured so
that it is compatible with the CHOLSOL built-in IDL routine. This
involves converting A to being upper to lower triangular, and
multiplying by SQRT(D). Users must be sure to check that all
elements of E are zero before using CHOLSOL.
PARAMETERS:
A - upon input, a symmetric NxN matrix to be factored.
Upon output, the upper triangle of the matrix is modified to
contain the factorization.
D - upon output, the diagonal matrix D.
E - upon output, the diagonal error matrix E.
KEYWORD PARAMETERS:
OUTFULL - if set, then A, D and E will be modified to be full IDL
matrices than can be matrix-multiplied. By default,
only the upper triangle of A is modified, and D and E
are returned as vectors.
PIVOT - if set, then diagonal elements of A are pivoted into place
and operated on, in decrease order of their amplitude.
The permutation vectors are returned in the PERMUTE and
INVPERMUTE keywords.
PERMUTE - upon return, the permutation vector which converts a
vector into permuted form.
INVPERMUTE - upon return, the inverse permutation vector which
converts a vector from permuted form back into
standard form.
SPARSE - if set, then operations optimized for sparse matrices are
employed. For large but very sparse matrices, this can
save a significant amount of computation time.
CHOLSOL - if set, then A and D are returned, suitable for input to
the built-in IDL routine CHOLSOL. CHOLSOL is mutually
exclusive with the FULL keyword.
TAU - if set, then use the Tau factor as described in the
"unconventional" modified Cholesky factorization, as
described by Xie & Schlick.
Default: the unconventional technique is not used.
EXAMPLE:
Example 1
---------
a = randomn(seed, 5,5) ;; Generate a random matrix
a = 0.5*(transpose(a)+a) ;; Symmetrize it
a1 = a ;; Make a copy
mcholdc, a1, d, e, /full ;; Factorize it
print, max(abs(e)) ;; This matrix is not positive definite
diff = transpose(a1) ## d ## a1 - e - a
;; Test the factorization by inverting
;; it and subtracting A
print, max(abs(diff)) ;; Differences are small
Example 2
---------
Solving a problem with MCHOLDC and CHOLSOL
a = [[6E,15,55],[15E,55,225],[55E,225,979]]
b = [9.5E,50,237]
mcholdc, a, d, e, /cholsol ;; Factorize matrix, compatible w/ CHOLSOL
if total(abs(e)) NE 0 then $
message, 'ERROR: Matrix A is not positive definite'
x = cholsol(a, d, b) ;; Solve with CHOLSOL
print, x
-0.500001 -0.999999 0.500000
which is within 1e-6 of the true solution.
REFERENCES:
Gill, P. E., Murray, W., & Wright, M. H. 1981
*Practical Optimization*, Academic Press
Schlick, T. & Fogelson, A., "TNPACK - A Truncated Newton
Minimization Package for Large- Scale Problems: I. Algorithm and
Usage," 1992, ACM TOMS, v. 18, p. 46-70. (Alg. 702)
Xie, D. & Schlick, T., "Remark on Algorithm 702 - The Updated
Truncated Newton Minimization Package," 1999, ACM TOMS, v. 25,
p. 108-122.
MODIFICATION HISTORY:
Written, CM, Apr 2001
Added CHOLSOL keyword, CM, 15 Feb 2002
$Id: mcholdc.pro,v 1.5 2002/02/25 19:33:44 craigm Exp $
(See /home/drw/idl/aux/markwardt/mcholdc.pro)
ROUTINE: mean
AUTHOR: Terry Figel, ESRG, UCSB 2-21-93
CALLING SEQUENCE: mean,var
INPUT:
var an array
PURPOSE: return the mean of var
(See /home/drw/idl/esrg/mean.pro)
ROUTINE: mean
AUTHOR: Terry Figel, ESRG, UCSB 2-21-93
CALLING SEQUENCE: mean,var
INPUT:
var an array
PURPOSE: return the mean of var
(See /home/drw/idl/old.esrg/mean.pro)
NAME: MEMTIME PURPOSE: This procedure displays the system time and memory usage' CATEGORY: General. CALLING SEQUENCE: MEMTIME, Label INPUTS: Value: A numeric label which is displayed when the program is excecuted EXAMPLE: memtime,4 MODIFICATION HISTORY: Written by David Sahnow, 20 November 1996.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/memtime.pro)
ROUTINE: menuws
PURPOSE: create a multiple value menu widget and return a selections
USEAGE: w=menuws(choices,title=title,group=group,$
font=font,ysize=ysize)
INPUT:
choices string array containing choices
KEYWORD INPUT:
title title of the widget
prompt string array of prompt message. each element of string
array appears on a new line.
ysize the number of lines to show in the list widget. If the
number of choices is greater than ysize the list widget
creates a vertical slider to allow the user to scan all
selections.
font String specifying font type. If omitted use the default
fixed width font:
"-misc-fixed-bold-r-normal--13-120-75-75-c-80-iso8859-1"
OUTPUT
result the indecies of the selected items. (-1 if no selections)
EXAMPLES:
; use MENUWS to make a sequence of menu selections
f=findfile('/home/paul/idl/esrg/[r-z]*.pro')
table,f(menuws(f))
DISCUSSION:
MENUWS calls MENUW to do the widget setup and selection of
individual items. MENUWS keeps track of which items have been
selected and updates the item labels to graphically indicate
active selections. When the operator makes a selection by
clicking with the LMB, the entire selection list is rewritten to
the menu widget. Selected items are indicated with an
asterisk (*) prefix. Selected items may be de-selected by
clicking on them again with the LMB. The list of selected
items is not locked in until the operator hits the DONE button.
BUGS:
Because MENUWS uses WIDGET_CONTROL to update the item list
there is a problem which only occurs when the the list is long
and you are selecting something near the bottom of the
scrolled list. In this case, when WIDGET_CONTROL re-writes
the item list the widget display jumps up to the top of the
list. This is disturbing but not disasterous: the selection
is recorded even though you have to scroll back down to see
it. The only fix I know is to make sure YSIZE is greater than
or equal to the number of menu items. Right now YSIZE is
defaulted to the min of the number of menu items and 60, which
is as many items as will fit on my screen when using the
default font.
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/esrg/menuws.pro)
ROUTINE: menuws
PURPOSE: create a multiple value menu widget and return a selections
USEAGE: w=menuws(choices,title=title,group=group,$
font=font,ysize=ysize)
INPUT:
choices string array containing choices
KEYWORD INPUT:
title title of the widget
prompt string array of prompt message. each element of string
array appears on a new line.
ysize the number of lines to show in the list widget. If the
number of choices is greater than ysize the list widget
creates a vertical slider to allow the user to scan all
selections.
font String specifying font type. If omitted use the default
fixed width font:
"-misc-fixed-bold-r-normal--13-120-75-75-c-80-iso8859-1"
OUTPUT
result the indecies of the selected items. (-1 if no selections)
EXAMPLES:
; use MENUWS to make a sequence of menu selections
f=findfile('/home/paul/idl/esrg/[r-z]*.pro')
table,f(menuws(f))
DISCUSSION:
MENUWS calls MENUW to do the widget setup and selection of
individual items. MENUWS keeps track of which items have been
selected and updates the item labels to graphically indicate
active selections. When the operator makes a selection by
clicking with the LMB, the entire selection list is rewritten to
the menu widget. Selected items are indicated with an
asterisk (*) prefix. Selected items may be de-selected by
clicking on them again with the LMB. The list of selected
items is not locked in until the operator hits the DONE button.
BUGS:
Because MENUWS uses WIDGET_CONTROL to update the item list
there is a problem which only occurs when the the list is long
and you are selecting something near the bottom of the
scrolled list. In this case, when WIDGET_CONTROL re-writes
the item list the widget display jumps up to the top of the
list. This is disturbing but not disasterous: the selection
is recorded even though you have to scroll back down to see
it. The only fix I know is to make sure YSIZE is greater than
or equal to the number of menu items. Right now YSIZE is
defaulted to the min of the number of menu items and 60, which
is as many items as will fit on my screen when using the
default font.
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/old.esrg/menuws.pro)
ROUTINE: menuw
PURPOSE: create a menu widget and return a selection
USEAGE: w=menuw(choices,title=title,group=group,$
font=font,ysize=ysize,done=done)
result=menuw(w)
while menus(w,ii) do (something that depends on ii)
PROCEDURE:
The value returned from MENUW is either a widget id or a
selection index, depending on the variable type of its
first argument. If the argument is a string array then
MENUW sets up a menu, based on an IDL list widget, and
returns a structure of widget identifiers of the
component widgets. If the argument is a structure then
MENUW returns the index of the selected menu choice.
Set up the widget with w=MENUW(choices)
Return choices with result=MENUW(w)
where
choices = a string array of menu choices
w = a structure variable containing the widget id.
result = index of the selected menu choice
INPUT:
choices string array containing choices
w widget id (returned by setup call to MENUW)
KEYWORD INPUT:
title title of the widget
prompt string array of prompt message. each element of string
array appears on a new line.
ysize the number of lines to show in the list widget. If the
number of choices is greater than ysize the list widget
creates a vertical slider to allow the user to scan all
selections.
font String specifying font type. If omitted use the default
fixed width font:
"-misc-fixed-bold-r-normal--13-120-75-75-c-80-iso8859-1"
done if set, a "DONE" button is created. If a DONE button
is not present the MENUW widget is destroyed the first
time result=MENUW(w) is executed.
cancel if set, a "CANCEL" button is created. Returns -1 when
pressed.
OUTPUT, SETUP MODE:
w widget indentifier used in subsequent calls to MENUW
When multiple copies of the MENUW widget exist, a call to
to MENUW(w) will interact only with the widget which
set W.
OUTPUT, SELECTION MODE:
selection If selection parameter is included in parameter list it
will contain the index of the selection and the function
return value will be set to -1 or 1 depending on whether
the DONE button was/was_not pressed. When used in a
while loop (see examples), the last selected value is
available even after DONE is pressed. If the SELECTION
parameter is not in the argument list the function
return value will be set to....
result if the DONE/CANCEL button is pressed => -1
otherwise the index of the list widget
(0 -- n_elements(choices)-1)
EXAMPLES:
; use MENUW in one-shot mode
items=findfile('/home/paul/idl/esrg/t*.pro')
prompt='choose a file to display'
print,items(menuw(menuw(items,prompt=prompt)))
; use MENUW to make a sequence of menu selections
items=findfile('/home/paul/idl/esrg/t*.pro')
prompt='choose a file to display'
w2=menuw(items,prompt=prompt,/done)
k=menuw(w2)
while k ne -1 do begin & print,items(k) & k=menuw(w2) & end
while menuw(w2,k) do print,items(k)
print,items(k)
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/esrg/menuw.pro)
ROUTINE: menuw
PURPOSE: create a menu widget and return a selection
USEAGE: w=menuw(choices,title=title,group=group,$
font=font,ysize=ysize,done=done)
result=menuw(w)
while menus(w,ii) do (something that depends on ii)
PROCEDURE:
The value returned from MENUW is either a widget id or a
selection index, depending on the variable type of its
first argument. If the argument is a string array then
MENUW sets up a menu, based on an IDL list widget, and
returns a structure of widget identifiers of the
component widgets. If the argument is a structure then
MENUW returns the index of the selected menu choice.
Set up the widget with w=MENUW(choices)
Return choices with result=MENUW(w)
where
choices = a string array of menu choices
w = a structure variable containing the widget id.
result = index of the selected menu choice
INPUT:
choices string array containing choices
w widget id (returned by setup call to MENUW)
KEYWORD INPUT:
title title of the widget
prompt string array of prompt message. each element of string
array appears on a new line.
ysize the number of lines to show in the list widget. If the
number of choices is greater than ysize the list widget
creates a vertical slider to allow the user to scan all
selections.
font String specifying font type. If omitted use the default
fixed width font:
"-misc-fixed-bold-r-normal--13-120-75-75-c-80-iso8859-1"
done if set, a "DONE" button is created. If a "DONE" button
is not present the MENUW widget is destroyed the first
time result=MENUW(w) is executed.
OUTPUT, SETUP MODE:
w widget indentifier used in subsequent calls to MENUW
When multiple copies of the MENUW widget exist, a call to
to MENUW(w) will interact only with the widget which
set W.
OUTPUT, SELECTION MODE:
selection If selection parameter is included in parameter list it
will contain the index of the selection and the function
return value will be set to -1 or 1 depending on whether
the DONE button was/was_not pressed. When used in a
while loop (see examples), the last selected value is
available even after DONE is pressed. If the SELECTION
parameter is not in the argument list the function
return value will be set to....
result if the DONE button is pressed => -1
otherwise the index of the list widget
(0 -- n_elements(choices)-1)
EXAMPLES:
; use MENUW in one-shot mode
items=findfile('/local/idl/user_contrib/esrg/t*.pro')
prompt='choose a file to display'
print,items(menuw(menuw(items,prompt=prompt)))
; use MENUW to make a sequence of menu selections
items=findfile('/local/idl/user_contrib/esrg/t*.pro')
prompt='choose a file to display'
w2=menuw(items,prompt=prompt,/done)
k=menuw(w2)
while k ne -1 do begin & print,items(k) & k=menuw(w2) & end
while menuw(w2,k) do print,items(k)
print,items(k)
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/old.esrg/menuw.pro)
ROUTINE: mindex
PURPOSE: given a one dimensional index, ii, and a vector, nn, giving the
size of each dimension in an array, output the array indices matching
the values of ii. See example.
USEAGE: mindex,ii,nn,i1,i2,i3,i4,i5
INPUT:
ii one dimensional index
nn vector array of array dimensions, array with up to 6 dimensions are allowed
KEYWORD INPUT:
OUTPUT:
i1,i2.. array indices
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 10 Feb 99
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/mindex.pro)
NAME:
MIN_CURVE_SURF
PURPOSE:
Interpolate a regular or irregularly gridded set of points
with a minimum curvature spline surface.
CATEGORY:
Interpolation, Surface Fitting
CALLING SEQUENCE:
Result = min_curve_surf(z [, x, y])
INPUTS:
X, Y, Z = arrays containing the x, y, and z locations of the
data points on the surface. Need not necessarily be
regularly gridded. For regularly gridded input data,
X and Y are not used, the grid spacing is specified
via the XGRID or XVALUES, and YGRID or YVALUES,
keywords, and Z must be a two dimensional array.
For irregular grids, all three parameters must be present
and have the same number of elements.
KEYWORD PARAMETERS:
Input grid description:
REGULAR = if set, the Z parameter is a two dimensional array,
of dimensions (N,M), containing measurements over a
regular grid. If any of XGRID, YGRID, XVALUES, YVALUES
are specified, REGULAR is implied. REGULAR is also
implied if there is only one parameter, Z. If REGULAR is
set, and no grid (_VALUE or _GRID) specifications are present,
the respective grid is set to (0, 1, 2, ...).
XGRID = contains a two element array, [xstart, xspacing],
defining the input grid in the X direction. Do not specify
both XGRID and XVALUES.
XVALUES = if present, Xvalues(i) contains the X location
of Z(i,j). Xvalues must be dimensioned with N elements.
YGRID, YVALUES = same meaning as XGRID, XVALUES except for the
Y locations of the input points.
Output grid description:
GS = spacing of output grid.
If present, GS a two-element vector
[XS, YS], where XS is the horizontal spacing between
grid points and YS is the vertical spacing. The
default is based on the extents of X and Y. If the
grid starts at X value Xmin and ends at Xmax, then the
default horizontal spacing is (Xmax - Xmin)/(NX-1).
YS is computed in the same way. The default grid
size, if neither NX or NY are specified, is 26 by 26.
BOUNDS = a four element array containing the grid limits in X and
Y of the output grid: [ Xmin, Ymin, Xmax, Ymax].
If not specified, the grid limits are set to the extend
of X and Y.
NX = Output grid size in the X direction. Default = 26, need
not be specified if the size can be inferred by
GS and BOUNDS.
NY = Output grid size in the Y direction. See NX.
XOUT = a vector containing the output grid X values. If this
parameter is supplied, GS, BOUNDS, and NX are ignored
for the X output grid. Use this parameter to specify
irregular spaced output grids.
YOUT = a vector containing the output grid in the Y direction.
If this parameter is supplied, GS, BOUNDS, and NY are
ignored for the Y output grid.
XPOUT, YPOUT = arrays containing X and Y values for the output
points. With these keywords, the output grid need not
be regular, and all other output grid parameters are
ignored. XPOUT and YPOUT must have the same number of
points, which is also the number of points returned in
the result.
OUTPUTS:
A two dimensional floating point array containing the interpolated
surface, sampled at the grid points.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Limited by the single precision floating point accuracy of the
machine.
SAMPLE EXECUTION TIMES (measured on a Sun IPX)
# of input points # of output points Seconds
16 676 0.19
32 676 0.42
64 676 1.27
128 676 4.84
256 676 24.6
64 256 1.12
64 1024 1.50
64 4096 1.97
64 16384 3.32
PROCEDURE:
A minimum curvature spline surface is fitted to the data points
described by X,Y, and Z. The basis function:
C(x0,x1, y0,y1) = d^2 log(d),
where d is the distance between (x0,y0), (x1,y1), is used,
as described by Franke, R., Smooth interpolation of scattered
data by local thin plate splines: Computers Math With Applic.,
v.8, no. 4, p. 273-281, 1982. For N data points, a system of N+3
simultaneous equations are solved for the coefficients of the
surface. For any interpolation point, the interpolated value
is:
F(x,y) = b(0) + b(1)*x + b(2)*y + Sum(a(i)*C(X(i),x,Y(i),y))
EXAMPLE: IRREGULARLY GRIDDED CASES
Make a random set of points that lie on a gaussian:
n = 15 ;# random points
x = RANDOMU(seed, n)
y = RANDOMU(seed, n)
z = exp(-2 * ((x-.5)^2 + (y-.5)^2)) ;The gaussian
get a 26 by 26 grid over the rectangle bounding x and y:
r = min_curve_surf(z, x, y) ;Get the surface.
Or: get a surface over the unit square, with spacing of 0.05:
r = min_curve_surf(z, x, y, GS=[0.05, 0.05], BOUNDS=[0,0,1,1])
Or: get a 10 by 10 surface over the rectangle bounding x and y:
r = min_curve_surf(z, x, y, NX=10, NY=10)
REGULARLY GRIDDED CASES
z = randomu(seed, 5, 6) ;Make some random data
interpolate to a 26 x 26 grid:
CONTOUR, min_curve_surf(z, /REGULAR)
MODIFICATION HISTORY:
DMS, RSI, March, 1993. Written.
DMS, RSI, July, 1993. Added XOUT and YOUT.
(See /home/drw/idl/esrg/min_curve_surf.pro)
NAME:
MIN_CURVE_SURF
PURPOSE:
Interpolate a regular or irregularly gridded set of points
with a minimum curvature spline surface.
CATEGORY:
Interpolation, Surface Fitting
CALLING SEQUENCE:
Result = min_curve_surf(z [, x, y])
INPUTS:
X, Y, Z = arrays containing the x, y, and z locations of the
data points on the surface. Need not necessarily be
regularly gridded. For regularly gridded input data,
X and Y are not used, the grid spacing is specified
via the XGRID or XVALUES, and YGRID or YVALUES,
keywords, and Z must be a two dimensional array.
For irregular grids, all three parameters must be present
and have the same number of elements.
KEYWORD PARAMETERS:
Input grid description:
REGULAR = if set, the Z parameter is a two dimensional array,
of dimensions (N,M), containing measurements over a
regular grid. If any of XGRID, YGRID, XVALUES, YVALUES
are specified, REGULAR is implied. REGULAR is also
implied if there is only one parameter, Z. If REGULAR is
set, and no grid (_VALUE or _GRID) specifications are present,
the respective grid is set to (0, 1, 2, ...).
XGRID = contains a two element array, [xstart, xspacing],
defining the input grid in the X direction. Do not specify
both XGRID and XVALUES.
XVALUES = if present, Xvalues(i) contains the X location
of Z(i,j). Xvalues must be dimensioned with N elements.
YGRID, YVALUES = same meaning as XGRID, XVALUES except for the
Y locations of the input points.
Output grid description:
GS = spacing of output grid.
If present, GS a two-element vector
[XS, YS], where XS is the horizontal spacing between
grid points and YS is the vertical spacing. The
default is based on the extents of X and Y. If the
grid starts at X value Xmin and ends at Xmax, then the
default horizontal spacing is (Xmax - Xmin)/(NX-1).
YS is computed in the same way. The default grid
size, if neither NX or NY are specified, is 26 by 26.
BOUNDS = a four element array containing the grid limits in X and
Y of the output grid: [ Xmin, Ymin, Xmax, Ymax].
If not specified, the grid limits are set to the extend
of X and Y.
NX = Output grid size in the X direction. Default = 26, need
not be specified if the size can be inferred by
GS and BOUNDS.
NY = Output grid size in the Y direction. See NX.
XOUT = a vector containing the output grid X values. If this
parameter is supplied, GS, BOUNDS, and NX are ignored
for the X output grid. Use this parameter to specify
irregular spaced output grids.
YOUT = a vector containing the output grid in the Y direction.
If this parameter is supplied, GS, BOUNDS, and NY are
ignored for the Y output grid.
XPOUT, YPOUT = arrays containing X and Y values for the output
points. With these keywords, the output grid need not
be regular, and all other output grid parameters are
ignored. XPOUT and YPOUT must have the same number of
points, which is also the number of points returned in
the result.
OUTPUTS:
A two dimensional floating point array containing the interpolated
surface, sampled at the grid points.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Limited by the single precision floating point accuracy of the
machine.
SAMPLE EXECUTION TIMES (measured on a Sun IPX)
# of input points # of output points Seconds
16 676 0.19
32 676 0.42
64 676 1.27
128 676 4.84
256 676 24.6
64 256 1.12
64 1024 1.50
64 4096 1.97
64 16384 3.32
PROCEDURE:
A minimum curvature spline surface is fitted to the data points
described by X,Y, and Z. The basis function:
C(x0,x1, y0,y1) = d^2 log(d),
where d is the distance between (x0,y0), (x1,y1), is used,
as described by Franke, R., Smooth interpolation of scattered
data by local thin plate splines: Computers Math With Applic.,
v.8, no. 4, p. 273-281, 1982. For N data points, a system of N+3
simultaneous equations are solved for the coefficients of the
surface. For any interpolation point, the interpolated value
is:
F(x,y) = b(0) + b(1)*x + b(2)*y + Sum(a(i)*C(X(i),x,Y(i),y))
EXAMPLE: IRREGULARLY GRIDDED CASES
Make a random set of points that lie on a gaussian:
n = 15 ;# random points
x = RANDOMU(seed, n)
y = RANDOMU(seed, n)
z = exp(-2 * ((x-.5)^2 + (y-.5)^2)) ;The gaussian
get a 26 by 26 grid over the rectangle bounding x and y:
r = min_curve_surf(z, x, y) ;Get the surface.
Or: get a surface over the unit square, with spacing of 0.05:
r = min_curve_surf(z, x, y, GS=[0.05, 0.05], BOUNDS=[0,0,1,1])
Or: get a 10 by 10 surface over the rectangle bounding x and y:
r = min_curve_surf(z, x, y, NX=10, NY=10)
REGULARLY GRIDDED CASES
z = randomu(seed, 5, 6) ;Make some random data
interpolate to a 26 x 26 grid:
CONTOUR, min_curve_surf(z, /REGULAR)
MODIFICATION HISTORY:
DMS, RSI, March, 1993. Written.
DMS, RSI, July, 1993. Added XOUT and YOUT.
(See /home/drw/idl/old.esrg/min_curve_surf.pro)
NAME: MJD2DATE PURPOSE: This function converts from Modified Julian Date to a date string. CATEGORY: Time. CALLING SEQUENCE: Result = MJD2DATE(MJD) INPUTS: MJD: Modified Julian Date. This should be a double. If it isn't, a warning is printed and truncation may occur. KEYWORD PARAMETERS: FORMAT: Determines format of output: 1 (default): Wednesday 2000 May 17 02:35:22 2: 2000-05-17 02:35:22 OUTPUTS: This function returns a standard time string. PROCEDURE: Straightforward. Uses APL routines. EXAMPLE: MODIFICATION HISTORY: Written by David Sahnow, 6 December 1999. 16 May 2000 Added 0.5 to the value of JD1 in order to round to the nearest second rather than the previous second. 29 September 2000 Added warning if the input is not a double.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/mjd2date.pro)
NAME: MKAVFLAT.pro PURPOSE: To read in a certain range of (7-frame) VTT FITS files, and create an average flat from them. USAGE: mkavflat, prepend, start, end, flatout INPUTS: PREPEND - generic start name of FITS files, e.g. 'caii' for a set of FITS called 'caii0.fits', 'caii1.fits', etc. It can include a path to the files, as shown in the second example below. FSTART - number of initial FITS file to be read, e.g. 0 FEND - number of last FITS file to be read, e.g. 14 OUTPUTS: FLATOUT - the averaged flat output KEYWORDS: UBF - if set, then MKAVFLAT requests a number corresponding to the index of the frame to be extracted, e.g., 0 refers to H-alpha, 3 to Mg b2 core... EXAMPLES: mkavflat, '410caii', 0, 14, avflat, /ubf mkavflat, '/scratch/user/caii/caii', 0, 12, avflat HISTORY: Version 1.0 - D.Williams, QUB 10/10/00
(See /home/drw/idl/vtt/mkavflat.pro)
NAME: MKSECIS2AVFLAT PURPOSE: To read in a certain range of (7-frame) VTT FITS files, and create an average flat from them. USAGE: mksecis2avflat, prepend, start, end, flatout INPUTS: PREPEND - generic start name of FITS files, e.g. 'caii' for a set of FITS called 'caii0.fits', 'caii1.fits', etc. It can include a path to the files, as shown in the second example below. FSTART - number of initial FITS file to be read, e.g. 0 FEND - number of last FITS file to be read, e.g. 14 OUTPUTS: FLATOUT - the averaged flat output KEYWORDS: UBF - if set, then MKAVFLAT requests a number corresponding to the index of the frame to be extracted, e.g., 0 refers to H-alpha, 3 to Mg b2 core... EXAMPLES: mkavflat, '410caii', 0, 14, avflat, /ubf mkavflat, '/scratch/user/caii/caii', 0, 12, avflat HISTORY: Based on the old MKAVFLAT for the VTT data (D.Williams, QUB 10/10/00) Rewritten to make it more useful for the SECIS 2001 (and 99) data
(See /home/drw/idl/secis/mksecis2avflat.pro)
name:
modct
purpose:
modify the image display color tables so the full range
runs from one color index to another.
category:
image processing, point operations.
calling sequence:
modct, ct, low=low, high=high, gamma=gamma, ct=ct,bar=bar
input:
ct color table index. if not supplied current color table
is modified.
keyword inputs:
low: starting point of color range interpolation
as a fraction of the current color table.
use keyword clrbar to see current table.
default=0
high: ending point of color range interpolation as
a fraction of current color table.
default=1. if high
(See /home/drw/idl/esrg/modct.pro)
MODCT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
name:
modct
purpose:
modify the image display color tables so the full range
runs from one color index to another.
category:
image processing, point operations.
calling sequence:
modct, ct, low=low, high=high, gamma=gamma, ct=ct,bar=bar
input:
ct color table index. if not supplied current color table
is modified.
keyword inputs:
low: starting point of color range interpolation
as a fraction of the current color table.
use keyword clrbar to see current table.
default=0
high: ending point of color range interpolation as
a fraction of current color table.
default=1. if high
(See /home/drw/idl/old.esrg/modct.pro)
MODE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MODE
PURPOSE:
Return the mode of an array.
CALLING SEQUENCE:
mod = mode(x)
INPUTS:
array the array of interest
OPTIONAL INPUTS:
binsz if set, the size of the histogram bins. Default = 1
OUTPUTS:
The value of the array where the maximum number of elements of
array are located given the bin size.
PROCEDURE
Uses histogram, stolen code from histo.pro
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke 11/21/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/mode.pro)
MODE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MODE
PURPOSE:
Return the mode of an array.
CALLING SEQUENCE:
mod = mode(x)
INPUTS:
array the array of interest
OPTIONAL INPUTS:
binsz if set, the size of the histogram bins. Default = 1
OUTPUTS:
The value of the array where the maximum number of elements of
array are located given the bin size.
PROCEDURE
Uses histogram, stolen code from histo.pro
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke 11/21/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/mode.pro)
MODTRNS[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: modtrns
PURPOSE: extract transmission from modtran tape8, display transmission
plots
USEAGE: modtrns,buf,archive=archive,file=file,xrange=xrange,$
title=title,sort=sort
KEYWORD INPUT:
file input file name (defaults to "tape8")
archive archive data set name, if this keyword is present and both
FILE and BUF are not set, input is read from specified
modtran data set which has been previously benn saved
in machine independent XDL format. IF either BUF or
FILE are set, the data in FILE or BUF are written to
ARCHIVE.
title string which specifies title of transmission plot
xrange wavelength range (defaults to wavelength range of modtran run)
sort if set, plot four most opaque species in order of
increasing band opacity. Otherwise order is
(total,h2o,co2,o3,o2, ch4+n2o+co+no2+so2+nh3+no)
verbose if set, print that code is reading data
INPUT/OUTPUT:
buf modtran transmission data fltarr(12,*)
0 wavenumber
1 H2O
2 O3
3 CO2
4 CO
5 CH4
6 N2O
7 O2
8 NH3
9 NO
10 NO2
11 SO2
DISCUSSION
if none of BUF, FILE and ARCHIVE are specified MODTRNS opens and
reads /home/paul/idl/esrg/data/modsaw.xdr
EXAMPLE:
;; read default archive file and plot
modtrns
;; read tape8 and make plot
modtrns,buf,title='Subarctic Winter Atmosphere',file='tape8'
;; save this run in an XDR archive to expedite data retrievals for
;; other IDL sessions.
modtrns,buf,archive='~/yourdirectory/modsaw.xdr'
;; retrieve an archived run (this archive file really exists, so try it)
delvar,buf
modtrns,buf,archive='/home/paul/idl/esrg/data/modsaw.xdr'
;; Here, the ZOOMBAR command is used in a WHILE loop to zoom in on
;; a region of interest. Use previously retrieved value of buf to
;; quicken plots. Window 0 is used to show whole wavelength range
;; while window 2 shows the zoomed in region.
delvar,buf
window,2,xs=600,ys=900 & window,0,xs=600,ys=900
modtrns,buf & xs=!x & r=0
while zoombar(r,/mess,init=r) do begin &$
wset,2 & modtrns,buf,xrange=r & !x=xs & wset,0 & end
REVISIONS:
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/modtrns.pro)
MODTRNS[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: modtrns
PURPOSE: extract transmission from modtran tape8, display transmission
plots
USEAGE: modtrns,buf,archive=archive,file=file,xrange=xrange,$
title=title,sort=sort
KEYWORD INPUT:
file input file name (defaults to "tape8")
archive archive data set name, if this keyword is present and both
FILE and BUF are not set, input is read from specified
modtran data set which has been previously benn saved
in machine independent XDL format. IF either BUF or
FILE are set, the data in FILE or BUF are written to
ARCHIVE.
title string which specifies title of transmission plot
xrange wavelength range (defaults to wavelength range of modtran run)
sort if set, plot four most opaque species in order of
increasing band opacity. Otherwise order is
(total,h2o,co2,o3,o2, ch4+n2o+co+no2+so2+nh3+no)
INPUT/OUTPUT:
buf modtran transmission data fltarr(12,*)
0 wavenumber
1 H2O
2 O3
3 CO2
4 CO
5 CH4
6 N2O
7 O2
8 NH3
9 NO
10 NO2
11 SO2 ;
DISCUSSION
if none of BUF, FILE and ARCHIVE are specified MODTRNS opens and
reads /local/idl/user_contrib/esrg/modsaw.xdr
EXAMPLE:
;; read default archive file and plot
modtrns
;; read tape8 and make plot
modtrns,buf,title='Subarctic Winter Atmosphere',file='tape8'
;; save this run in an XDR archive to expedite data retrievals for
;; other IDL sessions.
modtrns,buf,archive='~/yourdirectory/modsaw.xdr'
;; retrieve an archived run (this archive file really exists, so try it)
delvar,buf
modtrns,buf,archive='/local/idl/user_contrib/esrg/modsaw.xdr'
;; Here, the ZOOMBAR command is used in a WHILE loop to zoom in on
;; a region of interest. Use previously retrieved value of buf to
;; quicken plots. Window 0 is used to show whole wavelength range
;; while window 2 shows the zoomed in region.
delvar,buf
window,2,xs=600,ys=900 & window,0,xs=600,ys=900
modtrns,buf & xs=!x & r=0
while zoombar(r,/mess,init=r) do begin &$
wset,2 & modtrns,buf,xrange=r & !x=xs & wset,0 & end
REVISIONS:
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/modtrns.pro)
MON2STR[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MON2STR
PURPOSE:
Return a string containing a month's name.
CALLING SEQUENCE:
mon_name = mon2str(1)
INPUTS:
mon month desired. NOTE: mon is 1-based (e.g., January = 1)
OPTIONAL INPUTS:
type string defining type of string desired:
undefined: full string, first letter capitalized
e.g., 'December'
'short': abbreviated string, uncapitalized; three
letter abbreviations except September
e.g., 'dec', 'sept'
'capshort': abbreviated string, capitalized; three
letter abbreviations e.g., 'Dec', 'Sep'
OUTPUTS:
An string is returned.
EXAMPLE:
print,mon2str(12)
December
print,mon2str(12,'short')
dec
print,mon2str(9,'short')
sept
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/03/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/mon2str.pro)
MON2STR[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MON2STR
PURPOSE:
Return a string containing a month's name.
CALLING SEQUENCE:
mon_name = mon2str(1)
INPUTS:
mon month desired. NOTE: mon is 1-based (e.g., January = 1)
OPTIONAL INPUTS:
type string defining type of string desired:
undefined: full string, first letter capitalized
e.g., 'December'
'short': abbreviated string, uncapitalized; three
letter abbreviations except September
e.g., 'dec', 'sept'
'capshort': abbreviated string, capitalized; three
letter abbreviations e.g., 'Dec', 'Sep'
OUTPUTS:
An string is returned.
EXAMPLE:
print,mon2str(12)
December
print,mon2str(12,'short')
dec
print,mon2str(9,'short')
sept
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/03/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/mon2str.pro)
MOON_POSITION_BRD_CAM_STEP3_CORR2D_YH[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
choose point at the image presented in window number NWIND
the coordinates of the point are in device pixels
EXPLANATION:
left button choose the pixel pointed by mouse
the selection can be changed
right button sonfirmed the selection
CALLING SEQUENCE:
KUR, x, y, nwind
INPUTS:
nwind = number of the window with the image
OUTPUTS:
x, y = X- and Y-coordination of the choosen pixel in device coord. system
MODIFICATION HISTORY:
Written, ?, by ?
Modified, January 2002, P. Rudawy, IAUWr
Modified, 26 Marz 2002, P. Rudawy, IAUWr "cursor" instead of obsolete "tvrdc"
(See /home/drw/idl/pawel/Moon_position_brd_cam_step3_corr2d_YH.pro)
MOON_POSITION_BRD_CAM_STEP3_CORR2D_YH[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
plots rectangle in the active window
CALLING SEQUENCE:
plotbox, x1, x2, y1, y2
INPUTS:
X1 - X-coord of the lower-left corner
X2 - X-coord of the upper-right corner
Y1 - Y-coord of the lower-left corner
Y2 - Y-coord of the upper-right corner
OUTPUTS:
none
MODIFICATION HISTORY:
Written, January 2002, P. Rudawy, IAUWr
(See /home/drw/idl/pawel/Moon_position_brd_cam_step3_corr2d_YH.pro)
MOON_POSITION_BRD_CAM_STEP3_CORR2D_YH[3]
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
choose point at the image presented in window number NWIND
the coordinates of the point are in device pixels
EXPLANATION:
left button choose the pixel pointed by mouse
the selection can be changed
right button sonfirmed the selection
CALLING SEQUENCE:
KUR, x, y, nwind
INPUTS:
nwind = number of the window with the image
OUTPUTS:
x, y = X- and Y-coordination of the choosen pixel in device coord. system
MODIFICATION HISTORY:
Written, ?, by ?
Modified, January 2002, P. Rudawy, IAUWr
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH.pro)
MOON_POSITION_BRD_CAM_STEP3_CORR2D_YH[4]
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
plots rectangle in the active window
CALLING SEQUENCE:
plotbox, x1, x2, y1, y2
INPUTS:
X1 - X-coord of the lower-left corner
X2 - X-coord of the upper-right corner
Y1 - Y-coord of the lower-left corner
Y2 - Y-coord of the upper-right corner
OUTPUTS:
none
MODIFICATION HISTORY:
Written, January 2002, P. Rudawy, IAUWr
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH.pro)
MOON_POSITION_BRD_CAM_STEP3_CORR2D_YH_0[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
choose point at the image presented in window number NWIND
the coordinates of the point are in device pixels
EXPLANATION:
left button choose the pixel pointed by mouse
the selection can be changed
right button sonfirmed the selection
CALLING SEQUENCE:
KUR, x, y, nwind
INPUTS:
nwind = number of the window with the image
OUTPUTS:
x, y = X- and Y-coordination of the choosen pixel in device coord. system
MODIFICATION HISTORY:
Written, ?, by ?
Modified, January 2002, P. Rudawy, IAUWr
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH_0.pro)
MOON_POSITION_BRD_CAM_STEP3_CORR2D_YH_0[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
plots rectangle in the active window
CALLING SEQUENCE:
plotbox, x1, x2, y1, y2
INPUTS:
X1 - X-coord of the lower-left corner
X2 - X-coord of the upper-right corner
Y1 - Y-coord of the lower-left corner
Y2 - Y-coord of the upper-right corner
OUTPUTS:
none
MODIFICATION HISTORY:
Written, January 2002, P. Rudawy, IAUWr
(See /home/drw/idl/secis2/Moon_position_brd_cam_step3_corr2d_YH_0.pro)
MOON_POSITION_BRD_CAM_STEP4_FINALSHIFT_YH[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
plots rectangle in the active window
CALLING SEQUENCE:
plotbox, x1, x2, y1, y2
INPUTS:
X1 - X-coord of the lower-left corner
X2 - X-coord of the upper-right corner
Y1 - Y-coord of the lower-left corner
Y2 - Y-coord of the upper-right corner
OUTPUTS:
none
MODIFICATION HISTORY:
Written, January 2002, P. Rudawy, IAUWr
(See /home/drw/idl/pawel/Moon_position_brd_cam_step4_finalshift_YH.pro)
MOON_POSITION_BRD_CAM_STEP4_FINALSHIFT_YH[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
plots rectangle in the active window
CALLING SEQUENCE:
plotbox, x1, x2, y1, y2
INPUTS:
X1 - X-coord of the lower-left corner
X2 - X-coord of the upper-right corner
Y1 - Y-coord of the lower-left corner
Y2 - Y-coord of the upper-right corner
OUTPUTS:
none
MODIFICATION HISTORY:
Written, January 2002, P. Rudawy, IAUWr
(See /home/drw/idl/Moon_position_brd_cam_step4_finalshift_YH.pro)
MOON_POSITION_BRD_CAM_STEP4_FINALSHIFT_YH[3]
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
plots rectangle in the active window
CALLING SEQUENCE:
plotbox, x1, x2, y1, y2
INPUTS:
X1 - X-coord of the lower-left corner
X2 - X-coord of the upper-right corner
Y1 - Y-coord of the lower-left corner
Y2 - Y-coord of the upper-right corner
OUTPUTS:
none
MODIFICATION HISTORY:
Written, January 2002, P. Rudawy, IAUWr
(See /home/drw/idl/secis2/Moon_position_brd_cam_step4_finalshift_YH.pro)
MOON_POSITION_BRD_CAM_STEP4_FINALSHIFT_YH_0
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
plots rectangle in the active window
CALLING SEQUENCE:
plotbox, x1, x2, y1, y2
INPUTS:
X1 - X-coord of the lower-left corner
X2 - X-coord of the upper-right corner
Y1 - Y-coord of the lower-left corner
Y2 - Y-coord of the upper-right corner
OUTPUTS:
none
MODIFICATION HISTORY:
Written, January 2002, P. Rudawy, IAUWr
(See /home/drw/idl/secis2/Moon_position_brd_cam_step4_finalshift_YH_0.pro)
MOVELINE.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MOVELINE.PRO
PURPOSE:
To plot a line in a plot window which moves around
with the cursor and records its x-value when the 3rd
mouse button is pressed
CALLING SEQUENCE:
moveline,xchosen
HISTORY:
based on p.107 in 'IDL Programming: Learning IDL'
Adapted by D. Williams, QUB, 8/11/00
(See /home/drw/idl/secis/moveline.pro)
MOVE_IT_BACK2
[Previous Routine]
[Next Routine]
[List of Routines]
MOVE_IT_BACK2,PROM,PROMOUT,DISPARR,INITIAL=INIT
(See /home/drw/idl/secis/move_it_back2.pro)
MOYENVERT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MOYENVERT
PURPOSE:
Return the an array that is the "vertical" average of a stack of
arrays.
CATEGORY:
Array manipulation.
CALLING SEQUENCE:
moyenvert, tab, moy, stdv, nb
INPUTS:
tab the array to be averaged
OPTIONAL INPUTS:
quiet don't print messages
nodata use this value when searching for nodata values
OUTPUTS:
moy average of tab through third dimension
stdv standard deviation
nb number of values used in average at each pixel
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Didier Jourdan Earth Space Research Group, UCSB 12/03/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/moyenvert.pro)
MOYENVERT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MOYENVERT
PURPOSE:
Return the an array that is the "vertical" average of a stack of
arrays.
CATEGORY:
Array manipulation.
CALLING SEQUENCE:
moyenvert, tab, moy, stdv, nb
INPUTS:
tab the array to be averaged
OPTIONAL INPUTS:
quiet don't print messages
nodata use this value when searching for nodata values
OUTPUTS:
moy average of tab through third dimension
stdv standard deviation
nb number of values used in average at each pixel
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Didier Jourdan Earth Space Research Group, UCSB 12/03/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/moyenvert.pro)
MPCHILIM[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPCHILIM
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:
Compute confidence limits for chi-square statistic
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
DELCHI = MPCHILIM(PROB, DOF, [/SIGMA, /CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPCHILIM() computes confidence limits of the
chi-square statistic for a desired probability level. The returned
values, DELCHI, are the limiting chi-squared values: a chi-squared
value of greater than DELCHI will occur by chance with probability
PROB:
P_CHI(CHI > DELCHI; DOF) = PROB
In specifying the probability level the user has three choices:
* give the confidence level (default);
* give the significance level (i.e., 1 - confidence level) and
pass the /SLEVEL keyword; OR
* give the "sigma" of the probability (i.e., compute the
probability based on the normal distribution) and pass the
/SIGMA keyword.
Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.
INPUTS:
PROB - scalar or vector number, giving the desired probability
level as described above.
DOF - scalar or vector number, giving the number of degrees of
freedom in the chi-square distribution.
RETURNS:
Returns a scalar or vector of chi-square confidence limits.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level.
CLEVEL - if set, then PROB describes the confidence level
(default).
SIGMA - if set, then PROB is the number of "sigma" away from the
mean in the normal distribution.
EXAMPLES:
print, mpchilim(0.99d, 2d, /clevel)
Print the 99% confidence limit for a chi-squared of 2 degrees of
freedom.
print, mpchilim(5d, 2d, /sigma)
Print the "5 sigma" confidence limit for a chi-squared of 2
degrees of freedom. Here "5 sigma" indicates the gaussian
probability of a 5 sigma event or greater.
P_GAUSS(5D) = 1D - 5.7330314e-07
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
$Id: mpchilim.pro,v 1.4 2001/11/18 12:59:16 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpchilim.pro)
MPCHILIM[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPCHILIM
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:
Compute confidence limits for chi-square statistic
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
DELCHI = MPCHILIM(PROB, DOF, [/SIGMA, /CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPCHILIM() computes confidence limits of the
chi-square statistic for a desired probability level. The returned
values, DELCHI, are the limiting chi-squared values: a chi-squared
value of greater than DELCHI will occur by chance with probability
PROB:
P_CHI(CHI > DELCHI; DOF) = PROB
In specifying the probability level the user has three choices:
* give the confidence level (default);
* give the significance level (i.e., 1 - confidence level) and
pass the /SLEVEL keyword; OR
* give the "sigma" of the probability (i.e., compute the
probability based on the normal distribution) and pass the
/SIGMA keyword.
Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.
INPUTS:
PROB - scalar or vector number, giving the desired probability
level as described above.
DOF - scalar or vector number, giving the number of degrees of
freedom in the chi-square distribution.
RETURNS:
Returns a scalar or vector of chi-square confidence limits.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level.
CLEVEL - if set, then PROB describes the confidence level
(default).
SIGMA - if set, then PROB is the number of "sigma" away from the
mean in the normal distribution.
EXAMPLES:
print, mpchilim(0.99d, 2d, /clevel)
Print the 99% confidence limit for a chi-squared of 2 degrees of
freedom.
print, mpchilim(5d, 2d, /sigma)
Print the "5 sigma" confidence limit for a chi-squared of 2
degrees of freedom. Here "5 sigma" indicates the gaussian
probability of a 5 sigma event or greater.
P_GAUSS(5D) = 1D - 5.7330314e-07
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
$Id: mpchilim.pro,v 1.4 2001/11/18 12:59:16 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpchilim.pro)
MPCHITEST[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPCHITEST
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:
Compute the probability of a given chi-squared value
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
PROB = MPCHITEST(CHI, DOF, [/SIGMA, /CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPCHITEST() computes the probability for a value drawn
from the chi-square distribution to equal or exceed the given value
CHI. This can be used for confidence testing of a measured value
obeying the chi-squared distribution.
P_CHI(X > CHI; DOF) = PROB
In specifying the returned probability level the user has three
choices:
* return the confidence level when the /CLEVEL keyword is passed;
OR
* return the significance level (i.e., 1 - confidence level) when
the /SLEVEL keyword is passed (default); OR
* return the "sigma" of the probability (i.e., compute the
probability based on the normal distribution) when the /SIGMA
keyword is passed.
Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.
INPUTS:
CHI - chi-squared value to be tested.
DOF - scalar or vector number, giving the number of degrees of
freedom in the chi-square distribution.
RETURNS:
Returns a scalar or vector of probabilities, as described above,
and according to the /SLEVEL, /CLEVEL and /SIGMA keywords.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level
(default).
CLEVEL - if set, then PROB describes the confidence level.
SIGMA - if set, then PROB is the number of "sigma" away from the
mean in the normal distribution.
EXAMPLES:
print, mpchitest(1300d,1252d)
Print the probability for a chi-squared value with 1252 degrees of
freedom to exceed a value of 1300, as a confidence level.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
$Id: mpchitest.pro,v 1.5 2001/11/18 12:59:16 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpchitest.pro)
MPCHITEST[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPCHITEST
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:
Compute the probability of a given chi-squared value
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
PROB = MPCHITEST(CHI, DOF, [/SIGMA, /CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPCHITEST() computes the probability for a value drawn
from the chi-square distribution to equal or exceed the given value
CHI. This can be used for confidence testing of a measured value
obeying the chi-squared distribution.
P_CHI(X > CHI; DOF) = PROB
In specifying the returned probability level the user has three
choices:
* return the confidence level when the /CLEVEL keyword is passed;
OR
* return the significance level (i.e., 1 - confidence level) when
the /SLEVEL keyword is passed (default); OR
* return the "sigma" of the probability (i.e., compute the
probability based on the normal distribution) when the /SIGMA
keyword is passed.
Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.
INPUTS:
CHI - chi-squared value to be tested.
DOF - scalar or vector number, giving the number of degrees of
freedom in the chi-square distribution.
RETURNS:
Returns a scalar or vector of probabilities, as described above,
and according to the /SLEVEL, /CLEVEL and /SIGMA keywords.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level
(default).
CLEVEL - if set, then PROB describes the confidence level.
SIGMA - if set, then PROB is the number of "sigma" away from the
mean in the normal distribution.
EXAMPLES:
print, mpchitest(1300d,1252d)
Print the probability for a chi-squared value with 1252 degrees of
freedom to exceed a value of 1300, as a confidence level.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
$Id: mpchitest.pro,v 1.5 2001/11/18 12:59:16 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpchitest.pro)
MPCURVEFIT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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:
PRO MYFUNCT, X, P, YMOD
; The independent variable is X
; Parameter values are passed in "P"
YMOD = ... computed model values at X ...
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.
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.
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 residuals for the
returned parameter values.
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, $
FUNCTION_NAME='GAUSS1P') ; 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 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
$Id: mpcurvefit.pro,v 1.5 2003/06/30 21:48:01 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpcurvefit.pro)
MPCURVEFIT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
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,
FUNCTARGS=functargs, ITMAX=itmax, PARINFO=parinfo,
FTOL=ftol, XTOL=xtol, GTOL=gtol,
ITERPROC=iterproc, ITERARGS=iterargs,
NPRINT=nprint, QUIET=quiet, NOCOVAR=nocovar,
NFEV=nfev, ITER=iter, ERRMSG=errmsg,
CHISQ=chisq, COVAR=covar, 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:
PRO MYFUNCT, X, P, YMOD
; The independent variable is X
; Parameter values are passed in "P"
YMOD = ... computed model values at X ...
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.
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.
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.
.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.
INPUTS:
FUNCT - 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 described 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 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 residuals for the
returned parameter values.
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.
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 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.
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.
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.
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:
; 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, $
FUNCTION_NAME='GAUSS1P') ; 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 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
$Id: mpcurvefit.pro,v 1.2 2000/12/18 07:00:15 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpcurvefit.pro)
MPFIT2DFUN[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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 residuals for the
returned parameter values.
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 - 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)
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
$Id: mpfit2dfun.pro,v 1.4 2003/06/30 21:47:36 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpfit2dfun.pro)
MPFIT2DFUN[2]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
.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.
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 residuals for the
returned parameter values.
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.
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)
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
$Id: mpfit2dfun.pro,v 1.2 2000/12/18 07:00:15 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpfit2dfun.pro)
MPFIT2DPEAK[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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.
Default: 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
$Id: mpfit2dpeak.pro,v 1.5 2003/06/30 21:48:01 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpfit2dpeak.pro)
MPFIT2DPEAK[2]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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 j 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.
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.
Default: 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.
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.
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)
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.
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
$Id: mpfit2dpeak.pro,v 1.2 2000/12/18 07:00:15 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpfit2dpeak.pro)
MPFITELLIPSE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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
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%.
Users can weight their data as they see appropriate. However, the
following prescription for the weighting appears to be the correct
one, and produces values 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, it should be pointed
out that this weighting is only 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.
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.
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.
QUIET - if set then diagnostic fitting messages are suppressed.
Default: QUIET=1 (i.e., no diagnostics)
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.
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.
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)^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)
plot, x, y, psym=1
phi = dindgen(101)*2D*!dpi/100
oplot, p(2)+p(0)*cos(phi), p(3)+p(1)*sin(phi)
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
$Id: mpfitellipse.pro,v 1.8 2003/01/24 04:04:30 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpfitellipse.pro)
MPFITELLIPSE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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
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%.
Users can weight their data as they see appropriate. However, the
following prescription for the weighting appears to be the correct
one, and produces values 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, it should be pointed
out that this weighting is only 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.
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.
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.
QUIET - if set then diagnostic fitting messages are suppressed.
Default: QUIET=1 (i.e., no diagnostics)
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.
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.
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)^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)
plot, x, y, psym=1
phi = dindgen(101)*2D*!dpi/100
oplot, p(2)+p(0)*cos(phi), p(3)+p(1)*sin(phi)
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
$Id: mpfitellipse.pro,v 1.5 2001/11/18 13:06:52 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpfitellipse.pro)
MPFITEXPR[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
.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.
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 residuals for the
returned parameter values.
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
$Id: mpfitexpr.pro,v 1.10 2003/08/10 22:12:11 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpfitexpr.pro)
MPFITEXPR[2]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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.
.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.
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 residuals for the
returned parameter values.
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.
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
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(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)
$Id: mpfitexpr.pro,v 1.4 2001/05/25 04:34:23 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpfitexpr.pro)
MPFITFUN[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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.
See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
in MPFIT.PRO if you wish to compute the derivatives for yourself.
AUTODERIVATIVE is accepted by MPFITFUN 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.
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.
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.
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.
RETURNS:
Returns the array of best-fit parameters.
KEYWORD PARAMETERS:
BESTNORM - the value of the summed squared residuals for the
returned parameter values.
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.
CASH - when set, the fit statistic is changed to a derivative of
the CASH statistic. The model function must be strictly
positive.
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.
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
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
$Id: mpfitfun.pro,v 1.6 2003/06/30 21:47:36 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpfitfun.pro)
MPFITFUN[2]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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.
See the discussion under "ANALYTIC DERIVATIVES" and AUTODERIVATIVE
in MPFIT.PRO if you wish to compute the derivatives for yourself.
AUTODERIVATIVE is accepted by MPFITFUN 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.
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.
.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.
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.
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.
RETURNS:
Returns the array of best-fit parameters.
KEYWORD PARAMETERS:
BESTNORM - the value of the summed squared residuals for the
returned parameter values.
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.
ERRMSG - a string error or warning message is returned.
CASH - when set, the fit statistic is changed to a derivative of
the CASH statistic. The model function must be strictly
positive.
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(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
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
$Id: mpfitfun.pro,v 1.3 2001/01/11 22:28:10 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpfitfun.pro)
MPFITPEAK[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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.
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.
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.
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.
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.
Default: 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 / 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.
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.
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
$Id: mpfitpeak.pro,v 1.7 2003/09/06 16:29:44 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpfitpeak.pro)
MPFITPEAK[2]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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.
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.
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.
ERROR - upon input, the measured 1-sigma uncertainties in the "Y"
values. If no ERROR or WEIGHTS are given, then the fit is
unweighted.
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.
Default: 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.
NEGATIVE / POSITIVE - if set, and ESTIMATES is not provided, then
MPFITPEAK will assume that a
negative/positive peak is present.
Default: determined automatically
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)
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
The ERROR keyword takes precedence over any WEIGHTS
keyword values. If no ERROR or WEIGHTS are given, then
the fit is unweighted.
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
$Id: mpfitpeak.pro,v 1.5 2001/09/18 00:12:39 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpfitpeak.pro)
MPFIT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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 analytical 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 analytical 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.
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 (by setting ERROR_CODE to a
number between -15 and -1).
ANALYTIC 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, if you desire to compute them
analytically, then the AUTODERIVATIVE=0 keyword must be passed. As
a practical matter, it is often sufficient and even faster to allow
MPFIT to calculate the derivatives numerically, and so
AUTODERIVATIVE=0 is not necessary.
Also, the user function must be declared with one additional
parameter, as follows:
FUNCTION MYFUNCT, p, dp, X=x, Y=y, ERR=err
model = F(x, p)
if n_params() GT 1 then begin
; Compute derivatives
dp = make_array(n_elements(x), n_elements(p), value=x(0)*0)
for i = 0, n_elements(p)-1 do $
dp(*,i) = FGRAD(x, p, i)
endif
return, (y-model)/err
END
where FGRAD(x, p, i) is a user function which must compute the
derivative of the model with respect to parameter P(i) at X. When
finite differencing is used for computing derivatives (ie, when
AUTODERIVATIVE=1), the parameter DP is not passed. Therefore
functions can use N_PARAMS() to indicate whether they must compute
the derivatives or not.
Derivatives should be returned in the DP array. DP should be an m x
n array, where m is the number of data points and n is the number
of parameters. dp(i,j) is the derivative at the ith point with
respect to the jth parameter.
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.
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.
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.
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.
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 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.
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 (analytical) derivatives.
Default: set (=1)
NOTE: to supply your own analytical derivatives,
explicitly pass AUTODERIVATIVE=0
BESTNORM - the value of the summed squared residuals for the
returned parameter values.
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:
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.
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.
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, ...
; 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.
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 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. 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 - 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
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:
-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.
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_QRSOLV provides the solution for dx.
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.
More', Jorge J., "The Levenberg-Marquardt Algorithm:
Implementation and Theory," in *Numerical Analysis*, ed. Watson,
G. A., Lecture Notes in Mathematics 630, Springer-Verlag, 1977.
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)
$Id: mpfit.pro,v 1.30 2003/11/24 01:51:13 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpfit.pro)
MPFIT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
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 analytical 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 analytical 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.
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 (by setting ERROR_CODE to a
number between -15 and -1).
ANALYTIC 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, if you desire to compute them
analytically, then the AUTODERIVATIVE=0 keyword must be passed. As
a practical matter, it is often sufficient and even faster to allow
MPFIT to calculate the derivatives numerically, and so
AUTODERIVATIVE=0 is not necessary.
Also, the user function must be declared with one additional
parameter, as follows:
FUNCTION MYFUNCT, p, dp, X=x, Y=y, ERR=err
model = F(x, p)
if n_params() GT 1 then begin
; Compute derivatives
dp = make_array(n_elements(x), n_elements(p), value=x(0)*0)
for i = 0, n_elements(p)-1 do $
dp(*,i) = FGRAD(x, p, i)
endif
return, (y-model)/err
END
where FGRAD(x, p, i) is a user function which must compute the
derivative of the model with respect to parameter P(i) at X. When
finite differencing is used for computing derivatives (ie, when
AUTODERIVATIVE=1), the parameter DP is not passed. Therefore
functions can use N_PARAMS() to indicate whether they must compute
the derivatives or not.
Derivatives should be returned in the DP array. DP should be an m x
n array, where m is the number of data points and n is the number
of parameters. dp(i,j) is the derivative at the ith point with
respect to the jth parameter.
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.
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.
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.
.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.
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.
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 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.
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 (analytical) derivatives.
Default: set (=1)
NOTE: to supply your own analytical derivatives,
explicitly pass AUTODERIVATIVE=0
BESTNORM - the value of the summed squared residuals for the
returned parameter values.
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:
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.
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.
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, DOF=dof, ...
; 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.
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 Control-G on the keyboard. This
only works if you use the default ITERPROC.
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(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
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:
-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.
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_QRSOLV provides the solution for dx.
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.
More', Jorge J., "The Levenberg-Marquardt Algorithm:
Implementation and Theory," in *Numerical Analysis*, ed. Watson,
G. A., Lecture Notes in Mathematics 630, Springer-Verlag, 1977.
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
$Id: mpfit.pro,v 1.19 2002/04/02 17:08:36 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpfit.pro)
MPFTEST[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPFTEST
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:
Compute the probability of a given F value
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
PROB = MPFTEST(F, DOF1, DOF2, [/SIGMA, /CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPFTEST() computes the probability for a value drawn
from the F-distribution to equal or exceed the given value of F.
This can be used for confidence testing of a measured value obeying
the F-distribution (i.e., for testing the ratio of variances, or
equivalently for the addition of parameters to a fitted model).
P_F(X > F; DOF1, DOF2) = PROB
In specifying the returned probability level the user has three
choices:
* return the confidence level when the /CLEVEL keyword is passed;
OR
* return the significance level (i.e., 1 - confidence level) when
the /SLEVEL keyword is passed (default); OR
* return the "sigma" of the probability (i.e., compute the
probability based on the normal distribution) when the /SIGMA
keyword is passed.
Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.
For the ratio of variance test, the two variances, VAR1 and VAR2,
should be distributed according to the chi-squared distribution
with degrees of freedom DOF1 and DOF2 respectively. The F-value is
computed as:
F = (VAR1/DOF1) / (VAR2/DOF2)
and then the probability is computed as:
PROB = MPFTEST(F, DOF1, DOF2, ... )
For the test of additional parameters in least squares fitting, the
user should perform two separate fits, and have two chi-squared
values. One fit should be the "original" fit with no additional
parameters, and one fit should be the "new" fit with M additional
parameters.
CHI1 - chi-squared value for original fit
DOF1 - number of degrees of freedom of CHI1 (number of data
points minus number of original parameters)
CHI2 - chi-squared value for new fit
DOF2 - number of degrees of freedom of CHI2
Note that according to this formalism, the number of degrees of
freedom in the "new" fit, DOF2, should be less than the number of
degrees of freedom in the "original" fit, DOF1 (DOF2 < DOF1); and
also CHI2 < CHI1.
With the above definition, the F value is computed as:
F = ( (CHI1-CHI2)/(DOF1-DOF2) ) / (CHI2/DOF2)
where DOF1-DOF2 is equal to M, and then the F-test probability is
computed as:
PROB = MPFTEST(F, DOF1-DOF2, DOF2, ... )
Note that this formalism assumes that the addition of the M
parameters is a small peturbation to the overall fit. If the
additional parameters dramatically changes the character of the
model, then the first "ratio of variance" test is more appropriate,
where F = (CHI1/DOF1) / (CHI2/DOF2).
INPUTS:
F - ratio of variances as defined above.
DOF1 - number of degrees of freedom in first variance component.
DOF2 - number of degrees of freedom in second variance component.
RETURNS:
Returns a scalar or vector of probabilities, as described above,
and according to the /SLEVEL, /CLEVEL and /SIGMA keywords.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level
(default).
CLEVEL - if set, then PROB describes the confidence level.
SIGMA - if set, then PROB is the number of "sigma" away from the
mean in the normal distribution.
EXAMPLE:
chi1 = 62.3D & dof1 = 42d
chi2 = 54.6D & dof2 = 40d
f = ((chi1-chi2)/(dof1-dof2)) / (chi2/dof2)
print, mpftest(f, dof1-dof2, dof2)
This is a test for addition of parameters. The "original"
chi-squared value was 62.3 with 42 degrees of freedom, and the
"new" chi-squared value was 54.6 with 40 degrees of freedom.
These values reflect the addition of 2 parameters and the
reduction of the chi-squared value by 7.7. The significance of
this set of circumstances is 0.071464757.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
Added documentation, 30 Dec 2001, CM
Documentation corrections (thanks W. Landsman), 17 Jan 2002, CM
Example docs were corrected (Thanks M. Perez-Torres), 17 Feb 2002,
CM
Example corrected again (sigh...), 13 Feb 2003, CM
$Id: mpftest.pro,v 1.7 2003/02/13 23:41:16 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpftest.pro)
MPFTEST[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPFTEST
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:
Compute the probability of a given F value
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
PROB = MPFTEST(F, DOF1, DOF2, [/SIGMA, /CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPFTEST() computes the probability for a value drawn
from the F-distribution to equal or exceed the given value of F.
This can be used for confidence testing of a measured value obeying
the F-distribution (i.e., for testing the ratio of variances, or
equivalently for the addition of parameters to a fitted model).
P_F(X > F; DOF1, DOF2) = PROB
In specifying the returned probability level the user has three
choices:
* return the confidence level when the /CLEVEL keyword is passed;
OR
* return the significance level (i.e., 1 - confidence level) when
the /SLEVEL keyword is passed (default); OR
* return the "sigma" of the probability (i.e., compute the
probability based on the normal distribution) when the /SIGMA
keyword is passed.
Note that /SLEVEL, /CLEVEL and /SIGMA are mutually exclusive.
For the ratio of variance test, the two variances, VAR1 and VAR2,
should be distributed according to the chi-squared distribution
with degrees of freedom DOF1 and DOF2 respectively. The F-value is
computed as:
F = (VAR1/DOF1) / (VAR2/DOF2)
and then the probability is computed as:
PROB = MPFTEST(F, DOF1, DOF2, ... )
For the test of additional parameters in least squares fitting, the
user should perform two separate fits, and have two chi-squared
values. One fit should be the "original" fit with no additional
parameters, and one fit should be the "new" fit with M additional
parameters.
CHI1 - chi-squared value for original fit
DOF1 - number of degrees of freedom of CHI1 (number of data
points minus number of original parameters)
CHI2 - chi-squared value for new fit
DOF2 - number of degrees of freedom of CHI2
Note that according to this formalism, the number of degrees of
freedom in the "new" fit, DOF2, should be less than the number of
degrees of freedom in the "original" fit, DOF1 (DOF2 < DOF1); and
also CHI2 < CHI1.
With the above definition, the F value is computed as:
F = ( (CHI1-CHI2)/(DOF1-DOF2) ) / (CHI2/DOF2)
where DOF1-DOF2 is equal to M, and then the F-test probability is
computed as:
PROB = MPFTEST(F, DOF1-DOF2, DOF2, ... )
Note that this formalism assumes that the addition of the M
parameters is a small peturbation to the overall fit. If the
additional parameters dramatically changes the character of the
model, then the first "ratio of variance" test is more appropriate,
where F = (CHI1/DOF1) / (CHI2/DOF2).
INPUTS:
F - ratio of variances as defined above.
DOF1 - number of degrees of freedom in first variance component.
DOF2 - number of degrees of freedom in second variance component.
RETURNS:
Returns a scalar or vector of probabilities, as described above,
and according to the /SLEVEL, /CLEVEL and /SIGMA keywords.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level
(default).
CLEVEL - if set, then PROB describes the confidence level.
SIGMA - if set, then PROB is the number of "sigma" away from the
mean in the normal distribution.
EXAMPLE:
chi1 = 62.3D & dof1 = 42d
chi2 = 54.6D & dof2 = 40d
f = ((chi1-chi2)/(dof1-dof2)) / (chi2/dof2)
print, mpftest(f, dof1-dof2, dof2)
This is a test for addition of parameters. The "original"
chi-squared value was 62.3 with 42 degrees of freedom, and the
"new" chi-squared value was 54.6 with 40 degrees of freedom.
These values reflect the addition of 2 parameters and the
reduction of the chi-squared value by 7.7. The significance of
this set of circumstances is 0.029568701.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
Added documentation, 30 Dec 2001, CM
Documentation corrections (thanks W. Landsman), 17 Jan 2002, CM
Example docs were corrected (Thanks M. Perez-Torres), 17 Feb 2002, CM
$Id: mpftest.pro,v 1.6 2002/02/17 14:48:28 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpftest.pro)
MPNORMLIM[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPNORMLIM
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:
Compute confidence limits for normally distributed variable
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
Z = MPNORMLIM(PROB, [/CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPNORMLIM() computes confidence limits of a normally
distributed variable (with zero mean and unit variance), for a
desired probability level. The returned values, Z, are the
limiting values: a the magnitude of a normally distributed value
is greater than Z by chance with a probability PROB:
P_NORM(ABS(X) > Z) = PROB
In specifying the probability level the user has two choices:
* give the confidence level (default);
* give the significance level (i.e., 1 - confidence level) and
pass the /SLEVEL keyword; OR
Note that /SLEVEL and /CLEVEL are mutually exclusive.
INPUTS:
PROB - scalar or vector number, giving the desired probability
level as described above.
RETURNS:
Returns a scalar or vector of normal confidence limits.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level.
CLEVEL - if set, then PROB describes the confidence level
(default).
EXAMPLE:
print, mpnormlim(0.99d, /clevel)
Print the 99% confidence limit for a normally distributed
variable. In this case it is about 2.58 sigma.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
$Id: mpnormlim.pro,v 1.3 2001/11/18 12:59:17 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpnormlim.pro)
MPNORMLIM[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPNORMLIM
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:
Compute confidence limits for normally distributed variable
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
Z = MPNORMLIM(PROB, [/CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPNORMLIM() computes confidence limits of a normally
distributed variable (with zero mean and unit variance), for a
desired probability level. The returned values, Z, are the
limiting values: a the magnitude of a normally distributed value
is greater than Z by chance with a probability PROB:
P_NORM(ABS(X) > Z) = PROB
In specifying the probability level the user has two choices:
* give the confidence level (default);
* give the significance level (i.e., 1 - confidence level) and
pass the /SLEVEL keyword; OR
Note that /SLEVEL and /CLEVEL are mutually exclusive.
INPUTS:
PROB - scalar or vector number, giving the desired probability
level as described above.
RETURNS:
Returns a scalar or vector of normal confidence limits.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level.
CLEVEL - if set, then PROB describes the confidence level
(default).
EXAMPLE:
print, mpnormlim(0.99d, /clevel)
Print the 99% confidence limit for a normally distributed
variable. In this case it is about 2.58 sigma.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
$Id: mpnormlim.pro,v 1.3 2001/11/18 12:59:17 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpnormlim.pro)
MPNORMTEST[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPNORMTEST
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:
Compute the probability of a given normally distributed Z value
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
PROB = MPNORMTEST(Z, [/CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPNORMTEST() computes the probability for the
magnitude of a value drawn from the normal distribution to equal or
exceed the given value Z. This can be used for confidence testing
of a measured value obeying the normal distribution.
P_NORM(ABS(X) > Z) = PROB
In specifying the returned probability level the user has two
choices:
* return the confidence level when the /CLEVEL keyword is passed;
OR
* return the significance level (i.e., 1 - confidence level) when
the /SLEVEL keyword is passed (default).
Note that /SLEVEL and /CLEVEL are mutually exclusive.
INPUTS:
Z - the value to best tested. Z should be drawn from a normal
distribution with zero mean and unit variance. If a given
quantity Y has mean MU and standard deviation STD, then Z can
be computed as Z = (Y-MU)/STD.
RETURNS:
Returns a scalar or vector of probabilities, as described above,
and according to the /SLEVEL and /CLEVEL keywords.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level
(default).
CLEVEL - if set, then PROB describes the confidence level.
EXAMPLES:
print, mpnormtest(5d, /slevel)
Print the probability for the magnitude of a randomly distributed
variable with zero mean and unit variance to exceed 5, as a
significance level.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
Corrected error in handling of CLEVEL keyword, 05 Sep 2003
$Id: mpnormtest.pro,v 1.5 2003/09/06 16:30:02 craigm Exp $
(See /home/drw/idl/aux/markwardt/mpnormtest.pro)
MPNORMTEST[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MPNORMTEST
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:
Compute the probability of a given normally distributed Z value
MAJOR TOPICS:
Curve and Surface Fitting, Statistics
CALLING SEQUENCE:
PROB = MPNORMTEST(Z, [/CLEVEL, /SLEVEL ])
DESCRIPTION:
The function MPNORMTEST() computes the probability for the
magnitude of a value drawn from the normal distribution to equal or
exceed the given value Z. This can be used for confidence testing
of a measured value obeying the normal distribution.
P_NORM(ABS(X) > Z) = PROB
In specifying the returned probability level the user has two
choices:
* return the confidence level when the /CLEVEL keyword is passed;
OR
* return the significance level (i.e., 1 - confidence level) when
the /SLEVEL keyword is passed (default).
Note that /SLEVEL and /CLEVEL are mutually exclusive.
INPUTS:
Z - the value to best tested. Z should be drawn from a normal
distribution with zero mean and unit variance. If a given
quantity Y has mean MU and standard deviation STD, then Z can
be computed as Z = (Y-MU)/STD.
RETURNS:
Returns a scalar or vector of probabilities, as described above,
and according to the /SLEVEL and /CLEVEL keywords.
KEYWORD PARAMETERS:
SLEVEL - if set, then PROB describes the significance level
(default).
CLEVEL - if set, then PROB describes the confidence level.
EXAMPLES:
print, mpnormtest(5d, /slevel)
Print the probability for the magnitude of a randomly distributed
variable with zero mean and unit variance to exceed 5, as a
significance level.
REFERENCES:
Algorithms taken from CEPHES special function library, by Stephen
Moshier. (http://www.netlib.org/cephes/)
MODIFICATION HISTORY:
Completed, 1999, CM
Documented, 16 Nov 2001, CM
Reduced obtrusiveness of common block and math error handling, 18
Nov 2001, CM
$Id: mpnormtest.pro,v 1.4 2001/11/18 12:59:17 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/mpnormtest.pro)
MPRANK[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine mprank
purpose compute the nth percentile value in each of a number of a
image superpixel subregions
input:
image image array
perc percentile threshold ( measured from the top,
ie perc=7 => the pixel value which is at the 93% percentile))
binsize size of subregions (assumed square)
keyword input:
interp if set use, interpolation is used to resize results up
to the input image size. A boxy result is ofter produced
when INTERP is not set.
output:
result= value of pixels which are at the PERC percentilie in the
subarea. Values are CONGRIDed up to the size of image.
procedure: MPRANK looks at each subregion in the image and seperately
evaluates the value within that subregion which is in the
upper PERC percentile. The result of the function are
these values CONGRIDed up to the size of the original image.
EXAMPLE:
n=256
xs=sqrt(findgen(n))
ys=sqrt(findgen(n)) ; xss and yss are used
xss=xs # replicate(1,n_elements(ys)) ; to give the random
yss=replicate(1,n_elements(xs)) # ys ; data a nice shape
f=randata(n,n,s=4)
!p.multi=[0,2,2]
tvim,f,title='original data'
tvim,mprank(f,5,32),title='no interp'
tvim,mprank(f,5,32,/interp),title='with interp'
author: Paul Ricchiazzi Nov93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/mprank.pro)
MPRANK[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine mprank
purpose compute the nth percentile value in each of a number of a
image superpixel subregions
input:
image image array
perc percentile threshold ( measured from the top,
ie perc=7 => the pixel value which is at the 93% percentile))
binsize size of subregions (assumed square)
keyword input:
interp if set use, interpolation is used to resize results up
to the input image size. A boxy result is ofter produced
when INTERP is not set.
output:
result= value of pixels which are at the PERC percentilie in the
subarea. Values are CONGRIDed up to the size of image.
procedure: MPRANK looks at each subregion in the image and seperately
evaluates the value within that subregion which is in the
upper PERC percentile. The result of the function are
these values CONGRIDed up to the size of the original image.
EXAMPLE:
n=256
xs=sqrt(findgen(n))
ys=sqrt(findgen(n)) ; xss and yss are used
xss=xs # replicate(1,n_elements(ys)) ; to give the random
yss=replicate(1,n_elements(xs)) # ys ; data a nice shape
f=randata(n,n,s=4)
!p.multi=[0,2,2]
tvim,f,title='original data'
tvim,mprank(f,5,32),title='no interp'
tvim,mprank(f,5,32,/interp),title='with interp'
author: Paul Ricchiazzi Nov93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/mprank.pro)
MSTDEV[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MSTDEV
PURPOSE:
Compute the standard deviation and, optionally, the
mean of any array.
CATEGORY:
G1- Simple calculations on statistical data.
CALLING SEQUENCE:
Result = STDEV(Array [, Mean])
INPUTS:
Array: The data array. Array may be any type except string.
OUTPUTS:
STDEV returns the standard deviation (sample variance
because the divisor is N-1) of Array.
OPTIONAL OUTPUT PARAMETERS:
Mean: Upon return, this parameter contains the mean of the values
in the data array.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Mean = TOTAL(Array)/N_ELEMENTS(Array)
Stdev = SQRT(TOTAL((Array-Mean)^2/(N)))
MODIFICATION HISTORY:
DMS, RSI, Sept. 1983.
(See /home/drw/idl/esrg/mstdev.pro)
MSTDEV[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MSTDEV
PURPOSE:
Compute the standard deviation and, optionally, the
mean of any array.
CATEGORY:
G1- Simple calculations on statistical data.
CALLING SEQUENCE:
Result = STDEV(Array [, Mean])
INPUTS:
Array: The data array. Array may be any type except string.
OUTPUTS:
STDEV returns the standard deviation (sample variance
because the divisor is N-1) of Array.
OPTIONAL OUTPUT PARAMETERS:
Mean: Upon return, this parameter contains the mean of the values
in the data array.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
PROCEDURE:
Mean = TOTAL(Array)/N_ELEMENTS(Array)
Stdev = SQRT(TOTAL((Array-Mean)^2/(N)))
MODIFICATION HISTORY:
DMS, RSI, Sept. 1983.
(See /home/drw/idl/old.esrg/mstdev.pro)
MULTIPSD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
MULTIPSD
PURPOSE:
Given an array of times, ts divide the data into equal time segments,
calculate the FFT power spectra of these segments and average
the power spectra.
CATEGORY:
Math.
CALLING SEQUENCE:
Result = MULTIPSD( Ts, Bin, Nbin, Npsd, Mean, Sigma )
INPUTS:
Ts: An array of times with starting time, Ts(0)=0.
Bin: The length of one time bin in the same UNITS as the Ts array.
Nbin: The number of time bins in each time segment.
OPTIONAL INPUT KEYWORD PARAMETERS:
VERBOSE: Setting the keyword will display messages updating the user
on which time segment the routine is currently processing.
OUTPUTS:
This function returns the average FFT power spectra and the standard
deviations about each average in an array, FLTARR((nbin/2), 2). The
first column, (*,0) holds the power spectra
averaged over Npsd time segments and the second column (*,1) holds the
standard deviations about those averages.
OPTIONAL OUTPUTS:
Npsd: The number of equal time segments the data was divided into.
Mean: Average number of counts/bin over all times FFTed.
Sigma: Sqrt of the variance of the counts/bin about the Mean over
all times FFTed.
PROCEDURE:
The average power spectra is usually normalized in one of two ways:
Leahy or fractional RMS amplitude. The Leahy normalized power is
determined by multiplying (2/) with the results of this function:
Pwrarray = MULTIPSD( Ts, Bin, Nbin, Npsd, Mean, Sigma )
Ncts = Mean*Nbin
Pleahy = (2/Ncts)*Pwrarry(*,0)
where Ncts is the average total number of counts in one time segment.
The fractional RMS amplitude is a dimensionaless quantity defined as
the square root of the variance of the counts/bin divided by the
average counts/bin. Its normalization can be determined by dividing
the Leahy normalized power by the average intensity, :
Iavg = Mean/Bin
Prms = Pleahy/Iavg
To relate Prms to the actual fractional RMS amplitude, (Sigma/Mean):
rms = Sigma/Mean
dFreq = 1/(Bin*Nbin)
TOTAL(Prms)= rms^2/dFreq
EXAMPLE:
The input parameters, nbin and bin are related to the limits of the FFT
frequencies in the following manner:
1/(nbin*bin) = Minimum frequency
1/(2*bin) = Nyquist frequency
Given a time array, ts=LONARR(500000)=[0,1000000], determine the average
power spectra if Bin = 50 and Nbin = 4096.
Bin = 50
Nbin = 1024 -> Npsd = 19 time segments
pwr_result = MULTIPSD( Ts, Bin, Nbin, Npsd, RMS, /VERB )
MODIFICATION HISTORY:
Written by: Han Wen, August 1996.
14-AUG-1996 Eliminated LEAHY, RMS keywords, added RMS output parameter,
check number of parameters.
15-AUG-1996 Removed RMS parameter, added Mean and Sigma parameters.
30-AUG-1996 Bugfix: return sigma instead of variance.
(See /home/drw/idl/bin/ptg/multipsd.pro)
MULTI_READ[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: multi_read
PURPOSE: Read in files of the form s7038r**.fits, clean + callibrate
and then save to the specified directory.
USEAGE: multi_read, file, num, dir
INPUT:
file String containing the file stem in a sequence to be restored.
num The number of files to be read in
dir String containing directory name to which the .sav files are to be
written.
OUTPUT: Cleaned, callibrated IDL sav files in the named directory
EXAMPLE: multi_read, 's7103r', 10, '/scratch/ptg/SAV/'
... will clean & callibrate the files s7103r00.fits ->
s7103r09.fits and then save them to /scratch/ptg/SAV/*.sav
AUTHOR: Peter T. Gallagher, Jan. '98
(See /home/drw/idl/bin/multi_read.pro)
MULTI_READ[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: multi_read
PURPOSE: Read in files of the form s7038r**.fits, clean + callibrate
and then save to the specified directory.
USEAGE: multi_read, file, num, dir
INPUT:
file String containing the file stem in a sequence to be restored.
num The number of files to be read in
dir String containing directory name to which the .sav files are to be
written.
OUTPUT: Cleaned, callibrated IDL sav files in the named directory
EXAMPLE: multi_read, 's7103r', 10, '/scratch/ptg/SAV/'
... will clean & callibrate the files s7103r00.fits ->
s7103r09.fits and then save them to /scratch/ptg/SAV/*.sav
AUTHOR: Peter T. Gallagher, Jan. '98
(See /home/drw/idl/bin/ptg/multi_read.pro)
MUSLOPE
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: muslope
PURPOSE: compute dot product of surface normal to incomming solar ray
USEAGE: result=muslope(sunzen,sunaz,nrmzen,nrmaz)
INPUT:
sunzen solar zenith angle (degrees)
sunaz solar azimuth angle (clockwise from due north, degrees)
nrmzen zenith angle of surface normal vector
(nrmzen=0 for a horizontal surface)
nrmaz azimuth angle of surface normal vector (nrmaz=45 degrees
for a surface that slopes down in the north-east direction)
OUTPUT:
result the dot product of the surface-to-sun unit vector
and the surface normal unit vector.
EXAMPLE:
; find the solar zenith and azimuth for 3 pm, january 8
zensun,8,15.,34.456,-119.813,sunzen,sunaz,/local
; compute surface solar flux onto a surface inclined
; 5 degrees to the north-east
print,f='(3a15/3g15.4)','solar zenith','cos(sunzen)','muslope', $
sunzen,cos(sunzen*!dtor),muslope(sunzen,sunaz,5.,45.)
AUTHOR: Paul Ricchiazzi 08 Jan 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/muslope.pro)
MVE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: mve
AUTHOR: Terry Figel, ESRG, UCSB 10-21-92
CALLING SEQUENCE: mve,var
INPUT:
var an array
PURPOSE: print out the max min mean and std deviation of var
(See /home/drw/idl/esrg/mve.pro)
MVE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: mve
AUTHOR: Terry Figel, ESRG, UCSB 10-21-92
CALLING SEQUENCE: mve,var
INPUT:
var an array
PURPOSE: print out the max min mean and std deviation of var
(See /home/drw/idl/old.esrg/mve.pro)
NCDF
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: ncdf
PURPOSE:
USEAGE: ncdf
OUTPUT:
z net_cdf variable (the last one selected for preview)
KEYWORD INPUT/OUTPUT:
file A string containing the name of an existing NetCDF file or
on return, the name of a selected file.
dir if set to one (an integer) the current directory is scanned
for any files with a .cdf suffix. If instead dir is set to
a directory name (a string) then that directory is scanned
for NetCDF files. The list of files is presented as a menu,
and information for a selected file is displayed. If
present, the command line argument, FILE, is set to the
selected file, and can be used in subsequent commands.
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 20 Jul 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/ncdf.pro)
NCDF_GET_1FIELD[1]
[Previous Routine]
[Next Routine]
[List of Routines]
Get a variable and its metadata from a NetCDF file
Written 1 April 1993 by William Weibel, UCLA Atmospheric Sciences
Source code control Id %W% %G%
USEAGE: ncdf_get_1field, file, varname, z, name
arguments
file string containing the name of the NetCDF file
varname name of the variable to read (string)
z dependent field variable, any data type
name ?
bugs
only gets data, doesn't slice yet
assumes the field is rectilinear.
The way multiple coordinate arrays are allocated is not pretty
passes only up to nine dimensions
(See /home/drw/idl/esrg/ncdf_get_1field.pro)
NCDF_GET_1FIELD[2]
[Previous Routine]
[Next Routine]
[List of Routines]
Get a variable and its metadata from a NetCDF file
Written 1 April 1993 by William Weibel, UCLA Atmospheric Sciences
Source code control Id %W% %G%
USEAGE: ncdf_get_1field, file, varname, z, name
arguments
file string containing the name of the NetCDF file
varname name of the variable to read (string)
z dependent field variable, any data type
name ?
bugs
only gets data, doesn't slice yet
assumes the field is rectilinear.
The way multiple coordinate arrays are allocated is not pretty
passes only up to nine dimensions
(See /home/drw/idl/old.esrg/ncdf_get_1field.pro)
NCDF_GET_FIELD[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: NCDF_GET_FIELD
Get a variable and its metadata from a NetCDF file.
Calling Sequence
ncdf_get_field, File, Varname, Z, Name, C0, C1, C2, ...
Arguments
File
A string containing the name of an existing NetCDF file.
Varname
A string containing the name of the variable you want to
read, or an integer corresponding to a NetCDF variable
identifier.
Z
An array output by ncdf_get_field containing the dependent
variable given in Varname. The procedure will determine the
data type and dimensions of the array from the information
in the NetCDF file.
Name
An array of strings containing names for the coordinate axes,
i.e. the names of the independent variables.
C0, C1, C2, ...
Arrays output by ncdf_get_field containing the coordinates,
i.e. independent variables, of the field.
Example
Suppose you have a file called stuff.cdf, and you know it contains
a four-dimensional scalar variable called 't'. You would read the
data this way.
IDL> ncdf_get_field, 'stuff.cdf', 't', t, titles, x, y, z, time
If you examine your IDL memory contents, you find the following
IDL>help,t
T FLOAT = Array(60, 60, 10, 3)
The data could be sliced and displayed like so
IDL>sst = t(*,*,0,2)
IDL>contour,sst,x,y,max_value=9000
Bugs
only gets entire field, doesn't slice yet
The way multiple coordinate arrays are allocated is not pretty
passes only up to nine dimensions
Has not been tested on irregular fields
Author
William Weibel, UCLA Atmospheric Sciences
Last Revision Date
1 April 1993
(See /home/drw/idl/esrg/ncdf_get_field.pro)
NCDF_GET_FIELD[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: NCDF_GET_FIELD
Get a variable and its metadata from a NetCDF file.
Calling Sequence
ncdf_get_field, File, Varname, Z, Name, C0, C1, C2, ...
Arguments
File
A string containing the name of an existing NetCDF file.
Varname
A string containing the name of the variable you want to
read, or an integer corresponding to a NetCDF variable
identifier.
Z
An array output by ncdf_get_field containing the dependent
variable given in Varname. The procedure will determine the
data type and dimensions of the array from the information
in the NetCDF file.
Name
An array of strings containing names for the coordinate axes,
i.e. the names of the independent variables.
C0, C1, C2, ...
Arrays output by ncdf_get_field containing the coordinates,
i.e. independent variables, of the field.
Example
Suppose you have a file called stuff.cdf, and you know it contains
a four-dimensional scalar variable called 't'. You would read the
data this way.
IDL> ncdf_get_field, 'stuff.cdf', 't', t, titles, x, y, z, time
If you examine your IDL memory contents, you find the following
IDL>help,t
T FLOAT = Array(60, 60, 10, 3)
The data could be sliced and displayed like so
IDL>sst = t(*,*,0,2)
IDL>contour,sst,x,y,max_value=9000
Bugs
only gets entire field, doesn't slice yet
The way multiple coordinate arrays are allocated is not pretty
passes only up to nine dimensions
Has not been tested on irregular fields
Author
William Weibel, UCLA Atmospheric Sciences
Last Revision Date
1 April 1993
(See /home/drw/idl/old.esrg/ncdf_get_field.pro)
NCDF_INFO[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: NCDF_INFO
PURPOSE: Summarize the information from a NetCDF file
USEAGE: NCDF_INFO, File
INPUT:
file A string containing the name of an existing NetCDF file.
KEYWORD_INPUT:
dir if set to one (an integer) the current directory is scanned
for any files with a .cdf suffix. If instead dir is set to
a directory name (a string) then that directory is scanned
for NetCDF files. The list of files is presented as a menu,
and information for a selected file is displayed. If
present, the command line argument, FILE, is set to the
selected file, and can be used in subsequent commands.
noless 0 view info file with less (default)
1 do not view info file with less
2 view info file with xless
short just print variable names and quit
Keyword OUTPUT:
names array of variable names
Example
; Review information for a specific netcdf file
ncdf_info,'stuff.cdf'
; Review information for one of many files in a directory
ncdf_info,file,/dir ; defines file on output
; Retrieve a list of variable names and use in a menu to retrieve values
ncdf_info,file,/dir,/no,na=n & ncdf_get_1field,file,n(wmenu(n)),z
Bugs:
Although this algorithm follows NetCDF conventions, it is inappropriate
for irregularly gridded data.
Author:
William Weibel, Department of Atmospheric Sciences, UCLA
Revisions:
may98:PJR correct do loop index range (WW forgot to start at 0)
may98:PJR return variable names to caller
apr98:PJR pipe info into less
apr93:WW Summarize the information from a NetCDF file
Bugs:
Although this algorithm follows NetCDF conventions, it is inappropriate
for irregularly gridded data.
(See /home/drw/idl/esrg/ncdf_info.pro)
NCDF_INFO[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: NCDF_INFO
PURPOSE: Summarize the information from a NetCDF file
USEAGE: NCDF_INFO, File
INPUT:
File
A string containing the name of an existing NetCDF file.
Example
If you have a file called "stuff.cdf", you can find out what variables
are inside it by entering:
IDL> ncdf_info,'stuff.cdf'
IDL will print the following:
Contents of stuff.cdf
Variables
Name: t, data type: FLOAT
long_name = Temperature
units = celsius
Dimensions:
longitude[60], latitude[60], depth[10], time[3]
Bugs:
Although this algorithm follows NetCDF conventions, it is inappropriate
for irregularly gridded data.
Author:
William Weibel, Department of Atmospheric Sciences, UCLA
Last Revision:
April, 1993;
Summarize the information from a NetCDF file
Bugs:
Although this algorithm follows NetCDF conventions, it is inappropriate
for irregularly gridded data.
(See /home/drw/idl/old.esrg/ncdf_info.pro)
NEWFILE
[Previous Routine]
[Next Routine]
[List of Routines]
Purpose:
Return an unused filename of the form "root??.extension", where ??
is an integer in the range 01-99.
Usage:
NAME = NEWFILE( ROOT )
Input:
ROOT String variable specifying the root of the filename.
Optional keywords:
EXTENSION String variable specifying the extension of the filename.
Revised:
19-OCT-1997 Liam Gumley, CIMSS/SSEC
Example:
NAME = NEWFILE( "output" )
PRINT, NAME
NAME = NEWFILE( "test", EXTENSION = "gif" )
PRINT, NAME
(See /home/drw/idl/aux/newfile.pro)
NEWLIGHT
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
newlight
(new EUV lightcurve)
PURPOSE:
A rountine to make an TOTAL (over all chosen pixels) lightcurve for
1024x1024 EUV images.
CALLING SEQUENCE:
newlight, data, curve, background, expo
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
NEWLIGHT.PRO, a version based on a *total*
value summed over all pixels
which are >(quiet-mean+)2*standard-deviation)
(See /home/drw/idl/bin/newlight.pro)
NEWLIGHT2
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
newlight2
(new UV lightcurve)
PURPOSE:
A rountine to make an TOTAL (over all chosen pixels) lightcurve for
1024x1024 EUV images.
CALLING SEQUENCE:
newlight2, data, curve, background, expo
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
NEWLIGHT2.PRO, a version based on a *total*
value summed over all pixels
which are >(quiet-mean+)2*standard-deviation)
(See /home/drw/idl/bin/newlight2.pro)
NEWLIGHT2B
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
newlight2b
(new UV lightcurve)
PURPOSE:
A rountine to make an TOTAL (over all chosen pixels) lightcurve for
1024x1024 EUV images.
CALLING SEQUENCE:
newlight2, data, curve, background, expo
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
NEWLIGHT2.PRO, a version based on a *total*
value summed over all pixels
which are >=((quiet-mean)+standard-deviation)
(See /home/drw/idl/bin/newlight2b.pro)
NEWLIGHTB
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
newlightb
(new EUV lightcurve)
PURPOSE:
A rountine to make an TOTAL (over all chosen pixels) lightcurve for
1024x1024 EUV images.
CALLING SEQUENCE:
newlight, data, curve, background, expo
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
NEWLIGHT.PRO, a version based on a *total*
value summed over all pixels
which are >((quiet-mean)+standard-deviation)
(See /home/drw/idl/bin/newlightb.pro)
NEWLIGHTS
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
newlights
(new EUV lightcurve special - for zoomed EUV)
PURPOSE:
A rountine to make an TOTAL (over all chosen pixels) lightcurve for
1024x1024 EUV images.
CALLING SEQUENCE:
newlight, data, curve, background, expo
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
NEWLIGHT.PRO, a version based on a *total*
value summed over all pixels
which are >(quiet-mean+)2*standard-deviation)
(See /home/drw/idl/bin/newlights.pro)
NEW_MOVIE
[Previous Routine]
[Next Routine]
[List of Routines]
PRO new_movie,data
Data = FLTARR(504,504,100)
FOR i = 1, 63, 1 DO BEGIN
PRINT,i
IF (i LE 9) THEN a = READFITS('narrowband/narrowb0'+ARR2STR(i,/Trim)+'00.fit')
IF ((i GT 9) AND (i LE 64)) THEN a = READFITS('narrowband/narrowb'+ARR2STR(i,/Trim)+'00.fit')
Data(*,*,i) = a
ENDFOR
END
(See /home/drw/idl/secis/new_movie.pro)
NEXTTOK
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
NEXTTOK
PURPOSE:
Find the next occurance of any of a set of characters in a
string and return the character which occurs next.
CATEGORY:
text/strings
CALLING SEQUENCE:
tok = nexttok( strn, tokens )
INPUTS:
strn -- string to be searched for sub/superscripts in
tokens -- string containing characters to be found. in
KEYWORD PARAMETERS:
POSITION -- Set to a named variable to get position out
of next token, or -1 if none found.
/HELP -- Print useful message and exit.
OUTPUTS:
tok -- Contains the character among tokens which out
occurs next in strn, or null '' if none found.
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
EXAMPLE:
nexttok( 'x^2 + N_j^3', '^_', position=pos ) returns '^' and sets
pos to 1.
MODIFICATION HISTORY:
$Id: nexttok.pro,v 1.3 1996/06/14 20:00:27 mcraig Exp $
$Log: nexttok.pro,v $
Revision 1.3 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.2 1996/05/09 00:22:17 mcraig
Generalized so that the next occurence of any of a set of characters will
be returned.
Revision 1.1 1996/01/31 18:41:06 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/nexttok.pro)
NIUEG2
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: NIUEG2
Modified 7/5/88 from IUELOW to be called by NIUELO
now passes gross and background vectors ala NIUELO
PURPOSE:
procedure for getting final output from SDPS' MELO array
(analogous to iuelo.pro)
CATEGORY:
CALLING SEQUENCE:
INPUTS:
MELO - melo array
OUTPUTS:
H,WAVE, FLUX, EPS arrays
where FLUX = net flux if exp_time is not given
= absolute flux if exp_time is given
OPTIONAL OUTPUT PARAMETERS:
COMMON BLOCKS:
SIDE EFFECTS:
RESTRICTIONS:
PROCEDURE:
MODIFICATION HISTORY:
VERSION 1 by Sally Heap, August 1987
2 SEP 1987 - put in LWR degradation correction
VERSION 3 by jkf/acc - renamed IUELOW...originally FROMMELO and removed
calibration.
(See /home/drw/idl/icur/niueg2.pro)
NIUEGET
[Previous Routine]
[Next Routine]
[List of Routines]
***** NIUEGET
*NAME:
IUEGET 8 JANUARY 1981
*PURPOSE:
To acquire spectral data for a given order
from an IUE diskfile
*EXECUTION:
IUEGET,LUN,M,H,WAVE,FNET,EPS
*INPUT:
LUN - logical unit of opened file (MEHI or
MELO) containing IUE spectral data
M - spectral order for which data are to
be acquired (1 for low-dispersion spectra,
60-125 for high-dispersion spectra)
*OUTPUT:
H - header record
WAVE - vector of wavelengths
FNET - vector of net fluxes (GROSS-smoothed
BACKGROUND) in IUE units
EPS - error vector
*DISK DATA SETS:
The disk data file containing the IUE spectrum
must be opened for reading before execution of
IUEGET and closed after execution.
*METHOD:
The header record is acquired and examined
to determine which records contain the data for
the specified spectral order. The wavelength,
gross-flux, background-flux, and error vectors
are then acquired. The wavelength vector is
converted to angstroms, while the fluxes are
converted to IUE units. The background is first
smoothed by a median filter followed by two
running averages. The net flux is determined
as the difference between the gross flux
and the smoothed background flux. All the
vectors are stripped of padded zeros.
*OPERATIONAL NOTES:
Care should be taken when using this routine. IUEGET
uses the system variable !ERR to determine the record
length in the data file. !ERR is set when the file is
first opened. If the user does anything to change
!ERR before calling IUEGET (eg. any input/output from
tape or disk), the value of !ERR should be restored.
Example:
OPENR,1,'S6541L'
SAVE=!ERR
... other work that might change !ERR
!ERR=SAVE
IUEGET,1,1,H,WAVE,FNET,EPS
*EXAMPLES;
In this example, spectral data for orders
93 and 94 of the high-dispersion spectrum,
SWP 3323, are acquired and plotted:
OPENR,1,'IUER_USERDATA:S3323H'
IUEGET,1,93,H,W93,NET93,E93
IUEGET,1,94,H.W94,NET94,E94
CLOSE,1
!XMIN=W94(0) & !XMAX=MAX(W93)
PLOT,W94,F94
OPLOT,W93,F93
*SUBROUTINES CALLED:
GMEDIAN
PARCHECK
*MODIFICATION HISTORY:
VERSION 1 BY SALLY HEAP 2-16-81
22-OCT-85 KF modified for DIDL (i.e. /ERROR added & change
MEDIAN to GMEDIAN
19-NOV-85 RWT use intrinsic DIDL MEDIAN instead of GMEDIAN
4-13-87 RWT VAX mods: use GMEDIAN, add PARCHECK & remove EXTRACT commands
(See /home/drw/idl/icur/niueget.pro)
NIUELO
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
NIUELO 8 JANUARY 1981
mod of IUELO for ICUR I/O
*PURPOSE:
To acquire and calibrate low dispersion spectral
data from IUE with optional corrections for THDA
sensitivity variation and LWR sensitivity variation.
*EXECUTION:
IUELO,IMAGET,H,WAVE,FLUX,EPS
*INPUT:
IMAGET - disk file name for eslo or melo file
containing low-dispersion spectral data
(character string)
e.g. MELO file for IMAGET
SWP 7954 'SWP7954L'
LWR 9422 'LWR9422L'
*OUTPUT:
H - header record amended for exposure
time input by user, and flags for THDA
and LWR degradation corrections.
WAVE - wavelength vector (Angstroms)
FLUX - absolute flux vector (ergs/sec/cm2/A)
EPS - error vector
*INTERACTIVE INPUT:
1) Exposure time (in minutes,sec,ms), if the header
record does not already contain these quantities.
If the user types in zeros, then the net flux
in IUE units is returned. Values may be integer or real
but the total time must be less than 32767 minutes.
2) Correction for THDA sensitivity variation, if entry 68
in the header record equals 0 (see description below).
3) Correction for LWR sensitivity degradation, if entry 69
in the header records equals 0 (see description below).
*OUTPUT PLOTS:
wavelength vs net flux
wavelength vs. absolute flux
In both plots, those data-points with negative values of
epsilon are marked with asterisks.
*DISK DATA SETS:
1) The MELO (eslo) data file must be resident on
disk.
2) the files, 'IUER_PRODROOT:[DAT]IUECAL.DAT' and IUECAL2.DAT,
containing the calibration tables used to convert
fluxes from IUE units to absolute units, must be
available for CALIB. See IUER_PRODROOT:[INF]IUECAL.INF and
IUECAL2.INF for more documentation.
3) If the THDA correction is requested with a user-specified
THDA value, the label portion of the MELO file must be
resident on the system disk.
4) If the LWR sensitivity degradation correction is requested,
the file IUER_PRODROOT:[DAT]DEGRAD.TAB must exist. (See
documentation in IUER_PRODROOT:[INF]DEGRAD.INF.)
*OPERATIONAL NOTES:
- HFIX can be run prior to IUELO to set all the flags in
record 0 necessary to allow IUELO to run non-interactively.
- CALIB, which is called by IUELO requires that H(580) contains
the number of the ITF file used by IUESIPS. This is set either
with the new IUECOPY, or using ITFFLAG.
- Specifying 0 for the exposure time will result in net fluxes
being output rather than absolutely calibrated fluxes.
*METHOD:
IUEGET is used to acquire the header record
and the wavelength, net flux, and error
vectors. The header record is then examined
to see if the exposure time was recorded (i.e.
non-zero)
H(39) - minutes
H(40) - seconds
H(41) - ms
If the exposure time is not recorded, then
the user is asked to supply the exposure time
(in min, sec, ms) and these data are inserted
into the header record. Note that the user may
enter these values as either integer or real
numbers although real values for ms will be
truncated. The net fluxes are then converted
to absolute units with the use of IUECAL or IUECAL2
by CALIB (if the exposure time is not zero). CALIB
uses H(580) to decide which file is opened (see ITFFLAG).
If H(68) = 0, the user is asked if a correction for
THDA sensitivity variations is desired. The possible
options include no correction, correction using the
IUESIPS determined THDA stored in H(61), or correction
using a user-specified THDA with the temperature data
stored in the label displayed to assist the user.
If H(68) < 0, then the correction will be applied
automatically using -H(68) / 10.0 for the THDA.
If H(68) > 0, then the correction is not applied
and no user input is required. Note that the default
value for H(68) is 0.
If an LWR image is specified, and H(69) = 0, the user
is asked if a correction for the LWR sensitivity
degradation is desired. If H(69) < 0, then the
correction is applied automatically. If H(69) > 0,
then the correction is not applied and no user input
is required. Note the default for H(69) is 0.
*EXAMPLES:
spectral data for SWP 3373 are acquired via the command:
IUELO,'SWP3373L',HEAD,WAVE,ABSFLUX,EPS
*SUBROUTINES CALLED:
IUEPLOT
CALIB
SDC
TEMPCOR
LTI
INTIME
IUEGET
LABEL
*MODIFICATION HISTORY:
VERSION 1 BY SALLY HEAP 13-FEB-81
- June 11, 1981 change by Sally Heap per change
request #18. Uses COMPOSE before trying to open
files, and prints out the first 9 lines of the
label before it asks for the exposure time.
- July 20, 1981 by D. Lindler per change request # 73.
Corrected to work when the exposure time is already in
the header record.
- May 30, 1984 by RWT per URP #177. Corrected to allow either
integer or real exposure times.
- December 13, 1984 RWT use new versions of IUEPLOT & CALIB.
- 4-28-86 RWT includes LWR sensitivity degradation correction
(SDC & new CALIB), a correction for temperature-dependent
sensitivity variations (TEMPCOR), corrects problem with
exposure time error, and uses new DIDL IUEGET
- 8-27-86 RWT allow exp. times > 32767 sec or >32767 millisec.
using new subroutine INTIME
- 8-12-87 RWT VAX mods: eliminate subroutines, add PARCHECK,
add listing of procedure call, change UIC references, add
pause before plot, use vector subscript notation in
print statements and use GET_LUN & SET_XY.
- 12-31-87 RWT use label information rather than file name for
error checking and modify for new LWP absolute calibration
(See /home/drw/idl/icur/niuelo.pro)
NN_CLUST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: nn_clust.pro
PURPOSE: tag events with cluster #
CATEGORY: data processing - cluster analysis
CALLING SEQUENCE: result = NN_CLUST(data,weights,[N_PARAM=n_param],
[N_EVENT=n_event],[N_CLUST=n_clust])
INPUTS: data = data set to be clustered, weights = array of weights which
describe cluster centers (produced by the function NN_LEARN)
OPTIONAL INPUT PARAMETERS:
n_param = # of parameters in data set - 1st dimension of data set
n_event = # of events in data set - 2nd dimension of the data set
n_clust = # of clusters to find - arbitrary
KEYWORD PARAMETERS: none
OUTPUTS: result = integer array of cluster assignment of each event
OPTIONAL OUTPUT PARAMETERS: none
COMMON BLOCKS: none
SIDE EFFECTS: none (?)
RESTRICTIONS: Read the header of 'nn_learn.pro'.
PROCEDURE: The data set is processed against the weights array and a cluster
# assignment is made for each event in the input data set based
on the weights array which describe the center of each cluster.
MODIFICATION HISTORY: initial algorithm: Mark Naiver (Univ of Texas - Austin)
Date last modified ==> 1 March 93 : RCH [LANL]
Contact: Robb Habbersett (505/667-0296 or robb@big-geek.lanl.gov)
(See /home/drw/idl/esrg/nn_clust.pro)
NN_LEARN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: nn_learn.pro
PURPOSE: Learning step to cluster data using neural network techniques.
CATEGORY: Data processing - cluster analysis
CALLING SEQUENCE: weights = nn_learn(data,max_val,[BLR=blr],[ELR=elr],
[N_EVENT=n_event],[N_PASS=n_pass],[N_PARAM=n_param],[N_CLUST=n_clust]
INPUTS: data = data set to be clustered, max_val = maximum range of each
parameter in the data set (to normalize the weights).
OPTIONAL INPUT PARAMETERS:
blr = begining learning rate, elr = ending learning rate
n_pass = # of iterations of the learning pass
n_param = # of parameters in data set - 1st dimension of data set
n_event = # of events in learning set - 2nd dimension of data set
n_clust = # of clusters to find - arbitrary (?)
KEYWORD PARAMETERS: none
OUTPUTS: result = an array of weights describing the cluster centers.
OPTIONAL OUTPUT PARAMETERS: none
COMMON BLOCKS: none
SIDE EFFECTS: This approach has an inherent weakness in that it must be
set to find a specific number of clusters; It will find
that number of clusters in the data set - regardless.
RESTRICTIONS: This routine has not been rigorously tested on different types
of data. It "appears" to work on flow cytometry data.
PROCEDURE: A limited subset of a larger data set is presented to this
routine as a training set to condition the neural network. The
result is a set of weights which describe the centers of the
resolved clusters.
MODIFICATION HISTORY: Initial algorithm: Mark Naiver (Univ of Texas - Austin)
Date last modified ==> 1 March 93 : RCH [LANL]
Contact: Robb Habbersett (505/667-0296 or robb@big-geek.lanl.gov)
(See /home/drw/idl/esrg/nn_learn.pro)
NODATA
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: nodata
PURPOSE: mark grid points that have nodata value
USEAGE: nodata,arr,bval,nx,ny,color=color,psym=psym,thick=thick, &
symsize=symsize
INPUT:
arr 2-d array
bval points in arr less than or equal to bval are flagged as nodata
points.
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 22 Mar 00
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/nodata.pro)
NORMALIZE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
NORMALIZE
PURPOSE:
This is a utility routine to calculate the scaling vector
required to position a graphics primitive of specified range
at a specific position in an arbitray coordinate system. The
scaling vector is given as a two-element array like this:
scalingVector = [translationFactor, scalingFactor]
The scaling vector should be used with the [XYZ]COORD_CONV
keywords of a graphics object or model. For example, if you
wanted to scale an X axis into the coordinate range of -0.5 to 0.5,
you might type something like this:
xAxis->GetProperty, Range=xRange
xScale = Normalize(xRange, Position=[-0.5, 0.5])
xAxis, XCoord_Conv=xScale
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:
Object Graphics
CALLING SEQUENCE:
xscaling = NORMALIZE(xrange, POSITION=position)
INPUTS:
XRANGE: A two-element vector specifying the data range.
KEYWORD PARAMETERS:
POSITION: A two-element vector specifying the location
in the coordinate system you are scaling into. The vector [0,1]
is used by default if POSITION is not specified.
COMMON BLOCKS:
None.
EXAMPLE:
See above.
MODIFICATION HISTORY:
Written by: David Fanning, OCT 1997.
(See /home/drw/idl/aux/normalize.pro)
NOT_SET[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
NOT_SET
otherwise known as 'set...NOT!' thanks to Paul Ricchiazzi
PURPOSE:
Return the values of array2 that are not in array1. If array2
not defined, use lindgen(max(array1+1))
CATEGORY:
Array manipulation.
CALLING SEQUENCE:
array3 = not_set(array1, array2)
INPUTS:
array1
OPTIONAL INPUTS:
array2 See PURPOSE.
maxarr If array2 not defined, use this length rather
than max(array1+1))
OUTPUTS:
See PURPOSE.
EXAMPLE:
x = [0,2,3,4,6,7,9]
y = [3,6,10,12,20]
print,intersect(x,y)
3 6
print,intersect(x,y,/xor_flag)
0 2 4 7 9 10 12 20
print,not_set(x,y)
0 2 4 7 9
print,not_set(x)
1 5 8
print,not_set(x,maxarr=15)
1 5 8 10 11 12
13 14
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/03/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/not_set.pro)
NOT_SET[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
NOT_SET
otherwise known as 'set...NOT!' thanks to Paul Ricchiazzi
PURPOSE:
Return the values of array2 that are not in array1. If array2
not defined, use lindgen(max(array1+1))
CATEGORY:
Array manipulation.
CALLING SEQUENCE:
array3 = not_set(array1, array2)
INPUTS:
array1
OPTIONAL INPUTS:
array2 See PURPOSE.
maxarr If array2 not defined, use this length rather
than max(array1+1))
OUTPUTS:
See PURPOSE.
EXAMPLE:
x = [0,2,3,4,6,7,9]
y = [3,6,10,12,20]
print,intersect(x,y)
3 6
print,intersect(x,y,/xor_flag)
0 2 4 7 9 10 12 20
print,not_set(x,y)
0 2 4 7 9
print,not_set(x)
1 5 8
print,not_set(x,maxarr=15)
1 5 8 10 11 12
13 14
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/03/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/not_set.pro)
NUMFORM
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: numform
PURPOSE:
USEAGE: xlab=numform(x)
INPUT:
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 18 Nov 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/numform.pro)
NUM_EXT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
NUM_EXT
PURPOSE:
Return the number of extensions in a FITS file.
CALLING SEQUENCE:
extensions=NUM_EXT(FILE)
INPUT PARAMETERS:
FILE = FITS file name, scalar string
RETURNS:
Unit number of file or -1 if an error is detected.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Opens closes the file.
PROCEDURE:
Each FITS header is read in and parsed, and the file pointer is moved
to where the next FITS extension header until each
extension is reached.
PROCEDURE CALLS:
FXPAR(), MRD_HREAD, MRD_SKIP
MODIFICATION HISTORY:
Originally FXPOSIT in ASTRON library
Derived from William Thompson's FXFINDEND routine.
Modified by T.McGlynn, 5-October-1994.
Modified by T.McGlynn, 25-Feb-1995 to handle compressed
files. Pipes cannot be accessed using FXHREAD so
MRD_HREAD was written.
W. Landsman 23-Apr-1997 Force the /bin/sh shell when uncompressing
W. Landsman 26-May-1997 Non-unix is not just VMS
D. Sahnow 3 November 1998 Changed to NUMEXT to just count the number
of extensions.
D. Sahnow 15 November 1998 Renamed to NUM_EXT to avoid conflict with
a variable in FUSEFITS.PRO
D. Sahnow 18 November 1998 Added a few print statements for cases
when -1 is returned.
NOTE: should first check for the NEXTEND keyword, which may have the number
of extensions directly.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/num_ext.pro)
NUPLOT_MAP[1]
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO_CDS
Name : NUPLOT_MAP !!!! A TWEAKED VERSION TO ADD CONTOUR ANNOTATION AND CHARACTER SIZE CONTROL
Purpose : Plot an image map
Category : imaging
Syntax : plot_map,map
Inputs : MAP = image structure map created by MAKE_MAP
INDEX = optional index (if array of maps) [def=0]
Keywords :
ALAB = vector of contour labels (strings)
CSIZE = !p.charsize for the plotting of the map (title, labels, etc.)
/OVERLAY = overlay on previous image
/CONT = contour the image
SMOOTH_WIDTH = smoothing width (> 1)
FOV = [fx,fy] = field of view to be plotted
GRID = grid spacing (deg) for latitude-longitude grid [def= 0, no grid]
GLABEL = label grid with coordinate values [def = 0, no labels]
GSTYLE = grid linestyle [def=0]
CENTER = [xc,yc] = center coordinates (arcsec) of FOV [def = center of image]
(if center is a valid map, then use its center)
DMIN,DMAX = min, max data for plot [def = data min,max]
BORDER = draw border around image [def = no]
/TAIL = allows user to tailor contours
/LOG = log_10 scale image
WINDOW = window index to send plot to
/NOAXES = inhibit plotting axes
/NOTITLE = inhibit printing title
/NOLABELS = inhibit axis labels
/NOXTICKS = inhibit X-tick labels
/NOYTICKS = inhibit Y-tick labels
/DROTATE = solar rotate image contour
LEVELS = user specified contour levels
/POSITIVE_ONLY = plot positive data
/NEGATIVE_ONLY = plot negative data
XRANGE,YRANGE = cartesian plot limits
/INTERLACE = interlace two images when overlaying
/COMPOSITE = simultaneously plot two images when overlaying
= type of compositing:
1: original , 2: latest(new), 3: max(new/old) 4: min(new/old)
/AVERAGE = average two images when using /COMPOSITE
BOTTOM = lowermost color index to use in color scaling [def=0]
LAST_SCALE = use MIN/MAX from previous plot, or if LAST is a valid map
use scaling from it
LIMB = overplot solar limb
ROLL = roll image contour
BTHICK = border thickness
CTHICK = contour thickness
LCOLOR = contour line color
ACOLOR = axes color (removed)
MULTI = set for multiple plots per page, e.g. mult=[2,2] (or 2) for 4
plots per page (!p.multi remains at this value until cleared)
NOERASE = don't erase previous plot
SQUARE = force equal aspect ratio (by adjusting position)
CLABEL = label contours
CSTYLE = contour linestyle
MARGIN = margin around plot [normalized coords, used only if /SQUARE]
/SURFACE = show the image as a wire surface
/SHADE_SURF = show the image as a shaded surface
AX_SURF = Angle of rotation about X axis for surface (degrees)
AZ_SURF = Angle of rotation about Z axis for surface (degrees)
ERR_MSG = String error message if any
STATUS = 0/1 means failure/success
CBAR = 0/1 means draw colorbar on image plots (only works in > IDL 5.2)
CCHARSIZE = size of characters used for contour level labels. (if not set, but charsize is
passed in extra, then c_charsize is .75 * charsize. Otherwise 0.)
PERCENT = if levels are entered, they are in % of data max
Restrictions:
- do not set /GRID unless absolute coordinates of image are known
- do not set /OVERLAY unless a plot exists on the current device
History : Written 22 December 1996, D. Zarro, SAC/GSFC
: S.L.Freeland - let COMPOSITE have different interpretations
: Major modifications 15 Feb 1999, Zarro (SM&A/GSFC)
-- reorganized
-- sped-up sub-field extraction
-- fixed potential bug in contour levels scaling
-- fixed potential bug in image color scaling
-- fixed roll correction
: Zarro (SM&A/GSFC) 28 April 1999
-- fixed roll_center interpretation
(heaven help me for onlining this during Gopal's CDAW)
: Zarro (SM&A/GSFC) 3 May 1999
-- allowed overlaying images with different roll centers.
: Zarro (SM&A/GSFC) 5 Aug 1999
-- Made VIEW_ADJUST=1 the default
: Zarro (SM&A/GSFC) 25 Sep 1999
-- Made VIEW_ADJUST=0 the default
: Zarro (SM&A/GSFC) 1 Nov 1999
-- Added GSTYLE grid style keyword
: Zarro (SM&A/GSFC) 30 Nov 1999
-- Added OVERLAY=2 hidden feature
: Zarro (SM&A/GSFC) 14 Feb 2000
-- changed CONT keyword to CONTOUR, and added /EXTEND
: Zarro (SM&A/GSFC) 27 Mar 2000
-- changed CLABEL, removed old keywords
: Zarro (SM&A/GSFC) 7 Apr 2000
-- fixed roundoff errors causing edge pixels
to spill over during hardcopying. Also improved smoothing.
: Zarro (SM&A/GSFC) 25 Apr 2000
-- fixed problem with image viewport falling outside plot
limits; removed EXTENDS, VIEW_ADJUST keywords
: Zarro (EIT/GSFC) 10 May 2000, added optional INDEX argument
: Zarro (EIT/GSFC) 28 June 2000, added MARGIN keyword and call
to GET_ASPECT
: Kim 27 Sep 2000 - added surface and shade_surface options
: Kim 29 Sep 2000 - removed some keywords to stay under 64 argument limit
in versions < 5.3. Handle new keywords in _extra
: Kim 1 Oct 2000 - added show3 option
: Kim 4 Oct 2000 - added status keyword. err keyword became err_msg.
: Zarro (EIT/GSFC): 6 Oct 2000 -- restored capability to overlay
images without using contours.
13 Oct 2000 -- added rescale zoom logic
: Kim 9 Jan 2001 - added colorbar option (for > IDL V 5.2) and ccharsize keyword
: Khan (MSSL/ISAS): 2001 Mar 30 -- Changed Kim's colorbar to cbar to avoid conflict with color keyword
: Zarro (EITI/GSFC): 2001 Jun 18 -- Fixed Z-buffer bug
: Zarro (EITI/GSFC): 2001 Sept 1 -- added /PERCENT
: Kim: 2001 Sep 6 - don't draw limb for surface, shade_surf, or show3
Contact : dzarro@solar.stanford.edu
(See /home/drw/idl/vtt/post_bbso/nuplot_map.pro)
NUPLOT_MAP[2]
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO_CDS
Name : NUPLOT_MAP !!!! A TWEAKED VERSION TO ADD CONTOUR ANNOTATION AND CHARACTER SIZE CONTROL
Purpose : Plot an image map
Category : imaging
Syntax : plot_map,map
Inputs : MAP = image structure map created by MAKE_MAP
INDEX = optional index (if array of maps) [def=0]
Keywords :
ALAB = vector of contour labels (strings)
CSIZE = !p.charsize for the plotting of the map (title, labels, etc.)
/OVERLAY = overlay on previous image
/CONT = contour the image
SMOOTH_WIDTH = smoothing width (> 1)
FOV = [fx,fy] = field of view to be plotted
GRID = grid spacing (deg) for latitude-longitude grid [def= 0, no grid]
GLABEL = label grid with coordinate values [def = 0, no labels]
GSTYLE = grid linestyle [def=0]
CENTER = [xc,yc] = center coordinates (arcsec) of FOV [def = center of image]
(if center is a valid map, then use its center)
DMIN,DMAX = min, max data for plot [def = data min,max]
BORDER = draw border around image [def = no]
/TAIL = allows user to tailor contours
/LOG = log_10 scale image
WINDOW = window index to send plot to
/NOAXES = inhibit plotting axes
/NOTITLE = inhibit printing title
/NOLABELS = inhibit axis labels
/NOXTICKS = inhibit X-tick labels
/NOYTICKS = inhibit Y-tick labels
/DROTATE = solar rotate image contour
LEVELS = user specified contour levels
/POSITIVE_ONLY = plot positive data
/NEGATIVE_ONLY = plot negative data
XRANGE,YRANGE = cartesian plot limits
/INTERLACE = interlace two images when overlaying
/COMPOSITE = simultaneously plot two images when overlaying
= type of compositing:
1: original , 2: latest(new), 3: max(new/old) 4: min(new/old)
/AVERAGE = average two images when using /COMPOSITE
BOTTOM = lowermost color index to use in color scaling [def=0]
LAST_SCALE = use MIN/MAX from previous plot, or if LAST is a valid map
use scaling from it
LIMB = overplot solar limb
ROLL = roll image contour
BTHICK = border thickness
CTHICK = contour thickness
LCOLOR = contour line color
ACOLOR = axes color (removed)
MULTI = set for multiple plots per page, e.g. mult=[2,2] (or 2) for 4
plots per page (!p.multi remains at this value until cleared)
NOERASE = don't erase previous plot
SQUARE = force equal aspect ratio (by adjusting position)
CLABEL = label contours
CSTYLE = contour linestyle
MARGIN = margin around plot [normalized coords, used only if /SQUARE]
/SURFACE = show the image as a wire surface
/SHADE_SURF = show the image as a shaded surface
AX_SURF = Angle of rotation about X axis for surface (degrees)
AZ_SURF = Angle of rotation about Z axis for surface (degrees)
ERR_MSG = String error message if any
STATUS = 0/1 means failure/success
CBAR = 0/1 means draw colorbar on image plots (only works in > IDL 5.2)
CCHARSIZE = size of characters used for contour level labels. (if not set, but charsize is
passed in extra, then c_charsize is .75 * charsize. Otherwise 0.)
PERCENT = if levels are entered, they are in % of data max
Restrictions:
- do not set /GRID unless absolute coordinates of image are known
- do not set /OVERLAY unless a plot exists on the current device
History : Written 22 December 1996, D. Zarro, SAC/GSFC
: S.L.Freeland - let COMPOSITE have different interpretations
: Major modifications 15 Feb 1999, Zarro (SM&A/GSFC)
-- reorganized
-- sped-up sub-field extraction
-- fixed potential bug in contour levels scaling
-- fixed potential bug in image color scaling
-- fixed roll correction
: Zarro (SM&A/GSFC) 28 April 1999
-- fixed roll_center interpretation
(heaven help me for onlining this during Gopal's CDAW)
: Zarro (SM&A/GSFC) 3 May 1999
-- allowed overlaying images with different roll centers.
: Zarro (SM&A/GSFC) 5 Aug 1999
-- Made VIEW_ADJUST=1 the default
: Zarro (SM&A/GSFC) 25 Sep 1999
-- Made VIEW_ADJUST=0 the default
: Zarro (SM&A/GSFC) 1 Nov 1999
-- Added GSTYLE grid style keyword
: Zarro (SM&A/GSFC) 30 Nov 1999
-- Added OVERLAY=2 hidden feature
: Zarro (SM&A/GSFC) 14 Feb 2000
-- changed CONT keyword to CONTOUR, and added /EXTEND
: Zarro (SM&A/GSFC) 27 Mar 2000
-- changed CLABEL, removed old keywords
: Zarro (SM&A/GSFC) 7 Apr 2000
-- fixed roundoff errors causing edge pixels
to spill over during hardcopying. Also improved smoothing.
: Zarro (SM&A/GSFC) 25 Apr 2000
-- fixed problem with image viewport falling outside plot
limits; removed EXTENDS, VIEW_ADJUST keywords
: Zarro (EIT/GSFC) 10 May 2000, added optional INDEX argument
: Zarro (EIT/GSFC) 28 June 2000, added MARGIN keyword and call
to GET_ASPECT
: Kim 27 Sep 2000 - added surface and shade_surface options
: Kim 29 Sep 2000 - removed some keywords to stay under 64 argument limit
in versions < 5.3. Handle new keywords in _extra
: Kim 1 Oct 2000 - added show3 option
: Kim 4 Oct 2000 - added status keyword. err keyword became err_msg.
: Zarro (EIT/GSFC): 6 Oct 2000 -- restored capability to overlay
images without using contours.
13 Oct 2000 -- added rescale zoom logic
: Kim 9 Jan 2001 - added colorbar option (for > IDL V 5.2) and ccharsize keyword
: Khan (MSSL/ISAS): 2001 Mar 30 -- Changed Kim's colorbar to cbar to avoid conflict with color keyword
: Zarro (EITI/GSFC): 2001 Jun 18 -- Fixed Z-buffer bug
: Zarro (EITI/GSFC): 2001 Sept 1 -- added /PERCENT
: Kim: 2001 Sep 6 - don't draw limb for surface, shade_surf, or show3
Contact : dzarro@solar.stanford.edu
(See /home/drw/idl/aux/nuplot_map.pro)
NUTPLOT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
NUTPLOT
PURPOSE:
Plot X vs Y with Universal time labels on bottom X axis.
CALLING SEQUENCE:
NUTPLOT,X,Y,BASE_TIME( or Utstring or Xst0), $
TIMERANGE=TIMERANGE, LABELPAR=LBL, /SAV,TICK_UNIT=TICK_UNIT,NTICKS=NTICKS, $
MINORS=MINORS, /NOLABEL, ERROR=ERROR,$
[& ALL KEYWORDS AVAILABLE TO PLOT]
NUTPLOT, roadmap, y
nutplot, x, y, '1-sep-91'
nutplot, x, y, '1-sep-91', timerange=['1-sep-91', '2-sep-92']
nutplot, x, y, '1-sep-91', timerange=[index(0), index(i)], xstyle=1
INPUTS:
X - X array to plot in seconds relative to base time.
(MDM) Structures allowed. X axis
range can be as small as 5 msec or as large as 20 years.
Y - Y array to plot.
Base_time (optional)- reference time, it's purpose is as a fiducial
time to preserve the precision of the graphics, that is
the range over which a plot is drawn must not be too small
with respect to the absolute size of the start of the plot or
roundoff errors will create strange effects. In previous
versions of Utplot, Base_time was called Utstring or Xst which
are explained below:
UTSTRING -
(Optional) ASCII string containing base time for X axis.
Format for time is YY/MM/DD,HHMM:SS.XXX. If this parameter
isn't present and hasn't been set yet (by a previous call to
UTPLOT, via routine SETUTBASE, or directly), user is
prompted for base time.
xst0 -
Optional. The reference time to use for converting a structure
into a seconds array (OR) the time for the first value if
passing a double prec. array.
TIMERANGE - Optional. This can be a two element time range to be
plotted. It can be a string representation or structure.
LBL - (Labelpar=LBL) 2 element vector selecting substring from publication format
of ASCII time (YY/MM/DD, HH:MM:SS.XXX). For example,
LBL=[11,18] would select the HH:MM:SS part of the string.
SAV - If set, UTPLOT labels, tick positions, etc. in !X... system
variables will remain set so that they can be used by
subsequent plots (normally !x... structure is saved in
temporary location before plot and restored after plot).
To clear !x... structure, call CLEAR_UTPLOT.
TICK_UNIT - Time (in seconds) between Major tick marks is forced to TICK_UNIT
Has no effect for axis longer than 62 days.
If TICK_UNIT is negative, then a standard value for TICK_UNIT is used
that is closest to abs(TICK_UNIT). Returned as new value.
NTICKS - Previously unused in utplot. The default tick_unit is adjusted such
that the number of intervals is as close to NTICKS as possible. If two
values are consistent, the longer interval (smaller value) is used.
MINORS - Number of minor tick marks is forced to MINORS
NOLABEL If set then UTLABEL isn't printed on plot
XTITLE - text string for x-axis label - If the string contains
4 asterisks ('****'), the UT time will be substituted
for that substring
Year - Force the year to appear in the x axis labels
YOHKOH - Use Yohkoh style labels, e.g. '03-May-93 18:11:30.732'
OPTIONAL OUTPUT PARAMETERS:
ERROR - 0/1. 1 means there was an error in plotting.
COMMON BLOCKS:
COMMON UTCOMMON, UTBASE, UTSTART, UTEND, xst = base, start, and
end time for X axis in double precision variables containing
seconds since 79/1/1, 00:00. xst is the fully referenced start
time of the plot.
COMMON UTSTART_TIME, PRINT_START_TIME = 0/1 ( don't/do print
start time label on plot), ATIME_FORMAT ('YOHKOH' or 'HXRBS')
SIDE EFFECTS:
X vs Y plot is produced on current graphics device. The normal
X-axis is replaced by an axis with ticks and labels showing the
universal time. The start time of the plot is displayed in the
upper right inside corner of the plot if SET_UTLABEL,0 hasn't been
called.
RESTRICTIONS:
Cannot be used for times before 1-JAN-1950 or after 31-DEC-2049
Range of X axis can be anywhere between 5 msec and 20 years.
Keywords DATA, DEVICE, NORMAL are not available
The utbase time is only set if either base_time
is passed or required as input.
PROCEDURE:
If start or end time hasn't been set, autoscale X axis.
If either has been set (via routines SETUTSTART and SETUTEND,
or directly), only data between times selected will be displayed;
i.e. X min = UTSTART - UTBASE; X max = UTEND - UTBASE.
Calls SET_UTPLOT using keyword LABELPAR to customize X
axis labels and tickmarks. Otherwise it uses all normal plotting
procedures and the !X and !Y system variables.
Note: Format of time written in labels differs slightly from format
used to pass times to routines. Input format contains only one colon
between minutes and seconds (makes the meaning of a partial string
precise) while labels include an extra colon between hours and minutes
(more acceptable for publication).
MODIFICATION HISTORY:
Written by Kim Tolbert, 4/88.
Mod. by Richard Schwartz to Version 2 91/02/17
Mod. by Richard Schwartz for compatibility with OPLOT. 3/26/91
Mod. by RAS, keywords TICK_UNIT and MINORS added 91/05/02
MOD. BY RAS TO ACCEPT ALL PLOT KEYWORDS, 91/10/03
MOD. by AKT 11/12/92. Added error keyword argument.
Mod. ras, yohkoh style keyword
removed DATA, DEVICE, NORMAL keywords 14-May-93, ras
so version 2 can compile the many keywords
RAS, 93/6/8 -
If X window, make sure window is open before saving any bang variables
otherwise Linecolors will fail!
Mod by MDM to work with YOHKOH data (structure data types)
Mod by MDM to expand the COMMON block so that OUTPLOT will work
Mod by MDM 21-Apr-92 to not set !quiet
Mod by SLF 26-Apr-92 to reinstate the xtitle option
Mod by MDM 28-Aug-92 to add keyword YEAR to print the year on the
tick label
Mod by MDM 9-Apr-93 to added TIMERANGE option
Mod by MDM 12-Apr-93 to removed ZMARGIN since older IDL versions had
trouble with 9-Apr addition of TIMERANGE parameter
1-NOV-93, ras, integrate Yohkoh and SDAC software packages
10-Nov-93, ras, accept single element arguments for x0 and y0
14-Dec-93, MDM, - Added keyword XTHICK and YTHICK
- Set the x-axis label to be Start Time ... by default
4-jan-94, ras - undeclared base_times are set to start of day
for fully referenced times, used anytim to make time processing
more resilient to the type of the x axis variable
28-jan-94, ras - fixed ynozero problem
7-apr-94, ras - clarified some of the documentation on
tick_unit and labelpar
28-jul-94, ras - added keyword inheritance and eliminated explicit reference to zkeywords
8-Aug-94, MDM - Modified so that /NOLABEL is recognized with Yohkoh time
format
10-aug-94, ras - xtype is set explicitly to zero to facilitate later use of oplot
if utplot was used after a call to plot_oi, xtype not set properly
16-aug-94, ras - added zvalue keyword and removed _extra from call to oplot
treatment of symsize is changed to allow control by !p.symsize
2-aug-95, ras - symsize was not being utilized through !p.symsize
This is a clear IDL bug in version 4, also present in
version 3.6.1.c, !p.symsize is not being used, where
using the keyword symsize explicitly results in the
expected symbol size?
The second fix is to have the routine explicitly check for
data values within the requested range and to plot only the
plot box without data points. So utplot will
be much more resilient in the future and will not cause
a code-stopping error. However, an informative
message is issued using "message,/continue"
17-dec-98, richard.schwartz@gsfc.nasa.gov
Now, NTICKS can be used to help control the number of intervals.
Default minor selection held to 12 or less.
Approximate selection of TICK_UNIT enabled through negative values.
16-Aug-1999, William Thompson, GSFC
Changed way that MAX_VALUE is calculated if not
passed, to avoid problems with large Y ranges.
7-Feb-2000, Richard Schwartz (gsfc.nasa.gov), correctly implemented MAX_VALUE so it is
really used. Added MIN_VALUE.
25-Sep-2000, Richard Schwartz (gsfc.nasa.gov), added NaN protection to max_value and min_value.
Change per advice from Dale Gary, NJIT.
(See /home/drw/idl/gen/nutplot.pro)
N_LINES[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: n_lines
PURPOSE: count number of lines in a file
USEAGE: result=numlines(file,nw)
INPUT:
file file name
OUTPUT:
result number of lines in file
nw number of words in file
EXAMPLE:
file='/home/paul/idl/esrg/n_lines.pro
print,'number of lines =',n_lines(file,nw) ,$
'number of words =',nw
AUTHOR: Paul Ricchiazzi 29 Feb 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/n_lines.pro)
N_LINES[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: numlines
PURPOSE: count number of lines in a file
USEAGE: result=numlines(file)
INPUT:
file file name
OUTPUT:
result number of lines in file
EXAMPLE:
print,n_lines('/local/idl/user_contrib/esrg/n_lines.pro')
AUTHOR: Paul Ricchiazzi 29 Feb 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/n_lines.pro)
O2O2CONT
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: o2o2cont
PURPOSE: plot o2*o2 continuum optical depth
USEAGE: o2o2cont
INPUT:
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 27 Jul 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/o2o2cont.pro)
OAXIS
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: oaxis
PURPOSE: overplot the x or y axis with tick marks and labels
at irregularly spaced intervals.
NOTE: much of the same results can be obtained with
[xyz]ticks, [xyz]tickname, [xyz]minor, and [xyz]tickv
just make sure that the number of elements in xtickname
or xtickv exceeds the VALUE of xticks by one.
USEAGE: oaxis,t,tlabel=tlabel,bot=bot,top=top,right=right,left=left, $
title=title,charsize=charsize,space=space,ticklen=ticklen, $
gridstyle=gridstyle,extend=extend,color=color,tcolor=tcolor, $
offset=offset
INPUT:
t
a vector of axis points (data coordinates) to label or mark
if not set t is set to the number of tlabel elements, n_elements
of talel gt 1, or otherwise to !x.crange or !y.crange as appropriate
keyword input:
tlabel
string array of axis tickmark labels, if not of type
string, will be coerced into string. If tlable eq 1 then
tlabel is set to the values of t and then coerced into a string
using procedure numform.
title
x axis title, If XTICKNAME is undefined, TITLE appears immediately
outside axis line, outside the plot area if space is positive.
space
controls vertical spacing between axis, tick labels and axis
title. By default the centerline of the tick labels appear 1
character height below the x-axis while the x-axis title appears
2.5 character heights below the x-axis. The SPACE factor
multiplies these vertical offsets. SPACE < 0 causes the titles
to appear inside the plot area wrt to the axis. (default=1)
offset
controls offset from normal axis position. positive offset moves
the axis away from the center of the plot in units of the character
size
ticklen
length of tickmarks as a PERCENTAGE of the entire y coordinate range
TICKLEN=2 produces the standard major tickmark length, while
TICKLEN=1 produces the standard minor tickmark length. (defualt=0)
charsize
character size used for axis annotation. If more than two
plots are ganged in either the X or Y direction, the character
size is halved.
extend
if set and y lt 0 or y gt 1 then the y-axis lines are extended to
to intersect the new x-axis line. This produces an enclosed
rectangular area between the new x-axis and the old x-axis (if it
exists).
color
color index used to color axis
tcolor
color index used to color axis and tick titles (just for the characters)
DISCUSSION:
call the plot with ystyle or xstyle set to 4 or 5 to disable axis
drawing. Then call OAXIS to oveplot axis.
EXAMPLE:
f=randf(100,3) & f=(f-min(f))/(max(f)-min(f))
plot,f,xstyle=5,ystyle=5,ymargin=[10,10]
xpnts=findrng(0,99,11)
xlbl=findrng(0,20,11)
oaxis,xpnts,tlabel=xlbl,/ticklen,title='days'
oaxis,xpnts,tlabel=20-findrng(0,20,11),title='days remaining',offset=6
oaxis,xpnts,tlabel=xlbl*24,/ticklen,title='hours',/top
oaxis,findrng(0,1,11),/tlabel,/ticklen,title='value',/left
oaxis,findrng(0,1,11),/ticklen,/right
; fancy non-linear x-axis
f=randf(100,3) & f=(f-min(f))/(max(f)-min(f))
plot,f,xstyle=5,ymargin=[10,10]
xpnts=findrng(0,99,11)
xlbl=findrng(0,20,11)^2
oaxis,xpnts,tlabel=xlbl,/ticklen,title='days^2'
oaxis,xpnts,/ticklen,/top
AUTHOR: Paul Ricchiazzi 24 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/oaxis.pro)
OBAND[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: oband
USEAGE: oband,x,y1,y2,border=border,color=color,spacing=spacing,$
fill_pattern=fill_pattern,line_fill=line_fill,$
pattern=pattern,orientation=orientation
PURPOSE: Over plot shaded band on an x-y plot. Shaded region is
between y1 and y2 as a function of x. This is useful for
indicating an error bounds on an x-y plot.
INPUTS:
x vector of x values (data coordinates)
y1 vector of lower y values (data coordinates)
y2 vector of upper y values (data coordinates)
NOTE: y1 need not be smaller than y2. The shaded region
always extends from y1 to y2 no matter which one is
greater.
NOTE: If y1 or y2 is a scalor it will be used internally
as if it were a constant value vector of the same
length as x.
OPTIONAL KEYWORDS:
border
if set, draw a border around the filled region, the numerical
value of BORDER is the color index used to draw the border
Keywords recognized by the POLYFILL procedure:
COLOR
color index used to fill region
LINE_FILL
Set this keyword to indicate that polygons are
to be filled with parallel lines, rather than using
solid or patterned filling methods.When using the
line-drawing method of filling, the thickness, line-
style, orientation, and spacing of the lines may be
specified with keywords.
PATTERN
A rectangular array of pixels giving the fill
pattern. If this keyword parameter is omitted, POLY-
FILL fills the area with a solid color. The pattern
array may be of any size; if it is smaller than the
filled area the pattern array is cyclically
repeated.
SPACING
The spacing, in centimeters, between the parallel
lines used to fill polygons.
ORIENTATION
Orientation angle of lines used to fill region.
Graphics Keywords Accepted
See Chapter 2, Graphics Keywords and System Variables,
for the description of graphics and ploting keywords not
listed above. CHANNEL CLIP DATA DEVICE LINE NOCLIP NORMAL
T3D THICK Z.
EXAMPLE:
x=indgen(200)
y=randf(200,3)
y1=y+.1*(1.+randf(200,2)^2)
y2=y-.1*(1.+randf(200,2)^2)
plot,x,y
oband,x,y1,y2,color=100
oplot,x,y
plot,x,y
oband,x,y,0,/line_fill,orien=45,border=100
DISCUSSION: If y1 and y2 are more than 1 element, make sure their
array lengths are the same as x.
author: Paul Ricchiazzi 12apr93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/oband.pro)
OBAND[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine oband
useage oband,x,y1,y2,color=color
purpose: over plot shaded band on an x-y plot. Shaded region is between
y1 and y2 as a function of x.
inputs:
x vector of x values
y1 vector of lower y values
y2 vector of upper y values
NOTE: It really isn't necessary that y1 be always smaller than y2
as long as they are different somewhere. The shaded region
always extends from y1 to y2 no matter which one is greater.
optional keywords:
color color of shaded region (default = .9*!d.n_colors)
author: Paul Ricchiazzi 12apr93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/oband.pro)
OBJECT_SHADE_SURF
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
OBJECT_SHADE_SURF
PURPOSE:
This program shows you the correct way to write an
elevation-shaded surface in object graphics. This would
be the equivalent of these direct graphics commands:
Surface, data, Shades=BytScl(data)
Shade_Surf, data, Shades=BytScl(data)
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:
Object Graphics
CALLING SEQUENCE:
OBJECT_SHADE_SURF, data, x, y
INPUTS:
data: The 2D surface data.
x: A vector of X values, corresponding to the X values of data.
y: A vector of Y values, corresponding to the Y values of data.
KEYWORD PARAMETERS:
STYLE: Set equal to 1 for a wire-frame surface. Set equal to 2 for
a solid surface (the default).
COMMON BLOCKS:
None.
EXAMPLE:
OBJECT_SHADE_SURF
MODIFICATION HISTORY:
Written by: David Fanning, November 1998.
(See /home/drw/idl/aux/object_shade_surf.pro)
OCCULT
[Previous Routine]
[Next Routine]
[List of Routines]
to superimpose a black disc over an image, to simulate eclipse
plus, I wanted to write a routine called OCCULT.
drw
(See /home/drw/idl/secis/occult.pro)
OGRID
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: ogrid
PURPOSE:
USEAGE: ogrid,nx,ny,style=style
INPUT:
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 30 Oct 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/ogrid.pro)
OLDPGFFT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pgfft
PURPOSE: Calculate the FFT
USEAGE: result = PGFFT(Time,Flux)
INPUT:
Time Time array in seconds
Flux Flux array
OUTPUT:
result The power spectrum
AUTHOR: Peter T. Gallagher, Mar. '99
(See /home/drw/idl/bin/ptg/oldpgfft.pro)
OLDPGFFT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pgfft
PURPOSE: Calculate the FFT
USEAGE: result = PGFFT(Time,Flux)
INPUT:
Time Time array in seconds
Flux Flux array
OUTPUT:
result The power spectrum
AUTHOR: Peter T. Gallagher, Mar. '99
(See /home/drw/idl/secis/oldpgfft.pro)
OLD_AZ_SA
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: az_sa
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(349/341)
and SiX(356/347)
USEAGE: az_sa, qlds
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(See /home/drw/idl/secis/old_az_sa.pro)
ONESURF
[Previous Routine]
[Next Routine]
[List of Routines]
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.
(See /home/drw/idl/aux/onesurf.pro)
OPLANCK
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: oplanck
PURPOSE: overplot a series of plack body curves
units of planck function output is
W/m2/str/micron (microns=1) xrange in microns
W/m2/str/cm-1 (microns=0) xrange in cm-1
USEAGE: oplanck,t,xrange=xrange,microns=microns,scale=scale,$
xlab=xlab,color=color,linestyle=linestyle
INPUT:
t temperature(s) for black body curves
KEYWORD INPUT:
xrange x limits of planck output
microns if set, xrange is in microns and planck is in W/m2/micron,
otherwise xrange is in cm-1 and planck is in W/m2/cm-1
scale scale factor to multiply, planck function radiance.
set scale to !pi to convert planck to irradiance
xlab if set, write temperature label. Set xlab=0 to put labels
at xrange(0) or set xlab=1 to put lables at xrange(1)
EXAMPLE:
; thermal radiance, output in microns
ww=findrng(4,20,100)
rand=smooth((5*randomu(seed,100)) < 1,3)
rr=planck(ww,300,/mic)*rand
plot,ww,rr,xrange=[4,22]
oplanck,findrng(200,300,5),/mic,xrange=[4,20],ylab1=ylab1
; thermal radiance, output in cm-1
ww=findrng(300,2500,100)
rand=smooth((5*randomu(seed,100)) < 1,3)
rr=planck(ww,300)*rand
plot,ww,rr
oplanck,findrng(200,300,5),xrange=[300,2500],xlab=0
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/oplanck.pro)
OPLOTIMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
OPLOTIMAGE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Overlays an image on an existing plot.
CALLING SEQUENCE:
OPLOTIMAGE, img
DESCRIPTION:
OPLOTIMAGE overlays an image on an already-existing set of plot
axes. It should not matter what plot elements have already be
displayed, but at least one command is needed to set up the plot
axes.
Only the IMGXRANGE and IMGYRANGE keywords, specifying the extent
of the image, can be given in a call to OPLOTIMAGE.
See PLOTIMAGE for more detailed information.
INPUTS:
IMG - A byte array to be displayed. An image declared as
ARRAY(M,N) will be M pixels in the x-direction and N pixels
in the y-direction. The image is resampled via
interpolation to fill the desired display region.
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
IMGXRANGE, IMGYRANGE - Each is a two component vector that
describes the X and Y position of the first
and last pixels.
Default: the size of the image in pixels
OUTPUTS:
NONE
PROCEDURE:
EXAMPLE:
This example first constructs an image whose values are found by
z(x,y) = cos(x) * sin(y)
and x and y are in the range [-2,2] and [4,8], respectively.
The image is then plotted in the range [-10, 10] in both x and
y directions.
x = findgen(20)/5. - 2.
y = findgen(20)/5. + 4.
zz = cos(x) # sin(y)
imgxrange = [min(x), max(x)]
imgyrange = [min(y), max(y)]
xr=[-10.,10]
yr=[-10.,10]
plotimage, bytscl(zz), imgxrange=imgxrange, imgyrange=imgyrange
Now for the overlay. A new image is created in the ranges between
-10 and 0:
z(x,y) = x y
x = findgen(20)/2 - 10.
y = findgen(20)/2 - 10.
imgxrange = [min(x), max(x)]
imgyrange = [min(y), max(y)]
zz = x # y
oplotimage, bytscl(zz), imgxrange=imgxrange, imgyrange=imgyrange
SEE ALSO:
PLOTIMAGE, BYTSCL
EXTERNAL SUBROUTINES:
SUBCELL, DEFSUBCELL, TVIMAGE
MODIFICATION HISTORY:
Written, CM, 1997
Removed BYTE requirement, added ON_ERROR, CM 19 Apr 2000
Added copyright notice, CM 25 Mar 2001
$Id: oplotimage.pro,v 1.2 2001/03/25 18:10:44 craigm Exp $
(See /home/drw/idl/aux/markwardt/oplotimage.pro)
OPUS2HIST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
OPUS2HIST
PURPOSE:
Reads FITS file with histogram data in binary extensions.
Differs from mrdfits only in the ability to handle the same
keywords used by LIST2HIST. This is a modified version of
HIST2HIST which reads files output by OPUS. Usually run from
READIT rather than run directly.
CATEGORY:
FITS
CALLING SEQUENCE:
result = OPUS2HIST(Filename)
INPUTS:
Filename:
Input FITS file with histogram data as output by OPUS.
KEYWORD PARAMETERS:
NOTE: DO NOT change these without also modifying LIST2HIST.
TRANGE: A two element vector containing the start and ending
times to include in the array.
XRANGE: A two element vector containing the range of x to include
in the array.
YRANGE: A two element vector containing the range of y to include
in the array.
PRANGE: A two element vector containing the range of pulse height
to include in the array.
SCALE: Scale factor for array. Can be set to make the resultant
array a reasonable size. A scale size of n bins the
image n x n.
PHD: The returned pulse height distribution.
FHEADER:The returned primary HDU FITS header.
BHEADER:A string containing the FITS header of the extension containing
the data.
EXPAND: If present, scale the number of x and y pixels by SPECBINX
and SPECBINY. Flux in each pixel is spread evenly over the
new smaller pixels.
XSCALED,YSCALED:
If these keywords are present, on return they will contain
the value of x and y scaling that was applied to the data.
They are probably the values of SPECBINX and SPECBINY or 1,1.
SILENT: If included, suppress informative messages.
COMMON BLOCKS:
LAMSPACE:for IMAGE.PRO.
MODIFICATION HISTORY:
HIST2HIST Written by David Sahnow, 12 August 1997.
14 November 1997 Changed to return an empty string for BHEADER.
3 November 1998 Modified to OPUS2HIST.
4 November 1998 Changed from reading all extensions to just the first.
15 November 1998 Changed call to NUMEXT to NUM_EXT.
26 March 1999 Now reads all extensions with data and inserts it into
the array. Previously read only the first data extension.
24 May 1999 Changed to returned headers so that FHEADER is now the
primary header, and BHEADER is the header of the extension containing
the image.
30 January 2000 Added EXPAND keyword to scale input array by
SPECBINX and SPECBINY and restore original pixel ratio. Also
added XSCALED and YSCALED keywords in order to return the amount
of scaling that was done.
30 May 2000 Added SILENT keyword.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/opus2hist.pro)
OVECTOR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
OVECTOR
PURPOSE:
Produce a two-dimensional velocity field overplot.
A directed arrow is drawn at each point showing the direction and
magnitude of the field.
CATEGORY:
Plotting, two-dimensional.
CALLING SEQUENCE:
OVECTOR, U, V [, X, Y]
INPUTS:
U: The X component of the two-dimensional field.
U must be a two-dimensional array.
V: The Y component of the two dimensional field. Y must have
the same dimensions as X. The vector at point (i,j) has a
magnitude of:
(U(i,j)^2 + V(i,j)^2)^0.5
and a direction of:
ATAN2(V(i,j),U(i,j)).
OPTIONAL INPUT PARAMETERS:
X: Optional abcissae values. X must be a vector with a length
equal to the first dimension of U and V.
Y: Optional ordinate values. Y must be a vector with a length
equal to the second dimension of U and V.
KEYWORD INPUT PARAMETERS:
NX: The # of vectors to actually plot in the X-direction.
Uses CONGRID to reduce the size of the U,V,X arrays
NY: The # of vectors to plot in the Y-direction.
MISSING: Missing data value. Vectors with a LENGTH greater
than MISSING are ignored.
LENGTH: The vector length as fraction of Max(magnitude)
STANDARD: The standard length of a vector, instead of 1.5*STDEV(magnitudes).
This is useful when plotting several graphs, each of
which should have vectors of the same standard length.
HSIZE: Size of arrowhead, default is 1.
COLOR: The color used for the vectors.
DOTS: Set this keyword to place a dot at each missing point.
Has effect only IF MISSING is specified.
ZERO: Set this keyword to place a dot at each point
with magnitude 0.
NOTAIL: Set this keyword to not draw any tail, just the arrowhead.
(note that HSIZE may then need to be adjusted)
NOSCALE: Do not scale the vectors. Normally, OVECTOR takes
the ratio of plot window size to data coordinate
window size and uses this to scale the V component,
so the scale in the V-direction is the same in the U.
FILL: Fill in arrow heads.
LEGEND: Place a vector of the standard length on the plot with a label
LEG_LOC: Two element vector in data coords for the legend location
LEG_UNITS: String containing the units of the legend vector eg. "m/s"
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Plotting on the selected device is performed. System
variables concerning plotting are changed.
RESTRICTIONS:
None.
MODIFICATION HISTORY:
Created 2/16/93 C. Torrence
6/10/95 Added LEGEND keyword G. Compo
(See /home/drw/idl/aux/ovector.pro)
OWINDOW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
OWINDOW
PURPOSE:
The purpose of this program is to create an object window.
I use it mostly when I am creating and testing object graphics
programs, but it is also a nice template for larger object
graphics programs. The window is resizeable and it destroys
its objects when it is destroyed.
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:
thisWindow = OWindow(thisView)
REQUIRED INPUTS:
None. A default view object is created with a gray background and
a viewplane rectangle defined as [0,0,1,1].
OPTIONAL INPUTS:
thisView: A view or scene object that you wish to be displayed
in the window.
RETURN VALUE:
thisWindow: The window graphics object associated with this window.
OPTIONAL KEYWORD PARAMETERS:
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
TITLE: A string used as the title of the graphics window.
XSIZE: The X Size of the graphics window in device coordinates. The
default value is 300.
YSIZE: The Y Size of the graphics window in device coordinates. The
default value is 300.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To display a view object in this window, type:
IDL> thisWindow = OWindow(thisView)
Later, after you have modified the view object, you can type:
IDL> thisWindow->Draw, modifiedView
MODIFICATION HISTORY:
Written by David Fanning, 19 June 97.
Set RETAIN=1 on draw widget. 6 Oct 97. DWF.
Changed discredited IDLgrContainer to IDL_Container. 29 JUN 98. DWF.
(See /home/drw/idl/aux/owindow.pro)
PARCHECK
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
PARCHECK (GENERAL IDL LIBRARY 01) 30-MAR-1987
*CLASS:
Error checking
*CATEGORY:
*PURPOSE:
To check that a procedure has been called with the minimum of allowed
number of parameters.
*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'
*SYSTEM VARIABLES USED:
*INTERACTIVE INPUT:
*SUBROUTINES CALLED:
PCHECK
*FILES USED:
*SIDE EFFECTS:
*RESTRICTIONS:
*NOTES:
tested with IDL Version 2.1.0 (sunos sparc) 28 Jun 91
tested with IDL Version 2.1.0 (ultrix mipsel) N/A
tested with IDL Version 2.1.0 (vax vms) 28 Jun 91
*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
(See /home/drw/idl/icur/parcheck.pro)
PARSELINE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PARSELINE
PURPOSE:
This function accepts a string as an argument and returns an
array which contains the numerical values in that string. It can
handle space or comma delimited numerical values. It returns
a value of -1 if non-numerical stuff is found in the line.
CALLING SEQUENCE:
array_out = PARSELINE(string_in, desired_data)
OPTIONAL INPUTS:
DESIRED_DATA -- An array which specifies the desired columns of data
from the string. It is zero based. Column numbers can be repeated in
the array. If this is not specified the default is to return an array
containing each value in the string once in the order they appear in
the string.
KEYWORD PARAMETERS:
DOUBLE -- The default behavior. The returned array will be a double
precision floating point array.
FLOAT -- The returned array will be a single precision floating point
array.
INTEGER -- The returned array will be an array of short integers.
RETURN VALUE:
array_out = dblarr(n_data) N_DATA is either the number of columns in
the string or the number of elements in the DESIRED_DATA array.
USAGE:
The calling procedure will look something like:
IDL> text=''
IDL> openr,1,'input.dat'
IDL> readf,1,text
IDL> data=parseline(text,[0,1,5,4,6,7])
IDL> print,data
0.10000000 3.4000000 2.4000000e-06 5.0000000 2.0080000 0.0000000
MAJOR FUNCTIONS and PROCEDURES:
None.
MODIFICATION HISTORY:
Written by: Alan Munter, munter@uiuc.edu, May 1997.
(See /home/drw/idl/aux/parseline.pro)
PAUSE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: pause
useage: pause
pause,up=up,xcrs=xcrs,ycrs=ycrs,on_screen=on_screen
input: none
keyword input:
up
if set, don't return until a upward button transition is
detected. This is useful when pause is used between plots which
draw quickly. Setting this keyword ensures that no plots are
skipped but also requires that each new plot be accompanied by a
downward and upward button transition. The default is to skip
to the next plot as long a mouse button is pressed down.
xcrs,ycrs
pixel location to put cursor while waiting
on_screen
if set, don't pause if cursor not in plot window
output: none
PURPOSE:
Momentarily stop execution until a mouse key is pressed. While
in the paused state the cursor is changed to what looks like an
arrow pointing down on a button. When any of the mouse buttons
are pressed the cursor returns to its original form and
execution continues.
PAUSE will only interrupt execution if the output device is 'X'
and plot system variable !p.multi(0) eq 0. The first condition
disables PAUSE when output is directed to a postscript file.
The second condition ensures that pauses occur only just before
the screen is erased for a new plot.
NOTE: After PAUSE returns to the calling program different
actions can be performed depending on whether the left, middle
or right mouse button was pressed. Just test on the !err system
variable: !err=1 => left !err=2 => middle !err=4 => right.
COMMON BLOCKS: pause_blk
EXAMPLE:
x=findgen(201)/10.-10.
for a=-2.,2.,.1 do begin & plot,x,1/(x^2*10.^a+1),tit=string(a) & pause & end
for a=-2.,2.,.1 do begin & plot,x,1/(x^2*10.^a+1),tit=string(a) &$
pause,/u & end
author: Paul Ricchiazzi 22sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/pause.pro)
PAUSE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: pause
useage: pause
pause,up=up,xcrs=xcrs,ycrs=ycrs,on_screen=on_screen
input: none
keyword input:
up
if set, don't return until a upward button transition is
detected. This is useful when pause is used between plots which
draw quickly. Setting this keyword ensures that no plots are
skipped but also requires that each new plot be accompanied by a
downward and upward button transition. The default is to skip
to the next plot as long a mouse button is pressed down.
xcrs,ycrs
pixel location to put cursor while waiting
on_screen
if set, don't pause if cursor not in plot window
output: none
PURPOSE:
Momentarily stop execution until a mouse key is pressed. While
in the paused state the cursor is changed to what looks like an
arrow pointing down on a button. When any of the mouse buttons
are pressed the cursor returns to its original form and
execution continues.
PAUSE will only interrupt execution if the output device is 'X'
and plot system variable !p.multi(0) eq 0. The first condition
disables PAUSE when output is directed to a postscript file.
The second condition ensures that pauses occur only just before
the screen is erased for a new plot.
NOTE: After PAUSE returns to the calling program different
actions can be performed depending on whether the left, middle
or right mouse button was pressed. Just test on the !err system
variable: !err=1 => left !err=2 => middle !err=4 => right.
COMMON BLOCKS: pause_blk
EXAMPLE:
x=findgen(201)/10.-10.
for a=-2.,2.,.1 do begin & plot,x,1/(x^2*10.^a+1),tit=string(a) & pause & end
for a=-2.,2.,.1 do begin & plot,x,1/(x^2*10.^a+1),tit=string(a) &$
pause,/u & end
author: Paul Ricchiazzi 22sep92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/pause.pro)
PCA[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PCA
PURPOSE:
Carry out a Principal Components Analysis (Karhunen-Loeve Transform)
CALLING SEQUENCE:
PCA, data, eigenval, eigenvect, percentages, proj_obj, proj_atr,
[MATRIX =, TEXTOUT = ,/COVARIANCE, /SSQ, /SILENT ]
INPUT PARAMETERS:
data - 2-d data matrix, data(i,j) contains the ith sample of the
jth variable. DATA shoud be dimensioned (NSAMP,NVAR), where
NSAMP is the total number of samples and NVAR is the total
number of variable parameters. For example, consider
a scatter plot of temperature vs relative humidity.
The first index of DATA cycles over all measurments and the
second index cycles over two parameters: T and Rh. IF
T and Rh are 1-D arrays containing all sampled values then
DATA may be constructed as DATA=[[T],[Rh]].
OPTIONAL INPUT KEYWORD PARAMETERS:
/COVARIANCE - if this keyword set, then the PCA will be carried out
on the covariance matrix (rare), the default is to use the
correlation matrix
/SSQ - if this keyword is set, then the PCA will be carried out on
on the sums-of-squares & cross-products matrix (rare)
OPTIONAL OUTPUT PARAMETERS:
eigenval NVAR element vector containing the sorted eigenvalues
eigenvect NVAR x NVAR matrix containing the corresponding
eigenvectors, first index cycles over different eigenvectors
second index cycles over original coordinate directions
percentages NVAR element vector containing the cumulative percentage
variances associated with the principal components
proj_obj NSAMP by NVAR matrix containing the projections of the
objects on the principal components
proj_atr NVAR by NVAR matrix containing the projections of
the attributes on the principal components
MATRIX analysed matrix, either the covariance matrix if
/COVARIANCE is set, the "sum of squares and
cross-products" matrix if /SSQ is set, or the (by
default) correlation matrix. MATRIX will have
dimensions NVAR x NVAR
NOTES:
This procedure performs Principal Components Analysis (Karhunen-Loeve
Transform) according to the method described in "Multivariate Data
Analysis" by Murtagh & Heck [Reidel : Dordrecht 1987], pp. 33-48.
Keywords /COVARIANCE and /SSQ are mutually exclusive.
The printout contains only (at most) the first seven principle
eigenvectors. However, the output variables EIGENVECT contain
all the eigenvectors
Different authors scale the covariance matrix in different ways.
The eigenvalues output by PCA may have to be scaled by 1/NSAMP or
1/(NSAMP-1) to agree with other author's calculations when /COVAR is
set.
Users of V3.5.0 or later could change the calls to TQLI and TRED2
to NR_TQLI and NR_TRED2
EXAMPLE:
; PCA analysis on a scatter plot of two variable, t1,t2, which we
; will assume are linearly dependent on 2 random gaussian variables
; x1,x2 as follows,
;
nsamp=10000
x1=randomn(iseed,nsamp)
x2=randomn(iseed,nsamp)
t1=5*x1+2*x2 ; = = 25*+4* = 29
t2=5*x1-2*x2 ; = 25*-4* = 21
;
data=[[t1],[t2]] ; nsamp measurements of 2 parameters
pca,data,eval,evec,per ;
; |1-ev 21/29| eigenvalue
print,eval ; | | = 0 equation on
print,evec ; |21/29 1-ev | correlation matrix
print,per ;
; ev=1+-(21/29) = 1.7248, .2752
t=findrng(0,2*!pi,100)
xx1=evec(0,0)*20 ; 1st eigenvector
yy1=evec(0,1)*20
xx2=sqrt(eval(1)/eval(0))*evec(1,0)*20 ; 2nd eigenvector
yy2=sqrt(eval(1)/eval(0))*evec(1,1)*20
plot,t1,t2,psym=3,xra=[-20,20],yra=[-20,20],pos=boxpos(/asp)
oplot,xx1*[-1,1],yy1*[-1,1] & oplot,xx2*[-1,1],yy2*[-1,1]
oplot,cos(t)*xx1+sin(t)*xx2, cos(t)*yy1+sin(t)*yy2
putstr,'eigenvector 1',11.,16.6,chars=1.3
putstr,'eigenvector 2',5.4,-7.1,chars=1.3
COPYRIGHT:
Copyright 1993, Hughes STX Corporation, Lanham MD 20706.
REVISION HISTORY:
Immanuel Freedman (after Murtagh F. and Heck A.). December 1993
code cleanup and corrected output description (PJR) June 1997
(See /home/drw/idl/esrg/pca.pro)
PCA[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PCA
PURPOSE:
Carry out a Principal Components Analysis (Karhunen-Loeve Transform)
Results can be directed to the screen, a file, or output variables
CALLING SEQUENCE:
PCA, data, eigenval, eigenvect, percentages, proj_obj, proj_atr,
[MATRIX =, TEXTOUT = ,/COVARIANCE, /SSQ, /SILENT ]
INPUT PARAMETERS:
data - 2-d data matrix, data(i,j) contains the jth attribute value
for the ith object in the sample. If N_OBJ is the total
number of objects (rows) in the sample, and N_ATTRIB is the
total number of attributes (columns) then data should be
dimensioned N_OBJ x N_ATTRIB.
OPTIONAL INPUT KEYWORD PARAMETERS:
/COVARIANCE - if this keyword set, then the PCA will be carried out
on the covariance matrix (rare), the default is to use the
correlation matrix
/SSQ - if this keyword is set, then the PCA will be carried out on
on the sums-of-squares & cross-products matrix (rare)
TEXTOUT - Controls print output device, defaults to !TEXTOUT
textout=1 TERMINAL using /more option
textout=2 TERMINAL without /more option
textout=3 file pca.prt
textout=4 laser.tmp
textout=5 user must open file (see TEXTOPEN)
textout = 'filename' (default extension of .prt)
OPTIONAL OUTPUT PARAMETERS:
eigenval - N_ATTRIB element vector containing the sorted eigenvalues
eigenvect - N_ATRRIB x N_ATTRIB matrix containing the corresponding
eigenvectors
percentages - N_ATTRIB element containing the cumulative percentage
variances associated with the principal components
proj_obj - N_OBJ by N_ATTRIB matrix containing the projections of the
objects on the principal components
proj_atr - N_ATTRIB by N_ATTRIB matrix containing the projections of
the attributes on the principal components
OPTIONAL OUTPUT PARAMETER:
MATRIX = analysed matrix, either the covariance matrix if /COVARIANCE
is set, the "sum of squares and cross-products" matrix if
/SSQ is set, or the (by default) correlation matrix. Matrix
will have dimensions N_ATTRIB x N_ATTRIB
NOTES:
This procedure performs Principal Components Analysis (Karhunen-Loeve
Transform) according to the method described in "Multivariate Data
Analysis" by Murtagh & Heck [Reidel : Dordrecht 1987], pp. 33-48.
Keywords /COVARIANCE and /SSQ are mutually exclusive.
The printout contains only (at most) the first seven principle
eigenvectors. However, the output variables EIGENVECT contain
all the eigenvectors
Different authors scale the covariance matrix in different ways.
The eigenvalues output by PCA may have to be scaled by 1/N_OBJ or
1/(N_OBJ-1) to agree with other author's calculations when /COVAR is
set.
PCA uses the non-standard system variables !TEXTOUT and !TEXTUNIT.
These can be added to one's session using the procedure ASTROLIB.
Users of V3.5.0 or later could change the calls to TQLI and TRED2
to NR_TQLI and NR_TRED2
EXAMPLE:
Perform a PCA analysis on the covariance matrix of a data matrix, DATA,
and write the results to a file
IDL> PCA, data, /COVAR, t = 'pca.dat'
Perform a PCA analysis on the correlation matrix. Suppress all
printing, and save the eigenvectors and eigenvalues in output varaibles
IDL> PCA, data, eigenval, eigenvect, /SILENT
PROCEDURES CALLED:
Procedures TEXTOPEN, TEXTCLOSE
COPYRIGHT:
Copyright 1993, Hughes STX Corporation, Lanham MD 20706.
REVISION HISTORY:
Immanuel Freedman (after Murtagh F. and Heck A.). December 1993
Wayne Landsman, modified I/O December 1993
(See /home/drw/idl/old.esrg/pca.pro)
PCHECK
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
PCHECK
*CLASS:
*CATEGORY:
*PURPOSE:
This procedure is used to check the parameters of
a procedure for correct type and dimensions
*CALLING SEQUENCE:
PCHECK,VARIABLE,POSITION,DIMENSION,TYPE
*PARAMETERS:
VARIABLE - Variable to be checked
POSITION - Parameter position of the variable
DIMENSION - Valid dimensions (3 digit integer).
Each digit must be 0 or 1.
1 specifies that the dimension is valid.
1st digit - scalar
2nd - one dimensional array
3rd - two dimensional array
TYPE - Valid types ( 4 digit integer).
Each digit must be 0 or 1.
1 specifies a valid type.
1st digit - string
2nd - byte
3rd - integer, or longword integer
4th - floating point, double precision or complex
*EXAMPLES:
*SYSTEM VARIABLES USED:
*INTERACTIVE INPUT:
*SUBROUTINES CALLED:
*FILES USED:
*SIDE EFFECTS:
*RESTRICTIONS:
*NOTES:
tested with IDL Version 2.1.0 (sunos sparc) 28 Jun 91
tested with IDL Version 2.1.0 (ultrix mipsel) N/A
tested with IDL Version 2.1.0 (vax vms) 28 Jun 91
*PROCEDURE:
*I_HELP nn:
*MODIFICATION HISTORY:
d. lindler dec. 1980
version 2 f.h.schiffer 3rd 17 nov 1981
copied into [177001] by rwt 1-17-84
10-24-85 rwt modify for new didl data types: longword integer,
double precision & complex. modified to be compatible
with existing version (i.e., no new input parameters)
21-sep-88: converted to sun idl, john hoegy.
10 May 91 PJL created a RDAF format prolog
28 Jun 91 PJL added npar test; tested on SUN and VAX; updated prolog
(See /home/drw/idl/icur/pcheck.pro)
PCPOWER.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PCPOWER.PRO
PURPOSE:
To work out the total power in a certain frequency
interval in a FFT as a percentage of the total power
using mouse clicks at the desired limits of the
frequency interval.
CALLING SEQUENCE:
pcout = pcpower(fftin)
INPUTS:
FFTIN - a two-vector array containing a vector of
frequencies (FFTIN[0,*]) and one of associated
powers (FFTIN[1,*]).
OUTPUTS:
PCOUT - percentage of total output power contained
between the two mouse clicks.
KEYWORDS:
LOGS - show the plot of power logarithmically.
CALLS:
MOVELINE.PRO
HISTORY:
version 1.0 - D.Williams, QUB: 8/11/00
version 1.1 - D.Williams, 9/11/00: added LOGS keyword
(See /home/drw/idl/secis/pcpower.pro)
PFILL[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pfill
PURPOSE: break a long string consisting of many blank-separated
words into a paragraph that consists of several lines each
with a given number of characters (60 character default).
This procedure can be use used with LEGEND and CAPTION to
produce nicely formated figure captions. The nice thing
about PFILL is that it will properly compute the length of
lines which contain text escape sequences such as a =
!7d!x!ai!b.
USEAGE: result=pfill(string,nchars=nchars,exdent=exdent,cr=cr,nlines=nlines)
INPUT:
string a string which consists of words separated by blanks
Note that the !9K!x maps to a hardwired space
KEYWORD INPUT:
nchars maximum number of characters per line (default=60)
exdent if set, EXDENT specifies the number of characters with
which to indent all but the first line. Use this to make
a "hanging indent." You can indent the first line by
simply adding some spaces to the beginning of the string.
cr if set, replace instances of "\" in output string with "!c".
This allows formatted string to be used with XYOUTS or PUTSTR.
OUTPUT:
result a paragraph string which consists of several lines each
with a given number of characters (60 character default).
Lines are separated by the character "\", which is
understood by LEGEND to indicate a newline. You can turn
the string into a string array, with each array element
corresponding to one line in the paragraph by using
STR_SEP. For example, t=str_sep(pfill(t,n=30),'\').
KEYWORD OUTPUT:
nlines number of lines in result
EXAMPLE:
t='PURPOSE: break a long string consisting of many blank-separated '+$
'words into a paragraph that consists of several lines each with '+$
'a given number of characters (60 character default). This procedure'+$
' can be used with LEGEND to produce nicely formated figure'+$
' captions. The nice thing about PFILL is that it will properly'+$
' compute the length of lines which contain text escape sequences'+$
' such as x = !7d!xa!a2!n / !7d!xb!bi!n * (!13A - B!x) * (!13C -'+$
' D!3). Text editors do not understand that all those extra exclamation'+$
' points should not be included in the character count of each line.'
w8x11
legend,pfill(t),/fill,/box,/norm,pos=[0.14,0.71,0.82,0.98]
legend,pfill(t,nchar=80),/fill,/box,/norm,pos=[0.05,0.48,0.96,0.68]
legend,pfill(t,n=80,exdent=11),/fill,/norm,pos=[0.11,0.28,0.85,0.46]
legend,pfill(' '+t,n=80),bg=0,/fill,/norm,pos=[0.11,0.04,0.89,0.22]
AUTHOR: Paul Ricchiazzi 03 Jul 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/pfill.pro)
PFILL[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pfill
PURPOSE: break a long string consisting of many blank-separated
words into a paragraph that consists of several lines each
with a given number of characters (60 character default).
This procedure can be use used with LEGEND to produce
nicely formated figure captions. The nice thing about
PFILL is that it will properly compute the length of lines
which contain text escape sequences such as a = !7d!x!ai!b.
USEAGE: result=pfill(string,nchars=nchars)
INPUT:
string a string which consists of words separated by blanks
Note that the !9K!x maps to a hardwired space
KEYWORD INPUT:
nchars maximum number of characters per line (default=60)
exdent if set, EXDENT specifies the number of characters with
which to indent all but the first line. Use this to make
a "hanging indent." You can indent the first line by
simply adding some spaces to the beginning of the string.
cr if set, replace instances of "\" in output string with "!c".
This allows formatted string to be used with XYOUTS or PUTSTR.
OUTPUT:
result a paragraph string which consists of several lines each
with a given number of characters (60 character default).
Lines are separated by the character "\", which is
understood by LEGEND to indicate a newline. You can turn
the string into a string array, with each array element
corresponding to one line in the paragraph by using
STR_SEP. For example, t=str_sep(pfill(t,n=30),'\').
EXAMPLE:
t='PURPOSE: break a long string consisting of many blank-separated '+$
'words into a paragraph that consists of several lines each with '+$
'a given number of characters (60 character default). This procedure'+$
' can be used with LEGEND to produce nicely formated figure'+$
' captions. The nice thing about PFILL is that it will properly'+$
' compute the length of lines which contain text escape sequences'+$
' such as x = !7d!xa!a2!n / !7d!xb!bi!n * (!13A - B!x) * (!13C -'+$
' D!3). Text editors do not understand that all those extra exclamation'+$
' points should not be included in the character count of each line.'
w8x11
legend,pfill(t),/fill,/box,/norm,pos=[0.14,0.71,0.82,0.98]
legend,pfill(t,nchar=80),/fill,/box,/norm,pos=[0.05,0.48,0.96,0.68]
legend,pfill(t,n=80,exdent=11),/fill,/norm,pos=[0.11,0.28,0.85,0.46]
legend,pfill(' '+t,n=80),bg=0,/fill,/norm,pos=[0.11,0.04,0.89,0.22]
AUTHOR: Paul Ricchiazzi 03 Jul 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/pfill.pro)
PGFFT2
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: PGFFT2
PURPOSE: Calculate the FFT
USEAGE: result = pgfft2(Delt,Flux)
INPUT:
Time Time array in seconds
Flux Flux array
OUTPUT:
result The power spectrum
AUTHOR: Peter T. Gallagher, Mar. '99
(See /home/drw/idl/secis/pgfft2.pro)
PGFFTJMA
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pgfftjma
PURPOSE: Calculate the FFT
USEAGE: result = PGFFT(Time,Flux)
INPUT:
Time Time array in seconds
Flux Flux array
OUTPUT:
result The power spectrum
AUTHOR: Peter T. Gallagher, Mar. '99
Altered by R.T. James McAteer & David R. Williams according to
http://cires.colorado.edu/geo_data_anal/assign/assign4.html
Oct' 01
(See /home/drw/idl/gen/pgfftjma.pro)
PGFFT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pgfft
PURPOSE: Calculate the FFT
USEAGE: result = PGFFT(Time,Flux)
INPUT:
Time Time array in seconds
Flux Flux array
OUTPUT:
result The power spectrum
AUTHOR: Peter T. Gallagher, Mar. '99
Altered by R.T. James McAteer & David R. Williams according to
http://cires.colorado.edu/geo_data_anal/assign/assign4.html
Oct' 01
(See /home/drw/idl/vtt/post_bbso/pgfft.pro)
PGFFT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pgfft
PURPOSE: Calculate the FFT
USEAGE: result = PGFFT(Time,Flux)
INPUT:
Time Time array in seconds
Flux Flux array
OUTPUT:
result The power spectrum
AUTHOR: Peter T. Gallagher, Mar. '99
Altered by R.T. James McAteer & David R. Williams according to
http://cires.colorado.edu/geo_data_anal/assign/assign4.html
Oct' 01
(See /home/drw/idl/jma/pgfft.pro)
PG_CIRCLE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
Name:
pg_circle
Purpose:
Draw a circle.
Calling Sequence:
pg_circle, x0, y0, radius [,npts=npts]
Input Parameters:
x0 = Central x coordinate
y0 = Central y coordinate
radius = Radius
Optional input keywords:
Npts = Number of points (default = 10000)
device = If set, plots will assume device coordinates
data = If set, plots will assume data coordinates
psym = Plot symbol
color = Color
linestyle = Line style
fill = If set, call poly_fill
noclip = If noclip=0, circles will be clipped (read the IDL
manual on plots to find out why its this way).
Modification History:
Written, 26-feb-92, J. R. Lemen
2-feb-95, JRL, Added thick keyword
11-apr-96, S.L.Freeland, Add FILL keyword and function
25-apr-96, JRL, Added the NOCLIP keyword
1999 ---- Peter's obviously had a crack at this at some stage,
esp. since it's called PG_CIRCLE now....
(See /home/drw/idl/bin/pg_circle.pro)
PG_CIRCLE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
Name:
draw_circle
Purpose:
Draw a circle.
Calling Sequence:
draw_circle, x0, y0, radius [, npts=npts]
Input Parameters:
x0 = Central x coordinate
y0 = Central y coordinate
radius = Radius
Optional input keywords:
Npts = Number of points (default = 10000)
device = If set, plots will assume device coordinates
data = If set, plots will assume data coordinates
psym = Plot symbol
color = Color
linestyle = Line style
fill = If set, call poly_fill
noclip = If noclip=0, circles will be clipped (read the IDL
manual on plots to find out why its this way).
Modification History:
Written, 26-feb-92, J. R. Lemen
2-feb-95, JRL, Added thick keyword
11-apr-96, S.L.Freeland, Add FILL keyword and function
25-apr-96, JRL, Added the NOCLIP keyword
(See /home/drw/idl/bin/ptg/pg_circle.pro)
PG_ROTATE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : NIS_ROTATE
Purpose : Applies slant and tilt corrections to VDS images.
Explanation : Applies the slant and tilt corrections of VDS_ROTATE to all the
windows in a CDS/NIS data structure. The tilt values are taken
from GET_TILTCAL.
Use : NIS_ROTATE, DATA
Inputs : DATA = Structure variable as read by READCDSFITS.
Opt. Inputs : None.
Outputs : DATA = The calibrated data will be returned as a new
structure variable with the same format as the input.
Opt. Outputs: None.
Keywords : BILINEAR = Allows bilinear interpolation during rectification.
This is the default. If nearest-neighbor
interpolation is desired, then set BILINEAR=0.
CUBIC = Allows cubic interpolation during rectification
(NOTE: both of these change the intensity values.)
BOTTOM = If set, then the data is aligned so that the bottom
of the slit is aligned with the bottom of the array.
Ignored unless the data contains a full spectral
readout.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors
are encountered, then a null string is returned. In
order to use this feature, ERRMSG must be defined
first, e.g.
ERRMSG = ''
NIS_ROTATE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls : VDS_CALIB, TAG_EXIST, GET_TILTCAL, DETDATA, DETDESC, DATATYPE,
VDS_ROTATE, ST_WINDATA, ADD_TAG
Common : None.
Restrictions: Before this procedure can be used, the calibration for the VDS
detector must be applied, via the VDS_DEBIAS and VDS_CALIB
routines. If not already done, then this routine will attempt
to use the automatic facilities of those routines.
Side effects: None.
Category : Calibration, VDS
Prev. Hist. : None.
Written : William Thompson, GSFC, 6 February 1998
Modified : Version 1, 6-Feb-1998, William Thompson, GSFC
Version : Version 1, 6-Feb-1998
(See /home/drw/idl/bin/pg_rotate.pro)
PG_ROTATE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : NIS_ROTATE
Purpose : Applies slant and tilt corrections to VDS images.
Explanation : Applies the slant and tilt corrections of VDS_ROTATE to all the
windows in a CDS/NIS data structure. The tilt values are taken
from GET_TILTCAL.
Use : NIS_ROTATE, DATA
Inputs : DATA = Structure variable as read by READCDSFITS.
Opt. Inputs : None.
Outputs : DATA = The calibrated data will be returned as a new
structure variable with the same format as the input.
Opt. Outputs: None.
Keywords : BILINEAR = Allows bilinear interpolation during rectification.
This is the default. If nearest-neighbor
interpolation is desired, then set BILINEAR=0.
CUBIC = Allows cubic interpolation during rectification
(NOTE: both of these change the intensity values.)
BOTTOM = If set, then the data is aligned so that the bottom
of the slit is aligned with the bottom of the array.
Ignored unless the data contains a full spectral
readout.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors
are encountered, then a null string is returned. In
order to use this feature, ERRMSG must be defined
first, e.g.
ERRMSG = ''
NIS_ROTATE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls : VDS_CALIB, TAG_EXIST, GET_TILTCAL, DETDATA, DETDESC, DATATYPE,
VDS_ROTATE, ST_WINDATA, ADD_TAG
Common : None.
Restrictions: Before this procedure can be used, the calibration for the VDS
detector must be applied, via the VDS_DEBIAS and VDS_CALIB
routines. If not already done, then this routine will attempt
to use the automatic facilities of those routines.
Side effects: None.
Category : Calibration, VDS
Prev. Hist. : None.
Written : William Thompson, GSFC, 6 February 1998
Modified : Version 1, 6-Feb-1998, William Thompson, GSFC
Version : Version 1, 6-Feb-1998
(See /home/drw/idl/bin/ptg/pg_rotate.pro)
PG_TVIM
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tvim
USEAGE: tvim,a
tvim,a,scale=scale,range=range,xrange=xrange,yrange=yrange,$
aspect=aspect,title=title,xtitle=xtitle,ytitle=ytitle,$
noaxis=noaxis,interp=interp,colors=colors,c_map=c_map,$
stitle=stitle,rmarg=rmarg,clip=clip,labels=labels,$
pcharsize=pcharsize,lcharsize=lcharsize,nbotclr=nbotclr,&
clevels=clevels,nodata=nodata,rgb_nodata=rgb_nodata,$
barwidth=barwidth,position=position,noframe=noframe,rct=rct
PURPOSE: Display an image with provisions for
1. numbered color scale
2. plot title
3. annotated x and y axis
4. simplified OPLOT capability
5. manual or automatic scaling with smooth or discreet colors
6 special treatment of "invalid data" pixels
INPUT
a image quantity
Optional keyword input:
title
plot title
xtitle
x axis title
ytitle
y axis title
stitle
color key title (drawn to the right of color scale)
rmarg
right margin expansion factor to provide more room for extra wide
color scale annotation (default=1)
xrange
array spanning entire x axis range. (default = [0,x_dimension-1])
yrange
array spanning entire y axis range. (default = [0,y_dimension-1])
NOTE:TVIM only uses min(XRANGE), max(XRANGE), min(YRANGE) and max(YRANGE).
scale
if set draw color scale. SCALE=2 causes steped color scale
range
two or three element vector indicating physical range over which
to map the color scale. The third element of RANGE, if specified,
sets the step interval of the displayed color scale. It has no
effect when SCALE is not set. E.g., RANGE=[0., 1., 0.1] will
cause the entire color scale to be mapped between the physical
values of zero and one; the step size of the displayed color
scale will be set to 0.1.
clip
specifies a set percentage of pixels which will be left outside
the color scale. Larger values of CLIP yield images with greater
contrast. For example if clip=2 then the color scale range will
be set to include 98% of the pixels and to exclude the brightest
1% and the dimmest 1% of the pixel brightness distribution.
Keyword RANGE overides the effect of CLIP.
If CLIP is a two element vector, the upper and lower percentile
range can be specified. For example CLIP=[0,95] will exclude the
top 5%.
An alternative is to set CLIP to a single negative integer. This
causes the grey scale range to be obtained from the max and min
value of the image array after it is filtered by a 2-D median
filter. The radius of the median filter is set to -clip. Median
filtering is effective in removing "salt and pepper" noise,
(isolated high or low values). For example, setting clip=-1
causes the code to check the 9 element superpixel centered at
each pixel for median values. A single extremely large or small
value does not affect the final value of the median at each pixel
point.
aspect
the x over y aspect ratio of the output image. If not set, aspect
is set to (size_x/size_y) of the input image.
position
specifies the lower left and upper right TVIM frame position in
normal coordinates. When set POSITION overides the setting of
ASPECT.
noaxis
if set do not draw x and y numbered axis around image. Instead
just draw a box
noframe
if set no not draw anything around image, not even a box
interp
TVIM normally uses nearest neighbor sampling to resize the image
to fill the data window area. If INTERP is set the resizing
operation uses bilinear interpolation
If INTERP = 2 the interpolation range is adjusted so that there
is a half pixel border around the plot. This ensures that the
smoothed image properly represents the cell center values of the
pixels, but introduces an extrapolation on the outer edges. This
option has noticeable effects for small (<20) image arrays.
NOTE: When writing to a Postscript file the resizing operation is
accomplished by changing the pixel size. Thus the INTERP
parameter has no effect on Postscript output.
pcharsize
character size of numbers along x and y axis and the title
(default is !p.charsize if non-zero, 1 otherwise)
NOTE: The character size of the x and y-axis number scale
annotation may be independently controlled by the !x.charsize or
!y.charsize system variables. For example, the x and y axis
number scale characters may be made invisible by setting these
variables to a very small non-zero number before calling TVIM.
Remember to restore normal character sizes by setting !x.charsize
and !y.charsize to 1 or zero after the call to TVIM.
lcharsize
character size of color key number or labels (default is
!p.charsize if non-zero, 1 otherwise)
barwidth
width of color key which appears to right of image when SCALE is
set. (default=1)
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies. When the COLORS array is set TVIM
will map values of A into the color values specified in COLORS.
How physical values are assigned to color values depends on how
the RANGE parameter is set, as shown in this table:
RANGE color_value
----- -----------
1. not set COLORS(A)
2. [amin,amax] COLORS((A-amin)/dinc)
3. [amin,amax,inc] COLORS((A-amin)/inc)
where amin, amax and inc are user specified elements of RANGE
and dinc=(amax-amin)/n_elements(COLORS). In case 1, A is used
directly as a subscript into COLORS. When RANGE is not set
legend labels should be used to annotate the color values. In
case 2, A is scaled so that each color defined in COLORS
represents a proportionate fraction of the total dynamic range.
In case 3, amin and inc (and not amax) are used to control which
colors are associated with given physical values. See examples.
c_map
TVIM normally rescales the input image to span the entire color
table range. Setting C_MAP disables this automatic re-scaling.
This is useful when the image byte values correspond to a
particular color mapping that could be destroyed by the
rescaling process (E.G. a gif image).
NOTE: When the number of IDL color table entries is less than
256 some colors may be lost. Use a private color map to avoid
this. See examples.
nbotclr
number of reserved colors at the bottom of the color
table. Color values between 0 and nbotclr-1 will not
be used in the displayed image. This allows the
bottom of the table to be set to special colors which
will not be used in the displayed the image. This
keyword is disabled when either the COLORS or NODATA
options are used. (default=1)
NOTE: by default the color table indicies used within a TVIM
image is limited to the range 1 to !d.n_colors-2. In most
predefined color tables, color index 0 and !d.n_color-1
correspond to pure black and white, respectively. TVIM uses
these color indicies as background and foreground colors for
region blanking and axis annotation. Color tables which do not
define black and white in these index locatations are not good
choices for TVIM plots, unless the first and last color table
entries are redefined as black and white using TVLCT, e.g.,
tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
NOTE: the procedure DCOLORS can be used to load a set
of discreet colors in the bottom 11 color values
(0-10). The original color table is resampled to fit
between color value 11 and the !d.n_colors-1.
nodata
pixel values which are interpreted as invalid data. Pixels
containing this data value are colored with color RGB_NODATA.
rgb_nodata
an RGB value (a 3 component vector) used to color pixels filled
with invalid data. (default = [0,0,0])
NOTE: NODATA and RGB_NODATA override the effect of NBOTCLR
rct
if set, reverse direction of color table. This keyword can be
used on black & white printers to allow large field values to be
represented by dark colors.
KEYWORD OUTPUT:
clevels
physical values at the color key tic marks. Use this to set
contour levels in a subsequent call to CONTOUR.
SIDE EFFECTS:
Setting SCALE=2 changes the color scale using the STEP_CT
procedure. The color scale may be returned to its original
state by the command, STEP_CT,/OFF
PROCEDURE:
TVIM first determines the size of the plot data window with a
dummy call to PLOT. When the output device is "X", CONGRID is
used to scale the image to the size of the available data
window. Otherwise, if the output device is Postscript,
scaleable pixels are used in the call to TV.
If the input image quantity is not of type byte, TVIM converts
them to byte by scaleing the input between 0 and !d.n_colors-1.
If the input is already a byte array and if either the number of
color table entries is 256 or if C_MAP is set, then no scaling
is done. This is to ensure consistency with specially defined
private color tables.
After the the image is drawn TVIM calls PLOT again to draw the x
and y axis and titles. Finally if scale is set, TVIM calls the
COLOR_KEY procedure to draw the color scale just to the right of
the data window.
RESTRICTIONS:
A stepped color scale (SCALE = 2 option) is not available when
writing to a black & white postscript file (i.e., when the
DEVICE color option is not enabled).
DEPENDENCIES: COLOR_KEY, STEP_CT, PRANK
EXAMPLES:
; Plot a GIF image with its own preset RGB
; table (perhaps from a digitized video image)
window,colors=256 ; set up a private color map
read_gif,file,im,r,g,b
tvlct,r,g,b
tvim,im,/c_map
;
;
; Plot an image with descreet greyscale values to a printer
; which has its own hard-wired color table.
im=randata(128,128,s=4)
immx=max(im) & immn=min(im)
!p.multi=[0,2,2]
tvim,im,/scale,colors=!p.color*indgen(4)/3.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(5)/4.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(8)/7.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(10)/9.,range=[immn,immx]
;
;
; Display a map of surface types (green=veg, blue=water, red=sand)
; Notice how RANGE is used to associate physical values with colors.
; (use im from the previous example)
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
tvlct,[0,0,0,255],[0,255,0,0],[0,0,255,0]
!p.multi=[0,2,2]
colors=[1,2,3] & labels=[' veg',' water',' sand']
range=[immn,immx,delim/3]
tvim,im,/scale
tvim,im,colors=colors,range=range,/scale
tvim,im,colors=colors,range=range,/scale,labels=labels,lch=2
!p.multi=0
range=[immn-.25*delim,immx+.25*delim,delim/2]
lbl=[' veg!c region 1',' water!c region 2',' sand!c region 3']
tvim,im,colors=colors,range=range,/scale,labels=lbl,lch=2,rmarg=2,pchar=1.2
;
;
; Display the image from previous example and overlay a contour plot
;
loadct,5
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
xrange=[-120,-100]
yrange=[20,50]
range=[immn,immx]
xx=findrng(xrange,128)
yy=findrng(yrange,128)
tvim,im,/scale,xrange=xrange,yrange=yrange,clevels=clevels,range=range
contour,im,xx,yy,levels=clevels,/overplot
; NOTE: You might prefer the results obtained from procedure CONFILL.
confill,im,xx,yy,/asp,levels=clevels
;
;
; Display a grey scale image and annotate certain points in color
;
loadct,0
dcolors
tvim,im,/scale,nbotclr=11
xx=interpolate([40,80],randomu(iseed,10))
yy=interpolate([40,80],randomu(iseed,10))
plots,xx,yy,psym=2,color=1+indgen(10)
;
;
; Display a grey scale image and show nodata values in red
;
loadct,0
im=randata(100,100,s=4.5)
im(randomu(iseed,50)*9999)=-999.
tvim,im,/scale,nodata=-999.,rgb_nodata=[255,0,0]
;
;
; Postscript output with a reversed color scale. Because the
; background color is always RGB=(255,255,255) you must set the
; default color, !p.color, to a dark color if you want good contrast
; between the axis labels and the white paper. According to
; Didier's reversed color table a color index of 255 should produce
; black, but for some reason !p.color=255 doesn't work right.
; I think IDL is iterpreting !p.color=255 in some special way.
; So instead use !p.color=254; this seems to work fine.
;
toggle,/color
loadct,28
!p.color=254 ; don't use 255, don't ask me why
tvim,dist(20),/scale
toggle
;
; display data defined on a regular LAT-LON grid onto a given map
; projection. USE MAP_SET and MAP_IMAGE to create the map projection
; and to warp the image. Then use BOXPOS to position the TVIM frame
; to correctly register the map and image
IMAGE = sin(!pi*findrng(0,24,200))#sin(!pi*findrng(0,12,200))
!p.multi=[0,1,2]
map_set,45,0,/ortho,/advance,pos=boxpos(/aspect)
newimage=map_image(image,/bilin,latmin=-90,latmax=90,lonmin=-180,lonmax=180)
tvim,newimage,title='Warped data',pos=boxpos(/get),/scale
map_set,45,0,/ortho,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
tvim,image,xrange=[-180,180],yrange=[-90,90],/scale, $
title='Unwarped data',xtitle='Longitude',ytitle='Latitude'
map_set,0,0,/cyl,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
; use MAP_SET2 to mask out land areas. Note that the example below is
; unusual. MAP_SET2 doesn't always produce such nicely filled land areas.
; Typically one must run MAP_SET2 with /SAVE
; to create a ascii file containing the continental boundary lat-lon
; coordinates. Then use an editor to group the continental coordinates
; line segments to form closed contours which POLYFILL can understand
; (the call to POLYFILL is enabled by setting con_color).
;
image=randata(256,256,s=2.5)
tvim,image
map_set2,-64,-64,/cont,limit=[-65.1,-64.5,-64,-62],/ortho,con_col=100,$
pos=boxpos(/get),/noerase,/grid
;
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS:
28jan93: switched from PUT_COLOR_SCALE to COLOR_KEY
11feb93: added INTERP keyword
11feb93: added C_MAP keyword
11feb93: added STITLE keyword
20apr93: added RMARG keyword, centered image in plot window
23apr93: call COLOR_KEY before TV. Now stepped color scales copy to PS file
10sep93: deal with perfectly flat images. No more math error when a=0
14sep93: added CLIP keyword
11feb94: added PCHARSIZE,LCHARSIZE,LABELS, and COLORS keywords
18feb94: added NBOTCLR keyword
16mar94: added INTERP=2 option and adjusted centering of pixels
08Jul94: added NODATA and RGB_NODATA keywords
04Aug94: added BARWIDTH keyword
04Aug94: defaulted PCHARSIZE and LCHARSIZE to !P.CHARSIZE if non-zero
02Mar95: added POSITION keyword
31Mar95: added NOAXIS keyword
24may95: initial sizing includes allowance for PCHARSIZE > 1
06sep95: color indecies used in plot now run from 1 to !d.ncolors-2
24jul96: do a REFORM(a) to allow tvim,a(1,*,*)
(See /home/drw/idl/bin/ptg/pg_tvim.pro)
PHIST[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PHIST
PURPOSE:
plot histogram
CALLING SEQUENCE:
phist,variable
INPUTS:
arr array to be plotted
KEYWORD INPUTS:
numbin number of histogram bins
binsize size of bins (nullifies effect NUMBIN)
xrange x value range on plot (implies xstyle=1)
yrange y value range on plot
percent show percentage histogram
cumulative show cumulative histogram
overplot plot this histogram over a previous plot
xtitle x title on plot
ytitle y title on plot
title title on plot
width width of the histogram bars (1 causes vertical bars
to fill the horizontal space, values less than 1 leave
space between bars)
EXAMPLE:
!p.multi=[0,2,2]
r=randomn(seed,2000)
phist,r
phist,r,/perc
phist,r,/perc,/cum
phist,r,yrange=[0,.5],binsize=.5,color=100,/per
phist,r^3,yrange=[0,.5],binsize=.5,color=150,/per,/over,width=.3
AUTHOR and DATE:
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/phist.pro)
PHIST[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PHIST
PURPOSE:
plot histogram
CALLING SEQUENCE:
phist,variable
INPUTS:
arr array to be plotted
KEYWORD INPUTS:
numbin number of histogram bins
binsize size of bins (nullifies effect NUMBIN)
xrange x value range on plot (implies xstyle=1)
yrange y value range on plot
percent show percentage histogram
cumulative show cumulative histogram
overplot plot this histogram over a previous plot
xtitle x title on plot
ytitle y title on plot
title title on plot
width width of the histogram bars (1 causes vertical bars
to fill the horizontal space, values less than 1 leave
space between bars)
EXAMPLE:
!p.multi=[0,2,2]
r=randomn(seed,2000)
phist,r
phist,r,/perc
phist,r,/perc,/cum
phist,r,yrange=[0,.5],binsize=.5,color=100,/per
phist,r^3,yrange=[0,.5],binsize=.5,color=150,/per,/over,width=.3
AUTHOR and DATE:
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/phist.pro)
PHUNWRAP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PHUNWRAP
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:
Unwrap phase jumps to recover cycle counts
MAJOR TOPICS:
Mathematics
CALLING SEQUENCE:
CYCLES = PHUNWRAP(PHASE, TOLERANCE=, MAXVAL=)
DESCRIPTION:
PHUNWRAP unwraps a sequence of phases to produce a new series of
cycle counts. Phase jumps due to crossing over the PHASE=0
boundary are removed by adding an integral number of cycles. The
algorithm is based on the MATLAB "unwrap" function.
NOTE: the unwrapping process can be ambiguous if there is a phase
jump of more than a half cycle in the series. For example, if the
phase changes by ~0.5 cycles, it is not possible to distinguish
whether there wasa +0.5 cycle or -0.5 cycle jump. The most
accurate unwrapping can be performed if the PHASE series is nearly
continuous and does not have rapid phase changes.
Users can select the tolerance used to determine the phase jump.
Users can also select the definition of "1 cycle" by changing
MAXVAL. By default, MAXVAL is 2*!DPI, which correspondes to 1
cycle = 2*!DPI radians, but other values of 1 (cycle), or 360
(degrees) are possible.
INPUTS:
PHASE - phase series to be unwrapped. Values should range from 0
to MAXVAL. The ordering of the series is important.
RETURNS:
A new series, expressed in cycles, with cycle jumps larger than
TOLERANCE removed.
OPTIONAL KEYWORDS:
TOLERANCE - phase jump tolerance. If the phase from one sample to
the next changes by more than TOLERANCE, then a single
cycle jump is assumed to have occurred.
DEFAULT: 0.5*MAXVAL
MAXVAL - Maximum value for phase. Common values are: 2*!DPI
(radians; DEFAULT); 1 (cycle); 360 (degrees), but any
positive value may be used.
EXAMPLE:
;; Set up some fake data
x = dindgen(100)/10d
y = x/2
ph = y MOD 1.0 ;; Mock phases
cycles = phunwrap(ph, maxval=1)
MODIFICATION HISTORY:
Written and documented, CM, July 2003
$Id: phunwrap.pro,v 1.2 2003/08/03 21:20:14 craigm Exp $
(See /home/drw/idl/aux/markwardt/phunwrap.pro)
PICKANUMBER
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
To read in a given section of the VTT/UBF FITS files, i.e.
a certain passband.
IMPUTS:
number - integer (0 to 7) specifying which band to read in
file_lo - the number of the first UBF file
file_hi - the number of the last UBF file
OUTPUTS:
data - the name of the 3D array into which the images
will go
HISTORY:
Author - D.Williams 29/2/2000 version 1.0
D.Williams 29/2/2000 version 1.1 - added the
flipping of the images to correspond to true
solar X and solar Y
(See /home/drw/idl/bin/pickanumber.pro)
PICKCOLOR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PICKCOLOR
PURPOSE:
A modal dialog widget allowing the user to select
the RGB color triple specifying a color. The return
value of the function is the color triple specifying the
color or the "name" of the color if the NAME keyword is set.
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:
Graphics, Color Specification. See related program GETCOLOR.
CALLING SEQUENCE:
color = PickColor(colorindex)
RETURN VALUE:
The return value of the function is a 1-by-3 array containing
the values of the color triple that specifies the selected color.
The color can be loaded, for example, in any color index:
color = PickColor(240)
TVLCT, color, 240
The return value is the original color triple if the user
selects the CANCEL button.
IF the NAMES keyword is set, the return value of the function is
the "name" of the selected color. This would be appropriate for
passing to the GetColor program, for example.
OPTIONAL INPUT POSITIONAL PARAMETERS:
COLORINDEX: The color index of the color to be changed. If not
specified the color index !D.Table_Size - 2 is used.
The Current Color and the Color Sliders are set to the
values of the color at this color index.
OPTIONAL INPUT KEYWORD PARAMETERS:
GROUP_LEADER: The group leader for this widget program. This
keyword is required for MODAL operation. If not supplied
the program is a BLOCKING widget. Be adviced, however, that
the program will NOT work if called from a blocking widget
program, unless a GROUP_LEADER is supplied.
NAMES: Set this keyword to return the "name" of the selected color
rather than its color triple.
STARTINDEX: Sixteen pre-determined colors are loaded The STARTINDEX
is the index in the color table where these 16 colors will
be loaded. By default, it is !D.Table_Size - 17.
TITLE: The title on the program's top-level base. By default the
title is "Pick a Color".
OPTIONAL INPUT KEYWORD PARAMETERS:
CANCEL: A keyword that is set to 1 if the CANCEL button is selected
and to 0 otherwise.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Sixteen pre-determined colors are loaded in the color table.
In addition, the color index at COLORINDEX is modified while
the program is on the display. When the program exits, the
entry color table is restored. Thus, on 8-bit displays there
might be some color effects in graphics windows while PICKCOLOR
is on the display. Changes in the color table are not noticable
on 16-bit and 24-bit displays.
EXAMPLE:
To specify a color for a plot in color decomposition OFF mode:
Device, Decomposed=0
!P.Color = !P.Color < (!D.Table_Size - 1)
color = PickColor(!P.Color, Cancel=cancelled)
IF NOT cancelled THEN BEGIN
TVLCT, color, !P.Color
Plot, data
ENDIF
To specify a color for a plot in color decomposition ON mode:
Device, Decomposed=1
color = PickColor(Cancel=cancelled)
!P.Color = Color24(color)
IF NOT cancelled THEN Plot, data
To obtain the name of the selected color to pass to GetColor:
selectedColor = PickColor(/Name)
axisColor = GetColor(selectedColor, !D.Table_Size-4)
MODIFICATION HISTORY:
Written by: David Fanning, 28 Oct 99.
Added NAME keyword. 18 March 2000, DWF.
Fixed a small bug when choosing a colorindex less than !D.Table_Size-17. 20 April 2000. DWF.
Added actual color names to label when NAMES keyword selected. 12 May 2000. DWF.
(See /home/drw/idl/aux/pickcolor.pro)
PICKCOLORNAME
[Previous Routine]
[Next Routine]
[List of Routines]
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. Valid names
depend on program variables, but typically include these colors:
Black Pink
Magenta Aqua
Cyan SkyBlue
Yellow Beige
Green Charcoal
Red Gray
Blue Orchid
Navy White
The color WHITE is used if this parameter is absent.
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.
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 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.
(See /home/drw/idl/aux/pickcolorname.pro)
PICKC[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pickc
PURPOSE: interactive adjustment of a series of discreet color values
USEAGE: pickc,colrng,labels=labels,group=group
INPUT:
colrng 2 element vector specifying the color index range accessable
to pickc (default=[0,!d.n_colors-1])
KEYWORD INPUT:
labels names to be associated with particular color indecies.
if labels are provided NN is reset to n_elements(LABELS).
group widget id of widget procedure that calls PICKC
OUTPUT: none
PROCEDURE:
When first called, PICKC will create a new IDL window
named "PICKC". A color wheel is drawn with hue values
varying from 1 - 360 degrees around the circle and
saturation values varying from 0 at the center to 1 at
the outer edge of the circle.
Motion of the cursor inside the PICKC window with the
with a mouse button pressed down adjusts the Hue and Saturation
values and leaves the brigtness unchanged.
Use the intensity slider to change the brightness.
Use the color index slider to select a new color index
BUTTONS:
DONE: save new RGB values and quit
UNDO: undo last RGB modification (hit it twice and all changes
are undone)
ANCHOR: add (or remove) current color index from list of anchor points
INTERP: interpolate between points on anchor list
HELP: print this text
EXAMPLE:
Make a color plot and use PICKC to adjust color values:
plot, [0,100],[-3,3],/nodata
d=findgen(100)
efac=exp(-((d-50)/20)^2)
oplot,3*sin(d/2)*efac,color=1,thick=3
oplot,sin(d/3)*efac,color=2,thick=3
oplot,sin(d/2)*efac,color=3,thick=3
oplot,3*efac,color=4,thick=3
oplot,efac,color=5,thick=3
oplot,-3*efac,color=4,thick=3
oplot,-efac,color=5,thick=3
r=[0,0,127,255,0,127] & g=[0,127,255,0,127,255] & b=[0,255,0,127,255,0]
tvlct,r,g,b
pickc,[1,5]
loadct,0
pickc ; choose a color index, change its RGB value, smear it
author: Paul Ricchiazzi 5feb93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/pickc.pro)
PICKC[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pickc
PURPOSE: interactive adjustment of a series of discreet color values
USEAGE: pickc,colrng,labels=labels,group=group
INPUT:
colrng 2 element vector specifying the color index range accessable
to pickc (default=[0,!d.n_colors-1])
KEYWORD INPUT:
labels names to be associated with particular color indecies.
if labels are provided NN is reset to n_elements(LABELS).
group widget id of widget procedure that calls PICKC
OUTPUT: none
PROCEDURE:
When first called, PICKC will create a new IDL window
named "PICKC". A color wheel is drawn with hue values
varying from 1 - 360 degrees around the circle and
saturation values varying from 0 at the center to 1 at
the outer edge of the circle.
Motion of the cursor inside the PICKC window with the
with a mouse button pressed down adjusts the Hue and Saturation
values and leaves the brigtness unchanged.
Use the intensity slider to change the brightness.
Use the color index slider to select a new color index
BUTTONS:
DONE: save new RGB values and quit
CANCEL: restore old RGB values and quit
XLOADCT: call the XLOADCT widget
DIFFUSE: smear the current color to adjacent color indicies
repeated clicks on DIFFUSE button causes the current
color to diffuse further along the color scale.
HELP: print this text
EXAMPLE:
Make a color plot and use PICKC to adjust color values:
plot, [0,100],[-3,3],/nodata
d=findgen(100)
efac=exp(-((d-50)/20)^2)
oplot,3*sin(d/2)*efac,color=1,thick=3
oplot,sin(d/3)*efac,color=2,thick=3
oplot,sin(d/2)*efac,color=3,thick=3
oplot,3*efac,color=4,thick=3
oplot,efac,color=5,thick=3
oplot,-3*efac,color=4,thick=3
oplot,-efac,color=5,thick=3
r=[0,0,127,255,0,127] & g=[0,127,255,0,127,255] & b=[0,255,0,127,255,0]
tvlct,r,g,b
pickc,[1,5]
loadct,0
pickc ; choose a color index, change its RGB value, smear it
author: Paul Ricchiazzi 5feb93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/pickc.pro)
PICKN
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pickn
PURPOSE: Short version of cursor,x,y,/norm,/down
USEAGE: pickn,x,y
INPUT:
OUTPUT: x and y coords of chosen point
Example:
AUTHOR: Peter T. Gallagher, May. '98
bastardised by DRW, Oct, 2000 as PICKN
(See /home/drw/idl/bin/pickn.pro)
PICKPEAKPOWER
[Previous Routine]
[Next Routine]
[List of Routines]
(See /home/drw/idl/aux/pickpeakpower.pro)
PICKPEAKSCALE
[Previous Routine]
[Next Routine]
[List of Routines]
(See /home/drw/idl/gen/pickpeakscale.pro)
PICK[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pick
PURPOSE: Short version of cursor,x,y,/data,/down
USEAGE: pick,x,y
INPUT:
OUTPUT: x and y coords of chosen point
Example:
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/pick.pro)
PICK[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pick
PURPOSE: Short version of cursor,x,y,/data,/down
USEAGE: pick,x,y
INPUT:
OUTPUT: x and y coords of chosen point
Example:
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/ptg/pick.pro)
PICK_CURSOR[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: pick_cursor
useage: pick_cursor
inputs: none
outputs: none
side effects:
changes the graphics cursor
procedure cycle through different cursor types by hitting the
the left or middle mouse button. Hit the right mouse button
to exit
author: Paul Ricchiazzi aug93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/pick_cursor.pro)
PICK_CURSOR[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: pick_cursor
useage: pick_cursor
inputs: none
outputs: none
side effects:
changes the graphics cursor
procedure cycle through different cursor types by hitting the
the left or middle mouse button. Hit the right mouse button
to exit
author: Paul Ricchiazzi aug93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/pick_cursor.pro)
PIXLOOPLENGTH
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
PIXLOOPLENGTH
PURPOSE:
to determine the approximate length, in pixels,
of a loop, based on Pythagoras' theorem. Ten points
are selected along the loop, and the routine determines
the intermediate distances, sums them and prints them to
the X window; both pixel length and approximate
real-length in kilometres are given assuming:
a) that the loop is in the plane of the image
b) that the angular diameter of a pixel is 0.5
arcseconds
c) that 1.0 arcsec in TRACE's FOV is equivalent
to 720km on the Sun.
CALLING SEQUENCE:
pixlooplength,frame
INPUTS:
frame - the image
in this case, the image is generated by zooming in to
the relevant area of the image using LOOPZOOM.PRO (see
documentation) but this is interchangeable with TVIM.PRO
since it is based on the pixels of the image, not the
display device.
CALLS:
PICK.PRO, by P.T. Gallagher to get X & Y values for each
mouse click.
AUTHOR:
David Williams, 4/6/99
(See /home/drw/idl/bin/pixlooplength.pro)
PLACETEXT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLACETEXT
PURPOSE:
Put text on a plot using LEGEND.PRO.
CALLING SEQUENCE:
placetext,'this is a test'
INPUTS:
text text to be written to screen. May either be string
array or string with different lines separated by '\'.
OPTIONAL INPUTS:
center lines are centered rather than left justified
(below are taken from legend.pro)
pos position and size of legend area in normalized data
coordinates. Format of this four element vector is
[x0,y0,x1,y1] where x0,y0 is the position of lower
left corner and x1,y1 is the position of the upper
right corner. For example pos=[.5,.5,.9,.9] specifies
a legend in the upper right quadrant of the data
window. If the POS parameter is not set or if POS is
set to zero, then the CURBOX procedure is called to
set the legend position interactively.
NOTE: the value of POS can be retrieved by setting POS
to a named variable which has an initial value of zero.
linestyle an array of linestyle types, one for each element of LABELS
psym an array of symbol types, one for each element of LABELS
color an array of color indices, one for each element of LABELS.
Any elements of COLOR set to -1 causes the default color,
!P.COLOR, to be used.
thick an array of line thicknesses, one for each element of LABELS
(default=!p.thick)
numsym number of symbol nodes used to indicate linestyle or symbol
type. The length of the line is measured in units of 4
character widths so that the length of the line
= 4*(NUMSYM-1) * X_CHARSIZE (default=3)
fg_color color of box and legend titles (default=!P.COLOR)
bg_color background color. Setting BG_COLOR erases the area
covered by the legend (filling it with color BG_COLOR)
prior to writing the legend. If both BG_COLOR and !p.color
are zero then the background color is reset to 255 to
gaurantee a readability.
box if set draw a box around the legend text
ystretch factor by which to increase vertical spacing of legend
entries. (default = 1)
silent if set, don't print anything to the terminal
OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 2/22/94
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/placetext.pro)
PLACETEXT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLACETEXT
PURPOSE:
Put text on a plot using LEGEND.PRO.
CALLING SEQUENCE:
placetext,'this is a test'
INPUTS:
text text to be written to screen. May either be string
array or string with different lines separated by '\'.
OPTIONAL INPUTS:
center lines are centered rather than left justified
(below are taken from legend.pro)
pos position and size of legend area in normalized data
coordinates. Format of this four element vector is
[x0,y0,x1,y1] where x0,y0 is the position of lower
left corner and x1,y1 is the position of the upper
right corner. For example pos=[.5,.5,.9,.9] specifies
a legend in the upper right quadrant of the data
window. If the POS parameter is not set or if POS is
set to zero, then the CURBOX procedure is called to
set the legend position interactively.
NOTE: the value of POS can be retrieved by setting POS
to a named variable which has an initial value of zero.
linestyle an array of linestyle types, one for each element of LABELS
psym an array of symbol types, one for each element of LABELS
color an array of color indices, one for each element of LABELS.
Any elements of COLOR set to -1 causes the default color,
!P.COLOR, to be used.
thick an array of line thicknesses, one for each element of LABELS
(default=!p.thick)
numsym number of symbol nodes used to indicate linestyle or symbol
type. The length of the line is measured in units of 4
character widths so that the length of the line
= 4*(NUMSYM-1) * X_CHARSIZE (default=3)
fg_color color of box and legend titles (default=!P.COLOR)
bg_color background color. Setting BG_COLOR erases the area
covered by the legend (filling it with color BG_COLOR)
prior to writing the legend. If both BG_COLOR and !p.color
are zero then the background color is reset to 255 to
gaurantee a readability.
box if set draw a box around the legend text
ystretch factor by which to increase vertical spacing of legend
entries. (default = 1)
silent if set, don't print anything to the terminal
OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 2/22/94
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/placetext.pro)
PLANCK[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: planck
USEAGE: result=planck(ww,t [,/microns])
INPUT:
ww wavenumber (cm-1) or wavelength (microns) if /microns set,
can be either scalar or vector
t temperature (degrees K), can be scalar or vector.
OUTPUT:
result black body spectral intensity, commonly known as the
Planck function
microns set microns not set
----------- ---------------
units: W/m2/sr/micron W/m2/sr/cm-1
UNIT CONVERSION FACTORS:
W/m2/sr/cm-1 x 1000 = erg/s/cm2/sr/cm-1
W/m2/sr/micron x 1000 = erg/s/cm2/sr/micron
W/m2/sr/micron = erg/s/cm2/sr/nm
the spectral flux generated by a black body surface is = pi * planck
; EXAMPLE
; plot black body curve for a 300, 280 and 260 degrees K.
w=findrng(10000/333.33,10000/4.,200)
plot,w,planck(w,300),xtitle='wavenumber (cm!a-1!n)',ymargin=[10,2],$
ytitle='W/m!a2!n/sr/cm!a-1!n',title='Black Body Radiance'
AXIS,0,4*!d.y_ch_size,XAX=0,/dev,xtickv=[0,10000./[50,20,13,10,8,6,5,4]],$
xticks=8,xtickn=[' ','50','20','13','10','8','6','5','4'],$
xtitle='wavelength (microns)'
oplot,w,planck(w,280),li=3
oplot,w,planck(w,260),li=4
legend,'.cBlack Body\.cTemperature\\300\280\260',li=[0,3,4],pos=[.7,.6,.9,.9]
; planck function for one of the sbdart standard atmospheres
atmosz,idatm=4,zz,pp,tt
!p.multi=[0,2,2] & yt='Altititude (km)' & xt='W/m!a2!n/sr'
plot,planck(3,tt,/mic),zz,title='!7k!x = 3um',ytit=yt
plot,planck(4,tt,/mic),zz,title='!7k!x = 4um'
plot,planck(5,tt,/mic),zz,title='!7k!x = 5um',ytit=yt,xtit=xt
plot,planck(15,tt,/mic),zz,title='!7k!x = 15um',xtit=xt
author: Paul Ricchiazzi 3dec92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/planck.pro)
PLANCK[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: planck
USEAGE: result=planck(ww,t [,/microns])
INPUT:
ww wavenumber (cm-1) or wavelength (microns) if /microns set,
can be either scalar or vector
t temperature (degrees K), can be scalar or vector.
OUTPUT:
result black body spectral intensity, commonly known as the
Planck function
microns set microns not set
----------- ---------------
units: W/m2/sr/micron W/m2/sr/cm-1
UNIT CONVERSION FACTORS:
W/m2/sr/cm-1 x 1000 = erg/s/cm2/sr/cm-1
W/m2/sr/micron x 1000 = erg/s/cm2/sr/micron
W/m2/sr/micron = erg/s/cm2/sr/nm
the spectral flux generated by a black body surface is = pi * planck
; EXAMPLE
; plot black body curve for a 300, 280 and 260 degrees K.
w=findrng(10000/333.33,10000/4.,200)
plot,w,planck(w,300),xtitle='wavenumber (cm!a-1!n)',ymargin=[10,2],$
ytitle='W/m!a2!n/sr/cm!a-1!n',title='Black Body Radiance'
AXIS,0,4*!d.y_ch_size,XAX=0,/dev,xtickv=[0,10000./[50,20,13,10,8,6,5,4]],$
xticks=8,xtickn=[' ','50','20','13','10','8','6','5','4'],$
xtitle='wavelength (microns)'
oplot,w,planck(w,280),li=3
oplot,w,planck(w,260),li=4
legend,'.cBlack Body\.cTemperature\\300\280\260',li=[0,3,4],pos=[.7,.6,.9,.9]
; planck function for one of the sbdart standard atmospheres
atmosz,idatm=4,zz,pp,tt
!p.multi=[0,2,2] & yt='Altititude (km)' & xt='W/m!a2!n/sr'
plot,planck(3,tt,/mic),zz,title='!7k!x = 3um',ytit=yt
plot,planck(4,tt,/mic),zz,title='!7k!x = 4um'
plot,planck(5,tt,/mic),zz,title='!7k!x = 5um',ytit=yt,xtit=xt
plot,planck(15,tt,/mic),zz,title='!7k!x = 15um',xtit=xt
author: Paul Ricchiazzi 3dec92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/planck.pro)
PLOT3D_ROT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: plot3d_rot
PURPOSE: plot a 3-D trajectory and rotate plot interactively
USEAGE: plot3d_rot,xx,yy,zz
INPUT:
xx,yy,zz
vector trajectory of path
KEYWORD INPUT:
title
title string
dang
angle increment between successive rotations (default=5)
cang
constant angle of rotation of the xyz coordinate axis about z-axis.
(default=30)
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
x=randf(30,3)
y=randf(30,3)
z=randf(30,3)
plot3d_rot,x,y,z
plot3d_rot,x,y,z,/continuous
AUTHOR: Paul Ricchiazzi 11 Apr 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/plot3d_rot.pro)
PLOT3D_ROT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: plot3d_rot
PURPOSE: plot a 3-D trajectory and rotate plot interactively
USEAGE: plot3d_rot,xx,yy,zz
INPUT:
xx,yy,zz
vector trajectory of path
KEYWORD INPUT:
title
title string
dang
angle increment between successive rotations (default=5)
cang
constant angle of rotation of the xyz coordinate axis about z-axis.
(default=30)
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
x=randf(30,3)
y=randf(30,3)
z=randf(30,3)
plot3d_rot,x,y,z
plot3d_rot,x,y,z,/continuous
AUTHOR: Paul Ricchiazzi 11 Apr 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/plot3d_rot.pro)
PLOTBIN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTBIN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Makes a plot in a histogram style.
CALLING SEQUENCE:
PLOTBIN, x, y, WIDTH=width, PIXCENTER=pixcenter, ...
DESCRIPTION:
PLOTBIN makes an unfilled histogram plot. The width of each
histogram bin can be specified individually, and the alignment of
the bin centers can be given explicitly.
PLOTBIN accepts several specialized keyword parameters of its own,
but passes any other keywords to the built-in IDL PLOT procedure.
Thus, any keywords accepted by PLOT can be passed to PLOTBIN.
PLOTBIN uses the PANEL/SUBPANEL system to partition the viewport.
INPUTS:
X, Y - Two arrays which give the "X" and "Y" position of each bin.
If only the Y values are given, then the X values will be
the bin numbers.
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
PANEL, SUBPANEL - An alternate way to more precisely specify the
plot and annotation positions. See SUBCELL.
Default is full-screen. Overridden by POSITION.
WIDTH - The width of each histogram bin. If a scalar, then the
width is assumed to be the same for all histogram bins.
If a vector, then WIDTH should have the same number of
elements as X and Y, and specify the width of each
individual bin.
Default value: width is the separation between the first
two X values.
PIXCENTER - Describes the alignment of "X" values with respect to
the histogram bin centers:
PIXCENTER = 0.0 -- "X" values are left edges of bins
= 0.5 -- "X" values are bin centers
= 1.0 -- "X" values are right edges of bins
Intermediate values are also permitted.
Default value: 0.5 ("X" values are bin centers)
MIDPOINT - if set, then ignore the WIDTH and PIXCENTER keyword
values, and instead construct bin edges which lie at
the midpoints between data points. This is usually the
most straightforward way to connect irregularly sampled
points "like a histogram," although at the expense of
not having a direct relation between X and the bin
centers.
EDGE - if set, then the X values will be taken to be the bin edges
rather than the bin midpoints. In this case, the number of
X values should be one more than the number of Y values.
Other options are passed along to the PLOT command directly.
OUTPUTS:
NONE
PROCEDURE:
EXAMPLE:
SEE ALSO:
SUBCELL, DEFSUBCELL, SUBCELLARRAY
EXTERNAL SUBROUTINES:
PLOT, SUBCELL
MODIFICATION HISTORY:
Written, CM, 1997
Documented, CM, July 1999
Added MIDPOINT keyword, 21 Feb 2000
Added EDGE keyword, 21 Apr 2000
Corrected way that PIXCENTER works (Thanks to
J. Guerber), CM, 28 Mar 2002
Changed _EXTRA handling to use EXECUTE internally. Unfortunately
makes it incompatible with VM version of IDL, 03 Aug 2003, CM
Remove EXECUTE function, move to CALL_PROCEDURE, 23 Nov 2003, CM
$Id: plotbin.pro,v 1.5 2003/11/24 00:30:12 craigm Exp $
(See /home/drw/idl/aux/markwardt/plotbin.pro)
PLOTBLINK
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: plotblink
PURPOSE: blink plot of two quantities,
especially useful for dense scatter plots
USEAGE: plotblink,x1,y1,x2,y2,t1=t1,t2=t2
INPUT:
x1 x coordinate vector of first plot
y1 y coordinate vector of first plot
x2 x coordinate vector of second plot
y2 y coordinate vector of second plot
t1 title of first quantity
t2 title of second quantty
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
;;
x1=randomn(iseed,1000)
y1=randomn(iseed,1000)
x2=randomn(iseed,1000)
y2=randomn(iseed,1000)
rr=1.+.05/(.01+x2^2+y2^2)
x2=x2*rr
y2=y2*rr
plotblink,x1,y1,x2,y2,'case 1','case 2'
;;
AUTHOR: Paul Ricchiazzi 23 Aug 00
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/plotblink.pro)
PLOTCOLORFILL[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTCOLORFILL
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Plots colorful bar charts
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. If only
one data value is present, then a width of 1 is used.
MIDPOINT - if set, then ignore the WIDTH keyword value, and
instead construct bin edges which lie at the midpoints
between data points. This is usually the most
straightforward way to connect irregularly sampled
points "like a histogram," although at the expense of
not having a direct relation between X and the bin
centers.
NOERASE - if set, do not erase an existing plot before rendering
colored histogram. The effect is comparable to "OPLOT",
or the OVER keyword to CONTOUR.
NOTRACE - if set, do not draw a linear trace at the top of the
histogram.
TRANSPARENT - designates a color which is "transparent". Any bars
with this color are simply not rendered. 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.
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
MODIFICATION HISTORY:
Written, CM, 1997
Added NOERASE, NOTRACE and MIDPOINT keywords, CM 11 Feb 2000
(See /home/drw/idl/esrg/plotcolorfill.pro)
PLOTCOLORFILL[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTCOLORFILL
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Plots colorful bar charts
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. If only
one data value is present, then a width of 1 is used.
MIDPOINT - if set, then ignore the WIDTH keyword value, and
instead construct bin edges which lie at the midpoints
between data points. This is usually the most
straightforward way to connect irregularly sampled
points "like a histogram," although at the expense of
not having a direct relation between X and the bin
centers.
NOERASE - if set, do not erase an existing plot before rendering
colored histogram. The effect is comparable to "OPLOT",
or the OVER keyword to CONTOUR.
NOTRACE - if set, do not draw a linear trace at the top of the
histogram.
TRANSPARENT - designates a color which is "transparent". Any bars
with this color are simply not rendered. 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.
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
MODIFICATION HISTORY:
Written, CM, 1997
Added NOERASE, NOTRACE and MIDPOINT keywords, CM 11 Feb 2000
Logarithmic plots now work; so does the THICK keyword, CM 02 Apr
2001
Optimize drawing when the bin is zero, CM 04 Apr 2001
Try to handle YRANGE more properly, since there seem to be some
cases where the overlayed axes were erroneous, CM 15 Mar 2002
This time YRANGE tweaking with PANELs, CM 13 Jun 2002
$Id: plotcolorfill.pro,v 1.8 2003/09/06 16:36:19 craigm Exp $
(See /home/drw/idl/aux/markwardt/plotcolorfill.pro)
PLOTCOMPARE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTCOMPARE
PURPOSE:
Scatter plot two similar variables, print statistics.
CALLING SEQUENCE:
plotcompare,xquantity,yquantity
INPUTS:
xquantity variable to plot along x-axis
yquantity variable to plot along y-axis
KEYWORD INPUTS:
hist plot as 2D histogram (xrange, yrange turned off)
bindim number of bins on one side for 2D histogram
tvim display 2D histogram as image (default is contour plot)
interactive interactively set the statistics legend
pos after locating legend with interactive keyword, specify
legend location with this
bigtext print statistics with bigger font
widetext print statistics with wider font for use in printouts
below are plot keywords:
title
ymargin
xtitle
ytitle
xrange
yrange
psym
OPTIONAL INPUTS:
OUTPUTS:
OPTIONAL OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 1/04/94
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/plotcompare.pro)
PLOTCOMPARE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTCOMPARE
PURPOSE:
Scatter plot two similar variables, print statistics.
CALLING SEQUENCE:
plotcompare,xquantity,yquantity
INPUTS:
xquantity variable to plot along x-axis
yquantity variable to plot along y-axis
KEYWORD INPUTS:
hist plot as 2D histogram (xrange, yrange turned off)
bindim number of bins on one side for 2D histogram
tvim display 2D histogram as image (default is contour plot)
interactive interactively set the statistics legend
pos after locating legend with interactive keyword, specify
legend location with this
bigtext print statistics with bigger font
widetext print statistics with wider font for use in printouts
below are plot keywords:
title
ymargin
xtitle
ytitle
xrange
yrange
psym
OPTIONAL INPUTS:
OUTPUTS:
OPTIONAL OUTPUTS:
EXAMPLE:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 1/04/94
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/plotcompare.pro)
PLOTCUBE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTCUBE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Plots a three dimensional data that can be printed and made into a cube
CALLING SEQUENCE:
PLOTCUBE, x, y, z
DESCRIPTION:
PLOTCUBE plots a three dimensional data set so that it can be
printed on paper, cut out, and folded together to make a real-life
three dimensional cube. This may be useful in visualization
applications. The six faces of the cube contain a projection of
the data onto that face.
The output consists of a flat matrix of six plots, which are
joined together at the proper edges of the cube. Your task,
should you choose to accept it, is to cut out the cube and
assemble it.
Before folding the cube together, it will look like the diagram
below. You need to match together edges labelled with the same
letter.
A
+----+
B| |G
B | | G
+----+----+----+
| | | |
C| | | |E
+----+----+----+
D | | F
D| |F
+----+
| |
C| |E
+----+
A
HINT 1: When printing, be sure that the XSIZE and YSIZE are given
in the ratio of 3 to 4. A size of 6 in by 8 in is
suitable.
HINT 2: As a practical matter for assembling the cube once it has
been printed, you should leave some extra paper tabs so
that adhesive can be applied.
INPUTS:
X, Y, Z - Three arrays which specify position in three dimensional
space. All three arrays should be of the same length.
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
PANEL, SUBPANEL - An alternate way to more precisely specify the
plot and annotation positions. See SUBCELL.
Default is full-screen.
XRANGE, YRANGE, ZRANGE - gives plot range for each dimension, as
for other plot commands. Default is
range of data.
XTITLE, YTITLE, ZTITLE - gives title for each axis. The title
labels each face of the cube where
possible.
NOERASE - If set, the display is not erased before graphics
operations.
Other options are passed along to the PLOT command directly.
OUTPUTS:
NONE
PROCEDURE:
EXAMPLE:
This example takes some synthetic data and makes a cube out of it.
Visualizing the trace of the curve is more convenient when it can
be projected on the cube in each dimension.
t = findgen(200)/20. - 10.
x = cos(t)
y = sin(t) + 0.05*t
z = exp(t) + 0.05*randomn(seed, 200)
plotcube, x, y, z, xrange=[-1.5,1.5], yrange=[-1.5,1.5], zrange=[-1.5,1.5]
SEE ALSO:
DEFSUBCELL, SUBCELLARRAY
EXTERNAL SUBROUTINES:
SUBCELL, DEFSUBCELL, PLOTPAN
MODIFICATION HISTORY:
Written, CM, 1997
Modified to include SUBCELL, DEFSUBCELL and PLOTPAN when
distributed, CM, late 1999
(See /home/drw/idl/esrg/plotcube.pro)
PLOTCUBE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTCUBE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Plots a three dimensional data that can be printed and made into a cube
CALLING SEQUENCE:
PLOTCUBE, x, y, z
DESCRIPTION:
PLOTCUBE plots a three dimensional data set so that it can be
printed on paper, cut out, and folded together to make a real-life
three dimensional cube. This may be useful in visualization
applications. The six faces of the cube contain a projection of
the data onto that face.
The output consists of a flat matrix of six plots, which are
joined together at the proper edges of the cube. Your task,
should you choose to accept it, is to cut out the cube and
assemble it.
Before folding the cube together, it will look like the diagram
below. You need to match together edges labelled with the same
letter.
A
+----+
B| |G
B | | G
+----+----+----+
| | | |
C| | | |E
+----+----+----+
D | | F
D| |F
+----+
| |
C| |E
+----+
A
HINT 1: When printing, be sure that the XSIZE and YSIZE are given
in the ratio of 3 to 4. A size of 6 in by 8 in is
suitable.
HINT 2: As a practical matter for assembling the cube once it has
been printed, you should leave some extra paper tabs so
that adhesive can be applied.
INPUTS:
X, Y, Z - Three arrays which specify position in three dimensional
space. All three arrays should be of the same length.
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
PANEL, SUBPANEL - An alternate way to more precisely specify the
plot and annotation positions. See SUBCELL.
Default is full-screen.
XRANGE, YRANGE, ZRANGE - gives plot range for each dimension, as
for other plot commands. Default is
range of data.
XTITLE, YTITLE, ZTITLE - gives title for each axis. The title
labels each face of the cube where
possible.
NOERASE - If set, the display is not erased before graphics
operations.
Other options are passed along to the PLOT command directly.
OUTPUTS:
NONE
PROCEDURE:
EXAMPLE:
This example takes some synthetic data and makes a cube out of it.
Visualizing the trace of the curve is more convenient when it can
be projected on the cube in each dimension.
t = findgen(200)/20. - 10.
x = cos(t)
y = sin(t) + 0.05*t
z = exp(t) + 0.05*randomn(seed, 200)
plotcube, x, y, z, xrange=[-1.5,1.5], yrange=[-1.5,1.5], zrange=[-1.5,1.5]
SEE ALSO:
DEFSUBCELL, SUBCELLARRAY
EXTERNAL SUBROUTINES:
SUBCELL, DEFSUBCELL, PLOTPAN
MODIFICATION HISTORY:
Written, CM, 1997
Modified to include SUBCELL, DEFSUBCELL and PLOTPAN when
distributed, CM, late 1999
$Id: plotcube.pro,v 1.2 2001/03/25 18:10:44 craigm Exp $
(See /home/drw/idl/aux/markwardt/plotcube.pro)
PLOTIMAGE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTIMAGE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Displays an image via a "PLOT"-like interface.
CALLING SEQUENCE:
PLOTIMAGE, img, [xrange=xrange,] [yrange=yrange,] ...
DESCRIPTION:
PLOTIMAGE displays an image (or slice of an image) on the current
graphics device. The syntax is very similar to the PLOT command,
in the sense that an XRANGE and YRANGE for the plot can be
specified.
More importantly, coordinate ranges can be specified for the
*image* itself, and then PLOTIMAGE will intelligently crop the
image so that only the part that falls within the XRANGE and
YRANGE is displayed. Images often have physical units (other than
pixels) assigned to their X and Y dimensions. PLOTIMAGE allows
you to slice the image appropriately and display appropriate
coordinate axes.
Image coordinates are specified via the IMGXRANGE and IMGYRANGE
keywords. IMGXRANGE specifies the x-values for the first and last
pixels in each row. IMGYRANGE gives the y-values for the first
and last pixels in each column. Default image coordinates are in
units of pixels.
Plot coordinates are specified in the usual XRANGE and YRANGE
keywords. The [XY]RANGE may specify a range smaller than the
image size, so that the image is cropped; or a range larger than
the image size, in which case the appropriate portion of the image
is displayed.
Psuedocolor images may be of any type, but must rescaled to a byte
range by using the RANGE keyword. By default the color range used
in the rescaling operation is 0 to !D.N_COLORS - 3B. The extra
two color values are reserved for the background and default pen
colors. This behavior can be adjusted by specifying the BOTTOM
and/or NCOLORS keywords.
Truecolor images must always be of type BYTE and one of their
dimensions must have 3 elements, corresponding to the three color
planes of the image.
INPUTS:
IMG - Array to be displayed. For single-plane images (i.e.,
pseudocolor), the image must be two dimensional and of any
real numeric type. For images that are not of BYTE type,
the RANGE keyword must be supplied to rescale the image
values to a byte range.
An image declared as ARRAY(NX,NY) will be NX pixels in the
x-direction and NY pixels in the y-direction. The image is
resampled to fill the desired display region (and optionally
smoothed).
For three-plane images (i.e., truecolor) the image must be
of type BYTE. One of the dimensions of the array must have
three elements. Hence it must be one of BYTARR(NX, NY, 3),
BYTARR(NX, 3, NY) or BYTARR(3, NX, NY). The 3-element
dimension is recognized automatically.
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
IMGXRANGE, IMGYRANGE - Each is a two component vector that
describes the X and Y position of the outer
edges of the first and last pixels.
Default: [0, NUM_[XY]PIX] for IMG[XY]RANGE
XRANGE, YRANGE - Each is a two component vector that specifies the
X and Y plot ranges, respectively. These values
are not required to coincide with IMG[XY]RANGE.
Default: IMG[XY]RANGE
POSITION - Position of the inner plot window in the standard
graphics keyword format. Overrides PANEL and SUBPANEL.
INTERP - if set, interpolate (smooth) the image before displaying.
This keyword applies to the screen displays. For printed
images that are coarser than MIN_DPI, the image is
implicitly interpolated regardless of INTERP.
PRESERVE_ASPECT - if set, preserve the aspect ratio of the
original image (in pixels). The result will be
the largest image that fits in the display
region while maintaining approximately square
pixels. The POSITION keyword will be reset upon
output to the ultimate image position.
MIN_DPI - if printing, the minimum dot-per-inch pixel resolution
for the resulting image. Output images that would be
coarser than this value are resampled to be at least
MIN_DPI and smoothed. Some common resolutions are:
screen, 90 dpi; dot matrix, 72 dpi; laser printer
300-600 dpi. Note that large values of MIN_DPI will
produce very large output files.
Default: 0 (i.e., the output image will not be smoothed)
RANGE - a two element vector. If the image is single plane (i.e.,
pseudocolor) the input image can be of any real numeric
type, and then must be rescaled into byte range with this
keyword. In contrast, truecolor images must always be of
type BYTE. Values are scaled into byte range with the
following statement:
RESULT = BYTSCL(INPUT, MIN=RANGE(0), MAX=RANGE(1), $
TOP=NCOLORS-1) + BOTTOM
so that pixels with an intensity RANGE(0) are set to
BOTTOM; those with RANGE(1) are set to the maximum color.
Default: no range scaling occurs (and the image must hence
be of type BYTE -- otherwise an error occurs)
NCOLORS - number of color table values be used in the byte
rescaling operation.
Default: !D.N_COLORS - BOTTOM - 1 (for default pen color)
BOTTOM - bottom-most value of the color table to be used in the
byte rescaling operation.
Default: 1 (for default background color)
NOERASE - If set, the display is not erased before graphics
operations.
NODATA - If set, the image is not actually displayed, but
coordinate axes may be drawn.
NOAXES - An attempt is made to render the image without coordinate
axes. This is possible if POSITION, PANEL, or SUBPANEL
are given.
PANEL, SUBPANEL - An alternate way to more precisely specify the
plot and annotation positions. See SUBCELL.
PLOTIMAGE will pass other keywords directly to the PLOT command
used for generating the plot axes. XSTYLE=1 and YSTYLE=1 are
enforced.
OUTPUTS:
NONE
PROCEDURE:
EXAMPLE:
This example constructs an image whose values are found by
z(x,y) = cos(x) * sin(y)
and x and y are in the range [-2,2] and [4,8], respectively.
The image is then plotted, with appropriate axes.
x = findgen(20)/5. - 2. + .1 ; 0.1 = half-pixel
y = findgen(20)/5. + 4. + .1
zz = cos(x) # sin(y)
imgxrange = [-2.,2.] ; extend to pixel edges
imgyrange = [4.,8.]
plotimage, bytscl(zz), imgxrange=imgxrange, imgyrange=imgyrange
This second example plots the same image, but with a plot range
much larger than the image's.
xr=[-10.,10]
yr=[-10.,10]
plotimage, bytscl(zz), imgxrange=imgxrange, imgyrange=imgyrange, $
xrange=xr, yrange=yr
SEE ALSO:
OPLOTIMAGE, BYTSCL
EXTERNAL SUBROUTINES:
SUBCELL, DEFSUBCELL
MODIFICATION HISTORY:
Written, CM, 1997
Correct various one-off problems, 02 Feb 1999, CM
Made self-contained with some pre-processing, 17 Oct 1999, CM
Corrected bug in newly introduced CONGRID functions, 18 Oct 1999, CM
Correct behavior with no POSITION keyword, 17 Nov 1999, CM
Simplified axis plotting, 17 Nov 1999, CM
Use _EXTRA keyword in first PLOT, but with blank TITLEs, 11 Jan
2000, CM
Correct implementation of X/YSTYLE in first PLOT, 11 Feb 2000, CM
Correct CONGRID implementation (small effect when enlarging most
images), 14 Feb 2000, CM
Major changes: 19 Apr 2000
- now handle decomposed color, automatic color mapping via
RANGE, and 24-bit multiplane images
- new PRESERVE_ASPECT keyword to keep square pixels
- removed legacy TVIMAGE code
- smoothing is more configurable, esp. for printers, but is not
done by default; more printers are supported
Corrected INTERPOLATE behavior (thanks to Liam Gumley
), other minor tweaks, CM 20 Apr 2000
Added ability to use PRESERVE_ASPECT with POSITION, PANEL or
SUBPANEL keywords CM 20 Oct 2000
Oops, a typo is now fixed, CM 23 Oct 2000
Add fix for MacIntoshes and DECOMPOSED color, Tupper, 02 Aug 2001
Better behavior with fractional pixels (ie, when the image pixels
are very large compared to the screen), 23 Aug 2001
Add support for Z buffer, CM, 20 Oct 2002
Memory conservation: use REVERSE() to reverse IMG; rewrote
PLOTIMAGE_RESAMP to rescale entire image instead of each color plane
separately. Jeff Guerber, 30 July 2003
$Id: plotimage.pro,v 1.7 2003/08/03 20:12:11 craigm Exp $
(See /home/drw/idl/aux/markwardt/plotimage.pro)
PLOTIMAGE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTIMAGE
PURPOSE:
This procedure makes a PostScript file of all or part of an image.
CATEGORY:
Plotting.
CALLING SEQUENCE:
PLOTIMAGE, Image, Number, Binning, Title
INPUTS:
Image: The two dimensional image to plot.
Number: The number of pieces to break the image into (in x).
Binning:Bin by this factor in both x and y before plotting.
Title: Title of plot
KEYWORD PARAMETERS:
PAGE: By default, this procedure prints the entire image on one
page. If PAGE is set to a number other than -1, however, it
prints it on Number pages, and only page PAGE is printed on
this call.
PAGESCALE:
If set, individually scale the page to the maximum pixel on
that page. By default, the scaling is to the maximum pixel on
any page.
....... This procedure also accepts all keywords that ARRAYPS accepts.
These include MTITLE, XTITLE, YTITLE, MINC, MAXC, XSCALE,
YSCALE, CBAR, SQUARE, LANDSCAPE, XPSIZE, YPSIZE, XMIN,
XMAX, YMIN, YMAX, LOG, VERBOSE, ENCAPSULATED, BLINE,
BTEXT1, TLINE, TTEXT1, and all keywords that PLOT accepts.
SIDE EFFECTS:
Creates a PostScript file.
PROCEDURE:
EXAMPLE:
MODIFICATION HISTORY:
Written by David Sahnow, 3 February 1997.
7 February 1997 Changed so that newimage isn't always an integer
20 March 1997 Scaled image before rebinning so pixels with few
counts don't disappear in rebinning. Added call to dateit.
31 March 1997 Added Title input, replacing use of infile.
16 May 1997 Added memtime calls.
6 June 1997 Fixed bug which resulted in 'bin by nn' being added
multiple times if routine was called more than once.
19 June 1997 Fixed bug introduced in previous bug fix - title
was not printed when no binning was done.
20 June 1997 Removed 'x' and 'y' for x and y axis labels in order
to avoid x1,x2, etc. labels on plots
14 November 1997 Moved definition of arrtype after rebinning
to avoid integer wrapping problems. Changed all calls to MEMTIME
to occur only if /VERBOSE is set.
18 November 1998 Removed /LANDSCAPE in call to ARRAYPS. _EXTRA
keyword should still allow landscape plots to work
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/plotimage.pro)
PLOTPAGE
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: plotpage
PURPOSE:
USEAGE: plotpage,x,y,npage=npage
INPUT:
x variable ploted along x-axis
y variable ploted along y-axis,
if y is an 2-d array then
plot,x,y(*,0)
oplot,x,y(*,1)
oplot,x,y(*,2)...
KEYWORD INPUT:
npage suggested number of pages into which horizontal range of
plot is broken. the actual number of pages is chosen to
make the x range values come out to nice even numbers.
xrange x axis range which will be broken up into pages
yrange either a vector specifying y range, or a scalor. If
yrange is set to a scalor (e.g., /yrange) then the yrange
adapts to the y variable range appropriate to each page.
All other plot keywords are also accepted and passed to
the plot procedure.
KEYWORD OUTPUT:
xrng the x-axis range that corresponds to the last active page
before plotpage is terminated.
DISCUSSION:
use plotpage to page through pages of a very high density
plot. New pages (i.e., the next increment in the x-range
of the plot) are selected by the middle (forward) or left
(backward) mouse button. The number of plot pages in which
to break the horizontal range of the plot is selected with
the keyword parameter npage.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
solar,x,y
plotpage,x,y,npage=100
AUTHOR: Paul Ricchiazzi 24 Feb 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/plotpage.pro)
PLOTPAN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTPAN
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Same as PLOT command, but respects PANEL and SUBPANEL
CALLING SEQUENCE:
PLOTPAN, x, y, ...
DESCRIPTION:
PLOTPAN is almost identical to PLOT, except that it accounts for
panels and subpanels in the display. In fact, after a short
calculation, PLOTPAN calls PLOT to do its dirty work.
Once the coordinate grid has been set up by PLOTPAN, other plots
can be overlaid by calling OPLOT.
INPUTS:
X, Y - Two arrays which give the x and y position of each point.
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
PANEL, SUBPANEL - An alternate way to more precisely specify the
plot and annotation positions. See SUBCELL.
Default is full-screen. Overridden by POSITION.
Other options are passed along to the PLOT command directly.
OUTPUTS:
NONE
PROCEDURE:
EXAMPLE:
SEE ALSO:
SUBCELL, DEFSUBCELL, SUBCELLARRAY
EXTERNAL SUBROUTINES:
PLOT, SUBCELL
MODIFICATION HISTORY:
Written, CM, 1997
Added copyright notice, 25 Mar 2001, CM
$Id: plotpan.pro,v 1.2 2001/03/25 18:54:31 craigm Exp $
(See /home/drw/idl/aux/markwardt/plotpan.pro)
PLOTRATE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PLOTRATE
PURPOSE:
This procedure plots the count rate from a detector time tag data file,
or from an array previously created with READIT.
CATEGORY:
Detector.
CALLING SEQUENCE:
PLOTRATE, Infile, Data, Time, Rate
INPUTS:
Infile: Name of a time tag file. If infile is a vector of file
names, the data from all of these files will be combined
before making the rate plot.
OPTIONAL OUTPUTS:
Data: A structure containing the raw data.
Time: A vector containing the time for each element of Rate
Rate: A vector containing the count rate.
KEYWORDS:
INPUTDATA:
If this keyword is set equal to a structure containing time
tag data (such as that created by READIT), this data is used
instead of reading Infile. This can be used to save time
by reading the data once, and then plotting multiple times.
Note that Infile is still used in the title of the plot.
TIMESTEP:
Display the rates binned over this time interval in
seconds. If not set, TIMESTEP=1.
TIMEOFFSET
If included, returns the Modified Julian Day of the exposure
start.
TRANGE: An [N,2] element matrix containing the start and ending
times of N intervals to include in the array. If N = 1,
a simple two element vector, [tstart,tend] may be used.
XRANGE: A [N,2] element vector containing the start and ending x
pixel of N pixel ranges to include in the array. If N = 1,
a simple to element vector, [xstart,xend] may be used.
YRANGE: A [N,2] element vector containing the start and ending y
pixel of N pixel ranges to include in the array. If N = 1,
a simple to element vector, [ystart,yend] may be used.
NOTE that multiple ranges in XRANGE and YRANGE only work if the INPUTDATA keyword
is used. This will change once LIST2LIST is modified.
PRANGE: A two element vector containing the range of pulse height
to include in the array.
OUTFILE:Set this keyword to a filename to send the output to a file
rather than a plot.
MAXRATE:Maximum count rate to display on the plot.
NOPLOT: If set, no plot is made.
NOSHADE:If set, and there are times which fall outside the Good Time
Intervals, these regions are not shaded.
SIDE EFFECTS:
Creates plots or a file.
EXAMPLE:
To plot the count rate of the data in the file 'file.fits',
averaged over 4 second intervals, using the two xranges
3000 < x < 6400 and 7000 < 15000:
IDL> plotrate, 'file.fits', data, time, rate, timestep=4, $
IDL> xrange = [[3000,7000],[6400,15000]]
MODIFICATION HISTORY:
Written by David Sahnow, 21 May 1999.
14 June 1999 Modified to read multiple files. Can't concatonate
structures, so returned values are wrong in this case.
2 July 1999 Added date on plot.
14 August 1999 Now extracts MJD of exposure start time, and TIMEOFFSET
keyword.
15 August 1999 Added TRANGE, XRANGE, YRANGE, PRANGE keywords, and
replaced MRDFITS with LIST2LIST.
17 August 1999 Fixed an error in calculating rates.
21 August 1999 Plot now notes if XRANGE, YRANGE, TRANGE, or PRANGE
have been used.
22 August 1999 Added INPUTDATA and OUTFILE keywords.
18 September 1999 Modified TRANGE keyword to allow multiple ranges.
22 September 1999 Fixed a bug introduced on 9/18, which prevented
a single time range from working.
22 October 1999 Added MAXRATE keyword. Modified to work if tm
contains only one element.
23 October 1999 Added call to SHOWFHEADER.
29 October 1999 Moved SHOWFHEADER text to bottom left corner of plot,
and removed it if using existing data.
16 February 2000 Modified XRANGE and YRANGE keywords to allow multiple
ranges.
3 March 2000 Modified plotting of notes about xrange and yrange to use
!x.crange and !y.crange rather than normalized coordinates.
15 May 2000 Added back in code (apparently removed on 8/17/99) to
use noninteger TIMESTEPs.
16 May 2000 Added reading of TTPERIOD header keyword to see if TTAG
insertion rate doesn't match the TIMESTEP keyword. Added NOPLOT
option.
30 May 2000 Modified to use SHOWFHEADER2 rather than SHOWFHEADER.
6 September 2000 Now reads in Good Time Intervals and shades other regions.
Added NOSHADE keyword. Slightly modified reading of main FITS header.
12 September 2000 Modified shading to fix a bug.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/plotrate.pro)
PLOTSYM
[Previous Routine]
[Next Routine]
[List of Routines]
routine: plotsym
usage: plotsym,x,y,xsym,ysym
purpose: overlays plot symbols on the last data window. A single
call can create symbols of varying size, fill color, and
outline color and thickness. Symbols of arbitrary shape
can be created. Note that the symbols may be filled
with a different color then the outline color. This can
dramatically unclutter the appearance of densely packed
scatter plots. See example.
input:
x x coordinates of symbol centers on plot
y y coordinates of symbol centers on plot
xsym x coordinantes of symbol outline with respect to symbol center
ysym y coordinantes of symbol outline with respect to symbol center
NOTE: if TYPE or XSYM and YSYM are not supplied a circular symbol
is assumed
keyword input:
ocolor outline color of symbol
fcolor fill color of symbol
thick line thickness of symbol outline
sym_siz symbol size multiplier
type symbol type, a string matching one of
'DIAMOND', 'PENTAGON', 'CLOVER', 'PACMAN',
'SPIRAL', 'BIGX', 'CIRCLE', 'SQUARE',
'TRIANGLE', 'STAR', 'HEXAGON', 'HEART',
'SPADE', 'CLUB'
NOTE: OCOLOR, FCOLOR, THICK and SYM_SIZE may be specified as
single values or vector of values, one for each element
of x and y
device if set, coordinates are in device units
normal if set, coordinates are in normalized units
data if set, coordinates are in data units (default)
NOTE:
the OCOLOR, FCOLOR, THICK and SYM_SIZ parameters may be specified as
vectors quantities, one value for each point on the plot
SIDE EFFECTS:
changes the shape of user-defined plot symbol (accessed with psym=8).
EXAMPLE:
x=randomu(iseed,400)
y=randomu(iseed,400)
z=1.-x-y
fcolor=bytscl(z,top=!p.color)
ocolor=5*!p.color
loadct,5
plot,x,y,/nodata
plotsym,x,y,type='square',fcolor=fcolor,ocolor=ocolor,thick=1,sym_siz=1.5
; In this example note how PLOTSYM unclutters the scatter plot
!p.multi=[0,1,2]
x=randomn(iseed,400)
y=randomn(iseed,400)
plot,x,y,/nodata
plotsym,x,y,sym_siz=2
plot,x,y,psym=8
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/plotsym.pro)
PLOTSYM2
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
plotsym2
PURPOSE:
function to make plotting symbols much easier.
Usage:
plot,x,y,psym=plotsym(/circle,scale=2,/fill)
CATEGORY:
Graphics.
Keywords:
circle = circle symbol
triangle = triangle symbol
diamond = diamond symbold
box = box symbol
line = line symbol
scale = scales the symbol
angle = angle the symbol should be rotated
_extra = extra keywords for usersym. These are thick, color and fill
Written by:
Ronn Kling
Ronn Kling Consulting
7038 Westmoreland Dr.
Warrenton, VA 20187
klingrl@juno.com
copyright 1999, all rights reserved
(See /home/drw/idl/aux/plotsym2.pro)
PLOT_ASYM_ERR
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : PLOT_ERR
Purpose : Plot data with error bars in both X and Y directions
Explanation : Plots data points with accompanying error bars in both the X
and Y directions.
A plot of X versus Y with error bars drawn from X-XERR to
X+XERR and from Y-YERR to Y+YERR is written to the output
device. Optionally, one can give different sizes for the lower
and upper error bars.
If !BCOLOR is not zero, then that color is used for error bars.
Use : PLOT_ERR, [ X, ] Y [, XERR=XERR] [, YERR=YERR]
Inputs : Y = array of Y values.
Opt. Inputs : X = array of X values. If not passed, then the index of Y is
used instead.
Outputs : None.
Opt. Outputs: None.
Keywords : XERR = Array of errors in X
YERR = array of errors in Y.
The error arrays can take one of two forms:
* Same dimensions as the data arrays, in which case the
error is applied in both the X and Y directions
* An extra initial dimension of 2, in which case the
first value is the size of the lower (or left) error bar,
and the second value is the size of the upper (or upper)
error bar.
PSYM = Symbol to use for plotting. Default is 7 (X).
SYMSIZE = Symbol size
COLOR = Color to use for plotting.
BCOLOR = Color to use instead of !BCOLOR for error bars.
LINESTYLE = Line style
THICK = Line thickness
UTPLOT = If set, then the first (X) parameter is considered
to be time in one of the CDS time formats. This is
only allowed if both X and Y are passed. If used,
then XERR is in seconds.
Also, most PLOT keywords are supported.
Calls : DATATYPE, UTPLOT, OUTPLOT
Common : None.
Restrictions: Requires that the system parameter !BCOLOR be defined.
Side effects: None.
Category : Utilities, Plotting
Prev. Hist. : Based on an earlier routine called PLOTERR2.
Written : William Thompson, GSFC, 19 April 1995
Modified : Version 1, William Thompson, 19 April 1995
Version 2, William Thompson, GSFC, 20 April 1995
Added keyword UTPLOT.
Made determination of symmetrical/asymmetrical error
bars more robust.
Version 3 CDP, 30-Nov-95
Cut linestyle from plot call so keyword is acted upon
Version : Version 3, 30 November 1995
(See /home/drw/idl/gen/plot_asym_err.pro)
PLOT_CYCLE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE
plot_cycle
PURPOSE:
set the position of new plots so that they fill the frame in a given
order. New plots cause only a single subframe to be overwritten. Old
frames are left for comparison.
USEAGE:
plot_cycle,nx,ny,icycle,i
INPUT:
nx
number of horizontal frames
ny
number of vertical frames
icycle
index array specifying the order frames are overwritten, upper left
frame is 1.
i
index into icycle (incremented after each call)
OUTPUT: i
EXAMPLE:
!p.multi=[0,1,2]
f=randata(128,128,s=3)
tvim,f,/interp
xw=!x.window & xr=!x.crange
yw=!y.window & yr=!y.crange
x1=60 & x2=80 & y1=60 & y2=80
!p.charsize=2
while y1 gt 0 do begin &$
plot_cycle,2,4,[5,6,7,8],i &$
xx=x1+indgen(x2-x1+1) &$
yy=y1+indgen(y2-y1+1) &$
contour,f(x1:x2,y1:y2),xx,yy &$
wait,.5 &$
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess &$
endwhile
REVISIONS:
author: Paul Ricchiazzi date>
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/plot_cycle.pro)
PLOT_CYCLE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE
plot_cycle
PURPOSE:
set the position of new plots so that they fill the frame in a given
order. New plots cause only a single subframe to be overwritten. Old
frames are left for comparison.
USEAGE:
plot_cycle,nx,ny,icycle,i
INPUT:
nx
number of horizontal frames
ny
number of vertical frames
icycle
index array specifying the order frames are overwritten, upper left
frame is 1.
i
index into icycle (incremented after each call)
OUTPUT: i
EXAMPLE:
!p.multi=[0,1,2]
f=randata(128,128,s=3)
tvim,f,/interp
xw=!x.window & xr=!x.crange
yw=!y.window & yr=!y.crange
x1=60 & x2=80 & y1=60 & y2=80
!p.charsize=2
while y1 gt 0 do begin &$
plot_cycle,2,4,[5,6,7,8],i &$
xx=x1+indgen(x2-x1+1) &$
yy=y1+indgen(y2-y1+1) &$
contour,f(x1:x2,y1:y2),xx,yy &$
wait,.5 &$
curbox,x1,x2,y1,y2,xw,yw,xr,yr,/init,inc=4,/mess &$
endwhile
REVISIONS:
author: Paul Ricchiazzi date>
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/plot_cycle.pro)
PLOT_HIST[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
plot_hist
PURPOSE:
To plot a histogram with a properly labeled X axis.
SAMPLE CALLING SEQUENCE:
plot_hist, img
plot_hist, img, x, h
plot_hist, img, bin=0.1
plot_hist, img, xrange=xrange, yrange=yrange, tit=tit
INPUT:
data - The data to perform the historam on
OUTPUT:
x - The x axis for the plotting
h - The histogram
OPTIONAL KEYWORD INPUTS:
bin - The bin size to use (default is 1)
xrange - The x plotting range
yrange - The y plotting range
tit - The title
log - If set, then plot the y axis in log form
HISTORY:
Written Apr-95 by M.Morrison
18-May-95 (MDM) - Added /LOG switch
- Plot such that the minimum occurance is 0.1
7-Jul-95 (MDM) - Fixed the plot so that min occurance is 0.1
27-Nov-95 (LWA) - Added noerase, linestyle, charsize keywords.
8-Nov-96 (MDM) - Merged 27-Nov-95 changes with the ones below:
17-May-96 (MDM) - Added xtitle
11-Sep-96 (MDM) - Added ROUND when creating "data0"
8-Nov-96 (MDM) - Added "oplot" option
(See /home/drw/idl/bin/pg_hist.pro)
PLOT_HIST[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
plot_hist
PURPOSE:
To plot a histogram with a properly labeled X axis.
SAMPLE CALLING SEQUENCE:
plot_hist, img
plot_hist, img, x, h
plot_hist, img, bin=0.1
plot_hist, img, xrange=xrange, yrange=yrange, tit=tit
INPUT:
data - The data to perform the historam on
OUTPUT:
x - The x axis for the plotting
h - The histogram
OPTIONAL KEYWORD INPUTS:
bin - The bin size to use (default is 1)
xrange - The x plotting range
yrange - The y plotting range
tit - The title
log - If set, then plot the y axis in log form
HISTORY:
Written Apr-95 by M.Morrison
18-May-95 (MDM) - Added /LOG switch
- Plot such that the minimum occurance is 0.1
7-Jul-95 (MDM) - Fixed the plot so that min occurance is 0.1
27-Nov-95 (LWA) - Added noerase, linestyle, charsize keywords.
8-Nov-96 (MDM) - Merged 27-Nov-95 changes with the ones below:
17-May-96 (MDM) - Added xtitle
11-Sep-96 (MDM) - Added ROUND when creating "data0"
8-Nov-96 (MDM) - Added "oplot" option
(See /home/drw/idl/bin/ptg/pg_hist.pro)
PMOM
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pmom
PURPOSE: compute legendre moments of scattering phase function
USEAGE: pmom,mu,phase,nm,pm,f,view=view,angcut=angcut,deltam=deltam
INPUT:
mu cosine of polar angle, in range -1, 1
phase phase function at each polar angle, normalization is arbitrary
NOTE: the accuracy of the integration depends on the
number of values provided for mu and phase. For
example, 10000 steps were required to obtain better
than 1% accuracy for all 21 moments of the
Henyey-Greenstein function with g=0.7. More steps
may be required when higher moments or more sharply
peaked functions are considered. Since a simple
trapazoidal integration is used, a uniform spacing
in mu is desirable.
nm number of of legendre moments. moments are numbered from 0 to nm
for a total of nm+1 values.
KEYWORD INPUT
view if set, PMOM draws a plot of the original phase function,
the truncated phase function (if angcut is set), and the
legendre fit to the (possibly truncated) phase function.
angcut if set, forward scattering peak of the phase function will
be truncated as,
angle > angcut: phase = original phase function
angle < angcut: phase = extrapolation of phase function from
last two points with angle > angcut
deltam use the deltam method of wiscombe, 1977, JGR 34 1408-1422
shape of truncated part of phase function determined by
highest included legendre polynomial.
OUTPUT:
pm legendre moments (nm+1) values
f when angcut or deltam is set, a part of the forward
scattering peak is lopped off. 1-f is the ratio of
the total scattering without and with the truncated
portion of the phase function, i.e.,
f= 1 - integral( phase_truncated dmu)/ integral( phase dmu)
The f factor should be used to rescale the optical depth,
dtau, and single scattering albedo, w (Wiscombe, 1977):
dtau'= dtau*(q_ext*w*(1-f) + (1-w)q_ext)/q_ext
dtau'= dtau*(1-w*f)
w' = q_ext*w*(1-f)/(q_ext*w*(1-f)+(1-w)*q_ext)
w' = w*(1-f)/(1-w*f)
For phase functions with large forward scattering, 1-f << 1
DISCUSSION:
This procedure generates legendre moments of an arbitrary
function defined in the range -1 to 1. These coefficients are
the input quantities required by DISORT for the specification of
of scattering phase function or BRDF. The output quantity, pm,
is defined as,
/ / /
pm(i) = | f(mu) P(i,mu) d mu / | f(mu) d mu
/ / /
where P(i,mu) is the legendre polynomial, f is the phase function, and
the range of the integrals are from -1 to 1.
LIMITATIONS:
Some phase functions may require an impractically large number
of moments to resolve the forward scattering peak. In these cases
it may be desirable to lop off the forward peak using the ANGCUT
or DELTAM keyword parameters, in order to fit the phase function
with fewer legendre moments. If this is done, be sure to also
rescale optical depth and single scattering albedo, as discussed
above, in the radiative transfer model.
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE: find moments of Henyey-Greenstein phase function
The analytic result has pmom=1/g^indgen(nm+1)
ns=10000 & g=.85 & nm=20
mu=findrng(-1,1,ns)
phase=(1.-g^2)/(1.+g^2-2*g*mu)^1.5
!p.multi=[0,1,2]
pmom,mu,phase,nm,pm,f,/view
print,f='(a/(10f8.4))','pmom',pm(1:*)
print,f='(a/(10f8.4))','pmom/g^i',pm(1:*)/g^(1+indgen(nm))
pmom,mu,phase,nm,pm,f,/deltam,/view
print,f='(a/(10f8.4))','pmom',pm(1:*)
print,f='(a/(10f8.4))','pmom/g^i',pm(1:*)/g^(1+indgen(nm))
EXAMPLE: find moments of Rayleigh scattering phase function
the analytic result has pmom(0)=1 and pmom(2)=.1
ns=1000 & nm=10
mu=findrng(-1,1,ns)
phase=(1.+mu^2)
pmom,mu,phase,nm,pm
print,f='(a/10f8.4)','pmom',pm
phs=phase<0.
norm=integral(mu,phase)
for i=0,nm do phs=phs+.5*norm*(2*i+1)*pm(i)*legendre(mu,i)
plot,mu,phase
oplot,mu,phs
AUTHOR: Paul Ricchiazzi 29 Jul 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/pmom.pro)
PM[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PM
PURPOSE:
Shorthand way of setting !p.multi.
CALLING SEQUENCE:
PM,1,2
INPUTS:
OPTIONAL INPUTS:
row Sets number of plots per row
col Sets number of plots per col
OUTPUTS:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/03/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/pm.pro)
PM[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PM
PURPOSE:
Shorthand way of setting !p.multi.
CALLING SEQUENCE:
PM,1,2
INPUTS:
OPTIONAL INPUTS:
row Sets number of plots per row
col Sets number of plots per col
OUTPUTS:
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/03/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/pm.pro)
PNOISE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PNOISE
PROJECT:
Solar Orbiter study
PURPOSE:
Add poisson (photon) noise to an array
HISTORY:
DRW @ MSSL 07/03/03 17:30
(just a stop-gap until Charles Kankelborg sends his version)
(See /home/drw/idl/gen/pnoise.pro)
PNOISE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PNOISE
PURPOSE:
Add poisson noise to an array of data (in counts). Any
datum less than or equal to 0.0 is not modified.
CALLING SEQUENCE:
pnoise, data [, seed=seed]
INPUTS:
data - a data array of any size or dimension, in counts. This
array is modified in place.
OPTIONAL KEYWORDS:
seed - seed for the random number generator.
HISTORY:
CCK 20020915
(See /home/drw/idl/my_tomography3/pnoise.pro)
PNTS_NEAR[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: pnts_near
purpose: return index array of points within radius
useage: pnts_near,plon,plat,lonrng,latrng,nx,ny,radius,ii,nc
input:
plon longitude of point
plat latitude of point
lonrng longitude range (two element vector)
latrng latitude range
nx number of points across lonrng
ny number of points across latrng
radius radius of region
output:
ii index array of point within disk
nc number of points within disk
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/pnts_near.pro)
PNTS_NEAR[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: pnts_near
purpose: return index array of points within radius
useage: pnts_near,plon,plat,lonrng,latrng,nx,ny,radius,ii,nc
input:
plon longitude of point
plat latitude of point
lonrng longitude range (two element vector)
latrng latitude range
nx number of points across lonrng
ny number of points across latrng
radius radius of region
output:
ii index array of point within disk
nc number of points within disk
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/pnts_near.pro)
POINTER
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: pointer
PURPOSE:
USEAGE: pointer,x,y,a,size=size,vsize=vsize,color=color, $
norm=norm,subnorm=subnorm,device=device,scale=scale
INPUT:
x x coordinate values (default data coordinates)
y y coordinate values
a angle of pointer (increases clockwise, zero is up)
"a" may be set to atan(xvec,yvec) where xvec and yvec
are vector components in the x and y directions.
KEYWORD INPUT:
size size of circle part of pointer symbol in character units (scalor)
vsize size of arrow part of pointer symbol in character units
or in data units (if scale set). If VSIZE is not set it
is set to a 3 times the radius of the circle part of the
pointer symbol. VSIZE can be specified as a scalor or
vector of values.
scale if non-zero the size of the arrow part of the pointer
symbol is scaled to the units used for the vertical axis,
multiplied by the value SCALE. For example, if the units
of the vertical axis is degrees latitude then setting
SCALE to 111.2 causes VSIZE to be interpreted as
kilometers.
norm x and y in normalized coordinates
subnorm x and y in subnormalized coordinate (0 - 1 in plot frame)
device x and y in device coordinates
OUTPUT: none
EXAMPLE:
map_set3,0,0,/cont
lon=findrng(-180,180,20)
lat=findrng(-90,90,15)
gengrid,lon,lat
x=randata(20,15,s=4)
y=randata(20,15,s=4)
pointer,lon,lat,atan(x,y)
AUTHOR: Paul Ricchiazzi 01 Mar 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/pointer.pro)
POINTS2ARR
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
SECIS
NAME:
POINTS2ARR
PURPOSE:
lets you pick points and store them in an array
CALLING SEQUENCE:
CALLS:
MARK.PRO, a modification of PICK.PRO, by P.T. Gallagher
to get X & Y values for each mouse click.
HISTORY:
PIXLOOPLENGTH.PRO originally by David Williams, 4/6/99
Modified to allow the user to set the number of points
chosen (e.g. 10) and saved as LOOPLENGTH.PRO
- DRW, 27/4/01
(See /home/drw/idl/secis/points2arr.pro)
POINT_GET_SPEC
[Previous Routine]
[Next Routine]
[List of Routines]
a routine where you enter the X and Y solar co-ordinates and the size
of the area you want to analyse (a box of side N arcsecs) and then
(See /home/drw/idl/cds/point_get_spec.pro)
POLAR_ORTHO[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine polar_ortho
input:
alat latitude array
alon longitude array
outer_lat outer latitude limit
output:
xn x coordinate to which (alat,alon) maps (normalized 0-1)
yn y coordinate to which (alat,alon) maps (normalized 0-1)
purpose: use this map projection procedure with regrid.pro
EXAMPLE:
; polar projection
window,/free,xs=400,ys=1000
!p.multi=[0,1,3]
latrng=[30,70] & lonrng=[-110,-70] & nnx=200 & nny=150
alon=(float(c)-min(float(c)))/(max(float(c))-min(float(c)))
alat=(imaginary(c)-min(imaginary(c)))/(max(imaginary(c))-min(imaginary(c)))
alon=lonrng(0)+(lonrng(1)-lonrng(0))*alon
alat=latrng(0)+(latrng(1)-latrng(0))*alat
im=sqrt(abs(sin(alon*!pi)*sin(alat*!pi)))^.3
tvim,im,/scale,title='image'
contour,alat,/overplot,levels=[40,60],thick=4,color=0
contour,alon,/overplot,levels=[-100,-80],thick=4,color=0
regrid,alat,alon,nnx,nny,kx,ky,proj='polar_ortho',extras=30,degree=2
imm=poly_2d(im,kx,ky,0,nnx,nny,missing=0)
tvim,imm,/scale,xr=[-5517,5517],yr=[5517,5517],title='regrided image, d=2'
regrid,alat,alon,nnx,nny,kx,ky,proj='polar_ortho',extras=30,degree=3
imm=poly_2d(im,kx,ky,0,nnx,nny,missing=0)
tvim,imm,/scale,xr=[-5517,5517],yr=[5517,5517],title='regrided image, d=3'
AUTHOR: Paul Ricchiazzi feb94
Earth Space Research Group, UCSB
(See /home/drw/idl/esrg/polar_ortho.pro)
POLAR_ORTHO[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine polar_ortho
input:
alat latitude array
alon longitude array
outer_lat outer latitude limit
output:
xn x coordinate to which (alat,alon) maps (normalized 0-1)
yn y coordinate to which (alat,alon) maps (normalized 0-1)
purpose: use this map projection procedure with regrid.pro
EXAMPLE:
; polar projection
window,/free,xs=400,ys=1000
!p.multi=[0,1,3]
latrng=[30,70] & lonrng=[-110,-70] & nnx=200 & nny=150
alon=(float(c)-min(float(c)))/(max(float(c))-min(float(c)))
alat=(imaginary(c)-min(imaginary(c)))/(max(imaginary(c))-min(imaginary(c)))
alon=lonrng(0)+(lonrng(1)-lonrng(0))*alon
alat=latrng(0)+(latrng(1)-latrng(0))*alat
im=sqrt(abs(sin(alon*!pi)*sin(alat*!pi)))^.3
tvim,im,/scale,title='image'
contour,alat,/overplot,levels=[40,60],thick=4,color=0
contour,alon,/overplot,levels=[-100,-80],thick=4,color=0
regrid,alat,alon,nnx,nny,kx,ky,proj='polar_ortho',extras=30,degree=2
imm=poly_2d(im,kx,ky,0,nnx,nny,missing=0)
tvim,imm,/scale,xr=[-5517,5517],yr=[5517,5517],title='regrided image, d=2'
regrid,alat,alon,nnx,nny,kx,ky,proj='polar_ortho',extras=30,degree=3
imm=poly_2d(im,kx,ky,0,nnx,nny,missing=0)
tvim,imm,/scale,xr=[-5517,5517],yr=[5517,5517],title='regrided image, d=3'
AUTHOR: Paul Ricchiazzi feb94
Earth Space Research Group, UCSB
(See /home/drw/idl/old.esrg/polar_ortho.pro)
POLY_XYZ[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: poly_xyz
CALLING SEQUENCE:
RESULT=POLY_XY(X,Y,Z,K)
PURPOSE: Evaluate the trivariate polynomial function of x,y,z
where poly_xyz = SUM [ k(i,j,k) * x^i * y^j * z^k]
the sum extends over i,j,k
INPUT: x Vector of x independent variable
y Vector of y independent variable
z Vector of z independent variable
k Array of polynomial coefficients (as computed by the
the companion procedure POLY_XYZ_FIT.PRO)
author: Paul Ricchiazzi 1mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/poly_xyz.pro)
POLY_XYZ[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: poly_xyz
CALLING SEQUENCE:
RESULT=POLY_XY(X,Y,Z,K)
PURPOSE: Evaluate the trivariate polynomial function of x,y,z
where poly_xyz = SUM [ k(i,j,k) * x^i * y^j * z^k]
the sum extends over i,j,k
INPUT: x Vector of x independent variable
y Vector of y independent variable
z Vector of z independent variable
k Array of polynomial coefficients (as computed by the
the companion procedure POLY_XYZ_FIT.PRO)
author: Paul Ricchiazzi 1mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/poly_xyz.pro)
POLY_XYZ_FIT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: poly_xyz_fit
CALLING SEQUENCE:
result=poly_xyz_fit(x,y,z,u,degree)
result=poly_xyz_fit(x,y,z,u,degree,ufit)
PURPOSE: Find the least square polynomial coefficients fitting the
dependent variable u to three independent variables x,y and z.
The trivariate polynomial function of x,y,z is defined as
ufit=SUM [ k(i,j,k) * x^i * y^j * z^k] (summed over i,j and k)
INPUT:
x Vector of x values (independent variable)
y Vector of y values (independent variable)
z Vector of z values (independent variable)
u vector of u values (dependent variable)
degree 3 element vector specifying polynomial order.
The fitting polynomial will be of order DEGREE(0) in x
DEGREE(1) in y and DEGREE(2) in z
OUTPUT:
result Array of polynomial coefficients (can be used directly
in the companion procedure POLY_XYZ)
Optional OUTPUT:
ufit polynomial evaluated at (x,y,z) input points
author: Paul Ricchiazzi 1mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/poly_xyz_fit.pro)
POLY_XYZ_FIT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: poly_xyz_fit
CALLING SEQUENCE:
result=poly_xyz_fit(x,y,z,u,degree)
result=poly_xyz_fit(x,y,z,u,degree,ufit)
PURPOSE: Find the least square polynomial coefficients fitting the
dependent variable u to three independent variables x,y and z.
The trivariate polynomial function of x,y,z is defined as
ufit=SUM [ k(i,j,k) * x^i * y^j * z^k] (summed over i,j and k)
INPUT:
x Vector of x values (independent variable)
y Vector of y values (independent variable)
z Vector of z values (independent variable)
u vector of u values (dependent variable)
degree 3 element vector specifying polynomial order.
The fitting polynomial will be of order DEGREE(0) in x
DEGREE(1) in y and DEGREE(2) in z
OUTPUT:
result Array of polynomial coefficients (can be used directly
in the companion procedure POLY_XYZ)
Optional OUTPUT:
ufit polynomial evaluated at (x,y,z) input points
author: Paul Ricchiazzi 1mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/poly_xyz_fit.pro)
POLY_XY[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: poly_xy
CALLING SEQUENCE:
RESULT=POLY_XY(X,Y,K)
PURPOSE: Evaluate the bivariate polynomial function of x and y
where poly_xy = SUM [ k(i,j) * x^i * y^j ]
the sum extends over i and j
INPUT: x Vector of x values
y Vector of y values
k Array of polynomial coefficients (as computed by the
the companion procedure POLY_XY_FIT.PRO)
author: Paul Ricchiazzi 1mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/poly_xy.pro)
POLY_XY[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: poly_xy
CALLING SEQUENCE:
RESULT=POLY_XY(X,Y,K)
PURPOSE: Evaluate the bivariate polynomial function of x and y
where poly_xy = SUM [ k(i,j) * x^i * y^j ]
the sum extends over i and j
INPUT: x Vector of x values
y Vector of y values
k Array of polynomial coefficients (as computed by the
the companion procedure POLY_XY_FIT.PRO)
author: Paul Ricchiazzi 1mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/poly_xy.pro)
POLY_XY_FIT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: poly_xy_fit
CALLING SEQUENCE:
result=poly_xy_fit(x,y,u,degree)
result=poly_xy_fit(x,y,u,degree,ufit)
PURPOSE: Find the least square polynomial coefficients fitting the
dependent variable u to the independent variables x and y.
The bivariate polynomial function of x and y is defined as
ufit=SUM [ k(i,j) * x^i * y^j ] (summed over i and j)
INPUT:
x Vector of x independent variable
y Vector of y independent variable
u Vector of dependent variable
degree 2 element vector polynomial order.
The fitting polynomial will be of order DEGREE(0) in x
and of order DEGREE(1) in y
OUTPUT:
result Array of polynomial coefficients (can be used directly
in the companion procedure POLY_XY)
Optional OUTPUT:
ufit polynomial evaluated at x and y points
usig standard deviation of (u-ufit)
Example:
x=randomu(iseed,100)
y=randomu(iseed,100)
u=1.+x+y+x*y+x^2+y^2
k=poly_xy_fit(x,y,u,[2,2],ufit,usig)
print, usig
print, k
xx=double(x)
yy=double(y)
uu=1.+xx+yy+xx*yy+xx^2+yy^2
kk=poly_xy_fit(xx,yy,uu,[2,2],ufit,usig)
print,usig,kk
author: Paul Ricchiazzi 1mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/poly_xy_fit.pro)
POLY_XY_FIT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: poly_xy_fit
CALLING SEQUENCE:
result=poly_xy_fit(x,y,u,degree)
result=poly_xy_fit(x,y,u,degree,ufit)
PURPOSE: Find the least square polynomial coefficients fitting the
dependent variable u to the independent variables x and y.
The bivariate polynomial function of x and y is defined as
ufit=SUM [ k(i,j) * x^i * y^j ] (summed over i and j)
INPUT:
x Vector of x independent variable
y Vector of y independent variable
u Vector of dependent variable
degree 2 element vector polynomial order.
The fitting polynomial will be of order DEGREE(0) in x
and of order DEGREE(1) in y
OUTPUT:
result Array of polynomial coefficients (can be used directly
in the companion procedure POLY_XY)
Optional OUTPUT:
ufit polynomial evaluated at x and y points
usig standard deviation of (u-ufit)
author: Paul Ricchiazzi 1mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/poly_xy_fit.pro)
POPULATE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME:
POPULATE
PURPOSE:
calculate levels populations at a specific temperature and electron
density
CATEGORY:
science.
CALLING SEQUENCE:
POPULATE,T, Eden, Pop
INPUTS:
T: electron temperature
Eden: electron density (cm^(-3) )
OUTPUTS:
Pop: populations of all of the ions levels
COMMON BLOCKS:
common elvl,mult,ecm
common wgfa, wvl,gf,a_value
common upsilon,t_type,c_ups,splups
these must be filled with the necessary data before
populate can be run
RESTRICTIONS:
see above
PROCEDURE:
this is not a top level routine.
EXAMPLE:
> convertname,'c_2',iz,ion
> print,iz,ion
> 6,2
MODIFICATION HISTORY:
Written by: Ken Dere
March 1996: Version 2.0
Revised Nov 1996 by Ken Dere following suggestion of Vinay Kashyap
and Jeremy Drake to make arrays c,d,b,pop double precision to avoid
overflows
(See /home/drw/idl/bin/populate_pry.pro)
POPULATE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME:
POPULATE
PURPOSE:
calculate levels populations at a specific temperature and electron
density
CATEGORY:
science.
CALLING SEQUENCE:
POPULATE,T, Eden, Pop
INPUTS:
T: electron temperature
Eden: electron density (cm^(-3) )
OUTPUTS:
Pop: populations of all of the ions levels
COMMON BLOCKS:
common elvl,mult,ecm
common wgfa, wvl,gf,a_value
common upsilon,t_type,c_ups,splups
these must be filled with the necessary data before
populate can be run
RESTRICTIONS:
see above
PROCEDURE:
this is not a top level routine.
EXAMPLE:
> convertname,'c_2',iz,ion
> print,iz,ion
> 6,2
MODIFICATION HISTORY:
Written by: Ken Dere
March 1996: Version 2.0
Revised Nov 1996 by Ken Dere following suggestion of Vinay Kashyap
and Jeremy Drake to make arrays c,d,b,pop double precision to avoid
overflows
(See /home/drw/idl/bin/ptg/populate_pry.pro)
POP_PLOT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: POP_PLOT
PURPOSE:
To compute n_j A_ji / N_e for a selected transition(s) and plot it
against N_e. If it is insensitive to N_e, then the line(s) is
suitable for emission measure analysis.
CATEGORY:
Atomic data analysis
EXPLANATION:
The routine calls EMISS_CALC to give values of DE*n_j*A_ji at the
temperature TEMP and densities from 10^8 to 10^12. You are then
asked to select which transition(s) you are interested in. (If
more than one line is selected, the lines are blended.)
DE*n_j*A_ji/N_e is then plotted against density.
If TEMP is not specified, then the temperature at which the
ionisation fraction has its maximum is calculated. For the iron
ions, the ion balance calcs of Arnaud & Raymond are used,
otherwise Arnaud & Rothenflug are used. If TEMP is specified,
and the value is less than 20, then it is assumed that the log
of the temperature has been specified.
In emission measure work it is important to isolate lines for
which DE*n_j*A_ji/N_e is insensitive to density. If only such lines
are used, then the derived emission measure curve is independent
of density.
CALLING SEQUENCE:
POP_PLOT, IZ, ION, WRANGE, [TMAX=TMAX, /QUICK, DATA=DATA, $
DENS_RANGE=DENS_RANGE, DILUTE=DILUTE]
EXAMPLES:
POP_PLOT, 26, 14, [330,360]
- 3 lines should appear in the widget. Selecting 334.17 should show
a curve that falls off with density. Choosing 353.83 shows a curve
that rises with density. By selecting a blend of the two lines,
the curve will be insensitive to density, telling us that only a
blend of 334.17 and 353.83 is suitable for emission measure work.
POP_PLOT, 8, 4, [550,560], TEMP=6.0, /QUICK, DENS_RANGE=[6,10]
- O IV is a member of the boron sequence, and so calculations take a
lot longer. Giving the QUICK keyword speeds things up. The
temperature is well away from the T_max of the ion
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
WRANGE: Wavelength range from which lines are required
OPTIONAL INPUTS:
DILUTE: Used to set radiative dilution factor. (Default: 0.0)
TEMP: The temperature at which calculations are required. Usually
this will be the Tmax of the ion.
DENS_RANGE: The default density range is log Ne = 8 to 12. By
inputting two integers, a different range can be chosen.
OPTIONAL OUTPUTS:
DATA: An array that contains the data that is plotted: data(*,0)
contains
the densities, while data(*,1) contains the Y-axis values.
KEYWORDS:
QUICK: The density range over which the calculations are done is
8 to 12 in 0.2 intervals. This keyword forces the
calculations to be done at 0.5 intervals.
CALLS:
EMISS_CALC, POPULATE_PRY, READ_IONEQ
HISTORY:
Ver.1, PRY 28-Jul-97.
Ver.2, PRY 23-Sep-97 - added DILUTE keyword for photo-excitation
Ver.3, PRY 30-May-98 - added DENS_RANGE
CONTACT:
Peter Young, Cambridge University (P.R.Young@damtp.cam.ac.uk)
(See /home/drw/idl/bin/pop_plot.pro)
POP_PLOT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: POP_PLOT
PURPOSE:
To compute n_j A_ji / N_e for a selected transition(s) and plot it
against N_e. If it is insensitive to N_e, then the line(s) is
suitable for emission measure analysis.
CATEGORY:
Atomic data analysis
EXPLANATION:
The routine calls EMISS_CALC to give values of DE*n_j*A_ji at the
temperature TEMP and densities from 10^8 to 10^12. You are then
asked to select which transition(s) you are interested in. (If
more than one line is selected, the lines are blended.)
DE*n_j*A_ji/N_e is then plotted against density.
If TEMP is not specified, then the temperature at which the
ionisation fraction has its maximum is calculated. For the iron
ions, the ion balance calcs of Arnaud & Raymond are used,
otherwise Arnaud & Rothenflug are used. If TEMP is specified,
and the value is less than 20, then it is assumed that the log
of the temperature has been specified.
In emission measure work it is important to isolate lines for
which DE*n_j*A_ji/N_e is insensitive to density. If only such lines
are used, then the derived emission measure curve is independent
of density.
CALLING SEQUENCE:
POP_PLOT, IZ, ION, WRANGE, [TMAX=TMAX, /QUICK, DATA=DATA, $
DENS_RANGE=DENS_RANGE, DILUTE=DILUTE]
EXAMPLES:
POP_PLOT, 26, 14, [330,360]
- 3 lines should appear in the widget. Selecting 334.17 should show
a curve that falls off with density. Choosing 353.83 shows a curve
that rises with density. By selecting a blend of the two lines,
the curve will be insensitive to density, telling us that only a
blend of 334.17 and 353.83 is suitable for emission measure work.
POP_PLOT, 8, 4, [550,560], TEMP=6.0, /QUICK, DENS_RANGE=[6,10]
- O IV is a member of the boron sequence, and so calculations take a
lot longer. Giving the QUICK keyword speeds things up. The
temperature is well away from the T_max of the ion
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
WRANGE: Wavelength range from which lines are required
OPTIONAL INPUTS:
DILUTE: Used to set radiative dilution factor. (Default: 0.0)
TEMP: The temperature at which calculations are required. Usually
this will be the Tmax of the ion.
DENS_RANGE: The default density range is log Ne = 8 to 12. By
inputting two integers, a different range can be chosen.
OPTIONAL OUTPUTS:
DATA: An array that contains the data that is plotted: data(*,0)
contains
the densities, while data(*,1) contains the Y-axis values.
KEYWORDS:
QUICK: The density range over which the calculations are done is
8 to 12 in 0.2 intervals. This keyword forces the
calculations to be done at 0.5 intervals.
CALLS:
EMISS_CALC, POPULATE_PRY, READ_IONEQ
HISTORY:
Ver.1, PRY 28-Jul-97.
Ver.2, PRY 23-Sep-97 - added DILUTE keyword for photo-excitation
Ver.3, PRY 30-May-98 - added DENS_RANGE
CONTACT:
Peter Young, Cambridge University (P.R.Young@damtp.cam.ac.uk)
(See /home/drw/idl/bin/ptg/pop_plot.pro)
POWERLAG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: Powerlag.pro
PURPOSE: To view the change of correlation between the variation of frequency power of 2
lightcurves at various frequencies. It does this by creating wave plots of the the
2 lightcurves. It then takes a slice across the wavelet, creating a frequency 'power' curve.
USEAGE: powerlag,lightcurve1,lightcurve2,bandwidth,bandstep,correlations
INPUTs: lightcurves1 - first (filtered) lightcurve
lightcurves2 - second (filtered) lightcurve
bandwidth - width (in terms of frequency) of each band
bandstep - step up (in terms of frequency) of each successive band
OUTPUTS: corrs - a (3 * number of bands) array
first column is the shift for which maximum correlation occurs
second column is the maximum correlation
third column is the mean frequency of the band
CALLING: IDL> filt2,lc1,flc1
IDL> filt2,lc2,flc2
IDL> powerlag,flc1,flc2,0.2,0.05,res
IDL> window,2,title='3D PLOT'
IDL> surface,dist(5,5),/nodata,/save,xrange=[-50,50],yrange=[0,0.005],zrange=[-1.0,1.0],$
xtit='lag',ytit='freq',ztit='corr',charsize=3.0 ;defines axes
IDL> plots,res(0,*),res(2,*),res3(1,*),psym=4,/t3d,symsize=2.5,color=zcolors
IDL> colorbar,range=[-1.0,1.0],format='(F8.2)'
Or define which points you would like to discard by
IDL> okay=where( res(0,*) LT 40 AND res(0,*) GT -40 and res(1,*) GT 0.5 and res(1,*) GT 0.5)
and then define the axes accordingly
The 3D plot can be hard to decipher, the following lines plot 3 2D plots
IDL> window,1,title='2D plots',xsize=800,ysize=600
IDL> mult,2,2
IDL> surface,dist(5,5),/nodata,/save,xrange=[-40,40],yrange=[0,0.005],zrange=[0.5,1.0],$
IDL> xtit='lag',ytit='freq',ztit='corr',charsize=2
IDL> plots,res(0,okay),res(2,okay),res(1,okay),psym=4,/t3d,symsize=2.5,color=zcolors
IDL> plot,res(0,okay),res(2,okay),psym=3,yrange=[0,0.005],xtit='lag',ytit='freq'
IDL> plot,res(2,okay),res(1,okay),psym=3,xrange=[0.005,0],xtit='freq',ytit='corr'
IDL> plot,res(0,okay),res(1,okay),psym=3,xtit='lag',ytit='corr'
IDL> mult,1,1
HISTORY: v1.0 - written by R.T.James McAteer Jan' 02
(See /home/drw/idl/vtt/post_bbso/powerlag.pro)
POWERLAW1
[Previous Routine]
[Next Routine]
[List of Routines]
After JMA came back from BBSO, we talked about the statistical
tests that you can apply to a time series to see if it is indeed
random. Based on the method he described, and the method employed
in Cowsik et al.'s 1997 paper (SolPhys 170, 235), I've written this
routine to find the number of events that occur per power-of-event
bin. The power is determined by the Fourier power spectrum.
In a truly random time series, the relationship of log(N(E)) to E
will be a straight line with negative gradient
NAME:
POWERLAW1
PURPOSE:
To help determine if a time series is truly random, via the
distribution of frequency of peaks at given power intervals.
With equal power bins, the frequency of peaks at a certain
power interval should follow a power law (as described above).
CALLING SEQUENCE:
powerlaw1,time,series,bins,bincount,bins2,besfit,logcount
HISTORY:
DRW & JMA, 7-Sep-01, QUB.
(See /home/drw/idl/secis/powerlaw1.pro)
PRANK[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: prank
PURPOSE: compute the value in ARRAY which is at a given
percentile ranking within ARRAY. For example,
median_of_array=prank(array,50)
USEAGE: result=prank(array,percentile)
INPUT:
array an array of values, any type but string or complex
p percentile rank (0-100), may be a vector of ranks
OUTPUT: result=prank(array,percentile)
result=value within array which is at the specified percentile
rank
EXAMPLE:
r=10.^(randf(1000,2))*randomn(seed,1000)
plot,r,psym=3
plot,r,yrange=prank(r,[5,95]),psym=3
; print a set of percentile rankings within r
; percentile rank 0 => min
; percentile rank 50 => median
; percentile rank 100 => max
print,prank(r,[0,5,50,95,100])
REVISIONS:
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/bin/prank.pro)
PRANK[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: prank
PURPOSE: compute the value in ARRAY which is at a given
percentile ranking within ARRAY. For example,
median_of_array=prank(array,50)
USEAGE: result=prank(array,percentile)
INPUT:
array an array of values, any type but string or complex
p percentile rank (0-100), may be a vector of ranks
OUTPUT: result=prank(array,percentile)
result=value within array which is at the specified percentile
rank
EXAMPLE:
r=10.^(randf(1000,2))*randomn(seed,1000)
plot,r,psym=3
plot,r,yrange=prank(r,[5,95]),psym=3
; print a set of percentile rankings within r
; percentile rank 0 => min
; percentile rank 50 => median
; percentile rank 100 => max
print,prank(r,[0,5,50,95,100])
REVISIONS:
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/prank.pro)
PRANK[3]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: prank
PURPOSE: compute the value in ARRAY which is at a given
percentile ranking within ARRAY. For example,
median_of_array=prank(array,50)
USEAGE: result=prank(array,percentile)
INPUT:
array an array of values, any type but string or complex
p percentile rank (0-100), may be a vector of ranks
OUTPUT: result=prank(array,percentile)
result=value within array which is at the specified percentile
rank
EXAMPLE:
r=10.^(randf(1000,2))*randomn(seed,1000)
plot,r,psym=3
plot,r,yrange=prank(r,[5,95]),psym=3
; print a set of percentile rankings within r
; percentile rank 0 => min
; percentile rank 50 => median
; percentile rank 100 => max
print,prank(r,[0,5,50,95,100])
REVISIONS:
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/prank.pro)
PRECESS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PRECESS
PURPOSE:
Precess coordinates from EPOCH1 to EPOCH2. For interactive
display, one should use ASTRO which calls PRECESS.
CALLING SEQUENCE:
PRECESS,RA,DEC ;Prompt for initial and final epoch
PRECESS,RA,DEC,EPOCH1,EPOCH2
INPUTS:
RA - Input right ascension in DEGREES (scalar or vector)
DEC - Input declination in DEGREES (scalar or vector)
OPTIONAL INPUTS:
EPOCH1 - Original epoch of coordinates. If omitted, the program
will query for EPOCH1 and EPOCH2.
EPOCH2 - Epoch of precessed coordinates.
OUTPUTS:
RA - Right ascension after precession in DEGREES
DEC - Declination after precession in DEGREES
SIDE EFFECTS:
The input RA and DEC are modified to give the values after precession.
The result is always double precision, with the same number of dimensions.
RESTRICTIONS:
Accuracy of precession decreases for declination values near 90
degrees. PRECESS should not be used more than 2.5 centures from
1900.
EXAMPLE:
Precess the 1950 coordinates of Eps Ind (RA = 21h 59m,33.053s,
DEC = (-56d, 59', 33.053") to equinox 1950.
RA = TEN(21,59,33.053)*15. ;Convert to decimal degrees
DEC= TEN(-56,59,33.053)
PRECESS,RA,DEC,1950.,1975. ;Perform precession
PRINT,ADSTRING(RA,DEC) ;Print in pretty format
PROCEDURE:
Algorithm from Computational Spherical Astronomy by Taff (1983),
p. 24.
REVISION HISTORY
Written, Wayne Landsman, STI Corporation August 1986
Accept single element input vectors December 1988
Correct negative output RA values February 1989
(See /home/drw/idl/icur/precess2.pro)
PRINCAX[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: princax
PURPOSE: principle axis decomposion of a 2d distribution of points
USEAGE: princax,xx,yy,ev1,ev2,v1,v2
INPUTS:
xx, yy coordinate posititions
KEYWORD INPUTS:
view if set, draw a scatter plot and draw the major and minor
axis of the characteristic elipsoid with the half length
of the axis equal to the square root of the eigenvalue
OUTPUTS:
xcm,ycm coordinates of the center of mass
ev1,ev2 eigenvalues
v1,v2 principle axis
PROCEDURE: solves the following eigenvalue equation
A v = L v where A is the moment of inertia tensor
of the object, and L are the eigenvalues.
/ \
A = | |
\ /
the angled brackets indicate averages over
the point distribution
EXAMPLE:
u=5*randomn(iseed,50)
v=randomn(iseed,50)
x=u-v
y=u+v
princax,x,y,xcen,ycen,ev1,ev2,v1,v2,/view
AUTHOR: Paul Ricchiazzi nov93
Earth Space Research Group, UC Santa Barabara
REVISIONS:
(See /home/drw/idl/esrg/princax.pro)
PRINCAX[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: princax
PURPOSE: principle axis decomposion of a 2d distribution of points
USEAGE: princax,xx,yy,ev1,ev2,v1,v2
INPUTS:
xx, yy coordinate posititions
KEYWORD INPUTS:
view if set, draw a scatter plot and draw the major and minor
axis of the characteristic elipsoid with the half length
of the axis equal to the square root of the eigenvalue
OUTPUTS:
xcm,ycm coordinates of the center of mass
ev1,ev2 eigenvalues
v1,v2 principle axis
PROCEDURE: solves the following eigenvalue equation
A v = L v where A is the moment of inertia tensor
of the object, and L are the eigenvalues.
/ \
A = | |
\ /
the angled brackets indicate averages over
the point distribution
EXAMPLE:
u=5*randomn(iseed,50)
v=randomn(iseed,50)
x=u-v
y=u+v
princax,x,y,xcen,ycen,ev1,ev2,v1,v2,/view
AUTHOR: Paul Ricchiazzi nov93
Earth Space Research Group, UC Santa Barabara
REVISIONS:
(See /home/drw/idl/old.esrg/princax.pro)
PRINTLOG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PRINTLOG
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Captures transcript of console output
CALLING SEQUENCE:
PRINTLOG, d1, d2, ..., FORMAT=, LOG=LOG, /ONLYLOG, UNIT=UNIT
DESCRIPTION:
The PRINTLOG procedure provides the ability to print an arbitrary
expression to the console or an open file UNIT, and also to
capture the text in a "log" or archive. This archive can be used
as a verbatim record of console output, which is especially useful
when transactional history records must be maintained.
The log itself is stored as an array of strings which is passed
via the LOG keyword. PRINTLOG simply adds the current output to
the existing array and returns. When the transaction is complete,
the resulting array may be saved or printed as appropriate. For
example, the following set of commands will accumulate a log which
can be saved later:
IDL> x = 0 & y = 1 & u = -17. & v = 12. ;;; CREATE A LOG
IDL> PRINTLOG, X, Y, LOG=LOG
0 1
IDL> PRINTLOG, U, V, LOG=LOG
-17.0000 12.0000
IDL> PRINTLOG, 'Computation done.', LOG=LOG
Computation done.
IDL> print, log, format='(A)' ;;; PRINT THE LOG
0 1
-17.0000 12.0000
Computation done.
NOTE: Output to the console can be disabled and re-enabled using
the DEFAULT_PRINT keyword. The DEFAULT_PRINT keyword affects the
permanent state of PRINTLOG. When it is set to 0, then *all*
subsequent console output will be disabled until DEFAULT_PRINT is
reset to 1. Output will always be logged to the LOG;
DEFAULT_PRINT only controls the console output. This can be
useful to have a global switch which determines the governs the
console activity of an application. However, only *one* global
control variable is available.
INPUTS:
d1, d2, ... - the variables or expressions to be printed, as in
the PRINT or PRINTF commands. A maximum of twenty
parameters are allowed.
KEYWORDS:
LOG - input/output keyword, containing the accumulated transaction
log. Upon input, LOG should be an array of strings
containing previously accumulated log. Upon return, LOG
will have any new output appended. If, upon input, LOG is
undefined, or contains a single element (-1L or ''), then
LOG will be initialized.
FORMAT - a standard format statement, as used by STRING, PRINT or
PRINTF.
Default: default output formatting is used.
UNIT - a file unit to be used for output. If UNIT is undefined or
0, then output is made to the console.
Default: undefined (console output).
ONLYLOG - if set, then output will not be made to the screen, but
it will still be archived to LOG. This may useful to
record archane but important dianostic information that
normally would not appear to the user.
DEFAULT_PRINT - Change default behavior of PRINTLOG. If
DEFAULT_PRINT is 0 then all subsequent printlog's
will *not* be printed to the console, until
DEFAULT_PRINT is reset. If DEFAULT_PRINT is 1
then all subsequent printlog's will be printed to
the console.
Initial default: 1 (print to console)
Default: none (user must explicitly set)
EXAMPLE:
See above.
SEE ALSO:
PRINT, PRINTF, STRING
STATUSLINE - To print temporary status messages to console
MODIFICATION HISTORY:
Written, CM, June 1999
Documented, CM, 25 Feb 2000
Added STATUSLINE to "SEE ALSO," CM, 22 Jun 2000
Be more intelligent about growing log if PRINTLOG will be called
many times (secret NLOGLINES keyword parameter), CM, Feb 2003
Corrected bug if N_PARAMS was larger than 10, (H. Krimm) CM, 13
Feb 2003
Added DEFAULT_PRINT keyword, CM, 10 Oct 2003
TODO:
Have a way to internally store the log, rather than the LOG
keyword.
$Id: printlog.pro,v 1.5 2003/11/24 00:08:23 craigm Exp $
(See /home/drw/idl/aux/markwardt/printlog.pro)
PRINTRC[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: printrc
PURPOSE: Prints the row and col. given an index
USEAGE: printrc,Array, Index, Row, Col
INPUT:
OUTPUT:
Example:
AUTHOR: Peter T. Gallagher, June '98
(See /home/drw/idl/bin/printrc.pro)
PRINTRC[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: printrc
PURPOSE: Prints the row and col. given an index
USEAGE: printrc,Array, Index, Row, Col
INPUT:
OUTPUT:
Example:
AUTHOR: Peter T. Gallagher, June '98
(See /home/drw/idl/bin/ptg/printrc.pro)
PRINTWINDOW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME
PRINTWINDOW
This program sends the contents of the specified
window to the default printer. The current window
is used if a window index number is not provided.
POSITIONAL PARAMETERS:
WID The window index number of the window to send to the
printer. !D.Window used by default.
KEYWORD PARAMETERS:
LANDSCAPE If this keyword is set, the output is in Landscape
mode. Otherwise, Portrait mode is used.
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".
Written by David Fanning based on previous PRINT_IT program. 29 July 2000.
(See /home/drw/idl/aux/printwindow.pro)
PRINTXY
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: printxy
PURPOSE: Prints the x & y coords, given an index
USEAGE: printxy,Array, Index, x,y
INPUT:
OUTPUT:
Example:
AUTHOR: Peter T. Gallagher, June '98
(See /home/drw/idl/gen/printxy.pro)
PROCESS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PROCESS
PURPOSE:
The purpose of this routine is to demonstrate a simple
image processing program that runs as a "color aware"
application. The program works on 8-bit, 16-bit, and
24-bit displays. The image is displayed in a resizeable
graphics window and the window contents can be saved as
GIF or JPEG images. The application can "protect" its
colors from other applications that change colors. The
color protection is implemented via draw widget EXPOSE
events or the Refresh Colors button in the menubar.
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.
CALLING SEQUENCE:
PROCESS
INPUTS:
image: An optional 2D image. The image is always scaled.
KEYWORD PARAMETERS:
BOTTOM: The lowest color index of the colors to be changed.
GROUP: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
NCOLORS: This is the number of colors to load when a color table
is selected.
COMMON BLOCKS:
None.
SIDE EFFECTS:
This is a non-blocking widget.
RESTRICTIONS:
The GETIMAGE and XCOLORS programs from the Fanning Consulting
web page are required: http://www.dfanning.com/.
EXAMPLE:
To run the program, type:
PROCESS
MODIFICATION HISTORY:
Written by: David Fanning, 13 April 97.
Fixed a bug in the TVImage call. 25 June 97. DWF.
Extensively modified to incorporate changing ideas
about color protection and operation on 8-bit and
24-bit displays. 19 Oct 97. DWF.
Whoops. Forgot to make *this* draw widget the current
graphics window. 15 Nov 97. DWF.
IDL 5.1 changed the way color decomposition works. Had
to find a fix for this. 25 May 98. DWF.
(See /home/drw/idl/aux/process.pro)
PROCESSES[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: PROCESSES
PURPOSE:
To show the contributions of the different atomic processes to the
level balance of a selected level.
EXPLANATION:
Takes the CHIANTI atomic data and works out the populations entering
and leaving a specified level. If TEMP not selected, then the T_max
is used.
CALLING SEQUENCE:
PROCESSES, IZ, ION, DENS, TEMP=TEMP, DIL=DIL, LEVEL=LEVEL
EXAMPLES:
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
OPTIONAL INPUTS:
DENS: Logarithm of electron density (default: 10)
TEMP: If not specified, the T_max of the ion is used
DIL: The dilution factor to be used for radiative processes.
LEVEL: The level for which data is required. (Default=1)
KEYWORDS:
COMMON BLOCKS:
ELVL, WGFA, UPSILON, RADIATIVE
CALLS:
POPULATE_PRY, READ_ELVLC
HISTORY:
Ver 1, PRY 10-Dec-97
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/processes.pro)
PROCESSES[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: PROCESSES
PURPOSE:
To show the contributions of the different atomic processes to the
level balance of a selected level.
EXPLANATION:
Takes the CHIANTI atomic data and works out the populations entering
and leaving a specified level. If TEMP not selected, then the T_max
is used.
CALLING SEQUENCE:
PROCESSES, IZ, ION, DENS, TEMP=TEMP, DIL=DIL, LEVEL=LEVEL
EXAMPLES:
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
OPTIONAL INPUTS:
DENS: Logarithm of electron density (default: 10)
TEMP: If not specified, the T_max of the ion is used
DIL: The dilution factor to be used for radiative processes.
LEVEL: The level for which data is required. (Default=1)
KEYWORDS:
COMMON BLOCKS:
ELVL, WGFA, UPSILON, RADIATIVE
CALLS:
POPULATE_PRY, READ_ELVLC
HISTORY:
Ver 1, PRY 10-Dec-97
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/ptg/processes.pro)
PROFREE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PROFREE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Free the pointers associated with an PRODIS abstract syntax tree
CALLING SEQUENCE:
PROFREE, TREE
DESCRIPTION:
PROFREE frees the memory and pointers associated with an abstract
syntax tree, as returned by PRODIS. Users should use this
procedure when they are finished with an abstract syntax tree and
want to release its resources. The procedure frees all pointers
in the tree recursively.
INPUTS:
TREE - the abstract syntax tree to be freed. Upon return the
contents of TREE will be undefined.
SEE ALSO:
PRODIS, PROREND, CMSAVEDIR, CMSVLIB
MODIFICATION HISTORY:
Written, 2000-2002, CM
Documented, 19 Mar 2002, CM
$Id: profree.pro,v 1.3 2002/03/19 21:45:02 craigm Exp $
(See /home/drw/idl/aux/markwardt/profree.pro)
PROREND
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PROREND
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Render a PRODIS abstract syntax tree into IDL Language Text
CALLING SEQUENCE:
PROREND, TREE, TEXT, [ /INIT ]
DESCRIPTION:
PROREND converts an abstract syntax tree as returned by PRODIS,
into a human-readable form, written in the IDL programming
language. The abstract syntax tree format is a set of linked data
structures, and is derived from the raw data on disk. The human
readable form is returned as an array of strings that can be
printed to the console or a file.
The abstract syntax tree is generated by PRODIS, an external
procedure in the same library. The standard approach is to use
the following steps:
1. Use PRODIS to convert raw bytes to abstract syntax tree
2. Use PROREND to convert abstract syntax tree to IDL language
The external routine PROTRANS does the end-to-end conversion steps
of both PRODIS and PROREND for you.
At the moment there is relatively little flexibility in how the
IDL code is rendered to text. For example, all reserved keywords
and variables appear in upper-case letters, and array indexing
syntax is expressed with round ()'s instead of square []'s.
Suggestions on how to achieve this are solicited.
PROREND does not free the TREE structure. The user is responsible
to do this using the PROFREE procedure.
COMPATIBILITY:
-- File Format --
PROREND accepts any tree provided by PRODIS. PRODIS cannot
examine compressed save files. It is able to read and translate
SAVE files produced by IDL 4, and IDL versions 5.0 through 5.5.
The output of PROREND should be compatible with IDL 4 and 5.
This procedure is part of the CMSVLIB SAVE library for IDL by
Craig Markwardt. You must have the full CMSVLIB core package
installed in order for this procedure to function properly.
INPUTS:
TREE - the abstract syntax tree, as returned by PRODIS. This
structure is unmodified by PROREND.
TEXT - upon output, the IDL code is placed in as an array of
strings in TEXT. By default, any new IDL code will be
*appended* to TEXT. Use the /INIT keyword to overwrite the
existing contents of TEXT.
KEYWORDS:
INIT - if set, then overwrite the TEXT array with the new IDL
code. By default (INIT not set), any new IDL code is
*appended* to TEXT.
EXAMPLE:
This example compiles a test function, saves it to a file called
test_pro.sav, and then disassembles the save file into a syntax
tree using PRODIS. Finally, the syntax tree is converted to IDL
text, which is printed to the console.
IDL> .comp
- pro test_pro, x
- x = x + 1
- return
- end
% Compiled module: TEST_PRO.
IDL> save, 'test_pro', /routine, file='test_pro.sav'
IDL> prodis, 'test_pro.sav', prodecl, tree
IDL> prorend, tree, text
IDL> print, text, format='(A)'
PRO TEST_PRO, X
;; Beginning of code
X = X+1
RETURN
END
SEE ALSO:
PRODIS, PROREND, CMSAVEDIR, CMSVLIB
MODIFICATION HISTORY:
Written, 2000-2002, CM
Documented, 19 Mar 2002, CM
Added PRN_STRCAT, to avoid an internal library function, 22 Mar
2002, CM
$Id: prorend.pro,v 1.13 2002/03/22 22:01:11 craigm Exp $
(See /home/drw/idl/aux/markwardt/prorend.pro)
PSCONFIG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PSCONFIG
PURPOSE:
This program is simply a function wrapper for the FSC_PSCONFIG
object program (fsc_psconfig__define.pro). It was written so
that it could serve as a drop-in replacement for the PS_FORM
program it replaces. It calls the object program's graphical
user interface as a modal widget and returns the DEVICE keywords
collected from the form in a form that is appropriate for
configuring the PostScript device.
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/
CALLING SEQUENCE:
psKeywords = PSConfig()
CATEGORY:
Configuring PostScript output.
DOCUMENTATION:
Complete documentation for the FSC_PSCONFIG object, including
keyword and method descriptions, and example programs using the object
can be found on the Coyote's Guide to IDL Programming web page:
http://www.dfanning.com/programs/docs/fsc_psconfig.html
INPUT:
psConfigObject -- An optional FSC_PSCONFIG object reference can be
passed as an argument to the function. The object is not destroyed
if passed in as an argument.
psObject = Obj_New("FSC_PSCONFIG")
keywords = PSConfig(psObject)
Having the object means that you have an on-going and current record
of exactly how your PostScript device is configured. Be sure to destroy
the object when you are finished with it.
KEYWORDS:
Any keyword accepted by the FSC_PSCONFIG object can be used with
this program. Here are a few of the most popular keywords.
Bits_per_Pixel - The number of image bits saved for each image pixel: 2, 4, or 8. The default is 8.
Color - Set this keyword to select Color PostScript output. Turned on by default.
DefaultSetup - Set this keyword to the "name" of a default style. Current styles (you can easily
create and add your own to the source code) are the following:
"System (Portrait)" - The normal "default" system set-up. Also, "System".
"System (Landcape)" - The normal "default" landscape system set-up.
"Centered (Portrait)" - The window centered on the page. Also, "Center" or "Centered".
"Centered (Landscape)" - The window centered on the landscape page. Also, "Landscape".
"Square (Portrait)" - A square plot, centered on the page.
"Square (Landscape)" - A square plot, centered on the landscape page.
"Figure (Small)" - A small encapsulated figure size, centered on page. Also, "Encapsulated" or "Encapsulate".
"Figure (Large)" - A larger encapsulated figure size, centered on page. Also, "Figure".
"Color (Portrait)" - A "centered" plot, with color turned on. Also, "Color".
"Color (Landscape)" - A "centered" landscape plot, with color turned on.
Directory - Set this keyword to the name of the starting directory. The current directory is used by default.
Encapsulate - Set this keyword to select Encapsulated PostScript output. Turned off by default.
European - Set this keyword to indicate "european" mode (i.e., A4 page and centimeter units). Turned off by default.
Filename - Set thie keyword to the name of the PostScript file. The default is "idl.ps".
Inches - Set this keyword to indicate sizes and offsets are in inches as opposed to centimeters. Set by European keyword by default.
Landscape - Set this keyword to select Landscape page output. Portrait page output is the default.
PageType - Set this keyword to the "type" of page. Possible values are:
"Letter" - 8.5 by 11 inches. (Default, unless the European keyword is set.)
"Legal" - 8.5 by 14 inches.
"Ledger" - 11 by 17 inches.
"A4" - 21.0 by 29.7 centimeters. (Default, if the European keyword is set.)
XOffset - Set this keyword to the X Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
XSize - Set this keyword to the X size of the PostScript "window". Uses "System (Portrait)" defaults.
YOffset - Set this keyword to the Y Offset. Uses "System (Portrait)" defaults. (Note: offset calculated from lower-left corner of page.)
YSize - Set this keyword to the Y size of the PostScript "window". Uses "System (Portrait)" defaults.
In addition, the following keywords can be used:
CANCEL -- An output keyword that will be set to 1 if the user
chooses the Cancel button on the form. It will be 0 otherwise.
FONTINFO -- Set this keyword is you wish to have font information
appear on the form. The default is to not include font information.
FONTTYPE -- Set this keyword to a named variable that will indicate
the user's preference for font type. Values will be -1 (Hershey fonts),
0 (hardware fonts), and 1 (true-type fonts). This keyword will always
return -1 unless the FONTINFO keyword has also been set.
GROUP_LEADER -- Set this keyword to a widget identifier of the widget
you wish to be a group leader for this program.
EXAMPLE:
To have the user specify PostScript configuration parameters, use
the program like this:
keywords = PSConfig(Cancel=cancelled)
IF cancelled THEN RETURN
thisDevice = !D.Name
Set_Plot, 'PS'
Device, _Extra=keywords
Plot, findgen(11) ; Or whatever graphics commands you use.
Device, /Close_File
Set_Plot, thisDevice
OTHER PROGRAMS NEEDED:
The following programs are required to run this one:
fsc_droplist.pro
fsc_fileselect.pro
fsc_inputfield.pro
fsc_plotwindow
fsc_psconfig__define.pro
MODIFICATIONS:
Written by David Fanning, 31 January 2000.
(See /home/drw/idl/aux/psconfig.pro)
PSD[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: psd
USEAGE: psd,image,wavenum,power,scale=scale,view=view,$
unit=unit,title=title,binpower=binpower,$
xrange=xrange,density=density
PURPOSE: compute angle averaged power spectral density of an image
INPUT:
image
a one or two dimensional data array
OUTPUT:
wavenum
The spatial wave number of the scene (averaged over angle if
image is 2-D). WAVENUM ranges from a minimum value of about
2/max(NX,NY) cycle/pixel (i.e., the zero frequency component
should not be included) to a maximum value of 1 cycle/pixel,
i.e, the Nyquist frequency of the scene. If SCALE is set,
WAVENUM has units of cycles/unit where unit is the physical
units used to set SCALE (see UNIT and SCALE, below). If you
want to have WAVENUM expressed in units of cycles/frame,
(which only makes sense when NX=NY) set
SCALE=[1./fix(NX/2),1./fix(NY/2)]
power
energy spectra of scene. if image has only one dimension POWER
is the squared modulus of the fourier transform. If image is
two dimensional POWER is the angular integration of the
squared modulus of fourier transform coeficients, P, over the
anulus defined by a given value of k=sqrt(kx^2+ky^2).
total power = integral(2 pi P k dk) = integral(POWER(k) dk),
KEYWORD INPUT:
scale
physical resolution of image, i.e., the size of a single picture
element in physical units such as kilometers. If SCALE is set
to a two element vector, the two values specify the resolution
in the x and y directions, respectively. When SCALE is set, the
units of WAVENUM are cycles/unit where UNIT are the physical
units (see below) in which SCALE is specified.
unit
string variable specifying the physical units used to specify
SCALE (used in xtitle of plot)
view
if set, plot log-log plot of psd
if VIEW=2, WAVENUM and POWER are taken as input parameters
(i.e., psd is not computed) for the PSD plot option. In this
case the IMAGE parameter is not used, but a dummy value must be
supplied.
title
plot title
binpower
If set, changes the default bin size used for 2-D wavevector
binning. Normally wavevector binning is set up to put one
unit of the scalor wavevector in each wavenumber bin:
k = sqrt(kx^2+ky^2) scalor wavenumber
n < k < n+1
where n is an integer index for each wavenuber bin. anulus. The
kx and ky wavenumbers run from 0 to NX/2 and 0 to NY/2,
respectively, (NX/2 and NY/2 represent the Nyquist frequency) If
BINPOWER is set, the size of the wavenumber bins can be made to
increase as a power of the wavenumber so that
binsize = wavenumber^BINPOWER
for example setting binpower gt 0 causes more averaging at large
wavenumber and can be used to smooth out noisy power spectra.
A value of BINPOWER between .1 and .5 seems to be sufficient to
smooth out high frequency noise. (default: binpower=0)
xrange
XRANGE sets the min and max wavenumber included in power
spectrum plot. XRANGE is used to clip off noisy high frequency
part of psd which sometimes occurs beyond 1 cycle per pixel in
the horizontal or vertical direction. XRANGE does not affect
the returned values of WAVENUM and POWER, but it does affect the
value of BETA.
NOTE: For a square uniform grid the maximum wavenumber is
sqrt(2) x 1 cycle/pixel.
density
if set, plot spectral power density instead of spectral power.
This is equivalent to dividing the power spectra by the
wavenumber.
EXAMPLE:
; PSD of a scaling field
w8x11
!p.multi=[0,1,2]
n=512 ;
slope=3 ; power law slope
power=1./(1.>(dist(n)^(slope+1)))
gg=sqrt(power) ; fourier modulus
gg=gg*exp(complex(0,2*!pi*randomu(iseed,n,n))) ; randomized phase
ff=float(fft(gg,1)) ; realization
tvim,ff
psd,ff,/view
; Spectra of a 1-d data
n=2^14
f=randf(n,2)
!p.multi=[0,1,2]
plot,w,f
psd,f,w,p,/view
; PSD of a submatrix of a scene with spatially varying spectral structure,
;
; 1. lower left quandrant: scaling scene (SS) with spectral slope -2.5
; 2. upper left quandrant: SS plus structure at 0.125 nyq
; 3. upper right quandrant: SS plus structure at .25 and 0.125 nyq
; 4. upper left quandrant: SS plus structure at .25 nyq
;
; where nyq = 1.4141 cycles/(horizontal or vertical pixel)
;
; to stop looping this example, put box in lower frame and click RMB
w8x11
!p.multi=[0,1,2]
nx=512 & ny=512
ff=randata(nx,ny,s=2.5)
ff=5*cos(0.125*!pi*findgen(nx))#cos(0.125*!pi*findgen(ny))*$
(((replicate(1,nx)#findgen(ny)/(ny-1))-.5)>0)+ff
ff=5*cos(0.25*!pi*findgen(nx))#cos(0.25*!pi*findgen(ny))*$
(((findgen(ny)/(ny-1))#replicate(1,ny)-.5)>0)+ff
tvim,ff
xwin=!x.window & xrng=!x.crange
ywin=!y.window & yrng=!y.crange
x1=nx/4 & x2=x1+nx/2
y1=ny/4 & y2=y1+ny/2
!p.multi=[4,2,4]
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,inc=8,/init,/mess,label='region 1'
psd,ff(x1:x2,y1:y2),/view,title='region 1'
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,inc=8,/init,/mess,label='region 2'
psd,ff(x1:x2,y1:y2),/view,title='region 2'
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,inc=8,/init,/mess,label='region 3'
psd,ff(x1:x2,y1:y2),/view,title='region 3'
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,inc=8,/init,/mess,label='region 4'
psd,ff(x1:x2,y1:y2),/view,title='region 4'
author: Paul Ricchiazzi may93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/psd.pro)
PSD[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: psd
USEAGE: psd,image,wavenum,power,scale=scale,view=view,$
unit=unit,title=title,binpower=binpower,$
xrange=xrange,density=density
PURPOSE: compute angle averaged power spectral density of an image
INPUT:
image
a one or two dimensional data array
OUTPUT:
wavenum
The spatial wave number of the scene (averaged over angle if
image is 2-D). WAVENUM ranges from a minimum value of about
2/max(NX,NY) cycle/pixel (i.e., the zero frequency component
should not be included) to a maximum value of 1 cycle/pixel,
i.e, the Nyquist frequency of the scene. If SCALE is set,
WAVENUM has units of cycles/unit where unit is the physical
units used to set SCALE (see UNIT and SCALE, below). If you
want to have WAVENUM expressed in units of cycles/frame,
(which only makes sense when NX=NY) set
SCALE=[1./fix(NX/2),1./fix(NY/2)]
power
energy spectra of scene. if image has only one dimension POWER
is the squared modulus of the fourier transform. If image is
two dimensional POWER is the angular integration of the
squared modulus of fourier transform coeficients, P, over the
anulus defined by a given value of k=sqrt(kx^2+ky^2).
total power = integral(2 pi P k dk) = integral(POWER(k) dk),
KEYWORD INPUT:
scale
physical resolution of image, i.e., the size of a single picture
element in physical units such as kilometers. If SCALE is set
to a two element vector, the two values specify the resolution
in the x and y directions, respectively. When SCALE is set, the
units of WAVENUM are cycles/unit where UNIT are the physical
units (see below) in which SCALE is specified.
unit
string variable specifying the physical units used to specify
SCALE (used in xtitle of plot)
view
if set, plot log-log plot of psd
if VIEW=2, WAVENUM and POWER are taken as input parameters
(i.e., psd is not computed) for the PSD plot option. In this
case the IMAGE parameter is not used, but a dummy value must be
supplied.
title
plot title
binpower
If set, changes the default bin size used for 2-D wavevector
binning. Normally wavevector binning is set up to put one
unit of the scalor wavevector in each wavenumber bin:
k = sqrt(kx^2+ky^2) scalor wavenumber
n < k < n+1
where n is an integer index for each wavenuber bin. anulus. The
kx and ky wavenumbers run from 0 to NX/2 and 0 to NY/2,
respectively, (NX/2 and NY/2 represent the Nyquist frequency) If
BINPOWER is set, the size of the wavenumber bins can be made to
increase as a power of the wavenumber so that
binsize = wavenumber^BINPOWER
for example setting binpower gt 0 causes more averaging at large
wavenumber and can be used to smooth out noisy power spectra.
A value of BINPOWER between .1 and .5 seems to be sufficient to
smooth out high frequency noise. (default: binpower=0)
xrange
XRANGE sets the min and max wavenumber included in power
spectrum plot. XRANGE is used to clip off noisy high frequency
part of psd which sometimes occurs beyond 1 cycle per pixel in
the horizontal or vertical direction. XRANGE does not affect
the returned values of WAVENUM and POWER, but it does affect the
value of BETA.
NOTE: For a square uniform grid the maximum wavenumber is
sqrt(2) x 1 cycle/pixel.
density
if set, plot spectral power density instead of spectral power.
This is equivalent to dividing the power spectra by the
wavenumber.
EXAMPLE:
; PSD of a scaling field
w8x11
!p.multi=[0,1,2]
n=512 ;
slope=3 ; power law slope
power=1./(1.>(dist(n)^(slope+1)))
gg=sqrt(power) ; fourier modulus
gg=gg*exp(complex(0,2*!pi*randomu(iseed,n,n))) ; randomized phase
ff=float(fft(gg,1)) ; realization
tvim,ff
psd,ff,/view
; Spectra of a 1-d data
n=2^14
f=randf(n,2)
!p.multi=[0,1,2]
plot,w,f
psd,f,w,p,/view
; PSD of a submatrix of a scene with spatially varying spectral structure,
;
; 1. lower left quandrant: scaling scene (SS) with spectral slope -2.5
; 2. upper left quandrant: SS plus structure at 0.125 nyq
; 3. upper right quandrant: SS plus structure at .25 and 0.125 nyq
; 4. upper left quandrant: SS plus structure at .25 nyq
;
; where nyq = 1.4141 cycles/(horizontal or vertical pixel)
;
; to stop looping this example, put box in lower frame and click RMB
w8x11
!p.multi=[0,1,2]
nx=512 & ny=512
ff=randata(nx,ny,s=2.5)
ff=5*cos(0.125*!pi*findgen(nx))#cos(0.125*!pi*findgen(ny))*$
(((replicate(1,nx)#findgen(ny)/(ny-1))-.5)>0)+ff
ff=5*cos(0.25*!pi*findgen(nx))#cos(0.25*!pi*findgen(ny))*$
(((findgen(ny)/(ny-1))#replicate(1,ny)-.5)>0)+ff
tvim,ff
xwin=!x.window & xrng=!x.crange
ywin=!y.window & yrng=!y.crange
x1=nx/4 & x2=x1+nx/2
y1=ny/4 & y2=y1+ny/2
!p.multi=[4,2,4]
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,inc=8,/init,/mess,label='region 1'
psd,ff(x1:x2,y1:y2),/view,title='region 1'
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,inc=8,/init,/mess,label='region 2'
psd,ff(x1:x2,y1:y2),/view,title='region 2'
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,inc=8,/init,/mess,label='region 3'
psd,ff(x1:x2,y1:y2),/view,title='region 3'
curbox,x1,x2,y1,y2,xwin,ywin,xrng,yrng,inc=8,/init,/mess,label='region 4'
psd,ff(x1:x2,y1:y2),/view,title='region 4'
author: Paul Ricchiazzi may93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/psd.pro)
PSWINDOW
[Previous Routine]
[Next Routine]
[List of Routines]
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.
(See /home/drw/idl/aux/pswindow.pro)
PS_FORM[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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
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
MAJOR TOPICS:
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.
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
(See /home/drw/idl/aux/ps_form.pro)
PS_FORM[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
PS_FORM
PURPOSE:
This function puts up a form the user can configure a PostScript
device driver. The function result (if the user selects either the
ACCEPT or CREATE FILE buttons) can be sent directly to the DEVICE
procedure by means of its _Extra keyword. User's predefined
configurations may be retrieved from a common block.
AUTHOR:
*********** CM 01 Feb 2000 VERSION *************
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
$Id: ps_form.pro,v 1.4 2001/12/11 20:20:37 craigm Exp $
Based almost entirely on, but a totally revamped version of, PS_FORM by
FANNING SOFTWARE CONSULTING (David Fanning Ph.D.) http://www.dfanning.com
MAJOR TOPICS:
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 DEVICE command are returned.
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.
HELP:
formInfo = PS_FORM(/Help)
CALLING SEQUENCE:
formInfo = PS_FORM(xoffset, yoffset, Cancel=cancelButton)
OPTIONAL INPUTS:
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)
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 interrupting the user.
SELECT -- used only when INITIALIZE is set. Set SELECT to a
string which identifies the predefined configuration to
be returned by ps_form when INITIALIZE is set. This is
a convenient way to select a predefined config
non-interactively.
LANDSCAPE -- The initial configuration of the landscape/portrait switch.
LOCALDEFAULTS -- A structure like the DEFAULTS structure. If specified,
then it is added as a predefined configuration entry called "Local".
See below for a further discussion of predefined configurations.
PREDEFINED -- An alternate way to specify predefined
configurations. Pass an array of structures to
populate the "predefined" dropbox in the
dialog. This array, if specified, overrides the the
common block technique.
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.
ASPECT -- The aspect ratio of the window (Y/X). This keyword can
substitute for one of XSIZE or YSIZE.
PRESERVE_ASPECT -- Set this keyword if you want to hold the
aspect ratio constant.
PAPERSIZE -- If set, allows user to specify the size of the paper
media to be printed on, as a scalar string. NOTE:
this specification cannot be passed to DEVICE, but
can be selected for completeness's sake. Default is
'Letter'.
MARGINSIZE -- Size of the margins on all sides. Default is 0.25 inches.
When MARGINSIZE is non-zero, a graphic cannot directly
abut the edge of the page. This is normally a good thing,
since there is often a non-printable region which borders
the page.
DEFAULTPAPER -- Default paper size to use, when it is unspecified
in a predefined, "local", or "default"
configuration. This value also overrides any
configuration from common blocks. European users
will probably set this to 'A4'.
PARENT -- if this widget is invoked by another widget program,
then this keyword parameter must be set to the top level
widget which is to serve as the group leader. Failure
to do so will result in unexpected behavior. IDL 4
programs do not need to pass this parameter. Default:
NONE.
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.
PAPERSIZE -- If set to a named variable, any newly selected paper
size is returned in that variable.
XPAGESIZE -- Size of paper in "X" dimension, in units given by
the returned config structure.
YPAGESIZE -- Size of paper in "Y" dimension, in units given by
the returned config structure.
PAGEBOX -- specifies the page rectangle relative to the plot
window, in normalized units. A 4-vector of the form
[XLL, YLL, XUR, YUR] is returned, giving the positions
of the lower left (LL) and upper right (UR) corners of
the page with respect to the plot window. Thus, the
following command:
PLOT, x, y, position=PAGEBOX
will construct a graphic whose plot region exactly
fills the page (with no margin around the edges).
Naturally, the page is usually larger than the
graphics window, so the normalized coordinates will
usually fall outside the range [0,1].
However, the bounding box constructed by the
Postscript driver includes only the graphics window.
Anything drawn outside of it may be clipped or
discarded.
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?
isolatin1:0,$ ; Encoded with ISOLATIN1?
landscape:0 } ; Landscape or portrait mode?
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)
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
info.ps_config = formInfo
ENDIF ELSE
info.ps_config = formInfo
ENDIF
MAJOR FUNCTIONS and PROCEDURES:
None. Designed to work originally in conjunction with XWindow, a
resizable graphics window. [ NOTE: this modified version of
ps_form, by Craig Markwardt, is incompatible with the original
version of XWINDOW. ]
MODIFICATION HISTORY:
Based on ps_form of : David Fanning, RSI, March 1995.
Major rewrite by: Craig Markwardt, October 1997.
- Drawing and updating of form and sample box are now modular
- Option of storing more than one predefined postscript configuration
- Selection of paper size by name
- Access to predfined configurations through (optional) common
block
Several additions, CM, April 1998 VERSION CM2.0
- better integration of paper sizes throughout program.
Predefined configurations now also know about paper.
- allow passing predefined configurations instead of using
common block
- addition of ISOLATIN selection, and streamlining of dialog
appearance
Fixed bug in INITIALIZE w.r.t. paper sizes, CM, Nov 1998
Added SELECT keyword, CM, 09 Dec 1998
Added Parent keyword to allow modal widgets in IDL 5, 19 Jan 1999
Added "Choose" button for filename selection, 19 Sep 1999
Added ability to program different button names, 19 Sep 1999
Added ASPECT and PRESERVE_ASPECT, based on work by Aaron Barth, 18
Oct 1999
Removed NOCOMMON documentation and logic, 19 Oct 1999, CM
Added aspect to ps_form_numevents (per Aaron Barth), 18 Oct 1999
Corrected small bug under Initialize keyword (inches), 18 Oct 1999
Made call to *_pscoord more consistent, 18 Oct 1999
Added XPAGESIZE, YPAGESIZE and PAGEBOX keywords, 19 Oct 1999
Small cosmetic cleanup, CM, 01 Feb 2000
Fix for IDL 5.5's handling of structures with arrays, CM, 11 Dec 2001
COMMON BLOCKS:
The user may store frequently used or helpful configurations in a
common block, and ps_form() will attempt to access them. This
provides a way for the user to have persistent, named,
configurations.
NOTE: this format has changed since the last version. You may
have to quit your IDL session for the changes to take effect
properly. If you have place a predefined configuration in your
startup file, you should review the new format.
COMMON PS_FORM_CONFIGS, ps_form_DEFAULT_PAPERSIZE, $
ps_form_STDCONFIGS
ps_form_DEFAULT_PAPERSIZE - a string designating the default
paper size, when none is given.
The predefined configurations
offerred by this program will
respect the default value. (See
also the DEFAULTPAPER keyword.)
ps_form_STDCONFIGS - An array of ps_form_CONFIG structures,
each containing information about one
predefined configuration, such as its
name and size of paper. Each "config"
element is a ps_form_INFO structure,
which contains the actual postscript
configuration.
See the IDL source code ps_form_LOAD_CONFIGS for an example of how
to make a list of configurations. One possibility would be to
declare and populate the common block from within the user's
start-up script, allowing the same configurations to appear in
every session.
ps_form() takes its initial list of configurations from this
common block if it exists. A default list is provided ala the
procedure ps_form_LOAD_CONFIGS. Any modifications that take place
during the ps_form() widget session are not transferred back to
the common block upon return. It might be useful to be able to do
this, through some form of 'save' procedure.
Also, if the PREDEFINED keyword is used, then the common block is
not consulted.
$Id: ps_form.pro,v 1.4 2001/12/11 20:20:37 craigm Exp $
(See /home/drw/idl/aux/markwardt/ps_form.pro)
PTG_GAUSS
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : CDS_GFUNCT
Purpose : Evaluate gaussian and its partial derivatives.
Explanation : Used in call to curvefit from cds_gauss
Use : Only as parameter to curvefit
Inputs : X = VALUES OF INDEPENDENT VARIABLE.
A = PARAMETERS OF EQUATION DESCRIBED BELOW.
Opt. Inputs : None
Outputs : Value of function at each x value
Opt. Outputs: None
Keywords : None
Calls : None
Common : None
Restrictions: For use with cds_gauss and curvefit
Side effects: None
Category : Util, numerical
Prev. Hist. : As below for cds_gauss
Written : CDS version C D Pike, RAL, 7-Jan-94
Modified : Trap no data. CDP, 18-Jan-95
Version : Version 2, 18-Jan-95
(See /home/drw/idl/old.esrg/ptg_gauss.pro)
PULSEFUNC
[Previous Routine]
[Next Routine]
[List of Routines]
simulates an impulse which might drive a fast wave inside
a coronal loop, as per Berghmans, De Bruyne & Goossens, 1996
(See /home/drw/idl/secis/pulsefunc.pro)
PUTSTR[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE:
putstr
PURPOSE:
use cursor to position and orient text on a plot
USEAGE:
putstr,label,xs,ys,orient=orient,charsize=charsize,color=color,$
subnorm=subnorm,norm=norm,align=align,contrast=contrast, $
bg_color=bg_color,box=box,valign=valign
INPUT:
label
text label, type string
xs
x position of string (data coordinates, default)
ys
y position of string (data coordinates, default)
KEYWORD INPUT:
orient
orientation in degrees
charsize
character size parameter. The character size is the value of
CHARSIZE * !p.charsize. (default=1)
subnorm
if set, x and y positions are specified in data window
sub-normalized coordinates, i.e, the range 0 to 1 spans the entire
data coordinate range. Note that this is different then the
usual IDL normalized coordinates. When SUBNORM is set, a
given x,y coordinate causes the text to appear in the same
data window region regardless of how the x and y axes are
scaled. LEGEND also uses this coordinate system.
norm
if set, x and y positions are specified in usual IDL normalized
coordinates, i.e, the range 0 to 1 spans the entire window
display range.
align
the text alignment point.
ALIGN=0.0 => text is left justified to x,y
ALIGN=0.5 => text is centered at x,y
ALIGN=1.0 => text is right justified to x,y
The use of ALIGN is particularly useful to center or justify a
multiline text string (see example). Also, keep in mind the
length of a string isn't always predictable when written to a
hardcopy device. ALIGN should be used if you want to center or
right justify a string to line up with something.
valign
vertical offset in character units. This keyword has no effect
in interactive mode.
contrast
if set, PUTSTR writes the string twice; the first time the string
will be drawn with very thick lines and in a contrasting color.
The second time it will be drawn at the standard character thickness
(from !p.charthick) and with the color set by the color keyword. You
can control the thickness and the background color by setting
CONTRAST to a two element vector, [thick,color]. This option
should be used to draw annotation within image areas, where the
legibility may otherwise suffer due to lack of contrast or crossing
line clutter. The default blanking thickness is 15 for X and 50 for PS.
the default blanking color is !p.background.
KEYWORD INPUT:
OUTPUT:
none
DESCRIPTION:
Use PUTSTR to interactively position a text label on a plot. The
size and orientation of the text label are adjusted by pressing
the left or middle mouse buttons. Initially the LMB and MMB
control the size of the label. To enable the use of the LMB and
MMB to control the label orientation angle, press the RMB once. Two
consecutive RMB clicks without any intervening LMB or MMB clicks causes
the procedure to quit.
On exit, PUTSTR prints out the command line options which
will reproduce the text in the final position and orientation.
This string may be appended to the original PUTSTR command using
xwindows cut and paste.
For similar text annotation capabiltiy see LEGEND.PRO
EXAMPLE:
;; interactive placement of text strings:
plot,randf(200,2)
t1='Use PUTSTR to interactively position a text label!c'
t2='on a plot. The size and orientation of the text label!c'
t3='are adjusted by pressing the left or middle mouse buttons.'
text=t1+t2+t3
putstr,text
putstr,text,align=.5
putstr,text,align=1
;; use putstr in non-interactive mode
!p.multi=[0,1,2]
window,0,xs=600,ys=900
plot,randf(200,2),ymargin=[10,2]
text='Figure 1. Dew point temperature as a function of!c' + $
' foobar position relative to mordant.'
putstr,text,/subnorm,0.0,-0.2,charsize=2.0,orient=0.0
plot,randf(200,3),ymargin=[10,2]
text='Figure 2. Triple point temperature as a function of!c' + $
' mordant position relative to foobar.'
putstr,text,/subnorm,0.0,-0.2,charsize=2.0,orient=0.0
(See /home/drw/idl/esrg/putstr.pro)
PUTSTR[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE:
putstr
PURPOSE:
use cursor to position and orient text on a plot
USEAGE:
putstr,label,xs,ys,orient=orient,charsize=charsize,color=color,$
subnorm=subnorm,norm=norm,align=align,pschar=pschar
INPUT:
label
text label, type string
xs
x position of string (data coordinates, default)
ys
y position of string (data coordinates, default)
KEYWORD INPUT:
orient
orientation in degrees
charsize
character size parameter. The character size is the value of
CHARSIZE * !p.charsize. (default=1)
subnorm
if set, x and y positions are specified in data window
sub-normalized coordinates, i.e, the range 0 to 1 spans the entire
data coordinate range. Note that this is different then the
usual IDL normalized coordinates. When SUBNORM is set, a
given x,y coordinate causes the text to appear in the same
data window region regardless of how the x and y axes are
scaled. LEGEND also uses this coordinate system.
norm
if set, x and y positions are specified in usual IDL normalized
coordinates, i.e, the range 0 to 1 spans the entire window
display range.
align
the text alignment point.
ALIGN=0.0 => text is left justified to x,y
ALIGN=0.5 => text is centered at x,y
ALIGN=1.0 => text is right justified to x,y
The use of ALIGN is particularly useful to center or justify a
multiline text string (see example). Also, keep in mind the
length of a string isn't always predictable when written to a
hardcopy device. ALIGN should be used if you want to center or
right justify a string to line up with something.
contrast
if set, PUTSTR writes the string twice; the first time the string
will be drawn with very thick lines and in a contrasting color.
The second time it will be drawn at the standard line thickness
(from !p.thick) and with the color set by the color keyword. You
can control the thickness and the background color by setting
CONTRAST to a two element vector, [thick,color]. This option
should be used to draw annotation within image areas, where the
legibility may otherwise suffer due to lack of contrast.
KEYWORD INPUT:
OUTPUT:
none
DESCRIPTION:
Use PUTSTR to interactively position a text label on a plot. The
size and orientation of the text label are adjusted by pressing
the left or middle mouse buttons. Initially the LMB and MMB
control the size of the label. To enable the use of the LMB and
MMB to control the label orientation angle, press the RMB and
select the ANGLE menu item.
To quit the proceedure press RMB and select the "QUIT" menu item.
On exit, the PUTSTR command line options which will reproduce the
text in the final position and orientation is printed to the
terminal. This string may be appended to the original PUTSTR
comand using xwindows cut and paste.
For similar text annotation capabiltiy see LEGEND.PRO
EXAMPLE:
;; interactive placement of text strings:
plot,randf(200,2)
t1='Use PUTSTR to interactively position a text label!c'
t2='on a plot. The size and orientation of the text label!c'
t3='are adjusted by pressing the left or middle mouse buttons.'
text=t1+t2+t3
putstr,text
putstr,text,align=.5
putstr,text,align=1
;; use putstr in non-interactive mode
!p.multi=[0,1,2]
window,0,xs=600,ys=900
plot,randf(200,2),ymargin=[10,2]
text='Figure 1. Dew point temperature as a function of!c' + $
' foobar position relative to mordant.'
putstr,text,/subnorm,0.0,-0.2,charsize=2.0,orient=0.0
plot,randf(200,3),ymargin=[10,2]
text='Figure 2. Triple point temperature as a function of!c' + $
' mordant position relative to foobar.'
putstr,text,/subnorm,0.0,-0.2,charsize=2.0,orient=0.0
(See /home/drw/idl/old.esrg/putstr.pro)
PWD[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine pwd
purpose print the current working directory
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
(See /home/drw/idl/esrg/pwd.pro)
PWD[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine pwd
purpose print the current working directory
author: Paul Ricchiazzi jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/pwd.pro)
PWD[3]
[Previous Routine]
[Next Routine]
[List of Routines]
*Name: PWD (print working directory)
*Purpose: Display the current working directory to sys$output.
*Calling Sequence: pwd
*History
1-may-1993 jkf/acc - version 1
27-jan-1995 JKF/ACC - documented and added to GHRS DAF.
(See /home/drw/idl/icur/pwd.pro)
QPINT1D
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QPINT1D
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:
One dimensional numerical integration of IDL function or expression
MAJOR TOPICS:
Numerical Analysis.
CALLING SEQUENCE:
value = QPINT1D(FUNCT, A, B, [ PRIVATE, /EXPRESSION, FUNCTARGS=,
ERROR=error, NFEV=nfev, STATUS=status, NSUBINTERVALS=nsub,
EPSABS=, EPSREL=, LIMIT=, BREAKPOINTS=, NPOINTS=
/SYMMETRIC, SYM_AXIS= ] )
DESCRIPTION:
QPINT1D adaptively calculates an approximation result to a given
definite integral
result = Integral[ f(x) dx ] over [a,b]
hopefully satisfying a constraint on the accuracy of the solution.
QPINT1D is based on the QUADPACK fortran package originally by
Piessens, de Doncker, Ueberhuber and Kahaner (and implements
equivalents to the QAGSE, QAGPE, QAGIE, and DQKxx fortran routines).
The returned result is intended to satisfy the following claim for
accuracy: ABS(result-value) LE MAX([epsabs, epsrel*ABS(value)]),
where VALUE is the true value of the integral, and EPSABS and
EPSREL are the absolute and relative error tolerances defined
below. An estimate of the error is returned in the ERROR keyword.
Either A or B may be finite or infinite (i.e., an improper
integral).
QPINT1D is "adaptive" in the sense that it locates regions of the
integration interval which contain the highest error, and focusses
its efforts on those regions. The algorithm locates these regions
by successively bisecting the starting interval. Each subinterval
is assigned an error estimate, and the region with the largest
error estimate is subdivided further, until each subinterval
carries approximately the same amount of error. Convergence of the
procedure may be accelerated by the Epsilon algorithm due to Wynn.
The estimate of the integral and the estimate of the error in each
subinterval are computed using Gauss Kronrod quadrature.
Integrators based on the 15-, 21-, 31-, 41-, 51- and 61-point
Gauss-Kronrod rule are available, and selected using the NPOINTS
keyword. Generally, the more points the greater the precision,
especially for rapidly varying functions. However the default
value of 21 is often sufficient, especially because of the adaptive
nature of QPINT1D.
In the following sections the requirements for the form of the
integrand are established. Also, a description of how QPINT1D
handles singularities and discontinuities is presented.
INTEGRAND is a FUNCTION
The integrand can be specified in two forms, either as a standard
IDL function, or as an IDL expression. If integrating a function,
then the FUNCT should be a string naming the function. The
function must be declared as following:
FUNCTION MYFUNCT, X, P, KEYWORDS=...
RETURN, (compute function of X and P)
END
The function must accept at least one, but optionally two,
parameters. The first, 'X', is a vector of abcissae where the
function is to be computed. The function must return the same
number of function values as abcissae passed. The second
positional parameter, 'P', is a purely optional PRIVATE parameter
as described below. MYFUNCT may accept more positional parameters,
but QPINT1D will not use them. The difference between X and P is
that X is the variable of integration, while P contains any other
information expected to remain essentially constant over the
integration.
INTEGRAND is an EXPRESSION
The integrand can also be specfied as an IDL expression and setting
the EXPRESSION keyword. Any expression that can accept a vector of
abcissae named 'X' and produce a corresponding vector of output is
a valid expression. Here is an example:
RESULT = QPINT1D('X^2 * EXP(-X)', /EXPRESSION, 0D, 10D)
It is important to note that the variable of integration must
always be named 'X', and the expression must be vectorizable. The
expression may also use the PRIVATE data, and as above, it would be
referred to according to the variable 'P'. For example, if the
exponential decay constant is parameterized by PRIVATE(0), then the
expression would be:
RESULT = QPINT1D('X^2 * EXP(-X/P(0))', /EXPRESSION, 0D, 10D, PRIVATE)
The user is solely responsible for defining and using the PRIVATE
data. QPINT1D does not access or modify PRIVATE / P; it only
passes it on to the user routine for convenience.
IMPROPER INTEGRALS and DISCONTINUITIES
QPINT1D computes improper integrals, as well as integrands with
discontinuities or singularities.
Improper integrals are integrals where one or both of the limits of
integration are "infinity." (Formally, these integrals are defined
by taking the limit as the integration limit tends to infinity).
QPINT1D handles a small class of such integrals, generally for
integrands that are convergent and monotonic (i.e.,
non-oscillatory, and falling off as 1/ABS(X)^2 or steeper). Such
integrals are handled by a transformation of the original interval
into the interval [0,1].
Integrals from negative infinity to positive infinity are done in
two subintervals. By default the interval is split at X EQ 0,
however this can be controlled by using the SYM_AXIS keyword.
Users should note that if the first subinterval fails the second is
not attempted, and thus the return value VALUE should not be
trusted in those cases.
Infinite integration limits are specified by using the standard
values !VALUES.F_INFINITY or !VALUES.D_INFINITY. No other special
invocation syntax is required.
The integration routine is able to handle integrands which have
integrable singularities at the endpoints. For example, the
integral:
RESULT = QPINT1D('2*sqrt((1-x)/(1+x))/(1-x^2)', 0.0d, 1d, /expr)
has a singularity at a value of X EQ 1. Still, the singularity is
integrable, and the value returned is a correct value of 2.
If known singularities are present within the interval of
integration, then users should pass the BREAKPOINTS keyword to list
the locations of these points. QPINT1D will then integrate each
subinterval separately, while still maintaining an overall error
budget.
If known discontinuities exist in the integrand, then the user may
additionally list those points using the BREAKPOINTS keyword.
It should be noted that the algorithm used is different, depending
on whether the BREAKPOINTS keyword has been specified or not (this
is the difference between the QAGSE vs. QAGPE routines in the
original FORTRAN). The algorithm *without* BREAKPOINTS is
generally thought to be more precise than *with*. Thus, it may be
worth splitting the original integration interval manually and
invoking QPINT1D without BREAKPOINTS.
INPUTS:
FUNCT - by default, a scalar string containing the name of an IDL
function to be integrated. See above for the formal
definition of MYFUNCT. (No default).
If the EXPRESSION keyword is set, then FUNCT is a scalar
string containing an IDL expression to be evaluated, as
described above.
A, B - a scalar number indicating the lower and upper limits of the
interval of integration (i.e., [A, B] is the interval of
integration).
PRIVATE - any optional variable to be passed on to the function to
be integrated. For functions, PRIVATE is passed as the
second positional parameter; for expressions, PRIVATE can
be referenced by the variable 'P'. QPINT1D does not
examine or alter PRIVATE.
RETURNS:
The value of the integral. If either A or B are double precision,
then the integral is computed in double precision; otherwise the
result is returned in single precision floating point.
KEYWORD PARAMETERS:
BREAKPOINTS - an array of numbers specifying points within the
integration interval where the integrand is
discontinuous or singular. Out of bounds points are
ignored.
Default: undefined, i.e., no such points
EPSABS - a scalar number, the absolute error tolerance requested
in the integral computation. If less than or equal to
zero, then the value is ignored.
Default: 0
EPSREL - a scalar number, the relative (i.e., fractional) error
tolerance in the integral computation. If less than or
equal to zero, then the value is ignored.
Default: 1e-4 for float, 1d-6 for double
EXPRESSION - if set, then FUNCT is an IDL expression. Otherwise,
FUNCT is an IDL function.
ERROR - upon return, this keyword contains an estimate of the
error in the computation.
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.
LIMIT - a scalar, the maximum number of subintervals to create
before terminating execution. Upon return, a STATUS value
of 1 indicates such an overflow occurred.
Default: 100
NFEV - upon return, this keyword contains the number of function
calls executed (i.e., the number of abcissae).
NPOINTS - a scalar, the number of Gauss Kronrod points to use in
computing the integral over a subinterval. A larger
number of points can in principle increase the precision
of the integral, but also makes the computation take
longer. Possible values are 15, 21, 31, 41, 51, and 61.
NPOINTS is rounded up to the next nearest available set,
with a maximum of 61.
Default: 21
NSUBINTERVALS - upon return, this keyword contains the number of
subintervals the integration interval was divided
into.
STATUS - upon return, the status of the integration operation is
returned in this keyword as an integer value. A value of
zero indicates success; otherwise an abnormal condition
has occurred and the returned value should be considered
erroneous or less reliable according to STATUS:
any negative number - outright failure (reserved for
future use).
-1 - the input parameters are invalid, because
epsabs LE 0 and epsrel LT max([50*EPS,0.5d-28]),
where EPS is the machine precision, or if LIMIT
is smaller than the number of BREAKPOINTS.
0 - success.
1 - maximum number of subdivisions allowed has been
achieved. One can allow more subdivisions by
increasing the value of limit (and taking the
according dimension adjustments into
account). However, if this yields no
improvement it is advised to analyze the
integrand in order to determine the integration
difficulties. If the position of a local
difficulty can be determined (i.e. singularity,
discontinuity within the interval), it should
be supplied to the routine as an element of the
vector BREAKPOINTS.
2 - The occurrence of roundoff error is detected,
which prevents the requested tolerance from
being achieved. The error may be
under-estimated.
3 - Extremely "bad" integrand behaviour occurs at
some points of the integration interval.
4 - The algorithm does not converge. Roundoff
error is detected in the extrapolation table.
It is presumed that the requested tolerance
cannot be achieved, and that the returned
result is the best which can be obtained.
5 - The integral is probably divergent, or only
slowly convergent. It must be noted that
divergence can occur with any other value of
ier GT 0.
SYM_AXIS - a scalar number, the bisection point of the real line
for improper integrals from negative infinity to
positive infinity. Otherwise ignored.
Default: 0.
EXAMPLES:
Shows how function and expression can be used for exponential
integrand:
IDL> print, qpint1d('EXP(X)', 0D, 10D, /expr)
22025.466
IDL> print, qpint1d('EXP', 0D, 10D)
22025.466
Normal definite integral, and then parameterized using a PRIVATE
value of 2.
IDL> print, qpint1d('X^2*EXP(-X)', 0D, 10D, /expr)
1.9944612
IDL> print, qpint1d('X^2*EXP(-X/P(0))', 0D, 10D, 2D, /expr)
14.005568
Improper integrals of the gaussian function
IDL> inf = !values.d_infinity
IDL> print, qpint1d('EXP(-X^2)', 0D, +inf, 2D, /expr)
0.88622693
IDL> print, qpint1d('EXP(-X^2)', -inf, +inf, 2D, /expr), sqrt(!dpi)
1.7724539 1.7724539
The second integral shows the comparison to the analytic value of
SQRT(!DPI).
COMMON BLOCKS:
COMMON QPINT1D_MACHAR
COMMON QPINT1D_PROFILE_COMMON
COMMON QPINT1D_QKEVAL_COMMON
These common blocks are used internally only and should not be
accessed or modified.
REFERENCES:
R. Piessens, E. deDoncker-Kapenga, C. Uberhuber, D. Kahaner
Quadpack: a Subroutine Package for Automatic Integration
Springer Verlag, 1983. Series in Computational Mathematics v.1
515.43/Q1S 100394Z
Netlib repository: http://www.netlib.org/quadpack/
SLATEC Common Mathematical Library, Version 4.1, July 1993
a comprehensive software library containing over
1400 general purpose mathematical and statistical routines
written in Fortran 77. (http://www.netlib.org/slatec/)
MODIFICATION HISTORY:
Written, Feb-Jun, 2001, CM
Documented, 04 Jun, 2001, CM
Add usage message, error checking, 15 Mar 2002, CM
Correct usage message, 28 Apr 2002, CM
$Id: qpint1d.pro,v 1.13 2002/05/02 07:00:43 craigm Exp $
(See /home/drw/idl/aux/markwardt/qpint1d.pro)
QRFAC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QRFAC
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Perform QR decomposition of a rectangular matrix
MAJOR TOPICS:
Linear Systems
CALLING SEQUENCE:
QRFAC, A, R, [ IPVT, /PIVOT ]
DESCRIPTION:
Given an MxN matrix A (M>N), the procedure QRFAC computes the QR
decomposition (factorization) of A. This factorization is useful
in least squares applications solving the equation, A ## x = B.
Together with the procedure QRSOLV, this equation can be solved in
a least squares sense.
The QR factorization produces two matrices, Q and R, such that
A = Q ## R
where Q is orthogonal such that TRANSPOSE(Q)##Q equals the identity
matrix, and R is upper triangular. This procedure does not compute
Q directly, but returns the more-compact Householder reflectors,
which QRSOLV applies in constructing the solution.
Pivoting can be performed by setting the PIVOT keyword. Rows with
the largest L2-norm are pivoted into the top positions of the
matrix. The permutation matrix is returned in the IPVT parameter.
PARAMETERS:
A - upon input, an MxN matrix to be factored.
Upon output, the upper triangular MxN matrix of Householder
reflectors used in reconstructing Q. Obviously the original
matrix A is destroyed upon output.
Note that the dimensions of A in this routine are the
*TRANSPOSE* of the conventional appearance in the least
squares matrix equation.
R - upon ouptut, an upper triangular NxN matrix
IPVT - upon output, the permutation indices used in partial
pivoting. If pivoting is used, this array should be passed
to the PIVOTS keyword of QRSOLV. If the PIVOT keyword is
not set, then IPVT returns an unpermuted array of indices.
KEYWORD PARAMETERS:
PIVOT - if set, then partial pivoting is performed, to bring the
rows with the largest norm to the top of the matrix.
QMATRIX - upon return, the fully explicit "Q" matrix is returned.
This square matrix can be used to perform explicit
matrix multiplication (although not super efficiently).
The values returned modified in A are the Householder
vectors, which are then used to compute QMAT.
EXAMPLE:
Decompose the 3x2 matrix [[9.,2.,6.],[4.,8.,7.]]
aa = [[9.,2.,6.],[4.,8.,7.]]
qrfac, aa, r, ipvt
IDL> print, aa
1.81818 0.181818 0.545455
XXXXXXXXX 1.90160 0.432573
(position marked with Xs is undefined)
Construct the matrix Q by expanding the Householder reflectors
returned in AA. ( M = 3, N = 2 ) This same procedure is
accomplished by using the QMATRIX keyword.
ident = fltarr(m,m) ;; Construct an identity matrix
ident(lindgen(m),lindgen(m)) = 1
q = ident
for i = 0, n-1 do begin
v = aa(*,i) & if i GT 0 then v(0:i-1) = 0 ;; extract reflector
q = q ## (ident - 2*(v # v)/total(v * v)) ;; generate matrix
endfor
Verify that Q ## R returns to the original AA
print, q(0:1,*) ## r
9.00000 4.00000
2.00000 8.00000
6.00000 7.00000
(transposed)
See example in QRSOLV to solve a least squares problem.
REFERENCES:
More', Jorge J., "The Levenberg-Marquardt Algorithm:
Implementation and Theory," in *Numerical Analysis*, ed. Watson,
G. A., Lecture Notes in Mathematics 630, Springer-Verlag, 1977.
MODIFICATION HISTORY:
Written (taken from MPFIT), CM, Feb 2002
Added usage message, error checking, CM 15 Mar 2002
Corrected error in EXAMPLE, CM, 10 May 2002
Now returns Q matrix explicitly if requested, CM, 14 Jul 2002
Documented QMATRIX keyword, CM, 22 Jul 2002
$Id: qrfac.pro,v 1.4 2002/07/23 02:09:14 craigm Exp $
(See /home/drw/idl/aux/markwardt/qrfac.pro)
QRSOLV
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QRSOLV
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Solve a linear equation after performing QR factorization
MAJOR TOPICS:
Linear Systems
CALLING SEQUENCE:
X = QRSOLV(A, R, B, PIVOTS=IPVT)
DESCRIPTION:
The procedure QRSOLV completes the solution of a linear equation,
A ## x = B
after the MxN matrix has been factorized by QR decomposition.
After being factorized once using QRFAC, the matrices can be used
for multiple righthand sides (i.e., different B's).
The solution technique is to first compute the factorization using
QRFAC, which yields the orthogonal matrix Q and the upper
triangular matrix R. [ Actually, Q is represented by its
Householder reflectors. ] Then the solution vector, X, is computed
using QRSOLV.
If pivoting was performed in the factorization, the permutation
vector IPVT returned by QRFAC must also be passed to QRSOLV.
PARAMETERS:
A - upon input, the factorized matrix A, returned by QRFAC.
R - upon input, the upper diagonal matrix R, returned by QRFAC.
B - upon input, the righthand vector B, which fits into the
equation, A ## x = B
X - upon ouptut, the solution vector X, to the above linear
equation. For an overdetermined system, X is the least
squares solution which minimizes TOTAL( (A ## X - B)^2 ).
KEYWORD PARAMETERS:
PIVOTS - upon input, the permutation matrix IPVT returned by
QRFAC, if pivoting is to be performed.
EXAMPLE:
Solve the equation A ## X = B, in the least squares sense, where:
A = [[1.0,1.0,1.0,1.0,1.0,1.0],$
[0.6,0.8,0.5,0.8,0.7,0.9],$
[0.2,0.3,0.1,0.4,0.3,0.4]]
and B = [0.57E,0.69,0.5,0.7,0.6,0.8]
qrfac, a, r, ipvt, /PIVOT
x = qrsolv(a, r, b, PIVOTS=ipvt)
print, x
0.0834092 0.852273 -0.179545
REFERENCES:
More', Jorge J., "The Levenberg-Marquardt Algorithm:
Implementation and Theory," in *Numerical Analysis*, ed. Watson,
G. A., Lecture Notes in Mathematics 630, Springer-Verlag, 1977.
MODIFICATION HISTORY:
Written (taken from MPFIT), CM, Feb 2002
Usage message, error checking, CM, 15 Mar 2002
Error checking is fixed, CM, 10 May 2002
$Id: qrsolv.pro,v 1.3 2002/05/10 18:41:31 craigm Exp $
(See /home/drw/idl/aux/markwardt/qrsolv.pro)
QSELIGHT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
qselight
(quiet sun euv lightcurve)
PURPOSE:
A rountine to make an average[-per-pixel] lightcurve for 1024x1024 EUV
images.
CALLING SEQUENCE:
qselight, data, curve, background
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
(See /home/drw/idl/bin/qselight.pro)
QSELIGHT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
qselight
(quiet sun euv lightcurve)
PURPOSE:
A rountine to make an average[-per-pixel] lightcurve for 1024x1024 EUV
images.
CALLING SEQUENCE:
qselight, data, curve, background
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
(See /home/drw/idl/bin/qselight2.pro)
QSELIGHT_
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
qselight_
(quiet sun euv lightcurve)
PURPOSE:
A rountine to make an average[-per-pixel] lightcurve for 1024x1024 EUV
images.
CALLING SEQUENCE:
qselight, data, curve, background
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
(See /home/drw/idl/bin/qselight_.pro)
QSELIGHT_2
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
qselight_2
(quiet sun euv lightcurve)
PURPOSE:
A rountine to make an average[-per-pixel] lightcurve for 1024x1024 EUV
images.
CALLING SEQUENCE:
qselight, data, curve, background
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
(See /home/drw/idl/bin/qselight_2.pro)
QTANG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTANG
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:
Find rotation angle(s) of unit quaternion
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
PHI = QTANG(Q)
DESCRIPTION:
The function QTANG accepts a unit quaternion Q and returns the
rotation angle PHI of the quaternion.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
Q - array of one or more unit quaternions. For a single
quaternion, Q should be a 4-vector. For N quaternions, Q
should be a 4xN array.
RETURNS:
For a single quaternion, returns the scalar quaternion rotation
angle in radians. For N quaternions, returns an N-vector of
rotation angles.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
IDL> print, qtang(qtcompose([0d,1,0], !dpi/4))
0.78539816
Prints the angle part of the quaternion composed of a rotation of
!dpi/4 radians around the axis [0,1,0]
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtang.pro,v 1.5 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtang.pro)
QTAXIS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTAXIS
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:
Find rotation axis of unit quaternion
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
VAXIS = QTAXIS(Q)
DESCRIPTION:
The function QTAXIS accepts a unit quaternion Q and returns the
rotation axis VAXIS as a unit vector.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
Q - array of one or more unit quaternions. For a single
quaternion, Q should be a 4-vector. For N quaternions, Q
should be a 4xN array.
RETURNS:
For a single quaternion, returns the rotation axis unit vector in a
3-vector. For N quaternions, returns a 3xN-vector of rotation
axis unit vectors.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
IDL> print, qaxis(qtcompose([0d,1,0], !dpi/4))
0.0000000 1.0000000 0.0000000
Prints the axis part of the quaternion composed of a rotation of
!dpi/4 radians around the axis [0,1,0]
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Correct error in normalization, 26 Jan 2002, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtaxis.pro,v 1.6 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtaxis.pro)
QTCOMPOSE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTCOMPOSE
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:
Convert a rotation angle and axis into quaternion
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
Q = QTCOMPOSE(VAXIS, PHI)
DESCRIPTION:
The function QTCOMPOSE accepts a unit vector rotation axis VAXIS
and a rotation angle PHI, and returns the corresponding quaternion.
The user must take care to pass the same number of axes as rotation
angles.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
VAXIS - array of one or more unit vectors specifying the rotation
axes. For a single rotation, VAXIS should be a 3-vector.
For N vectors, VAXIS should be a 3xN array.
PHI - one or more rotation angles, in radians. For a single
rotation, PHI should be a scalar. For N rotations, PHI
should be an N-vector.
RETURNS:
For a single rotation, returns a quaternion as a 4-vector. For N
rotations, returns a 4xN vector of quaternions.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
IDL> print, qtcompose([0d,1,0], !dpi/4)
0.0000000 0.38268343 0.0000000 0.92387953
Prints the quaternion composed of a rotation of !dpi/4 radians
around the axis [0,1,0]
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Allow output to be DOUBLE, 27 Jan 2002, CM
Allow vector vs scalar arguments, 28 Jan 2002, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtcompose.pro,v 1.10 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtcompose.pro)
QTERP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTERP
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:
Smoothly interpolate from a grid of quaternions (spline or slerp)
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
QNEW = QTERP(TGRID, QGRID, TNEW, [/SLERP], QDIFF=, [/RESET])
DESCRIPTION:
The function QTERP is used to interplate from a set of known unit
quaternions specified on a grid of independent values, to a new set
of independent values. For example, given a set of quaternions at
specified key times, QTERP can interpolate at any points between
those times. This has applications for computer animation and
spacecraft attitude control.
The "grid" of quaternions can be regularly or irregularly sampled.
The new values can also be regularly or irregularly sampled.
The simplest case comes when one wants to interpolate between two
quaternions Q1 and Q2. In that case the user should specify the
gridded quaterion as QGRID = [[Q1], [Q2]], with grid points at
TGRID = [0d, 1d]. Then the user can sample any intermediate
orientation by specifying TNEW anywhere between 0 and 1.
The user has the option of performing pure spline interpolation of
the quaternion components (the default technique). The resulting
interpolants are normalized to be unit quaternions. This option is
useful for fast interpolation of quaternions, but suffers if the
grid is not well sampled enough. Spline interpolation will not
strictly find the shortest path between two orientations.
The second option is to use Spherical Linear IntERPolation, or
SLERPing, to interpolate between quaternions (by specifying the
SLERP keyword). This technique is guaranteed to find the shortest
path between two orientations, but is somewhat slower than spline
interpolation. This approach involves computing a finite
difference of the data. To avoid repeated computation of the
difference on every call, users can pass a named variable in the
QDIFF keyword. This value can be reset with the RESET keyword.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
Users must have the VALUE_LOCATE() function, available either in
IDL 5.3 or later, or from the Markwardt web page.
INPUTS:
TGRID - a vector of N independent variable values. In the
simplest case, this can be [0, 1, ...] up to the number of
quaternions in the grid. The grid sampling does not have
to be uniform.
QGRID - an 4xN array of unit quaternions specified on the grid.
TNEW - a vector of M desired independent variable values which
sample the grid specified by TGRID. The desired values do
not have to be uniformly sampled.
RETURNS:
A 4xM array of unit quaternions, where is M is the number of
desired samples.
KEYWORD PARAMETERS:
SLERP - if set, then spherical linear interpolation is performed.
The default is to perform spline interpolation on the
quaternion coefficients.
QDIFF - upon return, QDIFF is filled with finite difference values
which can be used to speed computations in subsequent
calls. Users should be aware that QDIFF may be
inadvertently reused from one call to the next. When the
difference data should no longer be reused, the named
variable passed to the QDIFF keyword should be set to a
scalar, or the /RESET keyword should be used.
RESET - if set, then the QDIFF finite difference will be forced to
be recalculated, even if there is already data present and
passed to the QDIFF keyword.
EXAMPLE:
This example starts with two quaternions representing rotations of
0 degrees and 45 degrees, and forms 1001 quaternions which are
smooth interpolations between 0 and 45 degrees.
;; Create a grid of two quaternions at times 0 and 1
Q0 = qtcompose([1,0,0], 0D) & T0 = 0D
Q1 = qtcompose([1,0,0], !dpi/4) & T1 = 1D
;; Put the grid elements into an array
TGRID = [T0, T1]
QGRID = [[Q0], [Q1]]
;; Make an array of 1001 values smoothly varying from 0 to 1
TNEW = dindgen(1001)/1000d
;; Perform spherical linear interpolation
QNEW = QTERP(TGRID, QGRID, TNEW, /SLERP)
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Usage message; check for 0- and 1-length quaternions; handle case
when quaternions are GE 180 degrees apart; handle case of
interpolating beyond end of known grid, 15 Mar 2002, CM
$Id: qterp.pro,v 1.6 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qterp.pro)
QTEULER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTEULER
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:
Compose a series of euler-type rotations into a single quaternion
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
Q = QTEULER(AXES, ANG0, ANG1, ... )
DESCRIPTION:
The function QTEULER composes a series of Euler-type rotations into
a single set of quaternion representations.
The user specifies a set of axes, and the angles to rotation about
those axes, and QTEULER constructs the corresponding quaternion.
There must be a one-to-one correspondence between the elements of
AXES and the number of rotations. AXES specifies the rotation axes
as an string, which must be one of 'X', 'Y', or 'Z'. Other axes
are invalid. For example, the following call:
QTEULER(['X','Z'], THETA, PHI)
will rotate first about the *Z* axis by the angle PHI, and then
around the *resulting X* axis by angle THETA.
Several things are worth noting here. First, rotations are applied
first from the right, not the left. This conforms to the usual
matrix notation for applying rotations to a vector on the right
hand side. For example, in matrix notation,
XNEW = A3 A2 A1 XOLD
applies first A1, then A2 and finally A3 to the XOLD vector,
resulting in the new vector XNEW. The same semantics apply here.
A second thing to bear in mind is that the axes themselves change
during the rotations. Thus, the coordinates specified in AXES
should be considered attached to the "body" and not the inertial
frame.
INPUTS:
AXES - a string array, specifies the rotation axes. Rotations are
applied last element first. Each element of AXES must be
one of 'X', 'Y' or 'Z'.
ANG0, ..., ANGi - the successive rotation angles. Angle ANGi
corresponds to axis AXES(i).
If ANGi is a scalar, then it will be promoted to a vector
the same size as the other rotation angles being performed.
Otherwise, if the angles ANGi are vectors, then they must
all be of the same size.
RETURNS:
The resulting quaternion (or, if ANGi are vectors, array of
quaternions), which represent the requested rotations.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
;; Precession Nutation
qtot = qteuler(['z','y','z', 'x','z','x' ], $
-zeta, +theta, -z, +eps0, -dpsi, -eps)
Applies a series of rotations to correct for earth nutation and
precession. The order of rotations on a vector would be
X-Z-X-Z-Y-Z (i.e., the reverse order printed).
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, 27 Jan 2002, CM
More error checking, 03 Mar 2002, CM
$Id: qteuler.pro,v 1.4 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qteuler.pro)
QTEXP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTEXP
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:
Compute "exponentiation" of a non-unit quaternion
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
Q = QTEXP(QLOG)
DESCRIPTION:
The function QTEXP computes the "exponentiation" of a quaternion.
The exponential is only defined for a non-unit quaternion with a
*zero* rotation angle. Specifically, the expression
QTEXP([VAXIS * PHI/2, 0])
becomes
[VAXIS*SIN(PHI/2), COS(PHI/2)]
where VAXIS is the unit vector rotation axis and PHI is the
rotation angle. Note that since VAXIS is a unit vector, the
product VAXIS*PHI can have an arbitrary direction and magnitude.
Typically the input to QTEXP is found by taking the logarithm of a
unit quaternion using QTLOG, and the identity QTEXP(QTLOG(Q)) is
the same as Q.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
QLOG - a non-unit quaternion of the form [VX, VY, VZ, 0]; or,
N quaternions of the same form, as a 4xN array.
RETURNS:
The exponentiated unit quaternion(s). For a single input
quaternion, returns a 4-vector; for N input quaternions, returns a
4xN array.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
IDL> print, qtlog(qtcompose([0d,1,0], !dpi/4))
0.0000000 0.39269908 0.0000000 0.0000000
Prints the logarithm of the quaternion composed of a rotation of
!dpi/4 radians around the axis [0,1,0]
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Documentation corrected, 27 Jan 2002, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtexp.pro,v 1.7 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtexp.pro)
QTFIND
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTFIND
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:
Find quaternion(s) from direction cosine matrix
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
Q = QTFIND(MATRIX)
DESCRIPTION:
The function QTFIND determines one or more unit quaternions from
direction cosine matrices.
This routine is optimized to avoid singularities which occur when
any one of the quaternion components is nearly zero. Up to four
different transformations are attempted to maximize the precision
of all four quaternion components.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
MATRIX - array of one or more direction cosine matrices. For a
single matrix, MATRIX should be a 3x3 array. For N
matrices, MATRIX should be a 3x3xN array. The arrays are
assumed to be valid rotation matrices.
RETURNS:
The resulting unit quaternions. For a single matrix, returns a
single quaternion as a 4-vector. For N matrices, returns N
quaternions as a 4xN array.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
;; Form a rotation matrix about the Z axis by 32 degrees
th1 = 32d*!dpi/180
mat1 = [[cos(th1),-sin(th1),0],[sin(th1),cos(th1),0],[0,0,1]]
;; Form a rotation matrix about the X axis by 116 degrees
th2 = 116d*!dpi/180
mat2 = [[1,0,0],[0,cos(th2),-sin(th2)],[0,sin(th2),cos(th2)]]
;; Find the quaternion that represents MAT1, MAT2 and the
composition of the two, MAT2 ## MAT1.
print, qtfind(mat1), qtfind(mat2), qtfind(mat2 ## mat1)
0.0000000 0.0000000 0.27563736 0.96126170
0.84804810 0.0000000 0.0000000 0.52991926
0.81519615 -0.23375373 0.14606554 0.50939109
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Re-added check to enforce q(3) GE 0, 15 Mar 2002, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtfind.pro,v 1.7 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtfind.pro)
QTINV
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTINV
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:
Compute inverse of QUATERNION
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
QINV = QTINV(Q)
DESCRIPTION:
The function QTINV computes the inverse of the quaternion Q. The
inverse of a quaternion is equivalent to a rotation about the same
axis but the opposite direction.
The inverse is also defined mathematically such that
QTMULT( Q, QTINV(Q) )
becomes [0, 0, 0, 1], which is the identity quaternion.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
Q - array of one or more unit quaternions. For a single
quaternion, Q should be a 4-vector. For N quaternions, Q
should be a 4xN array.
RETURNS:
The resulting inverse unit quaternions. For a single input
quaternion, returns a 4-vector. For N input quaternions, returns
N quaternions as a 4xN array.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
IDL> print, qtcompose([0d,1,0], !dpi/4)
0.0000000 0.38268343 0.0000000 0.92387953
IDL> print, qtinv(qtcompose([0d,1,0], !dpi/4))
0.0000000 0.38268343 0.0000000 -0.92387953
Prints the quaternion composed of a rotation of !dpi/4 radians
around the axis [0,1,0], then the inverse of the same quaternion.
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtinv.pro,v 1.6 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtinv.pro)
QTLOG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTLOG
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:
Compute "logarithm" of a unit quaternion
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
QLOG = QTLOG(Q)
DESCRIPTION:
The function QTLOG computes the "logarithm" of a unit quaternion.
The logarithm of a quaternion is defined for any unit quaternion,
such that the expression
QTLOG([VAXIS*SIN(PHI/2), COS(PHI/2)]
becomes
[VAXIS * PHI/2, 0]
where VAXIS is the unit vector rotation axis and PHI is the
rotation angle. Note that the output quaternion is not a *unit*
quaternion. The output of QTLOG is also commonly known as an
*axial vector*, for a rotation axis VAXIS and rotation angle
PHI/2.
Typically the output to QTLOG is eventually exponentiated with the
QTEXP function, and the identity QTEXP(QTLOG(Q)) is the same as Q.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
Q - array of one or more unit quaternions. For a single
quaternion, Q should be a 4-vector. For N quaternions, Q
should be a 4xN array.
RETURNS:
The non-unit quaternion logarithm(s). For a single input
quaternion, returns a 4-vector of the form [VX, VY, VZ, 0]. For N
input quaternions, returns N quaternions of the same form as a 4xN
array.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
IDL> q = qtlog(qtcompose([0d,1,0], !dpi/4))
IDL> print, qtexp(2 * q)
0.0000000 0.70710678 0.0000000 0.70710678
First, computes the logarithm Q of the quaternion composed of a
rotation of !dpi/4 radians around the axis [0,1,0]. Second,
computes the exponentiation of 2*Q. This is the same as raising
the original quaternion to the second power.
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Documentation clarified & corrected, 27 Jan 2002, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtlog.pro,v 1.6 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtlog.pro)
QTMAT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTMAT
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:
Find direction cosine matrix from quaternion(s)
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
MATRIX = QTMAT(Q)
DESCRIPTION:
The function QTMAT computes one or more direction cosine matrices
(i.e., rotation matrices) from unit quaternions.
The usage of the resulting matrix on a 3-vector X is either
MATRIX # X, or MATRIX ## X, depdending on the meaning of the
rotation (i.e., body-fixed or coordinate-fixed, see QTVROT).
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
Q - array of one or more unit quaternions. For a single
quaternion, Q should be a 4-vector. For N quaternions, Q
should be a 4xN array.
RETURNS:
The direction cosine matrices. For a single input quaternion,
retuns a 3x3 array. For N input quaternions, returns a 3x3xN
array.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
print, qtmat(qtcompose([0d,1,0], !dpi/4))
0.70710678 0.0000000 0.70710678
0.0000000 1.0000000 0.0000000
-0.70710678 0.0000000 0.70710678
Form a quaternion composed of a rotation of !dpi/4 radians around
the axis [0,1,0], and then print the corresponding rotation
matrix.
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Documentation clarifications, 28 Jan 2002, CM
Allow multiple quaternions, 28 Jan 2002, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtmat.pro,v 1.6 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtmat.pro)
QTMULT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTMULT
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:
Multiply quaternions
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
QRESULT = QTMULT(Q1, Q2)
DESCRIPTION:
The function QTMULT performs multiplication of quaternions.
Quaternion multiplication is not component-by-component, but
rather represents the composition of two rotations, namely Q2
followed by Q1.
More than one multiplication can be performed at one time if Q1
and Q2 are 4xN arrays. In that case both input arrays must be of
the same dimension.
Note that quaternion multiplication is not commutative.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
Q1 - array of one or more unit quaternions, the first operand in
the multiplication. For a single quaternion, Q1 should be a
4-vector. For N quaternions, Q1 should be a 4xN array.
Q2 - same as Q1, for the second operand.
RETURNS:
The resulting multiplied unit quaternions. For a single inputs,
returns a 4-vector. For N input quaternions, returns N
quaternions as a 4xN array.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
Q1 = qtcompose([0,0,1], 32d*!dpi/180d)
Q2 = qtcompose([1,0,0], 116d*!dpi/180d)
IDL> print, qtmult(q1, q2)
0.81519615 0.23375373 0.14606554 0.50939109
Form a rotation quaternion of 32 degrees around the Z axis, and
116 degrees around the X axis, then multiply the two quaternions.
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Documentation, allow 1xN or Nx1 multiplies, 27 Jan 2002, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtmult.pro,v 1.7 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtmult.pro)
QTPOW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTPOW
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:
Raise quaternion Q to the "power" POW
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
QNEW = QTPOW(Q, POW)
DESCRIPTION:
The function QTPOW raises a quaterion Q to the power P. The
operation
QNEW = QTPOW(Q, POW)
is equivalent to
QNEW = QTEXP( POW * QTLOG(Q))
which is the same as the definition of raising a real number to
any power (however, QTPOW is faster than using QTLOG and QTEXP).
For integer values of POW, this form of exponentiation is also
directly equivalent to the multiplication of that many Q's
together.
Geometrically, raising Q to any power between 0 and 1 realizes a
rotation that smoothly interpolates between the identity
quaternion and Q. Thus, QTPOW is useful for interpolation of
quaternions or SLERPing (spherical linear interpolation).
When raising more than one quaternion to a power at a time, the
number of quaternions and powers must be equal.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
Q - array of one or more unit quaternions. For a single
quaternion, Q should be a 4-vector. For N quaternions, Q
should be a 4xN array.
POW - array of N powers, where N is the number of quaternions.
RETURNS:
The resulting exponentiated unit quaternions. For a single
inputs, returns a 4-vector. For N input quaternions, returns N
quaternions as a 4xN array.
KEYWORD PARAMETERS:
NONE
EXAMPLE:
;; Form a rotation quaternion of 45 degrees about the X axis
Q = qtcompose([1,0,0], !dpi/4)
;; Make an array of 1001 values smoothly varying from 0 to 1
P = dindgen(1001)/1000d
;; Perform spherical linear interpolation
QNEW = QTERP(Q, P)
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtpow.pro,v 1.5 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtpow.pro)
QTVROT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
QTVROT
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:
Apply quaternion rotation to a 3-vector
MAJOR TOPICS:
Geometry
CALLING SEQUENCE:
VNEW = QTVROT(V, Q, [/INVERT])
DESCRIPTION:
The function QTVROT applies a quaternion rotation (or its inverse)
to a 3-vector V to produce a new vector VNEW.
If both V and VNEW are vector components measured in the same
inertial coordinate system, then VNEW returns the components of
the vector V rotated by quaternion Q. I.e., the AXES stay fixed
and the VECTOR rotates. Replace Q by QTINV(Q) in the case of
/INVERT.
If V are components of a vector measured in the "body" coordinate
frame, and Q represents the orientation of the body frame
w.r.t. the inertial frame, then VNEW are the components of the
same vector in the inertial frame. I.e., the VECTOR stays fixed
and the AXES rotate. For /INVERT, the coordinate transformation
is from inertial frame to body frame.
If either Q is a single quaternion, or V is a single 3-vector,
then QTVROT will expand the single to the number of elements of
the other operand. Otherwise, the number of quaternions and
vectors must be equal.
Conventions for storing quaternions vary in the literature and from
library to library. This library uses the convention that the
first three components of each quaternion are the 3-vector axis of
rotation, and the 4th component is the rotation angle. Expressed
in formulae, a single quaternion is given by:
Q(0:2) = [VX, VY, VZ]*SIN(PHI/2)
Q(3) = COS(PHI/2)
where PHI is the rotation angle, and VAXIS = [VX, VY, VZ] is the
rotation eigen axis expressed as a unit vector. This library
accepts quaternions of both signs, but by preference returns
quaternions with a positive 4th component.
INPUTS:
V - array of one or more 3-vectors. For a single vector, V should
be a 3-vector. For N vectors, V should be a 3xN array.
Q - array of one or more unit quaternions. For a single
quaternion, Q should be a 4-vector. For N quaternions, Q
should be a 4xN array.
RETURNS:
The resulting rotated vectors. For single inputs, returns a
3-vector. For N inputs, returns N vectors as a 3xN array.
KEYWORD PARAMETERS:
INVERT - if set, then the antirotation represented by QTINV(Q) is
performed.
EXAMPLE:
Q1 = qtcompose([0,0,1], 32d*!dpi/180d)
Q2 = qtcompose([1,0,0], 116d*!dpi/180d)
Q = qtmult(Q1, Q2)
V = [[1d,0,0],[0,1,0],[0,0,1]]
IDL> print, qtvrot(v, q)
0.84804810 0.52991926 0.0000000
0.23230132 -0.37175982 0.89879405
0.47628828 -0.76222058 -0.43837115
SEE ALSO
QTANG, QTAXIS, QTCOMPOSE, QTERP, QTEXP, QTFIND, QTINV, QTLOG,
QTMAT, QTMULT, QTPOW, QTVROT
MODIFICATION HISTORY:
Written, July 2001, CM
Documented, Dec 2001, CM
Small changes, 28 Jan 2002, CM
Usage message, error checking, 15 Mar 2002, CM
$Id: qtvrot.pro,v 1.7 2002/05/09 23:03:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/qtvrot.pro)
QUEUE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: queue
PURPOSE: display print queues
USEAGE: queue
PROCEDURE: choose print queue from pop up menu
AUTHOR: Paul Ricchiazzi 01 Jun 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/queue.pro)
QUEUE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: queue
PURPOSE: display print queues
USEAGE: queue
PROCEDURE: choose print queue from pop up menu
AUTHOR: Paul Ricchiazzi 01 Jun 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/queue.pro)
QWLIGHT
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
qwlight
(new UV lightcurve)
PURPOSE:
A rountine to make an TOTAL (over all chosen pixels) lightcurve for
1024x1024 EUV images.
CALLING SEQUENCE:
qwlight, data, curve, background, expo
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data, and
later tweaked for different image sizes and passbands
QWLIGHT.PRO, a version based on an *average*
value of all pixels
(See /home/drw/idl/bin/qwlight.pro)
QWLIGHT3
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
qwlight3
(new UV lightcurve)
PURPOSE:
A rountine to make an TOTAL (over all chosen pixels) lightcurve for
1024x1024 EUV images.
CALLING SEQUENCE:
newlight2, data, curve, background, expo
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
NEWLIGHT2.PRO, a version based on a *total*
value summed over all pixels
which are >(quiet-mean+)2*standard-deviation)
(See /home/drw/idl/bin/qwlight3.pro)
RADINT
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: radint
PURPOSE: For a given solid angle compute the average radiance or
or if FLUX is set, compute the normal flux contribution
from that solid angle
USEAGE: result=radint(rad,phi,uzen,philim=philim,zenlim=zenlim,
omega=omega,flux=flux)
INPUT:
rad radiance arrray (phi,zen)
phi azimuth angle array (degrees)
uzen zenith angle array (degrees)
zenlim 2 element array: zenith angle limits (in any order)
philim 2 element array: azimuth angle limits
Keyword Input:
flux if set, flux integral is computed. In this case the
output is power/unit_area
Keyword Output:
omega the solid angle specified by philim and zenlim (steradians)
OUTPUT:
result average radiance within given solid angle
EXAMPLE:
phi=findrng(0,360,dx=10)
uzen=findrng(0,90,dx=10)
rad=phi#uzen
rad(*,*)=1.
print,radint(rad,phi,uzen),radint(rad,phi,uzen,/flux)
rad=(1+.5*sin(phi*!dtor))#(1.+.2*cos(uzen*!dtor))
print,radint(rad,phi,uzen) ; should be = 1.1
AUTHOR: Paul Ricchiazzi 16 Apr 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/radint.pro)
RADTEMP
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: radtemp
PURPOSE: compute radiation temperature from a radiance distribution
USEAGE: radtemp,w,r,microns=microns
INPUT:
w wavelength in microns or wavenumber in cm-1
r radiance in w/m2/um/str or w/m2/cm-1/str
divide irradiance by pi
KEYWORD INPUT:
microns set to one for micron units
OUTPUT:
result radiation temperature in kelvin
EXAMPLE:
AUTHOR: Paul Ricchiazzi 20 Nov 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/radtemp.pro)
RANDATA[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: randata
purpose: generate a random field of data with given power spectrum
and array size
useage: randata,n,slope,nx=nx,ny=ny
inputs:
nx size of output grid in x direction
ny size of output grid in y direction, must be less than n.
Since an FFT is used to create the random data,
RANDATA runs faster if max(NX,NY) is a power of 2
Keyword input:
s power law slope of power spectrum (default=4)
locked phases of fourier components locked to grid centers
Keyword input/output
iseed the seed used to randomize the phases
EXAMPLE:
n=64
xs=sqrt(findgen(n))
ys=sqrt(findgen(n)) ; xss and yss are used
xss=xs # replicate(1,n_elements(ys)) ; to give the random
yss=replicate(1,n_elements(xs)) # ys ; data a nice shape
shade_surf,randata(n,n,s=4)*xss*yss,az=10,ax=40
author: Paul Ricchiazzi 27oct93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/randata.pro)
RANDATA[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: randata
purpose: generate a random field of data with given power spectrum
and array size
useage: randata,n,slope,nx=nx,ny=ny
inputs:
nx size of output grid in x direction
ny size of output grid in y direction, must be less than n.
Since an FFT is used to create the random data,
RANDATA runs faster if max(NX,NY) is a power of 2
Keyword input:
s power law slope of power spectrum (default=4)
locked phases of fourier components locked to grid centers
Keyword input/output
iseed the seed used to randomize the phases
EXAMPLE:
n=64
xs=sqrt(findgen(n))
ys=sqrt(findgen(n)) ; xss and yss are used
xss=xs # replicate(1,n_elements(ys)) ; to give the random
yss=replicate(1,n_elements(xs)) # ys ; data a nice shape
shade_surf,randata(n,n,s=4)*xss*yss,az=10,ax=40
author: Paul Ricchiazzi 27oct93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/randata.pro)
RANDF[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: randf
purpose: generate random time history data with given power spectrum
useage: randf,n,slope
inputs:
slope power law slope of power spectrum (default=4)
n number of elements in time history. Since an fft is used
to compute the random numbers powers of 2 are most efficient.
EXAMPLE:
; simple plot
plot,randf(256,2)
; demonstrate use of frequency domain filtering
f=randf(512,2)
gf=exp(-.005*(findgen(256)-1)^2) & gf=[gf,reverse(gf)]
ff=fft(gf*fft(f,1),-1)
fac=total(abs(f))/total(abs(ff))
plot,f
oplot,ff*fac,color=100
method: a power law is used to set the spectral power as a
function of frequency (i.e., p=1/w^s). After the phase of
the fourier components are randomized, the temporal
realization is generated by taking the inverse FFT.
author: Paul Ricchiazzi 27oct93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/randf.pro)
RANDF[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: randf
purpose: generate random time history data with given power spectrum
useage: randf,n,slope
inputs:
slope power law slope of power spectrum (default=4)
n number of elements in time history. Since an fft is used
to compute the random numbers powers of 2 are most efficient.
EXAMPLE:
plot,randf(256,2)
method: a power law is used to set the spectral power as a
function of frequency (i.e., p=1/w^s). After the phase of
the fourier components are randomized, the temporal
realization is generated by taking the inverse FFT.
author: Paul Ricchiazzi 27oct93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/randf.pro)
RATIOLC2
[Previous Routine]
[Next Routine]
[List of Routines]
ratiolc is a program which calculates a ratio lightcurve
check lab book (27/09/01) for furthur details
Lightcurve value = (bp - bg)/(bp +bg)
remember to check bin size and set it to appropriate level
INPUTS cubein:a cube of images
needs a lot of work on the commenting side of things
OUTPUTS lc :the lightcurve
bg :array of background levels
bp :array of bright point levels
nbg:number of pixels at bg level
nbp:number of pixels at bp level
EXAMPLE ratiolc,net1_cak,lc_net1_cak,bgcak,bpcak,nbgcak,nbpcak
ratiols,net1_0,lc_net1_0
NEW CALLING PROCEDURE
ratiolc,cube,lightcurve,threshold,wander_limit,num_of_pixels_included,background_level
check bin size
AUTHORS R.T.James McAteer, David R. Williams Sept '01
ALTERATIONS: loads and loads, too many to list, at least version 5 or 6 by now.
mainly to incorporate new methods of creation of the lightcurve
final version now uses DRW & JMA 'getstuff' function
(See /home/drw/idl/vtt/post_bbso/ratiolc2.pro)
RATIOLC3
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT CHROMOSPHERIC OSCILLATIONS
NAME: Ratiolc3.pro
PURPOSE: To create a contrast lightcurve of a series of images
USEAGE: ratiolc3, cubein, binsize, $
threshold level, wander_limit, lightcurve, no._pixels_in_NBP,
(,/quiet)
INPUTS cubein - series of images
binsize - binsize for histogram
thr - threshold level in terms of standard deviations
lim - wander limitm for getstuff program
OUTPUTS lc - the lightcurve
nbp - number of pixels contoured above thr level
KEYWORD quiet - shuts the whole thing up
INPUTS
EXAMPLE ratiolc3, cube,200,2.0,15,lc,nbp(,/quiet)
AUTHORS R.T.James McAteer Feb '02 QUB
(See /home/drw/idl/vtt/post_bbso/ratiolc3.pro)
RATIOLC[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ratiolc is a program which calculates a ratio lightcurve
check lab book (27/09/01) for furthur details
Lightcurve value = (bp - bg)/(bp +bg)
remember to check bin size and set it to appropriate level
INPUTS cubein:a cube of images
needs a lot of work on the commenting side of things
OUTPUTS lc :the lightcurve
bg :array of background levels
bp :array of bright point levels
nbg:number of pixels at bg level
nbp:number of pixels at bp level
EXAMPLE ratiolc,net1_cak,lc_net1_cak,bgcak,bpcak,nbgcak,nbpcak
ratiols,net1_0,lc_net1_0
NEW CALLING PROCEDURE
ratiolc,cube,lightcurve,threshold,wander_limit,num_of_pixels_included,background_level
check bin size
AUTHORS R.T.James McAteer, David R. Williams Sept '01
ALTERATIONS: loads and loads, too many to list, at least version 5 or 6 by now.
mainly to incorporate new methods of creation of the lightcurve
final version now uses DRW & JMA 'getstuff' function
(See /home/drw/idl/vtt/post_bbso/ratiolc.pro)
RATIOLC[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ratiolc is a program which calculates a ratio lightcurve
check lab book (27/09/01) for furthur details
Lightcurve value = (bp - bg)/(bp +bg)
remember to check bin size and set it to appropriate level
INPUTS cubein:a cube of images
needs a lot of work on the commenting side of things
OUTPUTS lc :the lightcurve
bg :array of background levels
bp :array of bright point levels
nbg:number of pixels at bg level
nbp:number of pixels at bp level
EXAMPLE ratiolc,net1_cak,lc_net1_cak,bgcak,bpcak,nbgcak,nbpcak
ratiols,net1_0,lc_net1_0
NEW CALLING PROCEDURE
ratiolc,cube,lightcurve,threshold,wander_limit,num_of_pixels_included,background_level
check bin size
AUTHORS R.T.James McAteer, David R. Williams Sept '01
ALTERATIONS: loads and loads, too many to list, at least version 5 or 6 by now.
mainly to incorporate new methods of creation of the lightcurve
final version now uses DRW & JMA 'getstuff' function
(See /home/drw/idl/vtt/post_bbso/ratiolc.old.pro)
RATIOLC[3]
[Previous Routine]
[Next Routine]
[List of Routines]
ratiolc is a program which calculates a ratio lightcurve
check lab book (27/09/01) for furthur details
Lightcurve value = (bp - bg)/(bp +bg)
remember to check bin size and set it to appropriate level
INPUTS cubein:a cube of images
needs a lot of work on the commenting side of things
OUTPUTS lc :the lightcurve
bg :array of background levels
bp :array of bright point levels
nbg:number of pixels at bg level
nbp:number of pixels at bp level
EXAMPLE ratiolc,net1_cak,lc_net1_cak,bgcak,bpcak,nbgcak,nbpcak
ratiols,net1_0,lc_net1_0
NEW CALLING PROCEDURE
ratiolc,cube,lightcurve,threshold,wander_limit,num_of_pixels_included,background_level
check bin size
AUTHORS R.T.James McAteer, David R. Williams Sept '01
ALTERATIONS: loads and loads, too many to list, at least version 5 or 6 by now.
mainly to incorporate new methods of creation of the lightcurve
final version now uses DRW & JMA 'getstuff' function
(See /home/drw/idl/jma/ratiolc.pro)
RAYLEIGH
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: rayleigh
PURPOSE: compute rayleigh optical depth at specified wavelengths
USEAGE: result=rayleigh(wl,ps=ps,idatm=idatm,sigma=sigma)
INPUT:
wl wavelength in microns
KEYWORD INPUT:
ps sea level pressure in mb
idatm index of standard atmosphere
1=tropical
2=midlat summer
3=midlat winter
4=sub arctic summer
5=sub arctic winter
6=us62
KEYWORD OUTPUT:
sigma extinction coeficient in km-1
OUTPUT: rayleigh optical depth
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
wl=[.414,.499,.609,.665,.860,.938]
print,rayleigh(wl,idatm=4)
; 0.311728 0.144443 0.0640821 0.0448406 0.0158600 0.0111786
AUTHOR: Paul Ricchiazzi 13 Apr 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/rayleigh.pro)
RDFITS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: RDFITS
(See /home/drw/idl/rdfits.pro)
RDI_ALIGN
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE: create a set of 'offsetss'. This gives the alignment offset
of each image to the middle image.
(See /home/drw/idl/rdi_align.pro)
RDI_CAL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
RDI_CAL
PURPOSE:
To remove dust (where necessary) & pedestal shape from RDI data and
align the images to the central image of each cube.
SYNTAX:
rdi_cal,st,en,data,sp=sp,commonpath,dateobs,dedust=dedust,$
gendust=gendust,flatim=flatim,genoffsets=genoffsets,shutup=shutup,$
outindex=outindex,notrim=notrim,offarray=offarray,gdelta=gdelta,$
nodestretch=nodestretch,zerospike=zerospike,nocorr=nocorr
INPUTS:
DATA - cube to read data into
ST - number of first file to be read in
EN - number of last file to be read in
SP - optional integer step between frames to be read in
COMMONPATH - e.g. commonpath =
'/scratch/jma2/CamBextra/CamB20020904T184237/SECIS\CamB20020904T184237a'
DEDUST - (optional) set to specify that the image should have dust removed
through the median method. Should only be applied to CamB images
GENDUST - (optional) calculate the mask of dust-affected pixels on the
fly from the which have been read in. If this option is desired,
make sure that DEDUST is set
FLATIM - the user-supplied median-normalised array containing the
flat-field/ vignetting shape (DEDUST takes care of the
pixel-to-pixel variation). Otherwise, the default calibration flat
is used.
GENOFFSETS - generate alignment offsets with respect to the middle frame
of the current data cube. If this switch isn`t set, then the default
calibration data generated by JMA are used.
SHUTUP - set this switch to suppress most terminal output
NOTRIM - set this to avoid trimming the data to get rid of the first
NODESTRETCH - set this to avoid destretching a set of N images with
respect to the (N/2)th image.
ZEROSPIKE - a facility for zero-ing spikes in the vertical axis of the
spatial FFT, as -- in the CamB images, there was s spike at k_y =
Nyquist frequency, as well as at the fourth position along k_y
from the origin. This is as yet incomplete, as there may be
constructive interference in the form of upward banding from
adjacent pixel combining their k_y-vectors to result in an overall
upwardly-directed vector. The matter is still under investigation.
ZEROSPIKE is, of course, applied before any other operations are
carried outupon the data, since the sources are presumed to be
electronic rather than physical or optical.
OUTPUTS:
DATEOBS - (optional) array of full SSW DATE_OBS header values. Very
handy sometimes
OUTINDEX - (optional) the original file number of each frame, useful
when not start from zero and/or using SP steps of more than 1.
OFFARRAY - (optional) if GENOFFSETS is set, this 2XN array holds the
calculated off corresponding to the frame indices held in OUTINDEX.
Useful for e.g. comparisons between on-the-fly calculations and
pre-defined offsets.
GDELTA - (optional) the DELTA keyword output from GRIDMATCH2, called
unless NODESTR is used. If GDETLA is specified in conjunction with
NODESTRETCH, GDELTA will be returned as (integer) zero.
CALLS:
DS_SERIES_DRW (and therefore DSGRID2).
HISTORY:
Versions 0.9 to 1.2: 26/11/03 to 05/12/03:
DRW (drw@mssl.ucl.ac.uk) &
JMA (j.mcateer@qub.ac.uk)
Version 1.3 05/12/03 DRW:
* tidied up code;
* included JMA`s offsets;
* began inclusion of a larger-than-one increment stepping facility.
Version 1.4 16/12/03 DRW:
* finished up stepping facility;
* included OUTINDEX parameter;
* included trimming option to remove first two columns of low-count
data (which can be disabled by using the NOTRIM switch).
Version 1.4.9 06/01/04 DRW:
* fixed incorrect application of offsets to data in final
IF(genoffsets)/ELSE loop.
Version 1.5 07/01/04 DRW:
* added optional OFFARRAY keyword
Version 1.5.8 07/01/04 DRW:
* added destretching functionality through DS_SERIES_DRW (a
modification of DS_SERIES_ALT). The parameters are currently
arbitrary and need to be examined; they will almost certainly
also need tweaking. The process can be skipped by setting the
keyword NODESTRETCH;
* included GDELTA optional output keyword to contain the DELTA
output from DS_SERIES_DRW.
Version 2.0 08/01/04 DRW & JMA:
* added ZEROPSIKE keyword;
* added NOCORR option to skip the alignment of the data completely.
Version 2.0.1 12/01/04 DRW:
* removed erroneous '+1' term on the line which calculates NUM_OUT.
TO DO:
++ Include DUSTYFILELOCATION in the DEDUST loop
++ Check that the right default offsets are being used when GENOFFSETS
isn`t called
+ Should we be using the /EVEN option in MEDIAN() ?
+ Allow user to supply their own offsets via a keyword input
++ Include USAGE term in this documentation header
+ (Work out why the word USAGE looks as if it`s spelt wrong)
+ Square (?) filtering to get rid of spikes at the spatial Nyquist
frequencies.
+ Automate the correct calling of appropriate keywords if the data is
from CamB?
++ Call FINDSPIKES and CUBESPIKES to remove the remaining, harmonic
spikes in the spatial FFT. Need to use
FINDSPIKES,data(*,*,0),outimage,spikemask,ct=5,/quick; then apply
CUBESPIKES,data,spikemask. Probably need to include ability to
reject a mask and start again/skip process completely if
unsatisfactory, once you've alread called it.
++ Set missing pixels in CamB. These do not move and should be set
either to NaN or -1, or a MISSING value supplied by the user.
(See /home/drw/idl/rdi_cal.pro)
READBUF[1]
[Previous Routine]
[Next Routine]
[List of Routines]
purpose: read a multi-dimension data buffer from a named ASCII file
USEAGE: readbuf,file,buf
readbuf,file,buf,tag=tag,ntag=ntag,nskip=nskip,point=point,$
err=err,nc=nc,nl=nl,awk=awk,perl=perl, $
double=double,complex=complex,integer=integer
input:
file file name. If file name ends in a .gz or .Z suffix, the file
is first uncompressed by running it through zcat.
NOTE: make sure your shell knows where to find the zcat
utility. Also note that the generic unix version
of zcat does not uncompress files created by the
gnu compression algorithm. These files usually
have a .gz suffix. The best bet is to set up a
link in your bin directory pointing to the gnu
version of zcat which uncompresses both .gz and .Z
type compressed files. (e.g.,
/home/user13/frew/gnu/alpha-osf/bin/zcat)
buf a named array or structure set up to match the
data structure of FILE.
optional keyword input:
tag string to search before reading begins.
READBUF will scan through FILE looking for a line
containing the string TAG. Data input starts on the
next record (or NSKIP records later, if NSKIP is set)
ntag number of times TAG string is searched before reading input
(default=1 when TAG is set, otherwise zero)
nskip number of records to skip before reading data.
If TAG is set, data input starts NSKIP records after the
NTAG'th occurance of the TAG string in the file.
If TAG is not set, data input starts NSKIP records
after the begining of the file. (default=0)
point byte offset into file after which reading begins
nc if set, buf is dimensioned fltarr(nc,nl) where nl is
either set with the NL keyword, or is set automatically
as the number of lines remaining in the file after tag,
ntag and nskip actions. This option doesn't work when
POINT is specified. Setting nc to zero causes both the
number of columns and the number of lines to be set
automatically by the file's line and word count (using the
unix wc utility). This specification is only useful if the
data is in the form of a rectangular array. The nc=0 option
does not work with the nskip, point, ntag, and tag options.
nl if set buf is dimensioned fltarr(nc,nl), nc should be set
with the NC keyword.
awk an awk command string used to preprocess the file.
if the awk command string is prefixed with "-f" then the
rest of the string is interpreted as the name of a
file containing awk commands. Otherwise the string itself is
interpreted as an awk command.
If the input file is compressed (indicated by a .gz or .Z
suffix) the results of 'zcat file' is piped into awk.
Otherwise, awk reads the input file directly. In either
case the awk command string is used by awk to extract
information from file and write the results to
readbuf_tmp~. This temporary file is subsequently read
by readbuf, and deleted after processing.
perl the name of a perl command script and any required command line
arguments which is used to preprocess the file. For example
if perl is set as,
perl='my_perl_script 3 -x test'
then the input file is preprocessed as
my_perl_script 3 -x test < file > readbuf_tmp~
If the input file is compressed (indicated by a .gz or .Z
suffix) the results of 'zcat file' is piped into perl.
Otherwise, perl reads the input file directly. In
either case the perl command script extracts information
from file and writes the results to readbuf_tmp~. This
temporary file is subsequently read by readbuf, and
deleted after processing.
double read buffer is double precision
complex read buffer is complex
integer read buffer is integer
output:
buf data array
keyword output:
point byte offset into file at which reading stopped,
can be used as input to next call of READBUF
err returns 1 if an io read error is detected.
returns 0 if read is successful.
EXAMPLE:
; After a bunch of uninteresting output, a fortran code
; writes to file junk.dat as follows:
;
; write(*,'(a)') 'bufout:'
; do 20 k=1,3
; do 10 j=1,6
; write(*,'(1p11e11.3)') (buf(i,j,k), i=1,11)
; 10 continue
; 20 continue
;
; the buf array could be read with
buf=fltarr(11,6,3)
readbuf,'junk.dat',buf,tag='bufout:'
; if the fortran code listed above were executed twice
; it is possible to read the second occurance of buf as follows
point=0
buf0=fltarr(1)
readbuf,'junk.dat',buf0,tag='bufout:',point=point
buf=fltarr(11,6,3)
readbuf,'junk.dat',buf,tag='bufout:',point=point
; In this case the first call to READBUF is used to find the
; point (byte offset) in the file just past the first instance
; of the string 'bufout:'. The second call to READBUF starts
; where the previous READBUF left off, scanning the file until
; just after the second occurance of 'bufout:'. At this point
; the second buf is read.
; another way of doing the same thing is with the NTAG parameter,
buf=fltarr(11,6,3)
readbuf,'junk.dat',buf,ntag=2,tag='bufout:',
NOTE: care must be taken that the TAG string is unique.
; Use awk to preprocess a file (which happens to be compressed)
; The awk command does the following:
;
; 1. change the file seperator character to a comma
; 2. select records for which column three = 272,273,276 or 277
; 3. print columns 3,6,7,8 and 9
awk='BEGIN {FS=","};int($3) ~ /27[2367]/ {print $3 $6 $7 $8 $9}'
readbuf,'a_D97.sgp.gz',buf,nc=0,awk=awk
print,buf
author: Paul Ricchiazzi 8JAN93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/readbuf.pro)
READBUF[2]
[Previous Routine]
[Next Routine]
[List of Routines]
purpose: read a multi-dimension data buffer from a named ASCII file
USEAGE: readbuf,file,buf
readbuf,file,buf,tag=tag,ntag=ntag,nskip=nskip,point=point
input:
file file name
buf a named array or structure set up to match the
data structure of FILE.
optional keyword input:
tag string to search before reading begins.
READBUF will scan through FILE looking for a line
containing the string TAG. Data input starts on the
next record (or NSKIP records later, if NSKIP is set)
ntag number of times TAG string is searched before reading input
(default=1 when TAG is set, otherwise zero)
nskip number of records to skip before reading data.
If TAG is set, data input starts NSKIP records after the
NTAG'th occurance of the TAG string in the file.
If TAG is not set, data input starts NSKIP records
after the begining of the file. (default=0)
point byte offset into file after which reading begins
columns if set buf is automatical dimensioned fltarr(columns,nlines)
where nlines is the number of lines remaining in the file
after tag, ntag and nskip actions. This option doesn't
work when POINT is specified.
nlines if set buf is dimensioned fltarr(columns,nlines)
where columns is set with the COLUMNS option.
output:
buf data array
keyword output:
point byte offset into file at which reading stoped,
can be used as input to next call of READBUF
EXAMPLE:
; following a bunch of uninteresting output a fortran code
; writes to file junk.dat as follows
;
; write(*,'(a)') 'bufout:'
; do 20 k=1,3
; do 10 j=1,6
; write(*,'(1p11e11.3)') (buf(i,j,k), i=1,11)
; 10 continue
; 20 continue
;
; the buf array could be read with
buf=fltarr(11,6,3)
readbuf,'junk.dat',buf,tag='bufout:'
; if the fortran code listed above were executed twice
; it is possible to read the second occurance of buf as follows
point=0
buf0=fltarr(1)
readbuf,'junk.dat',buf0,tag='bufout:',point=point
buf=fltarr(11,6,3)
readbuf,'junk.dat',buf,tag='bufout:',point=point
; In this case the first call to READBUF is used to find the
; point (byte offset) in the file just past the first instance
; of the string 'bufout:'. The second call to READBUF starts
; where the previous READBUF left off, scanning the file until
; just after the second occurance of 'bufout:'. At this point
; the second buf is read.
; a simpler way of doing the same thing is with the NTAG parameter,
buf=fltarr(11,6,3)
readbuf,'junk.dat',buf,ntag=2,tag='bufout:',
NOTE: care must be taken that the TAG string is unique.
author: Paul Ricchiazzi 8JAN93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/readbuf.pro)
READFITS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
READFITS
PURPOSE:
Read a FITS file into IDL data and header variables.
EXPLANATION:
Under Unix, READFITS() can also read gzip or Unix compressed FITS files.
CALLING SEQUENCE:
Result = READFITS( Filename,[ Header, heap, /NOSCALE, EXTEN_NO=,
NSLICE=, /SILENT , NaNVALUE =, STARTROW =, NUMROW = ] )
INPUTS:
FILENAME = Scalar string containing the name of the FITS file
(including extension) to be read. If the filename has
a *.gz extension, it will be treated as a gzip compressed
file. If it has a .Z extension, it will be treated as a
Unix compressed file.
OUTPUTS:
Result = FITS data array constructed from designated record.
If the specified file was not found, then Result = -1
OPTIONAL OUTPUT:
Header = String array containing the header from the FITS file.
heap = For extensions, the optional heap area following the main
data array (e.g. for variable length binary extensions).
OPTIONAL INPUT KEYWORDS:
EXTEN_NO - scalar integer specify the FITS extension to read. For
example, specify EXTEN = 1 or /EXTEN to read the first
FITS extension. Extensions are read using recursive
calls to READFITS.
NaNVALUE - This scalar is only needed on architectures (such as VMS)
that do not recognize the IEEE "not a number" (NaN) convention.
It specifies the value to translate any IEEE "not a number"
values in the FITS data array. In addition, if the data is
stored as integer (BITPIX = 16 or 32), and BSCALE is present,
then NaNValue gives the values to pixels assigned with the
BLANK keyword.
NOSCALE - If present and non-zero, then the ouput data will not be
scaled using the optional BSCALE and BZERO keywords in the
FITS header. Default is to scale.
NSLICE - An integer scalar specifying which N-1 dimensional slice of a
N-dimensional array to read. For example, if the primary
image of a file 'wfpc.fits' contains a 800 x 800 x 4 array,
then
IDL> im = readfits('wfpc.fits',h, nslice=2)
is equivalent to
IDL> im = readfits('wfpc.fits',h)
IDL> im = im(*,*,2)
but the use of the NSLICE keyword is much more efficient.
NUMROW - This keyword only applies when reading a FITS extension.
If specifies the number of rows (scalar integer) of the
extension table to read. Useful when one does not want to
read the entire table.
POINT_LUN - Position (in bytes) in the FITS file at which to start
reading. Useful if READFITS is called by another procedure
which needs to directly read a FITS extension. Should
always be a multiple of 2880.
SILENT - Normally, READFITS will display the size the array at the
terminal. The SILENT keyword will suppress this
STARTROW - This keyword only applies when reading a FITS extension
It specifies the row (scalar integer) of the extension table at
which to begin reading. Useful when one does not want to read
the entire table.
keywords added by FMW: NOBIG - set to NOT read array if >200000 bytes
keywords added by FMW: NODATA - set to return header and 0 for data array
keywords added by FMW: HFILE - set to header to disk file.
keywords added by FMW: SHORTHEAD - (def) set to limit header to 78 characters
EXAMPLE:
Read a FITS file TEST.FITS into an IDL image array, IM and FITS
header array, H. Do not scale the data with BSCALE and BZERO.
IDL> im = READFITS( 'TEST.FITS', h, /NOSCALE)
If the file contain a FITS extension, it could be read with
IDL> tab = READFITS( 'TEST.FITS', htab, /EXTEN )
The function TBGET() can be used for further processing of a binary
table, and FTGET() for an ASCII table.
To read only rows 100-149 of the FITS extension,
IDL> tab = READFITS( 'TEST.FITS', htab, /EXTEN,
STARTR=100, NUMR = 50 )
To read in a file that has been compressed:
IDL> tab = READFITS('test.fits.gz',h)
ERROR HANDLING:
If an error is encountered reading the FITS file, then
(1) the system variable !ERROR is set (via the MESSAGE facility)
(2) the error message is displayed (unless /SILENT is set),
and the message is also stored in !ERR_STRING
(3) READFITS returns with a value of -1
RESTRICTIONS:
(1) Cannot handle random group FITS
NOTES:
(1) If data is stored as integer (BITPIX = 16 or 32), and BSCALE
and/or BZERO keywords are present, then the output array is scaled to
floating point (unless /NOSCALE is present) using the values of BSCALE
and BZERO. In the header, the values of BSCALE and BZERO are then
reset to 1. and 0., while the original values are written into the
new keywords O_BSCALE and O_BZERO. If the BLANK keyword was
present, then any input integer values equal to BLANK in the input
integer image are scaled to NaN (or the value of the NaNValue
keyword) after the scaling to floating point.
(2) The procedure FXREAD can be used as an alternative to READFITS.
FXREAD has the option of reading an arbitary subsection of the
primary FITS data.
(3) The use of the NSLICE keyword is incompatible with the NUMROW
or STARTROW keywords.
PROCEDURES USED:
Functions: SXPAR(), WHERENAN()
Procedures: IEEE_TO_HOST, SXADDPAR, FDECOMP
MODIFICATION HISTORY:
MODIFIED, Wayne Landsman October, 1991
Added call to TEMPORARY function to speed processing Feb-92
Added STARTROW and NUMROW keywords for FITS tables Jul-92
Work under "windows" R. Isaacman Jan-93
Check for SIMPLE keyword in first 8 characters Feb-93
Removed EOF function for DECNET access Aug-93
Work under "alpha" Sep-93
Null array processing fixed: quotes in a message
properly nested, return added. Affected case when
readfits called from another procedure. R.S.Hill Jul-94
Correct size of variable length binary tables W.Landsman Dec-94
To read in compressed files on Unix systems. J. Bloch Jan-95
Check that file is a multiple of 2880 bytes Aug-95
Added FINDFILE check for file existence K.Feggans Oct-95
Consistent Error Handling W. Landsman Nov-95
Handle gzip image extensions W. Landsman Apr-96
Fixed bug reading 1-d data introduced Apr-96 W. Landsman Jun-96
Don't use FINDFILE (too slow), & check for Blank values WBL Oct-96
!VALUES wasn't compatible with IDL V3.6 WBL Jan-97
Added ability to read Unix compressed (.Z) files WBL Jan-97
Changed a FIX to LONG to handle very large tables WBL Apr-97
Force use of /bin/sh shell with gzip WBL Apr-97
Recognize BSCALE, BZERO in IMAGE extensions WBL Jun-97
Added NSLICE keyword WBL Jul-97
Added ability to read heap area after extensions WBL Aug-97
Suppress *all* nonfatal messages with /SILENT WBL Dec-97
Fix NaN assignment for int data C. Gehman/JPL Mar-98
Fix bug with NaNvalue = 0.0 C. Gehman/JPL Mar-98
FW updates April 1997
(See /home/drw/idl/icur/readfits.pro)
READIT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
READIT
PURPOSE:
This function reads two dimensional FUSE FITS files, such as
the *fraw.fit files created by OPUS. It may not properly read
other types of files.
CATEGORY:
FITS.
CALLING SEQUENCE:
Result = READIT(Filename)
INPUTS:
Filename:
Input FITS filename. It can be in any standard FUSE
FITS type.
KEYWORD PARAMETERS:
TRANGE: An [N,2] element matrix containing the start and ending
times of N intervals to include in the array. If N = 1,
a simple two element vector, [tstart,tend] may be used.
XRANGE: A two element vector containing the range of x to include
in the array.
YRANGE: A two element vector containing the range of y to include
in the array.
PRANGE: A two element vector containing the range of pulse height
to include in the array. Not relevant for histograms.
SCALE: Scale factor for array. Can be set to make the resultant
array a reasonable size. A scale size of n bins the
image n x n.
PHD: The returned pulse height distribution. Empty for histograms.
FHEADER:The returned FITS header.
BHEADER:The returned FITS header from the binary table extension.
Equal to FHEADER for histograms
PHOTONS:Reads only this number of photons from the data file. This
works only for photon lists files.
FTYPE: Set this to a type of image to override file type returned
by filetype(). Valid types include:
TTAG OPUS time tag
HIST OPUS spectral image mode
PIPELINE Science pipeline image
XYP_LIST UCB GSE photon list
COUNT_IMAGE UCB GSE histogram
GAIN_IMAGE UCB GSE gain histogram
TXYP_LIST UCB GSE photon list with time
FES FES file
TTGD TTGD file from pipeline
ERROR: If included, and the file is a pipeline calibration file,
load the error array (2nd extension) rather than the data
array (1st extension).
QUALITY:If included, and the file is a pipeline calibration file,
load the quality array (3rd extension) rather than the data
array (1st extension).
EXTENSION:If set, this extension will be read as a two dimensional
image. Note that this will only worked for unrecognized
file types.
GOODTIMES:If set, and the file is an OPUS TTAG file, data that is not
in a good time interval (as listed in the second binary
extension) is not included in the returned structure.
EXPAND: If present, scale the number of x and y pixels in a histogram
by SPECBINX and SPECBINY. Flux in each pixel is spread evenly
over the new smaller pixels.
XSCALED,YSCALED:
If these keywords are present, on return they will contain
the value of x and y scaling that was applied to the data.
They are probably the values of SPECBINX and SPECBINY or 1,1,
and are returned by OPUS2HIST or HIST2HIST.
SILENT: If included, suppress informative messages.
COMMON BLOCKS:
LAMSPACE:for IMAGE.PRO.
PROCEDURE:
Calls LIST2HIST, HIST2HIST, or OPUS2HIST as appropriate.
EXAMPLE:
To read the data from a 'raw' data file into the two dimensional
array data[]:
IDL> data = readit(infile)
To read a time tag file and return its FITS headers and pulse height
distribution for plotting:
IDL> data = readit(infile,fheader=fheader,bheader=bheader,phd=phd)
IDL> plot, phd, psym=10 ;to plot the pulse height distribution
IDL> print, fheader, bheader ;to display the FITS headers.
MODIFICATION HISTORY:
Written by David Sahnow, 12 August 1997.
14 November 1997 Added 'COUNT_IMAGE' option to ftype
4 December 1997 Now assumes ftype = UNDEFINED is a histogram
3 March 1998 Added FTYPE keyword to override default.
30 September 1998 Added TTAG ftype (from OPUS output).
1 October 1998 Added HIST ftype (from OPUS output).
3 November 1998 Added list=2 type, which calls OPUS2HIST.
6 November 1998 Added ftype = PIPELINE.
13 November 1998 Added PHOTON keyword.
8 April 1999 list=4 and list=5 type for pipeline calibration files.
11 June 1999 Added support for FES files. Added EXTENSION keyword.
12 September 1999 Added GOODTIMES keyword.
18 September 1999 Modified keyword parameter description for TRANGE.
29 November 1999 Modified to trap ftype of UNDEFINED.
1 November 1999 Added ftype of TCNT (total count rate file).
30 January 2000 Added EXPAND keyword, which gets passed to OPUS2HIST
and HIST2HIST.
17 February 2000 Now prints out the FILETYPE in the error message
noting that file can't be read.
30 May 2000 Added SILENT keyword.
20 June 2000 Added TTGD ftype.
6 July 2000 Now prints out filename if file not found
6 October 2000 Added ONED ftype.
1 November 2000 Set xscaled, yscaled = 1 for list = 3,4,5,6.
4 November 2000 Now uses EXPAND_TILDE to allow the use of the
tilde in the input filename.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/readit.pro)
READ_SAMPLE
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
SECIS (Zambia, 2001)
NAME:
READ_SAMPLE
PURPOSE:
To browse through a set of SECIS frames in a particular channel, with
the geometrical flip corrected if necessary, with a particular number
of frames skipped between each displayed frame, starting at an inital
frame number.
USAGE:
read_sample,outcube,firstframe,numframes,ut_times,step=step,$
white=white,quiet=quiet,zed=zed,fnorm=fnorm,indices=indices,$
pathwhite=pathwhite,pathgreen=pathgreen
OUTPUTS:
OUTCUBE - the name of the output data cube.
UT_TIMES - a vector of strings, each containing the UTC time at which
the original frame was grabbed. Assumes certain exposure time
and delay time between exposures (SECIS uses *asynchronous* mode).
INPUTS:
FIRSTFRAME - the frame number of the first file to be read in (integer).
e.g. 2000
NUMFRAMES - the number of frames in the output data cube (integer).
KEYWORDS:
(none are compulsory)
NOCAL - suppress the calibration of the images. Useful until we get the
process just right.
STEP - the number of frames between each reading, e.g. STEP=5 will result
in every 5th frame in the original sequence being read into the output
cube (integer)
WHITE - set this keyword to grab frames from the White Light sequence,
rather than the default Fe XIV 5303A sequence (i.e. /WHITE).
QUIET - Suppress noisiness from READFITS, the calibration process, etc.
(called as /QUIET)
ZED - if you want to include a suffix such as 'Z' at the end of the date and
time in the UT_TIMES vector of times (e.g. 2001-06-21T13:09:16.300Z)
then this is the place to do it (string).
PATHWHITE - the directory containing the white light images. This is used if
you want to read in data other than the level 0 (unprocessed FITS) data.
PATHGREEN - similar to PATHWHITE.
FNORM - set this keyword to normalise each frame to 255 (byte array)
before being stored in the output cube. Useful in the 2001 sequence
where recording started when some of the chromosphere was still visible
and hence saturated the CCDs in both channels. Looking at the cube with
XMOVIE is a lot nicer if you use this keyword.
INDICES - the vector of frame numbers selected.
EXAMPLE:
read_sample,data,0,16,uttimes,step=500,/quiet,zed='Z',/fnorm
read_sample,data,2500,50,uttimes
CALLS:
SECIS2UTC to get the UT times.
CALIB_SECIS to calibrate the input files.
HISTORY:
v1.0 - David Williams @ QUB -- 4th October 2001.
v1.1 - DRW @ MSSL -- 27th Jun 2002. Changed FNORM so that it now
scales each frame with BYTSCL (i.e. from 0 to 255). rather
than simply dividing through by the image maximum. This
makes it a lot friendlier to colour tables and XMOVIE.
Also added the NOCAL keyword to avoid calibration during
read-in, and WHOLEIM keyword to allow the entire frame
to be read and calibrated, rather than the portion
IMAGE[11:480,0:379] to which the routine otherwise defaults.
v1.2 - DRW @ MSSL -- 15th Jul 2002. Added pathgreen and pathwhite
keywords so that calibrated files can be read in from, e.g.
/work/shifted/e01x.N/ (x = {b|n}, N = level of processing)
TODO:
Need to add ability to choose subfields by specifying ranges of
X and Y, as well as T.
(See /home/drw/idl/secis2/read_sample.pro)
READ_SEC.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
READ_SEC.PRO
PURPOSE:
to read in SECIS sequences of length
N, where N is taken as (LAST-FIRST)+1
USAGE:
READ_SEC,DATA,FIRST,LAST[,/green]
INPUTS:
FIRST - the number of the first FITS image to
be read, e.g. 12 will set narrow0012.fit as
DATA(*,*,0).
LAST - the number of the last FITS image to
read in.
GREEN - if this is set, then the images will be
reversed before being set into the array DATA
(designed for the SECIS green line images)
OUTPUTS:
DATA - the floating point array of dimensions
504x504xN
HISTORY:
Author - D. Williams 7/3/2000
(See /home/drw/idl/secis/read_sec.pro)
READ_SEC_GREEN.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
READ_SEC_GREEN.PRO
PURPOSE:
to read in SECIS green-line sequences of length
N, where N is taken as (LAST-FIRST)+1
USAGE:
READ_SEC_GREEN,DATA,FIRST,LAST
INPUTS:
FIRST - the number of the first FITS image to
be read, e.g. 12 will set narrow0012.fit as
DATA(*,*,0).
LAST - the number of the last FITS image to
read in.
OUTPUTS:
DATA - the floating point array of dimensions
504x504xN
HISTORY:
Author - D. Williams 7/3/2000
(See /home/drw/idl/secis/read_sec_green.pro)
READ_TEXT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: read_text
PURPOSE: read text from a file
USEAGE: result=read_text(file,tag)
INPUT:
file name of input file (string). if only one argument is
supplied it is interpreted as the tag value and
"captions.txt" is used as the default file.
tag Text tag number. A text tag is of the form ;tag;. The return
value is a string extending from tag to the first blank line.
;1;this is an example
;2;this is the second line
then read_text(FILE,1) would yield, "this is an example".
NOTE: Since a semicolon is interpreted by IDL as a comment
you can put your caption text inside your IDL scripts.
OUTPUT:
result matched text in FILE.
DISCUSSION:
READ_TEXT can be used to read text blocks from a file. READ_TEXT
opens the named file and scans forward in the file until a line
containing the TAG string is found. READ_TEXT reads forward until
until a record containing no characters is found. (i.e., a
carriage return with no characters or spaces in the line). All
text between the TAGed record and the blank line are returned.
READ_TEXT can be used with CAPTION to write figure captions onto
plots.
EXAMPLE:
suppose file captions.txt contains ("|" indicates zeroeth column):
|figure 1. some stuff
|
|figure 2. some other stuff
|test test test
|
|figure 3. some more stuff
caption,read_text('captions.txt','figure 2.')
AUTHOR: Paul Ricchiazzi 13 Mar 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/read_text.pro)
READ_TEXT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: read_text
PURPOSE: read text from a file
USEAGE: result=read_text(file,tag)
INPUT:
file name of input file (string). if only one argument is
supplied it is interpreted as the tag value and
"captions.txt" is used as the default file.
tag search string. READ_TEXT scans forward in the file until
a line containing the TAG string is found. From there
READ_TEXT reads forward until an empty line is found.
You can also tag the text block with a special invisible
tag, i.e., a tag string which will not appear in the
output string. This special tag is composed of any NUMBER
surrounded by the semicolon character ";". In this case
the value of tag supplied to READ_TEXT should be an integer
For example if FILE contains the lines,
;1;this is an example
;2;this is the second line
then read_text(FILE,1) would yield, "this is an example".
NOTE: Since a semicolon is interpreted by IDL as a comment
you can put your caption text inside your IDL scripts.
OUTPUT:
result matched text in FILE.
DISCUSSION:
READ_TEXT can be used to read text blocks from a file. READ_TEXT
opens the named file and scans forward in the file until a line
containing the TAG string is found. READ_TEXT reads forward until
until a record containing no characters is found. (i.e., a
carriage return with no characters or spaces in the line). All
text between the TAGed record and the blank line are returned.
READ_TEXT can be used with CAPTION to write figure captions onto
plots.
EXAMPLE:
suppose file captions.txt contains ("|" indicates zeroeth column):
|figure 1. some stuff
|
|figure 2. some other stuff
|test test test
|
|figure 3. some more stuff
caption,read_text('captions.txt','figure 2.')
AUTHOR: Paul Ricchiazzi 13 Mar 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/read_text.pro)
READ_TOMS
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: read_toms,file,ozone
PURPOSE: read toms ascii data files
USEAGE: read_toms,ozone,lons,lats
INPUT:
file Name of the toms archive data file.
OUTPUT:
ozone ozone in dobson units in an global output grid
Longitudes: 288 bins centered on 179.375 W to 179.375 E
(1.25 degree steps)
Latitudes : 180 bins centered on 89.5 S to 89.5 N
(1.00 degree steps)
lons vector of longitudes (degrees)
lats vector of latitudes (degrees)
DISCUSSION:
TOMS ozone data files from the Earth Probe satellite may be
obtained via anonymous ftp from:
/anonymous@jwocky.gsfc.nasa.gov:/pub/eptoms
Each file contains global noon time measurements of total column
ozone for one day. The data format is directly readable by this
procedure. Data is available for 1996, 1997 and 1998 (in
directories oz96, oz97 and oz98)
EXAMPLE:
read_toms,'ga970930.ept',ozone,lons,lats
tvim,ozone,xrange=lons,yrange=lats,/scale
map_set,0,0,/cont,/cyl,/noerase,pos=boxpos(/get)
; find toms ozone at sgp site for each day in
; september and october of 1997
files=findfile('ozone/*.ept')
lat=36.605 & lon=-97.485
oz=fltarr(n_elements(files))
for i=0,n_elements(files)-1 do begin &$
print,files(i) &$
read_toms,files(i),ozone,lons,lats &$
fill_image,ozone,where(ozone eq 0.) &$
oz(i)=interp(ozone,lons,lon,lats,lat) &$
endfor
AUTHOR: Paul Ricchiazzi 04 Jun 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/read_toms.pro)
REDUCE_CAII
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: reduce_caii
PURPOSE: De-bias and flat-field CaII data from Sac Peak
Also select best image from 8 CaII images taken
every 40 sec interval.
USEAGE: REDUCE_CAII, File, Image, Time
INPUT:
File Filename as a string
OUTPUT:
Image Image array
Time String containing time image was taken at
EXAMPLE: IDL> Time=STRARR(200)
IDL> Data = fltarr(501,501,200)
IDL> FOR i=0,199 DO BEGIN REDUCE_CAII,'flare'+ARR2STR(i,/tr)+'.fits',dumi,dumt&data(*,*,i)=dumi&time(i)=dumt&print,i
AUTHOR: Peter T. Gallagher, Jan. '98
(See /home/drw/idl/vtt/reduce_caii.pro)
REDUCE_CAII_OLD
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: reduce_caii
PURPOSE: De-bias and flat-field CaII data from Sac Peak
Also select best image from 8 CaII images taken
every 40 sec interval.
USEAGE: REDUCE_CAII, File, Image, Time
INPUT:
File Filename as a string
OUTPUT:
Image Image array
Time String containing time image was taken at
EXAMPLE: IDL> Time=STRARR(200)
IDL> Data = fltarr(501,501,200)
IDL> FOR i=0,199 DO BEGIN REDUCE_CAII,'flare'+ARR2STR(i,/tr)+'.fits',dumi,dumt&data(*,*,i)=dumi&time(i)=dumt&print,i
AUTHOR: Peter T. Gallagher, Jan. '98
(See /home/drw/idl/vtt/reduce_caii_old.pro)
REDUCE_UBF
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: reduce_ubf
PURPOSE: De-bias and flat-field UBF data from Sac Peak
USEAGE: REDUCE_UBF, Cube, T, pass_band_number
INPUT:
OUTPUT:
EXAMPLE:
AUTHOR: Peter T. Gallagher, Jan. '98
(See /home/drw/idl/vtt/reduce_ubf.pro)
REDUCE_UBF_OLD
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: reduce_caii
PURPOSE: De-bias and flat-field CaII data from Sac Peak
Also select best image from 8 CaII images taken
every 40 sec interval.
USEAGE: REDUCE_CAII, File, Image, Time
INPUT:
File Filename as a string
OUTPUT:
Image Image array
Time String containing time image was taken at
EXAMPLE: IDL> Time=STRARR(200)
IDL> Data = fltarr(501,501,200)
IDL> FOR i=0,199 DO BEGIN REDUCE_CAII,'flare'+ARR2STR(i,/tr)+'.fits',dumi,dumt&data(*,*,i)=dumi&time(i)=dumt&print,i
AUTHOR: Peter T. Gallagher, Jan. '98
(See /home/drw/idl/vtt/reduce_ubf_old.pro)
REDUNDANT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: redundant
PURPOSE: returns the indicies of elements array which are non-unique
USEAGE: result=redundant(array)
INPUT:
array a vector array
KEYWORD INPUT:
all if set, return all elements which appear more than
once. The default is to return all but one of the
replicated elements
non If set, return all non-redundant elements. If ALL
is also set, return those elements which appear
only once, (i.e., all replicated items are left off
the list).
indecies If set return array indecies instead of the array
elements.
EXAMPLE:
;
array=[1,2,3,1,4,2,3,3,5]
print,array
; 1 2 3 1 4 2 3 3 5
print,redundant(array)
1 2 3 3
print,redundant(array,/non)
; 1 4 2 3 5
print,redundant(array,/all)
; 1 2 3 1 2 3 3
print,redundant(array,/all,/non)
; 4 5
print,redundant(array,/all,/non,/indecies)
4 8
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/redundant.pro)
REDUNDANT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: redundant
PURPOSE: returns the indicies of elements array which are non-unique
USEAGE: result=redundant(array)
INPUT:
array a vector array
KEYWORD INPUT:
all if set, return all elements which appear more than
once. The default is to return all but one of the
replicated elements
non If set, return all non-redundant elements. If ALL
is also set, return those elements which appear
only once, (i.e., all replicated items are left off
the list).
indecies If set return array indecies instead of the array
elements.
EXAMPLE:
;
array=[1,2,3,1,4,2,3,3,5]
print,array
; 1 2 3 1 4 2 3 3 5
print,redundant(array)
1 2 3 3
print,redundant(array,/non)
; 1 4 2 3 5
print,redundant(array,/all)
; 1 2 3 1 2 3 3
print,redundant(array,/all,/non)
; 4 5
print,redundant(array,/all,/non,/indecies)
4 8
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/redundant.pro)
REFICE
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: refice
PURPOSE: compute complex refractive index of ice
USEAGE: result=refice(w)
INPUT:
w wavelength in microns 0.29 < w < 333.33 um
if on input w=0, the entire lookup table contained in
"refice.dat" is returned, and w is set to the
corresponding wavelength vector which is
w=.29*(333.33/.29)^(findgen(400)/399)
KEYWORD INPUT:
none
OUTPUT:
complex refractive index
DISCUSSION:
uses table lookup
EXAMPLE:
w8x11
!p.multi=[0,1]
w=.29*(333.33/.29)^(findgen(400)/399)
plot_oi,w,float(refice(w))
plot_oi,w,imaginary(refice(w))
REVISIONS:
AUTHOR: Paul Ricchiazzi 27 Jul 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/refice.pro)
REGRID[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: regrid
USEAGE: regrid,alat,alon,nnx,nny,kx,ky, $
latrng=latrng,lonrng=lonrng, $
proj=proj,extras=extras,degree=degree
PURPOSE: Find polynomial coeffients to warp an irregular grid into
a regular grid, or to a specified map projection. The
actual morphing is accomplised by POLY_2D. The IDL
procedure MAP_IMAGE, performs a similar function. It is
used to map a *regularly* grided image to a given map
projection.
INPUT:
alat array of pixel latitudes
alon array of pixel longitudes
nnx number of pixels in x direction of output array
nny number of pixels in y direction of output array
OPTIONAL KEYWORD INPUT:
latrng range of output latitudes (default = [min(alat),max(alat)] )
not used when proj is set
lonrng range of output longitudes (default = [min(alon),max(alon)] )
not used when proj is set
nsamp number of sample points from which to
generate warping polynomial (default = 400)
degree the degree of the warping polynomial (default = 2)
extras extra parameters (single value, array or structure) used in
the user supplied projection procedure. The defininition of
extras is completely up to the user.
proj:
The name of the user supplied procedure which computes the
map projection. if proj is not supplied a cylindrical
projection is assumed. The user supplied procedure must
accept as arguments alat,alon,extras and return the
normalized coordinates xnorm,ynorm which show where a given
lat,lon map to on a unit grid. Here is an example for
polar orthographic projection.
pro polar_orthographic,alat,alon,extras,xn,yn
outer_lat=extras(0) ; the outer latitude limit
xmax=cos(outer_lat*!dtor)
xmin=-xmax
ymax=xmax
ymin=xmin
if outer_lat gt 0 then begin
xn=cos(alat*!dtor)*cos(alon*!dtor)
yn=cos(alat*!dtor)*sin(alon*!dtor)
endif else begin
xn=cos(alat*!dtor)*cos(-alon*!dtor)
yn=cos(alat*!dtor)*sin(-alon*!dtor)
endelse
xn=(xn-xmin)/(xmax-xmin) ; normalized coordinates
yn=(yn-ymin)/(ymax-ymin)
return
end
OUTPUT:
kx polynomial coefficients relating indecies xold to (xnew,ynew)
ky polynomial coefficients relating indecies yold to (xnew,ynew)
COMMON BLOCKS: NONE
SIDE EFFECTS: NONE
EXAMPLE:
;;
c=complex(2,2)+cmplxgen(250,200,/center)/100 ; create alat & alon
c=c+c^2
alon=float(c)-100
alat=20+imaginary(c)
im=sqrt(abs(sin(alon*!pi)*sin(alat*!pi)))^.3
!p.multi=[0,1,2]
window,/free,xs=400,ys=600 ; create new window
tvim,im,/scale,title='image'
latrng=[28,34] & lonrng=[-100,-95] & nnx=200 & nny=150
contour,alat,/overplot,levels=latrng,thick=4,color=0
contour,alon,/overplot,levels=lonrng,thick=4,color=0
; regrid and display
regrid,alat,alon,latrng=latrng,lonrng=lonrng,nnx,nny,kx,ky
imm=poly_2d(im,kx,ky,0,nnx,nny,missing=0)
tvim,imm,/scale,xr=lonrng,yr=latrng,title='regrided image'
;; polar projection
window,/free,xs=400,ys=1000
!p.multi=[0,1,3]
c=complex(2,2)+cmplxgen(128,128,/center)/100 ; create alat & alon
c=c+c^2
latrng=[30,70] & lonrng=[-110,-70] & nnx=200 & nny=200
alon=(float(c)-min(float(c)))/(max(float(c))-min(float(c)))
alat=(imaginary(c)-min(imaginary(c)))/(max(imaginary(c))-min(imaginary(c)))
alon=lonrng(0)+(lonrng(1)-lonrng(0))*alon
alat=latrng(0)+(latrng(1)-latrng(0))*alat
im=randata(128,128,s=4) gt 2
tvim,im,/scale,title='image'
tvlct,[0,255,0],[0,0,0],[0,0,255]
contour,alat,/overplot,levels=[40,50,60],thick=4,color=1
contour,alon,/overplot,levels=[-100,-90,-80],thick=4,color=2
regrid,alat,alon,nnx,nny,kx,ky,proj='polar_ortho',extras=30,degree=2
imm=poly_2d(im,kx,ky,0,nnx,nny,missing=0)
tvim,imm,/scale,xr=[-5517,5517],yr=[-5517,5517],title='regrided image, d=2'
r=cos([40,50,60]*!dtor)*6371
a=(-70-indgen(41))*!dtor
for i=0,2 do oplot,r(i)*cos(a),r(i)*sin(a),color=1
a=[-100,-90,-80]*!dtor
for i=0,2 do oplot,5517*[0,cos(a(i))],5517*[0,sin(a(i))],color=2
;;
NOTE: the bogus stuff in the upper half plane of the tvim image is
due to the use of the polynomial expansion outside the range
for which the fit is valid. This only happens when the new
grid extends far beyond the limits of the original irregular
grid.
author: Paul Ricchiazzi ESRG
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/regrid.pro)
REGRID[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: regrid,alat,alon,latrng=latrng,lonrng=lonrng,nnx,nny,kx,ky
PURPOSE: Find polynomial coeffients to warp an irregular grid into
a regular grid.
INPUT:
alat array of pixel latitudes
alon array of pixel longitudes
nnx number of pixels in x direction of output array
nny number of pixels in y direction of output array
OPTIONAL KEYWORD INPUT:
latrng range of output latitudes (default = [min(alat),max(alat)] )
not used when projection_name is set
lonrng range of output longitudes (default = [min(alon),max(alon)] )
not used when projection_name is set
nsamp number of sample points from which to
generate warping polynomial (default = 400)
degree the degree of the warping polynomial (default = 2)
extras extra parameters (single value, array or structure) used in
the user supplied projection procedure. The defininition of
extras is completely up to the user.
projection_name:
The name of the user supplied procedure which computes the
map projection. if projection_name is not supplied a
cylindrical projection is assumed. The user supplied
procedure must accept as arguments alat,alon,extras and
return the normalized coordinates xnorm,ynorm which show
where a given lat,lon map to on a unit grid. Here is an
example for polar orthographic projection.
pro polar_orthographic,alat,alon,extras,xn,yn
outer_lat=extras(0) ; the outer latitude limit
xmax=cos(outer_lat*!dtor)
xmin=-xmax
ymax=xmax
ymin=xmin
if outer_lat gt 0 then begin
xn=cos(alat*!dtor)*cos(alon*!dtor)
yn=cos(alat*!dtor)*sin(alon*!dtor)
endif else begin
xn=cos(alat*!dtor)*cos(-alon*!dtor)
yn=cos(alat*!dtor)*sin(-alon*!dtor)
endelse
xn=(xn-xmin)/(xmax-xmin) ; normalized coordinates
yn=(yn-ymin)/(ymax-ymin)
return
end
OUTPUT:
kx polynomial coefficients relating indecies xold to (xnew,ynew)
ky polynomial coefficients relating indecies yold to (xnew,ynew)
COMMON BLOCKS: NONE
SIDE EFFECTS: NONE
PROCEDURE: Use together with POLY_2D to warp images to regular lat,lon
grid.
EXAMPLE:
c=complex(2,2)+cmplxgen(250,200,/center)/100 ; create alat & alon
c=c+c^2
alon=float(c)-100
alat=20+imaginary(c)
im=sqrt(abs(sin(alon*!pi)*sin(alat*!pi)))^.3
!p.multi=[0,1,2]
window,/free,xs=400,ys=600 ; create new window
tvim,im,/scale,title='image'
latrng=[28,34] & lonrng=[-100,-95] & nnx=200 & nny=150
contour,alat,/overplot,levels=latrng,thick=4,color=0
contour,alon,/overplot,levels=lonrng,thick=4,color=0
; regrid and display
regrid,alat,alon,latrng=latrng,lonrng=lonrng,nnx,nny,kx,ky
imm=poly_2d(im,kx,ky,0,nnx,nny,missing=0)
tvim,imm,/scale,xr=lonrng,yr=latrng,title='regrided image'
; polar projection
window,/free,xs=400,ys=1000
!p.multi=[0,1,3]
c=complex(2,2)+cmplxgen(128,128,/center)/100 ; create alat & alon
c=c+c^2
latrng=[30,70] & lonrng=[-110,-70] & nnx=200 & nny=200
alon=(float(c)-min(float(c)))/(max(float(c))-min(float(c)))
alat=(imaginary(c)-min(imaginary(c)))/(max(imaginary(c))-min(imaginary(c)))
alon=lonrng(0)+(lonrng(1)-lonrng(0))*alon
alat=latrng(0)+(latrng(1)-latrng(0))*alat
im=randata(128,128,s=4) gt 2
tvim,im,/scale,title='image'
tvlct,[0,255,0],[0,0,0],[0,0,255]
contour,alat,/overplot,levels=[40,50,60],thick=4,color=1
contour,alon,/overplot,levels=[-100,-90,-80],thick=4,color=2
regrid,alat,alon,nnx,nny,kx,ky,proj='polar_ortho',extras=30,degree=2
imm=poly_2d(im,kx,ky,0,nnx,nny,missing=0)
tvim,imm,/scale,xr=[-5517,5517],yr=[-5517,5517],title='regrided image, d=2'
r=cos([40,50,60]*!dtor)*6371
a=(-70-indgen(41))*!dtor
for i=0,2 do oplot,r(i)*cos(a),r(i)*sin(a),color=1
a=[-100,-90,-80]*!dtor
for i=0,2 do oplot,5517*[0,cos(a(i))],5517*[0,sin(a(i))],color=2
NOTE: the bogus stuff in the upper half plane of the tvim image is
due to the use of the polynomial expansion outside the range
for which the fit is valid. This only happens when the new
grid extends far beyond the limits of the original irregular
grid.
author: Paul Ricchiazzi ESRG
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/regrid.pro)
REGSTAT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: regstat
PURPOSE: display regional statistics of an image.
USEAGE: regstat,im
INPUT:
im 2-d array
KEYWORD INPUT: none
OUTPUT: none
DISCUSSION:
Use REGSTAT to print the regional statistics of selected areas
within a TVIM image. The region is selected using CURBOX.
The left and middle mouse buttons reduce and increase the
region size. The right mouse button causes the region
statistics to be printed to the terminal (mean, standard
deviation, minimum, maximum and array indicies). Exit the
procedure by hitting the right mouse button while the the
box is outside the plot area
EXAMPLE:
im=randata(128,128,s=3)
tvim,im
regstat,im
REVISIONS:
AUTHOR: Paul Ricchiazzi 01 Jun 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/regstat.pro)
REGSTAT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: regstat
PURPOSE: display regional statistics of an image.
USEAGE: regstat,im
INPUT:
im 2-d array
KEYWORD INPUT: none
OUTPUT: none
DISCUSSION:
Use REGSTAT to print the regional statistics of selected areas
within a TVIM image. The region is selected using CURBOX.
The left and middle mouse buttons reduce and increase the
region size. The right mouse button causes the region
statistics to be printed to the terminal (mean, standard
deviation, minimum, maximum and array indicies). Exit the
procedure by hitting the right mouse button while the the
box is outside the plot area
EXAMPLE:
im=randata(128,128,s=3)
tvim,im
regstat,im
REVISIONS:
AUTHOR: Paul Ricchiazzi 01 Jun 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/regstat.pro)
RELHUM[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: relhum
PURPOSE: compute relative humidity from wet and dry bulb temperature
and pressure
USEAGE: result=relhum(td,tw,p)
INPUT:
t ambient (dry bulb) temperature (celsius)
tw wet bulb temperatrue (celsius)
p pressure (mb)
OUTPUT:
rh relative humidity (partial pressure of water vapor divided
by the saturated water vapor pressure)
EXAMPLE:
print,'the relative humidity is ',relhum(29,20,980)
References:
Tetans, O. 1930. Uber emige meteorologische Begriffe. Z. Geophys. 6:297-309
Weiss, A.1977. Algorithms for Calculation of Moist Air Properties on a Hand
Calculator. Trans. ASAE 20:1133-1136
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/relhum.pro)
RELHUM[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: relhum
PURPOSE: compute relative humidity from wet and dry bulb temperature
and pressure
USEAGE: result=relhum(td,tw,p)
INPUT:
t ambient (dry bulb) temperature (celsius)
tw wet bulb temperatrue (celsius)
p pressure (mb)
OUTPUT:
rh relative humidity (partial pressure of water vapor divided
by the saturated water vapor pressure)
EXAMPLE:
print,'the relative humidity is ',relhum(29,20,980)
References:
Tetans, O. 1930. Uber emige meteorologische Begriffe. Z. Geophys. 6:297-309
Weiss, A.1977. Algorithms for Calculation of Moist Air Properties on a Hand
Calculator. Trans. ASAE 20:1133-1136
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/relhum.pro)
REPCHR_ESRG
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: repchr
PURPOSE: produces a string composed of repititions of a given character
USEAGE: result=repchr(n,c)
INPUT:
n number of repititions
c character to repeat
EXAMPLE:
print,repchr(20,'-')
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/repchr_esrg.pro)
REPLACE_STRING
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
replace_string
PURPOSE:
This function replaces in a given string or vector of strings all values by an other. Length or only one char didn't matter.
It could also be used to delete a substring from a string.
CATEGORY:
PROG_TOOLS/STRINGS
CALLING SEQUENCE:
Result=replace_string(text,in_string,rep_string,[no_of_replaces=no_of_replaces],[pos=pos],[count=count])
INPUTS:
text: the text where to replace some informations
in_string: the search string
rep_string: the string which should replace in_string
KEYWORD PARAMETERS:
no_of_replace: if set two a number, this means in text as many times of no_of_replace in_string is reaplced by rep_string
pos: if set to a number the replacement starts at this string position
count: this argument returns the number of replaces
OUTPUTS:
Result is the new text
EXAMPLE:
help,replace_string('Dies ist ein Test',' ','_')
STRING = 'Dies_ist_ein_Test'
help,replace_string('Dies ist ein Test',' ','_',pos=5)
STRING = 'Dies ist_ein_Test'
help,replace_string('Dies ist ein Test',' ','_',pos=5,no=1)
STRING = 'Dies ist_ein Test'
help,replace_string('Dies ist ein Test','ist','ist')
STRING = 'Dies ist ein Test'
help,replace_string('Dies ist ein Test, ist ein','ist','ist nicht')
STRING = 'Dies ist nicht ein Test, ist nicht ein'
help,replace_string('\\\\\\\\\','\','/')
STRING = '/////////'
help,replace_string('["..\idl_html\idl_work_cat.htm"]','cat','cat_org')
STRING = '["..\idl_html\idl_work_cat_org.htm"]'
print,replace_string(['12:33:00','12:33:00','12:33:00'],':','')
123300 123300 123300
print,replace_string(['12:33:00','12:33:00','12:33:00'],':','',pos=5)
12:3300 12:3300 12:3300
print,replace_string( 'asdf___ertz_j','__', '')
asdf_ertz_j
print,replace_string(['12:33:00','12:33:00','12:33:00'],':','',pos=5,count=c),c
12:3300 12:3300 12:3300
3
print,replace_string(['12:33:00','12:33:00','12:33:00'],':','',count=c),c
123300 123300 123300
6
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1) , 1998-Sep-06
1998-09-26 bug removed with start_pos and a vector of strings
1998-09-26 special replacement include if a sign should be replaced by an other by n times
1999-09-07 bug removed with replacing '___' by '_'
1999-10-01 count added
2000-03-08 bug with no_of_replaces removed
if text is an array no_of_replaces is used for each element
2001-02-13 Loop in LONG
(See /home/drw/idl/icglib/pro/replace_string.pro)
RETICK
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: retick,x=x,y=y,major=major,minor=minor,color=color,toggle=toggle
PURPOSE: draw tickmarks on plots
USEAGE: retick,x=x,y=y,ticklen=ticklen,color=color,
toggle=toggle,thick=thick
INPUT:
KEYWORD INPUT:
x x axis points
y y axis points
ticklen length of ticks as a percentage of frame size
toggle x or y values at which to toggle color value (color=255-color)
endpoints if set draw endpoint tick marks
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 14 Apr 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/retick.pro)
RE_BIN
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: re_bin
PURPOSE: takes a scalar and shifts it into an appropriate
bin. eg.
x re_bin(x)
8.0 8
8.1 8
8.5 8
8.6 9
USEAGE: result = re_bin(x)
INPUT:
x scalar
OUTPUT: shifted integer value
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/old.esrg/re_bin.pro)
RHOZ[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: rhoz
USEAGE: result=rhoz(p0=p0,t0=t0,z=z,lr=lr)
PURPOSE: compute air density at altitude z
KEYWORD_INPUTS:
p0 surface pressure in mb (default=1013.0 mb)
t0 surface temperature in kelvin (default=273.0 K)
z alitude (km) (default=0 km)
lr lapse rate in kelvin/km (default=6.5 K/km)
;
KEYWORD_OUTPUT:
pz pressure at altitude (mb)
OUTPUT
result air density (kg/m3)
EXAMPLE: compute pressure at a given altitude
p=1013.0*rhoz(z=.440,t0=290.,lr=6.5)/rhoz(t0=290.,lr=6.5)
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/rhoz.pro)
RHOZ[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: rhoz
USEAGE: result=rhoz(p0=p0,t0=t0,z=z,lr=lr)
PURPOSE: compute air density at altitude z
KEYWORD_INPUTS:
p0 surface pressure in mb (default=1013.0 mb)
t0 surface temperature in kelvin (default=273.0 K)
z alitude (km) (default=0 km)
lr lapse rate in kelvin/km (default=6.5 K/km)
result air density (kg/m3)
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/rhoz.pro)
ROOT2D
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: root2d
USEAGE: root2d,utab,u,vtab,v,fx,fy,nc
PURPOSE: finds the floating point indices fx,fy such that
u=interpolate(utab,fx,fy)
v=interpolate(vtab,fx,fy)
i.e, it solves a set non-linear simulateous
equations of the form
u=utab(x,y)
v=utab(x,y)
INPUT:
utab 2d array of values
u scalor value found some where in utab
vtab 2d array of values
v scalor value found some where in vtab
OUTPUT:
fx,fy floating point interpolates into array utab and vtab
nc number of solutions
AUTHOR: Paul Ricchiazzi jun99
Earth Space Research Group, UCSB
EXAMPLE:
utab=randata(20,20,s=4,iseed=systime(1))
wait,.5
vtab=randata(20,20,s=3,iseed=systime(1)/100)
!p.multi=[0,2,2]
contour,utab,level=.5,/follow
contour,vtab,level=.5,/follow,/over,color=100
root2d,utab,.5,vtab,.5,fx,fy,nc
if nc gt 0 then begin &$
oplot,fx,fy,psym=4 &$
for i=0,nc-1 do print,i,fx(i),fy(i), $
interpolate(utab,fx(i),fy(i)),interpolate(vtab,fx(i),fy(i)) &$
end
(See /home/drw/idl/esrg/root2d.pro)
ROOTS
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: roots
PURPOSE: find floating point index, f, such that x=interpolate(xx,f)
where xx is a (possibly non-monotonic) table of values and
x is a scalor. ROOTS returns -1 if no roots are found.
USEAGE: result=roots(xx,x)
INPUT:
xx a table of real numbers, need not be monotonic
x a real number
OUTPUT:
nroot number of roots
DISCUSSION:
Though ROOTS isn't sophisticated, it is thorough. It
checks all the places where ff=(x-xx)/(shift(xx,-1)-xx) is
between [0,1). and returns the value ii+ff, where ii is
the index for which x is bounded by xx(ii) and xx(ii+1).
NOTE: Sparsely populated tables may not produce a
satisfactory accuracy.
EXAMPLE:
; find the roots of the equation t^3-10*t^2-200*exp(-t)+100. = 0
t=findrng(.0,10,1000)
xx=t^3-10*t^2-200*exp(-t)+80.
plot,t,xx
f=roots(xx,0)
oplot,interpolate(t,f),interpolate(xx,f),psym=2
oplot,!x.crange,[0,0],color=100
print,' t(f) =',interpolate(t,f)
AUTHOR: Paul Ricchiazzi 03 Apr 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/roots.pro)
ROUTINE_NAME
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ROUTINE_NAME
PURPOSE:
Tell what your routine does here. I like to start with the words:
"This function (or procedure) ..."
Try to use the active, present tense.
CATEGORY:
Put a category (or categories) here. For example:
Widgets.
CALLING SEQUENCE:
Write the calling sequence here. Include only positional parameters
(i.e., NO KEYWORDS). For procedures, use the form:
ROUTINE_NAME, Parameter1, Parameter2, Foobar
Note that the routine name is ALL CAPS and arguments have Initial
Caps. For functions, use the form:
Result = FUNCTION_NAME(Parameter1, Parameter2, Foobar)
Always use the "Result = " part to begin. This makes it super-obvious
to the user that this routine is a function!
INPUTS:
Parm1: Describe the positional input parameters here. Note again
that positional parameters are shown with Initial Caps.
OPTIONAL INPUTS:
Parm2: Describe optional inputs here. If you don't have any, just
delete this section.
KEYWORD PARAMETERS:
KEY1: Document keyword parameters like this. Note that the keyword
is shown in ALL CAPS!
KEY2: Yet another keyword. Try to use the active, present tense
when describing your keywords. For example, if this keyword
is just a set or unset flag, say something like:
"Set this keyword to use foobar subfloatation. The default
is foobar superfloatation."
OUTPUTS:
Describe any outputs here. For example, "This function returns the
foobar superflimpt version of the input array." This is where you
should also document the return value for functions.
OPTIONAL OUTPUTS:
Describe optional outputs here. If the routine doesn't have any,
just delete this section.
COMMON BLOCKS:
BLOCK1: Describe any common blocks here. If there are no COMMON
blocks, just delete this entry.
SIDE EFFECTS:
Describe "side effects" here. There aren't any? Well, just delete
this entry.
RESTRICTIONS:
Describe any "restrictions" here. Delete this section if there are
no important restrictions.
PROCEDURE:
You can describe the foobar superfloatation method being used here.
You might not need this section for your routine.
EXAMPLE:
Please provide a simple example here. An example from the PICKFILE
documentation is shown below. Please try to include examples that
do not rely on variables or data files that are not defined in
the example code. Your example should execute properly if typed
in at the IDL command line with no other preparation.
Create a PICKFILE widget that lets users select only files with
the extensions 'pro' and 'dat'. Use the 'Select File to Read' title
and store the name of the selected file in the variable F. Enter:
F = PICKFILE(/READ, FILTER = ['pro', 'dat'])
MODIFICATION HISTORY:
Written by: Your name here, Date.
July, 1994 Any additional mods get described here. Remember to
change the stuff above if you add a new keyword or
something!
(See /home/drw/idl/esrg/template.pro)
ROUTINE_NAMES (DOCUMENTATION ONLY)[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ROUTINE_NAMES (DOCUMENTATION ONLY)
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Examine variables and parameters of procedures and call stack (OBSOLETE)
CALLING SEQUENCE:
Various, see USAGE VARIATIONS.
DESCRIPTION:
ROUTINE_NAMES obtains information about routines, and their
variables and keywords. Using these functions, a subroutine can
interrogate, and in some cases change, the values and names of
variables and parameters in its calling routine, or at the $MAIN$
level. Some functionality of ROUTINE_NAMES is also in the IDL
system function ROUTINE_INFO, and other functionality is exclusive
to ROUTINE_NAMES.
ROUTINE_NAMES has been designated as "OBSOLETE" by RSI, although
it will probably not disappear soon since their own software
appears to use it.
ROUTINE_NAMES can be invoked in several different ways, which are
detailed below, under USAGE VARIATIONS.
ROUTINE_NAMES uses a notion of the current IDL "call level," which
is the numerical stack depth of the currently executing routine.
At each procedure or function call, the call level becomes one
*deeper*, and upon each RETURN, the call level becomes one
*shallower*. The call stack always begins at the $MAIN$ level.
The current call stack can always be printed by executing HELP.
When specifying the call level to ROUTINE_NAMES, one can use one
of two numbering systems, depending on whichever is most
convenient. In the *absolute* numbering system, the $MAIN$ level
starts at number 1, and becomes deeper with increasing numbers.
In the *relative* numbering system, the current (deepest) call
level is number 0, and becomes shallower with more negative
numbers. Hence, if the deepest level is N, then the
correspondence is thus:
VALUE MEANING
--------------------------------
1 or -N+1 $MAIN$ level
2 or -N+2 NEXT deeper level
... ...
N or 0 DEEPEST (currently executing) level
USAGE VARIATIONS:
PROCS = ROUTINE_NAMES( [/UNRESOLVED])
PROCS = ROUTINE_NAMES(/PROCEDURES [,/UNRESOLVED])
FUNCS = ROUTINE_NAMES(/FUNCTIONS [,/UNRESOLVED])
The currently compiled procedures and functions are
returned, respectively, as a string array. Functions
declared via FORWARD_FUNCTION are also returned. If the
UNRESOLVED keyword is set then the currently unresolved
procedures and functions are returned. These are known
routines which have not yet been compiled.
PROCS = ROUTINE_NAMES(/S_PROCEDURES)
FUNCS = ROUTINE_NAMES(/S_FUNCTIONS)
The lists of system procedures and functions is returned,
as a string array.
LEVNUM = ROUTINE_NAMES(/LEVEL)
The call level of the calling routine is returned.
NAMES = ROUTINE_NAMES(ARG0, ARG1, ..., ARGN, ARG_NAME=LEVEL)
The names of variables ARGi at call level LEVEL are
returned, as a string array. Note that ARGi are the
actual parameters, not strings containing their names.
ARGi must be parameters that have been passed to the
calling procedure. Variables that are unnamed at the
specified call level will return the empty string.
[IDL v5.0 and above only]
VARS = ROUTINE_NAMES(VARIABLES=LEVEL)
The names of variables at call level LEVEL are returned,
as a string array.
VARS = ROUTINE_NAMES(PROC, /P_VARIABLES, /P_PARAMETERS)
VARS = ROUTINE_NAMES(FUNC, /F_VARIABLES, /F_PARAMETERS)
The names of the variables and parameters, respectively,
defined in compiled procedure PROC, or compiled function
FUNC, are returned as a string array.
VALUE = ROUTINE_NAMES(NAME, FETCH=LEVEL)
The value of the named variable NAME at call level LEVEL
is returned. If the value is undefined, then the
assignment will cause an error. Therefore, the only safe
way to retrieve a value is by using a variant of the
following:
IF N_ELEMENTS(ROUTINE_NAMES(NAME, FETCH=LEVEL)) GT 0 THEN $
VALUE = ROUTINE_NAMES(NAME, FETCH=LEVEL)
DUMMY = ROUTINE_NAMES(NAME, VALUE, STORE=LEVEL)
The value VALUE is stored into the named variable NAME at
call level LEVEL. Note that there is no way to cause the
named variable to become undefined. The value returned
in DUMMY can be ignored.
[IDL v5.2 and earlier: new variables cannot be created]
[IDL v5.3 and later: new variables can be created]
SEE ALSO:
ROUTINE_INFO, ARG_PRESENT, DXDEBUG (Markwardt Debug Library)
MODIFICATION HISTORY:
Written, 20 Jul 2000
Documented differences between IDL versions, 21 Sep 2000, CM
(See /home/drw/idl/secis/routine_names.pro)
ROUTINE_NAMES (DOCUMENTATION ONLY)[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ROUTINE_NAMES (DOCUMENTATION ONLY)
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Examine variables and parameters of procedures and call stack (OBSOLETE)
CALLING SEQUENCE:
Various, see USAGE VARIATIONS.
DESCRIPTION:
ROUTINE_NAMES obtains information about routines, and their
variables and keywords. Using these functions, a subroutine can
interrogate, and in some cases change, the values and names of
variables and parameters in its calling routine, or at the $MAIN$
level. Some functionality of ROUTINE_NAMES is also in the IDL
system function ROUTINE_INFO, and other functionality is exclusive
to ROUTINE_NAMES.
ROUTINE_NAMES has been designated as "OBSOLETE" by RSI, although
it will probably not disappear soon since their own software
appears to use it.
ROUTINE_NAMES can be invoked in several different ways, which are
detailed below, under USAGE VARIATIONS.
ROUTINE_NAMES uses a notion of the current IDL "call level," which
is the numerical stack depth of the currently executing routine.
At each procedure or function call, the call level becomes one
*deeper*, and upon each RETURN, the call level becomes one
*shallower*. The call stack always begins at the $MAIN$ level.
The current call stack can always be printed by executing HELP.
When specifying the call level to ROUTINE_NAMES, one can use one
of two numbering systems, depending on whichever is most
convenient. In the *absolute* numbering system, the $MAIN$ level
starts at number 1, and becomes deeper with increasing numbers.
In the *relative* numbering system, the current (deepest) call
level is number 0, and becomes shallower with more negative
numbers. Hence, if the deepest level is N, then the
correspondence is thus:
VALUE MEANING
--------------------------------
1 or -N+1 $MAIN$ level
2 or -N+2 NEXT deeper level
... ...
N or 0 DEEPEST (currently executing) level
USAGE VARIATIONS:
PROCS = ROUTINE_NAMES( [/UNRESOLVED])
PROCS = ROUTINE_NAMES(/PROCEDURES [,/UNRESOLVED])
FUNCS = ROUTINE_NAMES(/FUNCTIONS [,/UNRESOLVED])
The currently compiled procedures and functions are
returned, respectively, as a string array. Functions
declared via FORWARD_FUNCTION are also returned. If the
UNRESOLVED keyword is set then the currently unresolved
procedures and functions are returned. These are known
routines which have not yet been compiled.
PROCS = ROUTINE_NAMES(/S_PROCEDURES)
FUNCS = ROUTINE_NAMES(/S_FUNCTIONS)
The lists of system procedures and functions is returned,
as a string array.
LEVNUM = ROUTINE_NAMES(/LEVEL)
The call level of the calling routine is returned.
NAMES = ROUTINE_NAMES(ARG0, ARG1, ..., ARGN, ARG_NAME=LEVEL)
The names of variables ARGi at call level LEVEL are
returned, as a string array. Note that ARGi are the
actual parameters, not strings containing their names.
ARGi must be parameters that have been passed to the
calling procedure. Variables that are unnamed at the
specified call level will return the empty string.
[IDL v5.0 and above only]
VARS = ROUTINE_NAMES(VARIABLES=LEVEL)
The names of variables at call level LEVEL are returned,
as a string array.
VARS = ROUTINE_NAMES(PROC, /P_VARIABLES, /P_PARAMETERS)
VARS = ROUTINE_NAMES(FUNC, /F_VARIABLES, /F_PARAMETERS)
The names of the variables and parameters, respectively,
defined in compiled procedure PROC, or compiled function
FUNC, are returned as a string array.
VALUE = ROUTINE_NAMES(NAME, FETCH=LEVEL)
The value of the named variable NAME at call level LEVEL
is returned. If the value is undefined, then the
assignment will cause an error. Therefore, the only safe
way to retrieve a value is by using a variant of the
following:
IF N_ELEMENTS(ROUTINE_NAMES(NAME, FETCH=LEVEL)) GT 0 THEN $
VALUE = ROUTINE_NAMES(NAME, FETCH=LEVEL)
DUMMY = ROUTINE_NAMES(NAME, VALUE, STORE=LEVEL)
The value VALUE is stored into the named variable NAME at
call level LEVEL. Note that there is no way to cause the
named variable to become undefined. The value returned
in DUMMY can be ignored.
[IDL v5.2 and earlier: new variables cannot be created]
[IDL v5.3 and later: new variables can be created]
SEE ALSO:
ROUTINE_INFO, ARG_PRESENT, DXDEBUG (Markwardt Debug Library)
MODIFICATION HISTORY:
Written, 20 Jul 2000
Documented differences between IDL versions, 21 Sep 2000, CM
$Id: routine_names.pro,v 1.2 2001/03/25 18:10:43 craigm Exp $
(See /home/drw/idl/aux/markwardt/routine_names.pro)
ROWCOL
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: rowcol
PURPOSE: compute the plot frame position of next plot
USEAGE: result=rowcol(ix=ix,iy=iy)
INPUT:
KEYWORD INPUT:
ix the x position index starting from 0 on left,
ix<0 indicates rightmost column of plots
iy the y position index starting from 0 on bottom
iy<0 indicates top row of plots
OUTPUT:
result 1 if plot position matches ix or iy position index,
otherwise zero
DISCUSSION:
This routine is intended to simplify labeling setup for multiframe
plots. Use ROWCOL in IF statements to set the XTITLE and YTITLE
as appropriate for plots in the left or right column or bottom or
top row. Since ROWCOL interprets a negative IX or IY as the
rightmost or top row of plots, respectively, you don't need to
explicitly refer to !p.multi in your plot routines when all you
want to do is set a special value of XTITLE for the right column
or top row of plots.
EXAMPLE:
!p.multi=[0,2,3]
; execute these lines four times:
if rowcol(ix=0) then ytitle='ylabel' else ytitle=''
if rowcol(iy=0) then xtitle='xlabel' else xtitle=''
plot,dist(20),xtitle=xtitle,ytitle=ytitle
AUTHOR: Paul Ricchiazzi 09 Apr 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
nov97: now works for column major ordering
(See /home/drw/idl/esrg/rowcol.pro)
RWB
[Previous Routine]
[Next Routine]
[List of Routines]
RWB - load the red, white & blue colour table from my own colour
table file
(See /home/drw/idl/gen/rwb.pro)
SATGRID[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: satgrid
PURPOSE: compute data coordinates of scanning sensors deployed on
polar orbiting satellites
USEAGE: satgrid,nx,ny,alon,alat,lon0=lon0,lat0=lat0,inclin=inclin, $
alt=alt,period=period,lres=lres,sres=sres,dmsp=dmsp, $
descend=descend,time=time
INPUT:
nx number of samples, if nx le 1 then alon and alat
are one dimensional vectors which specify the satellite
ground track.
ny number of lines
KEYWORD INPUT:
lon0 longitude of equator crossing (degrees)
the NOAA polar orbiters cross the equator at the same
local time each day.
For example, if the ascending node crossing occurs at local
time 10:30, or 1.5 hrs before noon, then the longitude offset
from the sub-solar longitude is
lon0=(10.30-12.00)*15=-22.5 degrees
inclin orbital inclination (degrees) (default=98.9127)
0 < inclin < 180
(this is the angle between the north pole and the the
satellite orbital axis. [Use right hand rule to establish
direction of orbital axis.] The default value cooresponds to
to a sun sychronous orbit.
alt altitude of orbit (km) (default=853. km)
period period of orbit (hours) (default=1.6985 hrs)
either alt or period may be specified and the other quantity is
computed through the relation between orbital period and altitude.
if neither parameter is set the indicated defaults are used.
dmsp set to 1 if satellite ground resolution is held constant
in the crosstrack direction, as it is on the DMSP satellite,
lres along track resolution at nadir=0 (km) (default=1.)
sres cross track resolution at nadir=0 (km) (default=1.)
NOTE: SRES is internally limited to less than
.999*2*nadrlim/(nx-1), where nadrlim is the
maximum nadir angle for which the earth is
still in the IFOV of the sensor.
descend if set, choose descending node. This affects the
ordering of the ALON and ALAT grids.
OUTPUT:
alon longitude array
alat latitude array
NOTE: when facing the direction of ground track motion the
first array index of the alat and alon arrays are filled
from left to right.
time time offset at which a given line of data is obtained (hours)
The offset is respect to the time at which the first line
of data is returned.
swath cross track swath width in km
DISCUSSION:
This routine is not intended to give precise satellite coordinates,
rather it can be used to compute illustritive grids to test other
routines. A circular orbit is assumed and the earth is allowed to
rotate during the period of the orbit. In reality, NOAA polar
orbiters have an eccentricity of about 0.0011. This has a very
small impact on inter pixel spacing. The ordering of alat and alon
may need to be transposed, reversed or rotated to account for
satellite direction of motion i.e., ascending / descending node and
for details of how a given satellite orders its output.
LIMITATIONS:
Should not be used to compute satelite ground track or data grids
when high accuracy is required.
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
;; show satellite ground track
map_set,0,-120,/cyl,/cont,/grid
satgrid,0,200,alon,alat,lres=240.
oplot,alon,alat
;; show sensor samples, color indicates array ordering (dark=>start)
loadct,5
color=(!d.n_colors*findgen(100)/100.) # replicate(1,600)
satgrid,100,600,alon,alat,lres=200,sres=16.5.,swath=swath
print,swath
plots,alon,alat,psym=3,color=color
AUTHOR: Paul Ricchiazzi 20 Dec 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/satgrid.pro)
SATGRID[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: satgrid
PURPOSE: compute data coordinates of scanning sensors deployed on
polar orbiting satellites
USEAGE: satgrid,nx,ny,elon,lat0,alon,alat
satgrid,nx,ny,elon,lat0,alon,alat,inclin=inclin,alt=alt,$
lres=lres,sres=sres,descend=descend
INPUT:
nx number of samples, if nx le 1 then alon and alat
are one dimensional vectors which specify the satellite
ground track.
ny number of lines
lat0 latitude of ground station (degrees)
elon longitude of equator crossing (degrees)
the NOAA polar orbiters cross the equator at the same
local time each day. Local time is defined as
tloc = utc - fix(lon+7.5)/15
For example if the ascending node crossing occurs at local
time 14:30, or 2.5 hrs after noon, then in a given day
elon takes on the values,
elon = indgen(24)*15 + 15*2.5
or for a particular longitude
elon = 15*fix(lon+7.5)/15 + 15*2.5
KEYWORD INPUT:
inclin orbital inclination (degrees) (default=98.9127)
0 < inclin < 180
(this is the angle between the north pole and the the
satellite orbital axis. [Use right hand rule to establish
direction of orbital axis.] The default value cooresponds to
to a sun sychronous orbit.
alt altitude (km) (default=853.)
this parameter controls sample resolution for nadir ne 0.
The pixel spacing is computed assuming the sensor nadir angle
increments are constant. This is the case for AVHRR but not
for DMSP. If satellite ground resolution is held constant
in the crosstrack direction, as it is on the DMSP satellite,
set alt=0
lres along track resolution at nadir=0 (km) (default=1.)
sres cross track resolution at nadir=0 (km) (default=1.)
descend if set, choose descending node. This affects the
ordering of the ALON and ALAT grids.
OUTPUT:
alon longitude array
alat latitude array
NOTE: when facing the direction of ground track motion the
first array index of the alat and alon arrays are filled
from left to right.
DISCUSSION:
This routine is not intended to give precise satellite coordinates,
rather it can be used to compute illustritive grids to test other
routines. A circular orbit is assumed. In reality, NOAA polar
orbiters have an eccentricity of about 0.0011. This has a very
small impact on inter pixel spacing. The ordering of alat and alon
may need to be transposed, reversed or rotated to account for
satellite direction of motion i.e., ascending / descending node and
for details of how a given satellite orders its output.
LIMITATIONS:
Should not be used to compute satelite ground track or data grids
when high accuracy is required.
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
;; show satellite ground track
map_set,0,-120,/cyl,/cont,/grid
satgrid,0,200,-125,35,alon,alat,lres=240.
oplot,alon,alat
;; show sensor samples, color indicates array ordering (dark=>start)
loadct,5
color=(!d.n_colors*findgen(100)/100.) # replicate(1,200)
satgrid,100,200,-125,35,alon,alat,lres=220.,sres=2.
plots,alon,alat,psym=3,color=color
satgrid,100,200,-125,35,alon,alat,lres=220.,sres=2.,/descend
plots,alon,alat,psym=3,color=color
AUTHOR: Paul Ricchiazzi 20 Dec 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/satgrid.pro)
SAVEOUT
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: saveout
PURPOSE: save terminal output to a named file
USEAGE: saveout ; start saving from this point (trash any prior stuff)
saveout,file ; copy saved text to file (clean up too)
INPUT:
file name of file to which terminal output is saved
(default = idlsave.txt)
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
This routine is based on IDL's journal facility. Ordinarily, when
the journal command is executed, IDL will pipe any terminal output
to a file named in the journal command (or idlsave.pro, if a
filename is not specified). The text in the journal file consists
of a short identifying header, followed by the records generated
by the idl terminal output. Output lines are prefixed by
semicolons to make them look like IDL comment lines. This isn't
usually what's desired when generating input for other programs.
Therefore, SAVEOUT removes the extraneous header lines, and strips
off the leading semicolon.
In addition, if the name of the text generating routine (tgr) is
on the same line as the initial SAVEOUT call, then the name of the
tgr is also removed from the output. Otherwise it appears in the
first line of the output file. see examples
LIMITATIONS:
uses unix system calls, not easily ported to PC.
COMMON BLOCKS:
SIDE EFFECTS:
creates a journal file
EXAMPLE:
;; list a bunch of numbers but not the routine that produced the numbers:
saveout & print,dist(20)
saveout,'dist_numbers'
saveout & for i=1,10 do print,"hello" & saveout,"hello.txt"
;; in this case the "print,dist(20)" statement will appear in the first line
saveout
print,dist(20)
saveout,'dist_numbers'
;;
AUTHOR: Paul Ricchiazzi 05 Jan 00
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/saveout.pro)
SAVE_DIAG
[Previous Routine]
[Next Routine]
[List of Routines]
SAVE_DIAG, FILENAME [, /DATA, /KEYWORDS, /VARIABLES, /SYMBOLS ]
Read and understand the contents of an IDL SAVE file from IDL.
This is just a toy program at the moment, meant to show that SAVE
files can be read and picked apart programmatically. It's not
fully documented since it's just a prototype. However, with the
concepts here, and what we know now about ROUTINE_NAMES(), a
full-on clone to SAVE and RESTORE could be developed.
This program understands and prints IDL variables, but also saved
procedures and functions.
It will crash on structure types.
FILENAME - name of IDL save file. IDL 4 and 5 files are
recognized. Probably not compressed though.
DATA - set this keyword to print (a sample of) the saved data
values.
KEYWORDS - set this keyword to print the keyword arguements to
saved procedures or functions
VARIABLES - set this keyword to print the variables of saved
procedures or functions
SYMBOLS - set this keyword to print the symbol table of saved
procedures or functions
(See /home/drw/idl/esrg/save_diag.pro)
SCALE_VECTOR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SCALE_VECTOR
PURPOSE:
This is a utility routine to scale the points of a vector
(or an array) into a given data range. The minimum value of
the vector (or array) is set equal to the minimum data range. And
the maximum value of the vector (or array) is set equal to the
maximum data range.
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:
Utilities
CALLING SEQUENCE:
scaledVector = SCALE_VECTOR(vector, minRange, maxRange)
INPUT POSITIONAL PARAMETERS:
vector: The vector (or array) to be scaled.
minRange: The minimum value of the scaled vector. Set to 0 by default.
maxRange: The maximum value of the scaled vector. Set to 1 by default.
INPUT KEYWORD PARAMETERS:
MAXVALUE: Any value in the input vector greater than this value is
set to this value before scaling.
MINVALUE: Any value in the input vector less than this value is
set to this value before scaling.
NAN: Set this keyword to enable not-a-number checking. NANs
in vector will be ignored.
RETURN VALUE:
scaledVector: The vector (or array) values scaled into the data range.
This is always at least a FLOAT value.
COMMON BLOCKS:
None.
EXAMPLE:
x = [3, 5, 0, 10]
xscaled = SCALE_VECTOR(x, -50, 50)
Print, xscaled
-20.0000 0.000000 -50.0000 50.0000
MODIFICATION HISTORY:
Written by: David Fanning, 12 Dec 1998.
Added MAXVALUE and MINVALUE keywords. 5 Dec 1999. DWF.
Added NAN keyword at request of Ben Tupper. 18 Sept 2000. DWF.
(See /home/drw/idl/aux/scale_vector.pro)
SCONVOL
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: sconvol
PURPOSE: convolve a spectrum defined on an arbitrary 1-d grid
with a response function.
USEAGE: sconvol,x,y,fwhm,xx,yy,type=type,isample=isample,osample=osample
INPUT:
x
x value
y
function values y(x)
fwhm
filter width at half of maximum value in x units
KEYWORD INPUT:
type
filter type
0 = square (default)
1 = triangular
2 = gausian
isample
number of pre-convolution samples taken within a given fwhm interval
(default = 11) should be an odd integer
osample
number of output samples provided within a given fwhm interval
(default = 1)
OUTPUT:
xx
x values at sample points, output values will be at multiples of
of OSAMPLE*FWHM starting at min(XX)+.5*FWHM
yy
response values at xx
DISCUSSION:
EXAMPLE: degrade MODTRAN spectral transmission to LOWTRAN resolution
;;
modtrns,buf,/noplot
w=reform(buf(0,*))
t=w & t(*)=1.
for i=1,11 do t=t*reform(buf(i,*))
sconvol,w,t,20,ww,tt,type=0
plot,10000./ww,tt,xrange=[.25,1]
;; show oxygen A line at 1 nm resolution
sconvol,10000/w,t,.001,w1,t1,osample=11
plot,10000/w,t,xrange=[.755,.77]
oplot,w1,t1,psym=10
;; show oxygen A line at 1.4nm resolution degraded with a gaussian filter
sconvol,10000/w,t,.0014,w1,t1,type=2,osample=11
plot,10000/w,t,xrange=[.755,.77]
oplot,w1,t1
;; and at 20 cm-1 resolution
sconvol,w,t,20,w20,t20
plot,10000./w,t,xrange=[.755,.77]
oplot,10000./w20,t20,psym=10
;;
AUTHOR: Paul Ricchiazzi 20 Nov 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/sconvol.pro)
SEC2UTC
[Previous Routine]
[Next Routine]
[List of Routines]
SECIS2UTC,ut_times,nframes=nframes,expo=0.022541,delay=0.0031,ut_date='2001-06-21',ut_base=[13,09,19.300],$
ut_sec_offset=-3.0,zed='z',step=step
(See /home/drw/idl/secis2/sec2utc.pro)
SECIS2UTC
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
SECIS 2001 (Zambia)
NAME:
SECIS2UTC
PURPOSE:
To enable the time-stamping of individual SECIS frames in each
channel. The system relies on accurate ephemeris data (e.g. Espenak)
and includes the facility for an estimate of how early (-ve) or late
(+ve) the initiation of recording was with respect to the beginning
of totality (this is implemented by using the offset keyword expressed
in units of seconds). The time is returned in CCSDS format, although
strictly speaking the ZED keyword should be set to 'Z' for it to be
ISO-8601 compliant. The time of 2nd contact should be entered as a
three-element floating point vector called UT_BASE, and in the form
[HOUR,MINUTE,SECONDS], with the seconds entered to millisecond accuracy.
CALLING SEQUENCE:
secis2utc,UT_TIMES,firstframe=firstframe,nframes=nframes,expo=expo,$
delay=delay,UT_DATE=UT_DATE,UT_BASE=UT_BASE,$
UT_SEC_OFFSET=UT_SEC_OFFSET,zed=zed,step=step
EXAMPLE:
SECIS2UTC,ut_times,firstframe=1000,nframes=12,expo=0.022541,delay=0.0031,$
ut_date='2001-06-21',ut_base=[13,09,19.300],$
ut_sec_offset=-3.0,zed='Z',step=10
HISTORY:
v1.0 - drw@qub.ac.uk in September 2001 for use with higher-level routines.
- scant documentation added by DRW (now drw@mssl.ucl.ac.uk) (8-Jul-2002).
(See /home/drw/idl/secis2/secis2utc.pro)
SECIS_BASIC
[Previous Routine]
[Next Routine]
[List of Routines]
want to write a widget-driven analysis tool for the SECIS
2001 data. This is going to be quite shaky to begin with.
DRW - 15-Aug-2001
(See /home/drw/idl/secis2/secis_basic.pro)
SECIS_STABILISE
[Previous Routine]
[Next Routine]
[List of Routines]
call correl_comp,prom,xmotion,ymotion
i.e. make it nested
(See /home/drw/idl/secis/secis_stabilise.pro)
SECIS_WAVETEST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: SECIS_WAVETEST
PURPOSE: Example IDL program for WAVELET, using NINO3 SST dataset
edited by D. Williams.
EXECUTION:
IDL> .run secis_wavetest
See "http://paos.colorado.edu/research/wavelets/"
Written January 1998 by C. Torrence
(See /home/drw/idl/secis/wavelet/secis_wavetest.pro)
SEC_GET_DISP.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sec_get_disp.pro
PURPOSE:
To remove the shaking from a sequence of digital
images in the form of a 50x40xN floating point
array.
USAGE:
sec_move,data,disparr
INPUTS:
DATA - the input array
OUTPUTS:
DATAOUT - the stabilised sequence
DISPARR - the 2xN array containing the
displacement co-ordinates relative to
DATA(*,*,0).
HISTORY:
D. Williams, QUB.
(See /home/drw/idl/secis/sec_get_disp.pro)
SEC_MOVE.PRO[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sec_move.pro
PURPOSE:
To remove the shaking from a sequence of digital
images in the form of a XxYxN floating point
array.
USAGE:
sec_move,data,dataout,disparr[,/nomove]
INPUTS:
DATA - the input array
OUTPUTS:
DATAOUT - the stabilised sequence
DISPARR - the 2xN array containing the
displacement co-ordinates relative to
DATA(*,*,0).
KEYWORDS:
NOMOVE - if set, then do not move the images,
just produce the displacement array DISPARR.
HISTORY:
D. Williams, QUB.
(See /home/drw/idl/secis/sec_move.pro)
SEC_MOVE.PRO[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sec_move.pro
PURPOSE:
To remove the shaking from a sequence of digital
images in the form of a 50x40xN floating point
array.
USAGE:
sec_move,data,dataout,disparr[,/nomove]
INPUTS:
DATA - the input array
OUTPUTS:
DATAOUT - the stabilised sequence
DISPARR - the 2xN array containing the
displacement co-ordinates relative to
DATA(*,*,0).
KEYWORDS:
NOMOVE - if set, then do not move the images,
just produce the displacement array DISPARR.
HISTORY:
D. Williams, QUB.
(See /home/drw/idl/secis/sec_movezero.pro)
SEC_MOVE2.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sec_move2.pro
PURPOSE:
To remove the shaking from a sequence of digital
images in the form of a XxYxN floating point
array.
USAGE:
sec_move2,data,dataout,disparr[,/nomove]
INPUTS:
DATA - the input array
OUTPUTS:
DATAOUT - the stabilised sequence
DISPARR - the 2xN array containing the
displacement co-ordinates relative to
DATA(*,*,0).
KEYWORDS:
NOMOVE - if set, then do not move the images,
just produce the displacement array DISPARR.
HISTORY:
D. Williams, QUB.
SEC_MOVE2 is a modification of SEC_MOVE
designed to take out the problem of wraparound
in the gradient image, which may have caused
flaws in the output displacement vectors.
(See /home/drw/idl/secis/sec_move2.pro)
SEC_MOVE3.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sec_move3.pro
PURPOSE:
To remove the shaking from a sequence of digital
images in the form of a XxYxN floating point
array.
USAGE:
sec_move3,data,dataout,disparr[,/nomove]
INPUTS:
DATA - the input array
OUTPUTS:
DATAOUT - the stabilised sequence
DISPARR - the 2xN array containing the
displacement co-ordinates relative to
DATA(*,*,0).
KEYWORDS:
NOMOVE - if set, then do not move the images,
just produce the displacement array DISPARR.
HISTORY:
D. Williams, QUB.
SEC_MOVE3 is a test version of SEC_MOVE
which doesn't use the gradient, only the
raw image to determine the displacement.
Reason - stabilisation to the Moon's limb.
(See /home/drw/idl/secis/sec_move3.pro)
SELECT_OBJECTS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SELECT_OBJECTS
PURPOSE:
The purpose of this program is to demonstrate how to select
and move objects in an object graphics window. Once the objects
appear in the window, use your mouse to select the objects and
move them in the window. The window is resizeable.
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:
Object Graphics.
CALLING SEQUENCE:
SELECT_OBJECTS
REQUIRED INPUTS:
None.
KEYWORD PARAMETERS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Requires VCOLORBAR from the Coyote Library:
http://www.dfanning.com/programs/vcolorbar__define.pro.
EXAMPLE:
Select_Objects
MODIFICATION HISTORY:
Written by David Fanning, 21 September 98.
Added the ability to shrink and expand the objects. 27 Sept 98. DWF.
(See /home/drw/idl/aux/select_objects.pro)
SELECT_REGION[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: select_region
PURPOSE: This procedure allows the user to select a region in an
intensity image (INT_DIST) using box cursor. The corresponding
region in both the velocity map and line width map are then
extracted and the 3 regions are then displayed and saved.
USEAGE: select_region,image1, image2, image3, region1, region2, region3
INPUT:
image1 intensity map
image2 velocity map
image3 line width map
OUTPUT:
region1 selected intensity region
region2 " velocity "
region3 " line width "
AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/select_region.pro)
SELECT_REGION[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: select_region
PURPOSE: This procedure allows the user to select a region in an
intensity image (INT_DIST) using box cursor. The corresponding
region in both the velocity map and line width map are then
extracted and the 3 regions are then displayed and saved.
USEAGE: select_region,image1, image2, image3, region1, region2, region3
INPUT:
image1 intensity map
image2 velocity map
image3 line width map
OUTPUT:
region1 selected intensity region
region2 " velocity "
region3 " line width "
AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/ptg/select_region.pro)
SERTSFIT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SERTSFIT
PURPOSE:
To fit a SERTS-89 Active Region spectrum, but it's generic enough to
be adapted to any spectral line fit.
USAGE:
sertsfit,lambda,flux,wavemin=wavemin,wavemax=wavemax,$
wavefit,specfit,centrz,widtz,ampz,linflux,errs=errs,$
nobgdsub=nobgdsub
INPUTS:
LAMBDA - the input wavelength array
FLUX - the input spectral flux corresponding to WAVE
REQUIRED INPUT KEYWORDS:
WAVEMIN - the minimum of the wavelength range you want to study
WAVEMAX - the maximum of the range to be studied
OPTIONAL INPUT KEYWORDS:
ERRS - an array of errors in the spectrum for plotting
NOBGDSUB - switch to say "don't subtract the background level"
otherwise, it will be substracted (the default), which is
more useful for line intensity diagnostics.
OUTPUTS:
SPECFIT - the values of the fit to the spectral lines
WAVEFIT - the wavelengths corresponding to SPECFIT
HISTORY:
Dave Williams (DRW) @ MSSL/UCL (May 2002)
(See /home/drw/idl/other.stuff/sertsfit.pro)
SETFITPARM.PRO[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SetFitParm.pro
AUTHOR:
F.Bringezu, denet - Internetservice, Halle Germany,
bringezu@denet.de
PURPOSE:
Provide a widget interface for creating a parinfo structure.
This parinfo structure can by used by mpfit routines of Craig B. Markwardt.
MAJOR TOPICS:
Widget, mpfit.
CALLING SEQUENCE:
parinfo=SetFitParm(used_parinfo)
DESCRIPTION:
SetFitParm creates PARINFO using a widget interface.
PARINFO provides constraints for paramters used by the mpfit routines.
PARINFO is an array of structures, one for each parameter.
A detailed description can be found in the documentation of mpcurvefit.pro
This routine creates an array that contains a structure for each element.
The structure has the following entries.
- VALUE (DOUBLE): The starting parameter
- FIXED (BOOLEAN): 1 fix the parameter, 0 don't fix it at the
point given in VALUE.
- LIMITS (DBLARRAY(2)): Set upper and lower limit.
- LIMITED (BOOLEAN ARRAY 2): Fix the limit.
The parameter OLDPARINFO is optional. OLDPARINFO is used to set
the default values in the widget.
You can simply run:
test=SetFitParm() to create the array for the first time.
Once the array is created it can be used to set the default values
in the widget by calling
test2=SetFitParm(test)
INPUTS:
OPTIONAL INPUTS:
OLDFITPARM - The default values of the new array
INPUT KEYWORD PARAMETERS:
PARENT - if this widget is to be a child, set this keyword to the
parent widget ID.
OUTPUT KEYWORD PARAMETERS:
CANCEL - if the user selected the cancel button on the SETFITPARM
widget, then this keyword will be set upon exit.
OUTPUTS:
PARINFO array of structures
SEE ALSO:
mpcurvefit
MODIFICATION HISTORY:
Written, FB, 12/1999
Documented, FB, Jan 2000
Generalized positioning code, CM 01 Feb 2000
(See /home/drw/idl/aux/markwardt/setfitparm.pro)
SETFITPARM.PRO[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SetFitParm.pro
AUTHOR:
F.Bringezu, denet - Internetservice, Halle Germany,
bringezu@denet.de
PURPOSE:
Provide a widget interface for creating a parinfo structure.
This parinfo structure can by used by mpfit routines of Craig B. Markwardt.
MAJOR TOPICS:
Widget, mpfit.
CALLING SEQUENCE:
parinfo=SetFitParm(used_parinfo)
DESCRIPTION:
SetFitParm creates PARINFO using a widget interface.
PARINFO provides constraints for paramters used by the mpfit routines.
PARINFO is an array of structures, one for each parameter.
A detailed description can be found in the documentation of mpcurvefit.pro
This routine creates an array that contains a structure for each element.
The structure has the following entries.
- VALUE (DOUBLE): The starting parameter
- FIXED (BOOLEAN): 1 fix the parameter, 0 don't fix it at the
point given in VALUE.
- LIMITS (DBLARRAY(2)): Set upper and lower limit.
- LIMITED (BOOLEAN ARRAY 2): Fix the limit.
The parameter OLDPARINFO is optional. OLDPARINFO is used to set
the default values in the widget.
You can simply run:
test=SetFitParm() to create the array for the first time.
Once the array is created it can be used to set the default values
in the widget by calling
test2=SetFitParm(test)
INPUTS:
OPTIONAL INPUTS:
OLDFITPARM - The default values of the new array
INPUT KEYWORD PARAMETERS:
PARENT - if this widget is to be a child, set this keyword to the
parent widget ID.
OUTPUT KEYWORD PARAMETERS:
CANCEL - if the user selected the cancel button on the SETFITPARM
widget, then this keyword will be set upon exit.
OUTPUTS:
PARINFO array of structures
SEE ALSO:
mpcurvefit
MODIFICATION HISTORY:
Written, FB, 12/1999
Documented, FB, Jan 2000
Generalized positioning code, CM 01 Feb 2000
(See /home/drw/idl/aux/oldmarkwardt/setfitparm.pro)
SET_CHARSIZE
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: set_charsize
PURPOSE: set default charactersize
USEAGE: set_charsize,charsize
INPUT: charsize
DISCUSSION:
This Routine sets the default character size to a fraction
of the screen width so that 128 characters will fit across
the entire screen. The number 128 was chosen because
that's how many standard size characters (!p.charsize=1)
fit across an 8.5 inch x-window. This routine can be used
inside scripts intended for either X or PS output, and
should make it easier to produce acceptable PS output
based on X-window previews.
NOTE: To take full advantage of this routine all character
size specifications should be multiples of
!p.charsize. This means all calls to routines that
have charsize as an keyword argument (e.g., XYOUTS
and PLOT) should have the size specified as,
CHARSIZE=chs*!p.charsize.
The character size argument in the PUTSTR routine,
(which is similar to the XYOUTS routine), is already a
character size multiplier and does not need to be
multiplied by !p.charsize.
SIDE EFFECTS:
sets the global variable !p.charsize to charsize*fac
where fac=float(!d.x_vsize)/(128*!d.x_ch_size)
AUTHOR: Paul Ricchiazzi 03 May 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/set_charsize.pro)
SF
[Previous Routine]
[Next Routine]
[List of Routines]
Print the current frame number and visible window ID, and optionally
switch to a specified frame number.
USAGE: SF
OPTIONAL ARGUMENTS:
FRAME Frame number to switch to
OPTIONAL KEYWORDS:
/QUIET Do not print any information (default=print)
/HELP Print help information only (default=do not print)
USAGE NOTES:
(1) FSET must have been executed previously to create frame buffers.
(2) Use the LF (loop frames) command for looping.
AUTHOR: Liam Gumley, CIMSS/SSEC, 15-APR-1996 (liam.gumley@ssec.wisc.edu)
10-MAY-1996 Fixed problem when size of non-scrolling window
was changed.
27-AUG-1996 Color table for visible frame is now loaded before image.
19-SEP-1997 Added !MAP to state variables.
RELATED COMMANDS:
FSET Set up frames in memory
AF Advance one frame
BF Backup one frame
LF Loop frames
EXAMPLE:
; Create two frames with a graphic in each, and switch between them.
; (Note that the LF command is designed for looping frames.)
FSET,FRAMES=2,XSIZE=512,YSIZE=512
A=DIST(64)
SF,0
TVSCL,REBIN(A,512,512) & LOADCT,39
SF,1
SHOW3,A & LOADCT,39
FRAME=0
PRINT,"HIT Q TO QUIT, ANY OTHER KEY TO SWITCH FRAMES"
WHILE GET_KBRD(1) NE "Q" DO BEGIN & SF,FRAME & FRAME=FRAME XOR 1 & ENDWHILE
(See /home/drw/idl/aux/sf.pro)
SHADOW
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: shadow,g,sza,drad
PURPOSE: Compute and print fraction of total diffuse irradiance
which is contained within a solid angle subtended by a
small disk centered on the sun's disk and subtending a
given half angle. Multiple scattering effects are not
included Output for Henyey-Greenstein and Rayleigh phase
function.
USEAGE: shadow,g,sza,drad
INPUT:
g asymmetry factor used in Henyey-Greenstein phase function
sza solar zenith angle (degrees)
drad half angle of shading disk in radians
keyword input:
type type of scatterer, accepted values of type
"henyey-greenstein" (default)
"rayleigh"
OUTPUT:
none
PRINT OUT:
three quantities:
1) the ratio of upwelling to downwelling diffuse irradiance
note that the up_diffuse + down_diffuse = direct*tau
where tau is the optical depth (tau << 1).
2) the fraction of downwelling diffuse irradiance obscured
by shading disk.
3) the fraction of total diffuse radiance obscured by disk
EXAMPLE: compute fraction of all single scattered radiation
within a disk which subtends one degree of the of
the forward direction.
drad=5.75*!dtor ; NIP FOV used to get direct beam
shadow & for g=.5,.91,.1 do for sz=0,81,15 do shadow,g,sz,drad
drad=5*2.25/20. ; shaded PSP used to get diffuse
shadow & for g=.5,.91,.1 do for sz=0,81,15 do shadow,g,sz,drad
AUTHOR: Paul Ricchiazzi 22 Apr 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/shadow.pro)
SHARPFOCUS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
sharpfocus
PURPOSE:
To
HISTORY:
Written 6-Apr-94 by M.Morrison (using Zayer routine as start)
26-Apr-94 (MDM) - Added /ISS option
(See /home/drw/idl/bin/sharpfocus2.pro)
SHIFT_BACK
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
SECIS 2001
NAME:
SHIFT_BACK
PURPOSE:
To move displaced images back to a common reference frame,
the latter being determined using Pawel's X,Y,R tests:
Moon_position_brd_cam_step1_YH.pro
Moon_position_brd_cam_step2_rfix_YH.pro
Moon_position_brd_cam_step3_corr2d_YH.pro
Moon_position_brd_cam_step4_finalshift_YH.pro.
These all work on the high-SNR white-light images.
CALLING SEQUENCE:
shift_back, inpath, outpath, initio, terminus, $
dx, dy, prepend=prepend
INPUTS:
INPATH - absolute path to the images to be shifted
OUTPATH - absolute path to which the shifted images should be
written
INITIO - number of the first frame to be shifted
TERMINUS - number of the last frame to be shifted
DX - vector of all 8000 X displacements from the desired position
DY - likewise for Y
INPUT KEYWORDS:
FLATF - flat-field image to use
DARK - dark-current image to use
*OR*
NOCALIB - set this to skip the calibration of the images (NOT
RECOMMENDED!)
EXAMPLE:
shift_back,'/disk/solar2/drw/secis2/e01b',$
'/disk/solar2/drw/secis2/work/shifted/e01b.1/',1000,1099,$
dx,dy,prepend='e01b',flatf=medianflat,dark=mediandark
HISTORY:
v1.0: David Williams @ MSSL - 15/07/02
Based on the code for SECIS'99: MOVE_IT_BACK2. Modified
to write out individual FITS images rather than store
bulky IDL SAV-format cubes.
(See /home/drw/idl/secis2/shift_back.pro)
SHIFT_SUB
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: SHIFT_SUB
PURPOSE:
Shift an image with subpixel accuracies
CALLING SEQUENCE:
Result = shift_sub(image, x0, y0)
(See /home/drw/idl/jma/shift_sub.pro)
SHOWDETECTOR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SHOWDETECTOR
PURPOSE:
This procedure writes a FUSE detector image to a PostScript file,
along with file information such as date acquired, number of counts,
etc.
CATEGORY:
Detector, Plotting.
CALLING SEQUENCE:
SHOWDETECTOR, Infile
INPUTS:
Infile: Filename of the histogram or photon list file to be plotted.
RESTRICTIONS:
The IDLPS environment variable should be set to the directory to which
the PostScript file will be written. If it does not exist, the
file will be written to the current directory.
If the image to print is large, this program may require a
substantial amount of memory.
KEYWORD PARAMETERS:
SICLABEL:A two column file containing labels for the plot. The
first column is the label, and the second is the wavelength.
These labels are placed below the image.
LIFLABEL:Same as SICLABEL, but placed above the image.
SICSPEC:Spectrum to label ('LWRS','MDRS','HIRS') for the SiC spectrum.
If included, the lines from the labels will be extended to the
approximate y position of this spectrum.
LIFSPEC:Same as SICSPEC, but for the LiF labels
BINTO: A two element vector describing the approximate final [x,y]
size of the image. Default is [4096,256]. Because the binning
is the same in x and Y, the final result may not be exactly
what was specified.
PAGESIZE:
A two element vector describing the [x,y] page size.
The Default is [8.5,11]
NUMIMAGES:
Number of of pieces to break the image into in x. Default
is 4.
LANDSCAPE:
Set if plot should be in landscape mode. This is the
default, except for 8.5 x 11.
EXPOSE: If set, adjust the color scale so that the maximum color
is set to include 98% of all pixels (excluding pixels with
no counts), i.e. the very brightest
pixels will be overexposed.
OVEREXPOSE:
If set, adjust the color scale so that the maximum color
is set to 15, so that any pixels brighter than 15 are
overexposed.
NOSAVE: If set, don't save the .XDR file. This speeds things up.
COLOR: If set, use color PostScript with the current screen palette.
PAGENUM:If set, print on NUMIMAGES pages rather than all on one page,
and only page PAGENUM is printed. Note that the first page
has PAGENUM = 0.
INPUTDATA:
If this keyword is set equal to an array containing
2D data (such as that created by READIT), this data is used
instead of reading Infile. This can be used to save time
by reading the data once, and then plotting multiple times.
Note that Infile is still used in the title of the plot,
and the header information will not be printed on the plot.
MINC: If set, uses this value as the minimum of the color scale.
MAXC: If set, uses this value as the maximum of the color scale.
OVEREXPOSE will override this keyword.
The following are passed directly to READIT:
PSFILE: If set to a filename, output goes to this file rather than
the default file $IDLPS/idl.ps.
TRANGE: A two element vector containing the start and ending
times to include in the array.
XRANGE: A two element vector containing the range of x to include
in the array.
YRANGE: A two element vector containing the range of y to include
in the array.
PRANGE: A two element vector containing the range of pulse height
to include in the array.
SCALE: Scale factor for array. Can be set to make the resultant
array a reasonable size. A scale size of n bins the
image n x n.
OUTPUTS:
SIDE EFFECTS:
A PostScript file is generated. If PSFILE is defined, it will be the
name of the file. Otherwise, it will be $IDLPS/idl.ps.
EXAMPLE:
For any of the examples, choose a file to print, for example:
INFILE = '$UCBDATA/Detectors/Flight/FL02/116char4/1A-HDSiCLiF-16'
To print a thumbnail image of a detector image binned to
8192x512 on 8.5x11 paper with all pixels containing more
then 15 counts set to black, enter:
SHOWDETECTOR,INFILE,binto=[8192,512],/OVEREXPOSE,/NOSAVE
To print a full size image in four parts on a single 36x36
plotter page with the top 2% brightest pixels truncated, use:
SHOWDETECTOR,INFILE,BINTO=[16384,1024],PAGESIZE=[36,36],/LANDSCAPE,
/EXPOSE,/NOSAVE
$nawk -f ~/utility/36x36la.awk $IDLPS/idl.ps > $IDLPS/plotter.ps
To print a single full size image on a 288x36 plotter page with the
top 2% brightest pixels truncated and with labels every angstrom
at the location of the SiC MDRS, use:
LLIST = '/home/kix/sahnow/linelists/Angstromlist.dat'
SHOWDETECTOR,INFILE,BINTO=[16384,1024],PAGESIZE=[36,288],/LANDSCAPE,
/EXPOSE,/NOSAVE,NUMIMAGES=1,SICLABEL=LLIST,SICSPEC='MDRS'
$nawk -f ~/utility/288x36la.awk $IDLPS/idl.ps > $IDLPS/plotter.ps
MODIFICATION HISTORY:
Written by David Sahnow, 7 November 1997.
10 November 1997 Added NOSAVE keyword
11 November 1997 Modified to change to/from PS device.
1 December 1997 Added COLOR keyword.
17 July 1998 Removed $SCRATCH in save line.
14 November 1998 Add PAGE keyword. Swapped pagesize if necessary.
20 November 1998 Replaced call to INTEGRAL with DSINTEGRAL.
7 February 1999 Added PSFILE keyword.
5 March 1999 Fixed error with EXPOSE keyword when binning.
21 August 1999 Added _extra keyword to use extra readit keywords.
22 August 1999 Added INPUTDATA keyword.
30 January 2000 Added EXPAND keyword in call to readit to rescale
histogram data back to full size.
2 March 2000 Modified output filename so not defining IDLPS doesn't
cause the program to crash.
30 May 2000 Added MINC, MAXC keywords.
6 September 2000 Removed titles on x and y axes.
12 October 2000 Added SICLABEL, LIFLABEL keywords.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/showdetector.pro)
SHOWFHEADER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SHOWFHEADER
PURPOSE:
This program puts a legend on a 2D image showing data from
the image's FITS header.
CATEGORY:
Image display.
CALLING SEQUENCE:
SHOWFHEADER, X, Y, Fitsheader, Image
INPUTS:
X: Normalized X position of FITS header data on plot.
Y: Normalized Y position of FITS header data on plot.
Fitsheader:
The FITS header of the file, which contains data on
the data (or simulated data) in the image.
Image: The 2D image
KEYWORDS:
CHARSIZE:
Character size of label. Default is 1.0.
NOCOUNTS:
If set, don't display the number of counts.
NOINTTIME:
If set, don't display the integration time.
NOSEGMENT:
If set, don't display the segment name.
PROCEDURE:
EXAMPLE:
MODIFICATION HISTORY:
Written by David Sahnow, 18 June 1997.
4 December 1997 Forced total counts to not be in scientific notation.
8 March 1999 Modified to work with OPUS files.
20 September 1999 Added CHARSIZE, NOCOUNTS, NOINTTIME and
NOSEGMENT keywords.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/showfheader.pro)
SHOWFHEADER2
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SHOWFHEADER2
PURPOSE:
This program puts a legend on a 2D image showing data from
the image's FITS header.
CATEGORY:
Image display.
CALLING SEQUENCE:
SHOWFHEADER2, X, Y, Fitsheader, Image
INPUTS:
X: Normalized X position of FITS header data on plot.
Y: Normalized Y position of FITS header data on plot.
Fitsheader:
The FITS header of the file, which contains data on
the data (or simulated data) in the image.
Image: The 2D image
KEYWORDS:
CHARSIZE:
Character size of label. Default is 1.0.
NOCOUNTS:
If set, don't display the number of counts.
NOINTTIME:
If set, don't display the integration time.
NOSEGMENT:
If set, don't display the segment name.
PROCEDURE:
EXAMPLE:
MODIFICATION HISTORY:
Written by David Sahnow as SHOWFHEADER, 18 June 1997.
4 December 1997 Forced total counts to not be in scientific notation.
8 March 1999 Modified to work with OPUS files.
20 September 1999 Added CHARSIZE, NOCOUNTS, NOINTTIME and
NOSEGMENT keywords.
30 May 2000 Renamed to SHOWFHEADER2. Modified to properly accommodate
!p.multi plots.
16 August 2000 Added '>1' to !p.multi in PLOTIT to avoid divide
by zero when !p.multi = 0.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/showfheader2.pro)
SHOWPROGRESS__DEFINE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SHOWPROGRESS__DEFINE
PURPOSE:
An object for creating a progress bar.
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:
Utilities
CALLING SEQUENCE:
progressBar = Obj_New("SHOWPROGRESS")
INPUTS:
parent: A widget identifier of the widget that will be the
group leader for this program. It is *required* for modal
operation. If missing, you are on your own. :-(
KEYWORDS:
CANCELBUTTON: Set this keyword if a Cancel button is desired.
DELAY: The total time the widget should be on the display in AutoUpDate
mode. The keyword applies only to AutoUpDate mode. Default is 5 seconds.
STEPS: The number of steps to take in AutoUpDate mode. The keyword applies only
to AutoUpDate mode.
MESSAGE: The text of the label above the progress bar. Default is "Operation
in Progress...".
TITLE: ; The text of the top-level base title bar. Default is ""
COLOR: The color to draw the progress bar.
XSIZE: The XSize of the progress bar in Device coordinates. Default is 150.
YSIZE: The YSize of the progress bar in Device coordinates. Default is 10.
AUTOUPDATE: Set this keyword to be in AutoUpDate mode.
PROCEDURE:
There are two modes. In AutoUpDate mode, a delay and number of steps is
required. The modal widget stays on the display until the total time
exceeds the DELAY or the requested number of steps is taken. A TIMER
widget is used to generate update events. Nothing can be going on
concurrently in AutoUpDate mode. To enter AutoUpDate mode, type this:
progressBar = Obj_New("SHOWPROGRESS", /AutoUpDate, Delay=2, Steps=10)
progressBar->Start
Obj_Destroy, progressBar
The program will update and destroy itself automatically. (The object
itself is not destroyed. You must do this explicitly, as in the example
above.)
In normal mode, the user is responsible for starting, updating, and
destroying the progress indicator. The sequence of commands might look
like this:
progressBar = Obj_New("SHOWPROGRESS")
progressBar->Start
FOR j=0,9 DO BEGIN
Wait, 0.5 ; Would probably be doing something ELSE here!
progressBar->Update, (j+1)*10
ENDFOR
progressBar->Destroy
Obj_Destroy, progressBar
Normal mode gives you the opportunity to update the Progress Bar
in a loop while something else is going on. See the example program
at the end of this file.
Note that the object itself is not destroyed when calling the DESTROY
method. You must explicitly destroy the object, as in the example above.
METHODS:
CHECKCANCEL: This function method returns a 1 if the user has clicked
the CANCEL button. Otherwise, it returns a 0.
cancelled = progressBar->CheckCancel()
IF cancelled THEN progressBar->Destroy
DESTROY: Destroys the ShowProgress widgets. It does NOT destroy the object.
progressBar->Destroy
GETPROPERTY: Gets the properties that can be set in the INIT method, including
the parent widget ID.
progressBar->GetProperty, Steps=currentNSteps, Delay=currentDelay
SETCOLOR: Changes the color of the progress bar.
progressBar->SetColor, !P.Color
SETLABEL: Changes the text on the widget label.
progressBar->SetLabel, 'This text instead'
SETPROPERTY: Allows the user to set the INIT parameter via keywords.
progressBar->SetProperty, Color=244, XSize=200, Message='Please Wait...'
START: Puts the ShowProgress bar on the display. In AutoUpDate mode, the
widget starts to automatically update.
progressBar->Start
UPDATE: Updates the progress bar. Requires on argument, a number between 0
and 100 that indicates the percent of progress bar that should be filled
with a color.
progressBar->Update, 50
EXAMPLE:
See the example program at the bottom of this file.
RESTRICTIONS:
In contradiction to the IDL documentation, making the parent widget
insensitive in normal mode does NOT prevent the parent widgets from
receiving events on my Windows NT 4.0, SP 4 system running IDL 5.2,
IDL 5.2.1, or IDL 5.3 (beta).
Note that if you specify a CANCEL button the Show Progress program CANNOT
run as a MODAL widget program. Thus, user *may* be able to generate events
in the calling program while this program is running.
MODIFICATION HISTORY:
Written by: David Fanning, 26 July 1999.
Added code so that the current graphics window doesn't change. 1 September 1999. DWF.
Added yet more code for the same purpose. 3 September 1999. DWF.
Added a CANCEL button and made other minor modifications. 12 Oct 1999. DWF.
(See /home/drw/idl/aux/showprogress__define.pro)
SHOWTEX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SHOWTEX
PURPOSE:
Display TeX sequence translation table on current graphics device.
CATEGORY:
text/strings
CALLING SEQUENCE:
showtex
INPUTS:
KEYWORD PARAMETERS:
/HELP -- print out info on use of the function
and exit.
FONT -- Set to 0 to use hardware font, -1 to use vector.
Note that the only hardware font supported is
Postscript
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
Plot is created.
NOTES:
Hardware fonts are supported only for device PS (PostScript)
EXAMPLE:
MODIFICATION HISTORY:
$Id: showtex.pro,v 1.3 1996/06/14 20:00:27 mcraig Exp $
$Log: showtex.pro,v $
Revision 1.3 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.2 1996/05/09 00:22:17 mcraig
Added error handling and updated built in help.
Revision 1.1 1996/02/08 18:55:12 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/showtex.pro)
SHOW_POPS[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: SHOW_POPS
PURPOSE:
To display populations of significant levels in a CHIANTI ion
model
CATEGORY:
Scientific analysis
EXPLANATION:
Displays percentage level populations and level IDs for all levels
in the specified ion with populations greater than 0.01%. If the
temperature is not specified, then it is taken to be where the
maximum of the ionisation fraction is.
CALLING SEQUENCE:
SHOW_POPS, IZ, ION, DENS, [TEMP=TEMP, N_LEVELS=N_LEVELS, DIL=DIL]
EXAMPLES:
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
DENS: Logarithm of electron density
OPTIONAL INPUTS:
TEMP: If not specified, the T_max of the ion is used
DIL: The radiative dilution factor (between 0.0 and 0.5;
default=0.0)
N_LEVELS: Can be used to reduce the number of levels used in solving
the level balance equations.
KEYWORDS:
ALL: Show populations for all levels.
COMMON BLOCKS:
None.
CALLS:
ZION2NAME, ZION2FILENAME, READ_ELVLC, READ_WGFA2, READ_SPLUPS
READ_IONEQ, POPULATE_PRY
HISTORY:
Ver 1, PRY 22-Sep-97
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/show_pops.pro)
SHOW_POPS[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT: CHIANTI
CHIANTI is an atomic database package for the calculation of
astrophysical emission line spectra. It is a collaborative project
involving Ken Dere (Naval Research Laboratory, Washington DC),
Brunella Monsignori-Fossi and Enrico Landi (Arcetri Observatory,
Florence), and Helen Mason and Peter Young (DAMTP, Cambridge Univ.).
NAME: SHOW_POPS
PURPOSE:
To display populations of significant levels in a CHIANTI ion
model
CATEGORY:
Scientific analysis
EXPLANATION:
Displays percentage level populations and level IDs for all levels
in the specified ion with populations greater than 0.01%. If the
temperature is not specified, then it is taken to be where the
maximum of the ionisation fraction is.
CALLING SEQUENCE:
SHOW_POPS, IZ, ION, DENS, [TEMP=TEMP, N_LEVELS=N_LEVELS, DIL=DIL]
EXAMPLES:
INPUTS:
IZ: The atomic number of the ion
ION: The spectroscopic number of the ion (e.g., 12 = XII)
DENS: Logarithm of electron density
OPTIONAL INPUTS:
TEMP: If not specified, the T_max of the ion is used
DIL: The radiative dilution factor (between 0.0 and 0.5;
default=0.0)
N_LEVELS: Can be used to reduce the number of levels used in solving
the level balance equations.
KEYWORDS:
ALL: Show populations for all levels.
COMMON BLOCKS:
None.
CALLS:
ZION2NAME, ZION2FILENAME, READ_ELVLC, READ_WGFA2, READ_SPLUPS
READ_IONEQ, POPULATE_PRY
HISTORY:
Ver 1, PRY 22-Sep-97
CONTACT:
Peter Young, Cambridge University (pry10@damtp.cam.ac.uk)
(See /home/drw/idl/bin/ptg/show_pops.pro)
SHOW_PROFILE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: show_profile
PURPOSE: Read in QLDS and allow user to select a region in the
raster from which the spectrum is required
USEAGE: show_profile, QLDS
INPUT:
qlds CDS Quick Look Data Structure.
OUTPUT:
Example:
AUTHOR: Peter T. Gallagher, June. '98
(See /home/drw/idl/bin/show_profile.pro)
SHOW_PROFILE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: show_profile
PURPOSE: Read in QLDS and allow user to select a region in the
raster from which the spectrum is required
USEAGE: show_profile, QLDS
INPUT:
qlds CDS Quick Look Data Structure.
OUTPUT:
Example:
AUTHOR: Peter T. Gallagher, June. '98
(See /home/drw/idl/bin/ptg/show_profile.pro)
SHUFFLE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SHUFFLE
PURPOSE:
This function returns the uniformly-shuffled elements of an array.
CATEGORY:
Math.
CALLING SEQUENCE:
Result = SHUFFLE( A [, Num])
INPUTS:
A: Array containing the elements to shuffle (e.g. INDGEN(100))
OPTIONAL INPUTS:
Num: Number of shuffled elements to return. Must be < N_ELEMENTS(A)+1
OPTIONAL INPUT KEYWORD PARAMETERS:
SEED: Number used to seed the random number generator, RANDOMU.
OUTPUTS:
Returns the Num shuffled elements of the A array.
OPTIONAL OUTPUT KEYWORD PARAMETERS:
INDICES: Array of indices pointing to the shuffled elements of A.
EXAMPLE:
Pick 10 unique random integers between the numbers 1..100:
i = INDGEN(100)
j = SHUFFLE(i,10)
MODIFICATION HISTORY:
Written by: Han Wen, January 1997.
(See /home/drw/idl/aux/shuffle.pro)
SIGMA
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SIGMA
PURPOSE:
Calculate the standard deviation value of an array, or calculate the
standard deviation over one dimension of an array as a function of all
the other dimensions.
CALLING SEQUENCE:
RESULT = SIGMA(ARRAY)
RESULT = SIGMA(ARRAY,N_PAR)
RESULT = SIGMA(ARRAY,N_PAR,DIM)
INPUTS:
ARRAY = Input array. May be any type except string.
OPTIONAL INPUT PARAMETERS:
N_PAR = Number of parameters. Default value is zero. The number of
degrees of freedom is N_FREE = N_POINTS - N_PAR, where N_POINTS
is either N_ELEMENTS(ARRAY) or the size of dimension DIM. The
value of SIGMA varies as 1 / SQRT(N_FREE). If N_PAR is
negative, then the absolute value of N_PAR is used, and an
additional factor of 1 / SQRT(N_POINTS) is included, yielding
the reduced sigma.
DIM = Optional dimension to do standard deviation over.
OUTPUTS:
The standard deviation value of the array when called with one
parameter.
If DIM is passed, then the result is an array with all the dimensions
of the input array except for the dimension specified, each element of
which is the standard deviation of the corresponding vector in the
input array.
For example, if A is an array with dimensions of (3,4,5), then the
command B = SIGMA(A,N,1) is equivalent to
B = FLTARR(3,5)
FOR J = 0,4 DO BEGIN
FOR I = 0,2 DO BEGIN
B(I,J) = SIGMA( A(I,*,J) , N )
ENDFOR
ENDFOR
RESTRICTIONS:
Dimension specified must be valid for the array passed; otherwise the
input array is returned as the output array.
PROCEDURE:
Uses the function AVG.
When DIM is passed, then the function SUM is used.
MODIFICATION HISTORY:
William Thompson Applied Research Corporation
July, 1986 8201 Corporate Drive
Landover, MD 20785
(See /home/drw/idl/old.esrg/sigma.pro)
SIGMA_FILTER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SIGMA_FILTER
PURPOSE:
Replace pixels more than a specified pixels deviant from its neighbors
EXPLANATION:
Computes the mean and standard deviation of pixels in a box centered at
each pixel of the image, but excluding the center pixel. If the center
pixel value exceeds some # of standard deviations from the mean, it is
replaced by the mean in box. Note option to process pixels on the edges.
CALLING SEQUENCE:
Result = sigma_filter( image, box_width, N_sigma=(#), /ALL,/MON )
INPUTS:
image = 2-D image (matrix)
box_width = width of square filter box, in # pixels (default = 3)
KEYWORDS:
N_sigma = # standard deviations to define outliers, floating point,
recommend > 2, default = 3. For gaussian statistics:
N_sigma = 1 smooths 35% of pixels, 2 = 5%, 3 = 1%.
RADIUS = alternative to specify box radius, so box_width = 2*radius+1.
/ALL_PIXELS causes computation to include edges of image,
/KEEP causes opposite effect: pixels with values outside of specified
deviation are not changed, pixels within deviation are smoothed.
/ITERATE causes sigma_filter to be applied recursively (max = 20 times)
until no more pixels change (only allowed when N_sigma >= 2).
/MONITOR prints information about % pixels replaced.
Optional Outputs:
N_CHANGE = # of pixels changed (replaced with neighborhood mean).
VARIANCE = image of pixel neighborhood variances * (N_sigma)^2,
DEVIATION = image of pixel deviations from neighborhood means, squared.
CALLS:
function filter_image( )
PROCEDURE:
Compute mean over moving box-cars using smooth, subtract center values,
compute variance using smooth on deviations from mean,
check where pixel deviation from mean is within variance of box,
replace those pixels in smoothed image (mean) with orignal values,
return the resulting partial mean image.
MODIFICATION HISTORY:
Written, 1991, Frank Varosi and Dan Gezari NASA/GSFC
F.V.1992, added optional keywords /ITER,/MON,VAR=,DEV=,N_CHANGE=.
Converted to IDL V5.0 W. Landsman September 1997
(See /home/drw/idl/bin/sigma_filter.pro)
SIGNIF_CONF[1]
[Previous Routine]
[Next Routine]
[List of Routines]
commented using http://cires.colorado.edu/geo_data_anal/assign/assign4.html
Assuming a Gaussian distribution for each point of your NINO3 timeseries, then each
point of the FFT Power Spectrum should have a chi-square
distribution with 2 degrees of freedom (DOF) (see Figure).
Looking at the curve, one can see that as one goes further to
the right (larger x), the probability of being greater than x
decreases. One can define the 95% level as that value of x
where there is only a 5% chance of being greater than x. This is referred to as either the
"95% significance level" or the "5% level of significance". Occasionally it is referred to as
the "95% confidence level", but the term "confidence" should really be reserved for
reference to "confidence intervals", which are the error bars seen on spectral plots.
For the FFT Power Spectrum, this means that if one were to choose 20 frequencies at
random, then only 1 of these frequencies would be expected to have FFT Power greater
than this value. Therefore, if you look at your power spectrum, and several peaks are
above the 95% level, then you can be reasonably "confident" that these are "real" peaks,
not just random noise.
(See /home/drw/idl/vtt/post_bbso/signif_conf.pro)
SIGNIF_CONF[2]
[Previous Routine]
[Next Routine]
[List of Routines]
commented using http://cires.colorado.edu/geo_data_anal/assign/assign4.html
Assuming a Gaussian distribution for each point of your NINO3 timeseries, then each
point of the FFT Power Spectrum should have a chi-square
distribution with 2 degrees of freedom (DOF) (see Figure).
Looking at the curve, one can see that as one goes further to
the right (larger x), the probability of being greater than x
decreases. One can define the 95% level as that value of x
where there is only a 5% chance of being greater than x. This is referred to as either the
"95% significance level" or the "5% level of significance". Occasionally it is referred to as
the "95% confidence level", but the term "confidence" should really be reserved for
reference to "confidence intervals", which are the error bars seen on spectral plots.
For the FFT Power Spectrum, this means that if one were to choose 20 frequencies at
random, then only 1 of these frequencies would be expected to have FFT Power greater
than this value. Therefore, if you look at your power spectrum, and several peaks are
above the 95% level, then you can be reasonably "confident" that these are "real" peaks,
not just random noise.
(See /home/drw/idl/jma/signif_conf.pro)
SIGNIF_CONT
[Previous Routine]
[Next Routine]
[List of Routines]
commented using http://cires.colorado.edu/geo_data_anal/assign/assign4.html
Assuming a Gaussian distribution for each point of your NINO3 timeseries, then each
point of the FFT Power Spectrum should have a chi-square
distribution with 2 degrees of freedom (DOF) (see Figure).
Looking at the curve, one can see that as one goes further to
the right (larger x), the probability of being greater than x
decreases. One can define the 95% level as that value of x
where there is only a 5% chance of being greater than x. This is referred to as either the
"95% significance level" or the "5% level of significance". Occasionally it is referred to as
the "95% confidence level", but the term "confidence" should really be reserved for
reference to "confidence intervals", which are the error bars seen on spectral plots.
For the FFT Power Spectrum, this means that if one were to choose 20 frequencies at
random, then only 1 of these frequencies would be expected to have FFT Power greater
than this value. Therefore, if you look at your power spectrum, and several peaks are
above the 95% level, then you can be reasonably "confident" that these are "real" peaks,
not just random noise.
(See /home/drw/idl/vtt/post_bbso/signif_cont.pro)
SIMPLE_SURFACE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SIMPLE_SURFACE
PURPOSE:
The purpose of this program is to demonstrate how to
create a simple surface plot with axes and rotational
capability in object graphics.
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, Object Graphics.
CALLING SEQUENCE:
SIMPLE_SURFACE, 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:
EXACT: Set this keyword to get exact axis scaling.
_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.
LANDSCAPE: Set this keyword if you are printing in landscape mode. The
default is Portrait mode. The Landscape keyword on the PRINTER object
is set, but not all printers will honor this keyword setting. If yours
does not, set Landscape mode in the Printer Setup dialog.
VECTOR: Set this keyword if you want vector printing (as opposed to
the default bitmap printing).
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.
EXAMPLE:
To use this program with your 2D data, type:
IDL> Simple_Surface, data
(See /home/drw/idl/aux/simple_surface.pro)
SIND[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SIND
PURPOSE:
Return the sine of an angle specified in degrees rather than radians.
CALLING SEQUENCE:
x = sind(deg)
INPUTS:
angle angle in degrees
OPTIONAL INPUTS:
OUTPUTS:
Sine of angle returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/sind.pro)
SIND[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SIND
PURPOSE:
Return the sine of an angle specified in degrees rather than radians.
CALLING SEQUENCE:
x = sind(deg)
INPUTS:
angle angle in degrees
OPTIONAL INPUTS:
OUTPUTS:
Sine of angle returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/sind.pro)
SLOPE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: slope
PURPOSE: compute a two point fitting function, y=f(x)
USEAGE: slope,a,b
INPUTS: none
KEYWORDS: none
OUTPUTS:
a fit coefficients
b fit coefficients
PROCEDURE: use the LMB to specify two points on the plot.
The form of the fitting function depends on whether the plot
has log axis in either the x or y directions, as follows,
x y
linear - linear y=a+b*x
log - linear y=a+b*log(x)
linear - log y=a*exp(b*x)
log - log y=a*x^b
After two points are chosen SLOPE will show the form of the
fitting function and the value of a and b in an XMESSAGE
widget. At this point the user can exit the procedure by
hitting any of the mouse buttons. The XMESSAGE widget is not
not destroyed if the RMB is used to exit SLOPE.
author: Paul Ricchiazzi nov93
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/esrg/slope.pro)
SLOPE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: slope
PURPOSE: compute a two point fitting function, y=f(x)
USEAGE: slope,a,b
INPUTS: none
KEYWORDS: none
OUTPUTS:
a fit coefficients
b fit coefficients
PROCEDURE: use the LMB to specify two points on the plot.
The form of the fitting function depends on whether the plot
has log axis in either the x or y directions, as follows,
x y
linear - linear y=a+b*x
log - linear y=a+b*log(x)
linear - log y=a*exp(b*x)
log - log y=a*x^b
After two points are chosen SLOPE will show the form of the
fitting function and the value of a and b in an XMESSAGE
widget. At this point the user can exit the procedure by
hitting any of the mouse buttons. The XMESSAGE widget is not
not destroyed if the RMB is used to exit SLOPE.
author: Paul Ricchiazzi nov93
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/old.esrg/slope.pro)
SOLVE2[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine solve2
purpose solve two simultaneous non-linear equations for variables
x and y. In The non-linear equations are formally
expressed as,
fu(x,y) = u
fv(x,y) = v
input:
fu name of first non-linear function (string)
fv name of second non-linear function (string)
u rhs value of first non-linear function (scalor)
v rhs value of second non-linear function (scalor)
x first guess value for variable x (scalor)
y first guess value for variable y (scalor)
xrange reasonable range of x (i.e., [xmin, xmax] )
yrange reasonable range of y (i.e., [ymin, ymax] )
keyword input
view plot convergence trace and print diagnostics
tol convergence criterium (see below).
maxit maximum number of iterations
Iteration terminates when one of the following
conditions is true:
1. number of iterations exceeds MAXIT
2. x or y is pegged at their extreme values,
given by XRANGE or YRANGE.
3. abs{fu(x,y)-u} lt TOL * u and
abs{fv(x,y)-v} lt TOL * v
output:
x converged value of x
y converged value of y
PROCEDURE: the functions fu and fv should return both the values
of the non-linear function and their derivatives with respect
to x and y. SOLVE2 assumes that these quantities are actually
implemented as procedures, so that all three values can be
obtained simply. The argument list of the fu or fv procedures
should be set up as follows,
pro fu,x,y,uu,dudx,dudy
and
pro fv,x,y,vv,dvdx,dvdy
where uu function value of fu at x,y
dudx partial derivative of fu with respect to x
dudy partial derivative of fu with respect to y
vv function value of fv at x,y
dvdx partial derivative of fv with respect to x
dvdy partial derivative of fv with respect to y
the equations are solved by newton-raphson iteration
author: Paul Ricchiazzi 22mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/solve2.pro)
SOLVE2[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine solve2
purpose solve two simultaneous non-linear equations for variables
x and y. In The non-linear equations are formally
expressed as,
fu(x,y) = u
fv(x,y) = v
input:
fu name of first non-linear function (string)
fv name of second non-linear function (string)
u rhs value of first non-linear function (scalor)
v rhs value of second non-linear function (scalor)
x first guess value for variable x (scalor)
y first guess value for variable y (scalor)
xrange reasonable range of x (i.e., [xmin, xmax] )
yrange reasonable range of y (i.e., [ymin, ymax] )
keyword input
view plot convergence trace and print diagnostics
tol convergence criterium (see below).
maxit maximum number of iterations
Iteration terminates when one of the following
conditions is true:
1. number of iterations exceeds MAXIT
2. x or y is pegged at their extreme values,
given by XRANGE or YRANGE.
3. abs{fu(x,y)-u} lt TOL * u and
abs{fv(x,y)-v} lt TOL * v
output:
x converged value of x
y converged value of y
PROCEDURE: the functions fu and fv should return both the values
of the non-linear function and their derivatives with respect
to x and y. SOLVE2 assumes that these quantities are actually
implemented as procedures, so that all three values can be
obtained simply. The argument list of the fu or fv procedures
should be set up as follows,
pro fu,x,y,uu,dudx,dudy
and
pro fv,x,y,vv,dvdx,dvdy
where uu function value of fu at x,y
dudx partial derivative of fu with respect to x
dudy partial derivative of fu with respect to y
vv function value of fv at x,y
dvdx partial derivative of fv with respect to x
dvdy partial derivative of fv with respect to y
the equations are solved by newton-raphson iteration
author: Paul Ricchiazzi 22mar93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/solve2.pro)
SORT_POWERS[1]
[Previous Routine]
[Next Routine]
[List of Routines]
sort_powers -- calculates the relative power of peaks and orders them.
INPUTS: the Fourier power spectrum (fspec) and number of peaks required
OUTPUTS: the ordered power peaks and corresponding frequencies
BASED on fish.pro by D.WIlliams & R.T.J McAteer
NOTES only returns the 10 largest peaks
(See /home/drw/idl/vtt/post_bbso/sort_powers.pro)
SORT_POWERS[2]
[Previous Routine]
[Next Routine]
[List of Routines]
SORT_POWERS -- orders the peaks in a power spectrum.
INPUTS: the Fourier power spectrum (fspec) and number of peaks required
OUTPUTS: the ordered power peaks and corresponding frequencies
AUTHOR R.T.J McAteer
BASED on fish.pro and fish_signif.pro by D.WIlliams & R.T.J McAteer
NOTES only returns the 'num' largest peaks
(See /home/drw/idl/vtt/post_bbso/sort_powers.pro)
SORT_POWERS[3]
[Previous Routine]
[Next Routine]
[List of Routines]
sort_powers -- calculates the relative power of peaks and orders them.
INPUTS: the Fourier power spectrum (fspec) and number of peaks required
OUTPUTS: the ordered power peaks and corresponding frequencies
BASED on fish.pro by D.WIlliams & R.T.J McAteer
NOTES only returns the 10 largest peaks
(See /home/drw/idl/jma/sort_powers.pro)
SORT_POWERS[4]
[Previous Routine]
[Next Routine]
[List of Routines]
SORT_POWERS -- orders the peaks in a power spectrum.
INPUTS: the Fourier power spectrum (fspec) and number of peaks required
OUTPUTS: the ordered power peaks and corresponding frequencies
AUTHOR R.T.J McAteer
BASED on fish.pro and fish_signif.pro by D.WIlliams & R.T.J McAteer
NOTES only returns the 'num' largest peaks
(See /home/drw/idl/jma/sort_powers.pro)
SPHASE
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: sphase,mu,g=g,type=type
PURPOSE: compute sphase greenstein phase function
USEAGE: sphase,mu,g=g,type=type
INPUT:
mu cosine of polar angle (mu=1 in forward direction)
g asymmetry factor
keywords
rayleigh
returns rayleigh phase function and ignors value of g
EXAMPLE: compute fraction of all single scattered radiation
within a disk which subtends one degree of the of
the forward direction.
;;
mu=findrng(-1,1,1000)
plot_io,acos(mu)/!dtor,sphase(mu),/xstyle
;;
;; print angle and phase for sbdart input
;;
sangle=findrng(0,180,181) & sph=sphase(cos(sangle*!dtor),g=.8)
print,f='(a,10(f6.2,","))',' sangle=',sangle(0:9)
print,f='((9x,10(f6.2,",")))',sangle(10:*)
print,f='(a,10(f8.5,","))',' sphase=',sph(0:9)
print,f='((9x,10(f8.5,",")))',sph(10:*)
;;
AUTHOR: Paul Ricchiazzi 22 Apr 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/sphase.pro)
SPHERE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: sphere
USAGE: sphere
DESCRIPTION: makes a sphere -- taken from the IDL BASICS guide
(See /home/drw/idl/gen/sphere.pro)
SPLINE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
Spline
PURPOSE:
Cubic Spline Interpolation
CATEGORY:
Interpolation - E1
CALLING SEQUENCE:
Result = Spline(X,Y,T) ... or:
Result = Spline(X,Y,T,Sigma)
INPUTS:
X = abcissa vector. MUST be monotonically increasing.
Y = vector of ordinate values corresponding to X.
T = vector of abcissae values for which ordinate is desired.
Elements of T MUST be monotonically increasing.
OPTIONAL INPUT PARAMETERS:
Sigma = optional parameter, default value is 1.0.
The amount of "tension" that is
applied to the curve. If sigma is close to 0, (e.g. .01),
then effectively there is a cubic spline fit. If sigma
is large, > 10 for example, then the fit will be like
a polynomial interpolation.
OUTPUTS:
Result = vector of interpolated ordinates. Result(i) = value
of function at T(i).
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
Abcissae values must be monotonically increasing.
PROCEDURE:
As below.
MODIFICATION HISTORY:
Author: Walter W. Jones, Naval Research Laboratory, Sept 26, 1976.
Reviewer: Sidney Prahl, Texas Instruments.
Adapted for IDL: DMS, Research Systems, March, 1983.
Example:
X = [2.,3.,4.] ;X values of original function
Y = (X-3)^2 ;Make a quadratic
T = FINDGEN(20)/10.+2 ;Values for interpolated points.
;twenty values from 2 to 3.9.
Z = SPLINE(X,Y,T) ;Do the interpolation.
(See /home/drw/idl/icur/spline.pro)
SPRITE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: sprite
PURPOSE:
interactive display of multi parameter correspondences. Points
corresponding to a single independent index variable is hilighted
by a small "sprite" symbol on several plot frames simultaneously.
The sprite position is controlled by the master index, which can
be incremented/decremented via the mouse.
USEAGE:
plot,x1,y1 & sprite,x1,y1,/init
plot,x2,y2 & sprite,x2,y2
plot,x3,y3 & sprite,x3,y3
...
sprite
INPUT:
xvec
x vector for current plot. Only required when accumulating the
DATA and CONTROL info after each plot. If xvec and yvec are not
set, SPRITE executes in interactive mode
yvec
y vector for current plot. Only required when accumulating the
DATA and CONTROL info after each plot.
KEYWORD INPUT:
init
Set the keyword to reinitialize SPRITE for a new set of plots.
psym
symbol used to indicate sprite
color
color index used to draw sprite
xtitle
title of x variable for current plot, used to label quantity in
print out widget.
ytitle
title of y variable for current plot, used to label quantity in
print out widget.
NOTE: Only those variables specified in a xtitle or ytitle label
are displayed in the print out widget. Just specify a
given variable once in xtitle or ytitle to avoid having
it listed several times in the print out widget.
DISCUSSION: SPRITE operates in two modes:
1. in accumulation mode SPRITE is called immediately after each
plot is written to the screen. Multiple plot frames can be
accumulated because SPITE stores all the data and plot geometry
information in an internal common block, SPRITE_BLK, for latter
use.
NOTE: SPRITE ignors the values of PSYM, COLOR and
LABELS while in accumulation mode.
2. In interactive mode a sprite control window is created with
several mouse-sensitive areas defined. Pressing a mouse button
in one of these areas causes the following actions:
control area action
------------ ------
QUIT quit
<< move sprite backward taking large steps
< move sprite backward one step
> move sprite forward one step
>> move sprite forward taking large steps
Using the RMB in the "<", ">" areas causes the sprite to pause
between steps and to update the print-out widget after each step.
Otherwise, if the LMB or MMB is used, the print-out widget is
updated only after the button is released.
SIDE EFFECTS:
Draws a sprite on each of the plot frames
While in operations the XOR graphics mode is set.
If psym is not set, user symbol, psym=8, is redefined to a filled
diamond
COMMON BLOCKS:
sprite_blk
EXAMPLE:
; use sprite to show solar flux values :
!p.multi=0
solar,wv,f
xtitle='wavenumber' & ytitle='W/m2' & title='irradiance'
plot,wv,f,xtitle=xtitle,ytitle=ytitle,title=title
sprite,wv,f,xtitle=xtitle,ytitle=title,/init
sprite,color=150
; try a four frame plot
!p.multi=[0,2,2]
time=findgen(100)*10 & tlab='Time (hours)'
lon=-90+10*cos(!dtor*time)+randf(100,3)
lat=30+5*sin(!dtor*time)+randf(100,3)
alt=5000*sin(time*!pi/999)+2000*randf(100,3.3)
ch1=10.+randf(100,3)
ch2=25.+randf(100,2.5)^3
plot,lon,lat,/yno,xtit='Longitude',ytit='Latitude',title='Flight path'
sprite,lon,lat,xtit='Longitude',ytit='Latitude',/init ; initialize
plot,time,alt,xtitle=tlab,title='Altitude',ytitle='meters'
sprite,time,alt,xtitle=tlab,ytitle='Altitude'
plot,time,ch1,xtitle=tlab,title='Ch1 flux'
sprite,time,ch1,ytitle='Ch1 flux' ; note xtitle not set
plot,time,ch2,xtitle=tlab,title='Ch2 flux'
sprite,time,ch2,ytitle='Ch2 flux' ; note xtitle not set
loadct,5
sprite,color=150
; You can also have two sprites in one plot frame:
!p.multi=[0,1,2]
w8x11
y2=randf(10000,3) & x1=indgen(10000)
y1=y2+.5*randf(10000,2)
!p.font=-1
plot,x1,y1 ,xtitle='time',ytitle='ch1 and ch2 flux'
sprite,x1,y1,xtitle='time',ytitle='ch1 flux',/init ; initialize
oplot,x1,y2,li=3
sprite,x1,y2,ytitle='ch2 flux'
sprite,color=150
AUTHOR: Paul Ricchiazzi 2 March 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
(See /home/drw/idl/esrg/sprite.pro)
SPRITE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: sprite
PURPOSE:
interactive display of multi parameter correspondences. Points
corresponding to a single independent index variable is hilighted
by a small "sprite" symbol on several plot frames simultaneously.
The sprite position is controlled by the master index, which can
be incremented/decremented via the mouse.
USEAGE:
plot,x1,y1 & sprite,x1,y1,/init
plot,x2,y2 & sprite,x2,y2
plot,x3,y3 & sprite,x3,y3
...
sprite
INPUT:
xvec
x vector for current plot. Only required when accumulating the
DATA and CONTROL info after each plot. If xvec and yvec are not
set, SPRITE executes in interactive mode
yvec
y vector for current plot. Only required when accumulating the
DATA and CONTROL info after each plot.
KEYWORD INPUT:
init
Set the keyword to reinitialize SPRITE for a new set of plots.
psym
symbol used to indicate sprite
color
color index used to draw sprite
xtitle
title of x variable for current plot, used to label quantity in
print out widget.
ytitle
title of y variable for current plot, used to label quantity in
print out widget.
DISCUSSION: SPRITE operates in two modes:
1. in accumulation mode SPRITE is called immediately after each
plot is written to the screen. Multiple plot frames can be
accumulated because SPITE stores all the data and plot geometry
information in an internal common block, SPRITE_BLK, for latter
use.
NOTE: SPRITE ignors the values of PSYM, COLOR and
LABELS while in accumulation mode.
2. In interactive mode a sprite control window is created with
several mouse-sensitive areas defined. Pressing a mouse button
in one of these areas causes the following actions:
control area action
------------ ------
QUIT quit
<< move sprite backward taking large steps
< move sprite backward one step
> move sprite forward one step
>> move sprite forward taking large steps
Using the MMB in the "<", ">" areas causes the sprite to pause
between steps and to update the print-out widget after each step.
Otherwise, if the LMB or RMB is used, the print-out widget is
updated only after the button is released.
SIDE EFFECTS:
Draws a sprite on each of the plot frames
While in operations the XOR graphics mode is set.
If psym is not set, user symbol, psym=8, is redefined to a filled
diamond
COMMON BLOCKS:
sprite_blk
EXAMPLE:
; use sprite to show solar flux values :
!p.multi=0
solar,wv,f
xtitle='wavenumber' & ytitle='W/m2' & title='irradiance'
plot,wv,f,xtitle=xtitle,ytitle=ytitle,title=title
sprite,wv,f,xtitle=xtitle,ytitle=title,/init
sprite,color=150
; try a four frame plot
!p.multi=[0,2,2]
time=findgen(100)*10 & tlab='Time (hours)'
lon=-90+10*cos(!dtor*time)+randf(100,3)
lat=30+5*sin(!dtor*time)+randf(100,3)
alt=5000*sin(time*!pi/999)+2000*randf(100,3.3)
ch1=10.+randf(100,3)
ch2=25.+randf(100,2.5)^3
plot,lon,lat,/yno,xtit='Longitude',ytit='Latitude',title='Flight path'
sprite,lon,lat,xtit='Longitude',ytit='Latitude',/init ; initialize
plot,time,alt,xtitle=tlab,title='Altitude',ytitle='meters'
sprite,time,alt,xtitle=tlab,ytitle='Altitude'
plot,time,ch1,xtitle=tlab,title='Ch1 flux'
sprite,time,ch1,ytitle='Ch1 flux'
plot,time,ch2,xtitle=tlab,title='Ch2 flux'
sprite,time,ch2,ytitle='Ch2 flux'
loadct,5
sprite,color=150
; You can also have two sprites in one plot frame:
!p.multi=[0,1,2]
w8x11
y2=randf(10000,3) & x1=indgen(10000)
y1=y2+.5*randf(10000,2)
!p.font=-1
plot,x1,y1 ,xtitle='time',ytitle='ch1 and ch2 flux'
sprite,x1,y1,xtitle='time',ytitle='ch1 flux',/init ; initialize
oplot,x1,y2,li=3
sprite,x1,y2,ytitle='ch2 flux'
sprite,color=150
AUTHOR: Paul Ricchiazzi 2 March 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
(See /home/drw/idl/old.esrg/sprite.pro)
SQUARELIGHT.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
squarelight.pro
(new,fixed-square UV lightcurve)
PURPOSE:
A rountine to make an TOTAL (over a fixed area of pixels) lightcurve for
512x512 UV images.
CALLING SEQUENCE:
squarelight, data, curve, background
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
SQUARELIGHT.PRO, a version based on a *total*
value summed over all pixels
which are in a box (250:369,250:369).
(See /home/drw/idl/bin/squarelight.pro)
SQUARELIGHTEUV.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
squarelighteuv.pro
(new,fixed-square EUV lightcurve)
PURPOSE:
A rountine to make an TOTAL (over a fixed area of pixels) lightcurve for
1024x1024 UV images.
CALLING SEQUENCE:
squarelighteuv, data, curve, background
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
SQUARELIGHTEUV.PRO, a version based on a *total*
value summed over all pixels
which are in a box (250:369,250:369).
(See /home/drw/idl/bin/squarelighteuv.pro)
SQUARELIGHTVTT.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
squarelightvtt.pro
(new,fixed-square VTT/UBF lightcurve)
PURPOSE:
A rountine to make an TOTAL (over a fixed area of pixels) lightcurve for
VTT/UBF images.
CALLING SEQUENCE:
squarelight, data, curve, background
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
SQUARELIGHTVTT.PRO, a version based on a *total*
value summed over all pixels
which are in a box (405:744,499:838).
(See /home/drw/idl/bin/squarelightvtt.pro)
SQUARELIGHTVTT2.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
squarelightvtt2.pro
(new,fixed-square VTT/UBF lightcurve)
PURPOSE:
A rountine to make an TOTAL (over a fixed area of pixels) lightcurve for
VTT/UBF images.
CALLING SEQUENCE:
squarelight, data, curve, background
INPUTS:
data - data cube
curve - name of floating, 1-D output array to contain curve
intensities
background - name of floating 1-D array to contain background flux
intensities
HISTORY:
based on LIGHT_CURVECAII.PRO by Peter Gallagher, modified by
Peter Gallagher and David Williams for TRACE EUV data.
SQUARELIGHTVTT.PRO, a version based on a *total*
value summed over all pixels in
which are in a box (37:598,126:665). CHanged from
squarelightvtt.pro to account for the change in position
as the flare goes off.
(See /home/drw/idl/bin/squarelightvtt2.pro)
SRVADD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SRVADD
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:
Add velocity 3-vectors according to special relativity
MAJOR TOPICS:
Physics, Geometry
CALLING SEQUENCE:
U0 = SRVADD(U1, V)
DESCRIPTION:
The function SRVADD performs addition of velocity 3-vectors
according to special relativity.
Consider two inertial coordinate frames. Frame "0" is a "lab" or
rest frame. Frame "1" is a "rocket" or moving frame, moving at
velocity V with respect to the lab frame. The velocity V is
allowed to be an arbitrary 3-vector.
* An observer in the rocket frame sees a body moving at velocity U1.
* An observer in the lab frame sees the same body moving at
velocity U0.
* This function solves for U0 in terms of V and U1.
U1 and V are allowed to be 3xN arrays, which means more than one
vector can be computed in a single call. If the dimensions of
either U1 or V are 3x1, then it will be expanded to match the
dimensions of the other vector. This simulates addition by a
"scalar" vector. Because V can be a 3xN array, this means that
multiple "rocket" frames can be computed at one time.
NOTE: Velocities passed to SRVADD are measured as a *fraction of
the speed of light*. Therefore, if the velocities are
measured in some physical units, and CLIGHT is the speed of
light in those same units, then the following statement:
U0 = SRVADD(U1/CLIGHT, V/CLIGHT)*CLIGHT
will compute the velocity U0, also in the same units.
The formula for computing the velocity in the lab frame is:
( (1-1/GAMMA)*(U1 . VUNIT)*VUNIT + U1/GAMMA + V )
U0 = -------------------------------------------------
(1 - U1 . V)
where
GAMMA is the Lorentz factor = 1/SQRT(1 - |V|^2)
VUNIT is the unit vector in the direction of V, = V/|V|
"." is the vector dot product
[ IDL notation is not strictly adhered to in this formula, for
clarity of presentation. ]
INPUTS:
U1 - 3-vector or 3xN array, the velocity of a body as seen in the
rocket frame (frame 1). The velocity is normalized such that
the speed of light is 1.
V - 3-vector or 3xN array, the velocity of the rocket frame as
seen by an observer in the lab. The velocity is normalized
such that the speed of light is 1.
RETURNS:
A 3xN array, containing the velocity of the body as seen in the
lab frame. The velocity is normalized such that the speed of
light is 1.
KEYWORD PARAMETERS:
CLASSICAL - if set, then classical velocity addition is performed,
and the relativistic form is disabled.
Default: not set (i.e., relativity is applied)
EXAMPLE:
IDL> print, srvadd([0.1d,0,0], [0.5d,0,0])
0.56504883 0.0000000 0.0000000
Adds velocities of 0.1 and 0.5 times the speed of light. The
result is slightly less than the arithmetic sum.
IDL> print, srvadd([0.,0.1,0],[0.5d,0,0])
0.50000000 0.086602542 0.0000000
Adds velocities in two orthogonal directions. Demonstrates the
relativistic aberration of velocities (i.e., velocities in the
perpendicular direction are affected).
MODIFICATION HISTORY:
Written, 28 Jan 2002, CM
More documentation, 29 Jan 2002, CM
Add CLASSICAL keyword, 29 Jul 2002, CM
$Id: srvadd.pro,v 1.3 2002/07/29 23:16:47 craigm Exp $
(See /home/drw/idl/aux/markwardt/srvadd.pro)
SRVDOPP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SRVDOPP
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:
Compute relativistic doppler shift (arbitrary velocity & photon dir.)
MAJOR TOPICS:
Physics, Geometry
CALLING SEQUENCE:
NU1_NU0 = SRVDOPP(U0, V)
DESCRIPTION:
The function SRVDOPP computes the relativistic doppler shift
between two inertial reference frames.
Consider two inertial coordinate frames. Frame "0" is a "lab" or
rest frame. Frame "1" is a "rocket" or moving frame, moving at
velocity V with respect to the lab frame. The velocity V is
allowed to be an arbitrary 3-vector.
* An observer in the lab frame sees a photon of frequency NU0
propagating in the direction U0. (U0 is a unit 3-vector)
* An observer in the rocket frame observes the same photon with
frequency NU1.
* This function computes the ratio NU1 / NU0.
U0 and V are allowed to be 3xN arrays, which means more than one
set of values can be computed in a single call. If the dimensions
of either U0 or V are 3x1, then it will be expanded to match the
dimensions of the other vector.
NOTE: Velocities passed to SRVDOPP are measured as a *fraction of
the speed of light*.
The formula for computing the relativistic doppler shift is:
NU1_NU0 = (1 - U0 . V) * GAMMA
where
GAMMA is the Lorentz factor = 1/SQRT(1 - |V|^2)
"." is the vector dot product
[ IDL notation is not strictly adhered to in this formula, for
clarity of presentation. ]
INPUTS:
U0 - 3-vector or 3xN array, the unit vector of the photon
propagation direction, as seen in the lab frame.
V - 3-vector or 3xN array, the velocity of the rocket frame as
seen by an observer in the lab. The velocity is normalized
such that the speed of light is 1.
RETURNS:
A N-vector giving the ratio, NU1/NU0, which is the ratio of the
frequency observed in the rocket frame to the frequency seen in
the lab frame.
KEYWORD PARAMETERS:
CLASSICAL - if set, then classical Doppler shift is performed,
and the relativistic form is disabled.
Default: not set (i.e., relativity is applied)
EXAMPLE:
IDL> RATIO = SRVDOPP([-1d,0,0], [0.1d,0,0])
A photon of frequency NU0 is moving along the -x axis in the lab
frame; a rocket observer is moving with speed 0.1 c along the +x
axis. NU0 * RATIO is the frequency seen by the rocket observer.
IDL> RATIO = SRVDOPP([0,-1d,0], [0.1,0,0])
The observer is the same, but the photon is moving along the -y
axis. NU0 * RATIO is the frequency seen by the rocket observer.
This is the relativistic transverse doppler shift.
MODIFICATION HISTORY:
Written, 05 May 2002, CM
Documentation, 12 May 2002, CM
Add CLASSICAL keyword, 29 Jul 2002, CM
$Id: srvdopp.pro,v 1.3 2002/07/29 23:16:47 craigm Exp $
(See /home/drw/idl/aux/markwardt/srvdopp.pro)
STABILISE2MOON.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STABILISE2MOON.PRO
PURPOSE:
To stabilise the SECIS images to the Moon's limb,
using different parts of the limb. It takes four
different sections of the image, takes their gradient
and then places those gradient images in a composite
or 'mosaic' master image which can then be used to
determine the cross-correlation displacement. This
method, it is hoped, will avoid slippage along any
one tangent to the Moon's limb.
USAGE:
stabilise2moon,data,dataout,displacement_array
CALLS:
TR_GET_DISP, GRAD
HISTORY:
VERSION 0.1: based heavily on the SEC_MOVE family of routines.
D. Williams, 31/3/00.
(See /home/drw/idl/secis/stabilise2moon.pro)
STABIL[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STABIL
PURPOSE:
shift images to the final common position using already calculated values of the shifts
EXPLANATION:
CALLING SEQUENCE:
STABIL [, NSTART=NSTART, NEND=NEND, $
SCALE=SCALE, NSTEP=NSTEP, SHIFTNAME=SHIFTNAME, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3, $
XYFLAT=XYFLAT, WYL=WYL ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
NSTART = number of the first raw image to be processed
NEND = number of the last raw image to be processed
SHIFTEXT = extennsion of the names of the shifted images [def. '_shftd']
SCALE = megnification factor for calculations of the shifting (should be keept 20 or greater)
NSTEP = step between the shifted images (normaly 1, it means all images between begname//nstart//extname and begname//nend//extname)
SHIFTNAME = name of the file with final values of of shifts along both axes
BEGNAME = prefix of the names of the raw images
EXTNAME = extension of the names of the raw images (normaly .fit)
DARKNAME = name of the averaged dark image
FLATNAME = name of the averaged flat image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
XYFLAT = X1,Y1,X2,Y2: 4-element vector of coord. of the lower-left anr upper-right corners of the flattened area [de. 1,100,480,480]
WYL = 20-element array with numers of the processed sub-fields [def.: 1,2,3,0,5,6,0,0,9,10,0,0,13,14,15,0,17,18,19,20]
OUTPUT:
Shifted images
MODIFICATION HISTORY:
Written, February 2002, Pawel Rudawy, IAUWr.
Modif. 24 Marz 2002 PR
added keyword xycorr
removed keywords x1flat...y2flat, instead added keyword xyflat
(See /home/drw/idl/pawel/Moon_position_brd_cam_step4_finalshift_YH.pro)
STABIL[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STABIL
PURPOSE:
shift images to the final common position using already calculated values of the shifts
EXPLANATION:
CALLING SEQUENCE:
STABIL [, NSTART=NSTART, NEND=NEND, $
SCALE=SCALE, NSTEP=NSTEP, SHIFTNAME=SHIFTNAME, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3, $
XYFLAT=XYFLAT, WYL=WYL ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
NSTART = number of the first raw image to be processed
NEND = number of the last raw image to be processed
SHIFTEXT = extennsion of the names of the shifted images [def. '_shftd']
SCALE = megnification factor for calculations of the shifting (should be keept 20 or greater)
NSTEP = step between the shifted images (normaly 1, it means all images between begname//nstart//extname and begname//nend//extname)
SHIFTNAME = name of the file with final values of of shifts along both axes
BEGNAME = prefix of the names of the raw images
EXTNAME = extension of the names of the raw images (normaly .fit)
DARKNAME = name of the averaged dark image
FLATNAME = name of the averaged flat image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
XYFLAT = X1,Y1,X2,Y2: 4-element vector of coord. of the lower-left anr upper-right corners of the flattened area [de. 1,100,480,480]
WYL = 20-element array with numers of the processed sub-fields [def.: 1,2,3,0,5,6,0,0,9,10,0,0,13,14,15,0,17,18,19,20]
OUTPUT:
Shifted images
MODIFICATION HISTORY:
Written, February 2002, Pawel Rudawy, IAUWr.
Modif. 24 Marz 2002 PR
added keyword xycorr
removed keywords x1flat...y2flat, instead added keyword xyflat
(See /home/drw/idl/Moon_position_brd_cam_step4_finalshift_YH.pro)
STABIL[3]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STABIL
PURPOSE:
shift images to the final common position using already calculated values of the shifts
EXPLANATION:
CALLING SEQUENCE:
STABIL [, NSTART=NSTART, NEND=NEND, $
SCALE=SCALE, NSTEP=NSTEP, SHIFTNAME=SHIFTNAME, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT, WYL=WYL ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
NSTART = number of the first raw image to be processed
NEND = number of the last raw image to be processed
SHIFTEXT = extennsion of the names of the shifted images [def. '_shftd']
SCALE = megnification factor for calculations of the shifting (should be keept 20 or greater)
NSTEP = step between the shifted images (normaly 1, it means all images between begname//nstart//extname and begname//nend//extname)
SHIFTNAME = name of the file with final values of of shifts along both axes
BEGNAME = prefix of the names of the raw images
EXTNAME = extension of the names of the raw images (normaly .fit)
DARKNAME = name of the averaged dark image
FLATNAME = name of the averaged flat image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
WYL = 20-element array with numers of the processed sub-fields [def.: 1,2,3,0,5,6,0,0,9,10,0,0,13,14,15,0,17,18,19,20]
OUTPUT:
Shifted images
MODIFICATION HISTORY:
Written, February 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/secis2/Moon_position_brd_cam_step4_finalshift_YH.pro)
STABIL[4]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STABIL
PURPOSE:
shift images to the final common position using already calculated values of the shifts
EXPLANATION:
CALLING SEQUENCE:
STABIL [, NSTART=NSTART, NEND=NEND, $
SCALE=SCALE, NSTEP=NSTEP, SHIFTNAME=SHIFTNAME, $
BEGNAME=BEGNAME, EXTNAME=EXTNAME, $
DARKNAME=DARKNAME, FLATNAME=FLATNAME, $
NCUT=NCUT, PATH1=PATH1, PATH2=PATH2, PATH3=PATH3, $
X1FLAT=X1FLAT, X2FLAT=X2FLAT, Y1FLAT=Y1FLAT, Y2FLAT=Y2FLAT, WYL=WYL ]
INPUTS:
none
OPTIONAL INPUT KEYWORDS:
NSTART = number of the first raw image to be processed
NEND = number of the last raw image to be processed
SHIFTEXT = extennsion of the names of the shifted images [def. '_shftd']
SCALE = megnification factor for calculations of the shifting (should be keept 20 or greater)
NSTEP = step between the shifted images (normaly 1, it means all images between begname//nstart//extname and begname//nend//extname)
SHIFTNAME = name of the file with final values of of shifts along both axes
BEGNAME = prefix of the names of the raw images
EXTNAME = extension of the names of the raw images (normaly .fit)
DARKNAME = name of the averaged dark image
FLATNAME = name of the averaged flat image
NCUT = number of the last raw image located in directory PATH1 [def. 3999]
PATH1 = full path to the directory with processed images with numbers le NCUT [def. current dir]
PATH2 = full path to the directory with processed images with numbers gt NCUT [def. current dir]
PATH3 = full path to the directory with mean flat and dark images [def. current dir]
X1FLAT = x-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
X2FLAT = x-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
Y1FLAT = y-coord. of the lower-left corner of the flattened area [image oriented as on the sky]
Y2FLAT = y-coord. of the upper-right corner of the flattened area [image oriented as on the sky]
WYL = 20-element array with numers of the processed sub-fields [def.: 1,2,3,0,5,6,0,0,9,10,0,0,13,14,15,0,17,18,19,20]
OUTPUT:
Shifted images
MODIFICATION HISTORY:
Written, February 2002, Pawel Rudawy, IAUWr.
(See /home/drw/idl/secis2/Moon_position_brd_cam_step4_finalshift_YH_0.pro)
STATS[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: stats
PURPOSE: compute mean and standard deviation of a
histogram
USEAGE: result = stats(x,y)
INPUT:
x 1-D array of x values
y 1-D array of y values
OUTPUT: result is a two element array containing
both mean and standard deviation.
EXAMPLE: print, stats(wavelength_array, flux_array)
... will print the mean and standard deviation
of the line profile.
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/bin/stats.pro)
STATS[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: stats
PURPOSE: compute mean and standard deviation of a
histogram
USEAGE: result = stats(x,y)
INPUT:
x 1-D array of x values
y 1-D array of y values
OUTPUT: result is a two element array containing
both mean and standard deviation.
EXAMPLE: print, stats(wavelength_array, flux_array)
... will print the mean and standard deviation
of the line profile.
AUTHOR: Peter T. Gallagher, Oct. '97
(See /home/drw/idl/bin/ptg/stats.pro)
STATUSLINE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STATUSLINE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Maintain a one-line status line on a VT100-compatible terminal. (Unix)
MAJOR TOPICS:
Text Output, Terminal.
CALLING SEQUENCE:
STATUSLINE, string, column, LENGTH=length, [/CLOSE,]
[/CLEAR,] [/LEFT,] [/RIGHT,] [/QUIET,] [/ENABLE,] [/DISABLE]
DESCRIPTION:
STATUSLINE maintains the current line of a VT100- or
ANSI-compatible terminal, usually as a status line.
Programs that run for extended periods of time can inform the user
of the status of the computation by printing vital information.
Instead of cluttering the console by using the PRINT procedure,
which uses a new line with each call, STATUSLINE will re-use the
same line. This can make a cleaner interface.
STATUSLINE interacts directly with the Unix terminal device,
sending VT100-compatible cursor commands. As a side effect it
opens the terminal device /dev/tty and allocates a logical unit
number. Picky programmers should call STATUSLINE, /CLOSE to close
the file unit.
Procedures that finish their computation, or wish to make normal
output to the console should first clear the terminal line with
STATUSLINE, /CLEAR. This will ensure that the console is
uncluttered before printing.
By default, STATUSLINE enables output for terminal types vt100,
vtnnn, xterm, dec, or ansi. *No* output appears on other
terminals. You can enable it explicitly by calling STATUSLINE,
/ENABLE, and disable it by calling STATUSLINE, /DISABLE.
INPUTS:
STRING - A string to be placed on the current line.
OPTIONAL INPUTS:
COLUMN - The starting column number, beginning with zero.
Default: zero.
INPUT KEYWORD PARAMETERS:
LENGTH - the record length, an integer. Strings longer than this
length will be truncated.
Default: strlen(STRING)
CLEAR - if set, clear the current line to the end. Control
returns immediately (i.e., no output is made).
LEFT - if set, then left justify the string within the record.
If the string is longer than the record length, then the
leftmost portion of the string is printed.
The Default (if /RIGHT is not given).
RIGHT - if set, then right jusfity the string within the record.
If the string is longer than the record length, then the
rightmost portion of the string is printed.
QUIET - if set, then no output is made (for this call only).
NOCR - if set, no carriage return operation is performed after
output. This also has the side effect that in subsequent
calls, column "0" will not cause the cursor to move.
Default: cursor returns to column 0 after each output.
ENABLE - if set, then permanently enable output by STATUSLINE.
Normally STATUSLINE automatically enables output only for
vt100-compatible terminals. By setting /ENABLE, you
override this automatic test. However, /QUIET will
still override ENABLE in an individual call.
DISABLE - if set, then permanently disable output by STATUSLINE.
When disabled, no output is ever produced. Output can
only be re-enabled again by using the /ENABLE flag.
CLOSE - if set, instruct STATUSLINE to close the terminal device
logical unit number. Users should perform this operation
when the computation has finished so that the terminal
device is not left dangling open. If, at a later time,
STATUSLINE is called again, the terminal device will be
re-opened.
OUTPUTS:
NONE
SEE ALSO:
PRINT, PRINTF
PRINTLOG - to maintain transcript of IDL output
MODIFICATION HISTORY:
Written, CM, 1997-1998
Documented, CM, Sep 1999
Added NOCR keyword, CM, 28 Oct 1999
Doesn't crash if can't write to TTY. Returns silently. CM, 16
Nov 1999.
Added PRINTLOG to "SEE ALSO", CM, 22 Jun 2000
Keyword QUIET now causes earlier exit; catch errors in the CLEAR
case, CM, 12 Oct 2001
$Id: statusline.pro,v 1.4 2001/10/13 17:52:46 craigm Exp $
(See /home/drw/idl/aux/markwardt/statusline.pro)
STELLARWAVE2
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STELLARWAVE2
PURPOSE:
Calculate and display the wavelet (power) transform of a time series
(CURVE) with the time series above the plot for comparison with the
transform, and also show the global wavelet spectrum to the right,
since it represents the summation of the power transform over time,
and is therefore analogous to the Fourier transform of the series.
CALLING SEQUENCE:
stellarwave2,curve,print=print,pc=pc,title=title,nocon=nocon,delt=delt,$
mother=mother,offset=offset
INPUTS:
CURVE - a 1-D time series, e.g. a light curve
INTERACTIVE INPUTS DURING EXECUTION:
The user is first asked for a maximum value for the low-pass filter
called by WAVE_EXAMPLE. For the SECIS data, an unfiltered time series
will be analysed by specifying half the data sampling rate of 44.2 Hz
(i.e. 22.1 Hz).
The second parameter requested is the significance (confidence)
level which the WAVELET function will calculate as a set of contours
in the power transform. Concentrations of power enclosed within these
contours will be significant to that level. E.g., if the user specifies
a value of 0.99 (i.e. 99%) then there is a 1% chance that the power
within the contours is due to noise.
KEYWORDS:
PRINT - if set, then set parameters applicable to printing to a
postscript file. NOTE: Does not actually set the display
to the PostScript device - this must be done manually.
PC - the plot colour for the contours and cone-of-influence
boundary and cross-hatching. This is a value from 0 to
255. In a monochromatic colour table (e.g. loadct,3 for
red temperature) 0 will be black, 255 will be white, and
any other colours will be somewhere in between (e.g.
scale linearly for colour tables 0,1,3, & 8;
logarithmically for colour table 9).
TITLE - a string, specifying the title over the wavelet transform
part of the display output.
NOCON - if set, then do not display either contours or the
cone-of-influence calculated by the WAVELET routine
OUTPUTS:
None, except for the display of the wavelet transform etc. to
either X windows (the default) or (optionally) the PostScript device.
EXAMPLES:
IDL> stellarwave2,series,title='Wavelet Transform for our series thing'
to write the output to an Encapsulated PostScript file:
IDL> set_plot,'PS
IDL> DEVICE,/encapsul,/color,filename='test1.eps',xsize=5,ysize=5
IDL> stellarwave2,series,title='Another Title',/print,pc=0
IDL> DEVICE,/close
IDL> SET_PLOT,'X'
or, if you have TOGGLE.PRO in your path:
IDL> TOGGLE,filename='wavelet.ps',/landscape,/color
IDL> stellarwave2,series,title='Another Title',/print,pc=0
IDL> TOGGLE
CALLS:
ECLIPSFILTER.PRO, WAVELET.PRO, WAVE_SIGNIF.PRO
HISTORY:
Based on ECLIPSE.PRO by Eoghan O'Shea, QUB, 2000
Modified in stages by D. Williams for the SECIS eclipse data
(See /home/drw/idl/gen/stellarwave2.pro)
STELLARWAVE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STELLARWAVE
PURPOSE:
Calculate and display the wavelet (power) transform of a time series
(CURVE) with the time series above the plot for comparison with the
transform, and also show the global wavelet spectrum to the right,
since it represents the summation of the power transform over time,
and is therefore analogous to the Fourier transform of the series.
CALLING SEQUENCE:
stellarwave,curve,print=print,pc=pc,title=title,nocon=nocon,delt=delt,$
mother=mother,offset=offset
INPUTS:
CURVE - a 1-D time series, e.g. a light curve
INTERACTIVE INPUTS DURING EXECUTION:
The user is first asked for a maximum value for the low-pass filter
called by WAVE_EXAMPLE. For the SECIS data, an unfiltered time series
will be analysed by specifying half the data sampling rate of 44.2 Hz
(i.e. 22.1 Hz).
The second parameter requested is the significance (confidence)
level which the WAVELET function will calculate as a set of contours
in the power transform. Concentrations of power enclosed within these
contours will be significant to that level. E.g., if the user specifies
a value of 0.99 (i.e. 99%) then there is a 1% chance that the power
within the contours is due to noise.
KEYWORDS:
PRINT - if set, then set parameters applicable to printing to a
postscript file. NOTE: Does not actually set the display
to the PostScript device - this must be done manually.
PC - the plot colour for the contours and cone-of-influence
boundary and cross-hatching. This is a value from 0 to
255. In a monochromatic colour table (e.g. loadct,3 for
red temperature) 0 will be black, 255 will be white, and
any other colours will be somewhere in between (e.g.
scale linearly for colour tables 0,1,3, & 8;
logarithmically for colour table 9).
TITLE - a string, specifying the title over the wavelet transform
part of the display output.
NOCON - if set, then do not display either contours or the
cone-of-influence calculated by the WAVELET routine
OUTPUTS:
None, except for the display of the wavelet transform etc. to
either X windows (the default) or (optionally) the PostScript device.
EXAMPLES:
IDL> stellarwave,series,title='Wavelet Transform for our series thing'
to write the output to an Encapsulated PostScript file:
IDL> set_plot,'PS
IDL> DEVICE,/encapsul,/color,filename='test1.eps',xsize=5,ysize=5
IDL> stellarwave,series,title='Another Title',/print,pc=0
IDL> DEVICE,/close
IDL> SET_PLOT,'X'
or, if you have TOGGLE.PRO in your path:
IDL> TOGGLE,filename='wavelet.ps',/landscape,/color
IDL> stellarwave,series,title='Another Title',/print,pc=0
IDL> TOGGLE
CALLS:
ECLIPSFILTER.PRO, WAVELET.PRO, WAVE_SIGNIF.PRO
HISTORY:
Based on ECLIPSE.PRO by Eoghan O'Shea, QUB, 2000
Modified in stages by D. Williams for the SECIS eclipse data
(See /home/drw/idl/vtt/post_bbso/stellarwave.pro)
STELLARWAVE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STELLARWAVE
PURPOSE:
Calculate and display the wavelet (power) transform of a time series
(CURVE) with the time series above the plot for comparison with the
transform, and also show the global wavelet spectrum to the right,
since it represents the summation of the power transform over time,
and is therefore analogous to the Fourier transform of the series.
CALLING SEQUENCE:
stellarwave,curve,print=print,pc=pc,title=title,nocon=nocon,delt=delt,$
mother=mother,offset=offset
INPUTS:
CURVE - a 1-D time series, e.g. a light curve
INTERACTIVE INPUTS DURING EXECUTION:
The user is first asked for a maximum value for the low-pass filter
called by WAVE_EXAMPLE. For the SECIS data, an unfiltered time series
will be analysed by specifying half the data sampling rate of 44.2 Hz
(i.e. 22.1 Hz).
The second parameter requested is the significance (confidence)
level which the WAVELET function will calculate as a set of contours
in the power transform. Concentrations of power enclosed within these
contours will be significant to that level. E.g., if the user specifies
a value of 0.99 (i.e. 99%) then there is a 1% chance that the power
within the contours is due to noise.
KEYWORDS:
PRINT - if set, then set parameters applicable to printing to a
postscript file. NOTE: Does not actually set the display
to the PostScript device - this must be done manually.
PC - the plot colour for the contours and cone-of-influence
boundary and cross-hatching. This is a value from 0 to
255. In a monochromatic colour table (e.g. loadct,3 for
red temperature) 0 will be black, 255 will be white, and
any other colours will be somewhere in between (e.g.
scale linearly for colour tables 0,1,3, & 8;
logarithmically for colour table 9).
TITLE - a string, specifying the title over the wavelet transform
part of the display output.
NOCON - if set, then do not display either contours or the
cone-of-influence calculated by the WAVELET routine
OUTPUTS:
None, except for the display of the wavelet transform etc. to
either X windows (the default) or (optionally) the PostScript device.
EXAMPLES:
IDL> stellarwave,series,title='Wavelet Transform for our series thing'
to write the output to an Encapsulated PostScript file:
IDL> set_plot,'PS
IDL> DEVICE,/encapsul,/color,filename='test1.eps',xsize=5,ysize=5
IDL> stellarwave,series,title='Another Title',/print,pc=0
IDL> DEVICE,/close
IDL> SET_PLOT,'X'
or, if you have TOGGLE.PRO in your path:
IDL> TOGGLE,filename='wavelet.ps',/landscape,/color
IDL> stellarwave,series,title='Another Title',/print,pc=0
IDL> TOGGLE
CALLS:
ECLIPSFILTER.PRO, WAVELET.PRO, WAVE_SIGNIF.PRO
HISTORY:
Based on ECLIPSE.PRO by Eoghan O'Shea, QUB, 2000
Modified in stages by D. Williams for the SECIS eclipse data
(See /home/drw/idl/gen/stellarwave.pro)
STEPIND[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: stepind
PURPOSE: step through a sequence of nested indicies
USEAGE: result=stepind(ic,n1,i1,n2,i2,n3,i3,n4,i4)
DISCUSSION:
each time stepind is called a single character is read from
the keyboard. The value of the character controls how the
the control index 'ic' is incremented, as follows:
'g' set index to 0
'G' set index to total number of elements -1
'b' decriminate index by one
' ' (space bar) increment index by one
'1' increment index by one
'2' increment index by n1 (increment index i2 by 1)
'3' increment index by n1*n2 (increment index i3 by 1)
'4' increment index by n1*n2*n3 (increment index i4 by 1)
'q' return zero
INPUT:
ic one dimensional index. decremented or incrimated by
LMB or MMB, respectively. if the starting value of ic
ic is -1, no delay occurs before the plot
n1 number of elements in first dimension
i1 index for first dimension
n2 number of elements in second dimension
i2 index for second dimension
etc
OUTPUT:
result logical flag, 0, unless 'q' is entered at keyboard
EXAMPLE:
;;
ic=-1 & & x=5*(findgen(360)-180)*!dtor
e=exp(-(x/(360*!dtor))^2) & phs=10.*!dtor
while stepind(ic,36) do plot,x,e*sin(x+ic*phs),title=string(ic*phs)
;;
while stepind(ic,36) do plot,x,e*sin(x+ic*phs),title=string(ic*phs)
;;
s=1
while stepind(ic,36) do plot,x,e*sin(x+ic*phs),title=string(ic*phs)
;;;
ic=-1
!p.multi=0
x=findrng(-5,5,100) & fmt='("f(",i1,", ",i2,")")'
while stepind(ic,10,i1,5,i2) do plot,x,exp(-(x/(1.+i1))^2)*cos(i2*x),titl=string(f=fmt,i1,i2)
;;
AUTHOR: Paul Ricchiazzi 22 Sep 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/stepind.pro)
STEPIND[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: stepind
PURPOSE: step through a sequence of nested indicies
USEAGE: result=stepind,ic,n1,i1,n2,i2,n3,i3,n4,i4,n5,i5,n6,i6
INPUT:
ic one dimensional index. incremented or decrimated by
LMB or MMB, respectively. if the starting value of ic
ic is -1, no delay occurs before the plot
n1 number of elements in first dimension
i1 index for first dimension
n2 number of elements in second dimension
i2 index for second dimension
etc
KEYWORD INPUT
nowait STEPIND returns immediately if button is in down state
step a named variable, if set to non-zero value STEP causes
STEPIND to return immediately. The initial value of STEP
determines wheather the first call to STEPIND will return
incremented indicies (STEP>0) or decremented indicies (step<0)
After the STEPIND where loop is started the sign of STEP
is toggled by the left or middle mouse buttons.
OUTPUT:
result logical flag, 0 if RMB is pressed, 1 otherwise
EXAMPLE:
ic=-1 & step=1 & x=5*(findgen(360)-180)*!dtor
s=exp(-(x/(360*!dtor))^2) & phs=10.*!dtor
while stepind(ic,36) do plot,x,s*sin(x+ic*phs),title=string(ic*phs)
while stepind(ic,36,/nowait) do plot,x,s*sin(x+ic*phs),title=string(ic*phs)
while stepind(ic,36,step=step) do plot,x,s*sin(x+ic*phs),title=string(ic*phs)
AUTHOR: Paul Ricchiazzi 22 Sep 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/stepind.pro)
STEP_CT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: step_ct
USEAGE: step_ct, range, inc, cs, nbotclr=nbotclr
step_ct, /off
PURPOSE: Discreetizes color scale at given numerical intervals.
NOTE: the rgb color value of the top color scale index is
not changed.
INPUT:
range array or vector which specifies range of physical values,
e.g., [amin,amax]
inc number scale increment
cs a floating point number between -1.0 to +1.0 that
translates the color table a fraction of a color step
higher (cs > 1) or lower (cs < -1). It has its most
noticeable effect when the number of steps is small,
because in this case a single step is usually a
significant change in color value. (default = 0)
nbotclr starting color index
off restore original unquantized color table,
no other input is required when this keyword is set
EXAMPLE
loadct,0
tvlct,r,g,b,/get
plot,r,xmargin=[10,20],/yst=1
color_key,range=[0,255],inc=20
range=[0,255]
inc=20
step_ct,range,inc
tvlct,r,g,b,/get
oplot,r,li=3
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group
UCSB
REVISIONS:
21sep93: fixed case of range spanning zero (see shiftup)
(See /home/drw/idl/esrg/step_ct.pro)
STEP_CT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: step_ct
USEAGE: step_ct, range, inc, cs, nbotclr=nbotclr
step_ct, /off
PURPOSE: Discreetizes color scale at given numerical intervals.
NOTE: the rgb color value of the top color scale index is
not changed.
INPUT:
range array or vector which specifies range of physical values,
e.g., [amin,amax]
inc number scale increment
cs a floating point number between -1.0 to +1.0 that
translates the color table a fraction of a color step
higher (cs > 1) or lower (cs < -1). It has its most
noticeable effect when the number of steps is small,
because in this case a single step is usually a
significant change in color value. (default = 0)
nbotclr starting color index
off restore original unquantized color table,
no other input is required when this keyword is set
EXAMPLE
loadct,0
tvlct,r,g,b,/get
plot,r,xmargin=[10,20],/yst=1
color_key,range=[0,255],inc=20
range=[0,255]
inc=20
step_ct,range,inc
tvlct,r,g,b,/get
oplot,r,li=3
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group
UCSB
REVISIONS:
21sep93: fixed case of range spanning zero (see shiftup)
(See /home/drw/idl/old.esrg/step_ct.pro)
STRCNT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STRCNT
PURPOSE:
Count number of occurrences of a substring in a string.
CATEGORY:
text/strings
CALLING SEQUENCE:
num = strcnt(strn, substring, [pos])
INPUTS:
string -- The string in which to count occurences. in
substring -- The substring to count occurrences of. in
pos -- the position at which to begin the search. [in]
If not supplied, start at beginning of
string.
KEYWORD PARAMETERS:
/HELP -- Print useful message and return.
OUTPUTS:
num -- Number of occurances of substring in string. out
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
Overlapping occurances are not counted separately. For
example, counting occurances of 'bb' in 'blah bbb' returns one
occurance.
EXAMPLE:
MODIFICATION HISTORY:
$Id: strcnt.pro,v 1.3 1996/06/14 20:00:27 mcraig Exp $
$Log: strcnt.pro,v $
Revision 1.3 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.2 1996/05/09 00:22:17 mcraig
Added fast processing using BYTE arrays if we are counting occurences of
a single character. Added error handling.
Revision 1.1 1996/01/31 18:47:37 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/strcnt.pro)
STREP
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: strep
PURPOSE: replace all instances of TARGET in STR with REPLACE
USEAGE: result=strep(str,target,replace)
INPUT:
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 15 Oct 98
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/strep.pro)
STRIP_FN[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STRIP_FN
PURPOSE:
Return a filename stripped of all directory information.
CALLING SEQUENCE:
result = strip_fn(filename)
INPUTS:
filename filename to be stripped. Can be scalar or vector.
OPTIONAL INPUTS:
OUTPUTS:
stripped filename. Same type (vector/scalar) as input filename.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke 8/12/93
MODIFICATION HISTORY:
JAH 8/13/93 Added filename vector capability.
(See /home/drw/idl/esrg/strip_fn.pro)
STRIP_FN[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STRIP_FN
PURPOSE:
Return a filename stripped of all directory information.
CALLING SEQUENCE:
result = strip_fn(filename)
INPUTS:
filename filename to be stripped. Can be scalar or vector.
OPTIONAL INPUTS:
OUTPUTS:
stripped filename. Same type (vector/scalar) as input filename.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke 8/12/93
MODIFICATION HISTORY:
JAH 8/13/93 Added filename vector capability.
(See /home/drw/idl/old.esrg/strip_fn.pro)
STRMATCH[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: strmatch
PURPOSE: check for string match to a wild card specification
USEAGE: 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
(See /home/drw/idl/esrg/strmatch.pro)
STRMATCH[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: strmatch
PURPOSE: check for string match to a wild card specification
USEAGE: 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
(See /home/drw/idl/old.esrg/strmatch.pro)
STRPACK
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE:
Convert to string by executing STRING and STRCOMPRESS
INPUTS:
input variable (any type) to be converted to string
OPTIONAL INPUTS:
format optional format statement ala FORTRAN
OUTPUTS:
Returns string, compressed.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke 06/24/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/strpack.pro)
STRREP
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: strrep
PURPOSE: replace all instances of character chro with chrn in string str
USEAGE: result=strrep(str,chro,chrn)
INPUT:
str input string
chro old character
chrn new character, if not specified then chro is removed from str
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
;;
print,strrep('this;is;an;example',';',' ')
print,strrep('this;is;an;example',';')
;;
AUTHOR: Paul Ricchiazzi 09 Jan 01
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/strrep.pro)
STRTRANS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STRTRANS
PURPOSE:
Translate all occurences of one substring to another.
CATEGORY:
text/strings
CALLING SEQUENCE:
new = strtrans(oldstr,from,to,ned)
INPUTS:
oldstr -- string on which to operate. in
May be an array.
from -- substrings to be translated. May be in
an array.
to -- what strings in from should be in
translated to. May be an array.
KEYWORD PARAMETERS:
/HELP -- Set this to print useful message and
exit.
OUTPUTS:
new -- Translated string. Array if oldstr is out
an array.
ned -- number of substitutions performed in out
oldstr. Array if oldstr is an array.
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
- Any of old, from, and to can be arrays.
- from and to must have the same number of elements.
EXAMPLE:
inp='Many*bad!chars+in_here'
from=['*','!','+','_']
to =[' ',' ',' ',' ']
out = strtrans(inp,from,to,ned)
Will produce out='Many bad chars in here', and set ned to 4.
MODIFICATION HISTORY:
$Id: strtrans.pro,v 1.3 1996/06/14 20:00:27 mcraig Exp $
$Log: strtrans.pro,v $
Revision 1.3 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.2 1996/05/09 00:22:17 mcraig
Sped up significantly by using str_sep to handle the translation. No longer
relies on routines fromother user libraries.
Revision 1.1 1996/01/31 18:47:37 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/strtrans.pro)
STRWHERE
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: strwhere
PURPOSE: a "where" operator for strings matching a set of string
wild cards
USEAGE: result=strwhere(starr,wildcard)
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 = '|')
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:
(See /home/drw/idl/esrg/strwhere.pro)
STR_SIZE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STR_SIZE
PURPOSE:
The purpose of this function is to return the proper
character size to make a specified string a specifed
width in a window. The width is specified in normalized
coordinates. The function is extremely useful for sizing
strings and labels in resizeable graphics windows.
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:
Graphics Programs, Widgets.
CALLING SEQUENCE:
thisCharSize = STR_SIZE(thisSting, targetWidth)
INPUTS:
thisString: This is the string that you want to make a specifed
target size or width.
OPTIONAL INPUTS:
targetWidth: This is the target width of the string in normalized
coordinates in the current graphics window. The character
size of the string (returned as thisCharSize) will be
calculated to get the string width as close as possible to
the target width. The default is 0.25.
KEYWORD PARAMETERS:
INITSIZE: This is the initial size of the string. Default is 1.0.
STEP: This is the amount the string size will change in each step
of the interative process of calculating the string size.
The default value is 0.05.
OUTPUTS:
thisCharSize: This is the size the specified string should be set
to if you want to produce output of the specified target
width. The value is in standard character size units where
1.0 is the standard character size.
EXAMPLE:
To make the string "Happy Holidays" take up 30% of the width of
the current graphics window, type this:
XYOUTS, 0.5, 0.5, ALIGN=0.5, "Happy Holidays", $
CHARSIZE=STR_SIZE("Happy Holidays", 0.3)
MODIFICATION HISTORY:
Written by: David Fanning, 17 DEC 96.
Added a scaling factor to take into account the aspect ratio
of the window in determing the character size. 28 Oct 97. DWF
Added check to be sure hardware fonts are not selected. 29 April 2000. DWF.
Added a pixmap to get proper scaling in skinny windows. 16 May 2000. DWF.
Forgot I can't do pixmaps in all devices. :-( Fixed. 7 Aug 2000. DWF.
(See /home/drw/idl/aux/str_size.pro)
STR_TOKEN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
STR_TOKEN
PURPOSE:
Retrieve portion of string up to token.
CATEGORY:
text/strings
CALLING SEQUENCE:
new = str_token( old, token )
INPUTS:
old -- String to be split. Contains text after in, out
token on output.
token -- Token to use in splitting old. in
KEYWORD PARAMETERS:
/TRIM -- set to remove leading blanks from old
before returning.
/HELP -- print useful message and exit.
OUTPUTS:
new -- portion of string up to token. out
old -- portion of old after token. out, in
COMMON BLOCKS:
SIDE EFFECTS:
Input parameter old is modified.
NOTES:
Token may be one or more characters.
If token is not found, returns old and sets old to ''.
EXAMPLE:
If old is 'foo44 bar', then str_token( old, '44' ) would return
'foo', and upon return, old will be left with ' bar'. If /TRIM
were set, old would be 'bar' on return.
If old='xyz', then new=str_token(old,'a') would return with
new='xyz' and old=''.
THANKS:
To D. Linder who wrote GETTOK, part of the goddard library,
upon which this is based.
MODIFICATION HISTORY:
$Id: str_token.pro,v 1.1 2000/06/14 19:09:22 mcraig Exp $
$Log: str_token.pro,v $
Revision 1.1 2000/06/14 19:09:22 mcraig
Changed name of strtok str_token to avoid conflict in IDL 5.3.
Revision 1.3 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.2 1996/05/09 00:22:17 mcraig
Added built in help.
Revision 1.1 1996/01/31 18:47:37 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/str_token.pro)
SUBCELL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SUBCELL
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Finds the position of a subwindow within a reference window.
CALLING SEQUENCE:
sub = subcell(panel, refposition)
DESCRIPTION:
SUBCELL finds the position of a subwindow within another window.
This could be useful in cases where the position of one window is
specified relative to another one.
When plotting, one often wants to describe the position of the
plot box with respect to another box on the screen. In that
respect, the reference window can be thought of as a virtual
display, and the SUBPOS as virtual a position on that display.
The SUBCELL function transforms the relative coordinates of the
virtual position back to normal screen coordinates.
INPUTS:
SUBPOS - A four-element array giving the position of the
subwindow, *relative* to a reference window given by
POSITION. Given as [XS1, YS1, XS2, YS2], which describes
the lower left and upper right corners of the subwindow.
Each value is a number between zero and one, zero being
the lower/left and one being the upper/right corners of
the reference window.
POSITION - A four-element array giving the position of the
reference window on the screen. Equivalent to the
graphics keyword of the same name.
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
MARGIN - If set, then a default value for SUBPOS is found using
the DEFSUBCELL function.
RETURNS:
The position of the subwindow, in normal coordinates.
PROCEDURE:
EXAMPLE:
SEE ALSO:
DEFSUBCELL, SUBCELLARRAY
EXTERNAL SUBROUTINES:
DEFSUBCELL
MODIFICATION HISTORY:
Written, CM, 1997
Added copyright notice, 25 Mar 2001, CM
$Id: subcell.pro,v 1.2 2001/03/25 18:54:31 craigm Exp $
(See /home/drw/idl/aux/markwardt/subcell.pro)
SUBCELLARRAY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SUBCELLARRAY
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Returns a set of subcells, suitable for creating a matrix of plots.
CALLING SEQUENCE:
subcellarray, xdivs, ydivs, newpanels, newsubpanels
DESCRIPTION:
SUBCELLARRAY generates a group of subcells. The subcells are
useful for plotting a matrix of windows.
This procedure takes a list of subdivisions in X and Y,
designating the subdivision of the plot into num(X) X panels and
num(Y) Y panels, and creates a new batch of panels and subpanels,
which can be used in the individual plot commands of the array.
INPUTS:
XDIVS - list of subdivisions in the X-direction. Example: [1,1,2]
will create three panels in the X-direction such that
their sizes are in the ratio of 1:1:2. These are the
subdivisions of the SUBPANEL, the inner plot box boundary,
not divisions of the PANEL, which is the boundary that
includes axis labels.
YDIVS - same, for Y direction
OPTIONAL INPUTS:
NONE
INPUT KEYWORD PARAMETERS:
PANEL - Original panel (outer margin) of plot. Default is to fill
screen.
SUBPANEL - Original subpanel (inner margin) of plot. Default is
to use defsubcell().
OUTPUTS:
NEWPANELS - output array of panels. The output is 4 x M x N where
M is the number of X divisions and N is the number of
Y divisions.
NEWSUBPANELS - output array of subpanels, with correct adjustment
for margins, same format as NEWPANELS.
PROCEDURE:
EXAMPLE:
See PLOTCUBE for an example usage.
SEE ALSO:
DEFSUBCELL, SUBCELLARRAY, PLOTCUBE
EXTERNAL SUBROUTINES:
DEFSUBCELL, SUBCELL
MODIFICATION HISTORY:
Written, CM, 1997
Added copyright notice, 25 Mar 2001, CM
$Id: subcellarray.pro,v 1.3 2003/10/30 05:19:58 craigm Exp $
(See /home/drw/idl/aux/markwardt/subcellarray.pro)
SUB_SUP_IDL[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SUB_SUP_IDL
PURPOSE:
Return the proper IDL font positioning command for TeX
sub/superscripts.
CATEGORY:
CALLING SEQUENCE:
fnt = sub_sup_idl( strn )
INPUTS:
strn -- Either '^' or '_', the TeX super/subscript in
characters
KEYWORD PARAMETERS:
/FORCE_UD -- Set this to use !U/!D instead of !E/!I for
sub/superscripts .
OUTPUTS:
fnt -- Either '!U' or !E' for superscripts, out
or '!D' or '!I' for subscripts.
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
EXAMPLE:
LIBRARY FUNCTIONS CALLED:
MODIFICATION HISTORY:
$Id: sub_sup_idl.pro,v 1.1 1996/01/31 18:47:37 mcraig Exp $
$Log: sub_sup_idl.pro,v $
Revision 1.1 1996/01/31 18:47:37 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
(See /home/drw/idl/aux/sub_sup_idl.pro)
SUB_SUP_IDL[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SUB_SUP_IDL
PURPOSE:
Return the proper IDL font positioning command for TeX
sub/superscripts.
CATEGORY:
TeXtoIDL
CALLING SEQUENCE:
fnt = sub_sup_idl( strn )
INPUTS:
strn -- Either '^' or '_', the TeX super/subscript in
characters
KEYWORD PARAMETERS:
/FORCE_UD -- Set this to use !U/!D instead of !E/!I for
sub/superscripts .
/HELP -- Set to print useful message and exit.
OUTPUTS:
fnt -- Either '!U' or !E' for superscripts, out
or '!D' or '!I' for subscripts.
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
Used only by translate_sub_super. Should be kept in same
file.
EXAMPLE:
MODIFICATION HISTORY:
$Id: translate_sub_super.pro,v 1.5 2000/06/14 19:09:22 mcraig Exp $
$Log: translate_sub_super.pro,v $
Revision 1.5 2000/06/14 19:09:22 mcraig
Changed name of strtok str_token to avoid conflict in IDL 5.3.
Revision 1.4 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.3 1996/05/09 00:22:17 mcraig
Changed some function calls to reflect changes in those functions, moved
some code out of the main loop that didn't need to be there, added
documentation.
Revision 1.1 1996/01/31 18:47:37 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/translate_sub_super.pro)
SUMERCAT
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT
sumer
NAME
sumercat
PURPOSE
read sumer catalogs and return observations made around the specified date and
time
CALLING SEQUENCE
sumerstr=sumercat(971211,1220)
INPUT
date,time
OUTPUT
structure containing sumer observations before and after specified time
OPTIONAL OUTPUT
n/a
OPTIONAL KEYWORD INPUT
n/a
RESTRICTION
CALLS
slog_rdlog
HISTORY
written Carl Foley @ MSSL - Wed Dec 11 12:07:13 GMT 2002
(See /home/drw/idl/sumercat.pro)
SUNGLINT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: sunglint
PURPOSE: compute lat-lon of point on earths surface which will
reflect sunlight to satellite observation point by
purely specular reflection.
USEAGE: sunglint,doy,time,lat,lon,alt,glat,glon
INPUT:
doy day of year (scalor)
time time UTC (hours) (scalor)
lat satellite latitude (scalor)
lon satellite longitude (scalor)
alt satellite altitude (scalor)
OUTPUT
glat sunglint latitude
glon sunglint longitude
gnadir sunglint nadir angle
gaz sunglint azimuth
if satellite is on the night side
glat and glon are returned as 1000,1000
if parameters GLAT, GLON, GNADIR and GAZ are left off the argument
list then SUNGLINT prints these parameters to the terminal
KEYWORD INPUT:
EXAMPLE:
sunglint,129,21.5,25,-120,800,glat,glon,gnadir,gaz
print,f='(4f10.2)',glat,glon,gnadir,gaz
sunglint,80,12,90.0,0,1000 ; sunlat =0 sunlon=0
sunglint,80,12,90.0,0,10000 ; note how glat approaches
sunglint,80,12,90.0,0,100000 ; 45 at alt is increased
sunglint,80,12,90.0,0,1000000 ;
REVISIONS:
author: Paul Ricchiazzi dec 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/sunglint.pro)
SUNGLINT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: sunglint
PURPOSE: compute lat-lon of point on earths surface which will
reflect sunlight to satellite observation point by
purely specular reflection.
USEAGE: sunglint,doy,time,lat,lon,alt,glat,glon
INPUT:
doy day of year (scalor)
time time UTC (hours) (scalor)
lat satellite latitude (scalor)
lon satellite longitude (scalor)
alt satellite altitude (scalor)
OUTPUT
glat sunglint latitude
glon sunglint longitude
gnadir sunglint nadir angle
gaz sunglint azimuth
if satellite is on the night side
glat and glon are returned as 1000,1000
if parameters GLAT, GLON, GNADIR and GAZ are left off the argument
list then SUNGLINT prints these parameters to the terminal
KEYWORD INPUT:
EXAMPLE:
sunglint,129,21.5,25,-120,800,glat,glon,gnadir,gaz
print,f='(4f10.2)',glat,glon,gnadir,gaz
sunglint,80,12,90.0,0,1000 ; sunlat =0 sunlon=0
sunglint,80,12,90.0,0,10000 ; note how glat approaches
sunglint,80,12,90.0,0,100000 ; 45 at alt is increased
sunglint,80,12,90.0,0,1000000 ;
REVISIONS:
author: Paul Ricchiazzi dec 95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/sunglint.pro)
SUPERPIX[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: superpix
USEAGE: superpix, a, binsz, abin, sbin
superpix, a, binsz, abin, sbib, /align, /compare
PURPOSE: compute super pixel average and standard deviation
of a scene
INPUT:
a image array
binsz A scalar specifying the number of horizontal and
vertical sub-pixels in one super pixel.
BINSZ must be an odd integer.
align If set, output arrays are REBINed back up to the
original size and output array cell centers are aligned
with input array cell centers.
compare if set, compare A and ABIN with the FLICK procedure
OUTPUT:
abin mean value of superpixel at superpixel cell centers
sbin standard deviation of superpixel at superpixel
cell centers.
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/esrg/superpix.pro)
SUPERPIX[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: superpix
USEAGE: superpix, a, binsz, abin, sbin
superpix, a, binsz, abin, sbib, /align, /compare
PURPOSE: compute super pixel average and standard deviation
of a scene
INPUT:
a image array
binsz A scalar specifying the number of horizontal and
vertical sub-pixels in one super pixel.
BINSZ must be an odd integer.
align If set, output arrays are REBINed back up to the
original size and output array cell centers are aligned
with input array cell centers.
compare if set, compare A and ABIN with the FLICK procedure
OUTPUT:
abin mean value of superpixel at superpixel cell centers
sbin standard deviation of superpixel at superpixel
cell centers.
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/old.esrg/superpix.pro)
SURFDEMO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SURFDEMO
PURPOSE:
This procedure demonstrates the use of the surface plotting
functions ONESURF and TWOSURF.
SURFDEMO's user interface is very crude: it describes the
next plot on the output log window and then asks the user whether
to display it or not. Typing any word beginning with 'n' or 'N'
skips to the next plot, typing anything else (including just a
return) plots that example and then proceeds to the next plot.
CATEGORY:
Graphics.
CALLING SEQUENCE:
SURFDEMO
INPUTS:
None.
KEYWORD PARAMETERS:
SURFONE: use this keyword to keep a copy of the demo surface
surfone (a gaussian hat).
SURFTWO: use this keyword to keep a copy of the demo surface
surftwo (a saddle shape).
COMMON BLOCKS:
None.
SIDE EFFECTS:
Sets the graphics system variable !p.t3d: the current 3d->2d
transformation
Sets the light direction for light shading
On 8-bit displays the colour map is altered
RESTRICTIONS:
None.
EXAMPLE:
Display the example plots and retain the surface data arrays
SURFDEMO, SURFONE=array1, SURFTWO=array2
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 - adapted to use _EXTRA keyword in ONESURF and TWOSURF
(See /home/drw/idl/aux/surfdemo.pro)
SURFGRID
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SURFGRID
PURPOSE:
This procedure is used to overlay or mask an image with a grid
contained in a second, 8-bit image.
The procedure's behaviour is set by the keyword GRIDCODE. If
GRIDCODE=1 (the default), for every pixel in the grid image which
is not filled with the background colour, the equivalent pixel in
the main image is set to a user-specified colour. If GRIDCODE=2,
the grid image is used to mask the main image so that every pixel
which is equal to the background colour in the grid image has its
corresponding pixel in the main image set to the background colour.
CATEGORY:
Graphics, Surface Plotting
CALLING SEQUENCE:
SURFGRID(image, gridpic)
INPUTS:
IMAGE: The image to be ovelaid or masked. IMAGE should be a
pixel-interleaved 24-bit image of type BYTARR(3, x, y).
GRIDPIC: The image containing the grid. GRIDPIC should be an
8-bit image of type BYTARR(x,y).
KEYWORD PARAMETERS:
GRIDCODE: If GRIDCODE=1 (the default) the grid in GRIDPIC is
overlaid onto IMAGE: every pixel in GRIDPIC whose
value is not equal to BGIDX has its corresponding
pixel in IMAGE set equal to GRIDCOL.
If GRIDCODE=2 the grid in GRIDPIC is used as a mask:
every pixel in GRIDPIC whose value is equal to BGIDX
has its corresponding pixel in IMAGE set equal to
BGCOL.
GRIDCOL: The rgb colour triple to use for overlaid grids.
GRIDCOL should be of type BYTARR(3). The default is
[0,0,0], black.
BGIDX: The colour index that denotes background in GRIDPIC
The default is the current value stored in the graphics
system variable !p.background (default: 0).
BGCOL: The rgb colour triple to use as the background colour
when masking. The default is [0,0,0], black.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
Overlay a red grid on an existing image:
surfgrid, image, gridpic, gridcol=[255,0,0]
Mask an image, setting the background to a dark grey:
surfgrid, image, gridpic, gridcode=2, bgcol=[30,30,30]
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.
(See /home/drw/idl/aux/surfgrid.pro)
SWALLOWGRID
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
SWALLOWGRID
PURPOSE:
to spatially average images in a data cube by specifying
the radius of pixels around each pixel whose values
will be added to the value of the corresponding central
pixel in the output array.
USAGE:
result=swallowgrid(grid,radius)
INPUTS:
GRID - image cube of X x Y pixels times Z frames.
RADIUS -
HISTORY:
Author - David Williams, QUB.
version 1.0 - Originally a routine, rather than a function,
it was called swallowgrid1. Now deprecated due to verbosity.
version 1.1 - 29/9/00: Changed format to make it more tidy and
return a neater output. Added RADIUS keyword after change
to a function format.
(See /home/drw/idl/secis/swallowgrid.pro)
SWALLOWGRID1
[Previous Routine]
[Next Routine]
[List of Routines]
PRO swallowgrid1,grid,lc_array,catch=catch
(See /home/drw/idl/secis/swallowgrid1.pro)
SWAP_BYTES
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
SWAP_BYTES (General IDL Library 01) 25-APR-80
*CLASS:
Conversion
*CATEGORY:
*PURPOSE:
To perform the byte reordering required for conversion of
integer, longword, floating point, or double precision
variables between various machine representations.
*CALLING SEQUENCE:
SWAP_BYTES,BVAR,PARAM
*PARAMETERS:
BVAR (REQ) (I/O) (0 1) (B)
byte representation of variable in which bytes will
be reordered
PARAM (REQ) (I/O) (0) (I)
parameter governing the byte reordering options
2: Even and Odd bytes are swapped
4: The order of each group of four bytes is reversed
8: The order of each group of eight bytes is reversed
*EXAMPLES:
*SUBROUTINES CALLED:
PARCHECK
*FILES USED:
*SIDE EFFECTS:
The byte representation of the original vector or scalar is
replaced by the reordered bytes
*RESTRICTIONS:
Input must be of byte type. All conversion operations should
be done on the byte stream BEFORE the variables are read by
IDL as integer, longword, floating point, or double precision.
Prematurely reading a byte stream as one of these data types
can cause conflicts with reserved values (NaN, infinity, and
reserved operand faults ) which will corrupt the final data.
*NOTES:
tested with IDL Version 2.0.10 (sunos sparc) 3 Oct 91
tested with IDL Version 2.1.0 (ultrix mipsel) 3 Oct 91
tested with IDL Version 2.1.0 (vms vax) 3 Oct 91
*PROCEDURE:
Three different byte reordering schemes are required for the
conversion of integer, longword, floating point, and double
precision data between the machine formats used by SunOS,
DEC ULTRIX, and VAX VMS. All conversions require the
interchange of even and odd byte elements. Longword and
floating point conversion requires an additional byte reordering
in which the order of the four bytes which represent a single
longword or floating point value are reversed. Double precision
conversion requires that the order of the eight bytes which
represent a double precision value are reversed.
*MODIFICATION HISTORY:
Apr. 25 1980 D.J. Lindler initial program
Mar. 21 1988 CAG add VAX RDAF-style prolog, add procedure
call listing, and check for parameters.
Feb. 09 1988 RWT change suggested by D. Lindler to handle
longword integers
Jun. 14 1989 RWT modify for SUN IDL, add optional parameter,
and allow swapping of bytes in a byte array
May 30 1990 RWT add changes by Gitta Domik for allowing
TYPE = 8.
Feb 11 1991 GRA Changed name to SWAP_BYTES, and rewrote to
work with byte variable types only.
Removed call to PARCHECK, and required that
PARAM be defined, rather that determined by
the IDL function SIZE. Changed the values of
PARAM to equal the number of bytes considered
as a group, i.e. 2, 4, and 8.
Mar 28 1991 PJL added PARCHECK; converted to lowercase
Jun 21 1991 GRA cleaned up; tested on SUN, DEC, VAX;
updated prolog.
Aug 15 1991 A.Veale converted to use IDL BYTEORDER calls; tested
on DEC
Oct 3 1991 GRA tested on SUN, DEC, and VAX.
(See /home/drw/idl/icur/swap_bytes.pro)
SWATH[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: swath
PURPOSE: plot raw data (not on a regular lat-lon grid) from a satellite
pass on a predifined ploting grid (usually setup by map_set)
USEAGE: swath,image,lon,lat,thick=thick,nlevels=nlevels, $
colors=colors,outline=outline
INPUT:
image
two dimensional satellite data field. the first index
corresponds to cross-track sample number and the second
to the along-track line number.
lon
longitude array, same size as image
lat
latitude array, same size as image
KEYWORD INPUT:
thick
thickness of lines used to fill lines in swath
(The default is 3 for "X" and 10 for "ps")
colors
discreet set of colors used for each level in LEVELS.
nlevels
number of contour level values (if not set continuous colors are used)
range
physical range of image (2 element vector)
outline
color index used to draw swath outline. If not set, a swath
outline is not drawn.
KEYWORD OUTPUT:
colors
a vector of color indicies which can be used as input to
color_key. This is required to coordinate the color key with the
discreet colors drawn by SWATH. It is not required when nlevels
is not set. COLORS is returned if the input value of COLORS is a
named variable with 0 or 1 elements.
DISCUSSION:
Each individual satellite line is drawn as a separate call
to PLOTS. Hence, there may be gaps between lines. This
can be controlled by adjusting the thickness of the drawn
lines. If the the printer has greater resolution than the
screen or if the number of lines is not large, you may have to
increase THICK to avoid getting gaps between lines on your
hardcopy.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
y=findrng(-8500,8500,400) ; satelite data coordinates (400 lines)
x=findrng(-1012,1012,100) ; (100 samples)
gengrid,x,y
incl=98 ; orbital inclination
az=atan(x,y)/!dtor ; azimuth (clockwise around track direction)
az=(az+90-incl+360) mod 360
rng=sqrt(x^2+y^2) ; range (from equator crossing)
compass,0,0,rng,az,alat,alon,/to_latlon
range=[0,1]
colors=0
map_set,0,0,/orth,pos=boxpos(/asp)
for i=0,5 do swath,abs(sin(!pi*x/2000)*sin(!pi*y/2000)), $
alon+25*i-50,alat,nlev=11,colors=colors,/outline
map_continents
map_grid
color_key,range=range,colors=colors
map_set,0,0,/cyl,pos=boxpos(/asp)
for i=0,5 do swath,abs(sin(!pi*x/2000)*sin(!pi*y/2000)), $
alon+30*i-60,alat,nlev=11,colors=colors,outline=255
map_continents
map_grid
color_key,range=range,colors=colors
AUTHOR: Paul Ricchiazzi 20 Dec 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/swath.pro)
SWATH[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: swath
PURPOSE: plot raw data (not on a regular lat-lon grid) from a satellite
pass on a predifined ploting grid (usually setup by map_set)
USEAGE: swath,image,lon,lat,thick=thick,nlevels=nlevels, $
colors=colors,outline=outline
INPUT:
image
two dimensional satellite data field. the first index
corresponds to cross-track sample number and the second
to the along-track line number.
lon
longitude array, same size as image
lat
latitude array, same size as image
KEYWORD INPUT:
thick
thickness of lines used to fill lines in swath
(The default is 3 for "X" and 10 for "ps")
colors
discreet set of colors used for each level in LEVELS.
nlevels
number of contour level values (if not set continuous colors are used)
range
physical range of image (2 element vector)
outline
color index used to draw swath outline. If not set, a swath
outline is not drawn.
KEYWORD OUTPUT:
colors
a vector of color indicies which can be used as input to
color_key. This is required to coordinate the color key with the
discreet colors drawn by SWATH. It is not required when nlevels
is not set. COLORS is returned if the input value of COLORS is a
named variable with 0 or 1 elements.
DISCUSSION:
Each individual satellite line is drawn as a separate call
to PLOTS. Hence, there may be gaps between lines. This
can be controlled by adjusting the thickness of the drawn
lines. If the the printer has greater resolution than the
screen or if the number of lines is not large, you may have to
increase THICK to avoid getting gaps between lines on your
hardcopy.
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
y=findrng(-8500,8500,400) ; satelite data coordinates (400 lines)
x=findrng(-1012,1012,100) ; (100 samples)
gengrid,x,y
incl=98 ; orbital inclination
az=atan(x,y)/!dtor ; azimuth (clockwise around track direction)
az=(az+90-incl+360) mod 360
rng=sqrt(x^2+y^2) ; range (from equator crossing)
compass,0,0,rng,az,alat,alon,/to_latlon
range=[0,1]
colors=0
map_set,0,0,/orth,pos=boxpos(/asp)
for i=0,5 do swath,abs(sin(!pi*x/2000)*sin(!pi*y/2000)), $
alon+25*i-50,alat,nlev=11,colors=colors,/outline
map_continents
map_grid
color_key,range=range,colors=colors
map_set,0,0,/cyl,pos=boxpos(/asp)
for i=0,5 do swath,abs(sin(!pi*x/2000)*sin(!pi*y/2000)), $
alon+30*i-60,alat,nlev=11,colors=colors,outline=255
map_continents
map_grid
color_key,range=range,colors=colors
AUTHOR: Paul Ricchiazzi 20 Dec 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/swath.pro)
SYMBOLS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: SYMBOLS
PURPOSE:
Create custom plotting symbols
CATEGORY:
CALLING SEQUENCE:
symbols,symbol_number,scale
INPUTS:
symbol_number=
1 = open circle
2 = filled circle
3 = arrow pointing right
4 = arrow pointing left
5 = arrow pointing up
6 = arrow pointing down
7 = arrow pointing up and left (45 degrees)
8 = arrow pointing down and left
9 = arrow pointing down and right.
10 = arrow pointing up and right.
11 through 18 are bold versions of 3 through 10
19 = horizontal line
20 = box
21 = diamond
22 = triangle
30 = filled box
31 = filled diamond
32 = filled triangle
Scale = size of symbols.
OPTIONAL INPUT PARAMETERS:
KEYWORD PARAMETERS:
Color = color of symbols
OUTPUTS:
OPTIONAL OUTPUT PARAMETERS:
COMMON BLOCKS:
SIDE EFFECTS:
The desired symbol is stored in the user buffer and
will be plotted if !P.PSYM = 8.
RESTRICTIONS:
PROCEDURE:
MODIFICATION HISTORY:
Jeff Bennett, U of Colorado, 198?
(See /home/drw/idl/esrg/symbols.pro)
TABINV
[Previous Routine]
[Next Routine]
[List of Routines]
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) LE X LT 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.
TABINV,WAVE,1150.0,I
FLUX( 0:FIX(I) ) = 0.
FUNCTIONS CALLED:
ISARRAY
REVISION HISTORY:
Adapted from the IUE RDAF January, 1988
More elegant code W. Landsman August, 1989
Adapted for ICUR, ISARRAY removed FMW 8/91
(See /home/drw/idl/icur/tabinv.pro)
TABLE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: table
PURPOSE: print a table of vectors in nicely formatted columns
USEAGE: table,p1,p2,p3,p4,p5,p6,p7,p8,p9,p10,p11,p12,f=f
INPUT:
p1,p2,... a set of vector quantities to print. all vectors must
be of the same length
KEYWORD INPUT:
f format specification string, E.G. 'f10.3,e11.2'
NOTE: don't provide a specification for the integer
subscript which appears in the first column. TABLE puts
it in automatically. Also, the format string need not
have opening and closing parenthesis, but its ok to put
them in.
index if set, the array indicies of the first parameter, p1,
are printed. This only has effect when p1 has dimension
greater than two. Indicies for array dimensions greater
than 5 are not printed.
EXAMPLE:
x=sqrt(findgen(20)+23)
y=sin(.1*x)
table,x,y ;
table,x,y,x+y,x-y,x*y,(x+y)*(x-y),x/y,f='7f10.3'
table,rebin(x,4,5),y,/index
table,rebin(x,5,4),y,/index
table,rebin(x,5,2,2),y,/index
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/table.pro)
TABLE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: table
PURPOSE: print a table of vectors in nicely formatted columns
USEAGE: table,p1,p2,p3,p4,p5,p6,p7,p8,p9,p10,p11,p12,f=f
INPUT:
p1,p2,... a set of vector quantities to print. all vectors must
be of the same length
KEYWORD INPUT:
f format specification string, E.G. 'f10.3,e11.2'
NOTE: don't provide a specification for the integer
subscript which appears in the first column. TABLE puts
it in automatically. Also, the format string need not
have opening and closing parenthesis, but its ok to put
them in.
index if set, the array indicies of the first parameter, p1,
are printed. This only has effect when p1 has dimension
greater than two. Indicies for array dimensions greater
than 5 are not printed.
EXAMPLE:
x=sqrt(findgen(20)+23)
y=sin(.1*x)
table,x,y ;
table,x,y,x+y,x-y,x*y,(x+y)*(x-y),x/y,f='7f10.3'
table,rebin(x,4,5),y,/index
table,rebin(x,5,4),y,/index
table,rebin(x,5,2,2),y,/index
author: Paul Ricchiazzi may94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/table.pro)
TAGSIZE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TAGSIZE
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Compute SIZE descriptors for each tag in a structure
CALLING SEQUENCE:
SIZES = TAGSIZE(STRUCT, N_TAGS=ntags, TAG_NAMES=tagnames,
STRUCTURE_NAME=structname, STATUS=status, LENGTH=length)
DESCRIPTION:
The TAGSIZE function determines the types and sizes of each tag in
a structure. This is not as easy as it may seem, because IDL
makes it very, *very* difficult to find out the true dimensions of
a structure element.
Here is a brief explanation. It is known that IDL drops trailing
dimensions of size 1 in many situations. Also, for structures
only, arrays of any dimensionality which have only one element are
RETURNED AS SCALARS. Thus, if you are doing any heavy duty work
with structures, copying and querying individual elements between
structures, etc., you will find that you will lose some crucial
dimensions which you can't normally regain.
TAGSIZE attempts to work around all of these limitations to
present the true dimensions of all elements in a structure.
It returns an 11xNTAGS array, which contains a SIZE-style vector
for each element in the structure. Eleven elements is the largest
array size needed to describe any IDL data type using SIZE. Thus,
to extract information about the second tag in structure X
(element number 1 starting from zero), you would use the following
code:
SIZES = TAGSIZE(X) ;; Extract type information from structure X
SIZE_1 = SIZES(*,1) ;; Extract type information about the 2nd element
SIZE_1 = SIZE_1(0:SIZE_1(0)+2) ;; Trim the array if desired
The last command is optional, but trims the resulting array to be
a true SIZE-style result.
TAGSIZE also has several convenience keywords to extract other
relevant information about a structure.
INPUTS:
STRUCTURE - any structure to examine. If the value is not a
structure then an error is reported.
KEYWORDS:
N_TAGS - upon return, the number of tags in the structure is
stored in this keyword.
TAG_NAMES - upon return, the names of each tag are stored in this
keyword, as an array of strings.
STRUCTURE_NAME - upon return, the name of the structure is stored
in this keyword. If the structure is anonymous
then the empty string ('') is returned.
LENGTH - upon return, the size in bytes of each tag element in the
structure is stored in this keyword, as an array of
integers.
STATUS - upon return, the status is stored in this keyword. A
value of 1 indicates success, 0 indicates failure.
RETURNS:
A two dimensional array, with dimensions LONARR(11,NTAGS),
containing the size information of all tag elements in the
structure. SIZES(*,i) is the SIZE-style vector for tag element i.
EXAMPLE:
Compute the sizes of the elements in X, defined here.
IDL> x = {a: [1], b: intarr(2,2), c: reform(strarr(2,1),2,1)}
IDL> help, /struct, x
** Structure <818c8b4>, 3 tags, length=28, refs=1:
A INT Array[1]
B INT Array[2, 2]
C STRING Array[2, 1]
IDL> print, byte(tagsize(x))
1 [1] 2 1 0 0 0 0 0 0 0
2 [2 2] 2 4 0 0 0 0 0 0
2 [2 1] 7 2 0 0 0 0 0 0
[ Array dimensions are emphasized with brackets ]
Compare this to the type information returned by HELP, which is
incorrect for tags A and C.
IDL> help, x.a, x.b, x.c
INT = 1
INT = Array[2, 2]
STRING = Array[2]
SEE ALSO:
TAG_NAMES, N_TAGS, SIZE, HELP, INPUTFORM, HELPFORM
MODIFICATION HISTORY:
Written, CM, 13 May 2000
Documented, 05 Jul 2000
Small documentation changes, CM, 31 Aug 2000
Signficant cleanup of HELP parsing, CM, 04 Dec 2000
Added case for array of structures with new parsing, CM 12 Jan
2001
$Id: tagsize.pro,v 1.4 2001/02/09 04:57:42 craigm Exp $
(See /home/drw/idl/aux/markwardt/tagsize.pro)
TAI_UTC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TAI_UTC
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:
Compute (TAI - UTC) time difference (i.e., leap seconds)
MAJOR TOPICS:
Time
CALLING SEQUENCE:
LEAP = TAI_UTC(JD_UTC) ;; or,
LEAP = TAI_UTC(JD_TAI, /INVERT)
DESCRIPTION:
The function TAI_UTC computes the difference between International
Atomic Time (TAI) and Universal Coordinated Time (UTC), in
seconds.
After 01 Jan 1972, the two time systems are synchronized, except
for a number of leap seconds added to account for the varying rate
of rotation of the earth. While TAI is a continuous atomic time
system, UTC is a civil time system which may have discontinuities
where leap seconds are introduced. This function computes the
differences between the two time systems.
The conversion from UTC to TAI is computed as:
JD_TAI = JD_UTC + TAI_UTC(JD_UTC)/86400
The inversion conversion, from TAI to UTC, is computed as:
JD_UTC = JD_TAI + TAI_UTC(JD_TAI, /INVERT)/86400
Here JD_UTC and JD_TAI are the UTC and TAI times measured in
Julian days respectively.
The introduction of leap seconds is not predictable, owing to the
non-linear processes that govern the rotation of the earth. The
International Earth Rotation Service determines when leap seconds
will be introduced. Thus, the user must download the history of
leap seconds. This file can be downloaded at the following URL:
ftp://maia.usno.navy.mil/ser7/tai-utc.dat
NOTE - the leap second file must be kept up to date as new leap
seconds are introduced. The file is kept internally in
memory, but is reloaded from disk at least once per day.
If the disk file is not available, then a copy of the file as
available from the USNO on 02 Jan 2002 is used, but a warning
message is printed.
PARAMETERS:
JD - time measured in Julian days. The time being converted
*from*.
RETURNS:
The number of seconds to be added to the input time, to arrive at
the desired time.
KEYWORD PARAMETERS:
INVERT - if set, then convert from TAI to UTC. If not set
(default), then convert from UTC to TAI.
EXAMPLE:
print, tai_utc(2451544.5d)
32.000000
REFERENCES:
Definition of leap seconds.
http://tycho.usno.navy.mil/leapsec.html
File containing leap seconds.
ftp://maia.usno.navy.mil/ser7/tai-utc.dat
SEE ALSO
TDB2TDT, SYSTIME, CALDAT, JULDAY
MODIFICATION HISTORY:
Written and Documented, CM, Dec 2001
Fixed array indexing errors when the requested time range falls in
the leap second period, and the input is an array; avoided use
of variable JDAY, which is a function clash for me, 02 Mar 2002,
CM
Added helpful usage message, CM, 15 Mar 2002
$Id: tai_utc.pro,v 1.4 2002/03/15 12:00:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/tai_utc.pro)
TAND[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TAND
PURPOSE:
Return the tangent of an angle specified in degrees rather than radians.
CALLING SEQUENCE:
x = tand(deg)
INPUTS:
angle angle in degrees
OPTIONAL INPUTS:
OUTPUTS:
Tangent of angle returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/esrg/tand.pro)
TAND[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TAND
PURPOSE:
Return the tangent of an angle specified in degrees rather than radians.
CALLING SEQUENCE:
x = tand(deg)
INPUTS:
angle angle in degrees
OPTIONAL INPUTS:
OUTPUTS:
Tangent of angle returned.
PROCEDURE
COMMON BLOCKS:
None.
NOTES
REFERENCES
AUTHOR and DATE:
Jeff Hicke Earth Space Research Group, UCSB 12/07/93
MODIFICATION HISTORY:
(See /home/drw/idl/old.esrg/tand.pro)
TDB2TDT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TDB2TDT
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:
Relativistic clock corrections due to Earth motion in solar system
MAJOR TOPICS:
Planetary Orbits
CALLING SEQUENCE:
corr = TDB2TDT(JD, TBASE=, DERIV=deriv)
DESCRIPTION:
The function TDB2TDT computes relativistic corrections that must
be applied when performing high precision absolute timing in the
solar system.
According to general relativity, moving clocks, and clocks at
different gravitational potentials, will run at different rates
with respect to each other. A clock placed on the earth will run
at a time-variable rate because of the non-constant influence of
the sun and other planets. Thus, for the most demanding
astrophysical timing applications -- high precision pulsar timing
-- times in the accelerating earth observer's frame must be
corrected to an inertial frame, such as the solar system
barycenter (SSB). This correction is also convenient because the
coordinate time at the SSB is the ephemeris time of the JPL
Planetary Ephemeris.
In general, the difference in the rate of Ti, the time kept by an
arbitrary clock, and the rate of T, the ephemeris time, is given
by the expression (Standish 1998):
dTi/dT = 1 - (Ui + vi^2/2) / c^2
where Ui is the potential of clock i, and vi is the velocity of
clock i. However, when integrated, this expression depends on the
position of an individual clock. A more convenient approximate
expression is:
T = Ti + (robs(Ti) . vearth(T))/c^2 + dtgeo(Ti) + TDB2TDT(Ti)
where robs is the vector from the geocenter to the observer;
vearth is the vector velocity of the earth; and dtgeo is a
correction to convert from the observer's clock to geocentric TT
time. TDB2TDT is the value computed by this function, the
correction to convert from the geocenter to the solar system
barycenter.
As the above equation shows, while this function provides an
important component of the correction, the user must also be
responsible for (a) correcting their times to the geocenter (ie,
by maintaining atomic clock corrections); (b) estimating the
observatory position vector; and and (c) estimating earth's
velocity vector (using JPLEPHINTERP).
Users may note a circularity to the above equation, since
vearth(T) is expressed in terms of the SSB coordinate time. This
appears to be a chicken and egg problem since in order to get the
earth's velocity, the ephemeris time is needed to begin with.
However, to the precision of the above equation, < 25 ns, it is
acceptable to replace vearth(T) with vearth(TT).
The method of computation of TDB2TDT in this function is based on
the analytical formulation by Fairhead, Bretagnon & Lestrade, 1988
(so-called FBL model) and Fairhead & Bretagnon 1990, in terms of
sinusoids of various amplitudes. TDB2TDT has a dominant periodic
component of period 1 year and amplitude 1.7 ms. The set of 791
coefficients used here were drawn from the Princeton pulsar timing
program TEMPO version 11.005 (Taylor & Weisberg 1989).
Because the TDB2TDT quantity is rather expensive to compute but
slowly varying, users may wish to also retrieve the time
derivative using the DERIV keyword, if they have many times to
convert over a short baseline.
Verification
This implementation has been compared against a set of FBL test
data found in the 1996 IERS Conventions, Chapter 11, provided by
T. Fukushima. It has been verified that this routine reproduces
the Fukushima numbers to the accuracy of the table, within
10^{-14} seconds.
Fukushima (1995) has found that the 791-term Fairhead & Bretagnon
analytical approximation use here has a maximum error of 23
nanoseconds in the time range 1980-2000, compared to a numerical
integration. In comparison the truncated 127-term approximation
has an error of ~130 nanoseconds.
PARAMETERS:
JD - Geocentric time TT, scalar or vector, expressed in Julian
days. The actual time used is (JD + TBASE). For maximum
precision, TBASE should be used to express a fixed epoch in
whole day numbers, and JD should express fractional offset
days from that epoch.
KEYWORD PARAMETERS:
TBASE - scalar Julian day of a fixed epoch, which provides the
origin for times passed in JD.
Default: 0
DERIV - upon return, contains the derivative of TDB2TDT in units
of seconds per day. As many derivatives are returned as
values passed in JD.
RETURNS:
The correction offset(s) in units of seconds, to be applied as
noted above.
EXAMPLE:
Find the correction at ephemeris time 2451544.5 (JD):
IDL> print, tdb2tdt(2451544.5d)
-0.00011376314
or 0.11 ms.
REFERENCES:
Princeton TEMPO Program
http://pulsar.princeton.edu/tempo/
FBL Test Data Set
ftp://maia.usno.navy.mil/conventions/chapter11/fbl.results
Fairhead, L. & Bretagnon, P. 1990, A&A, 229, 240
(basis of this routine)
Fairhead, L. Bretagnon, P. & Lestrade, J.-F. 1988, in *The Earth's
Rotation and Reference Frames for Geodesy and Geodynamics*,
ed. A. K. Babcock and G. A. Wilkins, (Dordrecht: Kluwer), p. 419
(original "FBL" paper)
Fukushima, T. 1995, A&A, 294, 895 (error analysis)
Irwin, A. W. & Fukushima, T. 1999, A&A, 348, 642 (error analysis)
Standish, E. M. 1998, A&A, 336, 381 (description of time scales)
Taylor, J. H. & Weisberg, J. M. 1989, ApJ, 345, 434 (pulsar timing)
SEE ALSO
JPLEPHREAD, JPLEPHINTERP, JPLEPHTEST
MODIFICATION HISTORY:
Original logic from Fairhead & Bretagnon, 1990
Drawn from TEMPO v. 11.005, copied 20 Jun 2001
Documented and vectorized, 30 Jun 2001
Added helpful usage message, CM, 15 Mar 2002
$Id: tdb2tdt.pro,v 1.5 2002/03/15 12:00:27 craigm Exp $
(See /home/drw/idl/aux/markwardt/tdb2tdt.pro)
TDEWP[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tdewp
PURPOSE: compute dew point temperature from ambient temperature and
relative humidity. The dew point is the temperature to
which air must be cooled at constant pressure and
constant mixing ratio to reach 100% saturation with
respect to a plane water surface
USEAGE: result=tdewp(t,p,rh)
INPUT:
t ambient temperature (celsius)
p ambient pressure (mb)
rh rh relative humidity (0-100%)
OUTPUT:
result dew point temperature (celsius)
METHOD:
From thermodynamics we know that the saturated water vapor pressure
is just a function of the temperature. Lets call that function
VPS(T). Then the water vapor mixing ratio, which is the ratio of
the mass of vapor to the mass of dry air, is
1. r = (Mw/Ma) .01*rh VPS(T)/(P - VPS(T))
where rh is the relative humidity (this equation can be taken as
the definition of rh) and k is Boltzman's constant and Mw and Ma
are the molecular masses of water and air. By the definition of
dew point temperature, the water vapor density in this
non-saturated situation can also be expressed by,
2. r = (Mw/Ma) VPS(Td)/(P - VPS(Td))
Now, to solve for Td in terms of T and rh we set the RHS of eqn 1
equal to the RHS of eqn 2.
So the dew point is found by solving
3. VPS(Td)/(1.-VPS(Td)/P)=.01*rh*VPS(T)/(1.-VPS(T)/P)
To simplify matters we use an analytic approximation,
4. VPS(t) = c0*exp(c1*t/(t+c2)) (Tetans, 1930).
References:
equation relating saturated vapor pressure to temperature from:
Tetans, O. 1930. Uber emige meteorologische Begriffe. Z. Geophys. 6:297-309
EXAMPLE:
print,'the dewpoint temperature is',tdewp(29,44)
15.4947
; plot contours dew point temperture for a range of temperature
; and relative humidity
t=findgen(100)
rh=1+findgen(100)
gengrid,t,rh
td=tdewp(t,1013,rh)
contour,td,t,rh,xtitle='temperature (C)',ytitle='relative humidity',$
levels=contlev(td),/follow
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/tdewp.pro)
TDEWP[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tdewp
PURPOSE: compute dew point temperature from ambient temperature and
relative humidity. The dew point is the temperature to
which air must be cooled at constant pressure and
constant mixing ratio to reach 100% saturation with
respect to a plane water surface
USEAGE: result=tdewp(t,p,rh)
INPUT:
t ambient temperature (celsius)
p ambient pressure (mb)
rh rh relative humidity (0-100%)
OUTPUT:
result dew point temperature (celsius)
METHOD:
From thermodynamics we know that the saturated water vapor pressure
is just a function of the temperature. Lets call that function
VPS(T). Then the water vapor mixing ratio, which is the ratio of
the mass of vapor to the mass of dry air, is
1. r = (Mw/Ma) .01*rh VPS(T)/(P - VPS(T))
where rh is the relative humidity (this equation can be taken as
the definition of rh) and k is Boltzman's constant and Mw and Ma
are the molecular masses of water and air. By the definition of
dew point temperature, the water vapor density in this
non-saturated situation can also be expressed by,
2. r = (Mw/Ma) VPS(Td)/(P - VPS(Td))
Now, to solve for Td in terms of T and rh we set the RHS of eqn 1
equal to the RHS of eqn 2.
So the dew point is found by solving
3. VPS(Td)/(1.-VPS(Td)/P)=.01*rh*VPS(T)/(1.-VPS(T)/P)
To simplify matters we use an analytic approximation,
4. VPS(t) = c0*exp(c1*t/(t+c2)) (Tetans, 1930).
References:
equation relating saturated vapor pressure to temperature from:
Tetans, O. 1930. Uber emige meteorologische Begriffe. Z. Geophys. 6:297-309
EXAMPLE:
print,'the dewpoint temperature is',tdewp(29,44)
15.4947
; plot contours dew point temperture for a range of temperature
; and relative humidity
t=findgen(100)
rh=1+findgen(100)
gengrid,t,rh
td=tdewp(t,1013,rh)
contour,td,t,rh,xtitle='temperature (C)',ytitle='relative humidity',$
levels=contlev(td),/follow
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/tdewp.pro)
TEM_LOOP
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tem_loop
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for SiIX(356/347)
and SiX(356/347)
USEAGE: tem_loop,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
modified to den_loop3 by DRW for SECIS-relevant
data.
(See /home/drw/idl/cds/tem_loop.pro)
TEM_LOOP2
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tem_loop_new
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for Fe XIV/Fe XIII
USEAGE: tem_loop_new,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
modified to tem_loop_new by DRW for SECIS-relevant
data.
(See /home/drw/idl/cds/tem_loop2.pro)
TEM_LOOP_NEW
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tem_loop_new
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for Fe XIV/Fe XIII
USEAGE: tem_loop_new,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
modified to tem_loop_new by DRW for SECIS-relevant
data.
(See /home/drw/idl/cds/tem_loop_new.pro)
TEM_LOOP_NEW_TALK
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tem_loop_new
PURPOSE: display CDS radial and azimuthal scan, do line
fitting and calculate ratios for Fe XIV/Fe XIII
USEAGE: tem_loop_new,qlds,quick=quick
INPUT:
qlds calibrated CDS data in CDS qlds format
OUTPUT:
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
modified to den_loop3 by DRW for SECIS-relevant
data.
(See /home/drw/idl/cds/tem_loop_new_talk.pro)
TERM_SIZE
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: term_size
PURPOSE: find the number columns and number of lines in the idl terminal
USEAGE: term_size,xs,ys
INPUT:
KEYWORD INPUT:
OUTPUT:
xs number of columns
ys number of lines
DISCUSSION:
uses the unix command "resize" to find the terminal size
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
term_size,xs,ys & print,xs,ys
AUTHOR: Paul Ricchiazzi 04 Nov 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/term_size.pro)
TEST_AVFLAT.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
test_avFLAT.PRO
PURPOSE:
testbed for MAKE_AVERAGE_FLAT.PRO
(See /home/drw/idl/secis/test_avflat.pro)
TEXTABLE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TEXTABLE
PURPOSE:
Returns a translation table from TeX to IDL.
CATEGORY:
text/strings
CALLING SEQUENCE:
table = textable()
INPUTS:
None
KEYWORD PARAMETERS:
/POSTSCRIPT -- If set, return postscript translation
table rather than vector fonts table.
Default is translations for vector
fonts.
/HELP -- Print help and exit.
OUTPUTS:
table -- a 2D text array. table(0,*) contains out
the words to be translated away, table(1,*)
contains the words to translate them to.
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
To find out what TeX sequences are available, look at
table(0,*).
EXAMPLE:
MODIFICATION HISTORY:
$Id: textable.pro,v 1.7 1996/07/22 23:56:08 mcraig Exp $
$Log: textable.pro,v $
Revision 1.7 1996/07/22 23:56:08 mcraig
Added \vartheta.
Revision 1.6 1996/07/12 21:31:42 mcraig
Fixed \varphi in vector font, added \circ.
Revision 1.5 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.4 1996/05/09 00:22:17 mcraig
Added command to return to previous font after switching to Greek or
symbol font.
Revision 1.3 1996/02/08 19:49:35 mcraig
Removed control sequence \perp because the postscript code for it is '^'.
Revision 1.2 1996/02/08 18:53:38 mcraig
Added translations for PostScript fonts, and added several new TeX
control sequences.
Revision 1.1 1996/01/31 18:47:37 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/textable.pro)
TEXTCLOSE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TEXTCLOSE
PURPOSE:
procedure to close file for text output as specifed
by the (non-standard) system variable !TEXTOUT.
CALLING SEQUENCE:
textclose, [ TEXTOUT = ]
KEYWORDS:
textout - Indicates output device that was used by
TEXTOPEN
SIDE EFFECTS:
if !textout is not equal to 5 and the textunit is
opened. Then unit !textunit is closed and released
HISTORY:
D. Lindler Dec. 1986 (Replaces PRTOPEN)
Test if TEXTOUT is a scalar string W. Landsman August 1993
(See /home/drw/idl/esrg/textclose.pro)
TEXTCLOSE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TEXTCLOSE
PURPOSE:
procedure to close file for text output as specifed
by the (non-standard) system variable !TEXTOUT.
CALLING SEQUENCE:
textclose, [ TEXTOUT = ]
KEYWORDS:
textout - Indicates output device that was used by
TEXTOPEN
SIDE EFFECTS:
if !textout is not equal to 5 and the textunit is
opened. Then unit !textunit is closed and released
HISTORY:
D. Lindler Dec. 1986 (Replaces PRTOPEN)
Test if TEXTOUT is a scalar string W. Landsman August 1993
(See /home/drw/idl/old.esrg/textclose.pro)
TEXTOIDL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TEXTOIDL
PURPOSE:
Convert a valid TeX string to a valid IDL string for plot labels.
CATEGORY:
text/strings
CALLING SEQUENCE:
new = textoidl(old)
INPUTS:
old -- TeX string to be converted. Will not be in
modified. old may be a string array.
KEYWORD PARAMETERS:
FONT -- Set to 0 to use hardware font, -1 to use
vector. Note that the only hardware font
supported is PostScript.
/TEX_SEQUENCES -- return the available TeX sequences
/HELP -- print out info on use of the function
and exit.
OUTPUTS:
new -- IDL string corresponding to old. out
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
- Use the procedure SHOWTEX to get a list of the available TeX
control sequences.
- The only hardware font for which translation is available is
PostScript.
- The only device for which hardware font'
translation is available is PostScript.'
- The FONT keyword overrides the font selected'
by !p.font'
EXAMPLE:
out = TeXtoIDL('\Gamma^2 + 5N_{ed}')
The string out may be used in XYOUTS or other IDL text
display routines. It will be an uppercase Gamma, with an
exponent of 2, then a plus sign, then an N with the subscript
ed.
MODIFICATION HISTORY:
$Id: textoidl.pro,v 1.4 1996/06/14 20:00:27 mcraig Exp $
$Log: textoidl.pro,v $
Revision 1.4 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.3 1996/05/09 00:22:17 mcraig
Added error handling, cleaned up documentation.
Revision 1.2 1996/02/08 18:52:50 mcraig
Added ability to use hardware fonts for PostScript device.
Revision 1.1 1996/01/31 18:47:37 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/textoidl.pro)
TEXTOPEN[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TEXTOPEN
PURPOSE
Procedure to open file for text output. The type of output
device (disk file or terminal screen) is specified by the
TEXTOUT keyword or the (nonstandard) system variable !TEXTOUT.
CALLING SEQUENCE:
textopen, program, [ TEXTOUT = ]
INPUTS:
program - scalar string giving name of program calling textopen
OPTIONAL INPUT KEYWORDS:
TEXTOUT - Integer scalar (0-6) specifying output file/device to be
opened (see below) or scalar string giving name of output file.
If TEXTOUT is not supplied, then the (non-standard) system
variable !TEXTOUT is used.
SIDE EFFECTS:
The following dev/file is opened for output.
textout=0 Nowhere
textout=1 TERMINAL using /more option
textout=2 TERMINAL without /more option
textout=3 .prt
textout=4 laser.tmp
textout=5 user must open file
textout = filename (default extension of .prt)
The unit it is opened to is obtained with the procedure GET_LUN
unless !TEXTOUT=5. The unit number is placed in system variable
!TEXTUNIT. For !TEXTOUT=5 the user must set !TEXTUNIT to the
appropriate unit number.
NOTES:
Note that TEXTOUT = 1 or TEXTOUT = 2 will open a unit to the terminal,
SYS$OUTPUT (VMS) or /dev/tty (Unix). However, this terminal
output will *not* appear in an IDL JOURNAL session, unlike text
printed with the PRINT command.
NON-STANDARD SYSTEM VARIABLES:
DEFSYSV,'!TEXTOUT',1
DEFSYSV,'!TEXTUNIT',0
HISTORY:
D. Lindler Dec. 1986
Keyword textout added, J. Isensee, July, 1990
Made transportable, D. Neill, April, 1991
Trim input PROGRAM string W. Landsman Feb 1993
Don't modify TEXTOUT value W. Landsman Aug 1993
(See /home/drw/idl/esrg/textopen.pro)
TEXTOPEN[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TEXTOPEN
PURPOSE
Procedure to open file for text output. The type of output
device (disk file or terminal screen) is specified by the
TEXTOUT keyword or the (nonstandard) system variable !TEXTOUT.
CALLING SEQUENCE:
textopen, program, [ TEXTOUT = ]
INPUTS:
program - scalar string giving name of program calling textopen
OPTIONAL INPUT KEYWORDS:
TEXTOUT - Integer scalar (0-6) specifying output file/device to be
opened (see below) or scalar string giving name of output file.
If TEXTOUT is not supplied, then the (non-standard) system
variable !TEXTOUT is used.
SIDE EFFECTS:
The following dev/file is opened for output.
textout=0 Nowhere
textout=1 TERMINAL using /more option
textout=2 TERMINAL without /more option
textout=3 .prt
textout=4 laser.tmp
textout=5 user must open file
textout = filename (default extension of .prt)
The unit it is opened to is obtained with the procedure GET_LUN
unless !TEXTOUT=5. The unit number is placed in system variable
!TEXTUNIT. For !TEXTOUT=5 the user must set !TEXTUNIT to the
appropriate unit number.
NOTES:
Note that TEXTOUT = 1 or TEXTOUT = 2 will open a unit to the terminal,
SYS$OUTPUT (VMS) or /dev/tty (Unix). However, this terminal
output will *not* appear in an IDL JOURNAL session, unlike text
printed with the PRINT command.
NON-STANDARD SYSTEM VARIABLES:
DEFSYSV,'!TEXTOUT',1
DEFSYSV,'!TEXTUNIT',0
HISTORY:
D. Lindler Dec. 1986
Keyword textout added, J. Isensee, July, 1990
Made transportable, D. Neill, April, 1991
Trim input PROGRAM string W. Landsman Feb 1993
Don't modify TEXTOUT value W. Landsman Aug 1993
(See /home/drw/idl/old.esrg/textopen.pro)
TEXT_BOX[1]
[Previous Routine]
[Next Routine]
[List of Routines]
Name : text_box
Purpose : Writes a text message within a box in a graphics window.
Description: 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.
Useage: text_box,text,pos=pos,color=color,$
justify=justify,vert_space=vert_space
Inputs
TEXT ASCII text string containing the message.
keywords
pos 4 element vector specifying the box position and size
pos(0),pos(1) specify the lower left corner coordinate
pos(2),pos(3) specify the upper right corner coordinate
data window normalized coordinates are use
fg_color color of box and legend titles (default=!P.COLOR)
bg_color background color. Setting BG_COLOR erases the area
covered by the text box (filling it with color BG_COLOR)
prior to writing the text. If both BG_COLOR and !p.color
are zero then the background color is reset to 255 to
gaurantee a readability.
right if set, right justify text
center if set, center the text
vert_space vertical spacing of lines in units of character height
(default = 1.5)
author: Paul Ricchiazzi 7Jul93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/text_box.pro)
TEXT_BOX[2]
[Previous Routine]
[Next Routine]
[List of Routines]
Name : text_box
Purpose : Writes a text message within a box in a graphics window.
Description: 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.
Useage: text_box,text,pos=pos,color=color,$
justify=justify,vert_space=vert_space
Inputs
TEXT ASCII text string containing the message.
keywords
pos 4 element vector specifying the box position and size
pos(0),pos(1) specify the lower left corner coordinate
pos(2),pos(3) specify the upper right corner coordinate
data window normalized coordinates are use
fg_color color of box and legend titles (default=!P.COLOR)
bg_color background color. Setting BG_COLOR erases the area
covered by the text box (filling it with color BG_COLOR)
prior to writing the text. If both BG_COLOR and !p.color
are zero then the background color is reset to 255 to
gaurantee a readability.
right if set, right justify text
center if set, center the text
vert_space vertical spacing of lines in units of character height
(default = 1.5)
author: Paul Ricchiazzi 7Jul93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/text_box.pro)
TEX_BEGIN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
tex_begin
PURPOSE:
This functions returns the beginning commands for a tex document
CATEGORY:
PROG_TOOLS/TEX
CALLING SEQUENCE:
Result = tex_begin([oddsidemargin=oddsidemargin],[headheight=headheight],[textheight=textheight],[textwidth=textwidth],[usepackage=usepackage],[pagestyle=pagestyle])
OUTPUTS:
This function returns a string array containing tex-code to start a tex text
OPTIONAL INPUTS:
oddsidemargin: the odd side magrgin, value type of string e.g '-2.5cm'
headheight: the height of the head, value type of string e.g. '-2cm'
textheight: the height of the text, value type of string e.g. 25cm
textwidth: the width of the text, value type of string e.g. '21cm'
usepackage: the package to add, value type of string, if not selected '\usepackage{a4,german}' is set
EXAMPLE:
test=tex_begin()
print,test
\documentclass{article} \usepackage{a4,german}
\begin{document}
test2=tex_begin(textwidth='25cm',oddsidemargin='-2cm',headheight='-2cm')
print,test2
\documentclass{article}
\usepackage{a4,german}
\setlength{\oddsidemargin} {-2cm}
\setlength{\headheight} {-2cm}
\setlength{\textwidth} {25cm}
\begin{document}
MODIFICATION HISTORY:
Written by: Reimar Bauer, 1998-Jun-29
1999-08-27 keywords added
(See /home/drw/idl/icglib/pro/tex_begin.pro)
TEX_END
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
tex_end
PURPOSE:
This functions returns the ending commands for a tex document
CATEGORY:
PROG_TOOLS/TEX
CALLING SEQUENCE:
Result = tex_end()
OUTPUTS:
This function returns a string array containing tex-code to end a tex text
EXAMPLE:
test=tex_end()
print,test
\end{document}
MODIFICATION HISTORY:
Written by: Reimar Bauer, 1998-Jun-29
(See /home/drw/idl/icglib/pro/tex_end.pro)
TEX_FILTER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
tex_filter
PURPOSE:
This function translates special tex symbols to their tex syntax
CATEGORY:
PROG_TOOLS/TEX
CALLING SEQUENCE:
result=tex_filter(value[/no_html])
KEYWORD PARAMETERS:
no_html: to remove all html included commands e.g.
INPUTS:
value: a string or vector of ascii text
MODIFICATION HISTORY:
Written by: R.Bauer (ICG-1), 1998-Jul-05
2000-Feb-18 help changed to call_help
(See /home/drw/idl/icglib/pro/tex_filter.pro)
TEX_TABULAR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
tex_tabular
PURPOSE:
This functions creates a tabular environment for a string array
CATEGORY:
PROG_TOOLS/STRINGS
CALLING SEQUENCE:
Result = tex_text_format(string)
INPUTS:
string: a string array which should be formatted
KEYWORD PARAMETERS:
TEXTSIZE: this keyword if this keyword is set large will be used
OUTPUTS:
This function returns a string array tex-code formated text
EXAMPLE:
MODIFICATION HISTORY:
Written by: Theo Brauers
1999-08-26 some typemismatches removed and keyword border programmed
(See /home/drw/idl/icglib/pro/tex_tabular.pro)
TEX_TEXT_FORMAT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
tex_text_format
PURPOSE:
This functions adds tex format to a string
CATEGORY:
PROG_TOOLS/STRINGS
CALLING SEQUENCE:
Result = tex_text_format(string)
INPUTS:
string: a string which should be formatted
KEYWORD PARAMETERS:
TEXTSIZE: this keyword if this keyword is set large will be used
OUTPUTS:
This function returns a string tex-code formated text
EXAMPLE:
IDL> print, tex_text_format( ['acfgbhjkl','b'], tex_style='\bf', tex_size=5, form='(a3)')
{\Huge\bf acf}
{\Huge\bf b}
MODIFICATION HISTORY:
Written by: Theo Brauers
(See /home/drw/idl/icglib/pro/tex_text_format.pro)
TFTD
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : TFTD -- stuck in the PRIORITY folder, because of
a problem with one of the files it reads [DRW]
Purpose : Search for a string in header documentation.
Explanation : From a previously created and saved list of one-liners
from the IDL userlib and CDS trees the routine selects
up to 50 at random and prints them. This routine is run at
IDL startup as part of a user-education drive.
Use : IDL> tftd [,'search_string', lines=lines, /prog, cat=cat]
Inputs : None
Opt. Inputs : search_string - if given only routine names or one-line
documentation containing that string will
be presented. If present, all matches are
output and the LINES keyword is ignored.
The default search is effectively wild-carded
to search for '*string*'. If however a
wildcard is used explicitly at the end of
the search string, eg 'FITS*' then only those
entries beginning with the supplied
characters will be located. The /NAME
keyword is then redundant.
Outputs : Listing to screen or printer
Opt. Outputs: None
Keywords : lines - specifies the number of one-liners to output
(limit of 50 is imposed)
prog - use programmer routines only
cat - if specified, only routines having the supplied
string in the CATEGORY header section will be
listed. If cat has the value '?' then a list
of possible categories is printed.
name - if set, search is conducted within the name only
of the program - not the explanation.
hard - produce hardcopy of list
keep - keep output in file tftd_results in current
directory
Calls : None
Common : None
Restrictions: Only userlib and CDS trees used at the moment.
Side effects: User awareness increased. Authors of routines with
non-standard documentation embarrassed (hopefully).
Category : Doc, help
Prev. Hist. : None
Written : C D Pike, RAL, 5-May-94
Modified : Look for save file in CDS_INFO, CDP, 20-May-1994
Add prog keyword. CDP, 13-Jun-94
Make LINES a keyword and string search the only parameter.
CDP, 14-Sep-94
To include category option. CDP, 20-Sep-94
Added /NAME keyword and explicit wildcard. CDP, 14-Feb-95
Added check for existence of save files. DMZ, 28-Feb-95
Add hardcopy option. CDP, 11-Apr-97
Add keep keyword. CDP, 25-Jan-99
Version : Version 8, 10-Apr-97
(See /home/drw/idl/priority/tftd.pro)
TFUNCT
[Previous Routine]
[Next Routine]
[List of Routines]
see documentation for CURVEFIT -- copied from GFUNCT
(See /home/drw/idl/secis2/tfunct.pro)
THICK[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: thick
PURPOSE: thicken lines and characters on postscript output.
USEAGE: thick,thck,cthck
INPUT: thck the thickening factor.
if not set all graphics system variables
related to line thickness are set to 1
cthck character thickening factor, if CTHCK is not
not set or equal to zero then it defaults to
1+.5*(thck-1) if not set.
OUTPUT: none
SIDE EFFECTS: changes the values of system varaibles as follows
!p.charthick=cthck
!p.thick=thck
!x.thick=thck
!y.thick=thck
PROCEDURE: a thickening factor of 3 is a good value to use for
plots on the Phaser color printer. and 5 is good for
very bold lines. 2 is good enough for the low resolution
printers
author: Paul Ricchiazzi feb94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/thick.pro)
THICK[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: thick
PURPOSE: thicken lines and characters on postscript output.
USEAGE: thick,thck,cthck
INPUT: thck the thickening factor.
if not set all graphics system variables
related to line thickness are set to 1
cthck character thickening factor, if CTHCK is not
not set or equal to zero then it defaults to
1+.5*(thck-1) if not set.
OUTPUT: none
SIDE EFFECTS: changes the values of system varaibles as follows
!p.charthick=cthck
!p.thick=thck
!x.thick=thck
!y.thick=thck
PROCEDURE: a thickening factor of 3 is a good value to use for
plots on the Phaser color printer. and 5 is good for
very bold lines. 2 is good enough for the low resolution
printers
author: Paul Ricchiazzi feb94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/thick.pro)
TIMELAG
[Previous Routine]
[Next Routine]
[List of Routines]
PURPOSE To calculate the maximum crosscorrelation of two lightcurves
USEAGE timelag,timeseries1,timeseries2,array of possible timelags, result
INPUT two time series , array of possible timelags (in terms of pixels)
OUTPUT result, an array of cross correlation values for each timelag
EXAMPLE IDL>tau=findgen(100)/10 -5 ;creates a array of 100 elements each 0.1 apart
from -5 to 4.9
IDL>timelag,time1,time2,tau,c
AUTHOR R.T.James McAteer and Peter T. Gallager
august 2001
(See /home/drw/idl/jma/timelag.pro)
TIMESTAMP[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE timestamp
PURPOSE print the current day and time in the lower right corner of
the device window
USEAGE timestamp
timestamp,label,charsize=charsize
INPUT:
label optional label string. If LABEL not supplied the current
working directory is used
KEYWORD INPUT:
charsize character size multiplier (default=0.5)
right put timestamp at lower right corner of the page
(default is lower left corner)
OUTPUT: none
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/esrg/timestamp.pro)
TIMESTAMP[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE timestamp
PURPOSE print the current day and time in the lower right corner of
the device window
USEAGE timestamp
timestamp,label,charsize=charsize
INPUT:
label optional label string. If LABEL not supplied the current
working directory is used
KEYWORD INPUT:
charsize character size multiplier (default=0.5)
right put timestamp at lower right corner of the page
(default is lower left corner)
OUTPUT: none
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/old.esrg/timestamp.pro)
TLAW (TURBULENCE LAW)
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
SECIS (Zambia, 2001)
NAME:
TLAW (turbulence law)
PURPOSE:
to work out the power law in an image of errors due to turbulence.
It's a pretty narrowly focussed routine, admittedly...
INPUTS:
errimage - the 2-D array of errors for each pixel, which should be
the warped image minus the dewarped image. Doesn't matter
too much which, as we'll take the modulus of the values.
mulp=[a,b] - the inputs for MULT.pro
(See /home/drw/idl/secis2/tlaw.pro)
TNMIN[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TNMIN
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:
Performs function minimization (Truncated-Newton Method)
MAJOR TOPICS:
Optimization and Minimization
CALLING SEQUENCE:
parms = TNMIN(MYFUNCT, X, FUNCTARGS=fcnargs, NFEV=nfev,
MAXITER=maxiter, ERRMSG=errmsg, NPRINT=nprint,
QUIET=quiet, XTOL=xtol, STATUS=status,
FGUESS=fguess, PARINFO=parinfo, BESTMIN=bestmin,
ITERPROC=iterproc, ITERARGS=iterargs, niter=niter)
DESCRIPTION:
TNMIN uses the Truncated-Newton method to minimize an arbitrary IDL
function with respect to a given set of free parameters. The
user-supplied function must compute the gradient with respect to
each parameter. TNMIN is based on TN.F (TNBC) by Stephen Nash.
If you want to solve a least-squares problem, to perform *curve*
*fitting*, then you will probably want to use the routines MPFIT,
MPFITFUN and MPFITEXPR. Those routines are specifically optimized
for the least-squares problem. TNMIN is suitable for constrained
and unconstrained optimization problems with a medium number of
variables. Function *maximization* can be performed using the
MAXIMIZE keyword.
TNMIN is similar to MPFIT in that it allows parameters to be fixed,
simple bounding limits to be placed on parameter values, and
parameters to be tied to other parameters. See PARINFO below for
discussion and examples.
USER FUNCTION
The user must define an IDL function which returns the desired
value as a single scalar. The IDL function must accept a list of
numerical parameters, P. Additionally, keyword parameters may be
used to pass more data or information to the user function, via the
FUNCTARGS keyword.
The user function should be declared in the following way:
FUNCTION MYFUNCT, p, dp [, keywords permitted ]
; Parameter values are passed in "p"
f = .... ; Compute function value
dp = .... ; Compute partial derivatives (optional)
return, f
END
The function *must* accept at least one argument, the parameter
list P. The vector P is implicitly assumed to be a one-dimensional
array. Users may pass additional information to the function by
composing and _EXTRA structure and passing it in the FUNCTARGS
keyword.
User functions may also indicate a fatal error condition using the
ERROR_CODE common block variable, as described below under the
TNMIN_ERROR common block definition (by setting ERROR_CODE to a
number between -15 and -1).
ANALYTIC vs. NUMERICAL DERIVATIVES
By default, the user must compute gradient components analytically
using AUTODERIVATIVE=0. As explained below, numerical derivatives
can also be calculated using AUTODERIVATIVE=1.
For analytic derivatives, the user should call TNMIN using the
default keyword value AUTODERIVATIVE=0. [ This is different
behavior from MPFIT, where AUTODERIVATIVE=1 is the default. ] The
IDL user routine should compute the gradient of the function as a
one-dimensional array of values, one for each of the parameters.
They are passed back to TNMIN via "dp" as shown above.
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.
For numerical derivatives, a finite differencing approximation is
used to estimate the gradient values. Users can activate this
feature by passing the keyword AUTODERIVATIVE=1. Fine control over
this behavior can be achieved using the STEP, RELSTEP and TNSIDE
fields of the PARINFO structure.
When finite differencing is used for computing derivatives (ie,
when AUTODERIVATIVE=1), the parameter DP is not passed. Therefore
functions can use N_PARAMS() to indicate whether they must compute
the derivatives or not. However there is no penalty (other than
computation time) for computing the gradient values and users may
switch between AUTODERIVATIVE=0 or =1 in order to test both
scenarios.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of TNMIN can be modified with respect to each
parameter to be optimized. 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 TNMIN.
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
TNMIN, 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 TNMIN does not use this tag in any
way.
.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.
.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.
.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" or "TN".
Therefore programmers are urged to avoid using tags starting with
these two combinations of 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:
MYFUNCT - a string variable containing the name of the function to
be minimized (see USER FUNCTION above). The IDL routine
should return the value of the function and optionally
its gradients.
X - An array of starting values for each of the parameters of the
model.
This parameter is optional if the PARINFO keyword is used.
See above. The PARINFO keyword provides a mechanism to fix or
constrain individual parameters. If both X and PARINFO are
passed, then the starting *value* is taken from X, but the
*constraints* are taken from PARINFO.
RETURNS:
Returns the array of best-fit parameters.
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 (analytical) derivatives.
Default: 0 (analytical derivatives required)
BESTMIN - upon return, the best minimum function value that TNMIN
could find.
EPSABS - a nonnegative real variable. Termination occurs when the
absolute error between consecutive iterates is at most
EPSABS. Note that using EPSREL is normally preferable
over EPSABS, except in cases where ABS(F) is much larger
than 1 at the optimal point. A value of zero indicates
the absolute error test is not applied. If EPSABS is
specified, then both EPSREL and EPSABS tests are applied;
if either succeeds then termination occurs.
Default: 0 (i.e., only EPSREL is applied).
EPSREL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at
most EPSREL. Therefore, EPSREL measures the relative
error desired in the function. An additional, more
lenient, stopping condition can be applied by specifying
the EPSABS keyword.
Default: 100 * Machine Precision
ERRMSG - a string error or warning message is returned.
FGUESS - provides the routine a guess to the minimum value.
Default: 0
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]}
then the user supplied function should be declared
like this:
FUNCTION MYFUNCT, P, XVAL=x, YVAL=y
By default, no extra parameters are passed to the
user-supplied function.
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.
ITERDERIV - Intended to print function gradient information. If
set, then the ITERDERIV keyword is set in each call to
ITERPROC. In the default ITERPROC, parameter values
and gradient information are both printed when this
keyword is set.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the TNMIN routine. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, _EXTRA=extra
; perform custom iteration update
END
ITERPROC must accept the _EXTRA keyword, in case of
future changes to the calling procedure.
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 is should be the function
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
between -15 and -1 (see TNMIN_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 TNMIN returns.
Default: 200 iterations
MAXIMIZE - If set, the function is maximized instead of
minimized.
MAXNFEV - The maximum number of function evaluations to perform.
If the number is exceeded, then the STATUS value is set
to -17 and TNMIN returns. A value of zero indicates no
maximum.
Default: 0 (no maximum)
NFEV - upon return, the number of MYFUNCT function evaluations
performed.
NITER - upon return, number of iterations completed.
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.
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 TNMIN.
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 TNMIN
STATUS - an integer status code is returned. All values greater
than zero can represent success (however STATUS EQ 5 may
indicate failure to converge). Gaps in the numbering
system below are to maintain compatibility with MPFIT.
Upon return, STATUS can have one of the following values:
-18 a fatal internal error occurred during optimization.
-17 the maximum number of function evaluations has been
reached without convergence.
-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 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 convergence was reached.
2-4 (RESERVED)
5 the maximum number of iterations has been reached
6-8 (RESERVED)
EXAMPLE:
FUNCTION F, X, DF, _EXTRA=extra ;; *** MUST ACCEPT KEYWORDS
F = (X(0)-1)^2 + (X(1)+7)^2
DF = [ 2D * (X(0)-1), 2D * (X(1)+7) ] ; Gradient
RETURN, F
END
P = TNMIN('F', [0D, 0D], BESTMIN=F0)
Minimizes the function F(x0,x1) = (x0-1)^2 + (x1+7)^2.
COMMON BLOCKS:
COMMON TNMIN_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, TNMIN 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:
TRUNCATED-NEWTON METHOD, TN.F
Stephen G. Nash, Operations Research and Applied Statistics
Department
http://www.netlib.org/opt/tn
Nash, S. G. 1984, "Newton-Type Minimization via the Lanczos
Method," SIAM J. Numerical Analysis, 21, p. 770-778
MODIFICATION HISTORY:
Derived from TN.F by Stephen Nash with many changes and additions,
to conform to MPFIT paradigm, 19 Jan 1999, CM
Changed web address to COW, 25 Sep 1999, CM
Alphabetized documented keyword parameters, 02 Oct 1999, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Continued and fairly major improvements (CM, 08 Jan 2001):
- calling of user procedure is now concentrated in TNMIN_CALL,
and arguments are reduced by storing a large number of them
in common blocks;
- finite differencing is done within TNMIN_CALL; added
AUTODERIVATIVE=1 so that finite differencing can be enabled,
both one and two sided;
- a new procedure to parse PARINFO fields, borrowed from MPFIT;
brought PARINFO keywords up to date with MPFIT;
- go through and check for float vs. double discrepancies;
- add explicit MAXIMIZE keyword, and support in TNMIN_CALL and
TNMIN_DEFITER to print the correct values in that case;
TNMIN_DEFITER now prints function gradient values if
requested;
- convert to common-based system of MPFIT for storing machine
constants; revert TNMIN_ENORM to simple sum of squares, at
least for now;
- remove limit on number of function evaluations, at least for
now, and until I can understand what happens when we do
numerical derivatives.
Further changes: more float vs double; disable TNMINSTEP for now;
experimented with convergence test in case of function
maximization, 11 Jan 2001, CM
TNMINSTEP is parsed but not enabled, 13 Mar 2001
Major code cleanups; internal docs; reduced commons, CM, 08 Apr
2001
Continued code cleanups; documentation; the STATUS keyword
actually means something, CM, 10 Apr 2001
Added reference to Nash paper, CM, 08 Feb 2002
Fixed 16-bit loop indices, D. Schelgel, 22 Apr 2003
TODO
- scale derivatives semi-automatically;
- ability to scale and offset parameters;
$Id: tnmin.pro,v 1.12 2003/04/22 23:42:49 craigm Exp $
(See /home/drw/idl/aux/markwardt/tnmin.pro)
TNMIN[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TNMIN
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:
Performs function minimization (Truncated-Newton Method)
MAJOR TOPICS:
Optimization and Minimization
CALLING SEQUENCE:
parms = TNMIN(MYFUNCT, X, FUNCTARGS=fcnargs, NFEV=nfev,
MAXITER=maxiter, ERRMSG=errmsg, NPRINT=nprint,
QUIET=quiet, XTOL=xtol, STATUS=status,
FGUESS=fguess, PARINFO=parinfo, BESTMIN=bestmin,
ITERPROC=iterproc, ITERARGS=iterargs, niter=niter)
DESCRIPTION:
TNMIN uses the Truncated-Newton method to minimize an arbitrary IDL
function with respect to a given set of free parameters. The
user-supplied function must compute the gradient with respect to
each parameter. TNMIN is based on TN.F (TNBC) by Stephen Nash.
If you want to solve a least-squares problem, to perform *curve*
*fitting*, then you will probably want to use the routines MPFIT,
MPFITFUN and MPFITEXPR. Those routines are specifically optimized
for the least-squares problem. TNMIN is suitable for constrained
and unconstrained optimization problems with a medium number of
variables. Function *maximization* can be performed using the
MAXIMIZE keyword.
TNMIN is similar to MPFIT in that it allows parameters to be fixed,
simple bounding limits to be placed on parameter values, and
parameters to be tied to other parameters. See PARINFO below for
discussion and examples.
USER FUNCTION
The user must define an IDL function which returns the desired
value as a single scalar. The IDL function must accept a list of
numerical parameters, P. Additionally, keyword parameters may be
used to pass more data or information to the user function, via the
FUNCTARGS keyword.
The user function should be declared in the following way:
FUNCTION MYFUNCT, p, dp [, keywords permitted ]
; Parameter values are passed in "p"
f = .... ; Compute function value
dp = .... ; Compute partial derivatives (optional)
return, f
END
The function *must* accept at least one argument, the parameter
list P. The vector P is implicitly assumed to be a one-dimensional
array. Users may pass additional information to the function by
composing and _EXTRA structure and passing it in the FUNCTARGS
keyword.
User functions may also indicate a fatal error condition using the
ERROR_CODE common block variable, as described below under the
TNMIN_ERROR common block definition (by setting ERROR_CODE to a
number between -15 and -1).
ANALYTIC vs. NUMERICAL DERIVATIVES
By default, the user must compute gradient components analytically
using AUTODERIVATIVE=0. As explained below, numerical derivatives
can also be calculated using AUTODERIVATIVE=1.
For analytic derivatives, the user should call TNMIN using the
default keyword value AUTODERIVATIVE=0. [ This is different
behavior from MPFIT, where AUTODERIVATIVE=1 is the default. ] The
IDL user routine should compute the gradient of the function as a
one-dimensional array of values, one for each of the parameters.
They are passed back to TNMIN via "dp" as shown above.
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.
For numerical derivatives, a finite differencing approximation is
used to estimate the gradient values. Users can activate this
feature by passing the keyword AUTODERIVATIVE=1. Fine control over
this behavior can be achieved using the STEP, RELSTEP and TNSIDE
fields of the PARINFO structure.
When finite differencing is used for computing derivatives (ie,
when AUTODERIVATIVE=1), the parameter DP is not passed. Therefore
functions can use N_PARAMS() to indicate whether they must compute
the derivatives or not. However there is no penalty (other than
computation time) for computing the gradient values and users may
switch between AUTODERIVATIVE=0 or =1 in order to test both
scenarios.
CONSTRAINING PARAMETER VALUES WITH THE PARINFO KEYWORD
The behavior of TNMIN can be modified with respect to each
parameter to be optimized. 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 TNMIN.
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
TNMIN, 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 TNMIN does not use this tag in any
way.
.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.
.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.
.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" or "TN".
Therefore programmers are urged to avoid using tags starting with
these two combinations of 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:
MYFUNCT - a string variable containing the name of the function to
be minimized (see USER FUNCTION above). The IDL routine
should return the value of the function and optionally
its gradients.
X - An array of starting values for each of the parameters of the
model.
This parameter is optional if the PARINFO keyword is used.
See above. The PARINFO keyword provides a mechanism to fix or
constrain individual parameters. If both X and PARINFO are
passed, then the starting *value* is taken from X, but the
*constraints* are taken from PARINFO.
RETURNS:
Returns the array of best-fit parameters.
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 (analytical) derivatives.
Default: 0 (analytical derivatives required)
BESTMIN - upon return, the best minimum function value that TNMIN
could find.
EPSABS - a nonnegative real variable. Termination occurs when the
absolute error between consecutive iterates is at most
EPSABS. Note that using EPSREL is normally preferable
over EPSABS, except in cases where ABS(F) is much larger
than 1 at the optimal point. A value of zero indicates
the absolute error test is not applied. If EPSABS is
specified, then both EPSREL and EPSABS tests are applied;
if either succeeds then termination occurs.
Default: 0 (i.e., only EPSREL is applied).
EPSREL - a nonnegative input variable. Termination occurs when the
relative error between two consecutive iterates is at
most EPSREL. Therefore, EPSREL measures the relative
error desired in the function. An additional, more
lenient, stopping condition can be applied by specifying
the EPSABS keyword.
Default: 100 * Machine Precision
ERRMSG - a string error or warning message is returned.
FGUESS - provides the routine a guess to the minimum value.
Default: 0
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]}
then the user supplied function should be declared
like this:
FUNCTION MYFUNCT, P, XVAL=x, YVAL=y
By default, no extra parameters are passed to the
user-supplied function.
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.
ITERDERIV - Intended to print function gradient information. If
set, then the ITERDERIV keyword is set in each call to
ITERPROC. In the default ITERPROC, parameter values
and gradient information are both printed when this
keyword is set.
ITERPROC - The name of a procedure to be called upon each NPRINT
iteration of the TNMIN routine. It should be declared
in the following way:
PRO ITERPROC, MYFUNCT, p, iter, fnorm, FUNCTARGS=fcnargs, $
PARINFO=parinfo, QUIET=quiet, _EXTRA=extra
; perform custom iteration update
END
ITERPROC must accept the _EXTRA keyword, in case of
future changes to the calling procedure.
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 is should be the function
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
between -15 and -1 (see TNMIN_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 TNMIN returns.
Default: 200 iterations
MAXIMIZE - If set, the function is maximized instead of
minimized.
MAXNFEV - The maximum number of function evaluations to perform.
If the number is exceeded, then the STATUS value is set
to -17 and TNMIN returns. A value of zero indicates no
maximum.
Default: 0 (no maximum)
NFEV - upon return, the number of MYFUNCT function evaluations
performed.
NITER - upon return, number of iterations completed.
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.
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 TNMIN.
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 TNMIN
STATUS - an integer status code is returned. All values greater
than zero can represent success (however STATUS EQ 5 may
indicate failure to converge). Gaps in the numbering
system below are to maintain compatibility with MPFIT.
Upon return, STATUS can have one of the following values:
-18 a fatal internal error occurred during optimization.
-17 the maximum number of function evaluations has been
reached without convergence.
-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 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 convergence was reached.
2-4 (RESERVED)
5 the maximum number of iterations has been reached
6-8 (RESERVED)
EXAMPLE:
FUNCTION F, X, DF, _EXTRA=extra ;; *** MUST ACCEPT KEYWORDS
F = (X(0)-1)^2 + (X(1)+7)^2
DF = [ 2D * (X(0)-1), 2D * (X(1)+7) ] ; Gradient
RETURN, F
END
P = TNMIN('F', [0D, 0D], BESTMIN=F0)
Minimizes the function F(x0,x1) = (x0-1)^2 + (x1+7)^2.
COMMON BLOCKS:
COMMON TNMIN_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, TNMIN 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:
TRUNCATED-NEWTON METHOD, TN.F
Stephen G. Nash, Operations Research and Applied Statistics
Department
http://www.netlib.org/opt/tn
Nash, S. G. 1984, "Newton-Type Minimization via the Lanczos
Method," SIAM J. Numerical Analysis, 21, p. 770-778
MODIFICATION HISTORY:
Derived from TN.F by Stephen Nash with many changes and additions,
to conform to MPFIT paradigm, 19 Jan 1999, CM
Changed web address to COW, 25 Sep 1999, CM
Alphabetized documented keyword parameters, 02 Oct 1999, CM
Changed to ERROR_CODE for error condition, 28 Jan 2000, CM
Continued and fairly major improvements (CM, 08 Jan 2001):
- calling of user procedure is now concentrated in TNMIN_CALL,
and arguments are reduced by storing a large number of them
in common blocks;
- finite differencing is done within TNMIN_CALL; added
AUTODERIVATIVE=1 so that finite differencing can be enabled,
both one and two sided;
- a new procedure to parse PARINFO fields, borrowed from MPFIT;
brought PARINFO keywords up to date with MPFIT;
- go through and check for float vs. double discrepancies;
- add explicit MAXIMIZE keyword, and support in TNMIN_CALL and
TNMIN_DEFITER to print the correct values in that case;
TNMIN_DEFITER now prints function gradient values if
requested;
- convert to common-based system of MPFIT for storing machine
constants; revert TNMIN_ENORM to simple sum of squares, at
least for now;
- remove limit on number of function evaluations, at least for
now, and until I can understand what happens when we do
numerical derivatives.
Further changes: more float vs double; disable TNMINSTEP for now;
experimented with convergence test in case of function
maximization, 11 Jan 2001, CM
TNMINSTEP is parsed but not enabled, 13 Mar 2001
Major code cleanups; internal docs; reduced commons, CM, 08 Apr
2001
Continued code cleanups; documentation; the STATUS keyword
actually means something, CM, 10 Apr 2001
Added reference to Nash paper, CM, 08 Feb 2002
TODO
- scale derivatives semi-automatically;
- ability to scale and offset parameters;
$Id: tnmin.pro,v 1.9 2002/02/11 23:31:09 craigm Exp $
(See /home/drw/idl/aux/oldmarkwardt/tnmin.pro)
TOGGLE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: toggle,color=color,landscape=landscape,portrait=portrait, $
letter=letter,legal=legal,filename=filename
PURPOSE: toggles IDL graphics output between X-window and a postscript
output file.
OPTIONAL INPUTS (keyword parameters):
COLOR Enable color plotting (output to Tek Phaser color printer)
LANDSCAPE Horizontal plotting format
PORTRAIT Vertical plotting format (default)
LETTER 8.5 by 11 inch page size (default)
LEGAL 11 by 14 inch page size (Phaser)
EPS
if set, encapsulated postscript file is produced.
Many word processing and typesetting programs provide
facilities to include encapsulated PostScript output
within documents. See the discussion of the POSTSCRIPT
and EPS options of the DEVICE command in the IDL
user manual.
PRINT 1 = submit to default printer ( setenv PRINTER ????)
otherwise if PRINT is a string variable
the job will be spooled to the named print queue
QUEUE if set, print queue is selected from a pop-up menu
FILENAME name of postscript file (default = plot.ps or plotc.ps)
PROCEDURE: The first call to TOGGLE (and all odd number calls)
changes the output device from X-window to a
Postscript output file. If the output file name is not
specified on the command line the default file name will
be plot.ps for the laser printers, or plotc.ps for the
TEK Phaser color printer.
The next call (and all even number calls) switches back
to the X-window and closes the plot file. If the keyword
PRINT is set the plotfile will be submitted to one of the
ESRG print queues.
NOTE: Only one postscript file can be open at any given time
SIDE EFFECTS:
In order to maintain a font size which keeps the same
relation to the screen size, the global variable
!p.charsize is changed when switching to and from
postscript mode, as follows,
When toggleing to PS !p.charsize --> !p.charsize/fac
When toggleing to X !p.charsize --> !p.charsize*fac
[!d.x_ch_size] [!d.x_vsize ]
where fac= [------------] [----------- ]
[!d.x_vsize ] [!d.x_ch_size]
PS X
Thus, to ensure that plotted character strings scale
properly in postscript mode, specify all character
sizes as as multiples of !p.charsize.
EXAMPLE:
View the IDL dist function and then make a hardcopy:
d=dist(200)
loadct,5
tvscl,d ; view the plot on X-windows
toggle,/color,/landscape ; redirect output to plotc.ps
tvscl,d ; write plot onto plotc.ps
toggle,/print ; resume output to X-windows
; submit plot job to default printer
toggle,/color,/land
tvscl,d
toggle,print='term' ; submit plot "term" print queue
author: Paul Ricchiazzi 1jun92
Institute for Computational Earth System Science
University of California, Santa Barbara
NOTE: you can check for the currently defined print queues in /etc/printcap
REVISIONS:
feb93: added PRINT keyword
feb93: set yoffset=10.5 in landscape mode
feb93: added FILENAME keyword
mar93: added bits=8 in black and white mode
mar96: modify !p.charsize to compensate for larger ps font size
mar96: send output to print queue tree on eos
(See /home/drw/idl/bin/toggle.pro)
TOGGLE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: toggle
USEAGE For opening a postscript file:
toggle,color=color,landscape=landscape,portrait=portrait, $
queue=queue,print=print,filename=filename, $
eps=eps,xoffset=xoffset,yoffset=yoffset,xsize=xsize, $
ysize=ysize,_extra=_extra
USEAGE For closing a postscript file:
toggle,print=print, queue=queue
PURPOSE: toggles IDL graphics output between X-window and a postscript
output file. This program creates postscript and encapsulated
files. You can generate other graphics output formats by using
the UNIX command "convert"
OPTIONAL INPUTS (keyword parameters):
;;; these keywords recognized when opening a postscript file:
COLOR
Enable color plotting (output to Tek Phaser color printer)
LANDSCAPE
Horizontal plotting format (i.e., long side of paper is horizontal)
PORTRAIT
Vertical plotting format (default)
EPS
If set, an encapsulated postscript file is produced. Many word
processing and typesetting programs provide facilities to
include encapsulated PostScript output within documents (for
example groff's PSPIC command). If the XSIZE and YSIZE
parameters are not set the value of EPS is interpreted as an
aspect ratio of the graphic.
NOTE: Using the SET_CHARSIZE procedure to set the character size
makes it easier to use an x-window preview to predict the
appearance of PS output.
XSIZE, YSIZE
Controls the size of the plotting area (inches). These
parameters can be used to set the size of an EPS graphic. If
XSIZE and YSIZE are not set the value of of EPS is used to
compute the aspect ratio. In that case, the internal values of
XSIZE and YSIZE are set to 8 and 8/EPS inches, respectively.
Setting XSIZE and YSIZE explicitly is useful for controlling the
appearance of different linestyles. For example, when linestyle
2 is used to produce dashed lines, a 4"x4" plot size will
produce half as many dashes as a 8"x8" plot size.
XOFFSET,YOFFSET
In PORTRAIT mode XOFFSET,YOFFSET is the coordinate position of
the lower left corner of the plotting area (inches) with respect
to the lower left corner of the paper. In LANDSCAPE mode the
whole coordinate system is turned to 90 degrees counter-
clockwise, so that XOFFSET is the bottom margin and YOFFSET is
the distance from the lower-left corner of the plotting area to
the RIGHT (yup, that's RIGHT) edge of the page.
FILENAME
name of postscript file (default = plot.ps or plotc.ps).
;;; these keywords recognized when closing a postscript file:
PRINT
PRINT=1 => submit to default printer ( setenv PRINTER ????)
otherwise if PRINT is a string variable the job will be spooled
to the named print queue (e.g., PRINT='tree').
QUEUE
if set, print queue is selected from a pop-up menu.
PROCEDURE:
The first call to TOGGLE (and all odd number calls) changes the
output device from X-window to a Postscript output file. If the
output file name is not specified on the command line the
default file name will be plot.ps for the laser printers, or
plotc.ps for the TEK Phaser color printer.
The next call (and all even number calls) switches back to the
X-window and closes the plot file. If the keyword PRINT is set
the plotfile will be submitted to one of the ICESS print queues.
NOTE: Only one postscript file can be open at any given time
SIDE EFFECTS:
In order to maintain a font size which keeps the same
relation to the screen size, the global variable
!p.charsize is changed when switching to and from
postscript mode, as follows,
When toggleing to PS !p.charsize --> !p.charsize/fac
When toggleing to X !p.charsize --> !p.charsize*fac
[!d.x_ch_size] [!d.x_vsize ]
where fac= [------------] [----------- ]
[!d.x_vsize ] [!d.x_ch_size]
PS X
Thus, to ensure that plotted character strings scale
properly in postscript mode, specify all character
sizes as as multiples of !p.charsize.
EXAMPLE: View the IDL dist function and then make a hardcopy:
;;
d=dist(200)
loadct,5
tvscl,d ; view the plot on X-windows
toggle,/color,/landscape ; redirect output to plotc.ps
tvscl,d ; write plot onto plotc.ps
toggle,/print ; resume output to X-windows
; submit plot job to default printer
toggle,/color,/land
tvscl,d
toggle,print='term' ; submit plot "term" print queue
;;
BUGS: EPS option does not work in LANDSCAPE format. Looks like a
a problem in IDL's DEVICE proceedure.
author: Paul Ricchiazzi 1jun92
Institute for Computational Earth System Science
University of California, Santa Barbara
NOTE: you can check for the currently defined print queues in /etc/printcap
REVISIONS:
feb93: added PRINT keyword
feb93: set yoffset=10.5 in landscape mode
feb93: added FILENAME keyword
mar93: added bits=8 in black and white mode
mar96: modify !p.charsize to compensate for larger ps font size
mar96: send output to print queue tree on eos
sep96: added EPS,XSIZE and YSIZE keywords
dec96: make PORTRAIT format standard for color plots
(See /home/drw/idl/esrg/toggle.pro)
TOGGLE[3]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: toggle,color=color,landscape=landscape,portrait=portrait, $
letter=letter,legal=legal,filename=filename
PURPOSE: toggles IDL graphics output between X-window and a postscript
output file.
OPTIONAL INPUTS (keyword parameters):
COLOR Enable color plotting (output to Tek Phaser color printer)
LANDSCAPE Horizontal plotting format
PORTRAIT Vertical plotting format (default)
LETTER 8.5 by 11 inch page size (default)
LEGAL 11 by 14 inch page size (Phaser)
EPS
if set, encapsulated postscript file is produced.
Many word processing and typesetting programs provide
facilities to include encapsulated PostScript output
within documents. See the discussion of the POSTSCRIPT
and EPS options of the DEVICE command in the IDL
user manual.
PRINT 1 = submit to default printer ( setenv PRINTER ????)
otherwise if PRINT is a string variable
the job will be spooled to the named print queue
QUEUE if set, print queue is selected from a pop-up menu
FILENAME name of postscript file (default = plot.ps or plotc.ps)
PROCEDURE: The first call to TOGGLE (and all odd number calls)
changes the output device from X-window to a
Postscript output file. If the output file name is not
specified on the command line the default file name will
be plot.ps for the laser printers, or plotc.ps for the
TEK Phaser color printer.
The next call (and all even number calls) switches back
to the X-window and closes the plot file. If the keyword
PRINT is set the plotfile will be submitted to one of the
ESRG print queues.
NOTE: Only one postscript file can be open at any given time
SIDE EFFECTS:
In order to maintain a font size which keeps the same
relation to the screen size, the global variable
!p.charsize is changed when switching to and from
postscript mode, as follows,
When toggleing to PS !p.charsize --> !p.charsize/fac
When toggleing to X !p.charsize --> !p.charsize*fac
[!d.x_ch_size] [!d.x_vsize ]
where fac= [------------] [----------- ]
[!d.x_vsize ] [!d.x_ch_size]
PS X
Thus, to ensure that plotted character strings scale
properly in postscript mode, specify all character
sizes as as multiples of !p.charsize.
EXAMPLE:
View the IDL dist function and then make a hardcopy:
d=dist(200)
loadct,5
tvscl,d ; view the plot on X-windows
toggle,/color,/landscape ; redirect output to plotc.ps
tvscl,d ; write plot onto plotc.ps
toggle,/print ; resume output to X-windows
; submit plot job to default printer
toggle,/color,/land
tvscl,d
toggle,print='term' ; submit plot "term" print queue
author: Paul Ricchiazzi 1jun92
Institute for Computational Earth System Science
University of California, Santa Barbara
NOTE: you can check for the currently defined print queues in /etc/printcap
REVISIONS:
feb93: added PRINT keyword
feb93: set yoffset=10.5 in landscape mode
feb93: added FILENAME keyword
mar93: added bits=8 in black and white mode
mar96: modify !p.charsize to compensate for larger ps font size
mar96: send output to print queue tree on eos
(See /home/drw/idl/old.esrg/toggle.pro)
TOR_BRANDT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: TOR_BRANDT
PURPOSE: Simulate the spectral broadening due to a torsional oscillation
at maximum amplitude (refinements to follow) given the rotational
velocity given by Brandt (196x). Then save
the data to a .SAV file with the velocity amplitude in the title.
INPUTS:
vel_amp: The velocity amplitude in km/s, as an integer, float or
double-precision float. It will be converted to double-precision
float internally.
OUTPUTS: The programme should produce a .SAV file in:
/disk/solar2/drw/mallorca/brandt/
with the name format:
sim_brandt_broadonly_vVEL_AMP.sav
HISTORY: DRW @ MSSL, 04-Nov-2003
(based on torsional_paper.bat)
(See /home/drw/idl/tor_brandt.pro)
TOR_RUDERMAN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: TOR_RUDERMAN
PURPOSE: Simulate the spectral broadening due to a torsional oscillation
at maximum amplitude (refinements to follow) given the rotational
velocity given by Ruderman et al. 1997 (A&A 320, p305). Then save
the data to a .SAV file with the velocity amplitude in the title.
INPUTS:
vel_amp: The velocity amplitude in km/s, as an integer, float or
double-precision float. It will be converted to double-precision
float internally.
OUTPUTS: The programme should produce a .SAV file in:
/disk/solar2/drw/mallorca/ruderman/
with the name format:
sim_ruderman_broadonly_vVEL_AMP.sav
HISTORY: DRW @ MSSL, 04-Nov-2003
(based on torsional_paper.bat)
(See /home/drw/idl/tor_ruderman.pro)
TRACE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: TRACE
PURPOSE: Define a path through a plot or image using the image display
system and the cursor/mouse. TRACE can be used either to
obtain the vector of x and y vertices of a path in data
coordinates or, when used with TVIM, the array of image
indecies of all points along the path or inside the defined
polygon.
CATEGORY: Image processing.
CALLING SEQUENCE:
trace,xv,yv,ii,retore=retore,silent=silent,region=region,dt=dt,
color=color
INPUTS: none
KEYWORD INPUT PARAMETERS:
RESTORE if set, originaly displayed image is restored to its
original state on completion.
SILENT If set no intructional printout is issued at the
beginning of execution
DT repitition time interval for adding or removing nodes
when the mouse button is held down
REGION keyword REGION is set II contains indecies of all points
within the polygon defined by XV and YV
COLOR color to shade polygonal region,
works only when REGION is set and RESTORE is not set
OUTPUTS:
XV Vector of x vertices of traced path in data coordinates
YV Vector of y vertices of traced path in data coordinates
ii subscript vector of all pixels along defined path. This works
on an image displayed by TVIM as long as you don't define
an XRANGE and YRANGE in the TVIM call.
if keyword REGION is set II contains indecies of all points
within the polygon defined by XV and YV
COMMON BLOCKS:
None.
SIDE EFFECTS:
Display is changed if RESTORE is not set.
RESTRICTIONS:
1. Only works for interactive, pixel oriented devices with a
cursor and an exclusive or writing mode.
2. A path may have at most 1000 vertices. If this is not enough
edit the line setting MAXPNTS.
3. Only works with images displayed by TVIM
PROCEDURE:
This procedure is intended to be used with TVIM. The original
TVIM image should be displayed without the XRANGE and YRANGE
parameters set, because in this case the x and y axis of the
TVIM plot represents the actual image or array coordinates of
the imaged quantity. TRACE uses these values to compute the
array indices either along a transect or within a specified
polygonal region.
The exclusive-or drawing mode is used to allow drawing and
erasing objects over the original object.
The operator marks the vertices of the path, either by
dragging the mouse with the left button depressed or by
marking individual points along the path by clicking the
left mouse button, or with a combination of both.
The center button removes the most recently drawn points.
Press the right mouse button when finished. On exit gaps in the
traced path are filled by interpolation
EXAMPLE
!p.multi=[0,1,2]
d=dist(300,100)
tvim,d
trace,xv,yv,ii ; draw a circle inside the image with the
; the left mouse button pressed down
polyfill,xv,yv,color=100 ; shade the selected region
oplot,xv,yv,psym=-1 ; highlight the border of the region
plot,d(ii),psym=-1 ; plot a transect of the path
; blowup a given region and show it under the original image
loadct,5
!p.multi=[0,1,2]
a=randata(200,200,s=4)
rng=[min(a,max=amx),amx] ; save range for use in blowup
tvim,a,/scale,range=rng
trace,xv,yv,ii,/region
xv=[xv,xv(0)] & yv=[yv,yv(0)]
oplot,xv,yv ; show border of blowup region
xrng=[min(xv,max=xmx),xmx] ; save xrng and yrng for blowup
yrng=[min(yv,max=ymx),ymx]
b=fltarr(200,200)
b(ii)=a(ii) ; show only the selected region
b=b(xrng(0):xrng(1),yrng(0):yrng(1))
tvim,b,xrange=xrng,yrange=yrng,range=rng,/scale
oplot,xv,yv ; show border of blowup region
Adapted from DEFROI by : Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS
29oct92: if no points are selected return -1
11nov92: allow input parameter AA to be 2 element vector
26apr93: massive simplifications to make TRACE easier to use
(See /home/drw/idl/esrg/trace.pro)
TRACE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: TRACE
PURPOSE: Define a path through a plot or image using the image display
system and the cursor/mouse. TRACE can be used either to
obtain the vector of x and y vertices of a path in data
coordinates or, when used with TVIM, the array of image
indecies of all points along the path or inside the defined
polygon.
CATEGORY: Image processing.
CALLING SEQUENCE:
trace,xv,yv,ii,retore=retore,silent=silent,region=region,dt=dt,
color=color
INPUTS: none
KEYWORD INPUT PARAMETERS:
RESTORE if set, originaly displayed image is restored to its
original state on completion.
SILENT If set no intructional printout is issued at the
beginning of execution
DT repitition time interval for adding or removing nodes
when the mouse button is held down
REGION keyword REGION is set II contains indecies of all points
within the polygon defined by XV and YV
COLOR color to shade polygonal region,
works only when REGION is set and RESTORE is not set
OUTPUTS:
XV Vector of x vertices of traced path in data coordinates
YV Vector of y vertices of traced path in data coordinates
ii subscript vector of all pixels along defined path. This works
on an image displayed by TVIM as long as you don't define
an XRANGE and YRANGE in the TVIM call.
if keyword REGION is set II contains indecies of all points
within the polygon defined by XV and YV
COMMON BLOCKS:
None.
SIDE EFFECTS:
Display is changed if RESTORE is not set.
RESTRICTIONS:
1. Only works for interactive, pixel oriented devices with a
cursor and an exclusive or writing mode.
2. A path may have at most 1000 vertices. If this is not enough
edit the line setting MAXPNTS.
3. Only works with images displayed by TVIM
PROCEDURE:
This procedure is intended to be used with TVIM. The original
TVIM image should be displayed without the XRANGE and YRANGE
parameters set, because in this case the x and y axis of the
TVIM plot represents the actual image or array coordinates of
the imaged quantity. TRACE uses these values to compute the
array indices either along a transect or within a specified
polygonal region.
The exclusive-or drawing mode is used to allow drawing and
erasing objects over the original object.
The operator marks the vertices of the path, either by
dragging the mouse with the left button depressed or by
marking individual points along the path by clicking the
left mouse button, or with a combination of both.
The center button removes the most recently drawn points.
Press the right mouse button when finished. On exit gaps in the
traced path are filled by interpolation
EXAMPLE
!p.multi=[0,1,2]
d=dist(300,100)
tvim,d
trace,xv,yv,ii ; draw a circle inside the image with the
; the left mouse button pressed down
polyfill,xv,yv,color=100 ; shade the selected region
oplot,xv,yv,psym=-1 ; highlight the border of the region
plot,d(ii),psym=-1 ; plot a transect of the path
; blowup a given region and show it under the original image
loadct,5
!p.multi=[0,1,2]
a=randata(200,200,s=4)
rng=[min(a,max=amx),amx] ; save range for use in blowup
tvim,a,/scale,range=rng
trace,xv,yv,ii,/region
xv=[xv,xv(0)] & yv=[yv,yv(0)]
oplot,xv,yv ; show border of blowup region
xrng=[min(xv,max=xmx),xmx] ; save xrng and yrng for blowup
yrng=[min(yv,max=ymx),ymx]
b=fltarr(200,200)
b(ii)=a(ii) ; show only the selected region
b=b(xrng(0):xrng(1),yrng(0):yrng(1))
tvim,b,xrange=xrng,yrange=yrng,range=rng,/scale
oplot,xv,yv ; show border of blowup region
Adapted from DEFROI by : Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS
29oct92: if no points are selected return -1
11nov92: allow input parameter AA to be 2 element vector
26apr93: massive simplifications to make TRACE easier to use
(See /home/drw/idl/old.esrg/trace.pro)
TRACK_LENGTH[1]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
TRACK_LENGTH
PURPOSE:
To plot points over an image by clicking on them
and ultimately to draw lines between these points
to track the motion of flare spray ejecta. Still
under development. Uses a 64x2 array to store the
point co-ordinates, so the maximum number of
points is 64. This is easily changed, however.
CALLING SEQUENCE:
track_length
INPUTS:
None
CALLS:
CURSOR
AUTHOR:
David Williams, 7/12/99
(See /home/drw/idl/bin/track_length.pro)
TRACK_LENGTH[2]
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
TRACK_LENGTH
PURPOSE:
To record co-ordinates of points in an image by
clicking on them, so that they can be plotted to
a PostScript file, with lines drawn between these points
to track the motion of flare spray ejecta. Still
under development. Uses a 2x256 array to store the
point co-ordinates, so the maximum number of
points is 256. This is easily changed, however.
CALLING SEQUENCE:
track_length
INPUTS:
None
CALLS:
CURSOR
AUTHOR:
David Williams, 7/12/99
(See /home/drw/idl/bin/track_length_plot.pro)
TRACK_TOP.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TRACK_TOP.PRO
PURPOSE:
To show all parts of the SECIS prominence
whose values are greater then 900. Hopefully
will help to show the prominence in useful
terms. Only works for one frame in current
incarnation. Working on that :)
USAGE:
track_top,frame
DATE:
19/1/2000
(See /home/drw/idl/secis/track_top.pro)
TRACK_WARP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TRACK_WARP
PURPOSE:
to monitor the warp in a VTT Fe I image sequence due to
seeing variations.
USAGE:
TRACK_WARP,CUBEIN,POS_CUBE
INPUTS:
CUBEIN - input cube of images
OUTPUTS:
POS_CUBE - output cube of [x,y,t]
x: absolute x co-ordinate of a grid point
y: similar
t: frame index
KEYWORDS:
??
HISTORY:
testing only.
(See /home/drw/idl/vtt/track_warp.pro)
TRANSLATE_SUB_SUPER[1]
[Previous Routine]
[Next Routine]
[List of Routines]
SPECIAL NOTE:
The file translate_sub_super.pro contains two functions,
translate_sub_super, and sub_sup_idl. The former is the
generic routine for processing TeX sub/superscripts, the
latter is used only by translate_sub_super and has no general
utility. Hence it lives here. You will see documentation for
translate_sub_super second if you use DOC_LIBRARY.
(See /home/drw/idl/aux/translate_sub_super.pro)
TRANSLATE_SUB_SUPER[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TRANSLATE_SUB_SUPER
PURPOSE:
Translate TeX sub/superscripts to IDL sub/superscripts.
CATEGORY:
text/strings
CALLING SEQUENCE:
new = translate_sub_super( old )
INPUTS:
old -- string to be translated from TeX to IDL. in
KEYWORD PARAMETERS:
/RECURSED -- set if this function is being called
recursively.
/HELP -- Set to print useful message and exit.
OUTPUTS:
new -- string old converted from TeX to IDL out
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
- For best results, when both a sub and superscript are used,
place the shorter of the two first (e.g. 'N^{a}_{bbbb}' is
better than 'N_{bbbb}^{a}').
- Single character sub/super scripts do not need to be
protected by braces.
- Sub/superscripts may be nested (e.g. 'N^{N_1^N}').
EXAMPLE:
out = translate_sub_super( 'N^2_{big}' )
Then out='N!U2!N!Dbig!N' which looks like it should on the
display.
LIBRARY FUNCTIONS CALLED:
str_token -- Text/string (mcraig)
sub_sup_idl -- contained in this file
MODIFICATION HISTORY:
$Id: translate_sub_super.pro,v 1.5 2000/06/14 19:09:22 mcraig Exp $
$Log: translate_sub_super.pro,v $
Revision 1.5 2000/06/14 19:09:22 mcraig
Changed name of strtok str_token to avoid conflict in IDL 5.3.
Revision 1.4 1996/06/14 20:00:27 mcraig
Updated Copyright info.
Revision 1.3 1996/05/09 00:22:17 mcraig
Changed some function calls to reflect changes in those functions, moved
some code out of the main loop that didn't need to be there, added
documentation.
Revision 1.2 1996/02/08 18:54:20 mcraig
Changed default sub/superscript size to be !D/!U rather than !I/!E to
improve readability of plat annotations.
Revision 1.1 1996/01/31 18:47:37 mcraig
Initial revision
RELEASE:
$Name: Rel_2_0 $
COPYRIGHT:
Copyright (C) 1996 The Regents of the University of California, All
Rights Reserved. Written by Matthew W. Craig.
See the file COPYRIGHT for restrictions on distrubting this code.
This code comes with absolutely NO warranty; see DISCLAIMER for details.
(See /home/drw/idl/aux/translate_sub_super.pro)
TRANSREAD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TRANSREAD
AUTHOR:
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
PURPOSE:
Parse a tabular ASCII data file or string array.
CALLING SEQUENCE:
TRANSREAD, UNIT, VARi [, FORMAT=FORMAT] (first usage)
or
TRANSREAD, UNIT, VARi [, FORMAT=FORMAT], FILENAME=FILENAME (second usage)
or
TRANSREAD, STRINGARRAY, VARi [, FORMAT=FORMAT] (second usage)
DESCRIPTION:
TRANSREAD parses an ASCII table into IDL variables, one variable
for each column in the table. The tabular data is not limited to
numerical values, and can be processed with an IDL FORMAT
expression.
TRANSREAD behaves similarly to READF/READS in that it transfers
ASCII input data into IDL variables. The difference is that
TRANSREAD reads more than one row in one pass, and returns data by
column. In a sense, it forms the *transpose* of the typical
output from READF or READS (which returns data by row), hence the
name TRANSREAD. [ TRANSREAD can parse up to 20 columns in its
current implementation, but that number can be easily increased. ]
TRANSREAD can optionally be provided with a FORMAT expression to
control the transfer of data. The usage is the same as for
READ/READF/READS. However, you may find that you need to slightly
modify your format statements to read properly. In this
implementation, variables are intermediately parsed with READS,
which appears from my experimentation to require at least a
default length for transfers.
Hence, you should use: ..., FORMAT='(D0.0,D0.0,I0)' ; GOOD
instead of: ..., FORMAT='(D,D,I)' ; BAD
As with the standard IDL READ-style commands, you need to supply
initial values to your variables before calling TRANSREAD, which
are used to determine the type. Then dimensions of the variable
are not important; TRANSREAD will grow the arrays to an
appropriate size to accomodate the input. Lines from the input
which do not contain the correct number of columns or do not obey
the format statement are ignored.
TRANSREAD will also flexibly manage typical data files, which may
contain blank lines, lines with comments (see COMMENT keyword), or
incomplete lines. These lines are ignored. It can be programmed
to wait for a user-specified "trigger" phrase in the input before
beginning or ending processing, which can be useful if for example
the input table contains some header lines (see STARTCUE and
STOPCUE keywords). [ The user can also pre-read these lines
before calling TRANSREAD. ] Finally, the total number of lines
read can be controlled (see MAXLINES keyword). TRANSREAD parses
until (a) the file ends, (b) the STOPCUE condition is met or (c)
the number of lines read reaches MAXLINES.
TRANSREAD has three possible usages. In the first, the file must
already be open, and TRANSREAD begins reading at the current file
position. In the second usage, a filename is given. TRANSREAD
automatically opens the file, and reads tabular data from the
beginning of the file. Normally the file is then closed, but this
can be prevented by using the NOCLOSE keyword.
In the third usage, a string array is passed instead of a file
unit. Elements from the array are used one-by-one as if they were
read from the file.
Since TRANSREAD is not vectorized, and does a significant amount
of processing on a per-line basis, it is probably not optimal to
use on very large data files.
INPUTS:
UNIT - in the first usage, UNIT is an open file unit which
contains ASCII tabular data to read. UNIT must not be a
variable which could be mistaken for a string array.
In the second usage, when FILENAME is specified, then upon
return UNIT contains the file unit that TRANSREAD used for
reading. Normally, the UNIT is closed before return, but
it can be kept open using the NOCLOSE keyword. In that
case the unit should be closed with FREE_LUN.
STRINGARRAY - this is the third usage of TRANSREAD. When a string
array is passed, elements from the array are used as
if they were lines from an input file. The array
must not be of a numeric type, so it cannot be
mistaken for a file unit. [ Of course, the string
itself can contain ASCII numeric data. ]
OUTPUTS:
VARi - List of named variables to receive columns from the table,
one variable for each column. Upon output each variable
will be an array containing the same number of elements,
one for each row in the table. If no rows were
successfully parsed, then the variable values are not
changed. Use the COUNT output keyword to determine whether
any rows were parsed.
NOTE: Up to twenty columns may be parsed. If more columns
are desired, then a simple modification must be made to the
IDL source code. To do so, find the beginning of the
procdure definition, identified by the words, "pro
transread, ..." and follow the instructions there.
INPUT KEYWORD PARAMETERS:
FORMAT - an IDL format expression to be used to transfer *each*
row in the table. If no format as given then the default
IDL transfer format is used, based on the types of the
input variables. As mentioned in the description above,
a length should be assigned to each format code; a length
of zero can be used for numeric types. Lines from the
input which do not contain the correct number of columns
or do not obey the format statement are ignored.
COMMENT - A one-character string which designates a "comment" in
the input. Input lines beginning with this character
(preceded by optional spaces) are ignored. FAILCOUNT
does not increase.
DEFAULT: no comments are recognized.
NOTE: lines which do not match the format statement are
ignored. Comments are likely to be ignored based on
this behavior, even without specifying the COMMENT
keyword; however the FAILCOUNT will increase.
MAXLINES - the maximum number of lines to be read from input. The
count begins *after* any STARTCUE is satisfied (if any)
DEFAULT: no maximum is imposed.
SKIPLINES - the number of lines of input to skip before beginning
to parse the table.
DEFAULT: no lines are skipped.
NOTE: if STARTCUE is also given, then the line count
does not start until after the STARTCUE phrase has
been encountered.
STARTCUE - a unique string phrase that triggers the start of
parsing. Lines up to and including the line containing
the cue are ignored. Because each line is checked for
this starting cue, it should be unambiguous.
DEFAULT: parsing begins immediately.
STOPCUE - a unique string phrase that triggers the finishing of
parsing. The line including the cue is ignored, and no
more reads occur afterward.
DEFAULT: no STOPCUE is imposed.
FILENAME - the presence of this keyword signals the second usage,
where TRANSREAD explicitly opens the input file named
by the string FILENAME. Reading begins at the start of
the file.
Normally TRANSREAD will close the input file when it
finishes. This can be prevented by setting the NOCLOSE
keyword.
DEFAULT: input is either an already-opened file passed
via the UNIT keyword, or a string array.
NOCLOSE - if set and if FILENAME is given, then the file is not
closed upon return. The file unit is returned in UNIT,
and must be closed by the user via FREE_LUN, UNIT.
DEFAULT: any files that TRANSREAD opens are closed.
DEBUG - set this keyword to enable debugging messages. Detailed
error messages will be printed for each failed line.
OUTPUT KEYWORDS:
LINES - the number of lines read, including comments and failed
parses.
COUNT - the number of rows successfully parsed. Can be zero if
accessing the input utterly fails, or if no rows are
present.
FAILCOUNT - the number of rows that could not be parsed
successfully. Comments and blank lines are not
included.
EXAMPLES:
OPENR, UNIT, 'widgets.dat', /GET_LUN
A = '' & B = 0L & C = 0D
TRANSREAD, UNIT, A, B, C, COUNT=COUNT, FORMAT='(A10,I0,D0.0)'
FREE_LUN, UNIT
(First usage) Opens widgets.dat and reads three columns. The
first column is a ten-character string, the second an integer, and
the third a double precision value.
A = '' & B = 0L & C = 0D
TRANSREAD, UNIT, A, B, C, COUNT=COUNT, FORMAT='(A10,I0,D0.0)', $
FILENAME='widgets.dat'
(Second usage) Achieves the same effect as the first example, but
TRANSREAD opens and closes the file automatically.
SPAWN, 'cat widgets.dat', BUF
A = '' & B = 0L & C = 0D
TRANSREAD, BUF, A, B, C, COUNT=COUNT, FORMAT='(A10,I0,D0.0)'
(Third usage) Achieves the same effect as the first two examples,
but input is read from the string variable BUF.
MODIFICATION HISTORY:
Feb 1999, Written, CM
Mar 1999, Added SKIPLINES and moved on_ioerror out of loop, CM
Jun 2000, Added NOCATCH and DEBUG keyword options, CM
$Id: transread.pro,v 1.2 2001/03/25 18:10:43 craigm Exp $
(See /home/drw/idl/aux/markwardt/transread.pro)
TRANS_BYTES
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
TRANS_BYTES
*PURPOSE:
To translate the byte representation of IDL variables to
a format compatible with the host operating system as defined
by the IDL system variable !version.arch. TRANS_BYTES currently
supports SPARC (Sun-4s and SPARCStations), MIPSEL (DECstation 3100
and IBM 386 class PCs), and VAX (VAXstation and MicroVAX).
*CALLING SEQUENCE:
TRANS_BYTES, BYTE_EQ, vartyp, cpupar
*PARAMETERS:
BYTE_EQ (REQ) (IO) (B) (012)
The byte representation of the data variable to be converted.
vartyp (OPT) (I) (I) (0)
Parameter to identify the type of data which BYTE_EQ represents.
byte 1
integer 2
longword integer 3
floating point 4
double precision 5
If VARTYP is not given in the call, the user will be prompted
for it.
cpupar (OPT) (I) (I) (0)
Parameter to identify data translation mode. If not present
in the calling statement, TRANS_BYTES will prompt the user.
no conversion 0
VAX to MIPSEL 1
MIPSEL to VAX 2
VAX to SPARC 3
SPARC to VAX 4
MIPSEL to SPARC 5
SPARC to MIPSEL 6
Supported Data Types:
VAX - VAXstations, MicroVAX
MIPSEL - DECstations, IBM 386
SPARC - SparcStations, Sun 4##
No Conversion is required between like data types, such as
DECstations and IBM 386s.
If CPUPAR is not given in the call, the user will be prompted
for it.
*SIDE EFFECTS:
*SUBROUTINES CALLED:
SWAP_BYTES
PARCHECK
*SYSTEM VARIABLES USED:
*NOTES:
The internal data formats currently supported are:
SunOs data type:
SUN4's and SPARCStations
IEEE standard (Big Endian Configuration)
DECStation data type:
IEEE standard (Little Endian Configuration)
VAXStation data type:
VAX (not IEEE)
This program considers floating point to be the VMS
"f-floating", and double precision to be "d-floating".
H-floating and g-floating are not supported.
DOS data type:
IEEE standard (same as DECstation)
The IEEE standard data types differ only in the byte order.
Big Indian configuration has the most significant byte at the
lowest machine address. For the Little Endian configuration,
the least significant byte is at the lowest machine address.
Big Endian: | 0 | 1 | 2 | 3 |
Little Endian: | 3 | 2 | 1 | 0 |
The IEEE standard single precision Big Endian representation is:
| 0 | 1 | ...
31 0
S E E E E E E E E F F F F F F F ...
Here, the "S" is the sign bit, "E"'s are the exponent bits,
and the "F"'s are the normalized fraction bits.
The IEEE standard floating point data types contain on sign bit,
an eight bit exponent field biased by 127, and a 23 bit fraction.
There are two reserved values, Nan (not a number), and infinity.
The VAX single precision floating point data type contains one
sign bit, an eight bit exponent biased by 128, and a 23 bit
normalized fraction. There is only on reserved value for the VAX,
reserved operand fault. The sign bit is bit number 15, bits 7
through 14 contain the exponent, and the remaining bits contain
the normalized fraction.
The IEEE standard double precision data types contain one sign
bit, an eleven bit exponent, biased by 1023, and a 52 bit
normalized fraction. The bit ordering within the bytes is
similar to that of single precision.
The VAX d-floating double precision floating point representation
contain one sign bit, an 8 bit exponent biased by 128, and a 55
55 bit normalized fraction. Again, the sign bit is bit 15, and
the exponent is contained in bits 7 through 14.
The same reserved values occur in double precision.
tested with IDL Version 2.1.2 (sunos sparc) 14 Oct 91
tested with IDL Version 2.1.2 (ultrix mipsel) 14 Oct 91
tested with IDL Version 2.2.0 (ultrix vax) 14 Oct 91
tested with IDL Version 2.1.2 (vms vax) 14 Oct 91
*RESTRICTIONS:
Converting the byte representation of a floating point or double
precision number to floating point or double precision type on a
CPU for which the byte representation was not intended may cause
conflicts with reserved values (i.e. NaN, infinity, or reserved
operand faults), resulting in corrupted data.
*EXAMPLE:
*MODIFICATION HISTORY:
Version 1 of vtos.pro By John Hoegy 13-Jun-88
27-Oct-89 - GD: Slightly modified program vtos.pro according
to suggestions by RWT.
5/30/90 RWT merge vtos and vtod to create vtou
1/25/90 GRA Modified vtou to enable transfers between VMS, ULTRIX
and SunOs systems.
3/18/91 GRA Renamed vtou to TRANS_BYTES.
3/28/91 PJL added PARCHECK
4/24/91 RWT add support for DOS
6/24/91 GRA cleaned up
7/26/91 RWT add cpupar=0 option for no conversion
10/8/91 GRA globally changed all references to "syspar" to "cpupar",
changed cpupar to reference machine architecture as
defined by !version.arch; tested on sunos/sparc,
ultrix/mipsel, ultrix/vax, and vms/vax.
(See /home/drw/idl/icur/trans_bytes.pro)
TRIM()
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TRIM()
PURPOSE:
Converts numbers to strings, without trailing zeros.
EXPLANATION:
Converts numbers into a string representation, and trims off leading
and/or trailing blanks. Differs from STRTRIM in that trailing zeros
after the period are also trimmed off, unless NUMBER is already a
string, or an explicit format is passed.
CALLING SEQUENCE:
Result = TRIM( NUMBER [, FORMAT ] [, FLAG ] )
INPUTS:
NUMBER = Scalar variable or constant. May be of any ordinary type,
including string. However, structures are not allowed.
OPTIONAL INPUTS :
FORMAT - Format specification for STRING function. Must be a string
variable, start with the "(" character, end with the ")"
character, and be a valid FORTRAN format specification. If
NUMBER is complex, then FORMAT will be applied separately to
the real and imaginary parts.
FLAG - Flag passed to STRTRIM to control the type of trimming:
FLAG = 0 Trim trailing blanks.
FLAG = 1 Trim leading blanks.
FLAG = 2 Trim both leading and trailing blanks.
The default value is 2. If NUMBER is complex, then FORMAT
will be applied separately to the real and imaginary parts.
OUTPUTS:
Function returns as a string variable representing the value NUMBER.
RESTRICTIONS:
NUMBER must not be an array. NUMBER must not be a structure.
FORMAT must be a valid format specification, and must not be passed
if NUMBER is of type string.
FLAG must not be of string type, or an array.
PROCEDURES USED:
None
REVISION HISTORY:
Version 1, William Thompson, GSFC, 9 April 1993,
Transferred from Solar Library, W. Landsman September 1997
Updated parentheses to V5.0, W. Landsman September 1997
Added check for undefined input D. Zarro December 1998
(See /home/drw/idl/esrg/trim.pro)
TRI_SURF[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TRI_SURF
PURPOSE:
This function Interpolates a regularly or irregularly gridded
set of points with a C1 smooth quintic surface.
CATEGORY:
Mathematical functions, Interpolation, Surface Fitting
CALLING SEQUENCE:
Result = TRI_SURF(Z [, X, Y])
INPUTS:
X, Y, Z: arrays containing the X, Y, and Z coordinates of the
data points on the surface. Points need not be
regularly gridded. For regularly gridded input data,
X and Y are not used: the grid spacing is specified
via the XGRID and YGRID (or XVALUES and YVALUES)
keywords, and Z must be a two dimensional array.
For irregular grids, all three parameters must be
present and have the same number of elements.
KEYWORD PARAMETERS:
Input grid description:
REGULAR: if set, the Z parameter is a two dimensional array
of dimensions (N,M), containing measurements over a
regular grid. If any of XGRID, YGRID, XVALUES, YVALUES
are specified, REGULAR is implied. REGULAR is also
implied if there is only one parameter, Z. If REGULAR is
set, and no grid (_VALUE or _GRID) specifications are
present, the respective grid is set to (0, 1, 2, ...).
XGRID: contains a two element array, [xstart, xspacing],
defining the input grid in the X direction. Do not
specify both XGRID and XVALUES.
XVALUES: if present, XVALUES(i) contains the X location
of Z(i,j). XVALUES must be dimensioned with N elements.
YGRID: contains a two element array, [ystart, yspacing],
defining the input grid in the Y direction. Do not
specify both YGRID and YVALUES.
YVALUES: if present, YVALUES(i) contains the Y location
of Z(i,j). YVALUES must be dimensioned with N elements.
Output grid description:
GS: If present, GS must be a two-element vector [XS, YS],
where XS is the horizontal spacing between grid points
and YS is the vertical spacing. The default is based on
the extents of X and Y. If the grid starts at X value
Xmin and ends at Xmax, then the default horizontal
spacing is (Xmax - Xmin)/(NX-1). YS is computed in the
same way. The default grid size, if neither NX or NY
are specified, is 26 by 26.
BOUNDS: If present, BOUNDS must be a four element array containing
the grid limits in X and Y of the output grid:
[Xmin, Ymin, Xmax, Ymax]. If not specified, the grid
limits are set to the extent of X and Y.
NX: The output grid size in the X direction. NX need not
be specified if the size can be inferred from GS and
BOUNDS. The default value is 26.
NY: The output grid size in the Y direction. See NX.
Others:
EXTRAPOLATE: If set, extrapolate the surface to points outside
the convex hull of input points. Has no effect if
input points are regularly gridded.
MISSING: If set, points outside the convex hull of input points
are set to this value. Default is 0. Has no effect
if input points are regularly gridded.
OUTPUTS:
This function returns a two-dimensional floating point array
containing the interpolated surface, sampled at the grid points.
RESTRICTIONS:
The output grid must enclose convex hull of the input points.
PROCEDURE:
This routine is similar to MIN_CURVE_SURF but the surface
fitted is a smooth surface, not a minimum curvature surface. This
routine has the advantage of being much more efficient
for larger numbers of points.
The built-in IDL routines TRIANGULATE and TRIGRID(/QUINTIC) are
used.
EXAMPLES:
Example 1: Irregularly gridded cases
Make a random set of points that lie on a gaussian:
n = 15 ;# random points
x = RANDOMU(seed, n)
y = RANDOMU(seed, n)
z = exp(-2 * ((x-.5)^2 + (y-.5)^2)) ;The gaussian
get a 26 by 26 grid over the rectangle bounding x and y:
r = TRI_SURF(z, x, y) ;Get the surface.
Or: get a surface over the unit square, with spacing of 0.05:
r = TRI_SURF(z, x, y, GS=[0.05, 0.05], BOUNDS=[0,0,1,1])
Or: get a 10 by 10 surface over the rectangle bounding x and y:
r = TRI_SURF(z, x, y, NX=10, NY=10)
Example 2: Regularly gridded cases
Make some random data
z = randomu(seed, 5, 6)
interpolate to a 26 x 26 grid:
CONTOUR, TRI_SURF(z, /REGULAR)
MODIFICATION HISTORY:
DMS, RSI, October, 1993. Written.
(See /home/drw/idl/esrg/tri_surf.pro)
TRI_SURF[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TRI_SURF
PURPOSE:
This function Interpolates a regularly or irregularly gridded
set of points with a C1 smooth quintic surface.
CATEGORY:
Mathematical functions, Interpolation, Surface Fitting
CALLING SEQUENCE:
Result = TRI_SURF(Z [, X, Y])
INPUTS:
X, Y, Z: arrays containing the X, Y, and Z coordinates of the
data points on the surface. Points need not be
regularly gridded. For regularly gridded input data,
X and Y are not used: the grid spacing is specified
via the XGRID and YGRID (or XVALUES and YVALUES)
keywords, and Z must be a two dimensional array.
For irregular grids, all three parameters must be
present and have the same number of elements.
KEYWORD PARAMETERS:
Input grid description:
REGULAR: if set, the Z parameter is a two dimensional array
of dimensions (N,M), containing measurements over a
regular grid. If any of XGRID, YGRID, XVALUES, YVALUES
are specified, REGULAR is implied. REGULAR is also
implied if there is only one parameter, Z. If REGULAR is
set, and no grid (_VALUE or _GRID) specifications are
present, the respective grid is set to (0, 1, 2, ...).
XGRID: contains a two element array, [xstart, xspacing],
defining the input grid in the X direction. Do not
specify both XGRID and XVALUES.
XVALUES: if present, XVALUES(i) contains the X location
of Z(i,j). XVALUES must be dimensioned with N elements.
YGRID: contains a two element array, [ystart, yspacing],
defining the input grid in the Y direction. Do not
specify both YGRID and YVALUES.
YVALUES: if present, YVALUES(i) contains the Y location
of Z(i,j). YVALUES must be dimensioned with N elements.
Output grid description:
GS: If present, GS must be a two-element vector [XS, YS],
where XS is the horizontal spacing between grid points
and YS is the vertical spacing. The default is based on
the extents of X and Y. If the grid starts at X value
Xmin and ends at Xmax, then the default horizontal
spacing is (Xmax - Xmin)/(NX-1). YS is computed in the
same way. The default grid size, if neither NX or NY
are specified, is 26 by 26.
BOUNDS: If present, BOUNDS must be a four element array containing
the grid limits in X and Y of the output grid:
[Xmin, Ymin, Xmax, Ymax]. If not specified, the grid
limits are set to the extent of X and Y.
NX: The output grid size in the X direction. NX need not
be specified if the size can be inferred from GS and
BOUNDS. The default value is 26.
NY: The output grid size in the Y direction. See NX.
Others:
EXTRAPOLATE: If set, extrapolate the surface to points outside
the convex hull of input points. Has no effect if
input points are regularly gridded.
MISSING: If set, points outside the convex hull of input points
are set to this value. Default is 0. Has no effect
if input points are regularly gridded.
OUTPUTS:
This function returns a two-dimensional floating point array
containing the interpolated surface, sampled at the grid points.
RESTRICTIONS:
The output grid must enclose convex hull of the input points.
PROCEDURE:
This routine is similar to MIN_CURVE_SURF but the surface
fitted is a smooth surface, not a minimum curvature surface. This
routine has the advantage of being much more efficient
for larger numbers of points.
The built-in IDL routines TRIANGULATE and TRIGRID(/QUINTIC) are
used.
EXAMPLES:
Example 1: Irregularly gridded cases
Make a random set of points that lie on a gaussian:
n = 15 ;# random points
x = RANDOMU(seed, n)
y = RANDOMU(seed, n)
z = exp(-2 * ((x-.5)^2 + (y-.5)^2)) ;The gaussian
get a 26 by 26 grid over the rectangle bounding x and y:
r = TRI_SURF(z, x, y) ;Get the surface.
Or: get a surface over the unit square, with spacing of 0.05:
r = TRI_SURF(z, x, y, GS=[0.05, 0.05], BOUNDS=[0,0,1,1])
Or: get a 10 by 10 surface over the rectangle bounding x and y:
r = TRI_SURF(z, x, y, NX=10, NY=10)
Example 2: Regularly gridded cases
Make some random data
z = randomu(seed, 5, 6)
interpolate to a 26 x 26 grid:
CONTOUR, TRI_SURF(z, /REGULAR)
MODIFICATION HISTORY:
DMS, RSI, October, 1993. Written.
(See /home/drw/idl/old.esrg/tri_surf.pro)
TURNING_POINTS[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: turning_points
PURPOSE: Locate turning points in a curve
USEAGE: TURNING_POINTS, Curve, Pos, Number
INPUT:
Curve The 1-D array inwhich peaks are to be detected
OUTPUT:
Pos Array containg zeros where there are no turning points and
a value otherwise.
Number The Number of turning points detected in the array.
AUTHOR: Peter T. Gallagher, May '98
(See /home/drw/idl/bin/turning_points.pro)
TURNING_POINTS[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: turning_points
PURPOSE: Locate turning points in a curve
USEAGE: TURNING_POINTS, Curve, Pos, Number
INPUT:
Curve The 1-D array inwhich peaks are to be detected
OUTPUT:
Pos Array containg zeros where there are no turning points and
a value otherwise.
Number The Number of turning points detected in the array.
AUTHOR: Peter T. Gallagher, May '98
(See /home/drw/idl/bin/ptg/turning_points.pro)
TVATS.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TVATS.PRO
PURPOSE:
(TVIM And TimeStamp) Given an image from a movie/data cube
named DATA - DATA(*,*,I) - and a corresponding INDEX structure,
this routine will read the relevant INDEX(I).TIME_OBS variable
and print it in the lower right-hand corner. Works with 128x128,
512x512 and 1024x1024 TRACE images by reading the variable
INDEX(I).NAXIS1. Automatically prints a colour table scale to
the right of the displayed image. For a simple timestamp routine
use TVTS.PRO (as TVATS.PRO but without TVIM)
CALLING SEQUENCE:
tvats,index,data,i
INPUTS:
data - m x n x i(max)+1 array.
index - structure containing all the headers for the images
in the data cube.
i - the number of the image in the data cube
AUTHOR:
David Williams, 1st Mar. 1999
(See /home/drw/idl/bin/tvats.pro)
TVB[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tvb
USEAGE: tvb,im
PURPOSE: Display a large image in one window at reduced resolution.
Use the CURBOX routine to select a region of interest.
The sub-array is displayed in another window at full resolution
For each new sub-array the selected subscript range is printed
to the terminal.
INPUT:
im a large two dimensional image array
OUTPUT: none
PROCEDURE:
when first invoked TVB renders the full image (possibly
at reduced resolution) in a large window. A region of
interest is selected via the CURBOX procedure, by moving
the mouse pointer or pressing the LMB or MMB to
decrease/increase the box size. The region is selected
with the right mouse button. Next, TVB draws the
selected region at full resolution in another window and
puts up a popup menu with 5 options. The operator can
choose to
1. select a new region, killing the last special region window
2. select a new region, keeping the last special region window
3. blow up the current special region window by 50%
4. quit the procedure, keeping all windows
5. quit the procedure, killing all windows
Side Effects:
When items 1,2,4 or 5 are selected the the sub-array indecies of
the save window are printed to the terminal in format,
window wid: (ix1:ix2, iy1:iy2)
where,
wid is the window id of the special region window
ix1:ix2 range of first subscript
iy1:iy2 range of second subscript
the sub array can be retrieved as,
sub_array = im(ix1:ix2, iy1:iy2)
EXAMPLE
loadct,5
im=randata(50,100,s=3)
im=congrid(im,500,1000,/interp)
tvb,im
author: Paul Ricchiazzi oct93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/tvb.pro)
TVB[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tvb
USEAGE: tvb,im
PURPOSE: Display a large image in one window at reduced resolution.
Use the CURBOX routine to select a region of interest.
The sub-array is displayed in another window at full resolution
For each new sub-array the selected subscript range is printed
to the terminal.
INPUT:
im a large two dimensional image array
OUTPUT: none
PROCEDURE:
when first invoked TVB renders the full image (possibly
at reduced resolution) in a large window. A region of
interest is selected via the CURBOX procedure, by moving
the mouse pointer or pressing the LMB or MMB to
decrease/increase the box size. The region is selected
with the right mouse button. Next, TVB draws the
selected region at full resolution in another window and
puts up a popup menu with 5 options. The operator can
choose to
1. select a new region, killing the last special region window
2. select a new region, keeping the last special region window
3. blow up the current special region window by 50%
4. quit the procedure, keeping all windows
5. quit the procedure, killing all windows
Side Effects:
When items 1,2,4 or 5 are selected the the sub-array indecies of
the save window are printed to the terminal in format,
window wid: (ix1:ix2, iy1:iy2)
where,
wid is the window id of the special region window
ix1:ix2 range of first subscript
iy1:iy2 range of second subscript
the sub array can be retrieved as,
sub_array = im(ix1:ix2, iy1:iy2)
EXAMPLE
loadct,5
im=randata(50,100,s=3)
im=congrid(im,500,1000,/interp)
tvb,im
author: Paul Ricchiazzi oct93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/tvb.pro)
TVCDS[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tvcds
PURPOSE: Plot CDS image with correct Solar_X,Solar_Y scale
USEAGE: tvcds,qlds,image
INPUT:
qlds CDS Quick Look Data Structure.
image The image to be plotted
OUTPUT:
Example:
AUTHOR: Peter T. Gallagher, Mar. '98
(See /home/drw/idl/bin/tvcds.pro)
TVCDS[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tvcds
PURPOSE: Plot CDS image with correct Solar_X,Solar_Y scale
USEAGE: tvcds,qlds,image
INPUT:
qlds CDS Quick Look Data Structure.
image The image to be plotted
OUTPUT:
Example:
AUTHOR: Peter T. Gallagher, Mar. '98
(See /home/drw/idl/bin/ptg/tvcds.pro)
TVIMAGE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
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.
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 keyword is used.
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
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.
(See /home/drw/idl/aux/tvimage.pro)
TVIMAGE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TVIMAGE
PURPOSE:
This purpose of TVIMAGE is to allow you to display an image
on the display or in a PostScript file in a particular position.
The position is specified by means of the POSITION keyword. In
this respect, TVIMAGE works like other IDL graphics commands.
Moreover, the TVIMAGE command works identically on the display
and in a PostScript file. You don't have to worry about how to
"size" the image in PostScript. The output on your display and
in the PostScript file will be identical. The major advantage of
TVIMAGE is that it can be used in a natural way with other IDL
graphics commands in resizeable IDL graphics windows. TVIMAGE
is a replacement for TV and assumes the image has been scaled
correctly when it is passed as an argument.
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:
Graphics display.
CALLING SEQUENCE:
TVIMAGE, image
INPUTS:
image: A 2D or 3D image array. It should be byte data.
KEYWORD PARAMETERS:
_EXTRA: This keyword picks up any TV keywords you wish to use.
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.
MINUS_ONE: The value of this keyword is passed along to the CMCONGRID
command. It prevents CMCONGRID from adding an extra row and
column to the resulting array.
HALF_HALF: The value of this keyword is passed along to the
CMCONGRID command, causing the "extra" row and column to
be split evenly between both sides.
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.15, 0.15, 0.85, 0.85]. Note that this can
be an output parameter if the KEEP_ASPECT_RATIO keyword is
used.
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 as an output parameter.
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, 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
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
(See /home/drw/idl/aux/markwardt/tvimage.pro)
TVIM[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tvim
USEAGE: tvim,a
tvim,a,scale=scale,range=range,xrange=xrange,yrange=yrange,$
aspect=aspect,title=title,xtitle=xtitle,ytitle=ytitle,$
noaxis=noaxis,interp=interp,colors=colors,c_map=c_map,$
stitle=stitle,rmarg=rmarg,clip=clip,labels=labels,$
pcharsize=pcharsize,lcharsize=lcharsize,nbotclr=nbotclr,&
clevels=clevels,nodata=nodata,rgb_nodata=rgb_nodata,$
barwidth=barwidth,position=position,noframe=noframe,rct=rct, $
subtitle=subtitle
PURPOSE: Display an image with provisions for
1. numbered color scale
2. plot title
3. annotated x and y axis
4. simplified OPLOT capability
5. manual or automatic scaling with smooth or discreet colors
6 special treatment of "invalid data" pixels
INPUT
a image quantity
Optional keyword input:
title
plot title
xtitle
x axis title
ytitle
y axis title
stitle
color key title (drawn to the right of color scale)
rmarg
right margin expansion factor to provide more room for extra wide
color scale annotation (default=1)
xrange
array spanning entire x axis range. (default = [0,x_dimension-1])
yrange
array spanning entire y axis range. (default = [0,y_dimension-1])
NOTE:TVIM only uses min(XRANGE), max(XRANGE), min(YRANGE) and max(YRANGE).
scale
if set draw color scale. SCALE=2 causes steped color scale
range
two or three element vector indicating physical range over which
to map the color scale. The third element of RANGE, if specified,
sets the step interval of the displayed color scale. It has no
effect when SCALE is not set. E.g., RANGE=[0., 1., 0.1] will
cause the entire color scale to be mapped between the physical
values of zero and one; the step size of the displayed color
scale will be set to 0.1.
clip
specifies a set percentage of pixels which will be left outside
the color scale. Larger values of CLIP yield images with greater
contrast. For example if clip=2 then the color scale range will
be set to include 98% of the pixels and to exclude the brightest
1% and the dimmest 1% of the pixel brightness distribution.
Keyword RANGE overides the effect of CLIP.
If CLIP is a two element vector, the upper and lower percentile
range can be specified. For example CLIP=[0,95] will exclude the
top 5%.
An alternative is to set CLIP to a single negative integer. This
causes the grey scale range to be obtained from the max and min
value of the image array after it is filtered by a 2-D median
filter. The radius of the median filter is set to -clip. Median
filtering is effective in removing "salt and pepper" noise,
(isolated high or low values). For example, setting clip=-1
causes the code to check the 9 element superpixel centered at
each pixel for median values. A single extremely large or small
value does not affect the final value of the median at each pixel
point.
aspect
the x over y aspect ratio of the output image. If not set, aspect
is set to (size_x/size_y) of the input image.
position
specifies the lower left and upper right TVIM frame position in
normal coordinates. When set POSITION overides the setting of
ASPECT.
noaxis
if set do not draw x and y numbered axis around image. Instead
just draw a box
noframe
if set no not draw anything around image, not even a box
interp
TVIM normally uses nearest neighbor sampling to resize the image
to fill the data window area. If INTERP is set the resizing
operation uses bilinear interpolation
If INTERP = 2 the interpolation range is adjusted so that there
is a half pixel border around the plot. This ensures that the
smoothed image properly represents the cell center values of the
pixels, but introduces an extrapolation on the outer edges. This
option has noticeable effects for small (<20) image arrays.
NOTE: When writing to a Postscript file the resizing operation is
accomplished by changing the pixel size. Thus the INTERP
parameter has no effect on Postscript output.
pcharsize
character size of numbers along x and y axis and the title
(default is !p.charsize if non-zero, 1 otherwise)
NOTE: The character size of the x and y-axis number scale
annotation may be independently controlled by the !x.charsize or
!y.charsize system variables. For example, the x and y axis
number scale characters may be made invisible by setting these
variables to a very small non-zero number before calling TVIM.
Remember to restore normal character sizes by setting !x.charsize
and !y.charsize to 1 or zero after the call to TVIM.
lcharsize
character size of color key number or labels (default is
!p.charsize if non-zero, 1 otherwise)
barwidth
width of color key which appears to right of image when SCALE is
set. (default=1)
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies. When the COLORS array is set TVIM
will map values of A into the color values specified in COLORS.
How physical values are assigned to color values depends on how
the RANGE parameter is set, as shown in this table:
RANGE color_value
----- -----------
1. not set COLORS(A)
2. [amin,amax] COLORS((A-amin)/dinc)
3. [amin,amax,inc] COLORS((A-amin)/inc)
where amin, amax and inc are user specified elements of RANGE
and dinc=(amax-amin)/n_elements(COLORS). In case 1, A is used
directly as a subscript into COLORS. When RANGE is not set
legend labels should be used to annotate the color values. In
case 2, A is scaled so that each color defined in COLORS
represents a proportionate fraction of the total dynamic range.
In case 3, amin and inc (and not amax) are used to control which
colors are associated with given physical values. See examples.
c_map
TVIM normally rescales the input image to span the entire color
table range. Setting C_MAP disables this automatic re-scaling.
This is useful when the image byte values correspond to a
particular color mapping that could be destroyed by the
rescaling process (E.G. a gif image).
NOTE: When the number of IDL color table entries is less than
256 some colors may be lost. Use a private color map to avoid
this. See examples.
nbotclr
number of reserved colors at the bottom of the color
table. Color values between 0 and nbotclr-1 will not
be used in the displayed image. This allows the
bottom of the table to be set to special colors which
will not be used in the displayed the image. This
keyword is disabled when either the COLORS or NODATA
options are used. (default=1)
NOTE: by default the color table indicies used within a TVIM
image is limited to the range 1 to !d.n_colors-2. In most
predefined color tables, color index 0 and !d.n_color-1
correspond to pure black and white, respectively. TVIM uses
these color indicies as background and foreground colors for
region blanking and axis annotation. Color tables which do not
define black and white in these index locatations are not good
choices for TVIM plots, unless the first and last color table
entries are redefined as black and white using TVLCT, e.g.,
tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
NOTE: the procedure DCOLORS can be used to load a set
of discreet colors in the bottom 11 color values
(0-10). The original color table is resampled to fit
between color value 11 and the !d.n_colors-1.
nodata
pixel values which are interpreted as invalid data. Pixels
containing this data value are colored with color RGB_NODATA.
rgb_nodata
an RGB value (a 3 component vector) used to color pixels filled
with invalid data. (default = [0,0,0])
NOTE: NODATA and RGB_NODATA override the effect of NBOTCLR
rct
if set, reverse direction of color table. This keyword can be
used on black & white printers to allow large field values to be
represented by dark colors.
subtitle
if used adds a subtitle to the plot. Added by dcjk, QUB, 97.
KEYWORD OUTPUT:
CLEVELS
physical values at the color key tic marks. Use this to set
contour levels in a subsequent call to CONTOUR.
SIDE EFFECTS:
Setting SCALE=2 changes the color scale using the STEP_CT
procedure. The color scale may be returned to its original
state by the command, STEP_CT,/OFF
PROCEDURE:
TVIM first determines the size of the plot data window with a
dummy call to PLOT. When the output device is "X", CONGRID is
used to scale the image to the size of the available data
window. Otherwise, if the output device is Postscript,
scaleable pixels are used in the call to TV.
If the input image quantity is not of type byte, TVIM converts
them to byte by scaleing the input between 0 and !d.n_colors-1.
If the input is already a byte array and if either the number of
color table entries is 256 or if C_MAP is set, then no scaling
is done. This is to ensure consistency with specially defined
private color tables.
After the the image is drawn TVIM calls PLOT again to draw the x
and y axis and titles. Finally if scale is set, TVIM calls the
COLOR_KEY procedure to draw the color scale just to the right of
the data window.
RESTRICTIONS:
A stepped color scale (SCALE = 2 option) is not available when
writing to a black & white postscript file (i.e., when the
DEVICE color option is not enabled).
DEPENDENCIES: COLOR_KEY, STEP_CT, PRANK
EXAMPLES:
; Plot a GIF image with its own preset RGB
; table (perhaps from a digitized video image)
window,colors=256 ; set up a private color map
read_gif,file,im,r,g,b
tvlct,r,g,b
tvim,im,/c_map
;
;
; Plot an image with descreet greyscale values to a printer
; which has its own hard-wired color table.
im=randata(128,128,s=4)
immx=max(im) & immn=min(im)
!p.multi=[0,2,2]
tvim,im,/scale,colors=!p.color*indgen(4)/3.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(5)/4.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(8)/7.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(10)/9.,range=[immn,immx]
;
;
; Display a map of surface types (green=veg, blue=water, red=sand)
; Notice how RANGE is used to associate physical values with colors.
; (use im from the previous example)
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
tvlct,[0,0,0,255],[0,255,0,0],[0,0,255,0]
!p.multi=[0,2,2]
colors=[1,2,3] & labels=[' veg',' water',' sand']
range=[immn,immx,delim/3]
tvim,im,/scale
tvim,im,colors=colors,range=range,/scale
tvim,im,colors=colors,range=range,/scale,labels=labels,lch=2
!p.multi=0
range=[immn-.25*delim,immx+.25*delim,delim/2]
lbl=[' veg!c region 1',' water!c region 2',' sand!c region 3']
tvim,im,colors=colors,range=range,/scale,labels=lbl,lch=2,rmarg=2,pchar=1.2
;
;
; Display the image from previous example and overlay a contour plot
;
loadct,5
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
xrange=[-120,-100]
yrange=[20,50]
range=[immn,immx]
xx=findrng(xrange,128)
yy=findrng(yrange,128)
tvim,im,/scale,xrange=xrange,yrange=yrange,clevels=clevels,range=range
contour,im,xx,yy,levels=clevels,/overplot
; NOTE: You might prefer the results obtained from procedure CONFILL.
confill,im,xx,yy,/asp,levels=clevels
;
;
; Display a grey scale image and annotate certain points in color
;
loadct,0
dcolors
tvim,im,/scale,nbotclr=11
xx=interpolate([40,80],randomu(iseed,10))
yy=interpolate([40,80],randomu(iseed,10))
plots,xx,yy,psym=2,color=1+indgen(10)
;
;
; Display a grey scale image and show nodata values in red
;
loadct,0
im=randata(100,100,s=4.5)
im(randomu(iseed,50)*9999)=-999.
tvim,im,/scale,nodata=-999.,rgb_nodata=[255,0,0]
;
;
; Postscript output with a reversed color scale. Because the
; background color is always RGB=(255,255,255) you must set the
; default color, !p.color, to a dark color if you want good contrast
; between the axis labels and the white paper. According to
; Didier's reversed color table a color index of 255 should produce
; black, but for some reason !p.color=255 doesn't work right.
; I think IDL is iterpreting !p.color=255 in some special way.
; So instead use !p.color=254; this seems to work fine.
;
toggle,/color
loadct,28
!p.color=254 ; don't use 255, don't ask me why
tvim,dist(20),/scale
toggle
;
; display data defined on a regular LAT-LON grid onto a given map
; projection. USE MAP_SET and MAP_IMAGE to create the map projection
; and to warp the image. Then use BOXPOS to position the TVIM frame
; to correctly register the map and image
IMAGE = sin(!pi*findrng(0,24,200))#sin(!pi*findrng(0,12,200))
!p.multi=[0,1,2]
map_set,45,0,/ortho,/advance,pos=boxpos(/aspect)
newimage=map_image(image,/bilin,latmin=-90,latmax=90,lonmin=-180,lonmax=180)
tvim,newimage,title='Warped data',pos=boxpos(/get),/scale
map_set,45,0,/ortho,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
tvim,image,xrange=[-180,180],yrange=[-90,90],/scale, $
title='Unwarped data',xtitle='Longitude',ytitle='Latitude'
map_set,0,0,/cyl,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
; use MAP_SET2 to mask out land areas. Note that the example below is
; unusual. MAP_SET2 doesn't always produce such nicely filled land areas.
; Typically one must run MAP_SET2 with /SAVE
; to create a ascii file containing the continental boundary lat-lon
; coordinates. Then use an editor to group the continental coordinates
; line segments to form closed contours which POLYFILL can understand
; (the call to POLYFILL is enabled by setting con_color).
;
image=randata(256,256,s=2.5)
tvim,image
map_set2,-64,-64,/cont,limit=[-65.1,-64.5,-64,-62],/ortho,con_col=100,$
pos=boxpos(/get),/noerase,/grid
;
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS:
28jan93: switched from PUT_COLOR_SCALE to COLOR_KEY
11feb93: added INTERP keyword
11feb93: added C_MAP keyword
11feb93: added STITLE keyword
20apr93: added RMARG keyword, centered image in plot window
23apr93: call COLOR_KEY before TV. Now stepped color scales copy to PS file
10sep93: deal with perfectly flat images. No more math error when a=0
14sep93: added CLIP keyword
11feb94: added PCHARSIZE,LCHARSIZE,LABELS, and COLORS keywords
18feb94: added NBOTCLR keyword
16mar94: added INTERP=2 option and adjusted centering of pixels
08Jul94: added NODATA and RGB_NODATA keywords
04Aug94: added BARWIDTH keyword
04Aug94: defaulted PCHARSIZE and LCHARSIZE to !P.CHARSIZE if non-zero
02Mar95: added POSITION keyword
31Mar95: added NOAXIS keyword
24may95: initial sizing includes allowance for PCHARSIZE > 1
06sep95: color indecies used in plot now run from 1 to !d.ncolors-2
24jul96: do a REFORM(a) to allow tvim,a(1,*,*)
(See /home/drw/idl/bin/tvim.pro)
TVIM[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tvim
USEAGE: tvim,a
tvim,a,scale=scale,range=range,xrange=xrange,yrange=yrange, $
aspect=aspect,title=title,xtitle=xtitle,ytitle=ytitle, $
noaxis=noaxis,interp=interp,colors=colors,c_map=c_map, $
stitle=stitle,rmarg=rmarg,clip=clip,labels=labels, $
pcharsize=pcharsize,lcharsize=lcharsize,nbotclr=nbotclr, $
clevels=clevels,nodata=nodata,rgb_nodata=rgb_nodata, $
barwidth=barwidth,position=position,noframe=noframe,rct=rct
PURPOSE: Display an image with provisions for
1. numbered color scale
2. plot title
3. annotated x and y axis
4. simplified OPLOT capability
5. manual or automatic scaling with smooth or discreet colors
6. special treatment of "invalid data" pixels
7. display true color images
INPUT
a image quantity
if A is a two dimensional array it is assumed to be an
array of a physical quantity in the same units as specified
in RANGE.
if A is a three dimensional array it is assumed to be a
band-interleaved true color image in the form
(3,nx,ny) or (nx,ny,3) [either form will work], where
nx and ny are the number of pixels in the x and y
directions and the red, green and blue components are
specified by the third index. All keywords associated
with scaling the image to the color key (e.g., SCALE,
RANGE, CLEVELS, STITLE etc.) are disabled for true color
images.
Before display the image array is scaled to the 0-255
range using bytscl. It is then routed through the
color tables. The red color table array contains the
intensity translation table for the red image, and so
forth. Assuming that the color tables have been loaded
with the vectors R, G, and B, a pixel with a color
value of (r, g, b) is displayed with a color of (R[r],
G[g], B[b]). As with other devices, a color table
value of 255 represents maximum intensity, while 0
indicates an absence of the color. To pass the RGB
pixel values without change, load the red, green and
blue color tables with a ramp with a slope of 1.0:
TVLCT, INDGEN(256), INDGEN(256), INDGEN(256) or with
the LOADCT procedure: LOADCT, 0 ; Load standard
black/white table.
True color images can be written to postscript using
toggle,/color
tvim,a
toggle
NOTE: To write a gif image you'll have to use color_quan to
quantize the true color image into 256 colors. This
procedure produces a pretty lousy result:
v=color_quan(a,3,r,g,b,color=256)
tvlct,r,g,b
tvim,v
gif_write,'junk.gif'
NOTE: if you have a pc you can use a screen capture
to cut and paste the image into a document ("ALT
print-screen" copies the screen into the paste
buffer).
Optional keyword input:
title
plot title
xtitle
x axis title
ytitle
y axis title
stitle
color key title (drawn to the right of color scale)
rmarg
right margin expansion factor to provide more room for extra wide
color scale annotation (default=1)
xrange
array spanning entire x axis range. (default = [0,x_dimension-1])
yrange
array spanning entire y axis range. (default = [0,y_dimension-1])
NOTE:TVIM only uses min(XRANGE), max(XRANGE), min(YRANGE) and max(YRANGE).
scale
if set draw color scale. SCALE=2 causes steped color scale
range
two or three element vector indicating physical range over which
to map the color scale. The third element of RANGE, if specified,
sets the step interval of the displayed color scale. It has no
effect when SCALE is not set. E.g., RANGE=[0., 1., 0.1] will
cause the entire color scale to be mapped between the physical
values of zero and one; the step size of the displayed color
scale will be set to 0.1.
clip
specifies a set percentage of pixels which will be left outside
the color scale. Larger values of CLIP yield images with greater
contrast. For example if clip=2 then the color scale range will
be set to include 98% of the pixels and to exclude the brightest
1% and the dimmest 1% of the pixel brightness distribution.
Keyword RANGE overides the effect of CLIP.
If CLIP is a two element vector, the upper and lower percentile
range can be specified. For example CLIP=[0,95] will exclude the
top 5%.
An alternative is to set CLIP to a single negative integer. This
causes the grey scale range to be obtained from the max and min
value of the image array after it is filtered by a 2-D median
filter. The radius of the median filter is set to -clip. Median
filtering is effective in removing "salt and pepper" noise,
(isolated high or low values). For example, setting clip=-1
causes the code to check the 9 element superpixel centered at
each pixel for median values. A single extremely large or small
value does not affect the final value of the median at each pixel
point.
aspect
the x over y aspect ratio of the output image. If not set, aspect
is set to (size_x/size_y) of the input image.
position
specifies the lower left and upper right TVIM frame position in
normal coordinates. When set POSITION overides the setting of
ASPECT, and disables screen blanking for new plots.
noaxis
if set do not draw x and y numbered axis around image. Instead
just draw a box
noframe
if set no not draw anything around image, not even a box
interp
TVIM normally uses nearest neighbor sampling to resize the image
to fill the data window area. If INTERP is set the resizing
operation uses bilinear interpolation
If INTERP = 2 the interpolation range is adjusted so that there
is a half pixel border around the plot. This ensures that the
smoothed image properly represents the cell center values of the
pixels, but introduces an extrapolation on the outer edges. This
option has noticeable effects for small (<20) image arrays.
NOTE: When writing to a Postscript file the resizing operation is
accomplished by changing the pixel size. Thus the INTERP
parameter has no effect on Postscript output.
pcharsize
character size of numbers along x and y axis and the title
(default is !p.charsize if non-zero, 1 otherwise)
NOTE: The character size of the x and y-axis number scale
annotation may be independently controlled by the !x.charsize or
!y.charsize system variables. For example, the x and y axis
number scale characters may be made invisible by setting these
variables to a very small non-zero number before calling TVIM.
Remember to restore normal character sizes by setting !x.charsize
and !y.charsize to 1 or zero after the call to TVIM.
lcharsize
character size of color key number or labels (default is
!p.charsize if non-zero, 1 otherwise)
barwidth
width of color key which appears to right of image when SCALE is
set. (default=1)
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies. When the COLORS array is set TVIM
will map values of A into the color values specified in COLORS.
How physical values are assigned to color values depends on how
the RANGE parameter is set, as shown in this table:
RANGE color_value
----- -----------
1. not set COLORS(A)
2. [amin,amax] COLORS((A-amin)/dinc)
3. [amin,amax,inc] COLORS((A-amin)/inc)
where amin, amax and inc are user specified elements of RANGE
and dinc=(amax-amin)/n_elements(COLORS). In case 1, A is used
directly as a subscript into COLORS. When RANGE is not set
legend labels should be used to annotate the color values. In
case 2, A is scaled so that each color defined in COLORS
represents a proportionate fraction of the total dynamic range.
In case 3, amin and inc (and not amax) are used to control which
colors are associated with given physical values. See examples.
c_map
TVIM normally rescales the input image to span the entire color
table range. Setting C_MAP disables this automatic re-scaling.
This is useful when the image byte values correspond to a
particular color mapping that could be destroyed by the
rescaling process (E.G. a gif image).
NOTE: When the number of IDL color table entries is less than
256 some colors may be lost. Use a private color map to avoid
this. See examples.
nbotclr
number of reserved colors at the bottom of the color
table. Color values between 0 and nbotclr-1 will not
be used in the displayed image. This allows the
bottom of the table to be set to special colors which
will not be used in the displayed the image. This
keyword is disabled when either the COLORS or NODATA
options are used. (default=1)
NOTE: by default the color table indicies used within a TVIM
image is limited to the range 1 to !d.n_colors-2. In most
predefined color tables, color index 0 and !d.n_color-1
correspond to pure black and white, respectively. TVIM uses
these color indicies as background and foreground colors for
region blanking and axis annotation. Color tables which do not
define black and white in these index locatations are not good
choices for TVIM plots, unless the first and last color table
entries are redefined as black and white using TVLCT, e.g.,
tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
NOTE: the procedure DCOLORS can be used to load a set
of discreet colors in the bottom 11 color values
(0-10). The original color table is resampled to fit
between color value 11 and the !d.n_colors-1.
nodata
pixel values which are interpreted as invalid data. Pixels
containing this data value are colored with color RGB_NODATA.
rgb_nodata
an RGB value (a 3 component vector) used to color pixels filled
with invalid data. (default = [0,0,0])
NOTE: NODATA and RGB_NODATA override the effect of NBOTCLR
rct
if set, reverse direction of color table. This keyword can be
used on black & white printers to allow large field values to be
represented by dark colors. Note, this feature is implemented
by reversing the association between physical values and color.
Though it reverses the colors on the color key, it does not
affect the actual color table.
KEYWORD OUTPUT:
clevels
physical values at the color key tic marks. Use this to set
contour levels in a subsequent call to CONTOUR.
SIDE EFFECTS:
Setting SCALE=2 changes the color scale using the STEP_CT
procedure. The color scale may be returned to its original
state by the command, STEP_CT,/OFF
PROCEDURE:
TVIM first determines the size of the plot data window with a
dummy call to PLOT. When the output device is "X", CONGRID is
used to scale the image to the size of the available data
window. Otherwise, if the output device is Postscript,
scaleable pixels are used in the call to TV.
If the input image quantity is not of type byte, TVIM converts
them to byte by scaleing the input between 0 and !d.n_colors-1.
If the input is already a byte array and if either the number of
color table entries is 256 or if C_MAP is set, then no scaling
is done. This is to ensure consistency with specially defined
private color tables.
After the the image is drawn TVIM calls PLOT again to draw the x
and y axis and titles. Finally if scale is set, TVIM calls the
COLOR_KEY procedure to draw the color scale just to the right of
the data window.
RESTRICTIONS:
A stepped color scale (SCALE = 2 option) is not available when
writing to a black & white postscript file (i.e., when the
DEVICE color option is not enabled).
DEPENDENCIES: COLOR_KEY, STEP_CT, PRANK
EXAMPLES:
;; Plot a GIF image with its own preset RGB
;; table (perhaps from a digitized video image)
window,colors=256 ; set up a private color map
read_gif,'/home/paul/gif/el-nino.gif',im,r,g,b
tvlct,r,g,b
tvim,im,/c_map
;;
;;
;; Plot an image with descreet greyscale values to a printer
;; which has its own hard-wired color table. check documentation of gray.pro
im=randata(128,128,s=4)
immx=max(im) & immn=min(im)
!p.multi=[0,2,2]
loadct,5
tvim,im,/scale,range=[immn,immx],color=gray(4)
tvim,im,/scale,range=[immn,immx],color=gray(5)
tvim,im,/scale,range=[immn,immx],color=gray(8)
tvim,im,/scale,range=[immn,immx],color=gray(10)
;;
;;
;; Display a map of surface types (green=veg, blue=water, red=sand)
;; Notice how RANGE is used to associate physical values with colors.
;; (use im from the previous example)
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
tvlct,[0,0,0,255],[0,255,0,0],[0,0,255,0]
!p.multi=[0,2,2]
colors=[1,2,3] & labels=[' veg',' water',' sand']
range=[immn,immx,delim/3]
tvim,im,/scale
tvim,im,colors=colors,range=range,/scale
tvim,im,colors=colors,range=range,/scale,labels=labels,lch=2
!p.multi=0
range=[immn-.25*delim,immx+.25*delim,delim/2]
lbl=[' veg!c region 1',' water!c region 2',' sand!c region 3']
tvim,im,colors=colors,range=range,/scale,labels=lbl,lch=2,rmarg=2,pchar=1.2
;;
;; Display the image from previous example and overlay a contour plot
;;
!p.multi=0
loadct,5
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
xrange=[-120,-100]
yrange=[20,50]
range=[immn,immx]
xx=findrng(xrange,128)
yy=findrng(yrange,128)
tvim,im,/scale,xrange=xrange,yrange=yrange,clevels=clevels,range=range
contour,im,xx,yy,levels=clevels,/overplot
;; NOTE: You might prefer the results obtained from procedure CONFILL.
confill,im,xx,yy,/asp,levels=clevels
;;
;;
;; Display a grey scale image and annotate certain points in color
;;
loadct,0
dcolors
tvim,im,/scale,nbotclr=11 ; reserve some colors at bottom
xx=interpolate([40,80],randomu(iseed,10))
yy=interpolate([40,80],randomu(iseed,10))
plots,xx,yy,psym=2,color=1+indgen(10)
;;
;; inset an image onto a line plot
;;
!p.multi=0
loadct,0
xy=randata(100,100,s=3)
plot,xy[*,40]
tvim,xy,pos=boxpos(/cur),title='transect',pcharsize=.7
oplot,[0,99],[40,40]
;;
;;
;; Display a grey scale image and show nodata values in red
;;
loadct,0
im=randata(100,100,s=4.5)
im(randomu(iseed,50)*9999)=-999.
tvim,im,/scale,nodata=-999.,rgb_nodata=[255,0,0]
;;
;;
;; Postscript output with a reversed color scale. Because the
;; background color is always RGB=(255,255,255) you must set the
;; default color, !p.color, to a dark color if you want good contrast
;; between the axis labels and the white paper. According to
;; Didier's reversed color table a color index of 255 should produce
;; black, but for some reason !p.color=255 doesn't work right.
;; I think IDL is iterpreting !p.color=255 in some special way.
;; So instead use !p.color=254; this seems to work fine.
;;
toggle,/color
loadct,28
!p.color=254 ; don't use 255, don't ask me why
tvim,dist(20),/scale
toggle
;;
;; display data defined on a regular LAT-LON grid onto a given map
;; projection. USE MAP_SET and MAP_IMAGE to create the map projection
;; and to warp the image. Then use BOXPOS to position the TVIM frame
;; to correctly register the map and image
w8x11
IMAGE = sin(!pi*findrng(0,24,200))#sin(!pi*findrng(0,12,200))
!p.multi=[0,1,2]
map_set,45,0,/ortho,/advance,pos=boxpos(/aspect)
newimage=map_image(image,/bilin,latmin=-90,latmax=90,lonmin=-180,lonmax=180)
tvim,newimage,title='Warped data',pos=boxpos(/get),/scale
map_set,45,0,/ortho,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
tvim,image,xrange=[-180,180],yrange=[-90,90],/scale, $
title='Unwarped data',xtitle='Longitude',ytitle='Latitude'
map_set,0,0,/cyl,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
;; use MAP_SET2 to mask out land areas. Note that the example below is
;; unusual. MAP_SET2 doesn't always produce such nicely filled land areas.
;; Typically one must run MAP_SET2 with /SAVE
;; to create a ascii file containing the continental boundary lat-lon
;; coordinates. Then use an editor to group the continental coordinates
;; line segments to form closed contours which POLYFILL can understand
;; (the call to POLYFILL is enabled by setting con_color).
;;
image=randata(256,256,s=2.5)
tvim,image,yrange=[-65.1,-64],xrange=[-64.5,-62]
map_set5,-64,-64,/cont,limit=[-65.1,-64.5,-64,-62],/pos,/noerase
map_set,-64,-64,/cont,limit=[-65.1,-64.5,-64,-62],pos=bospos(/get),/noerase
;; display a true color image
a=fltarr(100,100,3)
g=bytscl(replicate(1,100)#(findgen(100)>30))
a(*,*,0)=rotate(g,1)
a(*,*,1)=g
a(*,*,2)=rotate(g,3)
!p.multi=[0,2,2]
loadct,0
tvim,a,xrange=[100,300],yrange=[0,10],title='true color image'
tvim,a(*,*,0),range=[0,255],title='red component'
tvim,a(*,*,1),range=[0,255],title='green component'
tvim,a(*,*,2),range=[0,255],title='blue component'
;; other interleaving possibility
a=fltarr(3,100,100)
g=bytscl(replicate(1,100)#(findgen(100)>30))
a(0,*,*)=rotate(g,1)
a(1,*,*)=g
a(2,*,*)=rotate(g,3)
!p.multi=[0,2,2]
loadct,0
tvim,a,xrange=[100,300],yrange=[0,10],title='true color image'
tvim,a(0,*,*),range=[0,255],title='red component'
tvim,a(1,*,*),range=[0,255],title='green component'
tvim,a(2,*,*),range=[0,255],title='blue component'
;; display a sparse data field superposed on a background topography.
;; topography shown with a gray scale, data filled areas shown with
;; color table 5
minval=.1 ; minimum physical value of interest
nbotclr=30 ; number of colors assigned to gray scale
maxgray=240 ; max gray scale intensity (240 out of 255)
topo=randata(200,200,s=4) ; background topography variable (just for looks)
data=randata(200,200,s=2) ; data variable
loadct,5 ; color table 5
topo=topo-max(topo)
rngdata=max(data)-minval
rngtopo=-min(topo)
topo=nbotclr/(!d.n_colors<256.-nbotclr)*rngdata*topo/rngtopo
topo=topo+minval
ii=where(data lt minval)
data[ii]=topo[ii]
r=findrng(0,maxgray,nbotclr) & g=r & b=r
tvlct,r,g,b,0
tvim,data,rmarg=1
color_key,range=data>minval,nbotclr=nbotclr
;;
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS:
28jan93: switched from PUT_COLOR_SCALE to COLOR_KEY
11feb93: added INTERP keyword
11feb93: added C_MAP keyword
11feb93: added STITLE keyword
20apr93: added RMARG keyword, centered image in plot window
23apr93: call COLOR_KEY before TV. Now stepped color scales copy to PS file
10sep93: deal with perfectly flat images. No more math error when a=0
14sep93: added CLIP keyword
11feb94: added PCHARSIZE,LCHARSIZE,LABELS, and COLORS keywords
18feb94: added NBOTCLR keyword
16mar94: added INTERP=2 option and adjusted centering of pixels
08Jul94: added NODATA and RGB_NODATA keywords
04Aug94: added BARWIDTH keyword
04Aug94: defaulted PCHARSIZE and LCHARSIZE to !P.CHARSIZE if non-zero
02Mar95: added POSITION keyword
31Mar95: added NOAXIS keyword
24may95: initial sizing includes allowance for PCHARSIZE > 1
06sep95: color indecies used in plot now run from 1 to !d.ncolors-2
24jul96: do a REFORM(a) to allow tvim,a(1,*,*) to work with no complaints
01sep96: added the RCT keyword
17may00; treat true color images
01dec00; when position keyword is set, add to current page
(See /home/drw/idl/esrg/tvim.pro)
TVIM[3]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: tvim
USEAGE: tvim,a
tvim,a,scale=scale,range=range,xrange=xrange,yrange=yrange,$
aspect=aspect,title=title,xtitle=xtitle,ytitle=ytitle,$
noaxis=noaxis,interp=interp,colors=colors,c_map=c_map,$
stitle=stitle,rmarg=rmarg,clip=clip,labels=labels,$
pcharsize=pcharsize,lcharsize=lcharsize,nbotclr=nbotclr,&
clevels=clevels,nodata=nodata,rgb_nodata=rgb_nodata,$
barwidth=barwidth,position=position,noframe=noframe,rct=rct
PURPOSE: Display an image with provisions for
1. numbered color scale
2. plot title
3. annotated x and y axis
4. simplified OPLOT capability
5. manual or automatic scaling with smooth or discreet colors
6 special treatment of "invalid data" pixels
INPUT
a image quantity
Optional keyword input:
title
plot title
xtitle
x axis title
ytitle
y axis title
stitle
color key title (drawn to the right of color scale)
rmarg
right margin expansion factor to provide more room for extra wide
color scale annotation (default=1)
xrange
array spanning entire x axis range. (default = [0,x_dimension-1])
yrange
array spanning entire y axis range. (default = [0,y_dimension-1])
NOTE:TVIM only uses min(XRANGE), max(XRANGE), min(YRANGE) and max(YRANGE).
scale
if set draw color scale. SCALE=2 causes steped color scale
range
two or three element vector indicating physical range over which
to map the color scale. The third element of RANGE, if specified,
sets the step interval of the displayed color scale. It has no
effect when SCALE is not set. E.g., RANGE=[0., 1., 0.1] will
cause the entire color scale to be mapped between the physical
values of zero and one; the step size of the displayed color
scale will be set to 0.1.
clip
specifies a set percentage of pixels which will be left outside
the color scale. Larger values of CLIP yield images with greater
contrast. For example if clip=2 then the color scale range will
be set to include 98% of the pixels and to exclude the brightest
1% and the dimmest 1% of the pixel brightness distribution.
Keyword RANGE overides the effect of CLIP.
If CLIP is a two element vector, the upper and lower percentile
range can be specified. For example CLIP=[0,95] will exclude the
top 5%.
An alternative is to set CLIP to a single negative integer. This
causes the grey scale range to be obtained from the max and min
value of the image array after it is filtered by a 2-D median
filter. The radius of the median filter is set to -clip. Median
filtering is effective in removing "salt and pepper" noise,
(isolated high or low values). For example, setting clip=-1
causes the code to check the 9 element superpixel centered at
each pixel for median values. A single extremely large or small
value does not affect the final value of the median at each pixel
point.
aspect
the x over y aspect ratio of the output image. If not set, aspect
is set to (size_x/size_y) of the input image.
position
specifies the lower left and upper right TVIM frame position in
normal coordinates. When set POSITION overides the setting of
ASPECT.
noaxis
if set do not draw x and y numbered axis around image. Instead
just draw a box
noframe
if set no not draw anything around image, not even a box
interp
TVIM normally uses nearest neighbor sampling to resize the image
to fill the data window area. If INTERP is set the resizing
operation uses bilinear interpolation
If INTERP = 2 the interpolation range is adjusted so that there
is a half pixel border around the plot. This ensures that the
smoothed image properly represents the cell center values of the
pixels, but introduces an extrapolation on the outer edges. This
option has noticeable effects for small (<20) image arrays.
NOTE: When writing to a Postscript file the resizing operation is
accomplished by changing the pixel size. Thus the INTERP
parameter has no effect on Postscript output.
pcharsize
character size of numbers along x and y axis and the title
(default is !p.charsize if non-zero, 1 otherwise)
NOTE: The character size of the x and y-axis number scale
annotation may be independently controlled by the !x.charsize or
!y.charsize system variables. For example, the x and y axis
number scale characters may be made invisible by setting these
variables to a very small non-zero number before calling TVIM.
Remember to restore normal character sizes by setting !x.charsize
and !y.charsize to 1 or zero after the call to TVIM.
lcharsize
character size of color key number or labels (default is
!p.charsize if non-zero, 1 otherwise)
barwidth
width of color key which appears to right of image when SCALE is
set. (default=1)
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies. When the COLORS array is set TVIM
will map values of A into the color values specified in COLORS.
How physical values are assigned to color values depends on how
the RANGE parameter is set, as shown in this table:
RANGE color_value
----- -----------
1. not set COLORS(A)
2. [amin,amax] COLORS((A-amin)/dinc)
3. [amin,amax,inc] COLORS((A-amin)/inc)
where amin, amax and inc are user specified elements of RANGE
and dinc=(amax-amin)/n_elements(COLORS). In case 1, A is used
directly as a subscript into COLORS. When RANGE is not set
legend labels should be used to annotate the color values. In
case 2, A is scaled so that each color defined in COLORS
represents a proportionate fraction of the total dynamic range.
In case 3, amin and inc (and not amax) are used to control which
colors are associated with given physical values. See examples.
c_map
TVIM normally rescales the input image to span the entire color
table range. Setting C_MAP disables this automatic re-scaling.
This is useful when the image byte values correspond to a
particular color mapping that could be destroyed by the
rescaling process (E.G. a gif image).
NOTE: When the number of IDL color table entries is less than
256 some colors may be lost. Use a private color map to avoid
this. See examples.
nbotclr
number of reserved colors at the bottom of the color
table. Color values between 0 and nbotclr-1 will not
be used in the displayed image. This allows the
bottom of the table to be set to special colors which
will not be used in the displayed the image. This
keyword is disabled when either the COLORS or NODATA
options are used. (default=1)
NOTE: by default the color table indicies used within a TVIM
image is limited to the range 1 to !d.n_colors-2. In most
predefined color tables, color index 0 and !d.n_color-1
correspond to pure black and white, respectively. TVIM uses
these color indicies as background and foreground colors for
region blanking and axis annotation. Color tables which do not
define black and white in these index locatations are not good
choices for TVIM plots, unless the first and last color table
entries are redefined as black and white using TVLCT, e.g.,
tvlct,0,0,0,0 & tvlct,255,255,255,!d.n_colors-1
NOTE: the procedure DCOLORS can be used to load a set
of discreet colors in the bottom 11 color values
(0-10). The original color table is resampled to fit
between color value 11 and the !d.n_colors-1.
nodata
pixel values which are interpreted as invalid data. Pixels
containing this data value are colored with color RGB_NODATA.
rgb_nodata
an RGB value (a 3 component vector) used to color pixels filled
with invalid data. (default = [0,0,0])
NOTE: NODATA and RGB_NODATA override the effect of NBOTCLR
rct
if set, reverse direction of color table. This keyword can be
used on black & white printers to allow large field values to be
represented by dark colors.
KEYWORD OUTPUT:
clevels
physical values at the color key tic marks. Use this to set
contour levels in a subsequent call to CONTOUR.
SIDE EFFECTS:
Setting SCALE=2 changes the color scale using the STEP_CT
procedure. The color scale may be returned to its original
state by the command, STEP_CT,/OFF
PROCEDURE:
TVIM first determines the size of the plot data window with a
dummy call to PLOT. When the output device is "X", CONGRID is
used to scale the image to the size of the available data
window. Otherwise, if the output device is Postscript,
scaleable pixels are used in the call to TV.
If the input image quantity is not of type byte, TVIM converts
them to byte by scaleing the input between 0 and !d.n_colors-1.
If the input is already a byte array and if either the number of
color table entries is 256 or if C_MAP is set, then no scaling
is done. This is to ensure consistency with specially defined
private color tables.
After the the image is drawn TVIM calls PLOT again to draw the x
and y axis and titles. Finally if scale is set, TVIM calls the
COLOR_KEY procedure to draw the color scale just to the right of
the data window.
RESTRICTIONS:
A stepped color scale (SCALE = 2 option) is not available when
writing to a black & white postscript file (i.e., when the
DEVICE color option is not enabled).
DEPENDENCIES: COLOR_KEY, STEP_CT, PRANK
EXAMPLES:
; Plot a GIF image with its own preset RGB
; table (perhaps from a digitized video image)
window,colors=256 ; set up a private color map
read_gif,file,im,r,g,b
tvlct,r,g,b
tvim,im,/c_map
;
;
; Plot an image with descreet greyscale values to a printer
; which has its own hard-wired color table.
im=randata(128,128,s=4)
immx=max(im) & immn=min(im)
!p.multi=[0,2,2]
tvim,im,/scale,colors=!p.color*indgen(4)/3.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(5)/4.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(8)/7.,range=[immn,immx]
tvim,im,/scale,colors=!p.color*indgen(10)/9.,range=[immn,immx]
;
;
; Display a map of surface types (green=veg, blue=water, red=sand)
; Notice how RANGE is used to associate physical values with colors.
; (use im from the previous example)
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
tvlct,[0,0,0,255],[0,255,0,0],[0,0,255,0]
!p.multi=[0,2,2]
colors=[1,2,3] & labels=[' veg',' water',' sand']
range=[immn,immx,delim/3]
tvim,im,/scale
tvim,im,colors=colors,range=range,/scale
tvim,im,colors=colors,range=range,/scale,labels=labels,lch=2
!p.multi=0
range=[immn-.25*delim,immx+.25*delim,delim/2]
lbl=[' veg!c region 1',' water!c region 2',' sand!c region 3']
tvim,im,colors=colors,range=range,/scale,labels=lbl,lch=2,rmarg=2,pchar=1.2
;
;
; Display the image from previous example and overlay a contour plot
;
loadct,5
im=randata(128,128,s=4)
immx=max(im) & immn=min(im) & delim=immx-immn
xrange=[-120,-100]
yrange=[20,50]
range=[immn,immx]
xx=findrng(xrange,128)
yy=findrng(yrange,128)
tvim,im,/scale,xrange=xrange,yrange=yrange,clevels=clevels,range=range
contour,im,xx,yy,levels=clevels,/overplot
; NOTE: You might prefer the results obtained from procedure CONFILL.
confill,im,xx,yy,/asp,levels=clevels
;
;
; Display a grey scale image and annotate certain points in color
;
loadct,0
dcolors
tvim,im,/scale,nbotclr=11
xx=interpolate([40,80],randomu(iseed,10))
yy=interpolate([40,80],randomu(iseed,10))
plots,xx,yy,psym=2,color=1+indgen(10)
;
;
; Display a grey scale image and show nodata values in red
;
loadct,0
im=randata(100,100,s=4.5)
im(randomu(iseed,50)*9999)=-999.
tvim,im,/scale,nodata=-999.,rgb_nodata=[255,0,0]
;
;
; Postscript output with a reversed color scale. Because the
; background color is always RGB=(255,255,255) you must set the
; default color, !p.color, to a dark color if you want good contrast
; between the axis labels and the white paper. According to
; Didier's reversed color table a color index of 255 should produce
; black, but for some reason !p.color=255 doesn't work right.
; I think IDL is iterpreting !p.color=255 in some special way.
; So instead use !p.color=254; this seems to work fine.
;
toggle,/color
loadct,28
!p.color=254 ; don't use 255, don't ask me why
tvim,dist(20),/scale
toggle
;
; display data defined on a regular LAT-LON grid onto a given map
; projection. USE MAP_SET and MAP_IMAGE to create the map projection
; and to warp the image. Then use BOXPOS to position the TVIM frame
; to correctly register the map and image
IMAGE = sin(!pi*findrng(0,24,200))#sin(!pi*findrng(0,12,200))
!p.multi=[0,1,2]
map_set,45,0,/ortho,/advance,pos=boxpos(/aspect)
newimage=map_image(image,/bilin,latmin=-90,latmax=90,lonmin=-180,lonmax=180)
tvim,newimage,title='Warped data',pos=boxpos(/get),/scale
map_set,45,0,/ortho,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
tvim,image,xrange=[-180,180],yrange=[-90,90],/scale, $
title='Unwarped data',xtitle='Longitude',ytitle='Latitude'
map_set,0,0,/cyl,pos=boxpos(/get),/grid,/cont,/noerase ; draw map
; use MAP_SET2 to mask out land areas. Note that the example below is
; unusual. MAP_SET2 doesn't always produce such nicely filled land areas.
; Typically one must run MAP_SET2 with /SAVE
; to create a ascii file containing the continental boundary lat-lon
; coordinates. Then use an editor to group the continental coordinates
; line segments to form closed contours which POLYFILL can understand
; (the call to POLYFILL is enabled by setting con_color).
;
image=randata(256,256,s=2.5)
tvim,image
map_set2,-64,-64,/cont,limit=[-65.1,-64.5,-64,-62],/ortho,con_col=100,$
pos=boxpos(/get),/noerase,/grid
;
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
REVISIONS:
28jan93: switched from PUT_COLOR_SCALE to COLOR_KEY
11feb93: added INTERP keyword
11feb93: added C_MAP keyword
11feb93: added STITLE keyword
20apr93: added RMARG keyword, centered image in plot window
23apr93: call COLOR_KEY before TV. Now stepped color scales copy to PS file
10sep93: deal with perfectly flat images. No more math error when a=0
14sep93: added CLIP keyword
11feb94: added PCHARSIZE,LCHARSIZE,LABELS, and COLORS keywords
18feb94: added NBOTCLR keyword
16mar94: added INTERP=2 option and adjusted centering of pixels
08Jul94: added NODATA and RGB_NODATA keywords
04Aug94: added BARWIDTH keyword
04Aug94: defaulted PCHARSIZE and LCHARSIZE to !P.CHARSIZE if non-zero
02Mar95: added POSITION keyword
31Mar95: added NOAXIS keyword
24may95: initial sizing includes allowance for PCHARSIZE > 1
06sep95: color indecies used in plot now run from 1 to !d.ncolors-2
24jul96: do a REFORM(a) to allow tvim,a(1,*,*)
(See /home/drw/idl/old.esrg/tvim.pro)
TVPRINT2
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
TVPRINT2
Purpose :
Sends the contents of a window to a PostScript printer under 24-bit
display, using TVRD_24().
Explanation :
Reads the contents of a graphics window and creates and prints a
PostScript file. The routine TVREAD is called to read the window. It
is (optionally) converted to a grey scale, and EXPTV is used to write
this to a PostScript file.
Use :
TVPRINT [, FILENAME ]
Inputs :
None required.
Opt. Inputs :
FILENAME = Name of the PostScript file that will be created and
printed (and saved). If not passed, then TEMPORARY.ps is
used (but not saved).
Outputs :
None.
Opt. Outputs:
None.
Keywords :
WINDOW = Which window to read from. If passed, then overrides the
TVSELECT routine.
DISABLE = If set, then the current graphics device/window is read.
Otherwise, TVSELECT is called to select the image display
device/window. Ignored if WINDOW keyword is passed.
PORTRAIT = If set, then plot done in portrait mode, using all of the
paper.
LANDSCAPE = If passed, then plot done in landscape mode, using all of
the paper. This is the default mode.
TEX = If set, then plot done in encapsulated landscape mode,
to be compatible with TeX. If this keyword is passed, then
an explicit filename must be passed. The file is not
printed.
COLOR = If set, then a color PostScript file is created. The
default is to convert to a greyscale image.
REVERSE = If set, then plot is done in inverse video. In other
words, white areas on the screen will appear dark, and visa
versa. Ignored if COLOR is set.
NOBOX = If set, then a box is not drawn around the printed image of
the X-window. The default is to draw a box.
TITLE = An optional text title to display with the image.
BELOW = If set, then the title is displayed below the image.
Normally, the title is displayed above the image.
LEFT = If set, then the title is displayed to the left of the
image. Overrides BELOW keyword.
RIGHT = If set, then the title is displayed to the right of the
image. Overrides BELOW and LEFT keywords.
CHARSIZE = Character size to use in displaying titles. Normally 1.
RELATIVE = Size of area to be used for displaying the image, relative
to the total size available. Must be between 0 and 1.
Default is 1. Can be used to allow enough space for the
optional title.
NOPRINT = If set, then the PostScript file is created, but not
printed. This requires that an explicit filename be
passed.
QUEUE = Print queue to send file to.
PCL = If set, then an HP LaserJet PCL file will be created
instead of a PostScript file. In this case, the default
file extension will be ".pcl" instead of ".ps". The TEX
and COLOR keywords will be ignored.
Calls :
EXPTV, FORM_FILENAME, PCL, PCLCLOSE, PCLPLOT, PS, PSCLOSE, PSPLOT,
SETIMAGE, TVREAD
Common :
None.
Restrictions:
Device must be capable of the TVRD function. Window must be completely
visible, with no portion off the end of the screen.
NOTE: This routine does not do a good job on line graphics. It works
best with images.
In general, the SERTS image display routines use several non-standard
system variables. These system variables are defined in the procedure
IMAGELIB. It is suggested that the command IMAGELIB be placed in the
user's IDL_STARTUP file.
Some routines also require the SERTS graphics devices software,
generally found in a parallel directory at the site where this software
was obtained. Those routines have their own special system variables.
Side effects:
A temporary file, "TEMPORARY.ps" will be created and deleted, unless an
explicit filename is passed.
The SETIMAGE routine is called to reset to the default. Any SETIMAGE
setting is lost.
Category :
Utilities, Image_display.
Prev. Hist. :
William Thompson, May 1992, from XPRINT.
William Thompson, June 1992, added color support.
William Thompson, December 1992, modified to use a better and faster
translation from colors to grey-scale, as suggested by Alan
Youngblood.
Written :
William Thompson, GSFC, May 1992
Modified :
Version 1, William Thompson, GSFC, 11 May 1993
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 24 August 1993
Added PCL keyword.
Version 3, William Thompson, GSFC, 30 June 1995
Added keywords TITLE, BELOW, LEFT, RIGHT, CHARSIZE
Utilize GREYSCALE and REVERSE keywords of TVREAD.
Version :
Version 3, 30 June 1995
(See /home/drw/idl/gen/tvprint2.pro)
TVRD_24
[Previous Routine]
[Next Routine]
[List of Routines]
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.
(See /home/drw/idl/aux/tvrd_24.pro)
TVREAD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TVREAD
PURPOSE:
To get accurate screen dumps with the IDL command TVRD on 24-bit
PC and Macintosh computers, you have to be sure to set color
decomposition on. This program adds that capability automatically.
In addition, the program will optionally write BMP, GIF, JPEG,
PICT, PNG, and TIFF color image files of the screen dump.
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:
image = TVREAD(xstart, ystart, ncols, nrows)
The returned image will be a 2D image on 8-bit systems and
a 24-bit pixel interleaved true-color image on 24-bit systems.
A -1 will be returned if a file output keyword is used (e.g., JPEG, TIFF, etc.)=tvr
OPTIONAL INPUTS:
XSTART -- The starting column index. By default, 0.
YSTART -- The starting row index. By default, 0.
NCOLS -- The number of columns to read. By default, !D.X_Size - XSTART
NROWS -- The number of rows to read. By default, !D.Y_Size - YSTART.
KEYWORD PARAMETERS:
BMP -- Set this keyword to write the screen dump as a color BMP file.
COLORS -- If a 24-bit image has to be quantized, this will set the number
of colors in the output image. Set to 256 by default. Applies to BMP,
GIF, PICT, and PNG formats written from 24-bit displays.(See the
COLOR_QUAN documentation for details.)
CUBE -- If this keyword is set to a value between 2 and 6 the color
quantization will use a cubic method of quantization. Applies to BMP,
GIF, PICT, and PNG formats written from 24-bit displays.(See the
COLOR_QUAN documentation for details.)
DITHER -- If this keyword is set the quantized image will be dithered.
Applies to BMP, GIF, PICT, and PNG formats written from 24-bit displays.
(See the COLOR_QUAN documentation for details.)
FILENAME -- The base name of the output file. (No file extensions;
they will be added automatically.) This name may be changed by the user.
image = TVREAD(Filename='myfile', /JPEG)
GIF -- Set this keyword to write the screen dump as a color GIF file.
JPEG -- Set this keyword to write the screen dump as a color JPEG file.
PICT -- Set this keyword to write the screen dump as a color PICT file.
PNG -- Set this keyword to write the screen dump as a color PNG file.
TIFF -- Set this keyword to write the screen dump as a color TIFF file.
QUALITY -- This keyword sets the amount of compression for JPEG images.
It should be set to a value between 0 and 100. It is set to 75 by default.
(See the WRITE_JPEG documentation for details.)
WID -- The index number of the window to read from. The current graphics window
(!D.Window) is selected by default. An error is issued if no windows are
currently open on a device that supports windows.
_EXTRA -- Any keywords that are appropriate for the WRITE_*** routines are
also accepted via keyword inheritance.
COMMON BLOCKS:
None
RESTRICTIONS: Requires ERROR_MESSAGE from the Coyote Library:
http://www.dfanning.com/programs/error_message.pro
Requires IDL 5.2 and higher.
MODIFICATION HISTORY:
Written by David Fanning, 9 AUG 2000.
Added changes to make the program more device independent. 16 SEP 2000. DWF.
(See /home/drw/idl/aux/tvread.pro)
TVSCALE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TVSCALE
PURPOSE:
This purpose of TVSCALE is to enable the TVSCL 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, TVSCALE adds features
that TVSCL lacks. For example, images can be positioned in windows
using the POSITION keyword like other IDL graphics commands.
TVSCALE also supports the !P.MULTI system variable, unlike the
TVSCL command. TVSCALE 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. TVSCALE 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 TVSCALE. In addition, you can
use the TOP and BOTTOM keywords to define a particular set of
number to scale the data to. The algorithm used is this:
TV. BytScl(image, TOP=top-bottom) + bottom
Note that if you scale the image between 100 and 200, that
there are 101 possible pixel values. So the proper way to
load colors would be like this:
LoadCT, NColors=101, Bottom=100
TVSCALE, image, Top=200, Bottom=100
Alternatively, you could use the NCOLORS keyword:
LoadCT, NColors=100, Bottom=100
TVSCALE, image, NColors=100, Bottom=100
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:
TVSCALE, image
INPUTS:
image: A 2D or 3D image array. It does not have to be byte data.
x : The X position of the lower-left corner of the image.
This parameter is only recognized if the TVSCL keyword is set.
y : The Y position of the lower-left corner of the image.
This parameter is only recognized if the TVSCL 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 TVSCALE is
used to place the *first* plot.
BOTTOM: The image is scaled so that all displayed pixels have values
greater than or equal to BOTTOM and less than or equal to TOP.
The value of BOTTOM is 0 by default.
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 keyword is used.
MAXVALUE: The data is linearly scaled between the MIN and MAX values,
if they are provided. MAX is set to MAX(image) by default.
MINVALUE: The data is linearly scaled between the MIN and MAX values,
if they are provided. MIN is set to MIN(image) by default.
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.
NCOLORS: If this keyword is supplied, the TOP keyword is ignored and
the TOP keyword is set equal to BOTTOM + NCOLORS - 1. This
keyword is provided to make TVSCALE easier to use with the
color-loading programs such as LOADCT:
LoadCT, 5, NColors=100, Bottom=100
TVScale, image, NColors=100, Bottom=100
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.
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 TVSCL 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]
TVScale, 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.
TOP: The image is scaled so that all displayed pixels have values
greater than or equal to BOTTOM and less than or equal to TOP.
The value of TOP is !D.Table_Size by default.
TVSCL: Setting this keyword makes the TVIMAGE command work much
like the TVSCL 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 as an output parameter.
If the image is 2D then color decomposition is turned OFF
for the current graphics device (i.e., DEVICE, DECOMPOSED=0).
If outputting to the PRINTER device, the aspect ratio of the image
is always maintained and the POSITION coordinates are ignored.
The image always printed in portrait mode.
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
thisPosition = [0.1, 0.1, 0.9, 0.9]
TVSCALE, image, POSITION=thisPosition, /KEEP_ASPECT_RATIO
CONTOUR, image, POSITION=thisPosition, /NOERASE, XSTYLE=1, $
YSTYLE=1, XRANGE=[0,360], YRANGE=[0,360], NLEVELS=10
MODIFICATION HISTORY:
Written by: David Fanning, 27 May 1999 from TVIMAGE code.
Added MIN, MAX, and NCOLORS keywords 28 May 1999. DWF.
Added the OVERPLOT keyword to allow plotting on POSITION coordinates
estabished by the preceding graphics command. 11 Oct 99. DWF.
Added NOINTERPOLATION keyword so that nearest neighbor interpolation
is performed rather than bilinear. 3 Dec 99. DWF
Brought the TVSCALE code up to date with TVIMAGE code. 3 April 2000. DWF.
Brought the TVSCALE code up to date with TVIMAGE code. 6 May 2000. DWF.
Change MIN and MAX keywords to MINVALUE and MAXVALUE to prevent
ambiguous keyword errors. 27 July 2000. DWF.
Brought up to date with changes in TVImage. 23 Sept 2000. DWF.
Fixed a small problem with handling images that are slices from 3D image cubes. 19 Oct 2000. DWF
(See /home/drw/idl/aux/tvscale.pro)
TVSTACK
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TVSTACK
PURPOSE:
This procedure displays a multidimensional array (e.g. 3D) as a stack of
images lain side by side, and by default scaled between the minimum and
maximum values in the array. This is a method of visualizing 3D data
sets, for example reconstructions of tracer uptake in nuclear medicine.
For an image measuring NX by NY by NZ, the effect is somewhat the same
as typing
for z=0,nz-1 do tvscl, image(*,*,z), z
except that they aren't necessarily scaled to the frame maxima, and
some options are available through the keywords.
CATEGORY:
IMAGE DISPLAY
CALLING SEQUENCE:
TVSTACK, IMAGES
INPUTS:
IMAGES: The multidimensional array to be displayed. It may have any
number of dimensions but is displayed as if it is 3D.
KEYWORD PARAMETERS:
W_BORDER: Width of the border to be drawn around each frame displayed.
If framing is performed, each NX by NY image takes up
(NX+2*W_BORDER) pixels in the X direction and (NY+2*W_BORDER)
pixels in the Y direction. Default = NO BORDER.
C_BORDER: Color of the border, if the W_BORDER keyword is set. Default=
!d.n_colors/3.
TVSCL: If this keyword is set, each 2D image is scaled to its own max
and min. By default, the max and min of the multidimensional
array are used.
POSITION: The screen position used by the first image frame in the
sequence. Thus, images are positioned as if the command
for z=0,nz-1 do tvscl, image(*,*,z), position+z
were used. Default = 0 (start in upper left corner of th
display window.)
REVERSE_DIM: which dimension of the image is to be reversed (using the
REVERSE function from the USERLIB); 1 means X, 2 means Y.
Default = NO REVERSAL.
ROTATE_PAR: what parameter to use to rotate the image frames, with the
IDL ROTATE function (q.v.) in which 0=no rotation, 1=90 degrees
CCW without transposing, and so on. Defaul=NO ROTATION.
SKIP: Use this keyword if you desire to display only some of the images
for example every other one, which would be represented by
SKIP=2. Images are positioned as if the command
for z=0,nz-1,SKIP do tvscl, image(*,*,z), z/SKIP
were used. Default = 1, that is, do not skip. If you specify
/SKIP you end up not skipping (!!!) because in this case you
specify steps of 1.
OUTPUTS:
None; the procedure writes into the current display window.
EXAMPLE: A 3D gaussian can be displayed as follows:
n = 50
xysq = shift(dist(n)^2,n/2,n/2) ; x^2 + y^2
rsq = fltarr(n,n,n) ; array to hold r^2
for z=0,n-1 do rsq(0,0,z) = (z-n/2.0)^2 + xysq
; r^2 = x^2 + y^2 + z^2
fwhm=10.0 & sig=fwhm/(2*sqrt(2*alog(2))) & gauss_3D=exp(-rsq/(2*sig^2))
; 3D gaussian of 10 channels FWHM
tvstack, gauss_3D, /w_b ; display it
MODIFICATION HISTORY:
Written by: James Hamill
Siemens Medical Systems
2501 N. Barrington Rd.
Hoffman Estates, IL 60195-7372
(708)304-7760
hamill@sgi.siemens.com
April, 1992
(See /home/drw/idl/old.esrg/tvstack.pro)
TV_24
[Previous Routine]
[Next Routine]
[List of Routines]
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.
(See /home/drw/idl/aux/tv_24.pro)
TV_POLAR[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE:
tv_polar
USEAGE:
tv_polar,psi,phi,theta
tv_polar,psi,phi,theta,style=style,grdres=grdres,title=title,rot=rot, $
image=image,xvec=xvec,yvec=yvec,phitics=phitics,half=half, $
thetics=thetics,charsize=charsize,thephi=thephi,rmarg=rmarg, $
labels=labels,colors=colors,lcharsize=lcharsize,stitle=stitle, $
showpnts=showpnts,range=range,lower=lower,upper=upper,gclr=gclr, $
clevels=clevels,noscale=noscale,barwidth=barwidth, $
c_thick=c_thick,c_color=c_color,xtitle=xtitle,nadir=nadir
PURPOSE:
Display of images defined in polar coordinates (without resorting
to IDL's mapping routines).
INPUT:
psi
image quantity (2-d array) one value at each (phi,theta) point
note that the phi coordinate is the first index
phi
monitonically increasing vector specifying azimuthal coordinate
PHI must span either 0 to 360 degrees or 0 to 180 degrees. If
phi spans 0-180 degrees and the keyword HALF is not set, then
reflection symmetry is assumed, i.e., r(phi,theta)=r(360-phi,theta).
If phi(0) is not zero and keyword HALF is not set, then the
contour plot is rotated to that value of phi.
theta
monitonically increasing vector specifying polar coordinate (degrees)
KEYWORD INPUT:
style
0 do not plot anything, just return image,xvec and yvec
1 use confill for plot
2 use tvim for plot
3 use contour for plot, no grey scale
title
plot title
grdres
number of grid points in cartesian grid used to rebin polar
information. Array size is (grdres x grdres) default=51
phitics
azimuth tic mark spacing in degrees
thetics
polar angle tic mark spacing in degrees
half
if set, the part of the polar plot with azimuth angles between
180 and 360 is not displayed. if HALF lt 0 the half circle is
inverted so that the horizontal axis is at the top of the plot
and the magnitude of HALF is the vertical offset (in character
heights) below the previous plot (which is presumed to be a
TV_POLAR plot of the upper hemisphere). If abs(HALF) le 2 then
xaxis labeling is disabled. This option requires column major
ordering, i.e., either !P.MULTI(4)=1 or !P.MULTI(1)=1
Don't set HALF if ROT ne 0. (see example)
thephi
vector of azimuth angles at which to annotate polar angles. For
example setting THEPHI=[45,315] causes all the polar angles
listed in THETICS to be labeled at azimuth angles 45 and 315.
If maximum element of THEPHI is negative then the
(default is 45 degrees)
charsize
character size multiplier used on all plot labels but not on
color scale labels
rot
set location of azimuth zero point and direction of increase
0 right , azimuth increases counterclockwise (default)
1 top , azimuth increases counterclockwise
2 left , azimuth increases counterclockwise
3 bottom, azimuth increases counterclockwise
4 top , azimuth increases clockwise (standard compass)
5 left , azimuth increases clockwise
6 bottom, azimuth increases clockwise
7 left , azimuth increases clockwise
range
two or three element vector indicating physical range over which
to map the color scale. The third element of RANGE, if
specified, sets the step interval of the displayed color scale.
It has no effect when SCALE is not set. E.g., RANGE=[0., 1.,
0.1] will cause the entire color scale to be mapped between the
physical values of zero and one; the step size of the displayed
color scale will be set to 0.1. RANGE overides CLEVELS.
rmarg
right margin expansion factor to provide more room for extra
wide color scale annotation (default=1)
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies. When the COLORS array is set TVIM
will map values of A into the color values specified in COLORS.
How physical values are assigned to color values depends on how
the RANGE parameter is set, as shown in this table:
RANGE color_value
----- -----------
1. not set COLORS(A)
2. [amin,amax] COLORS((A-amin)/dinc)
3. [amin,amax,inc] COLORS((A-amin)/inc)
where amin, amax and inc are user specified elements
of RANGE and dinc=(amax-amin)/n_elements(COLORS). In
case 1, A is used directly as a subscript into COLORS.
lcharsize
character size of color key number or labels
stitle
color key title (drawn to the right of color scale)
contour
if set draw contour lines
showpnts
if set original grid of (phi,theta) points are ploted on the
image
gclr
the color used for grid labels and axis, default=!p.color
clevels
a vector of contour levels
barwidth
width of color key which appears to right of contour plot (default=1).
noscale
if set don't draw color scale to the right of the plot
c_thick
thickness of contour lines, set to zero to eliminate contour lines
c_color
color of contour lines (special interpretation of c_color is
possible when CONFILL is used, see CONFILL documentation)
lower
if set, theta values between 90 and 180 are ploted
nadir
if set, theta (which are usually zenith values) is displayed
as 180-theta
xtitle
title for horizontal axis when HALF is set, the titles would
usually be either "nadir angle" or "zenith angle",
OUTPUT:
none
KEYWORD OUTPUT:
image
rebined image of size (grdres,grdres)
xvec
vector of x coordinate values
yvec
vector of y coordinate values
These optional output quantities can be used to overplot contour
lines over the TV_POLAR output.
EXAMPLE:
; show all styles
loadct,5
phi=findgen(25)*15
theta=5+findgen(17)*5
psi=(cos(4*phi*!dtor)#sin(5*theta*!dtor))^2
w11x8 & !p.multi=[0,3,2]
tvim,psi,xrange=phi,yrange=theta,/interp
for s=1,3 do TV_POLAR,psi,phi,theta,style=s,c_thick=0
tv_polar,psi,phi,theta,style=1
tv_polar,psi,phi,theta,style=2
; show all ROT possibilities
w8x11 & !p.multi=[0,2,4]
loadct,5
phi=findgen(25)*15
theta=5+findgen(14)*5
psi=(phi*!dtor)#replicate(1.,n_elements(theta))
title="ROT = " + string(f='(i2)',indgen(8))+repchr(50,' ')
for rot=0,7 do TV_POLAR,psi,phi,theta,rot=rot,title=title(rot),sty=2,c_t=0
; plot radiance in lower and upper hemisphere
t=[0,15,32,45,60,70,80,89,91,100,110,120,135,148,165,180.]
p=[0,15,30,45,60,75,90,105,120,135,150,165,180.]
r=fltarr(13,16) & read,r
81, 81, 81, 81, 81, 81, 81, 81, 81, 81, 81, 81, 81,
96, 95, 93, 91, 87, 85, 84, 83, 80, 76, 74, 74, 73,
130,128,123,119,113,103, 95, 92, 84, 81, 80, 77, 75,
184,181,171,153,136,126,110,104, 93, 90, 84, 82, 84,
293,279,243,212,182,152,134,117,106, 99, 90, 93, 80,
388,370,323,250,208,165,144,119,110, 98, 91, 91, 90,
513,448,344,274,194,160,127,106, 97, 82, 82, 72, 74,
184,165,101, 71, 48, 40, 28, 26, 21, 19, 18, 18, 16,
97, 94, 89, 81, 73, 66, 60, 55, 52, 49, 47, 46, 45,
168,163,151,135,120,107, 96, 87, 80, 75, 71, 69, 69,
244,232,208,181,157,136,120,108, 98, 91, 87, 84, 83,
322,299,257,216,183,156,136,120,109,101, 95, 92, 91,
356,332,284,238,199,169,146,129,117,108,102, 98, 97,
291,281,254,222,193,168,148,132,121,112,107,103,102,
200,198,191,181,170,158,148,139,131,125,121,119,118,
148,148,148,148,148,148,148,148,148,148,148,148,148.
;
nclr=12 & cl=findrng(0,550,nclr) & clr=!d.n_colors*(1+findgen(nclr))/nclr
!p.multi=[0,2,4,1,1] & w8x11 & !y.omargin=[12,0] & set_charsize,2
loadct,5 & xtz='Zenith Angle' & xtn='Nadir Angle'
tv_polar,r,p,t,xt=xtz,/half,clevels=cl,colors=clr,/noscale
tv_polar,r,p,t,half=-4,/lower,clevels=cl,colors=clr,/noscale
tv_polar,r,p,t,xt=xtn,/half,clevels=cl,colors=clr,/noscale,/nadir
tv_polar,r,p,t,half=-4,/lower,clevels=cl,colors=clr,/noscale,/nadir
tv_polar,r,p,t,/half,clevels=cl,colors=clr,/noscale
tv_polar,r,p,t,half=-3,/lower,clevels=cl,colors=clr,/noscale
tv_polar,r,p,t,/half,clevels=cl,colors=clr,/noscale
tv_polar,r,p,t,half=-2,/lower,clevels=cl,colors=clr,/noscale
color_bar,cl,clr,pos=[0.1,0.05,0.9,0.12],title='Radiance (W/m!a2!n/um/sr)'
!y.omargin=0
DEPENDENCIES
TVIM, COLOR_KEY, CONTLEV, FINTERP, GENGRID, CONFILL, BOXPOS
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
Revisions:
aug98: use fill_image to smooth "horizon" points
sep98: allow phi(0) to be non-zero, causes rotation of plot to given azimuth
(See /home/drw/idl/esrg/tv_polar.pro)
TV_POLAR[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE:
tv_polar
USEAGE:
tv_polar,psi,phi,theta
tv_polar,psi,phi,theta,style=style,grdres=grdres,title=title,$
rot=rot,image=image,xvec=xvec,yvec=yvec,phitics=phitics,$
thetics=thetics,half=half,charsize=charsize,thephi=thephi,$
rmarg=rmarg,labels=labels,colors=colors,lcharsize=lcharsize,$
stitle=stitle,range=range,showpnts=showpnts,gclr=gclr,$
clevels=clevels,barwidth=barwidth,noscale=noscale
PURPOSE:
Display of images defined in polar coordinates (without resorting
to IDL's mapping routines).
INPUT:
psi
image quantity (2-d array) one value at each (phi,theta) point
note that the phi coordinate is the first index
phi
monitonically increasing vector specifying azimuthal coordinate
PHI must span either 0 to 360 degrees or 0 to 180 degrees. If
phi spans 0-180 degrees and the keyword HALF is not set, then
reflection symmetry is assumed, i.e.,
r(phi,theta)=r(360-phi,theta).
theta
monitonically increasing vector specifying polar coordinate (degrees)
KEYWORD INPUT:
style
0 do not plot anything, just return image,xvec and yvec
1 use confill for plot
2 use confill for plot, overlay contour lines
3 use tvim for plot
4 use tvim for plot, overlay contour lines
5 use contour for plot, no grey scale
title
plot title
grdres
number of grid points in cartesian grid used to rebin polar
information. Array size is (grdres x grdres) default=51
phitics
azimuth tic mark spacing in degrees
thetics
polar angle tic mark spacing in degrees
half
if set, the part of the polar plot with azimuth angles between
180 and 360 is not displayed
thephi
vector of azimuth angles at which to annotate polar angles. For
example setting THEPHI=[45,315] causes all the polar angles
listed in THETICS to be labeled at azimuth angles 45 and 315.
If maximum element of THEPHI is negative then the
(default is 45 degrees)
charsize
character size multiplier used on all plot labels but not on
color scale labels
rot
set location of azimuth zero point and direction of increase
0 right , azimuth increases counterclockwise (default)
1 top , azimuth increases counterclockwise
2 left , azimuth increases counterclockwise
3 bottom, azimuth increases counterclockwise
4 top , azimuth increases clockwise (standard compass)
5 left , azimuth increases clockwise
6 bottom, azimuth increases clockwise
7 left , azimuth increases clockwise
range
two or three element vector indicating physical range over which
to map the color scale. The third element of RANGE, if
specified, sets the step interval of the displayed color scale.
It has no effect when SCALE is not set. E.g., RANGE=[0., 1.,
0.1] will cause the entire color scale to be mapped between the
physical values of zero and one; the step size of the displayed
color scale will be set to 0.1. RANGE overides CLEVELS.
rmarg
right margin expansion factor to provide more room for extra
wide color scale annotation (default=1)
labels
a vector of strings used to label the color key levels. If not
set the default color key number labels are used. If the number
of elements in LABELS is the same as the number of elements in
COLORS then the labels will appear in the middle of a given
color band instead of at the boundary between colors. If COLORS
is not set the number of elements in LABELS should be at least
as large as the number of color key segments plus one.
colors
an array of color indicies. When the COLORS array is set TVIM
will map values of A into the color values specified in COLORS.
How physical values are assigned to color values depends on how
the RANGE parameter is set, as shown in this table:
RANGE color_value
----- -----------
1. not set COLORS(A)
2. [amin,amax] COLORS((A-amin)/dinc)
3. [amin,amax,inc] COLORS((A-amin)/inc)
where amin, amax and inc are user specified elements
of RANGE and dinc=(amax-amin)/n_elements(COLORS). In
case 1, A is used directly as a subscript into COLORS.
lcharsize
character size of color key number or labels
stitle
color key title (drawn to the right of color scale)
contour
if set draw contour lines
showpnts
if set original grid of (phi,theta) points are ploted on the
image
gclr
the color used for grid labels and axis, default=!p.color
clevels
a vector of contour levels
barwidth
width of color key which appears to right of contour plot (default=1).
noscale
if set don't draw color scale to the right of the plot
OUTPUT:
none
KEYWORD OUTPUT:
image
rebined image of size (grdres,grdres)
xvec
vector of x coordinate values
yvec
vector of y coordinate values
These optional output quantities can be used to overplot contour
lines over the TV_POLAR output.
EXAMPLE:
; show all styles
phi=findgen(25)*15
theta=5+findgen(17)*5
psi=(cos(4*phi*!dtor)#sin(5*theta*!dtor))^2
w11x8 & !p.multi=[0,3,2]
tvim,psi,xrange=phi,yrange=theta,/interp
for s=1,5 do TV_POLAR,psi,phi,theta,style=s
; show all ROT possibilities
w8x11 & !p.multi=[0,2,4]
phi=findgen(25)*15
theta=5+findgen(14)*5
psi=(phi*!dtor)#replicate(1.,n_elements(theta))
title="ROT = " + string(f='(i2)',indgen(8))+repchr(50,' ')
for rot=0,7 do TV_POLAR,psi,phi,theta,rot=rot,title=title(rot),style=3
DEPENDENCIES
TVIM, COLOR_KEY, CONTLEV, FINTERP, GENGRID, CONFILL
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/old.esrg/tv_polar.pro)
TWIN_MOVIE.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
TWIN_MOVIE.PRO
PURPOSE:
To read SECIS data from both the white light and Fe green line
channels into a single array for simultaneous display in an
XWindow or for using to create a movie with (e.g.) WR_MOVIE.PRO.
USAGE:
TWIN_MOVIE,TWIN
where TWIN is a floating point array of dimensions
1008x504x64.
AUTHOR:
D. Williams, 12/1/2000, verion 1.0, !defunkt!
(See /home/drw/idl/secis/twin_movie.pro)
TWOSURF
[Previous Routine]
[Next Routine]
[List of Routines]
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.
(See /home/drw/idl/aux/twosurf.pro)
UAV_PATH[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: uav_path
PURPOSE: dispay a time history of measured quantities obtained
on a moving ship or plane. UAV_PATH provides an easy
user interface to 1) select measured quantities to plot
and 2) run SPRITE to hilight the correspondences of
different data channels as a function of time and position.
USEAGE: uav_path,buf,labels,coor,trange=trange,select=select
INPUT:
buf array of data values of dimension (number of variables)
x (number of samples). Two of the measured quantities
should correspond to the horizontal coordiates of the
sample location, for example longitude and latitude.
A third quantity should provide the time coordinate of
the measurements.
labels string array of variable names
coor Three element vector array of indecies in BUF which
correspond to time and the "x" and "y" horizontal
coordinates of the measurement. For example the
uav/tddr data set has GPS_TIME, GPS_LON and GPS_LAT at
[7,3,2]. If COOR is not set, it defaults to [7,3,2].
KEYWORD INPUT:
trange time range of interest
select array of variable indecies to plot. You can also use
SELECT to retrieve the indecies of the plot quantities
selected interactively. Just set SELECT to an
undefined or zero valued variable on the first call to
UAV_PATH and reuse the returned value of SELECT in the
next call to UAV_PATH to repeat the plot set, (perhaps
with a different setting of TRANGE).
sprite run SPRITE after plots are displayed
bad a single scalor value which is interpreted as a "bad"
measurement. Any time sample returning this value for any
particular plot quantity will be rejected.
EXAMPLE:
get_uavtddr,buf,labels
select=0
uav_path,buf,labels,select=select ; select uav quantities interactively
; save selections in SELECT
uav_path,buf,labels,select=select,trange=[16,17],/sprite
; you can also use UAV_PATH with ZOOMBAR to zero in on a time range
get_uavtddr,buf,labels,coor
select=[0,5,11,12,17]
uav_path,buf,labels,coor,select=select
while zoombar(rng) do uav_path,buf,labels,select=select,trange=rng
REVISIONS:
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/uav_path.pro)
UAV_PATH[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: uav_path
PURPOSE: dispay a time history of measured quantities obtained
on a moving ship or plane. UAV_PATH provides an easy
user interface to 1) select measured quantities to plot
and 2) run SPRITE to hilight the correspondences of
different data channels as a function of time and position.
USEAGE: uav_path,buf,labels,coor,trange=trange,select=select
INPUT:
buf array of data values of dimension (number of variables)
x (number of samples). Two of the measured quantities
should correspond to the horizontal coordiates of the
sample location, for example longitude and latitude.
A third quantity should provide the time coordinate of
the measurements.
labels string array of variable names
coor Three element vector array of indecies in BUF which
correspond to time and the "x" and "y" horizontal
coordinates of the measurement. For example the
uav/tddr data set has GPS_TIME, GPS_LON and GPS_LAT at
[7,3,2]. If COOR is not set, it defaults to [7,3,2].
KEYWORD INPUT:
trange time range of interest
select array of variable indecies to plot. You can also use
SELECT to retrieve the indecies of the plot quantities
selected interactively. Just set SELECT to an
undefined or zero valued variable on the first call to
UAV_PATH and reuse the returned value of SELECT in the
next call to UAV_PATH to repeat the plot set, (perhaps
with a different setting of TRANGE).
sprite run SPRITE after plots are displayed
bad a single scalor value which is interpreted as a "bad"
measurement. Any time sample returning this value for any
particular plot quantity will be rejected.
EXAMPLE:
get_uavtddr,buf,labels
select=0
uav_path,buf,labels,select=select ; select uav quantities interactively
; save selections in SELECT
uav_path,buf,labels,select=select,trange=[16,17],/sprite
; you can also use UAV_PATH with ZOOMBAR to zero in on a time range
get_uavtddr,buf,labels,coor
select=[0,5,11,12,17]
uav_path,buf,labels,coor,select=select
while zoombar(rng) do uav_path,buf,labels,select=select,trange=rng
REVISIONS:
author: Paul Ricchiazzi feb95
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/uav_path.pro)
UNDEFINE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
UNDEFINE
PURPOSE:
The purpose of this program is to delete or undefine
an IDL program variable from within an IDL program or
at the IDL command line. It is a more powerful DELVAR.
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:
Utilities.
CALLING SEQUENCE:
UNDEFINE, variable
REQUIRED INPUTS:
variable: The variable to be deleted.
SIDE EFFECTS:
The variable no longer exists.
EXAMPLE:
To delete the variable "info", type:
IDL> Undefine, info
MODIFICATION HISTORY:
Written by David Fanning, 8 June 97, from an original program
given to me by Andrew Cool, DSTO, Adelaide, Australia.
Simplified program so you can pass it an undefined variable. :-) 17 May 2000. DWF
(See /home/drw/idl/aux/undefine.pro)
UNIQUE
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: unique
PURPOSE: returns sorted list of unique elements in an array
USEAGE: result=unique(x)
INPUT:
x array of values
EXAMPLE:
print,unique(dist(10))
AUTHOR: Paul Ricchiazzi 25 Feb 99
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
(See /home/drw/idl/esrg/unique.pro)
URZOOM.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
URZOOM.PRO
PURPOSE:
To enlarge the upper-right area of a 1024x1024 TRACE image
CALLING SEQUENCE:
urzoom,frame
INPUTS:
frame - image
HISTORY:
D. Williams 4/6/99, similar to zoom1, which only works
on images from an indexed datacube.
(See /home/drw/idl/bin/urzoom.pro)
URZOOM2.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
URZOOM2.PRO
PURPOSE:
To enlarge the upper-right area of a 512x512 TRACE image
CALLING SEQUENCE:
urzoom2,frame
INPUTS:
frame - image
HISTORY:
D. Williams 4/6/99, similar to zoom1, which only works
on images from an indexed datacube.
(See /home/drw/idl/bin/urzoom2.pro)
USERSYMBOL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: UserSymbol
PURPOSE: Make neat little user defined symbols
CATEGORY: Plotting/Graphics
CALLING SEQUENCE: UserSymbol,symbol_name,x,y,SYMSIZE=symsize,LIST=list,$
HELP=help,_EXTRA=_extra
+
INPUTS:
Symbol_name a string containing the name of the desired symbol.
Currently accepted values are:
'DIAMOND', 'PENTAGON', 'CLOVER', 'PACMAN',
'SPIRAL', 'BIGX', 'CIRCLE', 'SQUARE',
'TRIANGLE', 'STAR', 'HEXAGON', 'HEART',
'SPADE', 'CLUB' 'SUN', 'EYE',
'DASH0', 'DASH1', 'DASH2', 'DASH3',
'DASH4', 'DASH5', 'DTRIANGLE', 'RTRIANGLE',
'LTRINGLE'
if the symbol name is appended with the suffix
"_o" (e.g., "DIAMOND_O") then the symbol is
left unfilled. Filling has no effect on symbols
composed of open curves (e.g., "SPIRAL")
KEYWORD PARAMETERS:
SYMSIZE Symbol size (default=1)
LIST if set, puts the list of available symbol names
in the input parameter Symbol_Name
HELP if set, returns this documentation header
angle symbol angle
and also the keywords which apply to USERSYM
THICK Line thickness (default=1)
COLOR Symbol color
SIDE EFFECTS: Calls USERSYM to load the new symbol
EXAMPLE: UserSymbol,'BigX' ;to change to an X outline
UserSymbol,list,/LIST ;to get a list of possible symbols
usersymbol & erase & plots, .5,.5,psym=8,/norm,symsize=5
MODIFICATION HISTORY: Brian Jackel August 10 1992
University of Western Ontario
Bjj June 2 1994 Fixed up the handling of no clear match.
pjr feb 1996 "_o" suffix used to specify open non-filled symbols
(See /home/drw/idl/esrg/usersymbol.pro)
VCOLORBAR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
VCOLORBAR
FILENAME:
vcolorbar__define.pro
;
PURPOSE:
The purpose of this program is to create a vertical
colorbar object to be used in conjunction with other
IDL 5 graphics objects.
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:
IDL 5 Object Graphics.
CALLING SEQUENCE:
thisColorBar = Obj_New('VColorBar')
REQUIRED INPUTS:
None.
INIT METHOD KEYWORD PARAMETERS:
COLOR: A three-element array representing the RGB values of a color
for the colorbar axes and annotation. The default value is
white: [255,255,255].
NAME: The name associated with this object.
NCOLORS: The number of colors associated with the colorbar. The
default is 256.
MAJOR: The number of major tick divisions on the colorbar axes.
The default is 5.
MINOR: The number of minor tick marks on the colorbar axes.
The default is 4.
PALETTE: A palette object for the colorbar. The default palette
is a gray-scale palette object.
POSITION: A four-element array specifying the position of the
colorbar in normalized coordinate space. The default position
is [0.90, 0.10, 0.95, 0.90].
RANGE: The range associated with the colorbar axis. The default
is [0, NCOLORS].
TEXT: A text object. Colorbar axis annotation will use this text
object to set its properties. The default is a text object
using a 8 point Helvetica font in the axis color.
TITLE: A string containing a title for the colorbar axis
annotation. The default is a null string.
OTHER METHODS:
GetProperty (Procedure): Returns colorbar properties in keyword
parameters as defined for the INIT method. Keywords allowed are:
COLOR
MAJOR
MINOR
NAME
PALETTE
POSITION
RANGE
TEXT
TITLE
TRANSFORM
SetProperty (Procedure): Sets colorbar properties in keyword
parameters as defined for the INIT method. Keywords allowed are:
COLOR
NAME
MAJOR
MINOR
PALETTE
POSITION
RANGE
TEXT
TITLE
TRANSFORM
SIDE EFFECTS:
A VCOLORBAR object is created. The colorbar INHERITS IDLgrMODEL.
Thus, all IDLgrMODEL methods and keywords can also be used. It is
the model that is selected in a selection event, since the SELECT_TARGET
keyword is set for the model.
RESTRICTIONS:
None.
EXAMPLE:
To create a colorbar object and add it to a plot view object, type:
thisColorBarObject = Obj_New('VColorBar')
plotView->Add, thisColorBarObject
plotWindow->Draw, plotView
MODIFICATION HISTORY:
Written by David Fanning, 19 June 97.
Changed the optional "colorbarmodel" parameter to an
optional GETMODEL parameter. 26 June 97. DWF.
Fixed bug in the way the color palette was assigned. 13 Aug 97. DWF.
Added missing container object to self structure. 13 Aug 97. DWF.
Removed image model, which was a workaround for
broken 5.0 objects. 5 Oct 97. DWF
Fixed cleanup procedure to clean up ALL objects. 12 Feb 98. DWF.
Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
Modified colorbar to INHERIT an IDLgrModel object. This allows me to
add the colorbar to other models directly. 20 Sept 98. DWF.
Added NAME keyword to give the colorbar a name. 20 Sept 98. DWF.
Changed a reference to _Ref_Extra to _Extra. 27 Sept 98. DWF.
Fixed bug when adding a text object via the TEXT keyword. 9 May 99. DWF.
Fixed a bug with getting the text object via the TEXT keyword. 16 Aug 2000. DWF.
Added the TRANSFORM keyword to GetProperty and SetProperty methods. 16 Aug 2000. DWF.
Added RECOMPUTE_DIMENSIONS=2 to text objects. 16 Aug 2000. DWF.
Added a polygon object around the image object. This allows rotation in 3D space. 16 Aug 2000. DWF.
(See /home/drw/idl/aux/vcolorbar__define.pro)
VEL_LOOP[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: vel_loop
PURPOSE: Calculate the
USEAGE: vel_map, qlds, Ion, Int, Vel, Width
INPUT:
qlds CDS INT_DIST Quick Look Data Structure.
Ion String array containing ion name.
OUTPUT:
Int Light curve along loop
Vel Velocity map
Width Line width map
Example:
AUTHOR: Peter T. Gallagher, March. '98
(See /home/drw/idl/bin/vel_loop.pro)
VEL_LOOP[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: vel_loop
PURPOSE: Calculate the
USEAGE: vel_map, qlds, Ion, Int, Vel, Width
INPUT:
qlds CDS INT_DIST Quick Look Data Structure.
Ion String array containing ion name.
OUTPUT:
Int Light curve along loop
Vel Velocity map
Width Line width map
Example:
AUTHOR: Peter T. Gallagher, March. '98
(See /home/drw/idl/bin/ptg/vel_loop.pro)
VEL_MAP[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: vel_map
PURPOSE: Create velocity map and line width map from INT_DIST observations.
The code reads a CDS QLDS, then prompts the user to select an ion
and creates both a velocity map and a line width map in the
selected ion.
USEAGE: vel_map, QLDS, image, vel, width
INPUT:
qlds CDS INT_DIST Quick Look Data Structure.
ion String array containing ion name.
OUTPUT:
image image in selected line
vel velocity map
width line width map
Example:
Qlds = READCDSFITS('s7103r00.sav')
CDS_CLEAN,Qlds,/fill_missing
NIS_CALIB,Qlds
VEL_MAP, Qlds, image, Doppler_map, Line_width_map
AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/vel_map.pro)
VEL_MAP[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: vel_map
PURPOSE: Create velocity map and line width map from INT_DIST observations.
The code reads a CDS QLDS, then prompts the user to select an ion
and creates both a velocity map and a line width map in the
selected ion.
USEAGE: vel_map, QLDS, image, vel, width
INPUT:
qlds CDS INT_DIST Quick Look Data Structure.
ion String array containing ion name.
OUTPUT:
image image in selected line
vel velocity map
width line width map
Example:
Qlds = READCDSFITS('s7103r00.sav')
CDS_CLEAN,Qlds,/fill_missing
NIS_CALIB,Qlds
VEL_MAP, Qlds, image, Doppler_map, Line_width_map
AUTHOR: Peter T. Gallagher, Nov. '97
(See /home/drw/idl/bin/ptg/vel_map.pro)
VEL_SELECT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: vel_select
PURPOSE: Calculate the Velocity in a selected region of s7103r00 using cursor
USEAGE: vel_select,'s7103r00.sav'
INPUT:
OUTPUT:
Example:
AUTHOR: Peter T. Gallagher, March. '98
(See /home/drw/idl/bin/vel_select.pro)
VEL_SELECT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: vel_select
PURPOSE: Calculate the Velocity in a selected region of s7103r00 using cursor
USEAGE: vel_select,'s7103r00.sav'
INPUT:
OUTPUT:
Example:
AUTHOR: Peter T. Gallagher, March. '98
(See /home/drw/idl/bin/ptg/vel_select.pro)
VERLINE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: verline
PURPOSE: Draw a vertical line through a given data point
USEAGE: hline,x
INPUT:
x x-coord of point through which line is to be drawn
OUTPUT:
Example: CURSOR,x,y,/data,/down
VERLINE,x
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/verline.pro)
VERLINE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: verline
PURPOSE: Draw a vertical line through a given data point
USEAGE: hline,x
INPUT:
x x-coord of point through which line is to be drawn
OUTPUT:
Example: CURSOR,x,y,/data,/down
VERLINE,x
AUTHOR: Peter T. Gallagher, May. '98
(See /home/drw/idl/bin/ptg/verline.pro)
VMEDIAN
[Previous Routine]
[Next Routine]
[List of Routines]
vmedian
vector median filter routine
CALLING SEQUENCE:
vmedian,in,width,out
INPUTS:
in - input vector
width - filter width (should be odd)
OUTPUTS:
out - output median filtered vector.
unfiltered end points are replaced with closest filtered
point.
HISTORY
version 1. D. Lindler Mar 89
(See /home/drw/idl/icur/vmedian.pro)
VSCAT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE vscat
PURPOSE: 1. use the interactive graphics cursor and the
DEFINE_REGION procedure to select a region
2. plot a x vs y scatter plots of two variables from that
region
USEAGE vscat,x,y,image
INPUT:
x array ploted on x axis of scatter plot
y array ploted on y axis of scatter plot
image image used to select regions to plot
KEYWORD INPUT:
xrange range of scatter plot x axis
yrange range of scatter plot y axis
xtitle title of scatter plot x axis
ytitle title of scatter plot y axis
title title of image plot
EXAMPLE
!p.multi=[0,1,2]
x=20*randata(128,128,s=4)+(findgen(128) # replicate(1.,128))
y=20*randata(128,128,s=4)+(replicate(1.,128) # findgen(128))
image=x+y
vscat,x,y,image
OUTPUT: none
author: Paul Ricchiazzi aug93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/vscat.pro)
VSCAT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE vscat
PURPOSE: 1. use the interactive graphics cursor and the
DEFINE_REGION procedure to select a region
2. plot a x vs y scatter plots of two variables from that
region
USEAGE vscat,x,y,image
INPUT:
x array ploted on x axis of scatter plot
y array ploted on y axis of scatter plot
image image used to select regions to plot
KEYWORD INPUT:
xrange range of scatter plot x axis
yrange range of scatter plot y axis
xtitle title of scatter plot x axis
ytitle title of scatter plot y axis
title title of image plot
EXAMPLE
!p.multi=[0,1,2]
x=20*randata(128,128,s=4)+(findgen(128) # replicate(1.,128))
y=20*randata(128,128,s=4)+(replicate(1.,128) # findgen(128))
image=x+y
vscat,x,y,image
OUTPUT: none
author: Paul Ricchiazzi aug93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/vscat.pro)
VTT_TRIM.PRO[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
vtt_trim.PRO
PURPOSE:
To trim TRACE UV/WL images to the same field of view as
those of the Big Bear VTT observations, for simultaneous
presentation.
CALLING SEQUENCE:
vtt_trim,cube
INPUTS:
cube - 3D data set
HISTORY:
D. Williams 26/7/99, second version (vtt_trim_euv) to be
used to trim the larger EUV images to the same field.
PRO vtt_trim,cube,outcube
s=size(cube)
nframes=s(3)
outcube=fltarr(216,220,nframes)
FOR i=0,(nframes-1) do begin
frame=cube(*,*,i)
vttregion=frame(225:440,161:380)
outcube(*,*,i)=vttregion
PRINT,'trimmed frame...',i
ENDFOR
END
(See /home/drw/idl/bin/vtt_trim.pro)
VTT_TRIM.PRO[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
vtt_trim.PRO
PURPOSE:
To trim TRACE UV/WL images to the same field of view as
those of the Big Bear VTT observations, for simultaneous
presentation.
CALLING SEQUENCE:
vtt_trim_euv,cube,outcube
INPUTS:
cube - 3D data set
HISTORY:
D. Williams 26/7/99, second version (vtt_trim_euv) to be
used to trim the larger EUV images to the same field.
PRO vtt_trim,cube,outcube
s=size(cube)
nframes=s(3)
outcube=fltarr(216,220,nframes)
FOR i=0,(nframes-1) do begin
frame=cube(*,*,i)
vttregion=frame(481:696,427:646)
outcube(*,*,i)=vttregion
PRINT,'trimmed frame...',i
ENDFOR
END
(See /home/drw/idl/bin/vtt_trim_euv.pro)
W11X8[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: w11x8
PURPOSE: create a window which approximates the aspect ratio of a
8.5 x 11 piece of paper in landscape orientation
USEAGE: w11x8
INPUT: none
KEYWORD INPUT:
free if set, window,/free is used to create a new window
EXAMPLE:
w11x8
plot,dist(20)
AUTHOR: Paul Ricchiazzi 03 Aug 93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/w11x8.pro)
W11X8[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: w11x8
PURPOSE: create a window which approximates the aspect ratio of a
8.5 x 11 piece of paper in landscape orientation
USEAGE: w11x8
INPUT: none
KEYWORD INPUT:
free if set, window,/free is used to create a new window
EXAMPLE:
w11x8
plot,dist(20)
AUTHOR: Paul Ricchiazzi 03 Aug 93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/w11x8.pro)
W8X11[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: w8x11
PURPOSE: create a window which approximates the aspect ratio of a
8.5 x 11 piece of paper
USEAGE: w8x11
INPUT: none
KEYWORD INPUT:
free if set, window,/free is used to create a new window
EXAMPLE:
w8x11
plot,dist(20)
AUTHOR: Paul Ricchiazzi 03 Aug 93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/w8x11.pro)
W8X11[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: w8x11
PURPOSE: create a window which approximates the aspect ratio of a
8.5 x 11 piece of paper
USEAGE: w8x11
INPUT: none
KEYWORD INPUT:
free if set, window,/free is used to create a new window
EXAMPLE:
w8x11
plot,dist(20)
AUTHOR: Paul Ricchiazzi 03 Aug 93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/w8x11.pro)
WACONV
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WACONV
PURPOSE:
This function performs a Convolution for Two-Scale Transform.
CATEGORY:
Wavelets
CALLING SEQUENCE:
y = WACONV(f,x)
INPUTS:
f: filter.
x: 1-d signal.
OUTPUTS:
y: filtered result.
NOTES:
Filtering by periodic convolution of x with the
time-reverse of f.
EXAMPLE:
SEE ALSO:
wiconv, wupdydhi, wupdydlo, wdndydhi, wdndydlo
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: aconv.m
(See /home/drw/idl/wwbsrc/waconv.pro)
WADNOISE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WADNOISE
PURPOSE:
To add noise to the "sig" data array or image.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WADNOISE, sig, numrow, numcol, noise_type, noise_level
INPUTS:
sig = current data array/signal
numrow = number of rows
numcols = number of columns
noise_type = uniform (2) or normal (1) or Poisson (3) (default = 1)
noise_lev = amplitude of noise (default = 1)
OUTPUTS:
sig = now noisy data array/signal/image
TT = 'I' if image and 'S' if signal
EXAMPLE:
IDL> ;Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
IDL> ncol = WGETSIZE(sig, nrow)
IDL> tt = 'S' if 1D dataset or tt = 'I' if 2D dataset
IDL> WADNOISE, sig, nrow, ncol, noise_type, noise_lev, tt
IDL> If tt EQ 'S' then WPLOTIT, st, 1, sig ELSE WPLOTIT, st, 10, sig
MODIFICATION HISTORY:
Amara Graps September 1995.
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wadnoise.pro)
WANDER_WATCHER[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WANDER_WATCHER
PURPOSE:
track the motion of a given set of SECIS frames by tracking
the apparent motion of the prominence off the limb in the
broad-band sequence.
STATUS:
still being written!
(See /home/drw/idl/secis/wander_watcher.pro)
WANDER_WATCHER[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WANDER_WATCHER
PURPOSE:
track the motion of a given set of SECIS frames by tracking
the apparent motion of the prominence off the limb in the
broad-band sequence.
STATUS:
still being written!
(See /home/drw/idl/secis/wander_tracker.pro)
WAVELET
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: WAVELET
PURPOSE: Compute the WAVELET transform of a 1D time series.
CALLING SEQUENCE:
wave = WAVELET(Y,DT)
INPUTS:
Y = the time series of length N.
DT = amount of time between each Y value, i.e. the sampling time.
OUTPUTS:
WAVE is the WAVELET transform of Y. This is a complex array
of dimensions (N,J+1). FLOAT(WAVE) gives the WAVELET amplitude,
ATAN(IMAGINARY(WAVE),FLOAT(WAVE)) gives the WAVELET phase.
The WAVELET power spectrum is ABS(WAVE)^2.
OPTIONAL KEYWORD INPUTS:
S0 = the smallest scale of the wavelet. Default is 2*DT.
DJ = the spacing between discrete scales. Default is 0.125.
A smaller # will give better scale resolution, but be slower to plot.
J = the # of scales minus one. Scales range from S0 up to S0*2^(J*DJ),
to give a total of (J+1) scales. Default is J = (LOG2(N DT/S0))/DJ.
MOTHER = A string giving the mother wavelet to use.
Currently, 'Morlet','Paul','DOG' (derivative of Gaussian)
are available. Default is 'Morlet'.
PARAM = optional mother wavelet parameter.
For 'Morlet' this is k0 (wavenumber), default is 6.
For 'Paul' this is m (order), default is 4.
For 'DOG' this is m (m-th derivative), default is 2.
PAD = if set, then pad the time series with enough zeroes to get
N up to the next higher power of 2. This prevents wraparound
from the end of the time series to the beginning, and also
speeds up the FFT's used to do the wavelet transform.
This will not eliminate all edge effects (see COI below).
LAG1 = LAG 1 Autocorrelation, used for SIGNIF levels. Default is 0.0
SIGLVL = significance level to use. Default is 0.95
VERBOSE = if set, then print out info for each analyzed scale.
RECON = if set, then reconstruct the time series, and store in Y.
Note that this will destroy the original time series,
so be sure to input a dummy copy of Y.
FFT_THEOR = theoretical background spectrum as a function of
Fourier frequency. This will be smoothed by the
wavelet function and returned as a function of PERIOD.
OPTIONAL KEYWORD OUTPUTS:
PERIOD = the vector of "Fourier" periods (in time units) that corresponds
to the SCALEs.
SCALE = the vector of scale indices, given by S0*2^(j*DJ), j=0...J
where J+1 is the total # of scales.
COI = if specified, then return the Cone-of-Influence, which is a vector
of N points that contains the maximum period of useful information
at that particular time.
Periods greater than this are subject to edge effects.
This can be used to plot COI lines on a contour plot by doing:
IDL> CONTOUR,wavelet,time,period
IDL> PLOTS,time,coi,NOCLIP=0
YPAD = returns the padded time series that was actually used in the
wavelet transform.
DAUGHTER = if initially set to 1, then return the daughter wavelets.
This is a complex array of the same size as WAVELET. At each scale
the daughter wavelet is located in the center of the array.
SIGNIF = output significance levels as a function of PERIOD
FFT_THEOR = output theoretical background spectrum (smoothed by the
wavelet function), as a function of PERIOD.
[ Defunct INPUTS:
[ OCT = the # of octaves to analyze over. ]
[ Largest scale will be S0*2^OCT. ]
[ Default is (LOG2(N) - 1). ]
[ VOICE = # of voices in each octave. Default is 8. ]
[ Higher # gives better scale resolution, ]
[ but is slower to plot. ]
]
(See /home/drw/idl/secis/wavelet/wavelet.pro)
WAVESET
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WAVESET
PURPOSE:
To set the common variables used in the Wavelet Workbench library.
CATEGORY:
Wavelets
CALLING SEQUENCE:
IDL>.run waveset
INPUTS:
None.
OUTPUTS:
The common variables set for Wavelet Workbench.
COMMON VARIABLE DEFINITIONS:
COMMON WWB_COMMON, $
TEXT_ANNOUNCE, wd, sig, len, st, noise_type, noise_lev, $
QMF, LD, shrinkage_type, WaveType, ParVal
COMMON Wave_color, $
max_color, max_image, $
white, yellow, lavender, aqua, pink, green, red, orange, blue, $
lt_gray, med_green, brown, olive, purple, dk_gray, black
NOTES:
If one runs this program first, then they can use the Wavelet Workbench
routines without the widget interface provided in the routine: wwb.pro
MODIFICATION HISTORY:
copyright Amara Graps 1996.
(See /home/drw/idl/wwbsrc/waveset.pro)
WAVETEST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: WAVETEST
PURPOSE: Example IDL program for WAVELET, using NINO3 SST dataset
EXECUTION:
IDL> .run wavetest
See "http://paos.colorado.edu/research/wavelets/"
Written January 1998 by C. Torrence
(See /home/drw/idl/secis/wavelet/wavetest.pro)
WAVE_EXAMPLE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WAVE_EXAMPLE
PURPOSE:
Calculate and display the wavelet (power) transform of a time series
(CURVE) with the time series above the plot for comparison with the
transform, and also show the global wavelet spectrum to the right,
since it represents the summation of the power transform over time,
and is therefore analogous to the Fourier transform of the series.
CALLING SEQUENCE:
wave_example,curve,print=print,pc=pc,title=title,nocon=nocon
INPUTS:
CURVE - a 1-D time series, e.g. a light curve
INTERACTIVE INPUTS DURING EXECUTION:
The user is first asked for a maximum value for the low-pass filter
called by WAVE_EXAMPLE. For the SECIS data, an unfiltered time series
will be analysed by specifying half the data sampling rate of 44.2 Hz
(i.e. 22.1 Hz).
The second parameter requested is the significance (confidence)
level which the WAVELET function will calculate as a set of contours
in the power transform. Concentrations of power enclosed within these
contours will be significant to that level. E.g., if the user specifies
a value of 0.99 (i.e. 99%) then there is a 1% chance that the power
within the contours is due to noise.
KEYWORDS:
PRINT - if set, then set parameters applicable to printing to a
postscript file. NOTE: Does not actually set the display
to the PostScript device - this must be done manually.
PC - the plot colour for the contours and cone-of-influence
boundary and cross-hatching. This is a value from 0 to
255. In a monochromatic colour table (e.g. loadct,3 for
red temperature) 0 will be black, 255 will be white, and
any other colours will be somewhere in between (e.g.
scale linearly for colour tables 0,1,3, & 8;
logarithmically for colour table 9).
TITLE - a string, specifying the title over the wavelet transform
part of the display output.
NOCON - if set, then do not display either contours or the
cone-of-influence calculated by the WAVELET routine
OUTPUTS:
None, except for the display of the wavelet transform etc. to
either X windows (the default) or (optionally) the PostScript device.
EXAMPLES:
IDL> wave_example,series,title='Wavelet Transform for our series thing'
to write the output to an Encapsulated PostScript file:
IDL> set_plot,'PS
IDL> DEVICE,/encapsul,/color,filename='test1.eps',xsize=5,ysize=5
IDL> wave_example,series,title='Another Title',/print,pc=0
IDL> DEVICE,/close
IDL> SET_PLOT,'X'
or, if you have TOGGLE.PRO in your path:
IDL> TOGGLE,filename='wavelet.ps',/landscape,/color
IDL> wave_example,series,title='Another Title',/print,pc=0
IDL> TOGGLE
CALLS:
ECLIPSFILTER.PRO, WAVELET.PRO, WAVE_SIGNIF.PRO
HISTORY:
Based on ECLIPSE.PRO by Eoghan O'Shea, QUB, 2000
Modified in stages by D. Williams for the SECIS eclipse data
(See /home/drw/idl/secis/wave_example.pro)
WAVE_POINT2
[Previous Routine]
[Next Routine]
[List of Routines]
PRO WAVE_POINT2,data,series,print=print,nowave=nowave
PURPOSE:
To generate a time series and wavelet transform of the
intensity in a particular pixel in an image sequence
(cube) of the SECIS data. Currently in a very early,
sole-user version. To be upgraded and made more generic.
INPUT:
DATA - image cube containing the pixel you want to monitor
OUTPUT:
SERIES - the output time series, so you can re-run eclips2
on it at a later stage to get the wavelet transform.
KEYWORDS:
PRINT - send the output wavelet transform to a file named
'wave_point.output.ps'
NOWAVE - don't produce a wavelet transform, just return
the time series as an output.
CALLS:
ECLIPS3, so you need the WAVELET, WAVE_SIGNIF and ECLIPS_FILTER
routines in your path, as well as TVIM, for display purposes.
HISTORY:
version 0.5, 14/08/00, D.Williams.
(See /home/drw/idl/secis/wave_point2.pro)
WAVE_POINT2A
[Previous Routine]
[Next Routine]
[List of Routines]
PRO WAVE_POINT2A,data,series,print=print,nowave=nowave
PURPOSE:
To generate a time series and wavelet transform of the
intensity in a particular pixel in an image sequence
(cube) of the SECIS data. Currently in a very early,
sole-user version. To be upgraded and made more generic.
INPUT:
DATA - image cube containing the pixel you want to monitor
OUTPUT:
SERIES - the output time series, so you can re-run eclips2
on it at a later stage to get the wavelet transform.
KEYWORDS:
PRINT - send the output wavelet transform to a file named
'wave_point.output.ps'
NOWAVE - don't produce a wavelet transform, just return
the time series as an output.
CALLS:
ECLIPS2, so you need the WAVELET, WAVE_SIGNIF and ECLIPS_FILTER
routines in your path; TVIM, too.
HISTORY:
version 0.5, 14/08/00, D.Williams.
(See /home/drw/idl/secis/wave_point2a.pro)
WAVE_POINT2AW
[Previous Routine]
[Next Routine]
[List of Routines]
PRO WAVE_POINT2Aw,data,series,print=print,nowave=nowave
PURPOSE:
To generate a time series and wavelet transform of the
intensity in a particular pixel in an image sequence
(cube) of the SECIS data. Currently in a very early,
sole-user version. To be upgraded and made more generic.
INPUT:
DATA - white image cube containing the pixel you want to monitor
OUTPUT:
SERIES - the output time series, so you can re-run eclips2
on it at a later stage to get the wavelet transform.
KEYWORDS:
PRINT - send the output wavelet transform to a file named
'wave_point.output.ps'
NOWAVE - don't produce a wavelet transform, just return
the time series as an output.
CALLS:
ECLIPS2, so you need the WAVELET, WAVE_SIGNIF and ECLIPS_FILTER
routines in your path; TVIM, too.
HISTORY:
version 0.5, 14/08/00, D.Williams.
(See /home/drw/idl/secis/wave_point2aw.pro)
WAVE_POINT2B
[Previous Routine]
[Next Routine]
[List of Routines]
PRO WAVE_POINT2A,data,series,print=print,nowave=nowave
PURPOSE:
To generate a time series and wavelet transform of the
intensity in a particular pixel in an image sequence
(cube) of the SECIS data. Currently in a very early,
sole-user version. To be upgraded and made more generic.
INPUT:
DATA - image cube containing the pixel you want to monitor
OUTPUT:
SERIES - the output time series, so you can re-run eclips2
on it at a later stage to get the wavelet transform.
KEYWORDS:
PRINT - send the output wavelet transform to a file named
'wave_point.output.ps'
NOWAVE - don't produce a wavelet transform, just return
the time series as an output.
CALLS:
ECLIPS2, so you need the WAVELET, WAVE_SIGNIF and ECLIPS_FILTER
routines in your path; TVIM, too.
HISTORY:
version 0.5, 14/08/00, D.Williams.
(See /home/drw/idl/secis/wave_point2b.pro)
WAVE_POINT3
[Previous Routine]
[Next Routine]
[List of Routines]
PRO WAVE_POINT3,data,series,arrayname=arrayname,print=print,nowave=nowave
PURPOSE:
To generate a time series and wavelet transform of the
intensity in a particular pixel in an image sequence
(cube) of the SECIS data. Currently in a very early,
sole-user version. To be upgraded and made more generic.
INPUT:
DATA - image cube containing the pixel you want to monitor
ARRAYNAME - name to be included in the title of the
main window in the plot, e.g. arrayname='loop1801'
OUTPUT:
SERIES - the output time series, so you can re-run eclips2
on it at a later stage to get the wavelet transform.
KEYWORDS:
PRINT - send the output wavelet transform to a file named
'wave_point.output.ps'
NOWAVE - don't produce a wavelet transform, just return
SERIES as an output.
CALLS:
ECLIPS2, so you need the WAVELET, WAVE_SIGNIF and ECLIPS_FILTER
routines in your path; TVIM, too.
EXAMPLE CALLING SEQUENCE:
wave_point3,data,outputseries,arrayname='loop1801',/nowave
HISTORY:
version 0.5, 14/08/00, D.Williams.
(See /home/drw/idl/secis/wave_point3.pro)
WAVE_SIGNIF
[Previous Routine]
[Next Routine]
[List of Routines]
NAME: WAVE_SIGNIF
PURPOSE: Compute the significance levels for a wavelet transform.
CALLING SEQUENCE:
result = WAVE_SIGNIF(y,dt,scale,sigtest)
INPUTS:
Y = the time series, or, the VARIANCE of the time series.
(If this is a single number, it is assumed to be the variance...)
DT = amount of time between each Y value, i.e. the sampling time.
SCALE = the vector of scale indices, from previous call to WAVELET.
SIGTEST = 0, 1, or 2. If omitted, then assume 0.
If 0 (the default), then just do a regular chi-square test,
i.e. Eqn (18) from Torrence & Compo.
If 1, then do a "time-average" test, i.e. Eqn (23).
In this case, DOF should be set to NA, the number
of local wavelet spectra that were averaged together.
For the Global Wavelet Spectrum, this would be NA=N,
where N is the number of points in your time series.
If 2, then do a "scale-average" test, i.e. Eqns (25)-(28).
In this case, DOF should be set to a
two-element vector [S1,S2], which gives the scale
range that was averaged together.
e.g. if one scale-averaged scales between 2 and 8,
then DOF=[2,8].
OUTPUTS:
result = significance levels as a function of SCALE,
or if /CONFIDENCE, then confidence intervals
OPTIONAL KEYWORD INPUTS:
MOTHER = A string giving the mother wavelet to use.
Currently, 'Morlet','Paul','DOG' (derivative of Gaussian)
are available. Default is 'Morlet'.
PARAM = optional mother wavelet parameter.
For 'Morlet' this is k0 (wavenumber), default is 6.
For 'Paul' this is m (order), default is 4.
For 'DOG' this is m (m-th derivative), default is 2.
LAG1 = LAG 1 Autocorrelation, used for SIGNIF levels. Default is 0.0
SIGLVL = significance level to use. Default is 0.95
DOF = degrees-of-freedom for signif test.
IF SIGTEST=0, then (automatically) DOF = 2 (or 1 for MOTHER='DOG')
IF SIGTEST=1, then DOF = NA, the number of times averaged together.
IF SIGTEST=2, then DOF = [S1,S2], the range of scales averaged.
Note: IF SIGTEST=1, then DOF can be a vector (same length as SCALEs),
in which case NA is assumed to vary with SCALE.
This allows one to average different numbers of times
together at different scales, or to take into account
things like the Cone of Influence.
See discussion following Eqn (23) in Torrence & Compo.
GWS = global wavelet spectrum. If input then this is used
as the theoretical background spectrum,
rather than white or red noise.
CONFIDENCE = if set, then return a Confidence INTERVAL.
For SIGTEST=0,2 this will be two numbers, the lower & upper.
For SIGTEST=1, this will return an array (J+1)x2,
where J+1 is the number of scales.
OPTIONAL KEYWORD OUTPUTS:
PERIOD = the vector of "Fourier" periods (in time units) that corresponds
to the SCALEs.
FFT_THEOR = output theoretical red-noise spectrum as fn of PERIOD.
(See /home/drw/idl/secis/wavelet/wave_signif.pro)
WAVE_SPEEDS
[Previous Routine]
[Next Routine]
[List of Routines]
A routine to calculate kink and slow magento-acoustic wave speeds
given the appropriate parameters, as per Roberts (2000, SolPhys,
193, 139-152)
(See /home/drw/idl/gen/wave_speeds.pro)
WAVE_SPEEDS_COMM
[Previous Routine]
[Next Routine]
[List of Routines]
A routine to calculate kink and slow magento-acoustic wave speeds
given the appropriate parameters, as per B. Roberts (2000, SolPhys,
193, 139-152)
This wave_speeds_comm just allows you to specify the parameters
on the command line to speed things up a wee bit
(See /home/drw/idl/gen/wave_speeds_comm.pro)
WAVE_SPEEDS_FS
[Previous Routine]
[Next Routine]
[List of Routines]
The previous spec, for WAVE_SPESDS, is below:
=================
A routine to calculate kink and slow magento-acoustic wave speeds
given the appropriate parameters, as per B. Roberts (2000, SolPhys,
193, 139-152)
WAVE_SPEEDS_COMM just allows you to specify the parameters
on the command line to speed things up a wee bit
=================
...whereas this version takes its fast mode speed from Y.-M. Wang's
paper on 'EIT waves', 2000, ApJ, 543, L89
where you get the fast mode speed in general given by
(LaTeX form)
$v_f^2 = \frac{1}{2} ( v_a^2 + c_s^2 + \sqrt{(v_a^2 + c_s^2)^2 - 4v_a^2c_s^2cos^2\delta})$
(See /home/drw/idl/gen/wave_speeds_fs.pro)
WAVE_SPEEDS_FS_COMM
[Previous Routine]
[Next Routine]
[List of Routines]
The previous spec, for WAVE_SPEEDS, is below:
=================
A routine to calculate kink and slow magento-acoustic wave speeds
given the appropriate parameters, as per B. Roberts (2000, SolPhys,
193, 139-152)
WAVE_SPEEDS_COMM just allows you to specify the parameters
on the command line to speed things up a wee bit
=================
...whereas this version takes its fast mode speed from Y.-M. Wang's
paper on 'EIT waves', 2000, ApJ, 543, L89
where you get the fast mode speed in general given by
(LaTeX form)
$v_f^2 = \frac{1}{2} ( v_a^2 + c_s^2 + \sqrt{(v_a^2 + c_s^2)^2 - 4v_a^2c_s^2cos^2\delta})$
==================================
USAGE
wave_speeds_fs_comm,logTe,logNe0,logNee,B0,Be,delta_angle,vfast,valf,csound,beta0,betae
EXAMPLE:
wave_speeds_fs_comm,6.45,8.9,8.0,8,1,0.,vf,va,vae,cs,beta0,betae
wave_speeds_fs_comm,6.45,8.9,8.0,24.6,1,0.,vf,va,vae,cs,beta0,betae
(See /home/drw/idl/gen/wave_speeds_fs_comm.pro)
WBBASIS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WBBASIS
PURPOSE:
To find the best basis using the Coifman-Wickerhauser Best-Basis Algorithm.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
btree = WBBASIS(tree,D,vtree)
INPUTS:
tree = stat-tree (output by WSTATREE)
D = maximum depth of tree-search
OUTPUTS:
vtree = value of components of best basis
vtree(1) holds value of best basis
RESTRICTIONS:
None.
EXAMPLE:
SEE ALSO:
wstatree
NOTICE:
Yale University has filed a patent application for this algorithm.
Commercial Development based on this algorithm should
be cleared by Yale University. Contact them for liscensing information.
MODIFICATION HISTORY:
Written by: Amara Graps December 1994/September1995
Translated from MatLab Wavelab routine: bestbasis.m
(See /home/drw/idl/wwbsrc/wbbasis.pro)
WCALCEPS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WCALCEPS
PURPOSE:
To compute the distance between 1.0 and the next
largest floating point number. The output is the
equivalent of Matlab's system "eps" variable.
CATEGORY:
Numerical Precision
CALLING SEQUENCE:
WCALCEPS, eps
INPUTS:
None.
OUTPUTS:
eps = the distance between 1.0 and the next
largest single precision floating point number.
NOTES:
This eps value is useful for testing for round-off
tolerance. Discussion of this variable is in:
_Numerical Methods for Physicists_ by Alejandro
Garcia, Prentice-Hall, 1994.
MODIFICATION HISTORY:
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wcalceps.pro)
WCALCMRA
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WCALCMRA
PURPOSE:
This procedure calculates a multi-resolution without the plot.
It is used for testing purposes only as it only calculcates the
first dyad level.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
mra = WCALCMRA(sig, LD, QMF)
INPUTS:
sig: 1-d signal array
LD: lowest level resolution
QMF: Quadrature Mirror Filter
OUTPUTS:
mra: mra array.
EXAMPLE:
Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
Call multi-resolution
IDL> mra = WCALCMRA(sig, LD, QMF)
MODIFICATION HISTORY:
Written by: Amara Graps February 1996
(See /home/drw/idl/wwbsrc/wcalcmra.pro)
WCALCSCG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WCALCSCG
PURPOSE:
This procedure calculates a scalegram. The scalegram is
the wavelet analog of the power spectrum. It is just the (squared)
wavelet coefficient averaged over all location index values at a
fixed value of the scale index. The sums of squares --> scalegram
flat if input = white noise
CATEGORY:
Wavelets.
CALLING SEQUENCE:
sg = WCALCSCG(sig, QMF)
INPUTS:
sig: 1-d signal array
QMF: Quadrature Mirror Filter
OUTPUTS:
sg: scalegram.
EXAMPLE:
Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
Call scalegram
IDL> sg = WCALCSCG(sig, QMF)
MODIFICATION HISTORY:
Written by: Amara Graps February 1996
(See /home/drw/idl/wwbsrc/wcalcscg.pro)
WCOMBINE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WCOMBINE
PURPOSE:
To combine all elements in a matrix, like Matlab's "(:)".
CATEGORY:
Simple math.
CALLING SEQUENCE:
Result = WCOMBINE(A)
INPUTS:
A: A matrix
OUTPUTS:
The matrix turned into a column with all elements combined.
SIDE EFFECTS:
If A is an array, it is left unchanged.
RESTRICTIONS:
None.
EXAMPLE:
IDL>p = [[2,3],[4,5],[6,7]]
IDL>print, p
2 3
4 5
6 7
IDL>print, WCOMBINE(p)
2
4
6
3
5
7
MODIFICATION HISTORY:
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wcombine.pro)
WCUMSUM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WCUMSUM
PURPOSE:
To sum all of the elements in an array or matrix.
If A is a matrix, then sum(A) is a row vector with
the sum over each previous element in the column. This
function is an equivalent of Matlab's cumsum function.
CATEGORY:
Simple math.
CALLING SEQUENCE:
Result = WCUMSUM(A)
INPUTS:
A: A vector or matrix
OUTPUTS:
The cumulative sum of the vector or matrix.
RESTRICTIONS:
None.
EXAMPLE:
>a = [[8,2,6],[3,6,7],[4,9,3]]
>print, a
8 2 6
3 6 7
4 9 3
>print, WCUMSUM(a)
8.000 2.000 6.000
11.000 8.000 13.000
15.000 17.000 16.000
EXAMPLE:
>a = [1, 2, 3, 4 5, 6, 7, 8, 9, 10]
>print, WCUMSUM(a)
1 3 6 10 15 21 28 36 45 55
MODIFICATION HISTORY:
Amara Graps, September 1995
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wcumsum.pro)
WDELETEALL
[Previous Routine]
[Next Routine]
[List of Routines]
delete all windows
(See /home/drw/idl/esrg/wdeleteall.pro)
WDETREND
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDETREND
PURPOSE:
To remove a linear bias from the "sig" data array.
CATEGORY:
Wavelets
CALLING SEQUENCE:
out = WDETREND(sig)
INPUTS:
sig = current data array/signal
OUTPUTS:
out = now detrended data array/signal
TT = 'I' if image and 'S' if signal
EXAMPLE
IDL> ;Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
IDL> tt = 'S' if 1D dataset or tt = 'I' if 2D dataset
IDL> ;Detrend dataset
IDL> sig = WDETREND(sig, tt)
IDL> See the detrended data
IDL> If tt EQ 'S' then WPLOTIT, st, 1, sig ELSE WPLOTIT, st, 10, sig
MODIFICATION HISTORY:
Amara Graps September 1995.
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wdetrend.pro)
WDNDYDHI
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDNDYDHI
PURPOSE:
This function performs a Hi-Pass Downsampling operation.
(periodized).
CATEGORY:
Wavelets
CALLING SEQUENCE:
d = WDNDYDHI(x,f)
INPUTS:
x: 1-d signal at fine scale.
f: filter
OUTPUTS:
y: 1-d signal at coarse scale.
EXAMPLE:
SEE ALSO:
wdndydlo, wupdydhi, wupdydlo, wfwtpo, wiconv
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: downdyadhi.m
(See /home/drw/idl/wwbsrc/wdndydhi.pro)
WDNDYDLO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDNDYDLO
PURPOSE:
This function performs a Lo-Pass Downsampling operation.
(periodized).
CATEGORY:
Wavelets
CALLING SEQUENCE:
d = WDNDYDLO(x,f)
INPUTS:
x: 1-d signal at fine scale.
f: filter
OUTPUTS:
y: 1-d signal at coarse scale.
EXAMPLE:
SEE ALSO:
wdndydhi, wupdydhi, wupdydlo, wfwtpo, waconv
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: downdyadlo.m
(See /home/drw/idl/wwbsrc/wdndydlo.pro)
WDODWT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDODWT
PURPOSE:
This procedure performs a discrete wavelet transform and plots the coefficients.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WDODWT, X_work, QMF, LD, plotwin, wc
INPUTS:
X_work: 1-d signal array
QMF: Quadrature Mirror Filter
LD: lowest resolution level
st: signal title
plotwin: plot window to plot into
OUTPUTS:
wc = the array of wavelet coefficients
The discrete wavelet transform coeffs plotted to the screen.
SEE ALSO:
wintwave (necessary for this procedure to get QMF)
EXAMPLE:
Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
Calculate Discrete Wavelet Transform
IDL> WDODWT, sig, QMF, LD, st, 3, wc
MODIFICATION HISTORY:
Written by: Amara Graps August/September, 1995
(See /home/drw/idl/wwbsrc/wdodwt.pro)
WDOFILT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOFILT
PURPOSE: This procedure defines the quadrature mirror filter used for
all subsequent computations.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WDOFILT, WaveType, ParVal, QMF
INPUTS:
WaveType: String of choices: Haar, Daubechies, Coiflet, Symmlet
ParVal: Parameter value for a specific wavelet
OUTPUTS:
QMF: Quadrature Mirror Filter Defined
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
(See /home/drw/idl/wwbsrc/wdofilt.pro)
WDOMRA
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOMRA
PURPOSE:
This procedure performs a multi-resolution depiction
of the data or signal.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WDOMRA
INPUTS: (via COMMON)
sig: 1-d signal array
QMF: Quadrature Mirror Filter
st: signal title
LD = multiresolution scale
OUTPUTS:
The discrete wavelet transform coeffs plotted to the screen.
COMMON BLOCKS:
COMMON WWB_COMMON, $
TEXT_ANNOUNCE, wd, sig, len, st, noise_type, noise_lev, $
QMF, LD, shrinkage_type, WaveType, ParVal
SEE ALSO:
wintwave (necessary for this procedure to get QMF)
EXAMPLE:
IDL> ;Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
IDL> ;Call Multi-resolution analysis
IDL> WDOMRA
MODIFICATION HISTORY:
Written by: Amara Graps August/September, 1995
(See /home/drw/idl/wwbsrc/wdomra.pro)
WDOSCEG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOSCEG
PURPOSE:
This procedure generates a scalegram and plots it. The scalegram is
the wavelet analog of the power spectrum. It is just the (squared)
wavelet coefficient averaged over all location index values at a
fixed value of the scale index. The sums of squares --> scalegram
flat if input = white noise
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WDOSCEG
INPUTS: (via COMMON)
X_work: 1-d signal array
QMF: Quadrature Mirror Filter
OUTPUTS:
The scalegram plotted to the screen.
COMMON BLOCKS:
COMMON WWB_COMMON, $
TEXT_ANNOUNCE, wd, sig, len, st, noise_type, noise_lev, $
QMF, LD, shrinkage_type, WaveType, ParVal
COMMON Wave_color, $
max_color, max_image, $
white, yellow, lavender, aqua, pink, green, red, orange, blue, $
lt_gray, med_green, brown, olive, purple, dk_gray, black
SEE ALSO:
wintwave (necessary for this procedure)
EXAMPLE:
Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
Call scalegram
IDL> WDOSCEG
NOTES
We prefer to use the Haar wavelet because:
1. it is the only one that you can use down to the "finest
scale" ... i.e., width of wavelet = 2 X sampling interval.
2. No worries about end-effects (i.e. no wavelet sticking out
over the ends of the data!)
3. The correction of the resulting scalegram has a very simple
form ( = mean counting rate) for Poisson statistics in the data.
For noisy data, the discontinuity and nondifferentiability
of the Haar wavelet don't seem to be important deficiencies.
MODIFICATION HISTORY:
Written by: Amara Graps August 1995 - January 1996
Translated from MatLab Wavelab routine: do_scalegram.m
(See /home/drw/idl/wwbsrc/wdosceg.pro)
WDOSCOG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOSCOG
PURPOSE:
This procedure generates a scalogram and plots it. The scalogram is
a moderately well-established term for (a plot usually, of) the wavelet
coefficients as a function of the two independent variables, or indices
in the discrete case, scale and location. It is common to use the absolute
value, or even the log of the absolute value in practice. This imple-
mentation uses the output coefficients from the discrete wavelet
transform in a surface plot representation.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WDOSCOG
INPUTS: (via COMMON)
X_work: 1-d signal array
QMF: Quadrature Mirror Filter
OUTPUTS:
The scalegram plotted to the screen.
COMMON BLOCKS:
COMMON WWB_COMMON, $
TEXT_ANNOUNCE, wd, sig, len, st, noise_type, noise_lev, $
QMF, LD, shrinkage_type, WaveType, ParVal
EXAMPLE:
Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
Call scalogram
IDL> WDOSCOG
SEE ALSO:
wintwave (necessary for this procedure)
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
(Translated from Donoho, Scargle et al's MatLab Wavelab routines.)
(See /home/drw/idl/wwbsrc/wdoscog.pro)
WDOSGLEN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOSGLEN
PURPOSE:
To resize the "sig" data array (if it exists) or set it for future
purposes.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WDOSGLEN
INPUTS: (via COMMON)
sig = current data array/signal resized (if it exists)
OUTPUTS:
out = now wdetrended data array/signal
TT = 'I' if image and 'S' if signal
COMMON BLOCKS:
COMMON WWB_COMMON, $
TEXT_ANNOUNCE, wd, sig, len, st, noise_type, noise_lev, $
QMF, LD, shrinkage_type, WaveType, ParVal
MODIFICATION HISTORY:
Amara Graps September 1995.
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wdosglen.pro)
WDOSHRNK
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOSHRNK
PURPOSE:
This procedure denoises a time series, using wavelet shrinkage,
and plots the result. The time series is the working dataset,
the wavelet is the current one selected, and the shrinkage method
is the one chosen under the Wavelet Workbench Settings: DeNoising
Threshold.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WDOSHRNK
NECESSARY INPUTS (via COMMON)
sig: 1-d signal array
QMF: Quadrature Mirror Filter
LD: Coarseness level (set by WINTWAVE)
st: signal title
noise_lev: noise level (set by NoLev procedure, =0 by default)
noise_type: noise type (set by NoType procedure,
1, 2 or 3 = Normal, Uniform, Poisson, =1 by default)
shrinkage_type: shrinkage method (set by Threshold procedure, =1 by default)
1 = VisuThresh
2 = MultiHybrid
3 = MultiMAD
4 = MinMaxThresh
5 = WPDeNoise
WaveType: Wavelet Type: 'Haar', 'Daubechies', 'Coiflet', 'Symmlet'
ParVal: Parameter Value of the above wavelet, specific for the
wavelet. For:
WaveType = 'Haar'
ParVal = 1
WaveType = 'Daubechies'
ParVal = 4 or 6
WaveType = 'Coiflet'
ParVal = 2 or 3
WaveType = 'Symmlet'
ParVal = 6 or 8
OUTPUTS:
The denoised time series is plotted to the screen.
SEE ALSO:
wintwave (necessary for this procedure)
EXAMPLE:
IDL> ;Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
IDL> ;Need to normalize first, if working with natural data)
IDL> sig = WNNOISE(sig,QMF, tt)
IDL> If tt EQ `S' then WPLOTIT, st, 1, sig
IDL> WDOSHRNK
MODIFICATION HISTORY:
Written by: Amara Graps September-November 1995
Translated from MatLab Wavelab routine: do_shrinkage.m
(See /home/drw/idl/wwbsrc/wdoshrnk.pro)
WDOWAVE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOWAVE
PURPOSE:
This procedure calls the MakeWavelet procedure and plots the result.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WDOWAVE, WaveType, ParVal
INPUTS:
WaveType: Type of Wavelet: 'Haar' 'Daubechies' 'Coiflet' 'Symmlet'
ParVal: Parameter value corresponding to the wavelet
OUTPUTS:
A simple wavelet plot.
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
(See /home/drw/idl/wwbsrc/wdowave.pro)
WDOWPA
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOWPA
PURPOSE:
This procedure performs a wave packet analysis
of the data or signal.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WDOWPA
INPUTS: (via COMMON)
sig: 1-d signal array
QMF: Quadrature Mirror Filter
st: signal title
OUTPUTS:
A wavelet packet decomposition, an entropy drop tree,
and a phase plane all plotted to the screen in different
windows.
COMMON BLOCKS:
COMMON WWB_COMMON, $
TEXT_ANNOUNCE, wd, sig, len, st, noise_type, noise_lev, $
QMF, LD, shrinkage_type, WaveType, ParVal
SEE ALSO:
wintwave (necessary for this procedure to get QMF)
EXAMPLE:
IDL> ;Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
IDL> ;Call Wavelet Packet Analysis
IDL> WDOWPA
MODIFICATION HISTORY:
Written by: Amara Graps August/Sepember, 1995
(See /home/drw/idl/wwbsrc/wdowpa.pro)
WDOWPC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOWPC
PURPOSE:
This procedure performs a wave packet compression
of the data or signal. It is mainly for test purposes
to make sure everything works correctly before implementing
an equivalent wavelet packet compression to 'WDOWTC.pro'
which will contain buttons, sliders, thresholds etc.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WDOWPC
INPUTS: (via COMMON)
sig: 1-d signal array
QMF: Quadrature Mirror Filter
st: signal title
OUTPUTS:
A wavelet packet decomposition, an entropy drop tree,
and a phase plane all plotted to the screen in different
windows.
COMMON BLOCKS:
COMMON WWB_COMMON, $
TEXT_ANNOUNCE, wd, sig, len, st, noise_type, noise_lev, $
QMF, LD, shrinkage_type, WaveType, ParVal
COMMON WPC_common, FSLID1, BUTTON1, BUTTON2, BUTTON17, $
wpcoef, btree, wcwmnsort, thr, threshslider
SEE ALSO:
WINTWAVE (necessary for this procedure to get QMF)
EXAMPLE:
IDL> ;Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
IDL> ;Call Wavelet Packet Compression
IDL> WDOWPC
MODIFICATION HISTORY:
Written by: Amara Graps Sepember, 1995
(See /home/drw/idl/wwbsrc/wdowpc.pro)
WDOWTC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDOWTC
PURPOSE:
This procedure sets up runs a simple event loop for
the Wavelet Transform Compression action. It is part
of the Wavelet Workbench functions.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WDOWTC
INPUTS: (via COMMON)
sig: 1-d signal array
QMF: Quadrature Mirror Filter
st: signal title
OUTPUTS:
This procedure runs the wavelet data input as well as the actions
performed on the data.
EXAMPLE:
IDL> ;Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
IDL> ;Call Wavelet Transform Compression
IDL> WDOWTC
COMMON BLOCKS:
TEXT_ANNOUNCE: The block for passing the widget that present
messages as well as other important wavelet parameters such
as the data array (sig), the data array length(len), a string
describing the data (st) and the current chosen quadrature mirror
filter (QMF).
COMMON WTC_common, The block for the two sliders (FSLID3, FSLID4)
the four buttons (BUTTON4, BUTTON5, , BUTTON8, BUTTON9) and
array of wavelet coeffs (wc), sorted array of wavelet coeffs (wcwmnsort),
threshold value (thr), the max number of coeffs (n), the current
value of the sliders (threshslider, numslider), and the coarsest
level for the wavelet transform (Coarse)
MODIFICATION HISTORY:
Written by: Amara Graps, August/September 1995.
(See /home/drw/idl/wwbsrc/wdowtc.pro)
WDYAD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDYAD
PURPOSE:
This function indexes entire j-th dyad of 1-d wavelet xform.
CATEGORY:
Wavelets
CALLING SEQUENCE:
i = WDYAD(j)
INPUTS:
j: integer
OUTPUTS:
i: integer list (array) of all indices of wavelet coeffts at j-th level
RESTRICTIONS:
EXAMPLE:
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: dyad.m
(See /home/drw/idl/wwbsrc/wdyad.pro)
WDYAD2IX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDYAD2IX
PURPOSE:
This function converts wavelet indexing into linear indexing..
CATEGORY:
Wavelets
CALLING SEQUENCE:
ix = WDYAD2IX(j,k)
INPUTS:
j: Resolution Level. j>= 0.
k: Spatial Position. 0 <= k < 2^j.
OUTPUTS:
ix = index in linear 1-d wavelet transform array where
the (j,k) wavelet coefft. is stored
EXAMPLE:
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: dyad2ix.m
(See /home/drw/idl/wwbsrc/wdyad2ix.pro)
WDYADLNG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WDYADLNG
PURPOSE:
This function finds length and dyadic length of an array.
CATEGORY:
Wavelets
CALLING SEQUENCE:
n = WDYADLNG(x,J)
INPUTS:
x: array of length n = 2^J (hopefully)
OUTPUTS:
n: length(x)
J: least power of two greater than n
SIDE EFFECTS:
A warning is issued if n is not a power of 2.
EXAMPLE:
SEE ALSO:
wquadlen, wdyad, wdyad2ix
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: dyadlength.m
(See /home/drw/idl/wwbsrc/wdyadlng.pro)
WFPTWP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WFPTWP
PURPOSE:
This function analyzes an image into specific wavelet packet basis.
CATEGORY:
Wavelets
CALLING SEQUENCE:
coef = WFPTWP(basis,x,qmf)
INPUTS:
basis: tree selecting wavelet packet basis
x: 1-d image to be transformed into basis
qmf: quadrature mirror filter
OUTPUTS:
coef 1-d wavelet packet coeffts in given basis
EXAMPLE:
MODIFICATION HISTORY:
Written by: Amara Graps December, 1994
Translated from MatLab Wavelab routine: fpt_wp.m
(See /home/drw/idl/wwbsrc/wfptwp.pro)
WFUSEHIST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WFUSEHIST
PURPOSE:
This procedure creates a FUSE raw histogram file and writes a histogram
to it. The header can include information from a pre-existing header
which is passed, or a brand new header can be generated. It creates
a dummy of SIA table which includes the entire detector.
CATEGORY:
FITS.
CALLING SEQUENCE:
WFUSEHIST, Histogram, Filename, Fheader [,Header]
INPUTS:
Histogram:
The histogram to write to the file.
Fheader:The existing FITS primary header.
Filename:
Name of output FITS file.
KEYWORD PARAMETERS:
ADDKEY: Structure containing keywords to add to the primary header.
The format is a Nx3 string array. This procedure converts
numbers to strings before writing the file.
REMKEY: String containing a list of FITS keywords to remove from the
primary header.
NEW: If set, ignores fheader and creates a new one from scratch.
OPTIONAL OUTPUTS:
Header: Primary header for new file.
EXAMPLE:
To read in exposure I818020701 1A, shift the entire spectrum by
25 pixels in x, and write it back out as a valid histogram file
called 'modified.fit', do the following:
data = readit('I81802070011ahistfraw.fit',fheader=fheader)
data = shift(data,25,0)
wfusehist, data, 'modified.fit', fheader
MODIFICATION HISTORY:
Written by David Sahnow based on WHISTFITS.PRO, 4 February 2000.
7 February 2000 Added check that input data is a BYTE, INT, or LONG.
3 May 2000 Corrected documentation.
24 May 2000 Replaced call to WRITEFITS with MWRFITS when creating
the FITS file.
6 September 2000 Now forces FILETYPE and INSTMODE keywords to be
those appropriate for a histogram.
(See /home/drw/idl/fuse/fuse_idl_utilities_110600/wfusehist.pro)
WFWT2PO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WFWT2PO
PURPOSE:
This function performs a 2-dimensional wavelet transform (periodized, orthonormal).
CATEGORY:
Wavelets
CALLING SEQUENCE:
wc = WFWT2PO(x,L,qmf)
INPUTS:
x: 2-d image (n by n array, n dyadic)
L: coarse level
qmf: quadrature mirror filter
OUTPUTS:
wc: 2-d wavelet transform
NOTES:
A two-dimensional Wavelet Transform is computed for the
array x. To reconstruct, use WIWT2PO.
EXAMPLE:
SEE ALSO:
wiwt2po, wmkofilt
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: fwt2_po.m
(See /home/drw/idl/wwbsrc/wfwt2po.pro)
WFWTPO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WFWTPO
PURPOSE:
This function generates a Forward Wavelet Transform
(periodized, orthonormal).
CATEGORY:
Wavelets
CALLING SEQUENCE:
wc = WFWTPO(x,L,qmf)
INPUTS:
x: 1-d signal; length(x) = 2^J
L: Coarsest Level of V_0; L << J
qmf: quadrature mirror filter (orthonormal)
[qmf defines wavelet shape]
OUTPUTS:
wc: 1-d wavelet transform of x.
[Gives wavelet coefficients]
NOTES:
1. QMF filter may be obtained from WMKOFILT
2. usually, length(qmf) lt 2^(L+1)
3. To reconstruct use WIWTPO
EXAMPLE:
SEE ALSO:
wiwtpo, wmkofilt
NOTES on j, k:
The location k, at level j, runs from 0 to 2^j-1.
A signal of length n is taken to a set of n wavelet coefficients
by the (orthogonal) wavelet transformation. Since the wavelet
coefficients are indexed in a dyadic way due to the natural
location/scale interpretation inherent with wavelets, you cannot
pick a {j,k} combination that doesn't exist for the transformed data.
Consequently j ranges as above and k can be at most log_2(n).
The wavelet transformation is not over-complete (i.e., it takes a
signal of length n to a set of coefficients of length n).
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: fwt_po.m
(See /home/drw/idl/wwbsrc/wfwtpo.pro)
WGETSIZE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WGETSIZE
PURPOSE:
To determine from a matrix or array, the ncol and nrow..
CATEGORY:
Simple array typing.
CALLING SEQUENCE:
ncol = WGETSIZE(Array nrow)
INPUTS:
Array: array we wish to find ncol and nrow from
OUTPUTS:
nrow: number of rows
ncol: number of columns
EXAMPLE:
IDL> a=[[1,2,3],[4,5,6]]
IDL> print, a
1 2 3
4 5 6
IDL> ncol=WGETSIZE(a, nrow)
IDL> print, ncol
3
IDL> print, nrow
2
IDL> b=[1,2,3,4,5,6,7]
IDL> print, b
1 2 3 4 5 6 7
IDL> ncol=WGETSIZE(b, nrow)
IDL> print, ncol
7
IDL> print, nrow
1
MODIFICATION HISTORY:
Amara Graps September 1995.
(c) copyright Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wgetsize.pro)
WGETUSER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WGETUSER
PURPOSE:
This procedure goes to the two folders within the WWB folder that may or
may not contain user-defined data and returns two string arrays that
contain the titles of the files. The two folders that this function
checks are: 'u1ddata' and 'u2ddata'. If file(s) are in
'u1ddata'/'u2ddata', then the user1d/user2D string array returns
strings that precede the '.doc' filenames.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WGETUSER, wd, user1d, user2d, nf1, nf2
INPUTS:
wd = working directory (string)
OUTPUTS:
user1d = string array containing user-defined titles
of the 1d files
user2d = string array containing user-defined titles
of the 2d files.
nf1 = number of 1D user-defined files
nf2 = number of 2D user-defined files
EXAMPLE:
MODIFICATION HISTORY:
Written by: Amara Graps September, 1995
Updated by Amara Graps March 1996 to handle VMS paths/filenames
(See /home/drw/idl/wwbsrc/wgetuser.pro)
WHARDTHR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WHARDTHR
PURPOSE:
This function applies a hard threshold.
CATEGORY:
Wavelets
CALLING SEQUENCE:
x = WHARDTHR(y,t)
INPUTS:
y : Noisy Data
t : Threshold
OUTPUTS:
x : y 1_{|y|>t}
SEE ALSO:
wsoftthr, wdoshrnk
MODIFICATION HISTORY:
Written by: Amara Graps December, 1994
Translated from MatLab Wavelab routine: hardthresh.m
(See /home/drw/idl/wwbsrc/whardthr.pro)
WHERE_NEGZERO()
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WHERE_NEGZERO()
PURPOSE:
Find positions of IEEE -0.0 values.
EXPLANATION :
Finds the positions of all values within an array that correspond to the
IEEE value -0.0, as determined from the bit pattern. Prior to IDL V5.1,
the VMS operating system had trouble coping with these values. If using
any other operating system, then no action is performed.
CALLING SEQUENCE:
Result = WHERE_NEGZERO( ARRAY [, COUNT, /QUIET ] )
INPUTS:
ARRAY = Array to test against the IEEE -0.0 value. Must be
either floating point or double-precision.
OUTPUTS:
The result of the function is the indices of all values of
ARRAY corresponding to the IEEE -0.0 value, similar to the IDL
WHERE function.
OPTIONAL OUTPUT:
COUNT = Number of values found corresponding to IEEE -0.0.
OPTIONAL INPUT KEYWORD:
/QUIET = If set, then warning messages are not printed out.
RESTRICTIONS:
ARRAY must be of type float or double-precision.
SIDE EFFECTS:
If no -0.0 values are found, or if ARRAY is not of type float,
or double precision, or if the operating system is something
other than VMS, then -1 is returned, and COUNT is set to 0.
REVISION HISTORY:
Written, 31-Jan-1997, William Thompson, GSFC
Converted to IDL V5.0 W. Landsman September 1997
(See /home/drw/idl/aux/markwardt/where_negzero.pro)
WHICH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
which
PURPOSE: Prints a list of all directory pathnames which match a
given idl procedure name. The directory precedence is
set by the system variable !path. The file name may
contain any wild card characters understood by the
operating system. In the case that a given procedure
is found in more than one directory, the first listed
pathname is the one compiled by the IDL interpreter in
response to a .run statement.
USEAGE: which,filename
INPUT:
filename name of idl procedure (may include wild cards)
KEYWORD INPUT: none
OUTPUT: none
EXAMPLE:
which,'str*' ; produces this output:
/home/paul/idl/esrg/strip_fn.pro
/home/paul/idl/esrg/strmatch.pro
/home/paul/idl/esrg/strpack.pro
/home/paul/idl/esrg/strwhere.pro
/local/idl/lib/color/stretch.pro
/local/idl/lib/prog/str_sep.pro
AUTHOR: Paul Ricchiazzi 19 Nov 97
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/which.pro)
WHYBRTHR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WHYBRTHR
PURPOSE:
To perform Shrinkage to Wavelet Coefficients via
Adaptive Threshold Selection Using Principle of Stein's
Unbiased Risk Estimate Variant without Rigorous Proof
CATEGORY:
Wavelets.
CALLING SEQUENCE:
xhat = WHYBRTHR(Y)
INPUTS:
y : Noisy Data with Std. Deviation = 1
OUTPUTS:
xhat : Estimate of mean vector
EXAMPLE:
NOTES:
See Donoho, D.L. and Johnstone, I.M. ``Adapting
to Unknown Smoothness by Wavelet Shrinkage''
SEE ALSO:
wmhybrid, wdoshrnk
MODIFICATION HISTORY:
Written by: Amara Graps December, 1994
Translated from MatLab Wavelab routine: hybridthresh.m
(See /home/drw/idl/wwbsrc/whybrthr.pro)
WICONV
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WICONV
PURPOSE:
This function performs a Convolution for Two-Scale Transform.
CATEGORY:
Wavelets
CALLING SEQUENCE:
y = WICONV(f,x)
INPUTS:
f: filter.
x: 1-d signal.
OUTPUTS:
y: filtered result.
NOTES:
Filtering is a periodic convolution of x with f.
EXAMPLE:
SEE ALSO:
waconv, wupdydhi, wupdydlo, wdndydhi, wdndydlo
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: iconv.m
(See /home/drw/idl/wwbsrc/wiconv.pro)
WIDGET_CENTER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WIDGET_CENTER
PURPOSE:
Center an widget on the screen, or over an existing widget.
CATEGORY:
Widgets.
CALLING SEQUENCE:
WIDGET_CENTER, ID
INPUTS:
ID ID of the widget to be centered.
KEYWORD PARAMETERS:
PARENT ID of an existing widget over which
the widget should be centered.
OUTPUTS:
None.
EXAMPLE:
base = widget_base()
label = widget_label(base, value='Hello world')
widget_center, base
widget_control, base, /realize
MODIFICATION HISTORY:
Written by: Liam.Gumley@ssec.wisc.edu
$Id: widget_center.pro,v 1.2 1999/11/15 22:58:27 gumley Exp $
(See /home/drw/idl/esrg/widget_center.pro)
WIMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE WIMAGE
USEAGE: WIMAGE,a
WIMAGE,a,title=title,xtitle=xtitle,ytitle=ytitle,$
xrange=xrange,yrange=yrange,$
noframe=noframe,aspect
PURPOSE: Display an image with provisions for
1. plot title
2. annotated x and y axis
3. simplified OPLOT capability
INPUT a image quantity
Optional keyword input:
title plot title
xtitle x axis title
ytitle y axis title
xrange array spanning entire x axis range.
NOTE: WIMAGE only uses min(XRANGE) and max(XRANGE).
yrange array spanning entire y axis range.
NOTE: WIMAGE only uses min(YRANGE) and max(YRANGE).
aspect the x over y aspect ratio of the output image
if not set aspect is set to (size_x/size_y) of the
input image.
noframe if set do not draw axis box around image
PROCEDURE WIMAGE first determins the size of the plot data window
with a dummy call to PLOT. When the output device is
"X", CONGRID is used to scale the image to the size of
the available data window. Otherwise, if the output
device is Postscript, scaleable pixels are used in the
call to TV. PLOT draws the x and y axis and titles.
AUTHOR: Paul Ricchiazzi oct92
Earth Space Research Group, UCSB
Amara Graps, January 1995
Bay Area Environmental Research Institute/NASA-Ames
Adapted for WaveLab 0.6
(See /home/drw/idl/wwbsrc/wimage.pro)
WINFULL[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: winfull
PURPOSE: create full screen window
USEAGE: winfull
INPUT:
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 30 May 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/winfull.pro)
WINFULL[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: winfull
PURPOSE: create full screen window
USEAGE: winfull
INPUT:
KEYWORD INPUT:
OUTPUT:
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
AUTHOR: Paul Ricchiazzi 30 May 96
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/winfull.pro)
WINMEN
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: winmen
PURPOSE: set up a graphics window based button menu
USEAGE: winmen,nbt,blab ; set up button window
winmen_ev,nbt,ibt,mbt ; receive button values
INPUT:
nbt number of buttons
Optional INPUT:
blab button labels
KEYWORD INPUT:
OUTPUT:
ibt return value of selected button
mbt mouse button used to select menu button, lmb=1, mmb=2, rmb=4
DISCUSSION:
LIMITATIONS:
COMMON BLOCKS:
SIDE EFFECTS:
EXAMPLE:
winmen,3,['one','two','three']
winmen_ev,3,ibt & print,ibt
AUTHOR: Paul Ricchiazzi 12 Feb 99
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/winmen.pro)
WINTWAVE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WINTWAVE
PURPOSE:
This procedure generates a scalegram and plots it.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WINTWAVE, x_work, WType, Par, QMF, LD
INPUTS:
X_work: 1-d signal array
WType: Wavelet Type (string)
'Haar', 'Daubechies', 'Coiflet', 'Symmlet'
Par: Wavelet parameter depends on WType.
Options are:
'Haar'-->Par = 2
'Daubechies' -->Par = 4, 6
'Coiflet' -->Par = 2, 3
'Symmlet' -->par = 6, 8
OUTPUTS:
X_Work: truncated at 2^n length
QMF: Quadrature Mirror Filter
LD: Lowest resolution level
SEE ALSO:
wdosceg and many of the other ``do_" procedures
(They use the output from this procedure.)
MODIFICATION HISTORY:
Written by: Amara Graps August/September, 1995
(See /home/drw/idl/wwbsrc/wintwave.pro)
WIPTWP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WIPTWP
PURPOSE:
This function synthesizes a signal from wavelet packet
coefficients.
CATEGORY:
Wavelets
CALLING SEQUENCE:
x = WIPTWP(btree,coef,qmf)
INPUTS:
basis basis tree selecting wavelet packet basis
coef coefficients in that basis
qmf quadrature mirror filter
OUTPUTS:
x: 1-d signal reconstructed from coefficients
NOTES:
1. qmf filter may be obtained from WMKOFILT
2. usually, length(qmf) lt 2^(L+1)
EXAMPLE:
SEE ALSO:
wfptwp, wmkofilt
MODIFICATION HISTORY:
Written by: Amara Graps February, 1995
Translated from MatLab Wavelab routine: ipt_wp.m
(See /home/drw/idl/wwbsrc/wiptwp.pro)
WIWT2PO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WIWT2PO
PURPOSE:
This function performs an inverse 2-dimensional wavelet transform
(periodized, orthonormal).
CATEGORY:
Wavelets
CALLING SEQUENCE:
x = WIWT2PO(wc,L,qmf)
INPUTS:
wc: 2-d wavelet transform [n by n array, n dyadic]
L: coarse level
qmf: quadrature mirror filter
OUTPUTS:
x: 2-d signal reconstructed from wc.
NOTES:
If wc is the result of a forward 2d wavelet transform, with
wc = WFWT2PO(x,L,qmf) then x = WIWT2PO(wc,L,qmf) reconstructs
exactly if qmf is a nice quadrature mirror filter, e.g. one made
by WMKOFILT.
EXAMPLE:
SEE ALSO:
wfwt2po, wmkofilt
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: iwt2_po.m
(See /home/drw/idl/wwbsrc/wiwt2po.pro)
WIWTPO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WIWTPO
PURPOSE:
This function generates an Inverse Wavelet Transform
(periodized, orthonormal).
CATEGORY:
Wavelets
CALLING SEQUENCE:
x = WIWTPO(wc,L,qmf).
INPUTS:
wc: 1-d wavelet transform: length(wc)= 2^J.
L: Coarsest Level of V_0; L << J
qmf: quadrature mirror filter (orthonormal)
OUTPUTS:
x: 1-d signal reconstructed from wc.
NOTES:
1. qmf filter may be obtained from WMKOFILT
2. usually, length(qmf) lt 2^(L+1)
EXAMPLE:
SEE ALSO:
wfwtpo, wmkofilt
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: iwt_po.m
(See /home/drw/idl/wwbsrc/wiwtpo.pro)
WLCKAXES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WLCKAXES
PURPOSE:
This procedure creates an axis and sets the {xmin,xmax}{ymin,ymax}
CATEGORY:
Plotting
CALLING SEQUENCE:
WLCKAXES, a
INPUTS:
a: 4-element array containing x and y endpoints for the axes
OUTPUTS:
An axis
SEE ALSO:
wulkaxes
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
Translated from MatLab Wavelab routine: lockaxes.m
(See /home/drw/idl/wwbsrc/wlckaxes.pro)
WLNSPACE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WLNSPACE
PURPOSE:
This function creates an array of N equally spaced points between
x1 and x2.
CATEGORY:
Wavelets
CALLING SEQUENCE:
y = WLNSPACE( x1, x2, n)
INPUTS:
x1: value of 1st element.
n: number of points
x2: value of last element.
OUTPUTS:
y: An array of of uniformly-spaced values.
SEE ALSO:
wmkiarry, wmkfarry
MODIFICATION HISTORY:
Written by: Amara Graps BAER, December, 1994
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wlnspace.pro)
WLSHIFT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WLSHIFT
PURPOSE:
This function performs a circular left shift of 1-d signal.
CATEGORY:
Wavelets
CALLING SEQUENCE:
l = WLSHIFT(x)
INPUTS:
x: 1-d signal
OUTPUTS:
l: shifted 1-d signal
EXAMPLE:
NOTES:
l(i-1) = x(i) except l(n-1) = x(0)
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: lshift.m
(See /home/drw/idl/wwbsrc/wlshift.pro)
WMEAN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMEAN
PURPOSE:
To compute the mean of any array
CATEGORY:
G1- Simple calculations on statistical data.
CALLING SEQUENCE:
Result = WMEAN(Array)
INPUTS:
Array: The data array. Array may be any type except string.
OUTPUTS:
WMEAN returns the mean of the values in the data array.
PROCEDURE:
WMEAN = TOTAL(Array)/N_ELEMENTS(Array)
MODIFICATION HISTORY:
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wmean.pro)
WMFILT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMFILT
PURPOSE:
This function performs a convolution operation that runs a window
through a data set. The result is equivalent to Matlab's call:
filter(filt, 1, x).
CATEGORY:
Wavelets
CALLING SEQUENCE:
y = WMFILT(filt, x)
INPUTS:
x: 1-d signal.
filter: filter/window
OUTPUTS:
y: 1-d signal smeared with the filter/window function.
EXAMPLE:
SEE ALSO:
wiconv, waconv
MODIFICATION HISTORY:
Written by Amara Graps with help from Jeff Scargle (NASA-Ames),
October, 1994.
(See /home/drw/idl/wwbsrc/wmfilt.pro)
WMHYBRID
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMHYBRID
PURPOSE:
To perform Shrinkage to Wavelet Coefficients via
Adaptive Threshold Selection Using Principle of Stein's
Unbiased Risk Estimate Variant without Rigorous Proof
CATEGORY:
Wavelets.
CALLING SEQUENCE:
x = WMHYBRID(wc,L)
INPUTS:
wc = Wavelet Transform of noisy sequence with N(0,1) noise
L = low-frequency cutoff for Wavelet Transform
OUTPUTS:
ws = result of applying HybridThresh to each
dyadic Block
EXAMPLE:
SEE ALSO:
whybrthr, wdoshrnk
MODIFICATION HISTORY:
Written by: Amara Graps December, 1994
Translated from MatLab Wavelab routine: multihybrid.m
(See /home/drw/idl/wwbsrc/wmhybrid.pro)
WMIRFILT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMIRFILT
PURPOSE:
This function applies a (-1)^t modulation.
CATEGORY:
Wavelets
CALLING SEQUENCE:
h = WMIRFILT(x)
INPUTS:
x: 1-d signal
OUTPUTS:
h: a 1-d signal with DC frequency content shifted
to Nyquist frequency
EXAMPLE:
SEE ALSO:
wdndydhi
PROCEDURE:
h(t) = (-1)^(t-1) * x(t), 1 <= t <= length(x)
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: mirrorfilt.m
(See /home/drw/idl/wwbsrc/wmirfilt.pro)
WMKFARRY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMKFARRY
PURPOSE:
This function creates a FRACTIONAL array with the same notation that
Matlab uses in creating one, i.e. y = a:b:c.
CATEGORY:
Wavelets
CALLING SEQUENCE:
y = WMKFARRY( a, b, c)
INPUTS:
a: value of 1st element.
b: increment (usually 1).
c: value of last element.
OUTPUTS:
y: A fractional array.
SEE ALSO:
wmkiarry (array of integer index values)
EXAMPLE:
IDL> t=WMKFARRY(.5,.5,2.5)
IDL> print, t
.5 1.0 1.5 2.0 2.5
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wmkfarry.pro)
WMKIARRY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMKIARRY
PURPOSE:
This function creates an INTEGER INDEX array with the same notation that
Matlab uses in creating one, i.e. y = a:b:c.
CATEGORY:
Wavelets
CALLING SEQUENCE:
y = WMKIARRY( a, b, c)
INPUTS:
a: index of 1st element.
b: increment (usually 1).
c: index of last element.
OUTPUTS:
y: An array of index values.
NOTES:
Matlab indices for arrays begin with 1, IDL begins
with 0. This routine assumes that the array created
has index-1 of what Matlab uses. I.e. If Matlab
assumes an index array of: [2,6,10,14,18], this
routine creates: [1,5,9,13,17].
SEE ALSO:
wmkfarry (arrays of fractional values)
EXAMPLE:
IDL> t=WMKIARRY(1,1,5)
IDL> print, t
0 1 2 3 4
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wmkiarry.pro)
WMKOFILT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMKOFILT
PURPOSE:
This function generates an orthonormal QMF filter for a wavelet
transform.
CATEGORY:
Wavelets
CALLING SEQUENCE:
qmf = WMKOFILT(Type,Par)
INPUTS:
Type: string, 'Haar', 'Daubechies', 'Coiflet', 'Symmlet'
Par: integer, e.g. if Type ='Coiflet', Par=3 specifies
Coiflet3
OUTPUTS:
qmf: quadrature mirror filter
EXAMPLE:
SEE ALSO:
wfwtpo, wiwtpo, wfwt2po, wiwt2po, wpanalys
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: makeonfilter.m
(See /home/drw/idl/wwbsrc/wmkofilt.pro)
WMKSGNAL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMKSGNAL
PURPOSE:
This function generates an artificial signal.
CATEGORY:
Wavelets
CALLING SEQUENCE:
sig = WMKSGNAL(Name,n)
INPUTS:
Name: string, 'HeaviSine', 'Bumps', 'Blocks'
'Doppler', 'Ramp', 'Cusp', 'Sing', 'HiSine',
'LoSine', 'LinChirp', 'TwoChirp', 'QuadChirp'
'MishMash'
n: desired signal length
OUTPUTS:
sig: 1-d signal
EXAMPLE:
REFERENCES:
various articles of D.L. Donoho and I.M. Johnstone
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
Translated from MatLab Wavelab routine: makesignal.m
(See /home/drw/idl/wwbsrc/wmksgnal.pro)
WMKWVLET
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMKWVLET
PURPOSE:
This function generates a periodized orthogonal wavelet.
CATEGORY:
Wavelets
CALLING SEQUENCE:
wave = WMKWVLET(j,k [,Family=Famly,par=par,Gender=Gender,n=n])
INPUTS:
j,k: location-scale indices: 2^{-j} approx width of wavelet
k/2^j approx location of wavelet on unit interval
OUTPUTS:
wave: 1-d signal, the wavelet
KEYWORD PARAMETERS:
FAMILY: string, 'Haar', 'Daubechies', 'Coiflet', 'Symmlet'
PAR: integer parameter to MakeONFilter, e.g. if Family ='Coiflet',
Par=3 specifies Coiflet3
GENDER: 'Mother','Father'
N: signal length (dyadic)
EXAMPLE:
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: makewavelet.m
(See /home/drw/idl/wwbsrc/wmkwvlet.pro)
WMMIN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMMIN
PURPOSE:
To find the minimum elements of an array or matrix. This
function works the same way as Matlab's MIN: [y,ind]=min(array)
works.
CATEGORY:
Math.
CALLING SEQUENCE:
Result = WMMIN(array, ind)
INPUTS:
Array: The data array. Array may be any type except string.
OUTPUTS:
Result =
WMMIN returns the lowest value of an array, or if the array
is a matrix, it returns the lowest value of each *column* in
the matrix.
ind = the index of the lowest value(s).
NOTES: IDL's indices are one less than Matlab's.
EXAMPLE:
>array=[[1,3,2],[6,3,4],[9,1,0]]
>print, array
1 3 2
6 3 4
9 1 0
y= WMMIN(array, ind)
>print, y
1 1 0
>print, ind
0 2 2
MODIFICATION HISTORY:
Amara Graps, BAER, December 1994.
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wmmin.pro)
WMSORT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMSORT
PURPOSE:
To create a increasing-order sorted array. This
function works the same way as Matlab's SORT.
CATEGORY:
Math.
CALLING SEQUENCE:
Result = WMSORT(Array)
INPUTS:
Array: The data array. Array may be any type except string.
OUTPUTS:
WMSORT returns an increasing-order sorted array from the
input data array.
PROCEDURE:
WMSORT = REVERSE(SORT(SORT(array)))
EXAMPLE:
>a=[[1,3,2],[6,3,4],[9,1,0]]
>print, a
1 3 2
6 3 4
9 1 0
print, WMSORT(a)
1 1 0
6 3 2
9 3 4
MODIFICATION HISTORY:
Amara Graps, BAER, December 1994.
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wmsort.pro)
WMTHRESH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMTHRESH
PURPOSE:
To Perform Minimax Thresholding.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
x = WMTHRESH(y)
INPUTS:
y = signal upon which to perform thresholding
OUTPUTS:
x = result
EXAMPLE:
SEE ALSO:
wdoshrnk
NOTES:
See article ``Ideal Spatial Adaptation via Wavelet Shrinkage''
By D.L. Donoho and I.M. Johnstone
MODIFICATION HISTORY:
Written by: Amara Graps December, 1994
Translated from MatLab Wavelab routine: minmaxthresh.m
(See /home/drw/idl/wwbsrc/wmthresh.pro)
WMULTMAD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WMULTMAD
PURPOSE:
To perform Shrinkage to Wavelet Coefficients via
level-dependent Noise level estimation.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
ws = WMULTMAD(wc,L)
INPUTS:
wc = Wavelet Transform of noisy sequence
L = low-resolution cutoff for Wavelet Transform
OUTPUTS:
ws = result of applying VisuThresh to each wavelet level,
after scaling so MAD of coefficienst at each level = .6745
EXAMPLE:
SEE ALSO:
wvisuthr, wdoshrnk
MODIFICATION HISTORY:
Written by: Amara Graps December, 1994
Translated from MatLab Wavelab routine: multimad.m
(See /home/drw/idl/wwbsrc/wmultmad.pro)
WNNOISE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WNNOISE
PURPOSE:
This function normalizes the signal to noise level 1.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
y = WNNOISE(x,QMF)
INPUTS:
x = 1-d/2-d signal
QMF = quadrature mirror filter
OUTPUTS:
y = 1-d signal, scaled so wavelet coefficients
at finest level have median absolute deviation 1
TT = 'I' if image and 'S' if signal
EXAMPLE:
IDL> ;Truncate sig array appropriately and get QMF
IDL> WINTWAVE, sig, WaveType, ParVal, QMF, LD
IDL> tt = 'S' if 1D dataset or tt = 'I' if 2D dataset
IDL> sig = WNNOISE(sig,QMF, tt)
IDL> If tt EQ 'S' then WPLOTIT, st, 1, sig ELSE WPLOTIT, st, 10, sig
NOTES:
This is required pre-processing to use any of the DeNoising
tools on naturally-occurring data
SEE ALSO:
wpdnoise
MODIFICATION HISTORY:
Written by: Amara Graps September, 1995
Translated from MatLab Wavelab routine: normnoise.m
(See /home/drw/idl/wwbsrc/wnnoise.pro)
WNNORM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WNNORM
PURPOSE:
To compute the Euclidean norm of an column-dominant
or a row-dominant array.
CATEGORY:
Simple math.
CALLING SEQUENCE:
Result = WNNORM(A)
INPUTS:
A: A vector
OUTPUTS:
The Euclidean norm of the vector.
NOTES:
To get the same result as IDL's intrinsic NORM
function, one can run REFORM on the column-dominant array.
This function eliminates that step.
EXAMPLE:
IDL>a = [[1,2,3],[4,5,6],[7,8,9]]
IDL>print, a
1 2 3
4 5 6
7 8 9
IDL>b = a(0,*)
IDL>print, b
1
4
7
IDL>print, WNNORM(b)
8.12404
MODIFICATION HISTORY:
Amara Graps, January 1995.
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wnnorm.pro)
WNODE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WNODE
PURPOSE:
To perform tree indexing.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
index = WNODE(d,b)
INPUTS:
d = depth from root of tree
b = index among the 2^d possibilities
in a left-right scan at that depth
OUTPUTS:
index = linear index of node in tree structure
EXAMPLE:
SEE ALSO:
wbbasis, wstatree
MODIFICATION HISTORY:
Written by: Amara Graps December 1994/August1995
Translated from MatLab Wavelab routine: node.m
(See /home/drw/idl/wwbsrc/wnode.pro)
WPACKET
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPACKET
PURPOSE:
This function performs packet table indexing.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
p = WPACKET(d,b,n)
INPUTS:
d = depth of splitting in packet decomposition
b = block index among 2^d possibilities at depth d
n = length of signal
OUTPUTS:
p = linear indices of all coeff's in that block
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
Translated from MatLab Wavelab routine: packet.m
(See /home/drw/idl/wwbsrc/wpacket.pro)
WPANALYS
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPANALYS
PURPOSE:
This function creates a dyadic table of all Wavelet Packet coefficients.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
wp = WPANALYS(x,D,qmf)
INPUTS:
x = array of dyadic length n=2^J
D = degree of finest frequency partition
QMF = orthonormal quadrature mirror filter
OUTPUTS:
wp = array of Wavelet Packet Decompositions
Coefficients for frequency interval
[b/2^d,(b+1)/2^d] is stored in
wp(WPACKET(d,b,n),d+1)
SEE ALSO:
wintwave (necessary for this procedure to get QMF),
wpsynth, wpdnoise, wdndydhi, wdndydlo
REFERENCE:
title = {Signal processing and compression with wavelet packets},
author = {R.R. Coifman and Y. Meyer and S. Quake and M.V. Wickerhauser},
booktitle = {Progress in wavelet analysis and applications,
Proceedings of the International Conference ``Wavelets and
Applications", Toulouse, 1992},
editor = {Y. Meyer and S. Roques},
publisher = {Editions Frontieres},
year = 1993,
pages = {77-93}
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
Translated from MatLab Wavelab routine: wpanalysis.m
(See /home/drw/idl/wwbsrc/wpanalys.pro)
WPAROUND
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPAROUND
PURPOSE:
To perform a circular map onto 0->(n-1)
CATEGORY:
Array Transformation.
CALLING SEQUENCE:
indnew = WPAROUND(ind, n)
INPUTS:
ind = vector to wrap
n = length of wrap
OUTPUTS:
An array with the values wrapped.
EXAMPLE:
IDL> arr = [1,2,3,4,5,6,7,8,9]
IDL> print, arr
1 2 3 4 5 6 7
8 9
IDL> n = 7
IDL> indnew = WPAROUND(arr,n)
IDL> print, indnew
1 2 3 4 5 6 7
1 2
MODIFICATION HISTORY:
Written by: Amara Graps November, 1995
Translated from MatLab Wavelab routine: wraparound.m
(See /home/drw/idl/wwbsrc/wparound.pro)
WPC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPC
PURPOSE:
This procedure sets up runs a simple event loop for
the Wavelet Packet Compression action. It is part
of the Wavelet Workbench functions.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WPC
INPUTS:
none
OUTPUTS:
This procedure runs the wavelet data input as well as the actions
performed on the data.
COMMON BLOCKS:
COMMON WWB_COMMON, $
TEXT_ANNOUNCE, wd, sig, len, st, noise_type, noise_lev, $
QMF, LD, shrinkage_type, WaveType, ParVal
TEXT_ANNOUNCE: The block for passing the widget that present
messages as well as other important wavelet parameters such
as the data array (sig), the data array length(len), a string
describing the data (st) and the current chosen quadrature mirror
filter (QMF).
COMMON WPC_common, FSLID1, BUTTON1, BUTTON2, BUTTON17, $
wpcoef, btree, wcmsort, thr, threshslider
COMMON WPC_common, The block for the slider (FSLID1)
the two buttons (BUTTON1, BUTTON2) and
array of wavelet coeffs (wpcoef), sorted array of wavelet coeffs (wcmsort),
threshold value (thr), the current
value of the slider (threshslider)
MODIFICATION HISTORY:
Written by: Amara Graps, September 1995.
(See /home/drw/idl/wwbsrc/wpc.pro)
WPDNOISE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPDNOISE
PURPOSE:
This function De-Noises in an adaptively chosen WP basis
CATEGORY:
Wavelets.
CALLING SEQUENCE:
clean = WPDNOISE(x,D,QMF,bb,st)
INPUTS:
x = 1-d signal to be de-noised.
D = maximum depth of basis tree
QMF = quadrature mirror filter for freq. splitting
OUTPUTS:
clean cleaned signal
bb basistree naming basis in which de-noising was done
st stat tree: statistics driving basis search
NOTES
1. Assumes noise level eq 1
2. Uses Stein Unbiased Estimate of risk to evaluate basis
3. Uses Coifman-Wickerhauser BestBasis algorithm to select
best basis
MODIFICATION HISTORY:
Written by: Amara Graps December, 1994
Translated from MatLab Wavelab routine: wpdenoise.m
(See /home/drw/idl/wwbsrc/wpdnoise.pro)
WPHPLANE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPHPLANE
PURPOSE:
This procedure partitions phase space by rectangular blocks.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WPHPLANE, TFtype,btree,pkt,titlestr=titlestr,nTFR=nTFR,qmf=qmf
INPUTS:
TFtype = string: type of TF-packets used ('WP','CP')
btree = basis tree
pkt = wavelet or cosine packet table
titlestr = signal name
nTFR = number of x-points in phaseplane image (optional)
qmf = qmf for calculating WP phase plane location (optional)
OUTPUTS:
an image plot with colored rectangles based on
recursive dyadic partitioning of y axis according
to splits in basis tree
EXAMPLE:
To create a ``Heisenberg image" plot of data analyzed with WPANALYS,
make the following call:
IDL>WPHPLANE,`WP',btree,wp,titlestr = st, nTFR = 64
where `WP' is wavelet packet, btree and wp are outputs from WPANALYS,
st is the string identifier for the data (`seismic', `sunspots', etc.),
nTFR is the number of boxes (dyads!) on a side. Keep nTFR on the low side,
If nTFR = 256, or higher you'll be waiting 5 minutes or more for output.
NOTE:
This routine also performs a Cosine-Packet Analysis ('CP'), however,
cosine packet analysis isn't currently a function fully implemented
in Wavelet Workbench. So consider this 'CP' option a 'hook' for now.
MODIFICATION HISTORY:
Written by: Amara Graps November, 1995
Translated from MatLab Wavelab routine: imagephaseplane.m
(See /home/drw/idl/wwbsrc/wphplane.pro)
WPIPULSE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPIPULSE
PURPOSE:
This function calculates location of wavelet packet entry.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
dwp = WPIPULSE(wp,d,b,k,qmf)
INPUTS:
wp = packet table, ignored except for size
d,b,k = 1-d packet-index
qmf = quadrature mirror filter
OUTPUTS:
dwp = packet table -- complete wavelet packet analysis of
wavelet packet (d,b,k)
MODIFICATION HISTORY:
Written by: Amara Graps November, 1995
Translated from MatLab Wavelab routine: wpimpulse.m
(See /home/drw/idl/wwbsrc/wpipulse.pro)
WPKBCOEF
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPKBCOEF
PURPOSE:
This function stuffS basis coefficients into packet table.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
pkt = WPKBCOEF(basis,opkt,x)
INPUTS:
basis = basis tree selecting basis the coefficients come from
opkt = wavelet or cosine packet table
x = 1-d signal; coefficients in the basis of btree
OUTPUTS:
pkt = new packet table with coefficients in specified
basis filled in from x
MODIFICATION HISTORY:
Written by: Amara Graps September, 1995
Translated from MatLab Wavelab routine: wpkbcoef.m
(See /home/drw/idl/wwbsrc/wpkbcoef.pro)
WPLBTREE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPLBTREE
PURPOSE:
This procedure displays basis tree with decorated branch lengths
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WPLBTREE, btree,Depth,stree,st
INPUTS:
basis = basis tree (e.g. output of BestBasis)
Depth = max depth of tree
stree = stat tree of pkt table
st = signal title
OUTPUTS:
A plot of tree with height of each branch proportional
to improvement in cost function obtained by splitting.
MODIFICATION HISTORY:
Written by: Amara Graps November, 1995
Translated from MatLab Wavelab routine: plotbasistree.m
(See /home/drw/idl/wwbsrc/wplbtree.pro)
WPLMLRES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPLMLRES
PURPOSE:
This procedure generates a Multi-Resolution Display of
a 1-d Wavelet Transform. This multi-resolution depiction
of the signal is the type referenced in S. Mallat's work.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WPLMLRES,wc,L,scal,qmf, st
INPUTS:
wc: 1-d wavelet transform
L: level of coarsest scale
scal: scale factor [0 ==> autoscal]
qmf: quadrature mirror filter used to make wc
st: title of signal/dataset
OUTPUTS:
a Multi-Resolution Display of 1-d Wavelet Transform
SEE ALSO:
wplwcoef, wfwtpo, wiwtpo, wmkofilt
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: plotmultires.m
(See /home/drw/idl/wwbsrc/wplmlres.pro)
WPLMSURF
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPLMSURF
PURPOSE:
This procedure generates a Multi-Resolution Surface Display of
a 1-d Wavelet Transform.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WPLMSURF,wc,L,scal,qmf, st
INPUTS:
wc: 1-d wavelet transform
L: level of coarsest scale
scal: scale factor [0 ==> autoscal]
qmf: quadrature mirror filter used to make wc
st: title of signal/dataset
OUTPUTS:
a Multi-Resolution Surface Display of 1-d Wavelet Transform
SEE ALSO:
wplmlres, wfwtpo, wiwtpo, wmkofilt
MODIFICATION HISTORY:
Amara Graps for Wavelet Workbench, September 1996.
(See /home/drw/idl/wwbsrc/wplmsurf.pro)
WPLOTIT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPLOTIT
PURPOSE:
This procedure plots or images a 1D or 2D array.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WPLOTIT, pt, win, data
INPUTS:
pt = a plot title string
win = window number to plot into
=0 for Image,
=1 for Signal/Data,
=2 for Wavelet,
=10 or 11 for stretched image,
other number = just a window and no plotting
data = data or image array
OUTPUTS
plotted data array in window number #
MODIFICATION HISTORY:
Written by: Amara Graps September 1995
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wplotit.pro)
WPLPKTBL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPLPKTBL
PURPOSE:
This procedure display entries in wavelet and cosine packet tables.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WPLPKTBL, pkt,scal,signaltitle
INPUTS:
pkt wavelet or cosine packet table
scal optional scaling factor (0 =gt autoscale)
st = title of signal or dataset
OUTPUTS:
spike plot of coefficients in packet table
SEE ALSO:
wintwave (necessary for this procedure to get QMF),
wpanalys, wpsynth, wdndydhi, wdndydlo
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
Translated from MatLab Wavelab routine: plotpackettable.m
(See /home/drw/idl/wwbsrc/wplpktbl.pro)
WPLSPIKE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPLSPIKE
PURPOSE:
This procedure plots a 1-d signal as baseline with series of spikes.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WPLSPIKE,base,t,x, signaltitle
INPUTS:
base: number, baseline level
t: ordinate values
x: 1-d signal, specifies spike deflections from baseline
First: First time through (will erase data) = 'True' otherwise
= 'False' (will use oplot, and keep previous plotted data).
signaltitle: title for signal
OUTPUTS:
a 1-d signal plot as baseline with series of spikes.
SEE ALSO:
wplwcoef, wplpktbl
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
Translated from MatLab Wavelab routine: plotspikes.m
(See /home/drw/idl/wwbsrc/wplspike.pro)
WPLWCOEF
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPLWCOEF
PURPOSE:
This procedure plots a spike-plot display of wavelet coefficients.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WPLWCOEF,wc,L,scal,signaltitle
INPUTS:
wc: 1-d wavelet transform
L: level of coarsest scale
scal: scale factor [0 ==> autoscale]
signaltitle: title for plot
OUTPUTS:
A display of wavelet coefficients
(coarsest level NOT included) by level and position.
SEE ALSO:
wplmlres, wfwtpo, wiwtpo, wplspike
Note: L controls the lowest resolution level.
The lowest resolution level will be L out of log_2(n).
For example if L=0, the lowest resolution level with have 2^L+1
element in it, which will represent the overall average.
We often use L=3.
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: plotwavecoeff.m
(See /home/drw/idl/wwbsrc/wplwcoef.pro)
WPOISIMG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPOISIMG
PURPOSE:
Add Poisson noise to an array.
CATEGORY:
Image simulation.
CALLING SEQUENCE:
RESULT = WPOISIMG ( IM[, SEED] )
INPUT:
IM: A numeric array (byte, integer, long, or float) of arbitrary
dimensionality. This is the array of values around which values in the
result will be Poisson-distributed.
OPTIONAL INPUTS:
SEED: A longword seed for the random number generator. If this is not
supplied, the value -123456789L is used for generating the first random
value.
KEYWORD PARAMETER:
OUTPUT_KIND: The data type of the output array, that is byte, integer,
longword, or float. The words "byte", "int", "integer","long",
"longword", and "float", in upper or lower case, are accepted, as are
the numeric IDL values 1,2,3,4 for byte, integer, longword, and float.
OUTPUT:
WPOISIMG returns a copy of the input array, Poisson noise added.
RESTRICTIONS:
Negative input values are mapped to a result of 0.
PROCEDURE:
Create an image with values Poisson-distributed around the mean values
IM, using Knuth's "Algorithm Q". (Donald E. Knuth, The Art of
Computer Prograwmming, Volume 2, "Seminumerical Algorithms", Addison-
Wesley (1969), page 117. This routine IS NOT VECTORIZED, AND SHOULD RUN
SLOWLY. A deft IDL'er could probably vectorize the algorithm, and
anyone who does so is entitled to a gold star. Where the gaussian and
Poisson distributions are essentially identical (mean value > 50) a
normal, that is gaussian, distribution is used.
EXAMPLE:
Here is how you can create a 100x100 array of values Poisson-distributed
around the mean value 5.0, and check the empirical probability against
the Poisson distribution:
n = 100
a = REPLICATE(5.0,n,n)
b = WPOISIMG ( a, out="byte" )
tvscl, b
print, STDEV(b,mean), mean, SQRT(5.0)
h = histogram ( b )
prob = FLOAT(h)/N_ELEMENTS(b)
probi = EXP(-5.0)
FOR i=0,10 do begin PRINT, i, prob(i), probi & $
probi=probi*5.0/(i+1)
MODIFICATION HISTORY:
Written by: James Hamill
Siemens Medical Systems
2501 N. Barrington Rd.
Hoffman Estates, IL 60195-7372
(708)304-7760
hamill@sgi.siemens.com
February, 1992
Renamed from poisson_image.pro by A. Graps to go with Wavelet Workbench, March 1996.
(See /home/drw/idl/wwbsrc/wpoisimg.pro)
WPSYNTH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WPSYNTH
PURPOSE:
This function synthesize a signal from wavelet packet coefficients.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
x = WPSYNTH(basis,wp,qmf)
INPUTS:
basis = basis tree indicating wavelet packet to use
wp = wavelet packet table
qmf = quadrature mirror filter
OUTPUTS:
x = 1-d signal whose wavelet packet coefft's in
basis btree are in wp
SEE ALSO:
wintwave (necessary for this procedure to get QMF)
wpanalys, wpdnoise, wdndydhi, wdndydlo
REFERENCE:
title = {Signal processing and compression with wavelet packets},
author = {R.R. Coifman and Y. Meyer and S. Quake and M.V. Wickerhauser},
booktitle = {Progress in wavelet analysis and applications,
Proceedings of the International Conference "Wavelets and
Applications", Toulouse, 1992},
editor = {Y. Meyer and S. Roques},
publisher = {Editions Frontieres},
year = 1993,
pages = {77-93}
MODIFICATION HISTORY:
Written by: Amara Graps September, 1995
Translated from MatLab Wavelab routine: wpsynthesis.m
(See /home/drw/idl/wwbsrc/wpsynth.pro)
WQUAD2IX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WQUAD2IX
PURPOSE:
This function translates 2-d wavelet indexing into linear indexing.
CATEGORY:
Wavelets
CALLING SEQUENCE:
kx = WQUAD2IX(j,k1,k2,ep,ky)
INPUTS:
j: resolution level
k1,k2: spatial indices
ep: spatial orientation
ep = 0: Father(x)Father(y)
1: Mother(x)Father(y)
2: Father(x)Mother(y)
3: Mother(x)Mother(y)
OUTPUTS:
kx,ky index in 2-d wavelet transform array of indicated wavelet.
SEE ALSO:
fwt2_po, wiwt2po
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: quad2ix.m
(See /home/drw/idl/wwbsrc/wquad2ix.pro)
WQUADLEN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WQUADLEN
PURPOSE:
This function finds length and dyadic length of square matrix.
CATEGORY:
Wavelets
CALLING SEQUENCE:
n = WQUADLEN(x,J)
INPUTS:
x: 2-d image; SIZE(n,n), n = 2^J (hopefully)
OUTPUTS:
n: N_ELEMENTS(x) of one of the sides of the image
J: least power of two greater than n
SIDE EFFECTS:
A warning is issued if n is not a power of 2,
or if x is not a square matrix
EXAMPLE:
SEE ALSO:
wdyadlng, wquad2ix
MODIFICATION HISTORY:
Written by: Amara Graps November 1994/September 1995
Translated from MatLab Wavelab routine: quadlength.m
(See /home/drw/idl/wwbsrc/wquadlen.pro)
WRAND
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WRAND
PURPOSE:
To generate a matrix with ncol, nrow with unformly distributed
numbers. This function mimics the Matlab x=rand(size(A)) where
size A gives you a 2-element array with values (nrow,ncol).
CATEGORY:
Simple math.
CALLING SEQUENCE:
rmatrix = WRAND(seed, nrow, ncol)
INPUTS:
seed: Named variable containing the seed value for the random
number generation. If it is undefined, it is derived from the
system clock.
nrow: number of rows
ncol: number of columns
OUTPUTS:
A matrix w/ncol, nrow, uniformly distributed.
NOTE:
The easiest way to get the input rows/columns is to:
IDL> t=SIZE(A)
IDL> numcol = t(1) ;number of columns
IDL> numrow=t(2) ;number of rows
Or if A is an array:
IDL> numcol = t(1) ;number of columns
IDL> numrow=t(0) ;number of rows(=1)
EXAMPLE:
IDL> A = [[8,2,6],[3,6,7]]
IDL>print, A
8 2 6
3 6 7
IDL> t=SIZE(A)
IDL> numcol = t(1) ;number of columns
IDL> numrow=t(2) ;number of rows
IDL> rmatrix = WRAND(seed, nrow,ncol)
IDL> print, rmatrix
0.2190 0.6789 0.9347
0.0470 0.6793 0.3835
MODIFICATION HISTORY:
Amara Graps September 1995.
(c) copyright Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wrand.pro)
WRANDN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WRANDN
PURPOSE:
To generate a matrix with ncol, nrow with normally distributed
numbers. This function mimics the Matlab x=randn(size(A)) where
size A gives you a 2-element array with values (nrow,ncol).
CATEGORY:
Simple math.
CALLING SEQUENCE:
rmatrix = WRANDN(seed, nrow, ncol)
INPUTS:
seed: Named variable containing the seed value for the random
number generation. If it is undefined, it is derived from the
system clock.
nrow: number of rows
ncol: number of columns
OUTPUTS:
A matrix w/ncol, nrow, normally distributed.
NOTE:
The easiest way to get the input rows/columns is to:
IDL> t=SIZE(A)
IDL> numcol = t(1) ;number of columns
IDL> numrow=t(2) ;number of rows
Or if A is an array:
IDL> numcol = t(1) ;number of columns
IDL> numrow=t(0) ;number of rows(=1)
EXAMPLE:
IDL> A = [[8,2,6],[3,6,7]]
IDL>print, A
8 2 6
3 6 7
IDL> t=SIZE(A)
IDL> numcol = t(1) ;number of columns
IDL> numrow=t(2) ;number of rows
IDL> rmatrix = WRANDN(seed, nrow,ncol)
IDL> print, rmatrix
-0.323532 1.70055 -0.425996
-0.584817 -1.50207 1.04847
MODIFICATION HISTORY:
Amara Graps September 1995.
(c) copyright Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wrandn.pro)
WREADDAT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WREADDAT
PURPOSE:
This procedure reads in two files- both ascii- that hold a
one-d dataset and the description of that dataset.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WREADDAT, dtype, st, len, wd, data
INPUTS:
st = a string that directly relates to the
two files we will open:
st+'.asc' = the data file
st+'.doc' = the documentation file
wd = the working directory
dtype = 1(given) or 2(user-defined);
OUTPUTS: len = the length of the data set
Prints out the contents of the st+'.doc' file to
the screen.
EXAMPLE:
To read a user defined one-d dataset (2) with 'st' as the file
identifier (e.g. st='nmr'), and working directory wd (string)
Type:
IDL> WREADDAT, 1, st, len, wd, sig
The output will len = length of data array in addition
to plot in window.
MODIFICATION HISTORY:
Written by: Amara Graps September 1995
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wreaddat.pro)
WREADIMG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WREADIMG
PURPOSE:
This procedure reads in two files- one byte (image) and one ascii- that
hold a two-d dataset and the description of that dataset.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WREADIMG, dtype, st, len, wd, image
INPUTS:
st = a string that directly relates to the
two files we will open:
st+'.asc' = the data file
st+'.doc' = the documentation file
wd = the working directory
len = the square size of the image
dtype = 1(given) or 2(user-defined);
OUTPUTS:
len = the length of the data image
Prints out the contents of the st+'.doc' file to
the screen.
image = image array to be plotted
EXAMPLE:
To read a user defined Image dataset (2) with 'st' as the file
identifier (e.g. st='phone'), and working directory wd (string)
Type:
IDL> WREADIMG, 2, st, len, wd, image
The output will len = length on a side and image array in addition
to plot in window.
MODIFICATION HISTORY:
Written by: Amara Graps September 1995
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wreadimg.pro)
WREM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WREM
PURPOSE:
To compute the remainder after division.
CATEGORY:
Simple math.
CALLING SEQUENCE:
Result = WREM(x,y)
INPUTS:
x: numerator
y: denominator
OUTPUTS:
The remainder after x is divded by y.
SIDE EFFECTS:
If x is an array, this function operates element
by element.
RESTRICTIONS:
None.
PROCEDURE:
Remainder = x-n*y where n = FIX(x/y) is the integer
part of the quotient x/y.
MODIFICATION HISTORY:
Amara Graps, BAER, October 1994.
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wrem.pro)
WRESHAPE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WRESHAPE
PURPOSE:
To reshape all elements in a matrix to the desired
shape, like Matlab's "reshape".
CATEGORY:
Simple math.
CALLING SEQUENCE:
Result = WRESHAPE(A, nrows,ncols)
INPUTS:
A: A matrix
m: number of rows
n: number of columns
OUTPUTS:
The matrix turned into a column with the elements in the right shape.
SIDE EFFECTS:
If A does not have m*n elements, an error occurs.
EXAMPLE:
IDL>a = [[2,3],[4,5],[6,7]]
IDL>print, a
2 3
4 5
6 7
IDL>print, WRESHAPE(a, 2, 3)
2.00000 6.00000 5.00000
4.00000 3.00000 7.00000
MODIFICATION HISTORY:
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wreshape.pro)
WRITE_IN_BOX[1]
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : WRITE_IN_BOX
Purpose : Writes a text message within a box in a graphics window.
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.
Use : 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 charsize 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.
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 0.1, William Thompson, GSFC, 7 July 1993.
Version : Version 0.1, 7 July 1993.
(See /home/drw/idl/esrg/write_in_box.pro)
WRITE_IN_BOX[2]
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : WRITE_IN_BOX
Purpose : Writes a text message within a box in a graphics window.
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.
Use : 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 charsize 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.
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 0.1, William Thompson, GSFC, 7 July 1993.
Version : Version 0.1, 7 July 1993.
(See /home/drw/idl/old.esrg/write_in_box.pro)
WRITE_WIN
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: write_win
PURPOSE: copy image on current window to a gif, tiff or pict image file
NOTE: What you see is what you get. Make sure the
image you are reading/writing is not obscurred
by other windows, or is pushed off the edge of
your monitor's viewable area.
NOTE: You might get better results by writing to a
postscript file and then using the unix command:
convert -d 150x150 plot.ps plot.gif
convert -d 150x150 plot.ps plot.tiff
USEAGE: write_win,file
INPUT:
file Output file name, file suffix determins what type of
of graphic file format is used. Acceptable suffix
values are .gif, .tiff, and .pict. If one of these
string values are not found the image format defaults
to gif.
KEYWORD INPUT:
wid index of the idl window from which to copy the image,
if not set write_win copies from current default window
bgc background color. sets color index 0 of gif image to
specified RGB value. Does not affect current color table.
A scalor value of BGC is automatically turned into a color
triplet, i.e., bgc=255 => RGB=[255,255,255]
fgc foreground color. sets color index 255 of gif image to
specified RGB value. Does not affect current color table.
A scalor value of FGC is automatically turned into a color
triplet, i.e., fgc=0 => RGB=[0,0,0]
OUTPUT: none
EXAMPLE:
loadct,5
window,0
tvim,sin(20*hanning(200,200)*dist(200)),title='GIF test image',/sc
write_win,'test_image.gif',fgc=0,bgc=[210,255,210]
write_win,'test_image.tiff',fgc=0,bgc=[210,255,210]
exit
; this example wont work unless 256 colors are used
; you may have to restart idl
window,0,color=256
loadct,5
confill,dist(20)
write_win,'test_image.gif',fgc=0,bgc=[210,255,210]
xv test_image.gif
author: Paul Ricchiazzi feb94
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/esrg/write_win.pro)
WRSHIFT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WRSHIFT
PURPOSE:
This function performs a circular right shift of 1-d signal.
CATEGORY:
Wavelets
CALLING SEQUENCE:
r = WRSHIFT(x)
INPUTS:
x: 1-d signal
OUTPUTS:
r: shifted 1-d signal
EXAMPLE:
PROCEDURE:
r(i-1) = x(i-2) except r(0) = x(n-1)
SEE ALSO:
wlshift
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: rshift.m
(See /home/drw/idl/wwbsrc/wrshift.pro)
WSC_COMM
[Previous Routine]
[Next Routine]
[List of Routines]
This is WSC_COMM - Wave Speeds 'Complete' COMMand line.
It's been built on top of WAVE_SPEEDS_FS_COMM and its predecessors
to include more parameters from papers by Wang and Porter et al.
(94a & 94b) pertinent to coronal heating by fast M/A waves.
See the headers for WAVE_SPEEDS and WAVE_SPEEDS_FS_COMM for more
information regarding this history.
==================================
USAGE
wsc_comm,logTe,logNe0,logNee,B0,Be,delta,vf,va,vae,cs,beta0,$
betae,kcf,nuf_vis,nuf_cond,daml,quiet=quiet
EXAMPLE:
wsc_comm,6.3,9.3,8.9,40,1,45,vf,va,vae,cs,beta0,betae,kcf,$
nuf_vis,nuf_cond,daml
(See /home/drw/idl/gen/wsc_comm.pro)
WSC_COMM_SLOW
[Previous Routine]
[Next Routine]
[List of Routines]
This is WSC_COMM_SLOW - Wave Speeds 'Complete' COMMand line (slow-mode).
It's been built on top of WAVE_SPEEDS_FS_COMM and its predecessors
to include more parameters from papers by Wang and Porter et al.
(94a & 94b) pertinent to coronal heating by fast M/A waves.
See the headers for WAVE_SPEEDS and WAVE_SPEEDS_FS_COMM for more
information regarding this history.
==================================
USAGE
wsc_comm_slow,lTe,lne0,delta,Vs,kcs,nus_vis,nus_cond,daml,$
quiet=quiet
EXAMPLE:
wsc_comm_slow,6.3,9.3,45,Vs,kcs,$
nus_vis,nus_cond,daml
(See /home/drw/idl/gen/wsc_comm_slow.pro)
WSC_INT
[Previous Routine]
[Next Routine]
[List of Routines]
This is WSC_INT - Wave Speeds 'Complete' COMMand line.
It's been built on top of WAVE_SPEEDS_FS_COMM and its predecessors
to include more parameters from papers by Wang and Porter et al.
(94a & 94b) pertinent to coronal heating by fast M/A waves.
See the headers for WAVE_SPEEDS and WAVE_SPEEDS_FS_COMM for more
information regarding this history.
==================================
USAGE
wsc_int,logTe,logNe0,logNee,B0,Be,delta,vf,va,vae,cs,beta0,$
betae,kcf,nuf_vis,nuf_cond,daml,quiet=quiet
EXAMPLE:
wsc_int,6.3,9.3,8.9,40,1,45,vf,va,vae,cs,beta0,betae,kcf,$
nuf_vis,nuf_cond,daml
(See /home/drw/idl/gen/wsc_int.pro)
WSELECT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: wselect
PURPOSE: wset to window selected by a mouse click
USEAGE: wselect
DISCUSSION: the LMB selects the window and exits WSELECT,
the MMB kills the window and remains within the
WSELECT program loop. The WSELECT program loop
ends when either the LMB is pressed within a window
or when there are no remaining windows.
OUTPUT: none
author: Paul Ricchiazzi 11jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/wselect.pro)
WSELECT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: wselect
PURPOSE: wset to window selected by a mouse click
USEAGE: wselect
INPUT: none
OUTPUT: none
author: Paul Ricchiazzi 11jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/wselect.pro)
WSHASROW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSHASROW
PURPOSE:
This function makes a single or multi-dimensional
signal a row vector.
CATEGORY:
Wavelets
CALLING SEQUENCE:
row = WSHASROW(sig)
INPUTS:
sig: a row, column vector or matrix
OUTPUTS:
row: a row vector
EXAMPLE:
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: shapeasrow.m
(See /home/drw/idl/wwbsrc/wshasrow.pro)
WSHLIKE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSHLIKE
PURPOSE:
This function makes 1-d signal with given shape.
CATEGORY:
Wavelets
CALLING SEQUENCE:
vec = WSHLIKE(sig,proto)
INPUTS:
sig: a row, column vector, or matrix
proto: a prototype shape (row, column vector,
or matrix)
OUTPUTS:
vec: a vector with contents taken from sig
and same shape as proto
EXAMPLE:
SEE ALSO:
wshasrow
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: shapelike.m
(See /home/drw/idl/wwbsrc/wshlike.pro)
WSIGN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSIGN
PURPOSE:
To compute the sign of a number. This function mimics
Matlab's sign function.
CALLING SEQUENCE:
Result = WSIGN(num)
INPUTS:
Num: Any number or array
OUTPUTS:
WSIGN returns either 1, 0, or -1.
None.
MODIFICATION HISTORY:
Amara Graps, BAER, December 1994.
(c) copyright Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wsign.pro)
WSIGTYPE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSIGTYPE
PURPOSE:
This function returns a character identifying the sig array
as either a 1D signal "S" (size (n,1)) or matrix "I" (nrow,ncol)
where nrow = ncol .
CATEGORY:
Simple math.
CALLING SEQUENCE:
TT = WSIGTYPE(sig, len, error)
INPUTS:
sig: Either a 1D signal or a 2D matrix
OUTPUTS:
A character TT = "I" (Image) or "S" (Signal).
len = length of one side of square image (2D) or length of
signal (1D)
error = 1 (OK, square matrix or array) or 0 (not square matrix)
EXAMPLE:
IDL> a = [[3,3,3],[3,3,3],[3,3,3]]
IDL> PRINT, a
3 3 3
3 3 3
3 3 3
IDL> b = [1,2,3,4,5,6,7,8,9]
IDL> PRINT, b
1 2 3 4 5 6 7
8 9
IDL> TT = WSIGTYPE(a, len, error)
IDL> PRINT, tt, len, error
I 3 1
IDL> TT = WSIGTYPE(b, len, error)
IDL> PRINT, tt, len, error
S 9 1
MODIFICATION HISTORY:
Amara Graps September 1995.
(c) copyright Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wsigtype.pro)
WSMIN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSMIN
PURPOSE:
To find the minimum elements of an array or matrix. This
function works the same way as Matlab's MIN: y=min(array, val)
works.
CATEGORY:
Math.
CALLING SEQUENCE:
Result = WSMIN(array, val)
INPUTS:
Array: The data array. Array may be any type except string.
val: a value that is compared with every element of Array
OUTPUTS:
Result =
WSMIN returns the lowest value of an array element or "val",
or if the array is a matrix, it returns the lowest value of
each *column* in the matrix or "val".
NOTES: IDL's indices are one less than Matlab's.
EXAMPLE:
IDL> array=[[1,2,3],[4,5,6],[7,8,9]]
IDL> a = 1.4823
IDL> PRINT, array
1 2 3
4 5 6
7 8 9
IDL> y= WSMIN(array, a)
IDL> PRINT, y
1.0000 1.4823 1.4823
1.4823 1.4823 1.4823
1.4823 1.4823 1.4823
MODIFICATION HISTORY:
Amara Graps, September 1995.
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wsmin.pro)
WSOFTTHR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSOFTTHR
PURPOSE:
This function applies a soft threshold.
CATEGORY:
Wavelets
CALLING SEQUENCE:
x = WSOFTTHR(y,t)
INPUTS:
y = Noisy Data
t = Threshold
OUTPUTS:
x = SIGN(y)(|y|-t)
SEE ALSO:
whardthr, wdoshrnk
MODIFICATION HISTORY:
Written by: Amara Graps December, 1994
Translated from MatLab Wavelab routine: softthresh.m
(See /home/drw/idl/wwbsrc/wsoftthr.pro)
WSPECTRM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSPECTRM
PURPOSE:
This function generates a power spectrum.
CATEGORY:
Wavelets
CALLING SEQUENCE:
sp = WSPECTRM(x,n)
INPUTS:
x: a 1-d array
n: desired length of 1-d array
OUTPUTS:
sp: a power spectrum of input x array
EXAMPLE:
PROCEDURE:
Uses the IDL FFT function.
MODIFICATION HISTORY:
Written by: Amara Graps October, 1994
Translated from MatLab Wavelab routine: tw_spectrum.m
(See /home/drw/idl/wwbsrc/wspectrm.pro)
WSTATREE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSTATREE
PURPOSE:
To build tree with entropy numbers.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
stree = WSTATREE(pkt,Entropy,par)
INPUTS:
pkt packet table [wavelet or cosine packet] (n x L)
Entropy type of entropy to use: options are
'Entropy' -- Coifman-Wickerhauser
'l^p' -- sum th_i^p, 0 lt p lt 2, p = par
'N(eps)' -- # ge eps, eps = par
'Risk' -- sum min(th_i^2,eps^2), eps=par
'SURE' -- SURE(Thresholding), thresh = par
(Stein's unbiased estimate of risk)
par extra parameter for 'L^P', 'N(EPS)', 'SURE' Entropy
calculation
OUTPUTS:
stree stat tree of entropy numbers.
tree(WNODE(d,b)) contains entropy of WPACKET(d,b,n)
RESTRICTIONS:
None.
EXAMPLE:
SEE ALSO:
wbbasis, wplbtree
MODIFICATION HISTORY:
Written by: Amara Graps December 1994/August1995
Translated from MatLab Wavelab routine: calcstattree.m
(See /home/drw/idl/wwbsrc/wstatree.pro)
WSTBUSY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSTBUSY
PURPOSE:
This function can be embedded inside an IDL code that is expected to
run for a long time, announcing with printed messages that the code is
still running. Unlike a PRINT statement in a loop, WSTBUSY makes its
announcements just once a minute.
CATEGORY:
Calming down impatient users like the author.
CALLING SEQUENCE:
WSTBUSY[, ANNOUNCEMENT]
OPTIONAL INPUT:
ANNOUNCEMENT: An array of messages or values to be printed. If no
parameter is used, the message reads "STILL BUSY" plus the time and
date.
OUTPUT:
NONE.
COMMON BLOCKS:
BIZZY
SIDE EFFECTS:
The overhead of calling this function many times might be onerous; so
don't bury it deep inside nested loops.
PROCEDURE:
Each time the procedure is invoked, it decodes the !STIME system vari-
able to see if the minute has changed since the last time. If so, then
the program prints the announcement. If not, it returns and does
nothing.
EXAMPLE:
The following code might be used in a coded procedure that runs for
twenty minutes. About twenty times out of the 1000 passages through the
loop, a message appears on the screen.
for iter = 1, 1000 do begin
number_cruncher, data, i
WSTBUSY, "Processing iteration number " + strtrim(i,2)
endfor
MODIFICATION HISTORY:
Written by: James Hamill
Siemens Medical Systems
2501 N. Barrington Rd.
Hoffman Estates, IL 60195-7372
(708)304-7760
hamill@sgi.siemens.com
October, 1989
(See /home/drw/idl/wwbsrc/wstbusy.pro)
WSUM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSUM
PURPOSE:
To sum all of the elements in an array or matrix.
If A is a matrix, then sum(A) is a row vector with
the sum over each column. This function is an equiv-
alent of Matlab's sum function.
CATEGORY:
Simple math.
CALLING SEQUENCE:
Result = WSUM(A)
INPUTS:
A: A vector or matrix
OUTPUTS:
The sum of the vector or matrix.
RESTRICTIONS:
None.
EXAMPLE:
IDL> a = [[8,2,6],[3,6,7],[4,9,3]]
IDL> print, a
8 2 6
3 6 7
4 9 3
IDL> print, WSUM(A)
15.0000 17.0000 16.0000
MODIFICATION HISTORY:
Amara Graps, BAER, December 1994.
(c) copyright Amara Graps 1995, 1996
(See /home/drw/idl/wwbsrc/wsum.pro)
WSURETHR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSURETHR
PURPOSE:
To perform adaptive threshold selection
using principle of Stein's Unbiased Risk Estimate (SURE)
CATEGORY:
Wavelets.
CALLING SEQUENCE:
x = WSURETHR(y, thresh)
INPUTS:
y = Noisy Data with Std. Deviation = 1
OUTPUTS:
thresh = Threshold used
x = Estimate of mean vector
EXAMPLE:
SEE ALSO:
whardthr, wsurethr, wdoshrnk
MODIFICATION HISTORY:
Written by: Amara Graps September, 1995
Translated from MatLab Wavelab routine: surethresh.m
(See /home/drw/idl/wwbsrc/wsurethr.pro)
WSWHERE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WSWHERE
PURPOSE:
Same as 'where' function, except always returns a scalar,
never a vector.
CATEGORY:
array
CALLING SEQUENCE:
r = WSWHERE(v)
INPUTS:
v = variable to use 'where' on
OUTPUTS:
r = return code
if where(v) is a scalar, r = where(v)
if where(v) is a vector, r = w(0), where w = where(v)
RESTRICTIONS:
Object and search_string must be of type string.
REQUIRED ROUTINES:
IDL Library: where, size, lonarr
MODIFICATION HISTORY:
T.Atwater 910510 -- Created
Renamed from swhere.pro by Amara Graps for Wavelet Workbench, March 1996.
(See /home/drw/idl/wwbsrc/wswhere.pro)
WTC
[Previous Routine]
[Next Routine]
[List of Routines]
This routine handles the events from the Wavelet Transform
Compression Widget.
(See /home/drw/idl/wwbsrc/wtc.pro)
WTC2
[Previous Routine]
[Next Routine]
[List of Routines]
This routine handles the events from the 2D Wavelet Transform
Compression Widget.
(See /home/drw/idl/wwbsrc/wtc2.pro)
WTREEHGT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WTREEHGT
PURPOSE:
To measure the total height of a stat-tree.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
maxheight = WTREEHGT(stree,D, cost)
INPUTS:
stree = stat tree (e.g. generated by WSTATREE)
D = maximum depth of search
OUTPUTS:
maxheight = Height of the tree, assigning each branch
a length equal to the entropy drop between parent and child
cost = Tree of entropy drops associated with various splits
NOTES:
This is a utility used by WPLBTREE to set scale for plotting
It is not intended for other use.
EXAMPLE:
SEE ALSO:
wstatree, wplbtree
MODIFICATION HISTORY:
Written by: Amara Graps December 1994
Translated from MatLab Wavelab routine: calctreeheight.pro
(See /home/drw/idl/wwbsrc/wtreehgt.pro)
WULKAXES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WULKAXES
PURPOSE:
This procedure gets rid of the previously-set {xmin,xmax}{ymin,ymax} on the plot.
CATEGORY:
Plotting
CALLING SEQUENCE:
WULKAXES
INPUTS:
None
OUTPUTS:
The x and y limits are set to automatic scaling
SEE ALSO:
wlckaxes
MODIFICATION HISTORY:
Written by: Amara Graps August, 1995
Translated from MatLab Wavelab routine: unlockaxes.m
(See /home/drw/idl/wwbsrc/wulkaxes.pro)
WUPDYDHI
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WUPDYDHI
PURPOSE:
This function performs a Hi-Pass Upsampling operation; periodized.
CATEGORY:
Wavelets
CALLING SEQUENCE:
y = WUPDYDHI(x,qmf)
INPUTS:
x: A 1-d signal at coarser scale.
qmf: quadrature filter
OUTPUTS:
y: A 1-d signal at finer scale
EXAMPLE:
SEE ALSO:
wdndydlo, wdndydhi, wupdydlo, wiwtpo, waconv
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: updyadhi.m
(See /home/drw/idl/wwbsrc/wupdydhi.pro)
WUPDYDLO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WUPDYDLO
PURPOSE:
This function performs a Lo-Pass Upsampling operation; periodized.
CATEGORY:
Wavelets
CALLING SEQUENCE:
u = WUPDYDLO(d,f)
INPUTS:
x: A 1-d signal at finer scale.
qmf: quadrature mirror filter
OUTPUTS:
y: A 1-d signal at coarser scale
EXAMPLE:
SEE ALSO:
wdndydhi, wdndydlo, wupdydhi, wiwtpo, waconv
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: updyadlo.m
(See /home/drw/idl/wwbsrc/wupdydlo.pro)
WUPKCOEF
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WUPKCOEF
PURPOSE:
This function extracts the basis coefficients from packet table.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
x = WUPKCOEF(basis,wp)
INPUTS:
basis = basis tree
wp = packet table (wavelet- or cosine-)
OUTPUTS:
x = coefficients of signal in that basis
MODIFICATION HISTORY:
Written by: Amara Graps September, 1995
Translated from MatLab Wavelab routine: unpackbasiscoeff.m
(See /home/drw/idl/wwbsrc/wupkcoef.pro)
WUPSMPLE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WUPSMPLE
PURPOSE:
This function performs an upsampling operation.
CATEGORY:
Wavelets
CALLING SEQUENCE:
y = WUPSMPLE(x)
INPUTS:
x: 1-d signal, of length n
OUTPUTS:
y: 1-d signal, of length 2*n with zeros
interpolating alternate samples
y(2*i-2) = x(i-1), i=1 ..n
EXAMPLE:
SEE ALSO:
wdndydhi, wdndydlo, wupdydhi, wiwtpo, waconv
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
Translated from MatLab Wavelab routine: upsample.m
(See /home/drw/idl/wwbsrc/wupsmple.pro)
WVALSTHR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WVALSTHR
PURPOSE:
To perform adaptive threshold selection
using principle of Stein's Unbiased Risk Estimate (SURE)
CATEGORY:
Wavelets.
CALLING SEQUENCE:
thresh = WVALSTHR(x)
INPUTS:
x = Noisy Data with Std. Deviation = 1
OUTPUTS:
thresh = Value of Threshold
EXAMPLE:
SEE ALSO:
wsoftthr, wsurethr, wdoshrnk
MODIFICATION HISTORY:
Written by: Amara Graps December, 1994
Translated from MatLab Wavelab routine: valsurethresh.m
(See /home/drw/idl/wwbsrc/wvalsthr.pro)
WVISUTHR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WVISUTHR
PURPOSE:
To perform visually calibrated adaptive smoothing.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
x = WVISUTHR(y, TThresh)
INPUTS:
y = data array
TThresh = Type of Visu Thresholding:
= 1 (Hard) or = 2 (Soft)
OUTPUTS:
x = data array thresholded
EXAMPLE:
SEE ALSO:
WHARDTHR, WSOFTTHR, WDOSHRNK
NOTES:
See article ``Ideal Spatial Adaptation via Wavelet Shrinkage''
By D.L. Donoho and I.M. Johnstone
MODIFICATION HISTORY:
Written by: Amara Graps September 1995
Translated from MatLab Wavelab routine: visuthresh.m
(See /home/drw/idl/wwbsrc/wvisuthr.pro)
WVLOADCT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WVLOADCT
PURPOSE:
This procedure sets up the color table and color variables
used in the WaveLab plotting routines.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WVLOADCT, col_table
INPUTS:
col_table: integer
OUTPUTS:
Color table and color variables set (put in COMMON)
EXAMPLE:
WVLOADCT, 1
(Loading table BLUE/WHITE)
NOTES:
Put the following common block in your program to use the
pre-defined color variables
(i.e., the call: PLOT, x, color = yellow should work).
COMMON Wave_color, $
max_color, max_image, $
white, yellow, lavender, aqua, pink, green, red, orange, blue, $
lt_gray, med_green, brown, olive, purple, dk_gray, black
MODIFICATION HISTORY:
Written by: Amara Graps November, 1994
(lifted from IDL's tour_loadct.pro)
(See /home/drw/idl/wwbsrc/wvloadct.pro)
WWB
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WWB
PURPOSE:
This procedure sets up runs the event loop for
the Wavelet Workbench functions.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
WWB
INPUTS:
The user must specify what path the wavelets directory routines
are located at. A query is made in the IDL window when the user
calls the wwb procedure.
OUTPUTS:
This procedure runs the wavelet data input as well as the actions
performed on the data.
COMMON BLOCKS:
CWAVE: The block for passing the Wavelet Type (string: 'Haar' etc.)
CPAR: The block for passing the Wavelet Parameter for the
wavelet (integer)
TEXT_ANNOUNCE: The block for passing the widget that present
messages as well as other important wavelet parameters such
as the data array (sig), the data array length(len), a string
describing the data (st) and the current chosen quadrature mirror
filter (QMF).
MODIFICATION HISTORY:
Written by: Amara Graps, August/September 1995.
(See /home/drw/idl/wwbsrc/wwb.pro)
WWBDIR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WWBDIR
PURPOSE:
This procedure sets up the location of the directory of
Wavelet Workbench (WWB), so that the 1D and 2D data files
can be found and loaded into the program menu.
CATEGORY:
Wavelets
CALLING SEQUENCE:
WWBDIR
INPUTS: (via COMMON)
OUTPUTS:
wd = working directory. This value is output in the form of a
common block variable in WWB_COMMON
COMMON BLOCKS:
COMMON WWB_COMMON, $
TEXT_ANNOUNCE, wd, sig, len, st, noise_type, noise_lev, $
QMF, LD, shrinkage_type, WaveType, ParVal
MODIFICATION HISTORY:
Written by: Amara Graps, September 1995.
copyright (c) Amara Graps 1995, 1996.
(See /home/drw/idl/wwbsrc/wwbdir.pro)
WWPLOC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
WWPLOC
PURPOSE:
This function calculates location of wavelet packet entry.
CATEGORY:
Wavelets.
CALLING SEQUENCE:
pos = WWPLOC(d,b,k,qmf,n)
INPUTS:
d = depth index
b = block index
k = coef index
qmf = qmf filter
n = signal length
OUTPUTS:
pos = position in wp data structure
MODIFICATION HISTORY:
Written by: Amara Graps November, 1995
Translated from MatLab Wavelab routine: calcwplocation.m
(See /home/drw/idl/wwbsrc/wwploc.pro)
X2BMP
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SDAC
Name : X2BMP
Purpose : read and write X window to GIF file
Explanation : Uses TVRD to grab window
Use : X2BMP,FILE
Inputs : FILE = BMP file name
Opt. Inputs : R, G, B = color table values
Outputs : None.
Opt. Outputs: None.
Keywords :
WINDOW = index of window to be plotted
XSIZE, YSIZE = window size to select [def = whole window]
TITLE = title for GIF file
XPOS, YPOS = position of title
PSIZE = extra keywords for xyouts
RESIZE = [nx,ny] = dimensions to resize GIF image to
Calls : None.
Common : None.
Restrictions: None.
Side effects: None.
Category : Graphics
Prev. Hist. : None.
Written : Dominic Zarro (ARC)
Version : Version 1.0, 1 July 1994
(See /home/drw/idl/aux/x2bmp.pro)
XAGAUSSFIT
[Previous Routine]
[Next Routine]
[List of Routines]
xagaussfit
Interactive widget to fit multiple multiplicative absorption Gaussians
I.E. the routine fits Fits
y = C*A1*A2*...*A8
where:
C is the continuum flux defined by:
C = b0 + b1*x + b2*x^2
Ai are the absorption lines with the form (i = 0 to 7)
Ai = exp(-a0*Gi)
Gi are Gaussians:
Gi = exp(-[(x-a1)/a2]^2/2.0)
CALLING SEQUENCE
xagaussfit,xvector,yvector,bcoef,gcoef,fit,mask=mask
INPUTS:
xvector - X vector
yvector - Y vector
OUTPUTS:
bcoef - coefficients for the polynomial baseline
gcoef - 3 x ngaussian coefficients for the fitted Gaussians
gcoef(0,*) = a0
gcoef(1,*) = a1 (centers)
gcoef(2,*) = a2 (Gaussian sigmas)
fit - fit evaluated at x vector
OPTIONAL KEYWORD INPUTS:
title - plot title
xtitle - x plot title
ytitle - y plot title
group - widget id of the group leader
modal - set to make widget modal
OPTIONAL KEYWORD INPUT/OUTPUTS:
mask - mask vector (1 for good data, 0 for bad data)
HISTORY:
version 1 D. Lindler Aug 1999
Aug 2000, D. Lindler, Changed from curvefit to lmfit. added
manual continuum button, added ability to fix coefficients
(See /home/drw/idl/fuse/xagaussfit.pro)
XAXIS_MONTH[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xaxis_month
PURPOSE: label x axis with month names when the x axis plot quantity
is day of year
USEAGE: xaxis_month,year
INPUT:
year year, reqiured to set leap year calendar. if not set a
non-leap-year is used.
OUTPUT: none
SIDE EFFECTS:
draws in the x axis with month labels and tick marks
between months
EXAMPLE:
x=indgen(365)+1
zensun,x,12,35,0,zen
plot,x,zen,xstyle=5,title='solar zenith angle',ytitle='zenith'
xaxis_month
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/xaxis_month.pro)
XAXIS_MONTH[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xaxis_month
PURPOSE: label x axis with month names when the x axis plot quantity
is day of year
USEAGE: xaxis_month,year
INPUT:
year year, reqiured to set leap year calendar. if not set a
non-leap-year is used.
OUTPUT: none
SIDE EFFECTS:
draws in the x axis with month labels and tick marks
between months
EXAMPLE:
x=indgen(365)+1
zensun,x,12,35,0,zen
plot,x,zen,xstyle=5,title='solar zenith angle',ytitle='zenith'
xaxis_month
REVISIONS:
author: Paul Ricchiazzi jan94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/xaxis_month.pro)
XCD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
xcd
PURPOSE:
Change current directory via mouse.
Two lists are displayed side by side. The one on the left shows
directories. Click on a directory to cd there. The list
on the right shows files to help you see where you are.
(The list on the right does not respond to mouse clicks.)
CATEGORY:
Utility.
CALLING SEQUENCE:
xcd
INPUTS:
None.
KEYWORD PARAMETERS:
None
OUTPUTS:
None.
SIDE EFFECTS:
Your current directory can be changed.
RESTRICTIONS:
Windows & OpenVMS platforms only. Originally written on Windows95.
Should work on other Windows platforms, but I (Paul) havn't tried it.
With a little effort, one probably could port Xcd to other platforms
(i.e. Unix or Mac).
Note that drive names (e.g. "a:", "c:", etc.) are hardcoded in
xcd::init. Change that line of code to show drive letters
appropriate for your system.
PROCEDURE:
Xcd creates an object that has a reference to a DirListing, and
widgets for displaying that DirListing. If the user clicks on a
sub-directory (or "..\") in the xcd object, or droplist-selects
a different drive via the xcd object, the xcd object changes
IDL's current directory to that location, and refreshes with a
new current-directory DirListing.
MODIFICATION HISTORY:
Paul C. Sorenson, July 1997. paulcs@netcom.com.
Written with IDL 5.0. The object-oriented design of Xcd is
based in part on an example authored by Mark Rivers.
Jim Pendleton, July 1997. jimp@rsinc.com
Modified for compatability with OpenVMS as a basis for
platform independent code
Paul C. Sorenson, July 13 1997. Changes so that DirListing class
methods do not return pointers to data members. (Better
object-oriented design that way.)
(See /home/drw/idl/aux/xcd.pro)
XCOLORS
[Previous Routine]
[Next Routine]
[List of Routines]
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. The
event handler, object method, or IDL procedure is then responsibe
for updating the program's display on 16- or 24-bit display systems.
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.
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.
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. If 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.
_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.
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.
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.N_COLORS < 256), G:BytArr(!D.N_COLORS < 256), $
B:BytArr(!D.N_COLORS < 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.
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.
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 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.
(See /home/drw/idl/aux/xcolors.pro)
XCONTOUR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XCONTOUR
PURPOSE:
The purpose of this program is to demonstrate how to
create a contour plot with axes and a title in the
new IDL 5 object graphics.
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, IDL 5 Object Graphics.
CALLING SEQUENCE:
XCONTOUR, 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 old IDL contour command. Most of the keywords will
have absolutely no effect.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
NLEVELS: The number of equally spaced contour intervals to draw.
Default is 10. Note that contour levels are acutally calculated,
since the NLEVELS keyword to the contour object does not always
result in the correct number of contour levels.
TITLE: A string used as the title of the plot.
XTITLE: A string used as the X title of the plot.
YTITLE: A string used as the Y title of the plot.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To use this program with your 2D data, type:
IDL> XContour, data
MODIFICATION HISTORY:
Written by David Fanning, 9 June 97.
Added a colorbar to the plot. 19 June 97, DWF.
Modified the way VCOLORBAR was called. 14 July 97. DWF.
Fixed cleanup procedure to clean up ALL objects. 12 Feb 98. DWF.
Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
Modified to use the IDLgrColorbar object. 20 Sept 98. DWF.
Added the ability to do a filled contour. 27 Sept 98. DWF.
Fixed a bug in the way the data was scaled into the view. 9 May 99. DWF.
Fixed a bug in the filled contours. 11 May 99. DWF.
Added a line to make sure 256 colors are available in Z buffer. 19 Dec 99. DWF.
Fixed a small bug where the X and Y vectors weren't sent to IDLgrContour. 19 Sept 2000. DWF.
(See /home/drw/idl/aux/xcontour.pro)
XDATENT[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xdatent
PURPOSE: widget for text data entry.
USEAGE: xdatent,labels,value,ncol=ncol,group=group
INPUT:
labels string array of labels for data entry field
KEYWORD INPUT:
ncol number of columns of data entry fields
font text font to use
group group leader widget, when this widget dies, so does xdatent
INPUT/OUTPUT
value float, double, long or int array of values
on input: used to set default values
on exit: edited values
COMMON BLOCKS:
xdatentblk
EXAMPLE:
labels=['min latitude','max latitude','min longitude','max longitude']
value=[30.,40.,-130.,-120.]
xdatent,labels,value,ncol=2
table,labels,value
; NOTE: the input focus can be moved by hitting the tab key.
AUTHOR: Paul Ricchiazzi 05 Jul 95
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/esrg/xdatent.pro)
XDATENT[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xdatent
PURPOSE: widget for text data entry.
USEAGE: xdatent,labels,value,ncol=ncol,group=group
INPUT:
labels string array of labels for data entry field
KEYWORD INPUT:
ncol number of columns of data entry fields
font text font to use
group group leader widget, when this widget dies, so does xdatent
INPUT/OUTPUT
value float, double, long or int array of values
on input: used to set default values
on exit: edited values
COMMON BLOCKS:
xdatentblk
EXAMPLE:
labels=['min latitude','max latitude','min longitude','max longitude']
value=[30.,40.,-130.,-120.]
xdatent,labels,value,ncol=2
table,labels,value
; NOTE: the input focus can be moved by hitting the tab key.
AUTHOR: Paul Ricchiazzi 05 Jul 95
Institute for Computational Earth System Science
University of California, Santa Barbara
REVISIONS:
(See /home/drw/idl/old.esrg/xdatent.pro)
XDICE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XDICE
PURPOSE:
The primary purpose of this routine is to serve as an example for
the Widgets chapter of the IDL User`s Guide. It uses the CW_DICE
compound widget (also written as an example) to present a pair
of dice.
CATEGORY:
Widgets
CALLING SEQUENCE:
XDICE
INPUTS:
No explicit inputs.
KEYWORD PARAMETERS:
GROUP - Group leader, as passed to XMANAGER.
OUTPUTS:
None.
PROCEDURE:
Two dice are presented, along with "Done" and "Roll" buttons.
Pressing either dice rolls that dice. pressing the Roll
button rolls both dice.
A label widget at the bottom displays the current dice values.
Press "Done" to kill the application.
MODIFICATION HISTORY:
24 October 1993, AB, RSI
(See /home/drw/idl/moses/xdice.pro)
XFWINDOW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XFWINDOW
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:
Intelligent replacement for built-in WINDOW procedure (Unix)
MAJOR TOPICS:
Widgets, Graphics.
CALLING SEQUENCE:
XFWINDOW, WINDOW_INDEX, RETAIN=retain, TITLE=title, $
XPOS=xpos, YPOS=ypos, XSIZE=xsize, YSIZE=ysize, [ /INIT ]
DESCRIPTION:
XFWINDOW is an intelligent replacement for the normal direct
graphics window of IDL. XFWINDOW uses the XFILTER library to
store and replay graphics commands. This makes it easy to make
interactive graphics and then send the output to a postscript file
or printer.
XFWINDOW is currently only usable on IDL versions 5.1 and greater,
under the following (Unix only) systems: SunOS, Solaris/Sparc, SGI
IRIX, DEC Alpha Unix and Linux.
Normally, XFWINDOW is run from the command line, and brings up a
graphics widget running in "NO_BLOCK" mode. This allows you to
execute graphics commands and the IDL command prompt while the
widget is still on the screen.
All graphics commands which produce output on the window are
stored in memory cache. Any command that causes the window to be
erased also clears the cache. The memory cache thus represents a
faithful representation of the screen. *However*, the cache does
not store system variables such as !P, !X, !Y, or the colormap, so
any changes to those variables cannot be reproduced.
The graphics window that is displayed is normal in almost every
sense. Therefore all of the standard graphics commands will work
with it unmodified. When you wish to delete the window, you can
either choose the menu "Close" selection or issue a "wdelete, win"
command at the prompt.
At the top of the draw window is a button bar, displayed as
follows:
|Configure| |Output To| o File __________ o Printer ___________
You can output the current graphics screen to a file or printer
(or both) queue at any time using the "Output To" button. The
choice of output destinations is decided by whether the "File" or
"Printer" buttons are checked.
You can choose a new file name or printer name (if not the
default) by filling in either the File or Printer boxes with a new
name. Output is to postscript files/printers only.
The "Configure" menu allows you to perform more advanced
configurations. Configure | Postscript allows you to select a
print layout, while Configure | Colors allows you to select a new
color map.
XFWINDOW is not particularly suited for situations where there are
many, many graphics commands comprising a plot, or if the data
involved in each command is very large. In that case it may be
possible to exhaust IDL's memory. In such cases it is best to
*not* use XFWINDOW and instead generate a script to reproduce your
graphics.
PARAMETERS:
WINDOW_INDEX - This is an output parameter only. XWINDOW
allocates a new graphic window from the "FREE" pool
(window numbers greater than 32) and returns the
window number in this variable. A value of -1
indicates that the window was not successfully
created.
You *cannot* request a window number to be used.
Any window number passed as input to WINDOW_INDEX
is ignored and overwritten.
INPUT KEYWORD PARAMETERS:
RETAIN - Specifies how the window backing store is maintained.
[See IDL documentation for information on backing store.]
Set this keyword to 0, 1 or 2 according to the following
table. The default value is 1.
0 - no backing store is provided
1 - window system is requested to provide backing
store (it may or may not actually provide it).
2 - IDL will provide backing store.
TITLE - Specifies a the title for the new window. By default the
window is given a title "XFWindow NN" where NN is the draw
window number.
XSIZE - Horizontal size of draw window in pixels. The size cannot
be smaller than the button bar. [ XFWINDOW will adjust
the size upward if needed. ] Default is 500 pixels.
YSIZE - Vertical size of draw window in pixels. Default is 400
pixels.
XPOS - X position of upper left hand corner of window on screen.
YPOS - Y position of upper left hand corner of window on screen.
NO_PRINT - set this keyword to disable the "Print" portion of the
window adornments.
NOTE: you can't disable both "Print" and "File" parts.
NO_FILE - set this keyword to disable the "File" portion of the
window adornments.
NOTE: you can't disable both "Print" and "File" parts.
INIT - Set this keyword to load the XFILTER shared library only.
No windows are displayed.
LPR - a string, the path of the Unix print command. Default:
'lpr'
SCRATCH_DIR - a string, the path of a Unix scratch
directory. Default: '/var/tmp'
MODIFICATION HISTORY:
Written, Aug-Sep 1999, CM
Merged in TVIMAGE and CMCONGRID, Sep 19, 1999
(See /home/drw/idl/aux/xfilter/xfwindow.pro)
XGAUSSFIT
[Previous Routine]
[Next Routine]
[List of Routines]
xgaussfit
Interactive widget to fit multiple Gaussians
CALLING SEQUENCE
xgaussfit,xvector,yvector,bcoef,gcoef,mask=mask
INPUTS:
xvector - X vector
yvector - Y vector
OUTPUTS:
bcoef - coefficients for the polynomial baseline
gcoef - 3 x ngaussian coefficients for the fitted Gaussians
gcoef(0,*) = Peaks
gcoef(1,*) = centers
gcoef(2,*) = sigmas
fit - fit evaluated at x vector
OPTIONAL KEYWORD INPUTS:
title - plot title
xtitle - x plot title
ytitle - y plot title
group - widget id of the group leader
/noguess - set keyword so that an initial guess of the guassian is
not made
modal - set to make widget modal
OPTIONAL KEYWORD INPUT/OUTPUTS:
mask - mask vector (1 for good data, 0 for bad data)
HISTORY:
version 1 D. Lindler Aug 1999
(See /home/drw/idl/fuse/xgaussfit.pro)
XGLOBE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: XGLOBE
USEAGE: XGLOBE
PURPOSE: Display a world map and allow user to zoom in on a given region
INPUT: none
OUTPUT: none
BUTTONS:
DONE quit XGLOBE
ZOOM Pull down menu
ZOOM IN: The IDL routine BOX_CURSOR is used to select the region.
use left mouse button to point and drag the cursor box
use middle mouse button to resize cursor box
use right mouse to select region and draw the map
To reduce distortion on zoomed regions near the poles
it is a good idea to choose a short, wide map region.
ZOOM OUT: The latitude and longitude limits are increased by 20% and
the map is redrawn.
WORLD: Redisplay world map (equivalent to hitting ZOOM OUT many times)
PLOT: Replot map with current lat-lon limits.
PRINT Pull down menu
TERM: Print current map to device TERM
GAUTIER: print current map to device GAUTIER
PHASER: print current map to device PHASER (color plots)
DUP: print current map to device DUP
COLOR Pull down menu
CONTINENTS: adjust color value of continental boundaries
US STATE: adjust color value of US state boundaries
POLITICAL: adjust color value of political boundaries
RIVERS: adjust color value of rivers
NOTE: Each of these options use the procedure PICK_COLOR
to adjust the color value for a single color index.
Motion of the cursor inside the PICK_COLOR window
adjusts the Hue and Saturation values.
Holding down the left mouse button decreases brightness.
Holding down the middle mouse button increases brightness.
Pressing the right mouse button selects the color and returns.
HELP print this help file
TEXT WIDGET (labeled WHERE IS:)
Enter the latititude longitude
A symbol is drawn to indicate point on map.
NOTE: the code will bomb if you mess up the format
DRAW WIDGET The lat-lon coordinates under the cursor are
printed when the left mouse button is held down
(This feature is disabled in "ZOOM IN" region selection
mode)
author: Paul Ricchiazzi DEC92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/xglobe.pro)
XGLOBE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: XGLOBE
USEAGE: XGLOBE
PURPOSE: Display a world map and allow user to zoom in on a given region
INPUT: none
OUTPUT: none
BUTTONS:
DONE quit XGLOBE
ZOOM Pull down menu
ZOOM IN: The IDL routine BOX_CURSOR is used to select the region.
use left mouse button to point and drag the cursor box
use middle mouse button to resize cursor box
use right mouse to select region and draw the map
To reduce distortion on zoomed regions near the poles
it is a good idea to choose a short, wide map region.
ZOOM OUT: The latitude and longitude limits are increased by 20% and
the map is redrawn.
WORLD: Redisplay world map (equivalent to hitting ZOOM OUT many times)
PLOT: Replot map with current lat-lon limits.
PRINT Pull down menu
TERM: Print current map to device TERM
GAUTIER: print current map to device GAUTIER
PHASER: print current map to device PHASER (color plots)
DUP: print current map to device DUP
COLOR Pull down menu
CONTINENTS: adjust color value of continental boundaries
US STATE: adjust color value of US state boundaries
POLITICAL: adjust color value of political boundaries
RIVERS: adjust color value of rivers
NOTE: Each of these options use the procedure PICK_COLOR
to adjust the color value for a single color index.
Motion of the cursor inside the PICK_COLOR window
adjusts the Hue and Saturation values.
Holding down the left mouse button decreases brightness.
Holding down the middle mouse button increases brightness.
Pressing the right mouse button selects the color and returns.
HELP print this help file
TEXT WIDGET (labeled WHERE IS:)
Enter the latititude longitude
A symbol is drawn to indicate point on map.
NOTE: the code will bomb if you mess up the format
DRAW WIDGET The lat-lon coordinates under the cursor are
printed when the left mouse button is held down
(This feature is disabled in "ZOOM IN" region selection
mode)
author: Paul Ricchiazzi DEC92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/xglobe.pro)
XHELP[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
xhelp
PURPOSE:
Display an IDL procedure header using widgets and the widget manager.
CATEGORY:
Widgets.
CALLING SEQUENCE:
xhelp, Filename, TITLE = TITLE, GROUP = GROUP, WIDTH = WIDTH, $
HEIGHT = HEIGHT, TEXT = TEXT, FONT = font, unmanaged=unmanaged
INPUTS:
Filename: A scalar string that contains the filename of the file
to display. If FILENAME does not include a complete path
specification, xhelp will search for the file in
the current working directory and then each of the
directories listed in !PATH environment variable. The
".pro" file suffix will be appended if it is not supplied.
KEYWORD PARAMETERS:
FONT: The name of the font to use. If omitted use the default
font. If font is set to 1 then a fixed width font is used:
"-misc-fixed-bold-r-normal--13-120-75-75-c-80-iso8859-1"
GROUP: The widget ID of the group leader of the widget. If this
keyword is specified, the death of the group leader results in
the death of xhelp.
HEIGHT: The number of text lines that the widget should display at one
time. If this keyword is not specified, 24 lines is the
default.
TEXT: A string or string array to be displayed in the widget
instead of the contents of a file. This keyword supercedes
the FILENAME input parameter.
TITLE: A string to use as the widget title rather than the file name
or "xhelp".
WIDTH: The number of characters wide the widget should be. If this
keyword is not specified, XHELP checks the input file for
the maximum line length.
UNMANAGED: do not call xmanager and do not include a "DONE" button
on the widget. In this case the x window manager must be
used to kill the widget.
OUTPUTS:
No explicit outputs. A file viewing widget is created.
SIDE EFFECTS:
Triggers the XMANAGER if it is not already in use.
RESTRICTIONS:
None.
PROCEDURE:
Open a file and create a widget to display its contents.
MODIFICATION HISTORY:
Written By Steve Richards, December 1990
Graceful error recovery, DMS, Feb, 1992.
Modified to extract .pro documentation headers, PJR/ESRG mar94
author: Paul Ricchiazzi jun93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/xhelp.pro)
XHELP[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
xhelp
PURPOSE:
Display an IDL procedure header using widgets and the widget manager.
CATEGORY:
Widgets.
CALLING SEQUENCE:
xhelp, Filename
INPUTS:
Filename: A scalar string that contains the filename of the file
to display. If FILENAME does not include a complete path
specification, xhelp will search for the file in
the current working directory and then each of the
directories listed in !PATH environment variable. The
".pro" file suffix will be appended if it is not supplied.
KEYWORD PARAMETERS:
FONT: The name of the font to use. If omitted use the default
font. If font is set to 1 then a fixed width font is used:
"-misc-fixed-bold-r-normal--13-120-75-75-c-80-iso8859-1"
GROUP: The widget ID of the group leader of the widget. If this
keyword is specified, the death of the group leader results in
the death of xhelp.
HEIGHT: The number of text lines that the widget should display at one
time. If this keyword is not specified, 24 lines is the
default.
TEXT: A string or string array to be displayed in the widget
instead of the contents of a file. This keyword supercedes
the FILENAME input parameter.
TITLE: A string to use as the widget title rather than the file name
or "xhelp".
WIDTH: The number of characters wide the widget should be. If this
keyword is not specified, 80 characters is the default.
UNMANAGED: do not call xmanager and do not include a "DONE" button
on the widget. In this case the x window manager must be
used to kill the widget.
OUTPUTS:
No explicit outputs. A file viewing widget is created.
SIDE EFFECTS:
Triggers the XMANAGER if it is not already in use.
RESTRICTIONS:
None.
PROCEDURE:
Open a file and create a widget to display its contents.
MODIFICATION HISTORY:
Written By Steve Richards, December 1990
Graceful error recovery, DMS, Feb, 1992.
Modified to extract .pro documentation headers, PJR/ESRG mar94
author: Paul Ricchiazzi jun93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/xhelp.pro)
XIMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XIMAGE
PURPOSE:
The purpose of this program is to demonstrate how to
create a image plot with axes and a title in the
new IDL 5 object graphics.
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:
XImage, image
REQUIRED INPUTS:
None. The image "worldelv.dat" from the examples/data directory
is used if no data is supplied in call.
OPTIONAL INPUTS
image: A 2D or 3D image array.
OPTIONAL KEYWORD PARAMETERS:
COLORTABLE: The number of a color table to use as the image palette.
Color table 0 (grayscale) is used as a default.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
KEEP_ASPECT_RATIO: Set this keyword if you wish the aspect ratio
of the image to be preserved as the graphics display window is resized.
SIZE: The initial window size. Default is 300 by 300 pixels.
TITLE: A string used as the title of the plot.
XRANGE: A two-element array specifying the X axis range.
XTITLE: A string used as the X title of the plot.
YRANGE: A two-element array specifying the Y axis range.
YTITLE: A string used as the Y title of the plot.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To use this program with your 2D or 3D image data, type:
IDL> XImage, image
MODIFICATION HISTORY:
Written by David Fanning, 13 June 97.
Added Keep_Apect_Ratio keyword and Zoom buttons. DWF 15 JUNE 97.
Improved font handling and color support. DWF 4 OCT 97.
Fixed memory leakage from improper object cleanup. 12 FEB 98. DWF
Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
Modified program to show how image values can be selected. 8 May 2000. DWF.
Made several modifications to resize event handler. Much improved. 2 June 2000. DWF.
(See /home/drw/idl/aux/ximage.pro)
XLESS[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xless
PURPOSE: create a text widget to scroll through a string array or
a file
USEAGE: xless,text,file=file,space=space,xsize=xsize,ysize=ysize,$
xpad=xpad,ypad=ypad,title=title,font=font,group=group,$
unmanaged=unmanaged
INPUT:
text string array containing text. if TEXT is set FILE is ignored
KEYWORD INPUT:
file pathname of text file to display
space space to put around text widget
xsize x size of text widget (characters)
ysize y size of text widget (lines)
xpad padding
ypad padding
title title of text widget (default = XLESS)
font text font to use
group widget group leader
unmanaged don't put widget under control of the XMANAGER. This
also means there will be no DONE button: to kill the widget
use a XWINDOW manager command (EG, menu option "close")
OUTPUT:
none
EXAMPLE:
; list a string array
text=string(indgen(40)) & text(*)=text(*)+' this is a test'
xless,text
xless,text,/unman ; notice how control returns to the terminal
; imediately after this command
; list a file
xless,file=pickfile(/noconfirm)
REVISIONS:
author: Paul Ricchiazzi Jul94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/xless.pro)
XLESS[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xless
PURPOSE: create a text widget to scroll through a string array or
a file
USEAGE: xless,text,file=file,space=space,xsize=xsize,ysize=ysize,$
xpad=xpad,ypad=ypad,title=title,font=font,group=group,$
unmanaged=unmanaged
INPUT:
text string array containing text. if TEXT is set FILE is ignored
KEYWORD INPUT:
file pathname of text file to display
space space to put around text widget
xsize x size of text widget (characters)
ysize y size of text widget (lines)
xpad padding
ypad padding
title title of text widget (default = XLESS)
font text font to use
group widget group leader
unmanaged don't put widget under control of the XMANAGER. This
also means there will be no DONE button: to kill the widget
use a XWINDOW manager command (EG, menu option "close")
OUTPUT:
none
EXAMPLE:
; list a string array
text=string(indgen(40)) & text(*)=text(*)+' this is a test'
xless,text
xless,text,/unman ; notice how control returns to the terminal
; imediately after this command
; list a file
xless,file=pickfile(/noconfirm)
REVISIONS:
author: Paul Ricchiazzi Jul94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/xless.pro)
XLIST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XLIST
PURPOSE:
Pop-up list selection widget.
CATEGORY:
CALLING SEQUENCE:
out = xlist(list)
INPUTS:
list = string array of possible selections. in
KEYWORD PARAMETERS:
Keywords:
TITLE=txt title text or text array (def=Select item).
MAXSCOLL=n Max allowed lines before scrolling list used
(def=20).
/WAIT means wait for a selection before returning.
Needed if called from another widget routine.
OUTPUTS:
out = selected element. out
Null if Cancel button pressed.
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 11 Nov, 1993
Copyright (C) 1993, 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.
(See /home/drw/idl/esrg/xlist.pro)
XMAKEDRAW[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xmakedraw
PURPOSE: create a simple draw widget with a done button
USEAGE: xmakedraw,group=group,x_window_size=x_window_size,$
y_window_size=y_window_size,widget_label=widget_label,$
make_draw_index=make_draw_index,nowait=nowait
INPUT: none required
KEYWORD INPUT:
group widget id of parent widget
x_window_size width of draw widget
y_window_size height of draw widget
widget_label widget label
base_id widget id of base widget
nowait if set do not call xmanager, return immediately
after draw widget is realized
This keyword should be used when XMAKEDRAW is
not called by another widget procedure (see example)
EXAMPLE:
; called from non-widget application (e.g., interactive input)
xmakedraw,base_id=base_id,x_w=500,y_w=500,/nowait
!p.multi=[0,2,2]
loadct,5
plot,dist(10)
tvim,dist(100)
plot,hanning(10,10)
tvim,hanning(10,10)
xmanager,'xmakedraw',base_id
; in this example control is returned from the XMANAGER routine only
; after the operator hits the DONE button. If instead, this program
; segment were called from another widget application, the highest
; level call to the XMANAGER would supercede all lower level calls.
; That is, program flow in not halted and normal widget event
; processing would continue. In this case the NOWAIT parameter should
; not be set and the call to XMANAGER is not required.
Author: Jeff Hicke sep93
Earth Space Research Group, UC Santa Barbara
(See /home/drw/idl/esrg/xmakedraw.pro)
XMAKEDRAW[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xmakedraw
PURPOSE: create a simple draw widget with a done button
USEAGE: xmakedraw,group=group,x_window_size=x_window_size,$
y_window_size=y_window_size,widget_label=widget_label,$
make_draw_index=make_draw_index,nowait=nowait
INPUT: none required
KEYWORD INPUT:
group widget id of parent widget
x_window_size width of draw widget
y_window_size height of draw widget
widget_label widget label
base_id widget id of base widget
nowait if set do not call xmanager, return immediately
after draw widget is realized
This keyword should be used when XMAKEDRAW is
not called by another widget procedure (see example)
EXAMPLE:
; called from non-widget application (e.g., interactive input)
xmakedraw,base_id=base_id,x_w=500,y_w=500,/nowait
!p.multi=[0,2,2]
loadct,5
plot,dist(10)
tvim,dist(100)
plot,hanning(10,10)
tvim,hanning(10,10)
xmanager,'xmakedraw',base_id
; in this example control is returned from the XMANAGER routine only
; after the operator hits the DONE button. If instead, this program
; segment were called from another widget application, the highest
; level call to the XMANAGER would supercede all lower level calls.
; That is, program flow in not halted and normal widget event
; processing would continue. In this case the NOWAIT parameter should
; not be set and the call to XMANAGER is not required.
Author: Jeff Hicke sep93
Earth Space Research Group, UC Santa Barbara
(See /home/drw/idl/old.esrg/xmakedraw.pro)
XMAP[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xmap
PURPOSE: Display a world map and allow user to zoom in on a given region
INPUT: none
OUTPUT: none
INTERACTIVE CONTROLS:
BUTTON EVENTS WITHIN MAP FRAME:
Left mouse button --- Display lat-lon coordinates under cursor.
Middle mouse button - Display distance between the last LMB click
and the current cursor position
Right mouse button -- Enter region selection mode. An interactive
cursor box appears. The user selects the ZOOM
region by moving the cursor and using the
left/middle mouse buttons to decrease/increase
the box size. Hitting the right mouse
button again selects the region, draws the
map and displays the MAP_SET command line
which duplicates the displayed map. NOTE: to
improve performance, the whole world map is
drawn at low resolution whereas the zoomed
in maps are drawn at high resolution.
BUTTONS:
DONE
quit XMAP
WORLD
Redisplay world map
ROTATE
Rotates the central longitude by 180 degrees.
COLOR
Adjust color values of lines used to indicate continental
boundaries, US state boundaries, political boundaries, and
rivers.
NOTE: Color adjustment is accomplished via the PICKC widget.
Motion of the cursor inside the PICKC window adjusts
the Hue and Saturation values. The intensity is adjusted
with a horizontal slider.
SPAWN
Copy current map to a new window. The spawned window will
remain visible after XMAP terminates.
PRINT
Pull down menu
TERM: Print current map to device TERM
TREE: Print current map to device TREE
PSCOLOR: Print current color map to device PSCOLOR
BW PS: create a BW postscript file named plot.ps
COLOR PS: create a color postscript file named plotc.ps
PATH
trace a path on the map and compute total distance
LMB adds a new path line segment
MMB erases last path segment
RMB computes total distance of path in km, and return to normal mode
CITIES
mark major city locations
HELP
Display this help file in a scrollable widget.
TEXT WIDGET (labeled WHERE IS:)
Enter the latititude longitude. A symbol is drawn to
indicate point on map. NOTE: the code will bomb if you mess up
the format
author: Paul Ricchiazzi Dec92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/xmap.pro)
XMAP[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: xmap
PURPOSE: Display a world map and allow user to zoom in on a given region
INPUT: none
OUTPUT: none
INTERACTIVE CONTROLS:
BUTTON EVENTS WITHIN MAP FRAME:
Left mouse button --- Display lat-lon coordinates under cursor.
Middle mouse button - Display distance between the last LMB click
and the current cursor position
Right mouse button -- Enter region selection mode. An interactive
cursor box appears. The user selects the ZOOM
region by moving the cursor and using the
left/middle mouse buttons to decrease/increase
the box size. Hitting the right mouse
button again selects the region, draws the
map and displays the MAP_SET command line
which duplicates the displayed map. NOTE: to
improve performance, the whole world map is
drawn at low resolution whereas the zoomed
in maps are drawn at high resolution.
BUTTONS:
DONE
quit XMAP
WORLD
Redisplay world map
ROTATE
Rotates the central longitude by 180 degrees.
COLOR
Adjust color values of lines used to indicate continental
boundaries, US state boundaries, political boundaries, and
rivers.
NOTE: Color adjustment is accomplished via the PICKC widget.
Motion of the cursor inside the PICKC window adjusts
the Hue and Saturation values. The intensity is adjusted
with a horizontal slider.
SPAWN
Copy current map to a new window. The spawned window will
remain visible after XMAP terminates.
PRINT
Pull down menu
TERM: Print current map to device TERM
TREE: Print current map to device TREE
PSCOLOR: Print current color map to device PSCOLOR
BW PS: create a BW postscript file named plot.ps
COLOR PS: create a color postscript file named plotc.ps
PATH
trace a path on the map and compute total distance
LMB adds a new path line segment
MMB erases last path segment
RMB computes total distance of path in km, and return to normal mode
CITIES
mark major city locations
HELP
Display this help file in a scrollable widget.
TEXT WIDGET (labeled WHERE IS:)
Enter the latititude longitude. A symbol is drawn to
indicate point on map. NOTE: the code will bomb if you mess up
the format
author: Paul Ricchiazzi Dec92
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/xmap.pro)
XMESSAGE[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: xmessage
purpose: create a simple set of widget labels
useage: xmessage,labels,charsize=charsize,wbase=wbase,group=group,$
title=title,kill=kill,relabel=relabel,wlabels=wlabels,$
done=done,font=font
input:
labels string array of labels
keyword input:
charsize size of characters
wbase widget id of xmessage base widget
group widget id of parent widget
title widget label
kill kills xmessage widget if KILL is set to the value
of WBASE returned from a previous call of XMESSAGE
relabel scalor or integer array of widget id's. Used to relabel
xmessage labels, relabel should be set to the values
(possibly a subset) of WLABELS from a previous call of
XMESSAGE. When XMESSAGE is used with RELABEL, the
LABELS parameter should be set to a string array of
the new labels
done if set, the XMESSAGE widget will have a "DONE" button
which can be used to destroy the widget. Otherwise
the XMESSAGE widget is destroyed by calling XMESSAGE
with the KILL keyword set to the XMESSAGE widget id.
It is also destroyed when it is part of a widget
hierarchy whose group leader is killed
font the hardware font used in the labels
keyword output:
wbase widget id of xmessage base widget
wlabels widget id's of xmessage label widgets (intarr)
EXAMPLE:
; create xmessage widget
labels=['here is an example','of the xmessage widget']
xmessage,labels,wbase=wbase,wlabel=wlabels
; relabel 2'nd label
xmessage,'of The XMESSAGE WIDGET',relabel=wlabels(1)
; kill the message
xmessage,kill=wbase
author: Paul Ricchiazzi Jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/xmessage.pro)
XMESSAGE[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: xmessage_pg
purpose: create a simple set of widget labels
useage: xmessage_pg,labels,charsize=charsize,wbase=wbase,group=group,$
title=title,kill=kill,relabel=relabel,wlabels=wlabels,$
done=done,font=font
input:
labels string array of labels
keyword input:
charsize size of characters
wbase widget id of xmessage_pg base widget
group widget id of parent widget
title widget label
kill kills xmessage_pg widget if KILL is set to the value
of WBASE returned from a previous call of xmessage_pg
relabel scalor or integer array of widget id's. Used to relabel
xmessage_pg labels, relabel should be set to the values
(possibly a subset) of WLABELS from a previous call of
xmessage_pg. When xmessage_pg is used with RELABEL, the
LABELS parameter should be set to a string array of
the new labels
done if set, the xmessage_pg widget will have a "DONE" button
which can be used to destroy the widget. Otherwise
the xmessage_pg widget is destroyed by calling xmessage_pg
with the KILL keyword set to the xmessage_pg widget id.
It is also destroyed when it is part of a widget
hierarchy whose group leader is killed
font the hardware font used in the labels
keyword output:
wbase widget id of xmessage_pg base widget
wlabels widget id's of xmessage_pg label widgets (intarr)
EXAMPLE:
; create xmessage_pg widget
labels=['here is an example','of the xmessage_pg widget']
xmessage_pg,labels,wbase=wbase,wlabel=wlabels
; relabel 2'nd label
xmessage_pg_pg,'of The xmessage_pg WIDGET',relabel=wlabels(1)
; kill the message
xmessage_pg,kill=wbase
author: Paul Ricchiazzi Jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/xmessage.pro)
XMESSAGE_PG
[Previous Routine]
[Next Routine]
[List of Routines]
NOTE: This routine has been modified by P.T.Gallagher, 18:02:97.
routine: xmessage
purpose: create a simple set of widget labels
useage: xmessage,labels,charsize=charsize,wbase=wbase,group=group,$
title=title,kill=kill,relabel=relabel,wlabels=wlabels,$
done=done,font=font
input:
labels string array of labels
keyword input:
charsize size of characters
wbase widget id of xmessage base widget
group widget id of parent widget
title widget label
kill kills xmessage widget if KILL is set to the value
of WBASE returned from a previous call of XMESSAGE
relabel scalor or integer array of widget id's. Used to relabel
xmessage labels, relabel should be set to the values
(possibly a subset) of WLABELS from a previous call of
XMESSAGE. When XMESSAGE is used with RELABEL, the
LABELS parameter should be set to a string array of
the new labels
done if set, the XMESSAGE widget will have a "DONE" button
which can be used to destroy the widget. Otherwise
the XMESSAGE widget is destroyed by calling XMESSAGE
with the KILL keyword set to the XMESSAGE widget id.
It is also destroyed when it is part of a widget
hierarchy whose group leader is killed
font the hardware font used in the labels
keyword output:
wbase widget id of xmessage base widget
wlabels widget id's of xmessage label widgets (intarr)
EXAMPLE:
; create xmessage widget
labels=['here is an example','of the xmessage widget']
xmessage,labels,wbase=wbase,wlabel=wlabels
; relabel 2'nd label
xmessage,'of The XMESSAGE WIDGET',relabel=wlabels(1)
; kill the message
xmessage,kill=wbase
author: Paul Ricchiazzi Jan93
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/xmessage_pg.pro)
XMOVIE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XMOVIE
PURPOSE:
This program is a simplified version of XINTERANIMATE. It is written
to illustrate the proper way to write an animation loop in a widget
program using the WIDGET_TIMER functionality.
CATEGORY:
Widgets.
CALLING SEQUENCE:
XMOVIE, image3d
INPUTS:
image3d: A three-dimensional image array. The animation occurs over
the third dimension.
KEYWORD PARAMETERS:
GROUP: The group leader of the program. When the group leader dies,
this program dies as well.
TITLE: The window title of the program. The default is "Animation
Example...".
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
EXAMPLE:
To open the abnormal heart data and animate it, type:
filename = FILEPATH(SUBDIR=['examples', 'data'], 'abnorm.dat')
OPENR, lun, filename, /GET_LUN
data = BYTARR(64, 64, 15)
READU, lun, data
FREE_LUN, lun
data = REBIN(data, 256, 256, 15)
XMOVIE, data
MODIFICATION HISTORY:
Written by: David Fanning, June 96.
Added slider for controlling animation speed. 30 June 99.
(See /home/drw/idl/aux/xmovie.pro)
XMULTI[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: xmulti
purpose: set up margins for horizontally stacked multi frame plot
input:
p named variable, contains stuff you don't need to know
the contents of p are changed after each call
Keyword input
np number of frames in plot, set on first call only
xmargin 2 element vector specifying overall margin setting
left (0) and right (1) of the multiframe plot
if xmargin is not set the left and right margin is taken
from !x.margin. This keyword is ignored when NP not set
space space between frames of multiframe plots in units of
character width. This keyword is ignored when NP not set
SIDE EFFECTS: Changes the values !p.multi(4) to 0 to enforce row
major ordering of plots. Also changes the value of
!y.charsize to a very small value to disable y-axis
labeling. The original value of !y.charsize is
restored when xmulti is called with no arguments,
e.g., p=xmulti()
EXAMPLE: create a three frame plot stacked horizontally
y1=randf(200,1.5)
y2=randf(200,2)
y3=randf(200,2.5)
y4=randf(200,3)
!p.multi=[0,3,1]
plot,y1, xmargin=xmulti(p,np=3,xmargin=[5,3],space=1)
plot,y2, xmargin=xmulti(p)
plot,y3, xmargin=xmulti(p) & p=xmulti()
; Now try a four frame plot with no space between frames
!p.multi=[0,4,1]
plot,y1, xmargin=xmulti(p,np=4)
plot,y2, xmargin=xmulti(p)
plot,smooth(y2,5), xmargin=xmulti(p)
plot,smooth(y2,7), xmargin=xmulti(p) & p=xmulti()
; now try two four frame plots on the same page
;
!p.multi=[0,4,2]
plot,y1,xmargin=xmulti(p,np=4,space=1) & xl=!x.window(0)
plot,y2,xmargin=xmulti(p)
plot,y3,xmargin=xmulti(p)
plot,y4,xmargin=xmulti(p) & p=xmulti()
xl=(!x.window(1)+xl)/2
yl=!y.window(1)+.5*!y.margin(1)*!d.y_ch_size/float(!d.y_vsize)
xyouts,xl,yl,'top',align=.5,/norm
plot,y1^2,xmargin=xmulti(p,np=4,space=1)
plot,y2^2,xmargin=xmulti(p)
plot,y3^2,xmargin=xmulti(p)
plot,y4^2,xmargin=xmulti(p) & p=xmulti()
yl=!y.window(1)+.5*!y.margin(1)*!d.y_ch_size/float(!d.y_vsize)
xyouts,xl,yl,'bottom',align=.5,/norm
author: Paul Ricchiazzi Mar94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/esrg/xmulti.pro)
XMULTI[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: xmulti
purpose: set up margins for horizontally stacked multi frame plot
input:
p named variable, contains stuff you don't need to know
the contents of p are changed after each call
Keyword input
np number of frames in plot, set on first call only
xmargin 2 element vector specifying overall margin setting
left (0) and right (1) of the multiframe plot
if xmargin is not set the left and right margin is taken
from !x.margin. This keyword is ignored when NP not set
space space between frames of multiframe plots in units of
character width. This keyword is ignored when NP not set
SIDE EFFECTS: Changes the values !p.multi(4) to 0 to enforce row
major ordering of plots. Also changes the value of
!y.charsize to a very small value to disable y-axis
labeling. The original value of !y.charsize is
restored when xmulti is called with no arguments,
e.g., p=xmulti()
EXAMPLE: create a three frame plot stacked horizontally
y1=randf(200,1.5)
y2=randf(200,2)
y3=randf(200,2.5)
y4=randf(200,3)
!p.multi=[0,3,1]
plot,y1, xmargin=xmulti(p,np=3,xmargin=[5,3],space=1)
plot,y2, xmargin=xmulti(p)
plot,y3, xmargin=xmulti(p) & p=xmulti()
; Now try a four frame plot with no space between frames
!p.multi=[0,4,1]
plot,y1, xmargin=xmulti(p,np=4)
plot,y2, xmargin=xmulti(p)
plot,smooth(y2,5), xmargin=xmulti(p)
plot,smooth(y2,7), xmargin=xmulti(p) & p=xmulti()
; now try two four frame plots on the same page
;
!p.multi=[0,4,2]
plot,y1,xmargin=xmulti(p,np=4,space=1) & xl=!x.window(0)
plot,y2,xmargin=xmulti(p)
plot,y3,xmargin=xmulti(p)
plot,y4,xmargin=xmulti(p) & p=xmulti()
xl=(!x.window(1)+xl)/2
yl=!y.window(1)+.5*!y.margin(1)*!d.y_ch_size/float(!d.y_vsize)
xyouts,xl,yl,'top',align=.5,/norm
plot,y1^2,xmargin=xmulti(p,np=4,space=1)
plot,y2^2,xmargin=xmulti(p)
plot,y3^2,xmargin=xmulti(p)
plot,y4^2,xmargin=xmulti(p) & p=xmulti()
yl=!y.window(1)+.5*!y.margin(1)*!d.y_ch_size/float(!d.y_vsize)
xyouts,xl,yl,'bottom',align=.5,/norm
author: Paul Ricchiazzi Mar94
Institute for Computational Earth System Science
University of California, Santa Barbara
(See /home/drw/idl/old.esrg/xmulti.pro)
XPLOT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XPLOT
PURPOSE:
The purpose of this program is to demonstrate how to
create a line plot with axes and a title in the
new IDL 5 object graphics.
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:
XPlot, x, y
REQUIRED INPUTS:
x: A vector of input values used as the dependent data.
OPTIONAL INPUTS
y: A vector of input values used as the dependent data.
If both x and y parameters are present, x is the independent data.
OPTIONAL KEYWORD PARAMETERS:
COLORPRINT: Set this keyword to obtain printed output in color.
If not set (the default), printed output is in black and white.
EXACT: Set this keyword to a one- or two-element array to set exact axis
scaling for the axes. If Exact is a one-element array, both axes are
set to the same value. If Exact is a two-element array, the first
elements sets the X axis property and the second element sets the Y
axis property. For example, to set the X axis to exact scaling and
the Y axis to normal scaling, type:
IDL> x = Findgen(10)
IDL> XPlot, x, Sin(x), Exact=[1,0], XRange=[0,8.5]
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to new Plot command. To some extent these are similar to the
old IDL Plot command. For example: Linestyle=2, Thick=3,
XRange=[-100,100], etc.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
LANDSCAPE: Set this keyword if you are printing in landscape mode. The
default is Portrait mode. The Landscape keyword on the PRINTER object
is set, but not all printers will honor this keyword setting. If yours
does not, set Landscape mode in the Printer Setup dialog.
PSYM: The index of a plotting symbol to use on the plot. Integers 0-7
are valid values.
SYMSIZE: Sets the size of the symbols. By default, symbols are sized
so that they are 0.015 percent of the axis range.
VECTOR: Set this keyword if you want the printed output to be in
vector (as opposed to bitmap) form. This is faster, but not as accurate.
TITLE: A string used as the title of the plot.
XTITLE: A string used as the X title of the plot.
YTITLE: A string used as the Y title of the plot.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
RESTRICTIONS:
None.
EXAMPLE:
To use this program, pass a 1D vector or vectors, like this:
IDL> XPlot, RandomU(seed, 11) * 9, YRange=[0, 10]
MODIFICATION HISTORY:
Written by David Fanning, 13 June 97.
Modified axis font handling. 17 Sept 97. DWF.
Was not destroying all objects on exit. 12 Feb 98. DWF.
Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
Fixed a bug in the way symbols were (NOT!) sized. 11 May 99. DWF.
Added non-exact axis scaling. 12 May 99. DWF.
Fixed bug that changed data when calling with single parameter. 13 May DWF.
Added VECTOR, LANDSCAPE and COLORPRINT keywords and improved printing
capabilities. 16 Feb 2000. DWF.
Modified the EXACT keyword to accept values for X and Y axes
independently. 10 May 2000. DWF
(See /home/drw/idl/aux/xplot.pro)
XREADFUSE
[Previous Routine]
[Next Routine]
[List of Routines]
xreadfuse
widget to read FUSE data file
CALLING SEQUENCE:
xreadfuse,file,header,image,status
INPUTS:
none: file is interactively selected
OUTPUTS:
file - name of the file selected
header - FITS header
image - output image
status - null string if successful, otherwise error message
OPTIONAL KEYWORD INPUTS:
group - id of widget group leader
OPTIONAL KEYWORD INPUTS/OUTPUTS:
directory - initial directory to search for file. On output it
contains the directory that the file was in.
HISTORY:
written July 13, 1999 by D. Lindler
(See /home/drw/idl/fuse/xreadfuse.pro)
XSTRETCH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XSTRETCH
PURPOSE:
The purpose of this program is to interactively apply a simple
linear stretch to an image by moving two lines on a histogram
plot of the image. The portion of the image data between the
two lines is stretched over the available colors in the color table.
CATEGORY:
Graphics, Widgets
CALLING SEQUENCE:
XSTRETCH, image
INPUT PARAMETERS:
image: The image data to be stretched.It must be 2D. (This may now
be a pointer to the image data rather than the image itself.)
KEYWORD PARAMETERS:
COLORTABLE: The index of a colortable you would like to load.
The current colortable is used if this keyword is undefined.
_EXTRA: This keyword collects any keyword appropriate for the
Plot command.
GROUP_LEADER: Keyword to assign a group leader (so this program can be
called from within another widget program).
MAX_VALUE: Keyword to assign a maximun value for the Histogram Plot.
Images with lots of pixels of one color (e.g. black) skew
the histogram. This helps make a better looking plot.
NCOLORS: Keyword to assign the number of colors used to display
the image. The default is !D.Table_Size-4.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
DEPENDENCIES:
The following programs are required from the Coyote Library:
tvimage.pro
pswindow.pro
psconfig.pro
fsc_inputfield.pro
fsc_droplist.pro
fsc_fileselect.pro
fsc_plotwindow.pro
fsc_psconfig__define.pro
EXAMPLE:
If you have a 2D image in the variable "image", you can run this
program like this:
XSTRETCH, image
MODIFICATION HISTORY:
Written by: David Fanning, April 1996.
October, 1996 Fixed a problem with not restoring the color
table when the program exited. Substituted a call to XCOLORS
instead of XLOADCT.
October, 1998. Added NO_BLOCK keyword and modified to work with
24-bit color devices.
April, 1999. Made lines thicker. Offered default image. DWF.
April, 1999. Replaced TV command with TVIMAGE. DWF.
April, 1999. Made both windows resizeable. DWF.
April, 2000. Made several modifications to histogram plot and to
the way colors were handled. Added ability to pass pointer to
the image as well as image itself. DWF.
(See /home/drw/idl/aux/xstretch.pro)
XSURFACE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XSURFACE
PURPOSE:
The purpose of this program is to demonstrate how to
create a surface with axes and a title in the new IDL 5
object graphics.
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, Object Graphics.
CALLING SEQUENCE:
XSURFACE, 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:
COLORTABLE: Set this keyword to a number between 0 and 40 to select one
of the pre-selected IDL color tables for elevation shading.
ELEVATION_SHADING: Set this keyword to put elevation shading into effect.
EXACT: Set this keyword to a one-, two-,or three-element array to set exact axis
scaling for the X, Y, and Z axes, respectively. If Exact is a one-element array,
all three axes are set to the same value. For example, to set the X axis to
exact scaling and the Y and Z axes to normal scaling, type:
IDL> FSC_Surface, Exact=[1,0,0]
_EXTRA: This keyword collects otherwise undefined keywords that are
passed to the IDLgrSURFACE initialization routine.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
LANDSCAPE: Set this keyword if you are printing in landscape mode. The
default is Portrait mode. The Landscape keyword on the PRINTER object
is set, but not all printers will honor this keyword setting. If yours
does not, set Landscape mode in the Printer Setup dialog.
SHADED: Set this keyword to set up a shaded surface plot rather than a wire
mesh surface, which is the default.
TITLE: A string used as the title of the plot.
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.
DEPENDENCIES:
This program requires the following additional files from the Coyote Library:
error_message.pro
fsc_droplist.pro
getcolor.pro
loaddata.pro
pickcolor.pro
xcolors.pro
EXAMPLE:
To use this program with your data, type:
IDL> XSurface, data
MODIFICATION HISTORY:
Written by David Fanning, 8 June 97.
Made axis scaling more robust. 17 Sept 97. DWF.
Minor modifications to incorporate better understanding
of how objects work. 4 Oct 97. DWF.
Fixed error cleaning up all of my created objects. 12 Feb 98. DWF.
Changed IDLgrContainer to IDL_Container to fix 5.1 problems. 20 May 98. DWF.
Fixed mis-spelling of HELVETICA14. 29 June 98. DWF.
Added the EXACT keyword to the X and Y axes to force axis ranging. 27 July 98. DWF
Added the ability to select rendering "drag" quality for faster operation. 22 Aug 98. DWF.
Added ability to get non-exact axis scaling. 12 May 99. DWF.
Improved documentation and readability of code. 12 May 99. DWF.
Added VECTOR and LANDSCAPE keywords and improved printing capability. 16 Feb 2000. DWF.
Added different lights and a Light Controller option. 28 April 2000. DWF.
Added elevation shading. 8 May 2000. DWF.
Removed VECTOR keyword. Replaced with VECTOR/BITMAP/COLOR Print buttons. 8 May 2000. DWF.
Added HIDDEN_LINE keyword. 8 May 2000. DWF.
(See /home/drw/idl/aux/xsurface.pro)
XTTAG_FUSE
[Previous Routine]
[Next Routine]
[List of Routines]
ttag_centroid
Routine to compute centroid vs time in time tagged data
CALLING SEQUENCE:
ttag_centroid,time,x,y,tout,xcent,ycent,counts,tcounts,image
INPUTS:
time - time vector
x - vector of x positions
y - vector of y positions
KEYWORD INPUTS:
interval - time interval to bin the events(Seconds). (default = 60)
xrange - 2 element vector giving [xmin,xmax] of the region
to count the events (in HIRES pixels)
yrange - 2 element vector giving [ymin,ymax] of the region
to count the events (in HIRES pixels)
tmin - minimum time to process
tmax - maximum time to process
mincounts - minimum number of counts for computing centroid. If
fewer than mincounts, x and y are set to zero. (default=20)
OUTPUTS:
tout - time vector for the output rate vector
xcent - x centroid (in hi-res pixels)
ycent - y centroid (in hi-res pixels)
counts - total counts in each time bin
tcounts - vector of total counts in image
image - image of region centroided
HISTORY:
D. Lindler, Aug 1999
(See /home/drw/idl/fuse/xttag_fuse.pro)
XVOIGTFIT
[Previous Routine]
[Next Routine]
[List of Routines]
xvoigtfit
Interactive widget to fit multiple absorption Voigt Profiles
I.E. the routine fits Fits
y = C*A1*A2*...*A8
where:
C is the continuum flux defined by:
C = b0 + b1*x + b2*x^2
Ai are the absorption lines with the form (i = 0 to 7)
Ai = exp(-a0*Voigt(a2,(x-a1))
see IDL Voigt routine for further info.
CALLING SEQUENCE
xvoigtfit,xvector,yvector,bcoef,vcoef,mask=mask
INPUTS:
xvector - X vector
yvector - Y vector
OUTPUTS:
bcoef - coefficients for the polynomial baseline
vcoef - 3 x nvoigt coefficients for the fitted Profiles
vcoef(0,*) = a0
vcoef(1,*) = a1 (centers)
vcoef(2,*) = a2 (Voigt Damping Factor)
fit - fit evaluated at x vector
OPTIONAL KEYWORD INPUTS:
title - plot title
xtitle - x plot title
ytitle - y plot title
group - widget id of the group leader
modal - set to make widget modal
OPTIONAL KEYWORD INPUT/OUTPUTS:
mask - mask vector (1 for good data, 0 for bad data)
HISTORY:
version 1 D. Lindler Aug 1999
(See /home/drw/idl/fuse/xvoigtfit.pro)
XWINDOW[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XWINDOW
PURPOSE:
This routine implements a "smart" resizeable graphics window.
It is used as a wrapper for built-in IDL graphics procedures
such as SURFACE, CONTOUR, PLOT, SHADE_SURF, etc. In additon,
it can be used to display any user-written graphics procedure
so long as that procedure follows three simple rules: (1) It
does not open it's own graphics windows, (2) It is defined with
no more than three positional arguments (an unlimited number
of keyword arguments are allowed), and (3) It is defined
with an _EXTRA keyword.
Keyword arguments permit the window to have its own portion
of a color table and to be able to change the colors loaded in
that portion of the color table. Colors are updated
automatically on both 8-bit and 24-bit color displays. In
addition, the window colors can "protect" themselves. I mean
by this that the window can re-load its own colors into the
color table when the cursor is moved over the window (X device)
or the user clicks in the window (all other devices). This
prevents other applications from changing the colors used to
display data in this window. (This is an issue mainly in
IDL 5 applications where widget applications can run
concurrently with commands from the IDL command line.)
Keyword arguments also permit the window to create output
files of its contents. These files can be color and
gray-scale PostScript, GIF, TIFF, or JPEG files.
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, Graphics.
CALLING SEQUENCE:
XWINDOW, command, P1, P2, P3
REQUIRED INPUTS:
COMMAND: The graphics procedure command to be executed. This parameter
must be a STRING. Examples are 'SURFACE', 'CONTOUR', 'PLOT', etc.
OPTIONAL INPUTS:
P1: The first positional parameter appropriate for the graphics
command.
P2: The second positional parameter appropriate for the graphics
command.
P3: The third positional parameter appropriate for the graphics
command.
INPUT KEYWORD PARAMETERS:
BACKGROUND: The background color index for the window. Setting this color
along with the ERASE keyword causes the window to be erased with
this color.
CPMENU: Setting this keyword adds a "Color Protection" button to the
"Controls" menu. Color protection can then be turned ON or OFF for the
window. Otherwise, the color protection scheme used to open the window
cannot be changed once the window is open. (See the PROTECT keyword.)
The default is to have this keyword OFF.
ERASE: Setting this keyword "erases" the contents of the current
graphics window before re-executing the graphics command. For example,
this keyword might need to be set if the graphics "command" is TVSCL.
The default is to NOT erase the display before reissuing the graphics
command.
_EXTRA: This keyword forms an anonymous structure of any unrecognized
keywords passed to the program. The keywords must be appropriate
for the graphics command being executed.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
OUTPUT: Set this keyword if you want a "File Output" menu on
the menu bar. The default is to have this item turned OFF. File output
will allow you to create GIF, JPEG, TIFF, and PostScript output from
what you see in the display window.
JUST_REGISTER: If this keyword is set, the XWINDOW program is just
registered with XMANAGER, but XMANAGER doesn't run. This is
useful, for example, if you want to open an XWINDOW window in
the widget definition module of another widget program.
NO_CHANGE_CONFIG: Normally as the XWINDOW graphics window is resized
the size (or aspect ratio, in the case of PostScript) of the
hardware configuration dialogs change to reflect the new size of
the graphics window. This results in file output that resembles
the current graphics window in size and aspect ratio. If you want
the file output dialogs to remember their current configuration
even as the window is resized, set this keyword.
NOMENU: Setting this keyword results in a graphics window without
menu items. The default is to have a "Controls" menu item in the
window menu bar with a "Quit" button. Setting this keyword
automatically turns of the COLORS, OUTPUT, and CPMENU menu
choices. (Note that the values specified by the COLORS keyword
will still be valid for color protection, but no "Change Colors..."
menu item will appear.)
PROTECT: If this keyword is set, color protection for the draw
widget is turned ON. What this means is that the window colors
(see the XCOLOR keyword) will be restored when the cursor enters
the draw widget window (on X devices) or when the user clicks in
the draw widget window (other devices). This prevents someone at
the IDL command line in IDL 5 from changing the window display
colors permanently.
WTITLE: This is the window title. It is the string "Resizeable
COMMAND Window (1)" by default, where COMMAND is the input
parameter. And the number (1 in this case) is the window
index number of the draw widget.
WXPOS: This is the initial X offset of the window. Default is to
position the window in the approximate middle of the display.
WYPOS: This is the initial Y offset of the window. Default is to
position the window in the approximate middle of the display.
WXSIZE: This is the initial X size of the window. Default is 400
pixels.
WYSIZE: This is the initial Y size of the window. Default is 400
pixels.
XCOLORS: Using this keyword adds a "Change Colors..." button to the
"Controls" menu. Set this keyword to the number of colors available
in the window and the starting index of the first color. For example,
to allow the window access to 100 colors, starting at color index 50
(i.e., color indices 50 to 149), use XColor=[100, 50]. If you use the
keyword syntax "/XColor", all the colors available will be used, not just
one color. If the keyword is set to a scalar value greater than 1, the
starting color index is set to 0. The default value for this keyword
is [(!D.N_COLORS < 256), 0]. Note that color "protection" may be
turned on (via the PROTECT keyword) even if this keyword is NOT used.
OUTPUT KEYWORD PARAMETERS:
DRAWID: This keyword returns the draw widget identifier of the draw
widget created in XWINDOW.
TOP: This keyword returns the identifier of the top-level base widget
created by XWINDOW.
WID: This keyword returns the window index number of the draw widget
created in XWINDOW.
COMMON BLOCKS:
None.
SIDE EFFECTS:
If color protection is ON, the window colors are reloaded when the
cursor enters the XWINDOW graphics windows.
RESTRICTIONS:
This program requires six additional programs from the Fanning
Software Consulting library:
FSC_PSCONFIG__DEFINE.PRO
FSC_FILESELECT.PRO
FSC_DROPLIST.PRO
FSC_INPUTFIELD.PRO
PSWINDOW.PRO
XCOLORS.PRO
might also want to get the program TVIMAGE if you will be displaying
images in XWINDOW graphics windows.
If the "command" program requires keywords that are also keywords
to XWINDOW, then you must use the keyword twice on the command line.
The program uses the Z-Graphics Buffer to create GIF, TIFF, and JPEG
output. Be sure your program doesn't use commands that are illegal in
the Z-Buffer. Two commands in particular come to mind: Window and
Device, Decomposed=0.
EXAMPLE:
To display a surface in the window, type:
XWINDOW, 'SURFACE', Dist(20), Charsize=1.5
To enable the Change Colors and File Output menu items, type:
XWINDOW, 'SHADE_SURF', Dist(30), /XColors, /Output
MODIFICATION HISTORY:
Written by: David Fanning, October 96.
XSIZE and YSIZE keywords changed to WXSIZE and WYSIZE so as not to
conflict with these keywords on other programs. 14 April 1997, DWF.
Updated as non-blocking widget for IDL 5.0. 14 April 1997, DWF.
Extensively modified to work on either 8-bit or 24-bit displays,
to enable color protection schemes, to send the contents to a
number of different output files, and to give the user choices
about which menu items to enable. 21 April 1997, DWF.
Renamed COLORS keyword to XCOLORS and fixed a problem cancelling
out of File Configuration dialogs. 23 April 1997, DWF.
Updated program to IDL 5 functionality. 20 Oct 1997, DWF.
Changed color protection scheme to widget tracking for X devices
and clicking in the draw widget window for all other devices.
This gets around unreliable tracking events on window machines.
20 Oct 1997, DWF.
Added a BACKGROUND keyword and caused the program to ERASE in the
background color. 1 May 1998.
Added a Device, Decomposed=0 call to make this work on 24-bit
devices. DWF, 29 June 1998.
Fixed a problem with number of colors that RSI introduced in IDL
5.1 for PCs. 15 Aug 1998.
Added more error checking for programs that work on the display
but not in the Z-Graphics Buffer where GIF, TIFF, and JPEG
output is created. DWF. 10 September 1998.
Improved error handling and updated some obsolete commands. 6 May 99. DWF.
Added UNIX work-around for IDL 5.2 bug having to do with resizing
TLB with menu bars. 16 May 99. DWF.
Fixed a bug when updating file output sizes. 19 Dec 99. DWF.
Substituted COYOTE_FIELD for CW_FIELD calls by adding COYOTE_FIELD
code directly to program. 19 Dec 99. DWF.
Changed the way the Output buttons work to conform to what
users expect. 19 Dec 99. DWF.
Added support for FSC_PSConfig PostScript configuration object. 29 Jan 2000. DWF.
Hardcoded COLOR=1 keyword in all calls to the PostScript device. This
produces decent gray-scale output on most printers. 28 April 2000. DWF.
(See /home/drw/idl/aux/xwindow.pro)
XWINDOW[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
XWINDOW
PURPOSE:
This routine implements a "smart" resizeable graphics window.
It is used as a wrapper for built-in IDL graphics procedures
such as SURFACE, CONTOUR, PLOT, SHADE_SURF, etc. In additon,
it can be used to display any user-written graphics procedure
so long as that procedure follows three simple rules: (1) It
does not open it's own graphics windows, (2) It is defined with
no more than ten positional arguments (an unlimited number
of keyword arguments are allowed), and (3) It is defined
with an _EXTRA keyword.
Keyword arguments permit the window to have its own portion
of a color table and to be able to change the colors loaded in
that portion of the color table. Colors are updated
automatically on both 8-bit and 24-bit color displays. In
addition, the window colors can "protect" themselves. I mean
by this that the window can re-load its own colors into the
color table when the cursor is moved over the window. This
prevents other applications from changing the colors used to
display data in this window. (This is an issue mainly in
IDL 5.x applications where widget applications can run
concurrently with commands from the IDL command line.)
Keyword arguments also permit the window to create output
files of its contents. These files can be color and
gray-scale PostScript, GIF, TIFF, or JPEG files.
AUTHOR:
************* CM 19 Jan 1999 VERSION **********
Craig B. Markwardt, NASA/GSFC Code 662, Greenbelt, MD 20770
craigm@lheamail.gsfc.nasa.gov
Originally by:
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, Graphics.
CALLING SEQUENCE:
XWINDOW, command, P1, P2, ... , keywords=..., ...
REQUIRED INPUTS:
COMMAND: The graphics procedure command to be executed. This parameter
must be a STRING. Examples are 'SURFACE', 'CONTOUR', 'PLOT', etc.
OPTIONAL INPUTS:
Pn: A positional parameter appropriate for the graphics command.
Any number of parameters between 0 and 10 may be given.
INPUT KEYWORD PARAMETERS:
CPMENU: Setting this keyword adds a "Color Protection" button to the
"Controls" menu. Color protection can then be turned ON or OFF for the
window. Otherwise, the color protection scheme used to open the window
cannot be changed once the window is open. (See the PROTECT keyword.)
The default is to have this keyword OFF.
ERASE: Setting this keyword "erases" the contents of the current
graphics window before re-executing the graphics command. For example,
this keyword might need to be set if the graphics "command" is TVSCL.
The default is to NOT erase the display before reissuing the graphics
command.
_EXTRA: This keyword forms an anonymous structure of any unrecognized
keywords passed to the program. The keywords must be appropriate
for the graphics command being executed.
GROUP_LEADER: The group leader for this program. When the group leader
is destroyed, this program will be destroyed.
OUTPUT: Set this keyword if you want a "File Output" menu on
the menu bar. The default is to have this item turned OFF.
JUST_REGISTER: If this keyword is set, the XWINDOW program is just
registered with XMANAGER, but XMANAGER doesn't run. This is
useful, for example, if you want to open an XWINDOW window in
the widget definition module of another widget program.
NO_CHANGE_CONFIG: Normally as the XWINDOW graphics window is resized
the size (or aspect ratio, in the case of PostScript) of the
hardware configuration dialogs change to reflect the new size of
the graphics window. This results in file output that resembles
the current graphics window in size and aspect ratio. If you want
the file output dialogs to remember their current configuration
even as the window is resized, set this keyword.
NOMENU: Setting this keyword results in a graphics window without
menu items. The default is to have a "Controls" menu item in the
window menu bar with a "Quit" button. Setting this keyword
automatically turns of the COLORS, OUTPUT, and CPMENU menu
choices. (Note that the values specified by the COLORS keyword
will still be valid for color protection, but no "Change Colors..."
menu item will appear.)
PROTECT: If this keyword is set, color protection for the draw
widget is turned ON. What this means is that the window colors
(see the XCOLOR keyword) will be restored when the cursor enters
the draw widget window. This prevents someone at the IDL command
line in IDL 5.0 from changing the window display colors permanently.
WTITLE: This is the window title. It is the string "Resizeable
COMMAND Window (1)" by default, where COMMAND is the input
parameter. And the number (1 in this case) is the window
index number of the draw widget.
WXPOS: This is the initial X offset of the window. Default is to
position the window in the approximate middle of the display.
WYPOS: This is the initial Y offset of the window. Default is to
position the window in the approximate middle of the display.
WXSIZE: This is the initial X size of the window. Default is 400
pixels.
WYSIZE: This is the initial Y size of the window. Default is 400
pixels.
XCOLORS: Using this keyword adds a "Change Colors..." button to the
"Controls" menu. Set this keyword to the number of colors available
in the window and the starting index of the first color. For example,
to allow the window access to 100 colors, starting at color index 50
(i.e., color indices 50 to 149), use XColor=[100, 50]. If you use the
keyword syntax "/XColor", all the colors available will be used, not just
one color. If the keyword is set to a scalar value greater than 1, the
starting color index is set to 0. The default value for this keyword
is [(!D.N_COLORS < 256), 0]. Note that color "protection" may be
turned on (via the PROTECT keyword) even if this keyword is NOT used.
OUTPUT KEYWORD PARAMETERS:
DRAWID: This keyword returns the draw widget identifier of the draw
widget created in XWINDOW.
TOP: This keyword returns the identifier of the top-level base widget
created by XWINDOW.
WID: This keyword returns the window index number of the draw widget
created in XWINDOW.
COMMON BLOCKS:
None.
SIDE EFFECTS:
If color protection is ON, the window colors are reloaded when the
cursor enters the XWINDOW graphics windows.
RESTRICTIONS: This program requires three additional programs from
the Fanning Software Consulting library: PSWINDOW, PS_FORM (CM
version; available at
http://astrog.physics.wisc.edu/~craigm/idl), and XCOLORS. You
might also want to get the program TVIMAGE if you will be
displaying images in XWINDOW graphics windows.
If the "command" program requires keywords that are also keywords
to XWINDOW, then you must use the keyword twice on the command line.
EXAMPLE:
To display a surface in the window, type:
XWINDOW, 'SURFACE', Dist(20), Charsize=1.5
To enable the Change Colors and File Output menu items, type:
XWINDOW, 'SHADE_SURF', Dist(30), /XColors, /Output
MODIFICATION HISTORY:
Written by: David Fanning, October 96.
XSIZE and YSIZE keywords changed to WXSIZE and WYSIZE so as not to
conflict with these keywords on other programs. 14 April 1997, DWF.
Updated as non-blocking widget for IDL 5.0. 14 April 1997, DWF.
Extensively modified to work on either 8-bit or 24-bit displays,
to enable color protection schemes, to send the contents to a
number of different output files, and to give the user choices
about which menu items to enable. 21 April 1997, DWF.
Renamed COLORS keyword to XCOLORS and fixed a problem cancelling
out of File Configuration dialogs. 23 April 1997, DWF.
Modification: Craig Markwardt, 21 October 1997
Added capability for up to ten positional parameters
Modification: CM 15 May 1998
PS_FORM dependencies are not hardcoded now. Requires
CM version of PS_FORM function.
Modification: CM 19 Jan 1999
Added Parent keyword to widget invocation of PS_FORM, and
make widgets MODAL-safe.
(See /home/drw/idl/aux/markwardt/xwindow.pro)
X_AXIS[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: x_axis
PURPOSE: label x axis tick marks with the actual values of the x
vector.
USEAGE: x_axis,x,y,xticknames=xticknames,xtitle=xtitle, $
charsize=charsize,yspace=yspace,ticklen=ticklen, $
gridstyle=gridstyle,extend=extend
INPUT:
x
a vector of x-axis points (data coordinates) to label or mark
y
a scalor or two element vector. First element specifies the
vertical subnormal coordinates of the x-axis line. Y=0 puts
x-axis at bottom of the plot while Y=1 puts x-axis at top of
plot. The second element, if present, specifies an additional
vertical offset of the x-axis in units of the character
height. (default=0)
labels
x axis tick labels, a string or number array the same size as x
keyword input:
xticknames
string array of x axis tickmark labels, if not of type
string, will be coerced into string
xtitle
x axis title, If XTICKNAME is undefined, XTITLE appears immediately
below (YSPACE>0) or above (YSPACE<0) the x axis. Otherwise it
appears below/above the XTICKNAME labels.
yspace
controls vertical spacing between x-axis, tick labels and x-axis
title. By default the centerline of the tick labels appear 1
character height below the x-axis while the x-axis title appears
2.5 character heights below the x-axis. The YSPACE factor
multiplies these vertical offsets. YSPACE < 0 causes the titles
to appear above the x-axis. (default=1)
ticklen
length of tickmarks as a PERCENTAGE of the entire y coordinate range
TICKLEN=2 produces the standard major tickmark length, while
TICKLEN=1 produces the standard minor tickmark length. (defualt=0)
charsize
character size used for x-axis annotation. If more than two
plots are ganged in either the X or Y direction, the character
size is halved.
extend
if set and y lt 0 or y gt 1 then the y-axis lines are extended to
to intersect the new x-axis line. This produces an enclosed
rectangular area between the new x-axis and the old x-axis (if it
exists).
color
color index used to color axis
tcolor
color index used to color axis and tick titles (just for the characters)
DISCUSSION:
Calling X_AXIS with no arguments causes the system variables
!x.ticname and !x.ticklen to be reset to values which eliminate
tickmarks and tick labeling on the following plot. After the
plot is drawn, X_AXIS is called again to draw the specified
x-axis scale and reset the !x system variable.
EXAMPLE:
y=randomn(iseed,6)^2 & y(0)=0 & y(5)=0
x_axis
plot,y,psym=10
x_axis,1+findgen(5),xtitle='Surface type for 1993 field campagn', $
xticknames=['dirt','snow','ocean','grass','forrest'],/ticklen
; x_axis may be called repeatedly to build up fairly
; elaborate x axis labeling
xx=findrng(1.5,7.5,100)
x=2+indgen(6)
x_axis
plot,xx,planck(2^xx,200,/mic),ymargin=[10,10],/xstyle
oplot,xx,planck(2^xx,190,/mic)
oplot,xx,planck(2^xx,180,/mic)
oplot,xx,planck(2^xx,170,/mic)
x_axis,x,0,xtickn=2^x,ticklen=1,xtitle='wavelength (microns)'
x_axis,x,[1,3],ysp=-.5,xtitle='test',charsize=1.3,/ext
x_axis,x,1,xtickn=10000./2^x,ticklen=-1,yspace=-1,$
xtitle='wavenumber (cm!a-1!n)'
; fancy log axis labeling
v=.2*(20/.2)^(findgen(100)/99)
w=-4*(.2/v)^2+ 2*(v/10) - 10*(v/10)^2 + 5*(v/10)^3
x_axis
plot_oi,v,w,/xsty & oplot,v,w^2,li=1 & oplot,v,w^3,li=2
x_axis,[.2,.5,2,5,20],0,xtickname=['0.2','0.5','2','5','20'],/tickl
x_axis,[1,10],0,xtickname=['1','10'],charsize=1.3,tickl=2
x_axis,[.2+indgen(8)*.1,2+indgen(8)],0,/tickl
AUTHOR: Paul Ricchiazzi 24 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/esrg/x_axis.pro)
X_AXIS[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: x_axis
PURPOSE: label x axis tick marks with the actual values of the x
vector.
USEAGE: x_axis,x,y,xticknames=xticknames,xtitle=xtitle, $
charsize=charsize,yspace=yspace,ticklen=ticklen, $
gridstyle=gridstyle,extend=extend
INPUT:
x
a vector of x-axis points (data coordinates) to label or mark
y
a scalor or two element vector. First element specifies the
vertical subnormal coordinates of the x-axis line. Y=0 puts
x-axis at bottom of the plot while Y=1 puts x-axis at top of
plot. The second element, if present, specifies an additional
vertical offset of the x-axis in units of the character
height. (default=0)
keyword input:
xticknames
string array of x axis tickmark labels, if not of type
string, will be coerced into string
xtitle
x axis title, If XTICKNAME is undefined, XTITLE appears immediately
below (YSPACE>0) or above (YSPACE<0) the x axis. Otherwise it
appears below/above the XTICKNAME labels.
yspace
controls vertical spacing between x-axis, tick labels and x-axis
title. By default the centerline of the tick labels appear 1
character height below the x-axis while the x-axis title appears
2.5 character heights below the x-axis. The YSPACE factor
multiplies these vertical offsets. YSPACE < 0 causes the titles
to appear above the x-axis. (default=1)
ticklen
length of tickmarks as a PERCENTAGE of the entire y coordinate range
TICKLEN=2 produces the standard major tickmark length, while
TICKLEN=1 produces the standard minor tickmark length. (defualt=0)
charsize
character size used for x-axis annotation. If more than two
plots are ganged in either the X or Y direction, the character
size is halved.
extend
if set and y lt 0 or y gt 1 then the y-axis lines are extended to
to intersect the new x-axis line. This produces an enclosed
rectangular area between the new x-axis and the old x-axis (if it
exists).
color
color index used to color axis
tcolor
color index used to color axis and tick titles (just for the characters)
DISCUSSION:
Calling X_AXIS with no arguments causes the system variables
!x.ticname and !x.ticklen to be reset to values which eliminate
tickmarks and tick labeling on the following plot. After the
plot is drawn, X_AXIS is called again to draw the specified
x-axis scale and reset the !x system variable.
EXAMPLE:
y=randomn(iseed,6)^2 & y(0)=0 & y(5)=0
x_axis
plot,y,psym=10
x_axis,1+findgen(5),xtitle='Surface type for 1993 field campagn', $
xticknames=['dirt','snow','ocean','grass','forrest'],/ticklen
; x_axis may be called repeatedly to build up fairly
; elaborate x axis labeling
xx=findrng(1.5,7.5,100)
x=2+indgen(6)
x_axis
plot,xx,planck(2^xx,200,/mic),ymargin=[10,10],/xstyle
oplot,xx,planck(2^xx,190,/mic)
oplot,xx,planck(2^xx,180,/mic)
oplot,xx,planck(2^xx,170,/mic)
x_axis,x,0,xtickn=2^x,ticklen=1,xtitle='wavelength (microns)'
x_axis,x,[1,3],ysp=-.5,xtitle='test',charsize=1.3,/ext
x_axis,x,1,xtickn=10000./2^x,ticklen=-1,yspace=-1,$
xtitle='wavenumber (cm!a-1!n)'
; fancy log axis labeling
v=.2*(20/.2)^(findgen(100)/99)
w=-4*(.2/v)^2+ 2*(v/10) - 10*(v/10)^2 + 5*(v/10)^3
x_axis
plot_oi,v,w,/xsty & oplot,v,w^2,li=1 & oplot,v,w^3,li=2
x_axis,[.2,.5,2,5,20],0,xtickname=['0.2','0.5','2','5','20'],/tickl
x_axis,[1,10],0,xtickname=['1','10'],charsize=1.3,tickl=2
x_axis,[.2+indgen(8)*.1,2+indgen(8)],0,/tickl
AUTHOR: Paul Ricchiazzi 24 Aug 95
Institute for Computational Earth System Science
University of California, Santa Barbara
paul@icess.ucsb.edu
REVISIONS:
(See /home/drw/idl/old.esrg/x_axis.pro)
YMD2JD[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
YMD2JD
PURPOSE:
From Year, Month, and Day compute Julian Day number.
CATEGORY:
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.
(See /home/drw/idl/esrg/ymd2jd.pro)
YMD2JD[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
YMD2JD
PURPOSE:
From Year, Month, and Day compute Julian Day number.
CATEGORY:
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.
(See /home/drw/idl/old.esrg/ymd2jd.pro)
YMULTI[1]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: ymulti
purpose: set up margins for vertically stacked multi frame plot
input:
p named variable, contains stuff you don't need to know
the contents of p are changed after each call
Keyword input
np number of frames in plot, set on first call only (see examples)
ymargin 2 element vector specifying overall margin setting
below (0) and above (1) multiframe plot
if ymargin is not set the top and bot margin is taken
from !y.margin. This keyword is ignored when NP not set
space the separation distance between frames of a multiframe
plot in units of the character height. This keyword is
ignored when NP not set. Default is no space between plots
SIDE EFFECTS: Changes the value of !p.multi(4) to enforce column
major ordering of plots. To reinsate the default row
major ordering, set !p.multi=0 or !p.multi(4)=0.
System variables !x and !y are changed, but restored
to default after last plot.
EXAMPLE: create a three frame plot
y1=smooth(randomu(iseed,200),3)
y2=smooth(y1,11)
y3=smooth(randomu(iseed,200),11)
y4=smooth(y3,3)
!p.multi=[0,1,3]
plot,y1,ymargin=ymulti(p,np=3,ymargin=[5,3],space=1)
plot,y2,ymargin=ymulti(p)
plot,y3,ymargin=ymulti(p)
; Now try a four frame plot with no space between frames
!p.multi=[0,1,4]
plot,y1, ymargin=ymulti(p,np=4),ytitle='test'
plot,y2, ymargin=ymulti(p),ytitle='test'
plot,y3, ymargin=ymulti(p),ytitle='test'
plot,y4, ymargin=ymulti(p),ytitle='test'
; Now try a multi-column plot
!p.multi=[0,2,4]
plot,y1,title='top left',ymar=ymulti(p,np=2)
plot,y2,ymargin=ymulti(p)
plot,y3, title='bottom left',ymar=ymulti(p,np=2)
plot,y4, ymargin=ymulti(p)
plot,y1*y1, title='top right',ymar=ymulti(p,np=2)
plot,y2*y2, ymargin=ymulti(p)
plot,y3^2, title='bottom right',ymar=ymulti(p,np=2)
plot,y4^2, ymargin=ymulti(p)
AUTHOR Paul Ricchiazzi mar94
Institute for Computational Earth System Science
Univerity of California, Santa Barbara
MODIFIED Gwyn Fireman 7 Oct 1998
better way to disable intermediate X-axis labeling
disable intermediate Y-axis tick label
(See /home/drw/idl/esrg/ymulti.pro)
YMULTI[2]
[Previous Routine]
[Next Routine]
[List of Routines]
routine: ymulti
purpose: set up margins for vertically stacked multi frame plot
input:
p named variable, contains stuff you don't need to know
the contents of p are changed after each call
Keyword input
np number of frames in plot, set on first call only (see examples)
ymargin 2 element vector specifying overall margin setting
below (0) and above (1) multiframe plot
if ymargin is not set the top and bot margin is taken
from !y.margin. This keyword is ignored when NP not set
space the separation distance between frames of a multiframe
plot in units of the character height. This keyword is
ignored when NP not set. Default is no space between plots
SIDE EFFECTS: Changes the value of !p.multi(4) to enforce column
major ordering of plots. To reinsate the default row
major ordering, set !p.multi=0 or !p.multi(4)=0. Also
changes the value of !x.charsize to a very small value
to disable x-axis labeling on the upper frames. On
the bottom frame of a multi-frame plot !x.charsize is
restored to its original value.
EXAMPLE: create a three frame plot
y1=smooth(randomu(iseed,200),3)
y2=smooth(y1,11)
y3=smooth(randomu(iseed,200),11)
y4=smooth(y3,3)
!p.multi=[0,1,3]
plot,y1,ymargin=ymulti(p,np=3,ymargin=[5,3],space=1)
plot,y2,ymargin=ymulti(p)
plot,y3,ymargin=ymulti(p)
; Now try a four frame plot with no space between frames
!p.multi=[0,1,4]
plot,y1, ymargin=ymulti(p,np=4)
plot,y2, ymargin=ymulti(p)
plot,y3, ymargin=ymulti(p)
plot,y4, ymargin=ymulti(p)
; Now try a multi-column plot
!p.multi=[0,2,4]
plot,y1,title='top left',ymar=ymulti(p,np=2)
plot,y2,ymargin=ymulti(p)
plot,y3, title='bottom left',ymar=ymulti(p,np=2)
plot,y4, ymargin=ymulti(p)
plot,y1*y1, title='top right',ymar=ymulti(p,np=2)
plot,y2*y2, ymargin=ymulti(p)
plot,y3^2, title='bottom right',ymar=ymulti(p,np=2)
plot,y4^2, ymargin=ymulti(p)
AUTHOR Paul Ricchiazzi mar94
Institute for Computational Earth System Science
Univerity of California, Santa Barbara
(See /home/drw/idl/old.esrg/ymulti.pro)
ZENDAY[1]
[Previous Routine]
[Next Routine]
[List of Routines]
purpose: compute daylight average of solar zenith, daylight
hours per day and maximum solar zenith as a function of
latitude and day of year
useage: zenday,day,lat,mubar,mumax,hours
input:
day day of year
lat latitude
output:
mubar cosine of solar zenith angle (SZA) averaged over
daylight hours
mumax maximum value of cos(SZA)
hours hours of sunlight
NOTE: mubar*hours*Fo = average daily insolance
where Fo is the solar constant
EXAMPLE: as a function of latitude and season make plots of
;
; 1. hours of sunlight
; 2. average daylight value of cos(SZA)
; 3. daily average insolation
; 4. maximum cos(SZA)
!p.multi=[0,2,2]
day = findgen(365)+1
lat=findrng(-90,90,37)
gengrid,day,lat
zenday,day,lat,mubar,mumax,hours
ytickv=[-90,-75,-60,-45,-30,-15,0,15,30,45,60,75,90] & ytitle='Latitude'
contour, hours,day,lat, ytitle=ytitle,xstyle=5,/follow,$
ytickv=ytickv,yticks=14,levels=indgen(25),$
title='Daylight Hours'
xaxis_month
contour, mubar,day,lat, ytitle=ytitle,xstyle=5,/follow,$
ytickv=ytickv,yticks=14,levels=indgen(20)*.05,$
title='Average Daylight cos(zenith)'
xaxis_month
contour, 1371*hours*mubar/24.,day,lat, ytitle=ytitle,xstyle=5,/follow,$
ytickv=ytickv,yticks=14,levels=indgen(12)*50,$
title='Daily Average Insolation (W/m2)'
xaxis_month
contour, mumax,day,lat, ytitle=ytitle,xstyle=5,/follow,$
ytickv=ytickv,yticks=14,levels=indgen(20)*.05,$
title='Maximum cos(zenith)'
xaxis_month
;
AUTHOR: Paul Ricchiazzi 23oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/esrg/zenday.pro)
ZENDAY[2]
[Previous Routine]
[Next Routine]
[List of Routines]
purpose: compute daylight average of solar zenith, daylight
hours per day and maximum solar zenith as a function of
latitude and day of year
useage: zenday,day,lat,mubar,mumax,hours
input:
day day of year
lat latitude
output:
mubar cosine of solar zenith angle (SZA) averaged over
daylight hours
mumax maximum value of cos(SZA)
hours hours of sunlight
NOTE: mubar*hours*Fo = average daily insolance
where Fo is the solar constant
EXAMPLE: as a function of latitude and season make plots of
;
; 1. hours of sunlight
; 2. average daylight value of cos(SZA)
; 3. daily average insolation
; 4. maximum cos(SZA)
!p.multi=[0,2,2]
day = findgen(365)+1
lat=findrng(-90,90,37)
gengrid,day,lat
zenday,day,lat,mubar,mumax,hours
ytickv=[-90,-75,-60,-45,-30,-15,0,15,30,45,60,75,90] & ytitle='Latitude'
contour, hours,day,lat, ytitle=ytitle,xstyle=5,/follow,$
ytickv=ytickv,yticks=14,levels=indgen(25),$
title='Daylight Hours'
xaxis_month
contour, mubar,day,lat, ytitle=ytitle,xstyle=5,/follow,$
ytickv=ytickv,yticks=14,levels=indgen(20)*.05,$
title='Average Daylight cos(zenith)'
xaxis_month
contour, 1371*hours*mubar/24.,day,lat, ytitle=ytitle,xstyle=5,/follow,$
ytickv=ytickv,yticks=14,levels=indgen(12)*50,$
title='Daily Average Insolation (W/m2)'
xaxis_month
contour, mumax,day,lat, ytitle=ytitle,xstyle=5,/follow,$
ytickv=ytickv,yticks=14,levels=indgen(20)*.05,$
title='Maximum cos(zenith)'
xaxis_month
;
AUTHOR: Paul Ricchiazzi 23oct92
Earth Space Research Group, UCSB
(See /home/drw/idl/old.esrg/zenday.pro)
ZENSUN[1]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: zensun
PURPOSE: Compute solar position information as a function of
geographic coordinates, date and time.
USEAGE: zensun,day,time,lat,lon,zenith,azimuth,solfac,sunrise,sunset,
local=local
INPUT:
day Julian day (positive scalar or vector)
(spring equinox = 80)
(summer solstice= 171)
(fall equinox = 266)
(winter solstice= 356)
time Universal Time in hours (scalar or vector)
lat geographic latitude of point on earth's surface (degrees)
lon geographic longitude of point on earth's surface (degrees)
OUTPUT:
zenith solar zenith angle (degrees)
azimuth solar azimuth (degrees)
Azimuth is measured clockwise from due north
solfac Solar flux multiplier. SOLFAC=cosine(ZENITH)/RSUN^2
where rsun is the current earth-sun distance in
astronomical units.
NOTE: SOLFAC is negative when the sun is below the horizon
KEYWORD INPUT:
local if set, TIME is specified as a local time and SUNRISE
and SUNSET are output in terms of local time
NOTE: "local time" is defined as UT + local_offset
where local_offset is fix((lon+sign(lon)*7.5)/15)
with -180 < lon < 180
Be aware, there are no fancy provisions for
day-light savings time and other such nonsense.
KEYWORD OUTPUT:
sunrise Time of sunrise (hours)
sunset Time of sunset (hours)
latsun the latitude of the sub-solar point (fairly constant over day)
Note that daily_minimum_zenith=abs(latsun-lat)
lonsun the longitude of the sub-solar point
Note that at 12 noon local time (lon-lonsun)/15. is the
number of minutes by which the sun leads the clock.
; Often used lat, lon
Santa Barbara: 34.410,-119.727
Ellison Hall: 34.415,-119.846
SGP Cart Site: 36.605,-97.485
North Slope: 69.318,-151.015
Palmer Station: -64.767,-64.067
; EXAMPLE 1: Compute the solar flux at Palmer Station for day 283
time=findgen(1+24*60)/60
zensun,283,time,-64.767,-64.067,z,a,sf
solflx=sf*s
plot,time,solflx
where s is the TOA solar irradiance at normal incidence:
s=1618.8 ; W/m2/micron for AVHRR1 GTR100
s= 976.9 ; W/m2/micron for AVHRR2 GTR100
s=1685.1 ; W/m2/micron for 410nm GTR100
s= 826.0 ; W/m2/micron for 936nm GTR100
s=1.257e17 ; photons/cm2/s PAR GTR100
s=1372.9 ; w/m2 total broadband
; EXAMPLE 2: Find time of sunrise and sunset for current day
doy=julday()-julday(1,0,1994)
zensun,doy,12,34.456,-119.813,z,a,s,sunrise=sr,sunset=ss,/local &$
zensun,doy,[sr,.5*(sr+ss),ss],34.456,-119.813,z,az,/local &$
print,'sunrise: '+hms(3600*sr)+ ' PST azimuth angle: ',az(0) &$
print,'sunset: '+hms(3600*ss)+ ' PST azimuth angle: ',az(2) &$
print,'zenith: '+hms(1800*(ss+sr))+ ' PST zenith angle: ',z(1)
AUTHOR: Paul Ricchiazzi 23oct92
Earth Space Research Group, UCSB
REVISIONS:
jan94: use spline fit to interpolate on EQT and DEC tables
jan94: output SUNRISE and SUNSET, allow input/output in terms of local time
jan97: declare eqtime and decang as floats. previous version
this caused small offsets in the time of minimum solar zenith
(See /home/drw/idl/esrg/zensun.pro)
ZENSUN[2]
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: zensun
PURPOSE: Compute solar position information as a function of
geographic coordinates, date and time.
USEAGE: zensun,day,time,lat,lon,zenith,azimuth,solfac,sunrise,sunset,
local=local
INPUT:
day Julian day (positive scalar or vector)
(spring equinox = 80)
(summer solstice= 171)
(fall equinox = 266)
(winter solstice= 356)
time Universal Time in hours (scalar or vector)
lat geographic latitude of point on earth's surface (degrees)
lon geographic longitude of point on earth's surface (degrees)
OUTPUT:
zenith solar zenith angle (degrees)
azimuth solar azimuth (degrees)
Azimuth is measured clockwise from due north
solfac Solar flux multiplier. SOLFAC=cosine(ZENITH)/RSUN^2
where rsun is the current earth-sun distance in
astronomical units.
NOTE: SOLFAC is negative when the sun is below the horizon
sunrise UT of sunrise (hours)
sunset UT of sunset (hours)
KEYWORD INPUT:
local if set, TIME is specified as a local time and SUNRISE
and SUNSET are output in terms of local time
NOTE: "local time" is defined as UT + local_offset
where local_offset is fix((lon+sign(lon)*7.5)/15)
with -180 < lon < 180
Be aware, there are no fancy provisions for
day-light savings time and other such nonsense.
KEYWORD OUTPUT:
latsun the latitude of the sub-solar point
lonsun the longitude of the sub-solar point
; EXAMPLE 1: Compute the solar flux at Palmer Station for day 283
time=findgen(1+24*60)/60
zensun,283,time,-64.767,-64.067,z,a,sf
solflx=sf*s
plot,time,solflx
where s is the TOA solar irradiance at normal incidence:
s=1618.8 ; W/m2/micron for AVHRR1 GTR100
s= 976.9 ; W/m2/micron for AVHRR2 GTR100
s=1685.1 ; W/m2/micron for 410nm GTR100
s= 826.0 ; W/m2/micron for 936nm GTR100
s=1.257e17 ; photons/cm2/s PAR GTR100
s=1372.9 ; w/m2 total broadband
; EXAMPLE 2: Find time of sunrise and sunset for current day
doy=julday()-julday(1,0,1994)
zensun,doy,12,34.456,-119.813,z,a,s,sr,ss,/local &$
zensun,doy,sr,34.456,-119.813,z,arise,/local &$
zensun,doy,ss,34.456,-119.813,z,aset,/local &$
print,'sunrise: '+hms(3600*sr)+ ' azimuth: ',arise &$
print,'sunset: '+hms(3600*ss)+ ' azimuth: ',aset
PROCEDURE:
1. Calculate the subsolar point latitude and longitude, based on
DAY and TIME. Since each year is 365.25 days long the exact
value of the declination angle changes from year to year. For
precise values consult THE AMERICAN EPHEMERIS AND NAUTICAL
ALMANAC published yearly by the U.S. govt. printing office. The
subsolar coordinates used in this code were provided by a
program written by Jeff Dozier.
2. Given the subsolar latitude and longitude, spherical geometry is
used to find the solar zenith, azimuth and flux multiplier.
AUTHOR: Paul Ricchiazzi 23oct92
Earth Space Research Group, UCSB
REVISIONS:
3jan94: use spline fit to interpolate on EQT and DEC tables
5jan94: output SUNRISE and SUNSET, allow for input/output in terms of
local time
(See /home/drw/idl/old.esrg/zensun.pro)
ZIMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ZIMAGE
PURPOSE:
The purpose of this program is to display an image which
can be zoomed by drawing a rubberband box on top of it. The
"zoomed" image appears in its own window.
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:
Image Processing, Widgets.
CALLING SEQUENCE:
ZIMAGE, image
INPUTS:
image: A 2D array of image data.
KEYWORD PARAMETERS:
BOTTOM: The lowest color index of the colors to be used (see
NCOLORS). The default is 0.
COLORINDEX: The color index for the rubberband box. This index will
be loaded with a green color. Whatever color is there will
be restored when the ZIMAGE program exits. The default is
NCOLORS + BOTTOM.
NCOLORS: This is the number of colors to use when displaying the
image. The default is !D.N_COLORS-2.
GROUP_LEADER: This keyword is used to assign a group leader to this
program. This program will be destroyed when the group
leader is destroyed. Use this keyword if you are calling
ZIMAGE from another widget program.
NOINTERPOLATION: Setting this keyword causes nearest neighbor resampling of
of the zoomed image instead of the default bilinear interpolation
of resampled pixels.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
The COLORINDEX color is turned to green while the rubberband box
is being drawn. The color is restored after the box is drawn.
RESTRICTIONS:
Uses XCOLORS from the Coyote Library:
http://www.dfanning.com/programs/xcolors.pro
PROCEDURE:
Clicking the left mouse button allows you to drag a rubberband box
over the portion of the window you want to zoom into.
Clicking the right mouse button calls up hidden controls that allow
you to load different color tables and set the zoom factor.
The rubberband box is drawn with pixmaps and the "device copy"
technique.
This is an excellent example of how you can take advantage of the
widget program *as* the loop do to something (i.e., draw the box)
that in a regular IDL program would have to be done in a loop. It
is also a good example of modular programming style. Notice the draw
widget has two event handlers associated with it. Motion events
are only turned on for the draw widget when the box has to be
drawn.
EXAMPLE:
To display an image you can zoom into, type:
filename = FILEPATH(SUBDIR=['examples','data'], 'worldelv.dat')
image = BYTARR(360,360)
OPENR, lun, filename, /GET_LUN
READU, lun, image
FREE_LUN, lun
ZIMAGE, image
MODIFICATION HISTORY:
Written by: David Fanning, 15 August 96.
Fixed a !D.N_Colors problem. 17 June 98.
Made modifications so program works in 24-bit environment. 28 July 98. DWF.
Fixed a problem with the pop-up controls under certain circumstances.
13 Oct 98. DWF.
Added 24-bit color response. 13 Oct 98. DWF.
Added ability for each window to have its own color changing tool. 9 Oct 99. DWF.
Small changes, error checking. 24 April 2000. DWF.
(See /home/drw/idl/aux/zimage.pro)
ZOOM1.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ZOOM1.PRO
PURPOSE:
To enlarge the upper-right area of a 1024x1024 TRACE image
CALLING SEQUENCE:
zoom1,data,i
INPUTS:
data - input data cube
i - frame number of image in cube to be enlarged
HISTORY:
D. Williams 4/6/99
(See /home/drw/idl/bin/zoom1.pro)
ZOOMBAR[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
zoombar
USEAGE: while zoombar(range) do ...
PURPOSE:
Emulate the operation of a variable-sized box cursor (also known as
a "marquee" selector).
CATEGORY:
Interactive graphics.
CALLING SEQUENCE:
result = zoombar(range, INIT=init,message=message,$
ybar=ybar,xbar=xbar)
INPUTS:
No required input parameters.
OPTIONAL INPUT PARAMETERS:
x0, y0, nx, and ny give the initial location (x0, y0) and
size (nx, ny) of the box if the keyword INIT is set. Otherwise, the
box is initially drawn in the center of the screen.
KEYWORD PARAMETERS:
INIT
Sets the initial x or y range of the cursor bar. INIT should be
specified in data coordinates.
ybar
If this keyword is set, the horizontal size of the box
is fixed. Set this keyword to set vertical range
xbar
If this keyword is set, the vertical size of the box
is fixed. Set this keyword to set horizontal range
(default)
message
if set, an instructional pop-up widget appear
if MESSAGE is a string or string array, the contents of
MESSAGE are pre-pended to ZOOMBARs default instructions.
OUTPUTS:
result: 1 if exit is caused by RMB clicked inside bar
result: 0 if exit is caused by RMB clicked outside bar
range: the vertical (if ybar is set) or horizontal
(if xbar is set) range of the cursor bar.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A box is drawn in the currently active window. It is erased
on exit.
RESTRICTIONS:
Works only with window system drivers.
PROCEDURE:
The graphics function is set to 6 for eXclusive OR. This
allows the box to be drawn and erased without disturbing the
contents of the window.
Operation is as follows:
Left mouse button: Move the box by dragging.
Middle mouse button: Resize the box by dragging. The corner
nearest the initial mouse position is moved.
Right mouse button: Exit this procedure, returning the
current xrange or yrange parameters.
RMB click inside the bar, return value = 1
RMB click outside the bar, return value = 0
;; Example:
x=randf(1000,1.5) & plot,x & while zoombar(r,/mes) do plot,x,xr=r,/xst
;; select range in one window, plot zoomed plot in another:
window,1 & wset,0 & x=randf(1000,1.5) & plot,x & xs=!x & r=0
while zoombar(r,/mes,init=r) do begin &$
wset,1 & plot,x,xr=r & !x=xs & wset,0 & end
(See /home/drw/idl/esrg/zoombar.pro)
ZOOMBAR[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
zoombar
USEAGE: while zoombar(range) do ...
PURPOSE:
Emulate the operation of a variable-sized box cursor (also known as
a "marquee" selector).
CATEGORY:
Interactive graphics.
CALLING SEQUENCE:
result = zoombar(range, INIT=init,message=message,$
ybar=ybar,xbar=xbar)
INPUTS:
No required input parameters.
OPTIONAL INPUT PARAMETERS:
x0, y0, nx, and ny give the initial location (x0, y0) and
size (nx, ny) of the box if the keyword INIT is set. Otherwise, the
box is initially drawn in the center of the screen.
KEYWORD PARAMETERS:
INIT
Sets the initial x or y range of the cursor bar. INIT should be
specified in data coordinates.
ybar
If this keyword is set, the horizontal size of the box
is fixed. Set this keyword to set vertical range
xbar
If this keyword is set, the vertical size of the box
is fixed. Set this keyword to set horizontal range
(default)
message
if set, an instructional pop-up widget appear
if MESSAGE is a string or string array, the contents of
MESSAGE are pre-pended to ZOOMBARs default instructions.
OUTPUTS:
result: 1 if exit is caused by RMB clicked inside bar
result: 0 if exit is caused by RMB clicked outside bar
range: the vertical (if ybar is set) or horizontal
(if xbar is set) range of the cursor bar.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A box is drawn in the currently active window. It is erased
on exit.
RESTRICTIONS:
Works only with window system drivers.
PROCEDURE:
The graphics function is set to 6 for eXclusive OR. This
allows the box to be drawn and erased without disturbing the
contents of the window.
Operation is as follows:
Left mouse button: Move the box by dragging.
Middle mouse button: Resize the box by dragging. The corner
nearest the initial mouse position is moved.
Right mouse button: Exit this procedure, returning the
current xrange or yrange parameters.
RMB click inside the bar, return value = 1
RMB click outside the bar, return value = 0
;; Example:
x=randf(1000,1.5) & plot,x & while zoombar(r,/mes) do plot,x,xr=r,/xst
;; select range in one window, plot zoomed plot in another:
window,1 & wset,0 & x=randf(1000,1.5) & plot,x & xs=!x & r=0
while zoombar(r,/mes,init=r) do begin &$
wset,1 & plot,x,xr=r & !x=xs & wset,0 & end
(See /home/drw/idl/old.esrg/zoombar.pro)
ZOOMBOX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ZOOMBOX
PURPOSE:
The purpose of this program is to display an image which
can be zoomed by drawing a rubberband box on top of it. The
"zoomed" image appears in its own window. The program is written
in object graphics. Either 8-bit or 24-bit images may be used.
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:
Image Processing, Widgets.
CALLING SEQUENCE:
ZOOMBOX, image
INPUTS:
image: An 8-bit or 24-bit image.
GROUP_LEADER: This keyword is used to assign a group leader to this
program. This program will be destroyed when the group
leader is destroyed. Use this keyword if you are calling
ZOOMBOX from another widget program.
INTERPOLATE: Set this keyword to use bilinear interpolation on the sub-image
defined by the box when zooming. The default is to use nearest neighbor
interpolation.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
DEPENDENCIES:
Uses XCOLORS and PICKCOLOR from the Coyote Library:
http://www.dfanning.com/programs/xcolors.pro
http://www.dfanning.com/programs/pickcolor.pro
PROCEDURE:
Clicking the left mouse button allows you to drag a rubberband box
over the portion of the window you want to zoom into.
EXAMPLE:
IDL> ZOOMBOX
RESTRICTIONS:
Object graphics programs are really meant to be used on 24-bit displays.
Colors are decidedly ugly in 256 color environments.
MODIFICATION HISTORY:
Written by: David Fanning, 24 April 2000.
(See /home/drw/idl/aux/zoombox.pro)
ZOOM_EXTRACT.PRO
[Previous Routine]
[Next Routine]
[List of Routines]
PROJECT:
TRACE
NAME:
ZOOM_EXTRACT.PRO
PURPOSE:
takes the top right-hand quarter of any image (data)
and outputs it to out_array. Takes out the same area as
the NEWLIGHT/AVLIGHT routine family works on.
CALLING SEQUENCE:
zoom_extract, data, out_array
HISTORY:
David Williams 8/6/99
(See /home/drw/idl/bin/zoom_extract.pro)
ZPLOT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
ZPLOT
PURPOSE:
The purpose of this program is to display a line plot in a resizeable
graphics window which can be zoomed by drawing an "arrow box" on top
of it. To return to the un-zoomed plot, click and release anywhere in the window.
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.
CALLING SEQUENCE:
ZPlot, x, y
OPTIONAL INPUTS:
x: If only one positional parameter, this is assumed to be the
dependent data. If there are two positional parameters, this
is assumed to be the independent data in accordance with the
PLOT command.
y: The dependent data, if the X parameter is present.
KEYWORD PARAMETERS:
Any valid PLOT keyword can be used with this program. In additon,
the following keywords are defined specifically.
GROUP_LEADER: This keyword is used to assign a group leader to this
program. This program will be destroyed when the group
leader is destroyed. Use this keyword if you are calling
ZIMAGE from another widget program.
ZOOM_XSIZE: The initial X size of the plot window. Default is 400 pixels.
ZOOM_YSIZE: The initial Y size of the plot window. Default is 400 pixels.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Drawing colors are loaded into the color table.
RESTRICTIONS:
Zooms only along the X axis.
PROCEDURE:
Click and drag the cursor to create an "arrow box". The plot
is zoomed into the X coordinates of the box, when released.
To restore unzoomed plot, click and release anywhere in the
window.
EXAMPLE:
To display an plot you can zoom into, type:
ZPLOT
MODIFICATION HISTORY:
Written by: David Fanning, 15 February 2000.
Modified the original rubberband box to be an "arrow box". 1 April 2000. DWF.
(See /home/drw/idl/aux/zplot.pro)
[1]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
CONT_IMAGE
PURPOSE:
Overlay an image and a contour plot.
CALLING SEQUENCE:
CONT_IMAGE, IMAGE[,X,Y]
INPUTS:
IMAGE - 2 dimensional array to display.
OPTIONAL INPUTS:
X - 1 dimensional array of x-axis values.
Y - 1 dimensional array of y-axis values.
KEYWORD PARAMETERS:
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.
ASPECT - Set to retain image's aspect ratio. Assumes square
pixels. If ASPECT is set, the aspect ratio is
retained.
INTERP - Set to bi-linear interpolate if image is resampled.
NOCONTOUR - Set to just display the image with plot axes.
INVERT - Set to invert the image scale, ie image=255-image
TOP - The maximum value of the scaled image. If not set, then
it's set to (!d.n_colors < 255)-1.
MIN_VALUE - The minimum value of IMAGE to be displayed.
MAX_VALUE - The maximum value of IMAGE to be displayed.
COLORBAR - Set to display a color bar alongside the image.
BAR_TITLE - A text string to be used as the colorbar title if
COLORBAR is set.
BAR_WIDTH - Width of the colorbar, in pixels. Default is 10
pixels for non-scalable pixel devices, or 2% of
the plot width for scalable pixel devices.
BAR_OFFSET - Offset spacing between plot and colorbar. Default
is 10.
MODIFICATION HISTORY:
Adapted (i.e. stolen) from IMAGE_CONT.
D. L. Windt, Bell Laboratories, Nov 1989.
April 1994:
Changed image scaling to go from 32 to !d.n_colors, so that
TEK_COLOR can be called to use first 32 colors for other plotting.
Added _EXTRA keyword.
March 1998 - Added TOP, MIN_VALUE, MAX_VALUE, COLORBAR, and
BAR_TITLE keywords. Also fixed quite a few bugs.
Note that setting the XSTYLE, XTYPE, YSTYLE, and
YTYPE keywords has no effect: these parameters
are always set to 0,1,0, and 1, respectively.
August 1998 - Plots are now drawn properly when !p.multi is
different from 0. Added BAR_OFFSET keyword.
windt@bell-labs.com
(See /home/drw/idl/aux/cont_image.pro)
[2]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DGTZ_PLOT
PURPOSE:
A widget application used to extract (X,Y) values from an
image of plot. For example, you can use this program to
extract data from a published plot that you've scanned and
converted to an image array.
CATEGORY:
2D Graphics
CALLING SEQUENCE:
DGTZ_PLOT,IMAGE,XRANGE,YRANGE
INPUTS:
IMAGE - 2D array containing the plot image.
XRANGE - 2-element array specifying data range of X axis on
plot image.
YRANGE - 2-element array specifying data range of Y axis on
plot image.
KEYWORD PARAMETERS:
XTYPE - set if plot image has log x axis.
YTYPE - set if plot image has log x axis.
SXMAX - Visible size of draw widget along x direction, in pixels.
Default=512.
SYMAX - Visible size of draw widget along y direction, in pixels.
Default=512.
OUTPUTS:
The digitized X,Y pairs are listed on a widget. You can
also save these data to a file (using MORE.)
COMMON BLOCKS:
DGTZ_PLOT internal to this procedure.
PROCEDURE:
The image of the plot is displayed on a widget, and the user
can digitize points which are converted to X,Y values. The
first step,however, is generally to calibrate the X and Y
axes; the endpoints of the specified axis are digitized,
after pressing the Calibrate X Axis or Calibrate Y Axis
button.
MODIFICATION HISTORY:
David L. Windt, Bell Laboratories, May, 1997
September, 1998 - Addex SXMAX and SYMAX keywords.
windt@bell-labs.com
(See /home/drw/idl/aux/dgtz_plot.pro)
[3]
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GAUSSEXPO_FIT
PURPOSE:
Fit y=f(x) where:
f(x) = a0*exp(-z^2/2)+a3*exp(-abs(x-a4)/a5)+a6 and z=(x-a1)/a2
a0 = height of gaussian, a1 = center of gaussian, a2 = 1/e
width of ; gaussian, a3 = height of exponential, a4 = center
of exponential, ; a5 = 1/e width of exponential,
a6=background.
Estimate the parameters a0,a1,a2,a3,a4,a5,a6 and then call curvefit.
CALLING SEQUENCE:
YFIT = GAUSSEXPO_FIT(X,Y,A)
INPUTS:
X = independent variable, must be a vector.
Y = dependent variable, must have the same number of points as x.
OUTPUTS:
YFIT = fitted function.
OPTIONAL OUTPUT PARAMETERS:
A = Fit coefficients. A six element vector as described above.
MODIFICATION HISTORY:
Adapted from GAUSSFIT
D. L. Windt, Bell Laboratories, March, 1990
windt@bell-labs.com
(See /home/drw/idl/aux/gaussexpo_fit.pro)
~CDSTEST
[Previous Routine]
[Next Routine]
[List of Routines]
ROUTINE: cds_spectra1
PURPOSE: to extract spectra from a CDS/NIS raster for
various solar_x and solar_y positions
(re-writing az_sa.pro from scratch so I have
a better understanding of what's going on
at each stage; drw)
USEAGE: cds_spectra1,filename,qlds[,wave,spectrum?]
INPUT:
FILENAME - obvious
QLDS - calibrated CDS data in CDS qlds format
OUTPUT: (we'll see how I get along!)
a IDL save file is written containing ratios
for each chosen region.
AUTHOR: 21-Aug-2000, P. T. Gallagher (ptg@bbso.njit.edu)
(originally AZ_SA.PRO)
(See /home/drw/idl/secis/~cdstest.pro)
~MOVE_IT_BACK2
[Previous Routine]
[List of Routines]
MOVE_IT_BACK2,PROM,PROMOUT,DISPARR,INITIAL=INIT
(See /home/drw/idl/secis/~move_it_back2.pro)