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.1 2007/06/14 21:32:31 haimov Exp $
(See /tools/idl/idltools/arrinsert.pro)
NAME:
AUTOCORR (a modified version of A_CORRELATE)
PURPOSE:
This function computes the normalized autocorrelation of a sample
population X (1-D vector) as a function of the lag. Just as a
remainder, when selecting lags keep in mind that the autcorrelation
is an even function.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = autocorr(X, Lag)
INPUTS:
X: An n-element vector of type integer, float or double.
LAG: A scalar or n-element vector, in the interval [-(n-2), (n-2)],
of type integer that specifies the absolute distance(s) between
indexed elements of X. The default is interval 0 to n/2 with
step 1.
Note: It is recommended that the max(abs(lag)) does not exceed
10% of the X length in order to keep the errors in the
estimate low
KEYWORD PARAMETERS:
COVARIANCE: If set to 1 the sample autocovariance is computed;
to calculate autocorrelation function (does not
remove mean(X)) set COVARIANCE to -1
DOUBLE: If set to a non-zero value, computations are done in
double precision arithmetic.
NAN: If set to a non-zero value, treats NaNs in X as missing
values.
Note: the presence of missing values changes the
statistics of the estimate and the errors could be
significant; the errors have not been characterized
UNBIASED: If set to a non-zero value, unbiased estimate of the
covariance is calculated; this keyword is ignored if
COVARIANCE is 0 or not defined.
Note: the unbiased estimator is subject to a larger
variance in the estimate (for lags closer to the
end points) than the biased estimator
HELP: show this text
EXAMPLE
Define an n-element sample population.
x = [3.73, 3.67, 3.77, 3.83, 4.67, 5.87, 6.70, 6.97, 6.40, 5.57]
Compute the correlation coefficient of X for LAG = -3, 0, 1, 3, 4, 8
lag = [-3, 0, 1, 3, 4, 8]
result = autocorr(x, lag)
The result should be:
[0.0146185, 1.00000, 0.810879, 0.0146185, -0.325279, -0.151684]
PROCEDURE:
See computational formula published in IDL manual.
REFERENCE:
INTRODUCTION TO STATISTICAL TIME SERIES
Wayne A. Fuller
ISBN 0-471-28715-6
MODIFICATION HISTORY:
Written by: GGS, RSI, October 1994
Modified: GGS, RSI, August 1995
Corrected a condition which excluded the last term of the
time-series.
Modified: GGS, RSI, April 1996
Simplified AUTO_COV function. Added DOUBLE keyword.
Modified keyword checking and use of double precision.
CT, RSI, September 2002: Rewrote for speed, per W. Biagiotti suggestions.
Now handles large vectors and complex inputs.
CT, RSI, July 2003: Add note about using the mean over entire series.
SH, March 2009: Changed the name of the function from a_correlate to
autocorr, changed COVARIANCE keyword and added UNBIASED,
NAN and HELP keywords.
The changes have not been thoroughly tested
(See /tools/idl/idltools/autocorr.pro)
NAME:
AXIMAGE
PURPOSE:
Plot one or more images and draw axes and colorbar to X- or PS-device
CATEGORY:
idltools/image
CALLING SEQUENCE:
aximage,image,x,y
INPUTS:
image - fltarr(n,m), which does not need to be bytscl
x - fltarr(n), x-axis vector (default findgen(n))
y - fltarr(m), y-axis vector (default findgen(m))
KEYWORD PARAMETERS:
aspect - input, fltarr(2), [ratio,method], ratio represents actual
(physical) aspect ratio y/x, where y and x are in [unit/pixel]
(e.g., [m/pixel]);
method: -1 - down-sample greater dimension by ratio pixels
0 - average greater dimension by ratio pixels (default)
1 - interpolate smaller dimension by ratio pxls
2 - up-sample smaller dimension by ratio pixels
ATTENTION: method is ignored for a scaleable device (PS)'
barc - input, [bartype,baroffx,baroffy,barsize,begincolor,endcolor]
add vertical/horizontal colorbar
bar type:
1: adds horizontal bar; 3 : leaves space for hor. bar
2: adds vertical bar; 4: leaves space for ver. bar
baroffx/y: x/y bar offset
hor. bar default: baroffx=0.25, baroffy=0.
ver. bar default: baroffx=0., baroffy=0.15
baroff vals could be + or - but the offset direction
depends on plot position for multiple plots and the
bar is bound by the plot window size
barsize: size in normal units (0 to 1, default 0.6)
size > 1 might be used in some cases
If scroll window is used the bar type is ignored
Colors (used for image):
begincolor - first distinctive color in the color table to be used
endcolor - last distinctive color in the color table to be used
begincolor < endcolor = (0,number of distinctive colors)
Except for bartype you can use -1 to enforce default values
Example (use first part of WYO12 dual color table, 45):
barc=[1,-1,-1,-1,1,15] use first 15 colors from the color table
charsize - input, float, when set change the size of the labels
(default is 1.0). It is also useful to adjust the position
of the bar in case it partly overlaps with the axis labels
cross - when set, shows interactive cross-hair cursor;
input, byte>1, in addition zooms the traced area by the given
magnification (e.g. cross=4 will magnify 4 times)
extrabar - input, anonymous structure controling the color bar; accept all
keywords allowed by PLOT. Example:
aximage,image,/barc,extrabar={xtickname:['A','B'],xticks:1}
help - shows parameter/keyword descriptions
imgzoom - input,float, zoom factor for the image.
imgzoom<1 the image is decimated (no antialiasing filter is
applied; for more sophisticated resampling use
'resample' routine before running aximage);
imgzoom>1 the image is zoomed in (resampled) by linear
interpolation
isize - input, -1 causes isize output to be the plotted image array
otherwise plotted image size is returned
output, intarr(2), [xpix, ypix], number of x/y pixels plotted
or fltarr(xpix,ypix), plotted image
max - float, max value to be scaled for the image
min - float, min value to be scaled for the image
noerase - when set does not erase the graphics window (for X device)
nticks - input, bytarr(2), determines the approx. num. of ticks'
for x/y axes. If nticks is a byte, x-axis ticks only.
The following values have special meaning:
-1 : IDL auto
0 : aximage auto (attempt to determine best tick numbers)
1 : no tick labels
When combined with keyword timeax, nticks(0) sets approximate
number of x ticks
order - when set plots the image from top to bottom (defauls is bottom
to top); when used in combination with rotate function allows
different positioning of the image with respect to axes
resys - when set restore global(system) graphics variables changed
in aximage to their preveous values
revcolor - reverse colors in the image by acting directly on the image
array (while setwindow settings modify the color table):
1 - reverse colors of the image
-1 - reverse background (act as 1 for ps device)
2 - reverse colors and background (act as 1 for ps device)
This keyword is ignored if revct (part of setwindow) is 1 or 2.
setwindow - input,integer or intarr of up to 5 elements; set graphic window
to fit the image (for X and WIN devices only) and optionally;
a color table parameters [winn,colortb,revct,bf,ccol]:
winn: graphic window set
0 to 31 - opens winn graphic window
-1 - opens scroll widget graphic window if necessary
-2 - opens free(greater than 31) non-scroll window
colortb: loads color table with colortb number
revct: manipulate loaded color table
0 - leave the original color order
1 - reverse color table
2 - reverse color table not including first and last colors
3 - swap first and last colors in the color table
bf: change background and foreground colors in the loaded table
0 - no action
1 - replace first/last (back/foreground) colors w/ black/white
2 - replace first/last (back/foreground) colors w/ white/black
ccol: replace 4 color indices in the center of the color table
0 - no action
1 - use gray([200,200,200])
setwindow overrides the current graphic device and its settings
and cannot be combined with !p.multi.
silent - when set supress all standard outputs (useful for running
aximage in non-interactive mode)
timeax - byte/float, when set replaces x-axis as a time axis in hh:mm:ss
set from midnight and based on x given in seconds
0 : display original x
1 : display time axis in hh:mm:ss according to x in [s]
> 1 : adds the value to time axis and labels it in hh:mm:ss
timelbl - offset timeaxis labels as % of yrange; works with timeax only
title - string/strarr(2), main title and bar title when set bar
(default, none)
topxrange - fltarr(2), [topxmin,topxmax], when defined draws top x axis
according to the range given in topxrange
transpose - when set transpose the image; in this case don't forget to
exchange x and y. Example:
aximage,image[0:n-1,0:m-1],y[0:m-1],x[0:n-1],/transpose
xtitle - string/strarr(3), [bottom_xtitle, bar_title, top_xtitle], x-axis
titles and bar x title for horizontal bar (bar=1); default, none
ytitle - string, y-axis title (default, none)
widgetid - output, long, widget id or 10000+window_number when setwindow=-1
otherwise return -1; widget id can be used to destroy the widget
using widget_control: widget_control,widgetid,/destroy or
delete the ploting window: wdelete,widgetid-10000
winzoom - input,byte,when set zooms in(in a separate window) an area
around the cursor placed over the graphics by factor 4.
Input different integer number to use different zoom factors
Zoom window can be handled interactively using the mouse;
left button: zoom out; middle button: zoom in; right button: exit
Plus all keywords accepted by PLOT
NOTES: 0) This program uses routines from JHUAPL/S1R library
1) CHARSIZE affects the appearance of the image plot and the bar.
It can be used to adjust the output to a desirable shape.
2) The output for the display and PS could be rather different.
This is because PS is a scaleable device while the display is not.
Keep in mind that PS will always accomodate the whole image or
subimage in the allowed window (this may not be true if ASPECT
is used) while it might be clipped for the display
3) winn=-1 plots color bar when scroll X window is used
4) Color bar is not affected by any keywords included in _extra
Use EXTRABAR for additional graphics keywords.
5) Use PLOT keywords not explicitly listed in aximage with caution.
Not all of them have meaningful use in this environment.
6) Undesirable effects may occur for some combinations of
keywords. For example changing x/y margins while using
BARC keyword would not work properly. Another noticed and not
fixed bug is a shifted position of the axes when topxrange is
used.
EXAMPLES for different image rotations:
1) Display (IDL 0) image with given x and y (increasing in value):
aximage,image,x,y,setwindow=1
2) Display (IDL 1) image reversed in x:
aximage,rotate(image,7),reverse(x),y, setwindow=2
3) Display (IDL 2) image reversed in y:
aximage,image,x,reverse(y),/order,setwindow=3
4) Display (IDL 3) image reversed in x and y:
aximage,rotate(image,2),reverse(x),reverse(y),setwindow=4
(See /tools/idl/idltools/aximage.pro)
NAME:
BARTLETT
PURPOSE:
Returns n-point bartlett data window in double precision
CATEGORY:
idltools/signal
CALLING SEQUENCE:
res = bartlett(n,frac,help=help)
INPUTS:
N: long, size of the data window
Frac: long, number of points as fraction of N to be used for creating
bartlett taper (window with a flat top) with frac/2 in the
beginning and the end of the window following bartlett triangle;
frac must be less than N/2; default is 0 (no taper, returns
regular window)
KEYWORD PARAMETERS:
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/bartlett.pro)
NAME:
BARTLETT2
PURPOSE:
Returns [n,m]- 2-D Bartlett data window in double precision
CATEGORY:
idltools/signal
CALLING SEQUENCE:
res = bartlett2([n,m],[frn,frm], help=help)
INPUTS:
N: lonarr(2), [n,m], size of the data window
Frac: lonarr(2), [frn,frm], number of points as fraction of N
to be used for creating bartlett taper (window with a flat top)
with frac/2 in the beginning and the end of the window following
bartlett triangle; frac must be less than N/2;
default is 0 (no taper, returns regular window)
KEYWORD PARAMETERS:
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
PROCEDURE:
This function is a strightforward 2-D generalization
(See /tools/idl/idltools/bartlett2.pro)
NAME:
BLACKMAN
PURPOSE:
Returns n-point blackman data window in double precision
CATEGORY:
idltools/signal
CALLING SEQUENCE:
res = blackman(n,frac, wflag=wflag)
INPUTS:
N: long, size of the data window
Frac: long, number of points as fraction of N to be used for creating
blackman taper (window with a flat top) with frac/2 in the
beginning and the end of the window following blackman curve;
frac must be less than N/2; default is 0 (no taper, returns
regular window); frac < 16 is not recommended
KEYWORD PARAMETERS:
WFLAG: when set returns periodic window, otherwise it is symmetric
HELP: show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/blackman.pro)
NAME:
BLACKMAN2
PURPOSE:
Returns [n,m]- 2-D Blackman data window in double precision
CATEGORY:
idltools/signal
CALLING SEQUENCE:
res = blackman2([n,m],[frn,frm], wflag=wflag)
INPUTS:
N: lonarr(2), [n,m], size of the data window
Frac: lonarr(2), [frn,frm], number of points as fraction of N
to be used for creating blackman taper (window with a flat top)
with frac/2 in the beginning and the end of the window following
blackman curve; frac must be less than N/2;
default is 0 (no taper, returns regular window)
KEYWORD PARAMETERS:
WFLAG: when set returns periodic window, otherwise it is symmetric
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
PROCEDURE:
This function is a strightforward 2-D generalization
(See /tools/idl/idltools/blackman2.pro)
NAME:
CBAR
PURPOSE:
Make a color bar.
CATEGORY:
CALLING SEQUENCE:
cbar
INPUTS:
KEYWORD PARAMETERS:
Keywords:
VMIN=vmn Minimum value of color bar parameter (def=0).
VMAX=vmx Maximum value of color bar parameter (def=top).
CMIN=cmn Color that represents vmn (def=0).
CMAX=cmx Color that represents vmx (def=top).
where top = !d.table_size-1.
CCLIP=cc Actual max color index allowed (def=!d.table_size-1)
/HORIZONTAL Colors vary horizontally (def).
/VERTICAL Colors vary vertical.
/BOTTOM Horizontal axis on bottom (def).
/TOP Horizontal axis on top.
/RIGHT Vertical axis on right (def).
/LEFT Vertical axis on left.
/REVERSE Reverse color bar.
/KEEP_SCALING Keep color bar axes scaling on exit.
XSAVE=xs, YSAVE=ys, PSAVE=ps returned original scaling.
Use /KEEP to plot in cbar coordinates (x=[0,1],y=[vmn,vmx]).
May then restore original scale: !x=xs & !y=ys & !p=ps
Plus all keywords accepted by PLOT.
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: Bar is positioned using the POSITION keyword.
To display a title use TITLE and so on.
MODIFICATION HISTORY:
R. Sterner, 13 Dec, 1993
R. Sterner, 1994 Jul 5 --- Added axis positioning.
R. Sterner, 1995 Dec 10 --- Allow position to be in device coords.
R. Sterner, 1995 Dec 18 --- Fixed to not clobber current xy scaling.
R. Sterner, 1996 Dec 9 --- Added CCLIP keyword.
S. Haimov, 1997 Mar 20 --- Added REVERSE keyword
R. Sterner, 1998 Jan 23 --- Added charthick keyword.
R. Sterner, 2003 Jan 21 --- Added keyword /KEEP_SCALING, and [X|Y|P]SAVE.
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 /tools/idl/idltools/cbar.pro)
NAME:
CLEANPLOT
PURPOSE:
Reset all plotting system variables (!P,!X,!Y,!Z) to their default values
EXPLANATION:
Reset all system variables (!P,!X,!Y,!Z) which are set by the user
and which affect plotting to their default values.
CALLING SEQUENCE:
Cleanplot, [ /Silent, /Help]
INPUTS:
None
OPTIONAL KEYWORD INPUT:
/SILENT - If set, then CLEANPLOT will not display a message giving the
the system variables tags being reset.
/HELP - If set, shows this text
OUTPUTS:
None
SIDE EFFECTS:
The system variables that concern plotting are reset
to their default values. A message is output for each
variable changed. The CRANGE, S, WINDOW, and REGION fields of the
!X, !Y, and !Z system variables are not checked since these are
set by the graphics device and not by the user.
PROCEDURE:
This does NOT reset the plotting device.
This does not change any system variables that don't control plotting.
RESTRICTIONS:
If user default values for !P, !X, !Y and !Z are different from
the defaults adopted below, user should change P_old etc accordingly
MODIFICATION HISTORY:
Written IDL Version 2.3.0 W. Landsman & K. Venkatakrishna May '92
Handle new system variables in V3.0.0 W. Landsman Dec 92
Assume user has at least V3.0.0 W. Landsman August 95
V5.0 has 60 instead of 30 TICKV values W. Landsman Sep. 97
Change !D.N_COLORS to !D.TABLE_SIZE for 24 bit displays
W. Landsman April 1998
Added silent keyword to supress output & modified X_old to
handle the new !X and !Y tags in IDL 5.4 S. Penton July 2000
Test for visual depth if > V5.1 W. Landsman July 2000
Also reset negative values in !X W. Landsman November 2000
MacOS can report a visual depth of 32 W.Landsman March 2001
Added help keyword S. Haimov Apr 2001
(See /tools/idl/idltools/cleanplot.pro)
NAME:
COLINTRP
PURPOSE:
Linearly interpolates colors given in rgb or r,g,b
starting from color index colind to colind+length
CATEGORY:
idltools/graphics
CALLING SEQUENCE:
colintrp, rgb,colind,length,r=r,g=g,b=b, help=help
INPUTS:
rgb - bytarr(colors,3) with r,g, and b colors; colors is 256 or
max available colors (!D.TABLE_SIZE)
colind - starting color for interpolation, rgb(colind,*)
length - number of colors to be interpolated, rgb(colind:colind+length,*)
KEYWORD PARAMETERS:
r - bytarr(2), start/stop red color to be interpolated
g - bytarr(2), start/stop green color to be interpolated
b - bytarr(2), start/stop blue color to be interpolated
HELP - show this text
If any/all of r,g,b keywords is/are not defined colintrp uses colors from rgb
OUTPUTS:
rgb - array with interpolated colors
Examples:
1) Create interpolated color table between red and blue with 2 colors for
black background and 2 colors for white foreground and load to display
rgb=bytarr(!d.table_size,3) ; initilize rgb
rgb(2,*)=[255B,0B,0B] ; add start red color
rgb(!d.table_size-3,*)=[0B,0B,255B] ; add end blue color
rgb(!d.table_size-2:!d.table_size-1,*)=255B ; add white foreground
colintrp,rgb,2,!d.table_size-4 ; interpolate from red to blue
tvlct,rgb ; load color table
or same thing can be done
rgb=bytarr(!d.table_size,3)
rgb(2,*)=[255B,0B,0B]
colintrp,rgb,2,!d.table_size-4,r=[255,0],b=[0,255]
tvlct,rgb
(See /tools/idl/idltools/colintrp.pro)
NAME:
CREATECT
PURPOSE:
Create/recreate predifined WYO color tables or a new table
CATEGORY:
idltools/graphics
CALLING SEQUENCE:
CREATECT,rgb
CREATECT,rgb,idn,name,file
CREATECT,special='WYO1' (or any of the other predifined color tables)
CREATECT,special='WYO3',/gray
CREATECT,ncolors,special='new'
CREATECT,ncolors,idn,name,file=file,special='new',[/gray]
INPUTS:
Rgb - input, bytarr(ncolors,3) array, r,g,b user defined colors.
When special='new'
input, byte, number of colors, ncolors
Idn - input, byte, new color table ID number
Name - input, string, new color table ID name
KEYWORD PARAMETERS:
SPECIAL - input, string id for predifined Wyoming color tables 41 to 48
'WYO1', 'WYO2', 'WYO3', 'WYO_32', 'WYO12','WYO13','WYO_BW',
'WYO_YR'
- input, 'new', create widget based new color table
GRAY - when set adds 4B light gray strip in the midle of color table
FILE - input, string, path and file name of the color table to be
modified (default is current directory, colorwyo.tbl for
the predifined, 'special', color tables)
HELP - show this text
OUTPUTS:
COMMON BLOCKS:
common colors
NOTE: ncolors must be a factor of 252 (e.g., 1,2,3,4,6,7,9,12,14,18,21,28,36
42,63,84,126,252)
Two bytes of the color tables are reserved for black background and
white foreground and one byte is added to first and last color
(See /tools/idl/idltools/createct.pro)
NAME:
CROSSCORR (a modified version of C_CORRELATE)
PURPOSE:
This function computes the normalized cross-correlation of two sample
populations X and Y (1-D vectors) as a function of the lag.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = C_correlate(X, Y, Lag)
INPUTS:
X: An n-element vector of type integer, float or double.
Y: An n-element vector of type integer, float or double.
LAG: A scalar or n-element vector, in the interval [-(n-2), (n-2)],
of type integer that specifies the absolute distance(s) between
indexed elements of X.
KEYWORD PARAMETERS:
COVARIANCE: If set to a non-zero value, the sample cross covariance
is computed; to calculate autocorrelation function (does
not remove the mean from X and Y) set COVARIANCE to -1
DOUBLE: If set to a non-zero value, computations are done in
double precision arithmetic.
NAN: If set to a non-zero value, treats NaNs in X and Y as
missing values.
Note: the presence of missing values changes the
statistics of the estimate and the errors could be
significant; the errors have not been characterized
UNBIASED: If set to a non-zero value, unbiased estimate of the
covariance is calculated; this keyword is ignored if
COVARIANCE is 0 or not defined.
Note: the unbiased estimator is subject to a larger
variance in the estimate (for lags closer to the
end points) than the biased estimator
HELP: show this text
EXAMPLE
Define two n-element sample populations.
x = [3.73, 3.67, 3.77, 3.83, 4.67, 5.87, 6.70, 6.97, 6.40, 5.57]
y = [2.31, 2.76, 3.02, 3.13, 3.72, 3.88, 3.97, 4.39, 4.34, 3.95]
Compute the cross correlation of X and Y for LAG = -5, 0, 1, 5, 6, 7
lag = [-5, 0, 1, 5, 6, 7]
result = crosscorr(x, y, lag)
The result should be:
[-0.428246, 0.914755, 0.674547, -0.405140, -0.403100, -0.339685]
PROCEDURE:
See computational formula published in IDL manual.
REFERENCE:
INTRODUCTION TO STATISTICAL TIME SERIES
Wayne A. Fuller
ISBN 0-471-28715-6
MODIFICATION HISTORY:
Written by: GGS, RSI, October 1994
Modified: GGS, RSI, August 1995
Corrected a condition which excluded the last term of the
time-series.
- GGS, RSI, April 1996
Simplified CROSS_COV function. Added DOUBLE keyword.
Modified keyword checking and use of double precision.
- W. Biagiotti, Advanced Testing Technologies
Inc., Hauppauge, NY, July 1997, Moved all
constant calculations out of main loop for
greatly reduced processing time.
CT, RSI, September 2002. Further speed improvements, per W. Biagiotti.
Now handles large vectors and complex inputs.
SH, March 2009: Changed the name of the function from c_correlate to
autocorr, changed COVARIANCE keyword and added UNBIASED,
NAN and HELP keywords.
The changes have not been thoroughly tested
(See /tools/idl/idltools/crosscorr.pro)
NAME:
DATESTAMP
PURPOSE:
Print date/time stamp on the top-left corner of a page.
CALLING SEQUENCE:
datestamp, xypgpos=pos,inches=inches,comment=com,charsize=chars, $
user=user,rot=rot,setdev=setdev,xydpos=xydpos,help=help
INPUTS:
KEYWORD PARAMETERS:
xypgpos - input, fltarr(2), [top_left_offset, top_down_offset] in [cm]
for PS device only (default [1.,0.7])
inches - when set, xypgpos is given in inches (PS only)
comment - input string, appends to the end of the datetime stamp
charsize - input, float, datetime stamp character size (default 1.0)
user - when set, adds user name before the stamp
rot - input, byte, 0 - stamp printed on the top of the page
1 - stamp printed on the bottom of the page
2 - stamp printed at the left side of the page
setdev - input,fltarr(5),[xoffset,xsize,yoffset,ysize,ori]
when set, assumes that common block dev_com is not defined
(by setxpswin.pro). All parameters have to match corresponding
PS device in inches. ori should be 0 for portrait and 1 for
landscape. This parameter is valid for PS device only
xydpos - input, fltarr, [x,y] display position of the stamp in NORMAL
coordinates. For X device only, (default [0.01,0.98])
help - show this text
OUTPUTS:
COMMON BLOCKS:
common dev_comm, xoff, xsize, yoff, ysize, ori
NOTES:
Add date/time stamp to the current graphics device
Must be run after all plots in a page to avoid page change
Works for portrait and landscape.
Use setdev only when PS device is set not by setxpswin.pro and
dev_comm common block is not defined
DEFAULT STAMP
portrait orientation landscape orientation
top top
x=1 x=1
--------- -------------
y=0.7 | stamp | y=0.7 | stamp |
| | | |
| | | |
| | | |
| | -------------
| |
---------
(See /tools/idl/idltools/datestamp.pro)
NAME:
DETREND
PURPOSE:
Removes linear trend from a 1-D or 2-D array
CATEGORY:
idltools/signal
CALLING SEQUENCE:
res = detrend(y,trend=trend)
INPUTS:
Y: numerical array to be detrended
KEYWORD PARAMETERS:
NOFIT: detrend removes the mean only
TREND: output array matching Y with the trend values;
if NOFIT is set returns the mean of Y
HELP: show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
PROCEDURE:
Uses LSQ to find the linear trend
(See /tools/idl/idltools/detrend.pro)
NAME:
EDGE
PURPOSE:
For a given binary image returns its boundaries.
CATEGORY:
idltools/image
CALLING SEQUENCE:
Result=edge(image,pxsize,area=area,length=length,help=help)
INPUTS:
IMAGE: 2D binary image
PXSIZE: pixel scale factor (pixels are assumed squared, default=1)
KEYWORD PARAMETERS:
AREA: returns total number of pixels for IMAGE, scaled by PXSIZE^2
LENGTH: returns total length of the boundaries, scaled by PXSIZE
HELP: print,edge(/help) shows this text
PROCEDURE:
Finds all boundary pixels for any continuous non-zero pixels.
The image must consist of 0s and 1s (it could be other positive number)
SIDE EFFECT:
Boundary pixels are assigned values according to the number of
sides exposed to the 0 interface.
1- edge (one side exposed to 0)
2- corner (two sides exposed to 0s)
3- protruding pixel (3 sides exposed to 0s)
4- single pixel or diagonal shape of single pixels
EXAMPLE:
img=fltarr(40,100)
img(11:20,11:40)=1 & img(10,15)=1
img(18,50)=(img(19,51)=(img(19,50)=1))
img(28,50)=(img(29,51)=(img(30,50)=1))
img(25:35,61:90)=1
img(95,95)=1
pxsize=30. ; edge length in meters
bnd=edge(img,pxsize,area=ar,length=len)
aximage,img,setw=0,ntick=[3,3]
aximage,bnd,setw=1,ntick=[3,3]
(See /tools/idl/idltools/edge.pro)
NAME:
ELL_GEO_PT_SEP
PURPOSE:
Return geodesic separations of adjacent points in an array.
CATEGORY:
CALLING SEQUENCE:
ell_geo_pt_sep, x, y, d
INPUTS:
x, y = Input lng and lat array. in
KEYWORD PARAMETERS:
Keywords:
/LIST list separations (m) between point pairs.
NAME=nam Option list of point names.
OUTPUTS:
d = returned separations in m. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 2006 Feb 07
Copyright (C) 2006, 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 /tools/idl/idltools/ell_geo_pt_sep.pro)
NAME:
ELL_LL2RB
PURPOSE:
For two points on an ellipsoid return range and bearing.
CATEGORY:
CALLING SEQUENCE:
ell_ll2rb, lng1, lat1, lng2, lat2, dist, azi1, azi2
INPUTS:
lng1, lat1 = Point 1 geodetic long and lat (deg). in
lng2, lat2 = Point 2 geodetic long and lat (deg). in
KEYWORD PARAMETERS:
OUTPUTS:
dist = Distance along surface of ellipsoid (m). out
azi1 = forward geodetic azimuth (pt1 to pt2, deg). out
azi1 = reverse geodetic azimuth (pt2 to pt1, deg). out
COMMON BLOCKS:
NOTES:
Notes: Use ellipsoid,set=name to set working ellipsoid.
Uses T. Vincenty's method. Converted to IDL from FORTRAN code
at ftp://www.ngs.noaa.gov/pub/pcsoft/for_inv.3d/source/inverse.for
Example:
lng1 = 144.42486788D0 & lat1 = -37.95103341D0
lng2 = 143.92649552D0 & lat2 = -37.65282113D0
ell_ll2rb, lng1, lat1, lng2, lat2, dist, azi1, azi2
help, dist, azi1, azi2
Computed:
dist = 54972.271 meters
azi1 = 306.86816 deg
azi2 = 127.17363 deg
The Vicenty formulae should be good over distances from
a few cm to nearly 20,000 km with millimeter accuracy.
ell_rb2ll is inverse.
ll2rb is spherical version.
MODIFICATION HISTORY:
R. Sterner, 2001 Sep 04
R. Sterner, 2002 May 01 --- Generalized ellipsoid.
Copyright (C) 2001, 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 /tools/idl/idltools/ell_ll2rb.pro)
NAME:
ELL_TRACK_DIST
PURPOSE:
Return distance in meters along given track.
CATEGORY:
CALLING SEQUENCE:
d = ell_track_dist(lon,lat)
INPUTS:
lon, lat = Arrays of track longitudes and latitudes. in
These are arrays along a track.
KEYWORD PARAMETERS:
OUTPUTS:
d = Distances in meters along track for each point. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 2007 Dec 07
S. Haimov, 2008 Mar 07 - repalced Ray's cumulate with total(/cumul)
Copyright (C) 2007, 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 /tools/idl/idltools/ell_track_dist.pro)
NAME:
ERRORFINV
PURPOSE:
Returns inverse of the error function
CATEGORY:
idltools/general
CALLING SEQUENCE:
res = errorfinv(y)
INPUTS:
Y: float/double numerical scalar/array
KEYWORD PARAMETERS:
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
After the 7th significant digit the result(s) is/are different than
the corresponding values tabulated in Abramowitz and Stegun. It comes
from the insufficient accuracy of IDL error function, errorf (1996).
x=errorfinv(y) satisfies y=errorf(x), -1<=y<1, -Infinity<=x<=Infinity
(See /tools/idl/idltools/errorfinv.pro)
NAME:
FFT2SPEC
PURPOSE:
Estimates 2-D power spectra (psd) and related characteristics for one, x, or
two, x and y, 2-D data sequences, which could be real or complex.
2-D generalaized Welch method is implemented where (n,l) data sequence(s)
is(are) divided into m (overlapping or not) segments of (nwin,lwin) size,
each of which is detrended (mean or linear trend) then windowed, padded with
zeros (if needed) to a desired fft size, (nfft,lfft), FFT'd and accumulated.
CALLING SEQUENCE:
fft2spec, P,nfft,x,y,overlap=no,window=w,freq=freq,detrend=trend,raxis=rax,$
help=help
INPUTS:
nfft - input, [nfft,lfft], size of one segment fft; power of 2 is
recommended
x - input [n,l] array, real or complex data
y - input [n,l] array, (optional; type has to match x)
KEYWORD PARAMETERS:
Overlap(no) - when set gives the number of overlapping data points in a
segment, [no,lo], (default, [0,0]; maximum 0.75*nwin)
Window(w) - when set, [wintype,nwin] or [wintype,ntap,nwin]
wintype = 0 - no window (rectangular window)
1 - Hanning window
2 - Hamming window
3 - Blackman window
ntap - [ntap,ltap], when defined gives the number of wintype
points to be used for tapering of data window with
size nwin; usually ntap/nwin is about 0.1 to 0.2
nwin - [nwin,lwin], data window size over which nfft-points
FFT is performed
Default: [0,nfft= 2*nwin, lfft>=2*lwin
Time interpolation factor (2 and 4) may cause aliasing in the cov.
function. At this time this problem is not addressed.
(See /tools/idl/idltools/fft2spec.pro)
NAME:
FFTSPEC
PURPOSE:
Estimates power spectra (psd) and related characteristics for one, x, or two,
x and y, data sequences, which could be real or complex. Welch method is
implemented where n-point data sequence(s) is(are) divided into m (overlapping
or not) segments of nwin size, each of which is detrended (mean or linear
trend) then windowed, padded with zeros (if needed) to a desired fft size,
nfft, FFT'd and accumulated.
CALLING SEQUENCE:
fftspec, P,nfft,x,y,Pc=Pc,overlap=no,window=w,freq=f,conf=alpha, $
detrend=trend,raxis=rxya,moments=mom,help=hlp
INPUTS:
nfft - input, integer, size of one segment fft; power of 2 is
recommended; nfft is independent
x - input n-point vector, real or complex data
y - input n-point vector, (optional; type has to match x)
KEYWORD PARAMETERS:
Pc - when set, output, fltarr(k) for a single sequence (x) or
fltarr(k,7) for two sequences, x and y
Pc(*,0) - Pxxc, Pxx alpha*100% confidence interval
Pc(*,1) - Pyyc, Pyy alpha*100% confidence interval
Pc(*,2) - Pxyc, Pxy alpha*100% confidence interval
Pc(*,3) - Axyc, Axy alpha*100% confidence interval
Pc(*,4) - Txyc, Txy alpha*100% confidence interval
Pc(*,5) - Cxyc, Cxy alpha*100% confidence interval
Pc(*,6) - Pcoc, Co-Pxy alpha*100% confidence interval
Pc(*,7) - Pquc, Quad-Pxy alpha*100% confidence interval
Overlap(no) - when set gives the number of overlapping data points in a
segment (default, 0, maximum 0.75*nwin)
Window(w) - [wintype,nwin] or [wintype,ntap,nwin], data window parameters
wintype = 0 - no window (rectangular window)
1 - Hanning window
2 - Hamming window
3 - Blackman window
ntap - when defined gives the number of wintype points to be
used for tapering of data window with size nwin;
usually ntap/nwin is about 0.1 to 0.2
nwin - length of data window (data segment) over which nfft-
points FFT is performed
Default: [0,nfft= 2*nwin
Time interpolation factor (2 and 4) may cause aliasing in the cov.
function. At this time this problem is not addressed.
4) Confidence intervals, Txy and Cxy are not calculated and Pc=0 when
the number of segments, m, is 1 (no partitioning of the data).
5) The area under the spectrum equals the power in the data (DC is
excluded). Therefore for complex signals calculated spectra are
two-sided, while for real signals, one-sided.
6) For proper scaling of the spectra, sampling frequency, freq=fs is
required. This program calculates spectra as functions of freq.
not as functions of angular freq. (omega) or wave number (k).
7) Up to 50% overlapping is recommended when Hann, Hamming or Blackman
windows are used. Low or no overlapping should be used with tapers
to avoid correlation between sample spectra.
8) Co and Quadrature components of cross psd can be calculated from
Pxy and Axy. fftspec calculates conf. interval for Co- and Q- psds.
9) plotspec.pro can be used for plotting the results of fftspec
(See /tools/idl/idltools/fftspec.pro)
NAME:
FINDEQUAL
PURPOSE:
Finds multiple occurences of identical array values
CATEGORY:
idltools/general
CALLING SEQUENCE:
FINDEQUAL,Inarr,Outarr,Count
INPUTS:
Inarr: input array that will be searched for identical elements
KEYWORD PARAMETERS:
INDEX: Output structure; {sort:lonarr(k), start:lonarr(kk)}
sort: indices of the sorted Inarr
start: indices of Index.sort for the starting position of
a new unique element in the sorted Inarr
HELP: Prints this text
SORTED: When set assume sorted input array inarr
NOINDEX: When set will supress preparing the output structure INDEX
OUTPUTS:
Outarr: Sorted array with the unique values of Inarr only
OPTIONAL OUTPUTS:
Count: lonarr(kk) of the number of identical values in Inarr
RESTRICTIONS:
This routine has not been tested for multi-dimensional arrays yet
It does not work with NaN or Infinity.
EXAMPLE:
x=[1,0,2,2,1,1,4,5,4,6]
findequal,x,y,cnt,index=ind
y=[0,1,2,4,5,6]
cnt=[1,3,2,2,1,1]
ind.sort=[1,0,4,5,2,3,6,8,7,9]
ind.start=[0,1,4,6,8,9]
(See /tools/idl/idltools/findequal.pro)
NAME:
FIXANG
PURPOSE:
Fix angle discontinuety at 0-360.
CATEGORY:
CALLING SEQUENCE:
b = fixang(a)
INPUTS:
a = input array of angles. in
KEYWORD PARAMETERS:
Keywords:
/RADIANS means angles are in radians.
OUTPUTS:
b = array of angles with discontinueties removed. out
COMMON BLOCKS:
NOTES:
Notes: Assumes no valid delta angle GT 180 deg.
Looks for large jumps in the angle. Offset each
section to match one before. Angles may not be in
the range 0 to 360 when done.
MODIFICATION HISTORY:
Ray Sterner 13 Aug, 1985.
R. Sterner, 14 May, 1993 --- Cleaned up a little bit.
R. Sterner, 1998 May 8 --- Added new keyword /RADIANS.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1985, Johns Hopkins University/Applied Physics Laboratory
Wyoming. 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 expressed or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See /tools/idl/idltools/fixang.pro)
NAME:
GETFILE
PURPOSE:
Read a text file into a string array.
CATEGORY:
CALLING SEQUENCE:
s = getfile(f)
INPUTS:
f = text file name. in
KEYWORD PARAMETERS:
Keywords:
ERROR=err error flag: 0=ok, 1=file not opened,
2=no lines in file.
/QUIET means give no error message.
LINES=n Number of lines to read (def=all).
Much faster if number of lines is known.
Automatic for IDL 5.6 or later.
OUTPUTS:
s = string array. out
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 20 Mar, 1990
R. Sterner, 1999 Apr 14 --- Added LINES=n keyword.
R. Sterner, 2003 Aug 29 --- Automatic lines if IDL 5.6+.
R. Sterner, 2003 Sep 02 --- Check if file exists first.
R. Sterner, 2003 Sep 04 --- Fixed error in number of lines in file.
R. Sterner, 2003 Oct 10 --- Fixed error when no lines.
R. Sterner, 2004 Jan 27 --- Fixed to work in IDL as old as vers 4.
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See /tools/idl/idltools/getfile.pro)
NAME:
GRID
PURPOSE:
Overplot a grid on the current graphics. Must be run right after plot
CATEGORY:
idltools/graphics
CALLING SEQUENCE:
grid, gridstyle=gridstyle,xgrid=xgrid,ygrid=ygrid,help=help,$
_extra=extra
INPUTS:
KEYWORD PARAMETERS:
GRIDSTYLE: integer, sets grid style (see x/ygridstyle plot keywords);
default is 1 (dotted line)
XGRID: when set makes x-grid only
YGRID: when set makes y-grid only
HELP: show this text
The routine also accepts all graphics keywords allowed in plot command
IMPORTANT NOTE: This routine WON'T work in the following cases:
-> When !p.multi is used (hopefully this is fixed)
-> When several windows are opened and the single plots
have diffrent x/y ranges
At this point the use is limmited to single plots, and it is recommended
that GRID is executed right after the actual plot is created.
(See /tools/idl/idltools/grid.pro)
NAME:
HAMMING
PURPOSE:
Returns n-point Hamming data window in double precision
CATEGORY:
idltools/signal
CALLING SEQUENCE:
res = hamming(n,frac, wflag=wflag)
INPUTS:
N: long, size of the data window
Frac: long, number of points as fraction of N to be used for creating
hamming taper (window with a flat top) with frac/2 in the
beginning and the end of the window following hamming curve;
frac must be less than N/2; default is 0 (no taper, returns
regular window); frac < 16 is not recommended
KEYWORD PARAMETERS:
WFLAG: when set returns periodic window, otherwise it is symmetric
HELP: show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/hamming.pro)
NAME:
HAMMING2
PURPOSE:
Returns [n,m]- 2-D hamming data window in double precision
CATEGORY:
idltools/signal
CALLING SEQUENCE:
res = hamming2([n,m],[frn,frm], wflag=wflag)
INPUTS:
N: lonarr(2), [n,m], size of the data window
Frac: lonarr(2), [frn,frm], number of points as fraction of N
to be used for creating hamming taper (window with a flat top)
with frac/2 in the beginning and the end of the window following
hamming curve; frac must be less than N/2;
default is 0 (no taper, returns regular window)
KEYWORD PARAMETERS:
WFLAG: when set returns periodic window, otherwise it is symmetric
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
PROCEDURE:
This function is a strightforward 2-D generalization
(See /tools/idl/idltools/hamming2.pro)
NAME:
HANN
PURPOSE:
Returns n-point Hanning data window in double precision
CATEGORY:
idltools/signal
CALLING SEQUENCE:
res = hann(n,frac, wflag=wflag)
INPUTS:
N: long, size of the data window
Frac: long, number of points as fraction of N to be used for creating
hanning taper (window with a flat top) with frac/2 in the
beginning and the end of the window following hanning curve;
frac must be less than N/2; default is 0 (no taper, returns
regular window); frac < 16 is not recommended
KEYWORD PARAMETERS:
WFLAG: when set returns periodic window, otherwise it is symmetric
HELP: show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/hann.pro)
NAME:
HANN2
PURPOSE:
Returns [n,m]- 2-D hann data window in double precision
CATEGORY:
idltools/signal
CALLING SEQUENCE:
res = hann2([n,m],[frn,frm], wflag=wflag)
INPUTS:
N: lonarr(2), [n,m], size of the data window
Frac: lonarr(2), [frn,frm], number of points as fraction of N
to be used for creating hann taper (window with a flat top)
with frac/2 in the beginning and the end of the window following
hanning curve; frac must be less than N/2;
default is 0 (no taper, returns regular window)
KEYWORD PARAMETERS:
WFLAG: when set returns periodic window, otherwise it is symmetric
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
PROCEDURE:
This function is a strightforward 2-D generalization
(See /tools/idl/idltools/hann2.pro)
NAME:
IDLTOOLS
PURPOSE:
Show Sam Haimov generic IDL library routines
CATEGORY:
idltools
CALLING SEQUENCE:
idltools
___________________________________________________________________________
idltools.pro - Displays this information
**** idltools general routines:
errorfinv.pro - Returns inverse of the error function
findequal.pro - Finds multiple occurences of identical array values
isample.pro - Image digitizer. Samples the current graphics window
num2str.pro - Converts a numerical var/array to a string (array)
padstrarr.pro - Return padded with spaces string array that matches the
longest string in the array
pause.pro - Pauses the program until any key is pressed
pickfiles.pro - Widget to select one or more files
rebin1.pro - Resizes a vector/array (modified RSI rebin routine)
(Starting with idl5.5 this routine is obsolete; the standard
idl rebin routine can be used just like rebin1)
resample.pro - Returns a resized 1-D or 2-D input numerical array. The
input array or the resulting array could be non-evenly
sampled. Only the last dimension (for 2-D) can be
irregularly gridded.
replicarr.pro - Replicates N-dim. array to (N+1)-dim. array
sec2str.pro - Convert seconds after midnight to a time string
of the form: [DDD/]hh:mm:ss[:nnn/ddd]
sec2time.pro - Returns time after midnight given in seconds as hhmmss.dd
sec2timestr.pro - Returns time after midnight given in seconds as a
string/array 'hh:mm:ss'
srtm2hll.pro - Extract terrain elevation data (in meters) from SRTM data
strarr2str.pro - Concatenates the elements of a string array to a string
stradj.pro - Adjust a string or string array to the left, right or center
timeaxis.pro - Plot a time axis (slightly modified Ray's JHUAPL version)
time2sec.pro - Returns time after midnight given as hhmmss.dd in seconds
time2timestr.pro - Returns time after midnight given in hhmmss.dd as a
string/array 'hh:mm:ss'
timestr2sec.pro - Returns time given in 'hh:mm:ss[.dd]' as seconds after
midnight.
undefine.pro - Delete or undelete an IDL variable within an idl routine
(more powerful version of RSI delvar command line function)
unixtime2us.pro - Returns unix seconds (double) given unix date/time. UNIX
seconds are defined here as seconds from Jan 1 1970 00:00:00
us2unixtime.pro - Returns unix date/time given unix seconds
xmessage.pro - Widget based message display (similar to RSI dialog_message)
**** idltools graphics routines:
cleanplot.pro - Reset system variables !P,!X,!Y,!Z
colintrp.pro - Linearly interpolates colors given in rgb
createct.pro - Create color table
datestamp.pro - Print date/time stamp on the top-left corner of a page
fcolors.pro - Finds the number of discrete colors in a color table and
the starting color table index for every color
grid.pro - Adds grid to the current active plot
loadct1.pro - Modified version of RSI loadct routine
modifywyo_32.pro - Creates a 3-color table with black/white back/foreground
resetps2x.pro - Closes the graphics device and reset it to x device
setps.pro - Set postscript device
setxpswin.pro - Set X- or PS- device (many options available)
wyoctind.pro - Returns starting black color index for dual color tables
separated by a black color strip,
e.g. WYO12(ct=45), WYO23(ct=46)
xcolors.pro - change color tables in a manner similar to XLOADCT
It provides additional features and lists the color table
number
xcolort.pro - Changes a color table for given color indices
xcreatect.pro - Creates a color table for given color indices
**** idltools image processing routines:
aximage.pro - Plot one or more images and draw axes and colorbar to X/PS-device
edge.pro - For a given binary image returns its boundaries
rawimage.pro - Plots 2-D array displayed with its bigger size mapped on x axis
showprof.pro - Interactively draw row or column profiles of an image
zoom.pro - Display part of an image (or graphics) from the current window
enlarged in another window
**** idltools netcdf routines:
ncdf_addnew.pro - Add new dimension(s), variable or attribute(s) in an
existing netCDF file
ncdf_attload.pro - Returns string/string array of attribute value(s)
ncdf_dimnames.pro - Return string array with all the dimension names in a
netCDF file. It can also return the dimension sizes.
ncdf_fcopy.pro - Copy vars from a source netCDF file to a new netCDF file
ncdf_rename.pro - Rename existing dimension(s), variable(s) or attribute(s)
in a netCDF file
ncdf_update.pro - Update existing variable(s) or attribute(s) in a netCDF file
ncdf_vardef1.pro - Add a new variable to an open netCDF file in define mode
ncdf_varinq1.pro - Returns a structure with information about netCDF variable
ncdf_varload.pro - Returns a hyperslab of values from a netCDF variable
ncdf_varnames.pro - Returns a string array with all var names in a netCDF file
**** idltools printer routines:
printidlps.pro - Prints idl.ps file and rename/remove the file (UNIX)
printps.pro - Prints PS file(s) (UNIX)
**** idltools signal processing routines:
bartlett.pro - Returns n-point Bartlett data window
bartlett2.pro - Returns 2-D Bartlett data window
blackman.pro - Returns n-point Blackman data window
blackman2.pro - Returns 2-D Blackman data window
detrend.pro - Removes linear trend from a 1-D or 2-D array
fft2spec.pro - Estimates 2-D power spectra (psd)
fftspec.pro - Estimates 1-D power spectra (psd)
hamming.pro - Returns n-point Hamming data window
hamming2.pro - Returns 2-D Hamming data window
hann.pro - Returns n-point Hanning data window
hann2.pro - Returns 2-D Hanning data window
linaverage.pro - Averages dependent variable y and independent variable x
in nlint equally (linearly) spaced bins of x
logaverage.pro - Averages dependent variable y and independent variable x
in nlint equally,log10 scale, spaced bins of x
plotspec.pro - Plots the results from fftspec
spectrogram.pro - Estimates fft spectrogram (PSD as a function of freq and time)
**** idltools statistics routines:
kurt.pro - Returns the kurtosis of an array
mean.pro - Returns mean value for a random variable
pdfmom.pro - Computes the first 5 moments of a given distribution
skew.pro - Returns the skewness of an array
std.pro - Returns unbiased standard deviation/variance for a random variable
___________________________________________________________________________
(See /tools/idl/idltools/idltools.pro)
NAME:
ISAMPLE
PURPOSE:
This routine serves as an image digitizer. It samples the current
graphics window area and returns X/Y DATA coordinates
CATEGORY:
idltools/general
CALLING SEQUENCE:
isample,x,y,n
INPUTS:
N: Optional number of samples; integer; MAx N <= 500
If N <= 0 it is ignored and used as output parameter
If N is not given up to 500 points can be sampled
OUTPUTS:
X: X-coordinate samples in DATA coordinate; float array
Y: Y-coordinate samples in DATA coordinate; float array
N: Number of points sampled; integer; Max N <= 500
KEYWORD PARAMETERS:
CLICKTIME: Adjust click time for taking a sample in sec.
Default is 0.2 s. Min=0.2 s; Max=1.0
HELP: Shows this text
PROCEDURE:
Uses JHUAPL crossi routine
SIDE EFFECT:
Holding the mouse button longer than CLICKTIME causes
recordings of multiple samples from the same location
EXAMPLE:
wset,0
isample,x,y,32,clicktime=0.25
(See /tools/idl/idltools/isample.pro)
NAME:
KURT
PURPOSE:
Returns the kurtosis of an array X.
CALLING SEQUENCE:
result=kurt(x, dim, var=var, nan=nan, help=help)
INPUTS:
x - input array (any numerical type)
dim - the array dimension over which to calculate kurt, starting from 1
If DIM=0 or not present kurt for the whole array is calculated.
OUTPUTS:
The result is a scalar for DIM=0 or not present. For DIM > 0 the result
is an array with one less dimension than X. For double and complex
type arrays the result is of the same type; for all others it is
single-precision floating.
The result is normalized with respect to Gaussian distribution
(i.e. for Gaussian distribution kurtosis=0.)
KEYWORD PARAMETERS:
nan - when set, NaNs in X are treated as missing values
help - prints this help
SIDE EFFECTS:
This function does not work for multi-dimensional complex arrays
NOTES:
The result has better precision and the computation is faster for
1_D arrays or when DIM=0.
print,kurt() prints out the usage
(See /tools/idl/idltools/kurt.pro)
NAME:
LINAVERAGE
PURPOSE:
Averages dependent variable y and independent variable x in n
equally, linear scale, spaced bins of x
CATEGORY:
idltools/signal
CALLING SEQUENCE:
linaverage, n,x,y,xa,ya,yastd=yastd,xastd=xastd,nan=nan,help=help
INPUTS:
N - integer, number of bins for x
fltarr(3), n(0)=x_min, n(1)=x_max, n(2)=x_step
Y - fltarr(np), np-point data sequence
X - fltarr(np), np-point argument for y
KEYWORD PARAMETERS:
YASTD: output, fltarr(nlint), standard deviation of ya
XASTD: output, fltarr(nlint), standard deviation of xa
NAN: when set, interprets NaN values in x and y as missing values
HELP: Show this text
OUTPUTS:
Ya - fltarr(nlint), averaged data sequence
Xa - fltarr(nlint), averaged argument sequence, corresponding to ya
COMMON BLOCKS:
SIDE EFFECTS:
yastd and xastd are calculated if 5 or more data points are available
otherwise 0 values are assigned
(See /tools/idl/idltools/linaverage.pro)
NAME:
LOADCT1
PURPOSE:
Load predefined color tables. This is a modified version of the RSI LOADCT
routine with added color table manipulations.
CATEGORY:
idltools
CALLING SEQUENCE:
loadct1 [, Table],revct=revct,bf=bf,ccol=ccol,silent=silent,file=file,help=help
INPUTS:
Table: byte, identification number of the pre-defined color table to load.
If this value is omitted, a menu of the available tables is printed
and the user is prompted to enter a table number.
KEYWORD PARAMETERS:
BF: input, change background and foreground colors in the table
0 - no action (default, same as not defined)
1 - replace first/last (back/foreground) colors with black/white
2 - replace first/last (back/foreground) colors with white/black
CCOL: input, integer or intarr(3), RGB triplet defining a color to be
placed in the center of the selected color table; uses 4 of the 256
color indices (approx. 1.5% of the table);
0 - no action (default, same as not defined)
1 - use gray color [200,200,200]
FILE: input, string, file by the given name is used instead of the IDL
colors1.tbl file
REVCT: input, byte, manipulate loaded color table
0 - no action (default, same as not defined)
1 - reverse color table
2 - reverse color table w/o changing first and last colors
3 - swap first and last colors in the color table
SILENT: when set, the Color Table message is suppressed.
HELP: show this text
All other keywords allowed by LOADCT are also accepted.
OUTPUTS:
SIDE EFFECTS:
When SILENT is not used prints out color table identification message
This routine does not affect the background (!P.BACKGROUND) and foreground
(!P.COLOR) settings. Therefore the use of REVCT and BF will impact the
color of the background and the axes. A side effect of this is that for
PS device the axes may become invisible (if last color becomes white) and
thus it would require change in !P.COLOR prior to PS plotting.
The following is an example using PS device,which requires change in the
foreground color to make the axes visible, when making 255 color to be
white (loadct,41,revct=3):
setxpswin,99,2
!p.color=255B ; change the default (0) to 255
loadct1,3, revct=3
aximage,[findgen(200,300),fltarr(200,300)*!values.f_nan]
loadct1,3
!p.color=0B
aximage,fltarr(400,500)*!values.f_nan
resetps2x
EXAMPLES:
loadct1,16,bf=2 ; loads 'Hase' table and replace first and last colors
in the table with white and black,respectively
(See /tools/idl/idltools/loadct1.pro)
NAME:
LOGAVERAGE
PURPOSE:
Averages dependent variable y and independent variable x in nlint
equally, log10 scale, spaced bins of x
CATEGORY:
idltools/signal
CALLING SEQUENCE:
logaverage, nlint,x,y,xa,ya,help=help
INPUTS:
Nlint - integer, number of bins for log10(x)
Y - fltarr(np), np-point data sequence
X - fltarr(np), np-point argument for y
KEYWORD PARAMETERS:
HELP: Show this text
OUTPUTS:
Ya - fltarr(nlint), averaged data sequence
Xa - fltarr(nlint), averaged argument sequence, corresponding to ya
COMMON BLOCKS:
SIDE EFFECTS:
NOTES:
1) x must be non-negative
2) nlint must be less than np (usually nlint << np)
3) this program is used in plotspec routine to smooth graphics
plotted in x-log scale
(See /tools/idl/idltools/logaverage.pro)
NAME:
MATCHARR
PURPOSE:
Returns indices of vector A for the values in A matching the
values in vector B
CALLING SEQUENCE:
inda=matcharr(a,b, indb=indb,count=count)
INPUTS:
A: n-element vector
B: m-element vector
OUTPUTS:
OPTIONAL KEYWORD OUTPUT:
INDB: input, when set inda returns the indices of b matching a
COUNT: output, long, set to the number of matches,
SIDE EFFECTS:
!ERR is set to the number of matches, can be used instead of COUNT
RESTRICTIONS:
A and B should not have duplicate values within them.
You can use rem_dup function to remove duplicate values
in a vector
EXAMPLE:
If a = [3,5,7,9,11] & b = [5,6,7,8,9,10]
then
inda=matcharr(a,b)
will give inda = [1,2,3]
indb=matcharr(a,b,/indb)
will give indb = [0,2,4]
and suba(a) = subb(b) = [5,7,9]
HISTORY:
D. Lindler Mar. 1986.
Fixed "indgen" call for very large arrays W. Landsman Sep 1991
Added COUNT keyword W. Landsman Sep. 1992
Fixed case where single element array supplied W. Landsman Aug 95
Changed match to a function called matcharr S. Haimov Oct 2008
(See /tools/idl/idltools/matcharr.pro)
NAME:
MEAN
PURPOSE:
Returns mean value for a random variable X.
CALLING SEQUENCE:
result=mean(x, dim, double=double,nan=nan,silent=silent,help=help)
INPUTS:
X: input array (any numerical type)
Dim: the array dimension over which to calculate mean, starting from 1
If DIM=0 or not present mean for the whole array is calculated.
OUTPUTS:
The result is a scalar for DIM=0 or not present. For DIM > 0 the result
is an array with one less dimension than X. For LONG, DOUBLE, DCOMPLEX,
ULONG, LONG64, or ULONG64 the result is DOUBLE; for BYTE, INT, FLOAT it
is FLOAT; and for the complex types it matches the type.
KEYWORD PARAMETERS:
DOUBLE: if set to a non-zero value, computations are done in
double precision arithmetic (this is include for compatibility
with the IDL mean routine added with IDL version 5.1)
NAN: when set, NaNs in X are treated as missing values
SILENT: when set, information messages are suppressed
HELP: prints this help
SIDE EFFECTS:
The function returns NaN when no finite values are found for
the averaged array or part of the array regardless if NAN
keyword is set or not.
The function returns empty string '' if X is non-numerical.
When NAN keyword is set but there are no valid data (all values
are NaN or Inifinity) the result is NaN.
NOTES:
print,mean() prints out the usage
Same name function was added to standard IDL library with idl 5.1.
This kind of name conflicts are always possible thus it is a good
practice for the user to arrange the IDL path in an order where the
desired routines with duplicated names are found first.
It may be useful to be reminded that when an array is assembled
using numerical data of different types there is precedence that
determines the type of the array. For example if you try to use
!values.f_nan as missing values in an array of long integers the
array will be converted to float and some of the long integers
in single precision float may not be correct.
(See /tools/idl/idltools/mean.pro)
NAME:
MODIFYWYO_32
PURPOSE:
Creates a 3-color table with black background and white foreground
and adjustable color widths according to crange.
CALLING SEQUENCE:
modifywyo_32, crange
INPUT:
crange - 4-element integer/float array giving the color boundaries
in data defined units, [min,mid1,mid2,max]. Normally min and
max should equal the min/max values for the image being plot
with this color table or match the desired min/max values
given in keywords, (e.g., aximage,image,max=max,min=min).
NOTE: The newly created color table does not modify the standard table
and is active during the current IDL session.
(See /tools/idl/idltools/modifywyo_32.pro)
NAME:
NCDF_ADDNEW
PURPOSE:
Add new dimension(s), variable or attribute(s) in an existing
netCDF file
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
ncdf_addnew,Cdfid,name,value,rtype [,filename],gatt=gatt, $
close=close,silent=silent,help=help
INPUTS:
Cdfid: netCDF file ID, returned from a previous call to
ncdf_open, ncdf_create. The netcdf file must be in WRITE
and data mode (see Notes)
Name: string/long or strarr/lonarr, name of new dimension(s),
variable or attribute(s)
When Rtype='var' Name is the following string array:
[varname, dimname1, ...]; where dimname1, ..., are netCDF
file existing dim names containing the dim sizes of Value
Value: scalar or array with value(s) for Name
any allowed netcdf type;
Rtype: string/strarr, identifies netcdf entity to be renamed (see Notes)
Allowed strings/strarr are:
'dim' - Name is dimension(s)
'var' - Name is a variable
'global' - Name is global attribute(s) (see Notes)
'allvars'- Name is attribute(s) to be added to all existing
variables in the netCDF file
att_var - String/strarr with name(s) of the netcdf variable(s)
for which Name attribute will be added
Filename: string, optional netCDF file name; if given will open netCDF
file in WRITE and data modes. In this case Cdfid is an output
parameter
KEYWORD PARAMETERS:
GATT: input, strarr(2); optional new global attribute to be added
gatt[0] - attribute name, gatt[1] - attribute value;
(recommended for adding global history attribute)
CLOSE: when set netcdf file will be closed. Default is to keep the
file open in WRITE mode. CAUTION: If a writable netcdf file
is not closed before exiting IDL, the disk copy of the file
may not reflect recent data changes or new definitions.
SILENT: suppress information messages
HELP: shows this text
OUTPUTS:
Cdfid: netCDF file ID, returned if Filename is given
SIDE EFFECTS:
The routine displays the names of the updated variable or attribute(s)
When adding attributes to all relevant variables (vars that do not
have attribute(s) Name) the routine always prints out a message with the
number of variables for which attribute values were updated.
NOTES:
* Only one variable per routine call can be added, while one or more
dimensions or attributes can be added for each routine call.
* When updating multiple attributes the following restrictions apply:
- all attributes must have scalar values
- all attributes must be the same data type
These restrictions are result of the 1-D simple array allowed for
Value
* Be aware that when a netcdf file is closed the Cdfid becomes invalid
but is not deleted. Thus any attempt to read a new file with a new
filename but same Cdfid will result in error. The reason for this
behavior is that with a new file name and existing (defined) Cdfid
the program tries first to close the netcdf file corresponding to
the existing Cdfid. This is to prevent leaving unintentionally a
large number of open netcdf files.
EXAMPLES:
The following calls will add a 2-D array z(100,2000) as a netcdf
variable Z with dimensions range and time. The dimension range
is not defined and time is already defined with size 2000 in the
netcdf file called mydata.nc.
1) Add range dimension and size it to 100
ncdf_addnew,'range',100,'dim','mydata.nc'
2) Add the variable Z
ncdf_addnew,ncid,['Z','range','time'],z,'var'
3) Add 3 attributes to the variable Z and add global attribute
history to acknowledge the addition of Z to the file. Note that the
3rd attribute has a numerical value and cannot be added together
with the string type attributes. Finally close the netcdf file,
which has been open for writing and in data mode.
attnames=['long_name','units']
attvalues=['Radar reflectivity','dBZ']
glob=['History','Added dim range and var Z, S.H.,02/01/21']
ncdf_addnew,ncid,attnames,attvalues,'Z'
ncdf_addnew,ncid,'CalValue',47.5,'Z',gatt=glob
ncdf_close,ncid
delvar,ncid ; to remind me ncid isn't a valid nc file ID anymore
(See /tools/idl/idltools/ncdf_addnew.pro)
NAME:
NCDF_ATTLOAD
PURPOSE:
The function returns:
string or string array with the value(s) of requested attribute(s)
It is an expanded version of IDL ncdf_attget.
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
result=ncdf_attload(Cdfid [,varname] ,attname [,filename],
global=global,silent=silent,help=help)
INPUTS:
Cdfid: netCDF file ID, returned from a previous call to
ncdf_open, ncdf_create, ncdf_varload or ncdf_fcopy (see Notes)
Varname: string, netCDF variable name for which attribute(s)
is(are) loaded
Attname: string, netCDF att. name. If 'allatts' is given return all
attribute names and their corresponding values as string array
Filename: string, optional netCDF file name; if given will open netCDF
file first. In this case Cdfid is an output var
Silent: supress informational messages
KEYWORD PARAMETERS:
GLOBAL: if set Attname is global attribute and Varname must be omitted
HELP: shows this text
OUTPUTS:
Cdfid: netCDF file ID, returned if Filename is given
SIDE EFFECTS:
The function returns strings:
'-1' if the variable is not found or
'-2' if the attribute is not found or the variable has no attributes
Format of the return:
For "allatts": string array with all Varname att names and values
For single attribute: scalar or array with attribute value(s)
NOTES:
* Be aware that when a netcdf file is closed the Cdfid becomes invalid
but is not deleted. Thus any attempt to read a new file with a new
filename but same Cdfid will result in error. The reason for this
behavior is that with a new file name and existing (defined) Cdfid
the program tries first to close the netcdf file corresponding to
the existing Cdfid. This is to prevent leaving unintentionally a
large number of open netcdf files.
EXAMPLES:
(See /tools/idl/idltools/ncdf_attload.pro)
NAME:
NCDF_BROWSER
PURPOSE:
This program is designed to make it easier to browse
and read the data and metadata in netCDF files. The user
can browse files, and read the data and metadata into
main-level IDL variables. New netCDF files can be opened
at any time. The user interacts with the program via a
graphical user interface (GUI).
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:
File I/O
CALLING SEQUENCE:
IDL> NCDF_Browser, filename
Arguments:
filename: The name of a netCDF file to open and browse.
KEYWORD PARAMETERS:
EXTENSION: In general, netCDF files use *.nc, *.ncf, or *.ncdf file extensions to
identify themselves as netCDF files. Some users have their own file extensions.
You can use this keyword to identify the file extension you wish to use. If
set here, it will be used as the file filter in place of the normal file
extensions in DIALOG_PICKFILE.
obj = ('NCDF_DATA', file, EXTENSION='*.bin')
HELP: When set the routine displays this text
NOTES:
This program is only a (useful) front-end for a more flexible
object program of class NCDF_DATA. In this front end, the NCDF_DATA
object is created and then destroyed when the GUI is destroyed.
The NCDF_DATA object can be used to read netCDF data in a non-interactive
way, if you prefer not to use a GUI to interact with the data file.
REQUIRES:
The following programs are required from the Coyote Library.
http://www.dfanning.com/netcdf_data__define.pro
http://www.dfanning.com/error_message.pro
http://www.dfanning.com/centertlb.pro
http://www.dfanning.com/undefine.pro
http://www.dfanning.com/textbox.pro
http://www.dfanning.com/fsc_base_filename.pro
http://www.dfanning.com/textlineformat.pro
MODIFICATION HISTORY:
Written by: David W. Fanning, 03 Feb 2008. Used ideas from many
people, including Chris Torrence, Ken Bowman, Liam Gumely,
Andrew Slater, and Paul van Delst.
Added Extension keyword. DWF. 04 Feb 2008
Added Help keyword. SH 08 Feb 2008
(See /tools/idl/idltools/ncdf_browser.pro)
NAME:
NCDF_DIMNAMES
PURPOSE:
Return string array with all the dimension names in a netCDF file.
It can also return the dimension sizes.
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
result=ncdf_dimnames(Cdfid [,filename],help=help, $
recdimname=recdimname,recdimsize=recdimsize,dimsize=dimsize)
INPUTS:
Cdfid: netCDF file ID, returned from a previous call to
ncdf_open, ncdf_create, ncdf_varload or ncdf_fcopy (see Notes)
Filename: string, optional netCDF file name; if given will open netCDF
file first. In this case Cdfid is an output var
KEYWORD PARAMETERS:
RECDIMNAME: output,string, returns the name of the unlimited dimension
(null string if does not exist)
RECDIMSIZE: output,long, returns unlimited dimension size if any
DIMSIZE: output, lonarr, returns corresponding dimension sizes
HELP: shows this text
OUTPUTS:
Cdfid: netCDF file ID, returned if Filename is given
NOTES:
* Be aware that when a netcdf file is closed the Cdfid becomes invalid
but is not deleted. Thus any attempt to read a new file with a new
filename but same Cdfid will result in error. The reason for this
behavior is that with a new file name and existing (defined) Cdfid
the program tries first to close the netcdf file corresponding to
the existing Cdfid. This is to prevent leaving unintentionally a
large number of open netcdf files.
(See /tools/idl/idltools/ncdf_dimnames.pro)
NAME:
NCDF_FCOPY
PURPOSE:
Copy (subset of) variables from a source netCDF file to a new net CDF file
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
ncdf_fcopy,fin,fout,varnames,selvar,selcond,dim=dim,exclude=exclude, $
indir=indir,outdir=outdir,inid=inid,outid=outid, $
nohistory=nohistory,help=help
INPUTS:
fin - string, netCDF source file name; DO NOT include path, use indir
fout - string, netCDF output file name; DO NOT include path, use outdir
varnames- string array, names of input netCDF variables to be copied
string, 'all' - copy all variables in the input file
selvar - string, variable or dimension name for which selcond is defined.
If variable name, the corresponding netCDF var must be 1-D array
If empty string '' or omitted (selcond must be omitted as well)
all vars in varnames are copied completely.
selcond - [start,stop] , defines variable range to be copied to the
output file if selname is not an empty string
[start,stop,step], when dim is set, defines indices range and
index step for the given dimension name.
lonarr(n), array of indices for the selection var/dim, n>3
KEYWORD PARAMETERS:
dim - when set, selvar (selname) is a dimension name
exclude - when set all vars in the source file are copied except the
ones listed in varnames
indir - input string, input file directory (default, current)
outdir - input string, output file directory (default, current)
inid - input, any defined value will cause input file to stay open
output, long, input file ID
ncplot - when set, assumes that the input file is NCAR/nimbus convention
type and adjust the output file to allow the use of ncplot
program (see notes)
nohistory- when set, does not create or update global history attribute
'Data_subset' (see SIDE EFFECTS)
outid - input, any defined value will cause output file to stay open
output, long, output file ID
help - display this text
SIDE EFFECTS:
If NOHISTORY is not set the routine adds a global attribute
'Data_subset' acknowledging that the output file is a (subset)
copy of the input file and when it was done. If 'Data_subset'
exists the new information is appended to the existing one.
NOTES: 1) ATTN: variables of up to 4 dimensions are allowed to copy
2) variables are copied with their attributes not modified
3) selvar variable format must be compatible with subset conditions
[start,stop], e.g., hhmmss. ATTN: selcond based on time var
in hhmmss cannot be used if [start,stop] cross midnight
4) when no variable subsets are needed, selvar and selcond can be
omitted
5) all input file global attributes are copied to the output file
6) Input and output files cannot have identical names (overwriting
input file is not allowed).
7) Wnen ncplot keyword is used the program searches for TimeInterval
global atttribute and modifies it to reflect any change in the
time period being copied (e.g., extracting sub time interval).
EXAMPLES:
1) Input file is in indata directory, output file is saved in the
current directory; selection variable is TIME given in hhmmss
and the selection condition is to copy variables TIME, ztrue and
hroll between times 121959 and 122005. Use ncplot keyword to make
the output file compatible with NCAR ncplot package.
ncdf_fcopy,indir='indata','indata.nc','outdata.nc',['ztrue', $
'hroll'],'TIME',[121959,122005], /ncplot
Note that this example will not work if start stop times cross
midnight. A work around is to load TIME, find the indices for
the desired interval that crosses midnight and use ncdf_fcopy
as shown in the next example.
2) Same as above but selection dimension is used (time)
and the conditions are indices 10 to 20
ncdf_fcopy,indir='indata','indata.nc','outdata.nc', $
['TIME','ztrue','hroll'],'time',[10,20],/dim,/ncplot
Note that TIME variable was added to the list of selected vars in
order to have it in the copied file
3) Same as above but explicit selection of indices are given and no
ncplot compatibility is requested
ncdf_fcopy,indir='indata','indata.nc','outdata.nc',['ztrue', $
'hroll'],'TIME',[0,5,10,15,20,100,105,110,115,120]
4) Assume that in the input file there is a variable hroll with
dimensions [time,time30], time is seconds and time30 is 30 Hz
sampling within each second. Assume that there are 132 sec
of data and we want 5-second samplings of hroll.
This can be accomplished the following way:
ncdf_fcopy,indir='indata','indata.nc','outdata1.nc', $
['hroll'],'time',[0,131,5],/dim
ncdf_fcopy,'outdata1.nc','outdata2.nc','roll','time30',[0,0],/dim
The first call extracts every 5th sample for dimension time and
the second call takes only the 0th index for time30 dimension.
The intermediate file outdata1.nc can be deleted if not needed.
(See /tools/idl/idltools/ncdf_fcopy.pro)
NAME:
NCDF_RENAME
PURPOSE:
Rename existing dimension(s), variable(s) or attribute(s)
in a netCDF file
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
ncdf_rename,Cdfid,name,newname,rtype [,filename],gatt=gatt, $
close=close,silent=silent,help=help
INPUTS:
Cdfid: netCDF file ID, returned from a previous call to
ncdf_open, ncdf_create. The netcdf file must be in WRITE
and data mode. Also see Notes.
Name: string/long or strarr/lonarr, existing var, dim or attribute
name(s)
Newname: string/strarr, corresponding to Name new variable, dimension
or attribute name(s)
Rtype: string/strarr, identifies netcdf entity to be renamed (see Notes)
Allowed strings/strarr are:
'dim' - Name is dimension(s)
'var' - Name is variable(s)
'global' - Name is global attribute(s)
'allvars'- Name is attribute(s) to be renamed in all
relevant netcdf variables
att_var - String/strarr with name(s) of the netcdf variable(s)
whose Name attribute(s) is/are to be renamed
Filename: string, optional netCDF file name; if given will open netCDF
file in WRITE and data modes. In this case Cdfid is an output
parameter
KEYWORD PARAMETERS:
GATT: input, strarr(2); optional new global attribute to be added
gatt[0] - attribute name, gatt[1] - attribute value;
(recommended for adding global history attribute)
CLOSE: when set netcdf file will be closed. Default is to keep the
file open in WRITE mode. CAUTION: If a writable netcdf file
is not closed before exiting IDL, the disk copy of the file
may not reflect recent data changes or new definitions.
SILENT: suppress information messages
HELP: shows this text
OUTPUTS:
Cdfid: netCDF file ID, returned if Filename is given
SIDE EFFECTS:
The routine displays the old and new names when SILENT is set.
When renaming attributes in all relevant variables (vars that
have attribute(s) Name and do not have attribute(s) Newname)
the routine always prints out a message with the number of variables
for which attribute(s) were renamed.
NOTES:
* When renaming netcdf file dimension, variable or attribute keep in mind
that if the new name is longer than the existing one the netcdf may be
rewritten (which may take longer time) to accommodate the longer header.
* Be aware that when a netcdf file is closed the Cdfid becomes invalid
but is not deleted. Thus any attempt to read a new file with a new
filename but same Cdfid will result in error. The reason for this
behavior is that with a new file name and existing (defined) Cdfid
the program tries first to close the netcdf file corresponding to
the existing Cdfid. This is to prevent leaving unintentionally a
large number of open netcdf files.
(See /tools/idl/idltools/ncdf_rename.pro)
NAME:
NCDF_UPDATE
PURPOSE:
Update existing variable(s) or attribute(s) in a netCDF file
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
ncdf_update,Cdfid,name,value,rtype [,filename],gatt=gatt, $
close=close,silent=silent,help=help
INPUTS:
Cdfid: netCDF file ID, returned from a previous call to
ncdf_open, ncdf_create. The netcdf file must be in WRITE
and data mode. Also see Notes.
Name: string/long or strarr/lonarr, existing variable name or
attribute name(s)
Value: scalar or array with the replacement value(s) of any allowed
netcdf type;
Rtype: string/strarr, identifies netcdf entity to be updated (see Notes)
Allowed strings/strarr are:
'var' - Name is a variable
'global' - Name is global attribute(s) (see Notes)
'allvars'- Name is attribute(s) to be updated in all relevant
netcdf variables (see Notes)
att_var - String/strarr with name(s) of the netcdf variable(s)
whose Name attribute(s) is/are to be updated
Filename: string, optional netCDF file name; if given will open netCDF
file in WRITE and data modes. In this case Cdfid is an output
parameter
KEYWORD PARAMETERS:
GATT: input, strarr(2); optional new global attribute to be added
gatt[0] - attribute name, gatt[1] - attribute value;
(recommended for adding global history attribute)
CLOSE: when set netcdf file will be closed. Default is to keep the
file open in WRITE mode. CAUTION: If a writable netcdf file
is not closed before exiting IDL, the disk copy of the file
may not reflect recent data changes or new definitions.
SILENT: suppress information messages
HELP: shows this text
OUTPUTS:
Cdfid: netCDF file ID, returned if Filename is given
SIDE EFFECTS:
The routine displays the names of the updated variable or attribute(s)
When updating attributes in all relevant variables (vars that
have attribute(s) Name) the routine always prints out a message with the
number of variables for which attribute values were updated.
NOTES:
* Only one variable per routine call can be updated, while one or more
attributes can be replaced for each routine call.
* When updating multiple attributes the following restrictions apply:
- all attributes must have scalar values
- all attributes must be the same data type
These restrictions are result of the 1-D simple array allowed for
Value
* Be aware that when a netcdf file is closed the Cdfid becomes invalid
but is not deleted. Thus any attempt to read a new file with a new
filename but same Cdfid will result in error. The reason for this
behavior is that with a new file name and existing (defined) Cdfid
the program tries first to close the netcdf file corresponding to
the existing Cdfid. This is to prevent leaving unintentionally a
large number of open netcdf files.
(See /tools/idl/idltools/ncdf_update.pro)
NAME:
NCDF_VARDEF1
PURPOSE:
Add a new variable to an open netCDF file in define mode.
If successful, the variable ID is returned
Same as the standard ncdf_vardef function except that variable type
keywords in ncdf_vardef are replaced with a keyword vartype that
accepts the variable type as a string.
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
result=ncdf_vardef1(Cdfid,Name [,Dim],vartype=vartype,help=help)
INPUTS:
Cdfid: netCDF file ID, returned from a previous call to
ncdf_open, ncdf_create, ncdf_varload or ncdf_fcopy
Name: scalar string containing the variable name
Dim: optional vector containing the dimension IDs corresponding to
the variable dimensions. If the ID of the unlimited
dimension is included, it must be the rightmost element in the
array. If Dim is omitted, the variable is assumed to be a
scalar.
KEYWORD PARAMETERS:
VARTYPE: scalar string with the variable type: BYTE,CHAR,DOUBLE,FLOAT,
LONG, SHORT
HELP: shows this text
(See /tools/idl/idltools/ncdf_vardef1.pro)
NAME:
NCDF_VARINQ1
PURPOSE:
Return a structure that contains information about netCDF variable
given its name. It is a modification of ncdf_varinq.
The structure has the form:
{ ID:0L, DATATYPE:"", NDIMS:0L, NATTS:0L,
DIMSIZE:LONARR(NDIMS), DIMNAME:STRARR(NDIMS) }
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
result=ncdf_varinq1(Cdfid,varname [,filename],help=help)
INPUTS:
Cdfid: netCDF file ID, returned from a previous call to
ncdf_open, ncdf_create, ncdf_varload or ncdf_fcopy (see Notes)
Varname: string, netCDF variable name
Filename: string, optional netCDF file name; if given will open netCDF
file first. In this case Cdfid is an output var
KEYWORD PARAMETERS:
HELP: shows this text
OUTPUTS:
Cdfid: netCDF file ID, returned if Filename is given
SIDE EFFECTS:
The function returns -1 in the Id tag if the variable is not found.
NOTES:
Explanation of the structure tags:
Id: variable id
Datatype: string describing the data type of the variable.
('BYTE', 'CHAR','SHORT','LONG','FLOAT', or 'DOUBLE')
Ndims: number of dimensions
Natts: number of attributes assigned to this variable
Dimsize: vector of the dimension sizes of the variable
Dimname: string array of the dimension names
* Be aware that when a netcdf file is closed the Cdfid becomes invalid
but is not deleted. Thus any attempt to read a new file with a new
filename but same Cdfid will result in error. The reason for this
behavior is that with a new file name and existing (defined) Cdfid
the program tries first to close the netcdf file corresponding to
the existing Cdfid. This is to prevent leaving unintentionally a
large number of open netcdf files.
EXAMPLES:
(See /tools/idl/idltools/ncdf_varinq1.pro)
NAME:
NCDF_VARLOAD
PURPOSE:
Return a hyperslab of values from a netCDF variable. The netCDF file
must be in data mode to use this function
It is similar to ncdf_varget with some facilitations.
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
result=ncdf_varload(Cdfid,varname [,filename], $
varid=varid,count=count,offset=offset,stride=stride,help=help)
INPUTS:
Cdfid: netCDF file ID, returned from a previous call to
ncdf_open, ncdf_create, ncdf_varload or ncdf_fcopy (see Notes)
Varname: string, netCDF variable name
Filename: string, optional netCDF file name; if given will open netCDF
file first. In this case Cdfid is an output var
KEYWORD PARAMETERS:
VARID: optional scalar, returns variable ID
COUNT: optional vector containing the counts to be used in loading
values to result (default, [1,1,1,...])
OFFSET: optional vector containing starting position for the read
(default, [0,0,0,...]).
STRIDE: optional vector containing the strides, or sampling intervals,
between accessed values of the netCDF variable
(default, [1,1,1,...])
HELP: shows this text
OUTPUTS:
Cdfid: netCDF file ID, returned if Filename is given
SIDE EFFECTS:
The function returns -1 if the variable is not found.
NOTES:
* Be aware that when a netcdf file is closed the Cdfid becomes invalid
but is not deleted. Thus any attempt to read a new file with a new
filename but same Cdfid will result in error. The reason for this
behavior is that with a new file name and existing (defined) Cdfid
the program tries first to close the netcdf file corresponding to
the existing Cdfid. This is to prevent leaving unintentionally a
large number of open netcdf files.
EXAMPLES:
(See /tools/idl/idltools/ncdf_varload.pro)
NAME:
NCDF_VARNAMES
PURPOSE:
Return string array with all the variable names in a netCDF file
CATEGORY:
idltools/netcdf, netCDF utility
CALLING SEQUENCE:
result=ncdf_varnames(Cdfid [,filename],recdimname=recdimname, help=help)
INPUTS:
Cdfid: netCDF file ID, returned from a previous call to
ncdf_open, ncdf_create, ncdf_varload or ncdf_fcopy (see Notes)
Filename: string, optional netCDF file name; if given will open netCDF
file first. In this case Cdfid is an output var
KEYWORD PARAMETERS:
RECDIMNAME: string, returns the name of the unlimited dimension
(null string if does not exist)
HELP: shows this text
OUTPUTS:
Cdfid: netCDF file ID, returned if Filename is given
NOTES:
* Be aware that when a netcdf file is closed the Cdfid becomes invalid
but is not deleted. Thus any attempt to read a new file with a new
filename but same Cdfid will result in error. The reason for this
behavior is that with a new file name and existing (defined) Cdfid
the program tries first to close the netcdf file corresponding to
the existing Cdfid. This is to prevent leaving unintentionally a
large number of open netcdf files.
(See /tools/idl/idltools/ncdf_varnames.pro)
NAME:
NUM2STR
PURPOSE:
Converts a numerical var/array to a string (array)
with blanks stripped off
CATEGORY:
idltools/general
CALLING SEQUENCE:
res=num2str(num,nozero=nozero,fract=fract,len=len,char=char,help=help)
INPUT:
Num: number or numerical array
KEYWORD PARAMETERS:
NOZERO: set this keyword to remove leading/trailing zeros
FRACT: n : defines the digits after decimal point
(default is 4 for floating type and 0 for integer type)
LEN: -n : use n as desired length and adjust left
n : use n as desired length and adjust right
CHAR: filling character for adjusted strings, default is space;
LEN must be defined otherwise ignored(see example below)
HELP: Show this text
OUTPUTS:
res - num converted to string or string array
SIDE EFFECTS:
If the input is a string it is returned without modification.
This function does not work with complex numbers, structures and
pointers. If Num is not a real number or numerical array the function
prints a message and returns the value of num
Multidimensional numeric arrays are converted to one-dimensional string
array
EXAMPLE:
1) Creating an adjusted numerical table is one useful application
of this function in combination with string function stradj.pro
stra=strarr(10,11)
stra(*,0)=['A','B','C','D','E','F','G','H','I','K']
stra(*,1:10)=num2str(findgen(10,10),/nozero,len=4)
print,stradj(stra,adj=3,len=7)
For more information on stradj run print,stradj(/help)
2) Create a time string from given hour,minite,second
hour=12 & minute=5 & second=9
time=[hour,minute,second] ; integer array
timestr=strarr2str(num2str(time,len=2,char='0'),':')
(See /tools/idl/idltools/num2str.pro)
NAME: PADSTRARR PURPOSE: Return padded with spaces string array that matches the longest string in the array CALLING SEQUENCE: res=padstrarr(str,/front) INPUTS: Str: string array KEYWORD PARAMETERS: FRONT: when set pad the necessary spaces at the beginning HELP: displays this help text OUTPUTS: Res: padded with spaces string array COMMON BLOCKS:
(See /tools/idl/idltools/padstrarr.pro)
NAME:
PAUSE
PURPOSE:
PAUSE pauses the program until any key is pressed
CATEGORY:
idltools/general
CALLING SEQUENCE:
pause
INPUTS:
KEYWORD PARAMETERS:
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/pause.pro)
NAME:
PAUSECOM
PURPOSE:
This command from the idl prompt let you pause a program and execute
other command(s).
CALLING SEQUENCE:
@pausecom
(See /tools/idl/idltools/pausecom.pro)
NAME:
PDFMOM
PURPOSE:
This function computes the first 5 moments (power, mean, variance or
stdev, skewness and kurtosis of a given 1-D PDF as a function of
up to 2 parameters (input array can be one-, two-, or three-dim array)
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = pdfmom(f,x)
INPUTS:
F: An n-element vector or 2-D, or 3_D array with the given
distribution(s); n must be greater than 3.
X: Optional x-axis of the F (pdf); must be monotonic and equally
spaced. It could also be given as a 2- or 3-element array:
[first,last] or [first,deltaX,0.].
If missed (default) X is defined between [-n/2,n/2) and deltaX=1.
KEYWORD PARAMETERS:
DIM: input, array dimension over which to calculate moments,
1,2,3 are allowed values; if Dim is not defined, F must be a
vector
WHAT: input, use this keyword to specify the moments included in the
result. Use 0 to 4. It could be scalar or array.
Default are all moments.
RMS : input, use this keyword to calculate the square root of 2nd
moment.
HELP: Shows this text
PROCEDURE:
M0 = SUM(f(i))*deltaX
M1 = SUM(x(i)*f(i))*deltaX/M0
M2 = SUM((x(i)-M1)^2*f(i))*deltaX/M0
M3 = SUM((x(i)-M1)^3*f(i))*deltaX/M0/sqrt(M2)^3
M4 = SUM((x(i)-M1)^4*f(i))*deltaX/M0/M2^2-3.
EXAMPLE:
result = moment(f,x,what=[0,1,2],/rms)
print,pdfmom(/help) - print help info
print,pdfmom() - print calling sequence
(See /tools/idl/idltools/pdfmom.pro)
NAME:
PDFMOM1
PURPOSE:
This function computes the first 5 moments (zero-moment, mean,
variance, skewness and kurtosis of a given 1-D probability distribution.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = pdfmom1(f,x)
INPUTS:
F: An n-element vector with the given distribution;
n must be greater than 3.
X: Optional x-axis of the F (pdf); must be monotonic and equally
spaced. It could also be given as a 2- or 3-element array:
[first,last] or [first,deltaX,0.].
If missed (default) X is defined between [-n/2,n/2) and deltaX=1.
KEYWORD PARAMETERS:
WHAT: Use this keyword to specify the moments included in the
result. Use 0 to 4. It could be scalar or array.
Default are all moments.
RMS : Use this keyword to calculate the square root of 2nd moment.
HELP: Shows this text
PROCEDURE:
M0 = SUM(f(i))*deltaX
M1 = SUM(x(i)*f(i))*deltaX/M0
M2 = SUM((x(i)-M1)^2*f(i))*deltaX/M0
M3 = SUM((x(i)-M1)^3*f(i))*deltaX/M0/sqrt(M2)^3
M4 = SUM((x(i)-M1)^4*f(i))*deltaX/M0/M2^2-3.
EXAMPLE:
result = moment(f,x,what=[0,1,2],/rms)
print,pdfmom(/help) - print help info
print,pdfmom() - print calling sequence
(See /tools/idl/idltools/pdfmom1.pro)
NAME:
PICKFILES
PURPOSE:
This function allows the user to interactively pick one or more
file(s). A file selection tool with a graphical user interface
is created. Files can be selected and deselected from the
current directory or other directories.
CATEGORY:
Widgets.
CALLING SEQUENCE:
Result = PICKFILES()
KEYWORD PARAMETERS:
FILE: (input) A string or string array for setting the initial
value of the selection. Useful if there is a default file
GROUP: (input) The widget ID of the widget that calls PICKFILES.
When this ID is specified, a death of the caller results
in the death of the PICKFILES widget application.
READ: (Flag) Set this keyword to make the title of the PICKFILE
window "Select File(s) to Read".
WRITE: (Flag) Set this keyword to make the title of the PICKFILE
window "Select File(s) to Write".
PATH: (input) The initial path to select files from. If this
keyword is not set, the current directory is used.
FILTER: (input) A string value for filtering the files in the
file list. This keyword is used to reduce the number of
files to choose from. The user can modify the filter
unless the FIX_FILTER keyword is set. Example filter
values might be "*.pro" or "*.dat".
FIX_FILTER: (Flag) When this keyword is set, only files that
satisfy the filter can be selected. The user has no
ability to modify the filter and the filter is not shown.
TITLE: (input) A scalar string to be used for the window title.
If it is not specified, the default title is "Select File"
MUST_EXIST: (Flag) When set, only files that actually exist can
be selected.
POSITION: (input) 2-el vector with position of upper left
corner of the widget base, counted from top left
screen corner. May be ignored depending on your window
manager.
HELP: show this text
OUTPUTS:
PICKFILES returns a string or string array that contains the name
of the file(s) selected. If no file is selected, PICKFILE
returns a null string.
COMMON BLOCKS:
NEWPICKERS: COMMON block that maintains state for the widget.
SIDE EFFECTS:
This function initiates the XMANAGER if it is not already running.
RESTRICTIONS:
This routine is known to work on Suns (OPEN LOOK), MIPS, RS/6000,
DEC Ultrix, HP/700, VAX/VMS, SGI and Linux machines.
Only one instance of the PICKFILE widget can be running at one time.
PICKFILES does not recognize symbolic links to other files in UNIX.
PROCEDURE:
Create and register the widget and then exit, returning the
filename(s) that were picked.
EXAMPLE:
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 = PICKFILES(/READ, FILTER = '*.pro *.dat')
(See /tools/idl/idltools/pickfiles.pro)
NAME:
PRINTIDLPS
PURPOSE:
Prints idl.ps file (UNIX)
CATEGORY:
idltools/printers, print utilities
CALLING SEQUENCE:
printidlps, filename, PRINTER=printer, REMOVE=remove, HELP=help
INPUTS:
Filename: input string, renames idl.ps file with the given name
KEYWORD PARAMETERS:
PRINTER: when defined gives the printer name (default,'lj5local')
REMOVE: keyword for removing the standard idl.ps file. It is ignored
when filename exists
HELP: shows this text
OUTPUTS:
SIDE EFFECTS:
Prints a postscript file on a postscript printer
EXAMPLES:
(See /tools/idl/idltools/printidlps.pro)
NAME:
PRINTPS
PURPOSE:
Prints PS file(s) (UNIX)
CATEGORY:
idltools/printers, print utilities
CALLING SEQUENCE:
printps, fname, PRINTER=printer, HELP=help
INPUTS:
Fname: input string, postscript file name for the file to be printed
KEYWORD PARAMETERS:
PRINTER: when defined gives the printer name (default,'lj5local')
HELP: shows this text
OUTPUTS:
SIDE EFFECTS:
Prints a postscript file on a postscript printer
EXAMPLES:
(See /tools/idl/idltools/printps.pro)
NAME:
PUTFILE
PURPOSE:
Write a text file from a string array.
CATEGORY:
CALLING SEQUENCE:
putfile, f, s
INPUTS:
f = text file name. in
s = string array. in
KEYWORD PARAMETERS:
Keywords:
ERROR=err error flag: 0=ok, 1=invalid string array.
OUTPUTS:
COMMON BLOCKS:
NOTES:
MODIFICATION HISTORY:
R. Sterner, 20 Mar, 1990
R. Sterner, 4 Nov, 1992 --- allowed scalar strings.
Copyright (C) 1990, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See /tools/idl/idltools/putfile.pro)
NAME:
RAWIMAGE
PURPOSE:
Plots 2-D array displayed with its bigger size mapped on x axis
CATEGORY:
idltools/image
CALLING SEQUENCE:
rawimage, d2, db=db, win=w, help=help
INPUTS:
D2: 2-D image array
KEYWORD PARAMETERS:
DB: If set d2 is converted into dB
COLORTB: color table number (default, WYO1: 41)
WIN: Window number(default is 0) with fixed dimensions (600 x 200) pxls
HELP: Shows this text
SIDE EFFECT:
The shorter size of the d2 image must be less than 140 pixels
If the x size of d2 is more than 600 pxls program rolls the image
To temporary stop the rolling press SPACE BAR.
Any key will continue the roll.
Use AXIMAGE.PRO for more general applications
EXAMPLE:
(See /tools/idl/idltools/rawimage.pro)
NAME:
READSE
PURPOSE:
Reads unformatted binary data from a file into IDL variables.
READSE transfers data by first transforming the byte order of the
data in the file, if necessary, to the byte order defined by the
computer architecture used to run the idl session and the byte order
of the data in the file (keyword BIG_ENDIAN).
This procedure is similar to READU.
CATEGORY:
Input/Output.
CALLING SEQUENCE:
READSE, Unit, Var1,Var2,Var3,Var4,Var5
INPUTS:
Unit: idl file unit from which input is taken.
Var1,...,Var5: named variables to receive the data. For non-string
variables, the number of bytes required for Var are
read. When READSE is used with a variable of type string,
IDL reads exactly the number of bytes contained in the
existing string. No swaping is done on strings.
KEYWORD PARAMETERS:
TRANSFER_COUNT: output, returns the number of elements (not bytes)
transfered by the input operation (for UNIX only)
BIG_ENDIAN: when set, assumes that the file data are in big
endian order. The default is LITTLE_ENDIAN.
SWAPBYTES: output, returns 1 if bytes were swapped and 256 if bytes
were NOT swapped
HELP: show this text
SIDE EFFECTS:
The procedure accept maximum of 5 variables to be read with one call
NOTES:
EXAMPLES:
(See /tools/idl/idltools/readse.pro)
NAME:
REBIN1
PURPOSE:
The REBIN1 function resizes a vector/array to dimensions given in DIMS
This function is identical to RSI function REBIN but accepts an input
array for the dimensions instead of a list of the dimensions.
(Starting with idl5.5 this routine is obsolete; the standard idl rebin
routine can be used just like rebin1)
CATEGORY:
idltools/general array routine
CALLING SEQUENCE:
result=rebin1(Array,Dims, [/SAMPLE, /HELP])
INPUTS:
Dims: Array with the dimensions of the resulting resampled array
(Dims = [D1,D2,...,DN]). The dimensions must be integer
multiples or factors of the corresponding original dimension
Max num. of dimensions (dims size) is 8
KEYWORD PARAMETERS:
SAMPLE: Normally, REBIN uses bilinear interpolation when magnifying
and neighborhood averaging when minifying. Set the keyword to
use nearest neighbor sampling for both magnification and
minification. Bilinear interpolation gives higher quality
results but requires more time.
HELP: Shows this text
(See /tools/idl/idltools/rebin1.pro)
NAME:
REPLICARR
PURPOSE:
This function replicates N-dim. array to (N+1)-dim. array
(e.g, vector to matrix). Scalars can be strings or any numerical type.
Vectors can be any numerical type. Matrices and higer dim. arrays must
be non-complex numerical.
CATEGORY:
General.
CALLING SEQUENCE:
result=replicarr(x,dn)
INPUTS:
X: scalar or array to be replicated
DN: size of the new (added) dimension
OUTPUTS:
The result has one more DN-size dimension than X.
Every element along DN is a copy of X.
KEYWORD PARAMETERS:
DIM: Position of the new dimension; 1, 2, ..., LastXdim+1
1 - replication in row stack
LastXdim+1 - replication in column stack (default)
HELP: Shows this text
SIDE EFFECT:
Scalar is copied DN times to a vector (uses replicate function)
Matrix is copied DN times to a 3-D array in a manner determined by DIM
N_dimensional arrays are coppied DN times to N+1_dim array along DIM
This function does not work for string arrays or complex arrays
with more than 1 dimension
EXAMPLE:
x=findgen(3,3)
y=replicarr(x,2)
z=replicarr(x,2,dim=1)
(See /tools/idl/idltools/replicarr.pro)
NAME:
RESAMPLE
PURPOSE:
Returns a resized 1-D or 2-D input numerical(complex is not allowed)
array. The input array or the resulting array could be non-evenly
gridded. Only the last dimension (for 2-D) can be irregularly gridded.
This function can also be used to examine the irregularities in the
sampling by returning the number of samples per given interval for
a given irregular grid (requires the use of TEST keyword)
CATEGORY:
idltools/general
CALLING SEQUENCE:
For IRREGULARLY gridded data:
1-D data
result=resample(inarr,ingrid,outgrid,method=method,analyze=analyze, $
silent=silent,help=help)
2-D data
result=resample(inarr,ingrid,outgrid,outdim,method=method, $
analyze=analyze,silent=silent,help=help)
For REGULARLY gridded data (1-D or 2-D):
result=resample(inarr,outdim,method=method,silent=silent,help=help)
or for 1-D data only
result=resample(inarr,ingrid,outgrid,method=method,analyze=analyze, $
silent=silent,help=help)
For testing the irregularities in ingrid (or outgrid)
result=resample(grid,interval,/test)
INPUTS:
Inarr: numerical array to be resampled (1-D or 2_D)
Ingrid: numerical array containing grid points for last dim of inarr
(must be monotonically ascending)
Outgrid: numerical array containing desired grid points of the result
array last dimension (must be monotonically ascending)
Outdim: long or lonarr(2) with the desired dimension size of the output
array (can be skipped for 1-D data if ingrid and outgrid are
defined). If the inarr is 2-D and outdim is a scalar, outdim
is the desired size of the 1st dim of the result and 2nd
dimension is determined from outgrid.
For non-regularly gridded inarr or result, both ingrid and outgrid
input arrays are required.
When using TEST keyword the inputs are:
Grid: numerical array which contains uneven grid points
Interval: the sampling interval for which grid is tested. It has to
be positive and is considered the step and the first value
of a regular positive grid
KEYWORD PARAMETERS:
ANALYZE: named variable returns a structure
analyze.gint - interval widths for irregularly gridded data;
for evenly spaced data always 1
analyze.nind - For irregular grid:
METHOD=0 - array, number of averaged input
points for every output interval;
METHOD=2/3 - upsampling grid dimension using
the minimal irregular interval
0 if interpolating or regular ingrid
For regular data:
input/output dim ratio
analyze.filt - 0 - no filtering (interpolation only)
1 - input filtered (2-D: one of dims. filtered)
2 - both dims are filtered (2-D only)
3 - filtering performed on low number of points
4 - 1st dim filtered, 2nd filtered w/ low points
5 - input data averaged (2nd dim for 2-D)
6 - 1st dim filtered, 2nd dim. averaged (2-D)
METHOD: input, integer, resampling method (ignored for upsampling in
which case a simple linear or bilinear interpolation is done)
For 1-D input data (1-D METHOD):
0 - default method
Regularly gridded input data: Lowpass filter (FIR) the
data before decimation (see Notes)
Irregularly gridded input data: Average all available
input data points for every output grid interval (Notes)
1 - does not condition (lowpass filter) the input array
and use linear or bilinear interpolation to resample
2 - for downsampling of irregularly gridded input data only.
This is an alternative method to METHOD=0 for irregular
input data. Upsample the input data, regularize by
interpolation and then perform decimation with filtering
(see Notes).
For 2-D input data:
1st dim 1-D METHOD 2nd dim 1-D METHOD
0 - 0 (default) 0 (default)
1 - 1 1
2 - 0 2
3 - 1 2
4 - 0 1
5 - 1 0
SILENT: when set suppress display of function messages
TEST: when set the function returns an array with the number of
samples per Interval for all the points given in Grid. All
other keywords (except HELP) are ignored.
HELP: shows this text
OUTPUTS:
SIDE EFFECTS:
The function returns an empty string if the usage is incorrect,
-1 if inarr is not of numerical type, excluding complex type
-2 if inarr is a scalar, not defined or has more than 2 dimensions,
-3 if outdim # of elements doesn't match the # of dimensions of Inarr,
-4 if ingrid # of elements doesn't match Inarr number of elements,
-5 if outgrid is not a subset of ingrid (no extrapolation is allowed),
-6 if not enough points are available for reliable filtering (currently
30-point FIR filter is used),
-7 if invalid value for METHOD is used,
-8 if ingrid and outgrid are evenly spaced within 0.01% of their mean
intervals (this has been disabled and regular grids are allowed now;
in this case the data is treated as regularly spaced),
-9 if ingrid and/or outgrid are not in ascending order
-10 if ingrid and outgrid are both irregular
NOTES:
* For regularly gridded data
Ingrid and outgrid inputs must be omitted.
When downsampling the input array is first filtered (see next note)
to prevent aliasing and then decimated to the desired sampling rate.
If METHOD=1 the input array is not filtered and the data is
only resampled using linear or bilinear interpolation.
For downsampling a 30-point FIR lowpass filter is used by default
(METHOD=0). This leads to a requirement for minimum input data points
which is set to 60 points. This also means that edge effects are
possible and the end points might be unreliable. One solution is to
use data arrays bigger than the desired segment for resampling and
then use the needed part (subarray). This routines makes an attempt
to minimize the 'end' effects by padding mirror data segments to the
beginning and end of the input data. Another possible problem when
downsampling with filtering is the existance of singularities (big
step jumps, which could be valid) in the data. That may cause filter
transient artifacts to appear in the resampled data. Choosing between
filtering (METHOD=0) and interpolation only (METHOD=1) is a tradeoff
between possible filter artifacts and possible frequency aliasing
artifacts. Some analysis of the original signal/image and tests with
this routine can help choosing the better approach.
* For irregularly gridded data
Ingrid and outgrid must be defined. One of the arrays could be
evenly spaced and the other non-evenly spaced. The ingrid matches
the gridding of the input array, inarr, last dimension. The gridding
of outgrid determines how the resampled array(result) last dimension
is gridded.
Downsampling and METHOD=0.
Input data is regularly gridded (output is irregularly gridded)
Input data is first filtered and then resampled at the outgrid
points using linear interpolation. The cutoff frequency of the
filter is based on the median spacing of the outgrid.
Input data is irregularly gridded (ingrid).
Input data points centered around every outgrid point are averaged.
If there are no points available for a particular grid interval
NaN is recorded. Please note that the number of data points
averaged for every outgrid interval can vary and thus the
statistics from data point to data point may not be stationary.
In addition if the samples around the output grid point (center
point) are very non-lineary distributed or in the extreme case only
one data point is available the resulted average value may not
represent accurately the outgrid point (i.e, no grid weighting is
applied). And finally frequency aliasing is possible. No tests of
the severity of these problems have been performed and it is
recommended that the input data contain no big sampling
irregularities.
Downsampling and METHOD=1. Only resampling by interpolation is done
and there are no NaNs in the output. Since no integration
(filtering) is performed frequency aliasing is possible.
Downsampling and METHOD=2. This works for irregularly gridded input
data only (if ingrid is evenly spaced, METHOD is ignored and the
default method is used). It assumes slightly unevenly spaced input
data. The input data is first upsampled and regularized and then
lowpass filtered and resampled according to outgrid. No NaNs are
used and big data gaps are filled with interpolated values.
The outgrid must always be a subset of ingrid (no extrapolation is
allowed) and it is recommended that the subset start and end points
are no less than one (average) grid interval inside the input grid.
* For upsampling (or downsampling and METHOD=1) a simple linear or
bilinear interpolation is done.
* For downsampling, initial filtering of the input data (METHOD=0,2-5)
is NOT performed if the downsampling rate is within 10% of the input
sampling rate. For example, if the input sampling frequency is 105Hz
and the output sampling frequency is 100Hz, the output is directly
resampled from the input and the possible aliasing is ignored.
IN THE FUTURE I MAY ADD A KEYWORD 'STRICT' TO ENFORCE FILTERING. At
this point I have no results to analyze for better judgement and
am trying to avoid filter 'end' effects for close resampling.
* Resampling irregularly gridded data is not a straightforward process
and thus it is not always obvious which METHOD to use or for that
matter if any method would return good results. The user has to
analyze the desired resampling of the data to determine the best
approach or perform some tests. At this point only linear
interpolation is utilized in the resampling.
* Resampling of 2-D data is performed dimension wise according to
METHOD. The quality of the 2-D resampling (decimation in particular)
of this routine is not well researched. The use of a 2-D separable
FIR filter, which allows dimension wise filtering may not be the
optimal. Caution in the use of 2-D decimation is advised. Generally
when an image (2-D field) is downsized and an anti-aliasing lowpass
filter is applied, artifacts from the filtering may appear in the
image. Also if the aspect ratio of the input is not preserved the
output image will look distorted in comparison with the original
(input) image. The results are reasonable when the 2-D resampling
is applied to images with somewhat continuous spectra.
* Missing data points in the input array. Caution should be
exercised when missing points exist in the data. If they are
represented by some finite value they will affect the resulted
resampled data. If they are NaNs when averaging is done (for
decimation) they are treted as missing; any other filtering or
interpolation will cause the resampled value that was affected by
a NaN to become a NaN (RSI has not added a missing value feature
in many of the routines used here).
* ATTENTION: To resample(decimate) a simple linear field
always use interpolation (METHOD=1)
* This routine has not been fully tested. Report problems to
haimov@uwyo.edu
EXAMPLES:
------------------------------------------------------------------
Examples with 1-D data
------------------------------------------------------------------
Irregular input, regular decimated output
ingrid =[0.1,0.15,0.23, 0.31,0.45,0.55,0.6,0.7, $
0.77,0.89,1.,1.05,1.11,1.2, $
1.3,1.4,1.5,1.6,1.7, 1.8,1.9,2.0,2.1]
outgrid=[0.5, 1.0, 1.5, 2.0]
inarr=10.*ingrid
Test ingrid irregularities
print,resample(ingrid,0.5,/test)
Resample using different methods
outarr=resample(inarr,ingrid,outgrid,ana=test)
outarr=resample(inarr,ingrid,outgrid,ana=test,met=2)
outarr=resample(inarr,ingrid,outgrid,anal=test,met=1)
ingrid=[0.,1.1,2.3,3.1,4.0,5.0,5.8,6.9,7.8,9.1]
outgrid=findgen(10)
outarr=resample(ingrid,ingrid,outgrid,met=0,ana=test)
outarr=resample(ingrid,ingrid,outgrid,met=1,ana=test)
---------------------------------------------------
Example with regular input and irregular decimated output
as small subset of ingrid. RESAMPLE finds that it
has to filter (downsampling) by comparing the median
interval of outgrid with the ingrid interval.
ingrid=findgen(60)*0.1
outgrid=[2.1,2.23,2.45,2.6, 2.77,3.,3.11,3.3, 3.5,3.7,3.8,4.1]
inarr=10.*ingrid
outarr=resample(inarr,ingrid,outgrid,ana=test)
---------------------------------------------------
Example with regular input, irregular upsampled output
ingrid =[0.0, 0.5, 1.0, 1.5, 2.0, 2.5]
outgrid=[0.1,0.15,0.23, 0.31,0.45,0.55,0.6,0.7, $
0.77,0.89,1.,1.05,1.11,1.2, $
1.3,1.4,1.5,1.6,1.7, 1.8,1.9,2.0,2.1]
inarr=10.*ingrid
outarr=resample(inarr,ingrid,outgrid,ana=test)
2nd example with small output subset
ingrid =[0.0, 0.5, 1.0, 1.5, 2.0, 2.5]
outgrid=[0.1,0.15,0.23]
inarr=10.*ingrid
outarr=resample(inarr,ingrid,outgrid,ana=test)
------------------------------------------------------------------
Test with 2-D data
------------------------------------------------------------------
ingrid=[0.,1.1,2.3,3.1,4.0,5.0,5.8,6.9,7.8,8.9]
outgrid=findgen(10)
inarr=replicarr(findgen(10),100,dim=1)
filttoll causes just resampling for 1st dim, 2nd dim is interpolated
b=resample(inarr,outgrid,ingrid,[91,10],ana=test)
1st dim is filtered, 2nd dim is interpolated
c=resample(inarr,outgrid,ingrid,[90,10],ana=test)
----------------------------------------------------
Example using WCR radar cloud data from CLEX01 Oct 14
The data is irregularly sampled in time and regularly
sampled in range. No data gaps (missing mesaurements)
@commonwcrinclude
openwcrf,'Wpp01-10-14-12-51-44'
readwcrdata,58737,60736
decimate 1st and 2nd dim, also regularize 2nd dim.
; Use method=0
hh5=resample(hh[*,0:1899],time[0:1899]-time[0],findgen(925)*0.05+0.6, $
[100,925],ana=test)
; Use method=2
hh6=resample(hh[*,0:1899],time[0:1899]-time[0],findgen(925)*0.05+0.6, $
[100,925],met=2,ana=test)
aximage,10.*alog10(hh5),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH5 (dBm)'
aximage,10.*alog10(hh6),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH6 (dBm)'
aximage,10.*alog10(hh6/hh5),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH6/HH5 (dB)'
.......................................................
Another example using DYCOMS01 data from July 20. There are data gaps.
@commonwcrinclude
openwcrf,'Wpp01-07-20-09-35-20'
readwcrdata,0,1000
t1=time-time[0]
decimate 2nd dim (close resample)
t2=findgen(981)*0.05
; Use method=0 (averaging for 2nd dim)
hh0=resample(hh,t1,t2,[100,981],met=0,ana=test)
; Use method=1 (inetrpolation for 2nd dim)
hh1=resample(hh,t1,t2,[100,981],met=1,ana=test)
aximage,10.*alog10(hh0),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH0 (dB)',/ord
aximage,10.*alog10(hh1),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH1 (dB)',/ord
decimate 2nd dim (significant decimation)
t3=findgen(400)*0.12
; Use method=0 (averaging for 2nd dim)
hh2=resample(hh,t1,t3,[100,400],met=0,ana=test)
; Use method=1 (inetrpolation for 2nd dim)
hh3=resample(hh,t1,t3,[100,400],met=1,ana=test)
; Use method=2 (inetrpolation for 2nd dim)
hh4=resample(hh,t1,t3,[100,400],met=2,ana=test)
aximage,10.*alog10(hh2),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH2 (dB)',/ord
aximage,10.*alog10(hh3),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH3 (dB)',/ord
aximage,10.*alog10(hh4),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH4 (dB)',/ord
decimate 1st and 2nd dims
hh5=resample(hh,t1,t3,[50,400],met=0,ana=test)
hh6=resample(hh,t1,t3,[50,400],met=1,ana=test)
hh7=resample(hh,t1,t3,[50,400],met=2,ana=test)
aximage,10.*alog10(hh5),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH5 (dB)',/ord
aximage,10.*alog10(hh6),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH6 (dB)',/ord
aximage,10.*alog10(hh7),/tr,setw=[-1,41],/bar,tit=wcrfile+': HH7 (dB)',/ord
(See /tools/idl/idltools/resample.pro)
NAME:
RESETPS2X
PURPOSE:
Closes current graphics device and reset it to 'x' or 'win' device.
All plotting system variables are reset to their default values.
CATEGORY:
idltools/graphics
CALLING SEQUENCE:
resetps2x, noclean=noclean, help=help
INPUTS:
KEYWORD PARAMETERS:
NOCLEAN - when set plotting system variables are left with their last
values
HELP - show this text
OUTPUTS:
COMMON BLOCKS:
(See /tools/idl/idltools/resetps2x.pro)
NAME:
SEC2STR
PURPOSE:
Convert seconds after midnight to a time string.
CATEGORY:
CALLING SEQUENCE:
tstr: sec2str(sec, [d])
INPUTS:
sec: seconds after midnight (scalar or array) in
d: optional denominator for a fraction. in
KEYWORD PARAMETERS:
HOURS: forces largest time unit to be hours instead of days
OUTPUTS:
tstr: resulting text string. out
COMMON BLOCKS:
NOTES:
Output is of the form: [DDD/]hh:mm:ss[:nnn/ddd]
where DDD=days, hh=hours, mm=minutes, ss=seconds,
nnn/ddd=fraction of a sec given denominator ddd in call.
If sec is double precision then 1/10 second can be
resolved in more than 10,000 days. Use double precision when
possible. Time is truncated, so to round to nearest second,
when not using fractions, add .5 to sec.
(See /tools/idl/idltools/sec2str.pro)
NAME:
SEC2TIME
PURPOSE:
Returns time given in seconds as hhmmss.dd time after midnight
CATEGORY:
idltools/general
CALLING SEQUENCE:
res = sec2time(s)
INPUTS:
S: input, long/double, time hhmmss[.dd] given in seconds
or unix seconds
KEYWORD PARAMETERS:
UNIX: if set, S is unix seconds
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/sec2time.pro)
NAME:
SEC2TIMESTR
PURPOSE:
Returns time after midnight given in seconds as a string/array 'hh:mm:ss'
Fractional seconds in the input are truncated.
CATEGORY:
idltools/general
CALLING SEQUENCE:
res = sec2timestr(s)
INPUTS:
S: input, long/double, time hhmmss[.dd] given in seconds
KEYWORD PARAMETERS:
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/sec2timestr.pro)
NAME:
SETPS
PURPOSE:
Set postscript device
CATEGORY:
idltools/graphics
CALLING SEQUENCE:
setps, fname,orientation=ori,colortb=colortb,nocolor=nocolor, $
silent=silent,help=help
INPUTS:
fname - input string, postscript output file name
if not defined default is idl.ps
KEYWORD PARAMETERS:
colortb - input, byte, loads the corresponding color table. For PS device
loads 256-color color table (default is the current table
for X device and 256 shades B/W for PS device) or
bytarr(3), [colortb,revcolor,back_foreground]
colortb: color tabel number to be loaded
revcolor:
0 - leave the original color order
1 - reverse color table
2 - reverse color table not including first/last colors
3 - swap first and last colors in the color table
back_foreground:
0 - no action
1 - replace first/last colors with black/white
2 - replace first/last colors with white/black
nocolor - when set uses 4-bit no color device (default is 8-bit);
COLORTB is ignored.
orientation - 'landscape'
'portrait' (default)
silent - input, when set supresses information messahes
help - show this text
OUTPUTS:
SIDE EFFECTS:
Combined use of 'ps' device and colortb can produce undesirable
side effect of not showing the axes and the labels. This can happen
if the selected color table has white as first(0) color index. IDL,
by default, assigns 0 to !P.COLOR when set_plot,'ps' is used. To fix
the problem select anoder color for !P.COLOR after running setps.
(See /tools/idl/idltools/setps.pro)
NAME:
SETXPSWIN
PURPOSE:
Set 'X', 'WIN' or 'PS' device
CATEGORY:
idltools/graphics
CALLING SEQUENCE:
setxpswin, winn, ngraph, pagesplit=psplit,horizontal=hor,landscape=land,$
psfilename=psfn,xyoff=xyoff,xysize=xysize,xymargin=xymargin, $
colortb=colortb,nocolor=nocolor,encapsulate=pse,scale=scale, $
silent=silent,help=help
INPUTS:
winn - input, byte, IDL window number; enter 99 for PS device, any other
number greater than 31 will open new free window
ngraph - input, byte, number of graphics on a page (default, 1)
KEYWORD PARAMETERS:
colortb - input, byte, loads the corresponding color table. For PS device
loads 256-color color table (default is the current table
for X device and 256 shades B/W for PS device) or
bytarr(3), [colortb,revcolor,back_foreground]
colortb: color tabel number to be loaded
revcolor:
0 - leave the original color order
1 - reverse color table
2 - reverse color table not including first/last colors
3 - swap first and last colors in the color table
back_foreground:
0 - no action
1 - replace first/last colors with black/white
2 - replace first/last colors with white/black
encapsulate- input, when set encapsulate a PS file. PS device only.
horizontal - input, byte, when set, plots multiple graphics horizontally
default is vertically. If horizontal > 1 divides ngraph
to (horizontal graphs x ngraph/horizontal vertical graphs)
landscape - input, byte, when set, turns to landscape (default is portrait)
for PS device only
nocolor - input, when set uses 4-bit no color device (default is 8-bit,
color). PS device only. COLORTB keyword is ignored.
pagesplit - input, byte, plot multiple graphics in one (0) or two (1) columns
If horizontal is set to 1, divides into 2 rows
psfilename - input, string, when set saves PS file with the given name
default is idl.ps
scale - input, float, printed page scale factor (>0, <1, default, 1).
PS device only.
silent - input, when set supresses information messahes
xymargin - input, fltarr(4), when set defines the x/y margins
[x_left,x_right,y_bottom,y_top],(default [10.,3.,4.,2.]
xyoff - input, fltarr(2), when set determines xoffset and yoffset in
inches for PS device only; defaults depend on other inputs
PS device only:
portrait: [0.75,5.0] page origin in inches; ngraph=1
[0.9, 1.8] page origin in inches; ngraph>1
landscape:[2.0,10.0] page origin in inches; ngraph=1
[1.8,10.2] page origin in inches; ngraph>1
xysize - input, fltarr(2), when set determines the display/page plotting
area in pix/inches (defaults depend on the other inputs)
PS device:
portrait: [7.0,5.0] page frame in inches; ngraph=1
[7.2,8.7] page frame in inches; ngraph>1
landscape:[9.0,5.5] page frame in inches; ngraph=1
[9.7,6.2] page frame in inches; ngraph>1
X device: [640,512] window size in pixels; ngraph = 1
[640,900] window size in pixels; ngraph > 1
help - shows this text
OUTPUTS:
COMMON BLOCKS:
common dev_comm
NOTES: 1) xyoff and encapsulate are ignored for 'x' or 'win' device
2) colortb is ignored when nocolor is set
3) nocolor is ignored for 'x' or 'win' device
4) combined use of 'ps' device and colortb can produce undesirable
side effect of not showing the axes and the labels. This can happen
if the selected color table has white as first(0) color index. IDL,
by default, assigns 0 to !P.COLOR when set_plot,'ps' is used. To fix
the problem select anoder color for !P.COLOR after running setps.
(See /tools/idl/idltools/setxpswin.pro)
NAME:
SHOWPROF
PURPOSE:
Interactively draw row or column profiles of an image in a separate
window.
CATEGORY:
idltools/image
CALLING SEQUENCE:
SHOWPROF, Image [,SX=sx, SY=sy,XSIZE=xsize,YSIZE=ysize, $
WRANGE=wrange,ORDER=order,HELP=help]
INPUTS:
Image: The variable that represents the image displayed in current
window. This data need not be scaled into bytes.
The profile graphs are made from this array.
KEYWORD PARAMETERS:
SX: Starting X position of the image in the window. If this
keyword is omitted, 0 is assumed.
SY: Starting Y position of the image in the window. If this
keyword is omitted, 0 is assumed.
XSIZE: The x size of the PROFILE window (default 640).
YSIZE: The y size of the PROFILE window (default 512).
WRANGE: [Min, Max] range for the image
ORDER: Set this keyword param to 1 for images written top down or
0 for bottom up. Default is the current value of !ORDER.
HELP: Show this text
OUTPUTS:
No explicit outputs.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A new window is created and used for the profiles. When done,
the new window is deleted.
RESTRICTIONS:
None.
PROCEDURE:
A new window is created and the mouse location in the original
window is used to plot profiles in the new window. Pressing the
left mouse button toggles between row and column profiles.
The right mouse button exits.
EXAMPLE:
Create and display an image and use the SHOWPROF routine on it.
Create and display the image by entering:
A = BYTSCL(DIST(256))
TV, A
Run the SHOWPROF routine by entering:
SHOWPROF, A
The SHOWPROF window should appear. Move the cursor over the original
image to see the profile at the cursor position. Press the left mouse
button to toggle between row and column profiles. Press the right
mouse button (with the cursor over the original image) to exit the
routine.
(See /tools/idl/idltools/showprof.pro)
NAME:
SKEW
PURPOSE:
Returns the skewness of an array X.
CALLING SEQUENCE:
result=skew(x, dim, var=var, nan=nan, help=help)
INPUTS:
x - input array (any numerical type)
dim - the array dimension over which to calculate skew, starting from 1
If DIM=0 or not present skew for the whole array is calculated.
OUTPUTS:
The result is a scalar for DIM=0 or not present. For DIM > 0 the result
is an array with one less dimension than X. For double and complex
type arrays the result is of the same type; for all others it is
single-precision floating.
KEYWORD PARAMETERS:
nan - when set, NaNs in X are treated as missing values
help - prints this help
SIDE EFFECT:
This function does not work for multi-dimensional complex arrays
NOTES:
The result has better precision and the computation is faster for
1_D arrays or when DIM=0.
print,skew() prints out the usage
(See /tools/idl/idltools/skew.pro)
NAME:
SPECFFT
PURPOSE:
Estimates power spectrum (psd) and related characteristics for one, x, or two,
x and y, data sequences, which could be real or complex. Welch method is
implemented where n-point data sequence(s) is(are) divided into m (overlapping
or not) segments of nfft[1] size, each of which is detrended (mean or linear
trend) then windowed, padded with zeros (if needed) to the desired fft length,
nfft[0], FFT'd and accumulated. If m=(n-overlap)/(nfft[1]-overlap) is not an
integer the last not complete data segment is ignored.
CATEGORY:
idltools/signal
CALLING SEQUENCE:
specfft, P,nfft,x,y, alpha=alpha,detrendw=detrendw,freq=freq,overlap=overlap,$
Pc=Pc,psdmom=psdmom,raxis=raxis,windat=windat,help=help
INPUTS:
Nfft: long integer, or lonarr(2); fft length and data segment length
nfft[0]: FFT length (usually equal to the size of a data segment
unless nfft[1] is defined); proportional to power of 2
(e.g., 16,1024,...) is recommended
nfft[1]: optional data segment size (default is nfft[0]);
required conditions: nfft[0] ge nfft[1] and
nfft[1] le n_elements(x)
X: n-point vector, real or complex data
Y: n-point vector, data (optional; type and size have to match x)
KEYWORD PARAMETERS:
ALPHA: input, float (0. < confint < 1.), confidence interval percentile
(default, 0.95)
DETRENDW: input, removes the mean or the linear trend from every data segment
0 - removes data segment linear trend (default)
1 - removes data segment mean
FREQ: input/output, sampling_rate/psd_freq__axis
input: float, sampling rate, fs (it is used for psd scaling);
default (FREQ not defined) is 1; If FREQ is an array
it is assumed that fs=2*freq[n_elements(freq)-1]
output: frequency axis for the P(psd); psd freq. resolution is
the first positive non-zero value;
freq[n_elements(freq)-1] is the Nyquist frequency
OVERLAP: input,long integer, number of overlapping data points
per data segment (default, 0, maximum 0.75*nfft[1])
PC: output, fltarr(k), confidence interval for a single sequence (x) or
fltarr(k,7), confidence intervals for two sequences (x,y)
k = nfft[0] - for complex data
nfft[0]/2+1 - for real data and even nfft[0]
(nfft[0]+1)/2 - for real data and odd nfft[0]
Pc[*,0] - Pxxc, Pxx alpha*100% confidence interval
Pc[*,1] - Pyyc, Pyy alpha*100% confidence interval
Pc[*,2] - Pxyc, Pxy alpha*100% confidence interval
Pc[*,3] - Axyc, Axy alpha*100% confidence interval
Pc[*,4] - Txyc, Txy alpha*100% confidence interval
Pc[*,5] - Cxyc, Cxy alpha*100% confidence interval
Pc[*,6] - Pcoc, Co-Pxy alpha*100% confidence interval
Pc[*,7] - Pquc, Quad-Pxy alpha*100% confidence interval
Read Note 4.
PSDMOM: output, fltarr(5), returns first 5 moments of the psd (total power
w/o the mean, mean freq, psd width, skewness, kurtosis)
RAXIS: input: integer, time interpolation factor for covar. func.;
(for a single sequence, autocovar. func.)
Allowed values: 1,2,4; replaced with 1 for any other value
output: fltarr(k), auto- or cross-cov (P[*,1] or P[*,6]) lag axis
ATTN: see important note 3 (NOTES:)
WINDAT: input,wintype or [wintype,ntap], or [wintype,ntap,wflag] data
window parameters:
wintype: 0 - no data windowing (rectangular window, default)
1 - Hanning data window
2 - Hamming data window
3 - Blackman data window
ntap: number of points to be used to create wintype taper
(i.e., flat top window tapered as wintype for the first
ntap/2 and last ntap/2 points of the nfft[1] window);
usually ntap/nfft[1] is about 0.1 to 0.2;
if ntap=0 no tapering is performed; ntap < 16 is not
recommended
wflag: when set calculates periodical window;
default (or 0) is symmetrical window
HELP: show this help information
OUTPUTS:
P: fltarr(k) or fltarr(k,2) for a single sequence (x)
k = nfft[0] - for complex data
nfft[0]/2+1 - for real data and even nfft[0]
(nfft[0]+1)/2 - for real data and odd nfft[0]
P[*,0] - Pxx, x psd
P[*,1] - Rxx, x normalized autocovariance
(if x is real and Raxis is defined)
fltarr(k,7) or fltarr(k,6) for two sequences, x and y
k = nfft[0] - for complex data
nfft[0]/2+1 - for real data and even nfft[0]
(nfft[0]+1)/2 - for real data and odd nfft[0]
P[*,0] - Pxx, x psd
P[*,1] - Pyy, y psd
P[*,2] - Pxy, xy cross psd (magnitude)
P[*,3] - Axy, xy cross psd (phase in radians)
P[*,4] - Txy, xy transfer function (magnitude)
P[*,5] - Cxy, xy squared coherence function
P[*,6] - Rxy, xy normalized cross covariance function
(for real signals only)
Read Notes 2,3,5,6,8.
NOTES:
0) Running specfft without parameters will display the usage
1) External routines: detrend, hann, hamming, blackman, errorfinv, mean,
pdfmom
2) For complex signals, P and Pc are freq. shifted and 0 freq.(DC) is
f[nfft[0]/2] for even nfft[0] and f[(nfft[0]+1)/2] for odd nfft[0].
Nyquist freq is the last positive frequency.
3) Normalized covariance is calculated for real signals only. For
cross-cov., lags are between -nfft[0]/(4*raxis*fs) and
nfft[0]/(4*raxis*fs); raxis(as input paramer) is time compression
factor. For auto-cov.(single sequence x) lags are from 0 to
nfft[0]/(2*raxis*fs). The covariance is a circular biased estimate.
To resolve the circularity it is advisable to use nfft[0]>=2*nfft[1]
Time interpolation factor (2 and 4) may cause aliasing in the cov.
function. At this time this problem is not addressed.
4) Confidence intervals, Txy and Cxy are not calculated and Pc=0 when
the number of segments, m, is 1 (no partitioning of the data).
Minimum of m=10 is recommended for good confidence int. estimates.
5) The area under the spectrum equals the power in the data (DC is
excluded). Therefore for complex signals calculated spectra are
two-sided, while for real signals, one-sided.
6) For proper scaling of the spectra, sampling frequency, freq=fs is
required. This program calculates spectra as functions of freq.
not as functions of angular freq. (omega) or wave number (k).
7) Up to 50% overlapping is recommended when Hann, Hamming or Blackman
windows are used. Low or no overlapping should be used with tapers
to avoid correlation between sample spectra.
8) Co and Quadrature components of cross psd can be calculated from
Pxy and Axy. specfft calculates conf. interval for Co- and Q- psds.
9) specplot.pro can be used for plotting the results of specfft
EXAMPLE:
Example illustrating the use of specfft.pro and specplot.pro
Calulating spectra of 0.1 Hz cos and sin embedded in white noise
n=15000 & dt=0.05 & fs=1./dt & phi=2*!pi*0.1*findgen(n)*dt
n1=randomn(seed,n) & n2=randomn(seed,n)
u=cos(phi) & v=sin(phi)
x=u+0.1*n1 & y=v+1.1*n2
z=complex(x,-y)
nwin= 1500 & nfft= [2048,nwin] & df=1./(nfft[0]*dt)
wintype=1 & ntap=0 & wflag=0 & w=[wintype,ntap,wflag]
alpha=0.95 & f=(f1=fs) & rxya=(raxis=1)
txt='Test: x=cos(2*pi*0.1*t)+0.1*noise1 ; SNR=17 dB'+'!C'+$
' y=sin(2*pi*0.1*t)+1.1*noise2 ; SNR=-4 dB'+'!C'+$
' Hann Window, nwin=1500, nfft=2048, 0% ovrlp'+'!C'+$
' Alpha=0.95'
specfft,P,nfft,x,y,Pc=Pc,overlap=0,win=w,freq=f,alpha=alpha, $
/detrendw,raxis=rxya,psdmom=mom
specplot,P,Pc,plotm=15,freq=f,raxis=rxya,plotps=0,psdmom=mom, $
infotext=txt,chars=1.5,/nodate
Calculate and plot auto-spectrum of a complex sinusoid
specfft,P1,nfft,z,Pc=Pc1,overlap=0,win=w,freq=f1,raxis=raxis, $
alpha=alpha,/detrendw,psdmom=mom1
specplot,P1,Pc1,plotm=1,freq=f1,plotps=1,psdmom=mom1,zoom=[-1,1]
(See /tools/idl/idltools/specfft.pro)
NAME:
SPECFFT2
PURPOSE:
Estimates 2-D power spectra (psd) and related characteristics for one, x, or
two, x and y, 2-D data sequences, which could be real or complex.
2-D generalaized Welch method is implemented where (n,l) data sequence(s)
is(are) divided into m (overlapping or not) segments of (nwin,lwin) size,
each of which is detrended (mean or linear trend) then windowed, padded with
zeros (if needed) to a desired fft size, (nfft,lfft), FFT'd and accumulated.
CATEGORY:
idltools/signal
CALLING SEQUENCE:
specfft2, P,nfft,x,y,detrendw=detrendw,freq=freq,overlap=overlap, $
raxis=raxis,windat=windat,help=help
INPUTS:
Nfft: lonarr(2) or lonarr(2,2), fft length and data segment length
nfft[*,0]: [nfft,lfft], 2-D fft lengths(usually equal to the
size of a 2-D data segment unless nfft[*,1] are
defined); proportional to power of 2(e.g., 16,1024,
...) is recommended
nfft[*,1]: [nwin,lwin], optional data segment size (default
is nfft[*,0]); required conditions:
nfft ge nwin, lfft ge lwin
nwin le n, lwin le l
X: [n,l] array, real or complex data
Y: [n,l] array, (optional; type and size have to match x)
KEYWORD PARAMETERS:
DETRENDW: input, removes the mean or the linear trend from every
2-D data segment
0 - removes data segment best fit plane (default)
1 - removes data segment total mean value
FREQ: input/output, sampling rate/fn-,fl-frequency axes
input: [fsn,fsl], sampling rates in 2-D (needed for proper
psd scaling); default is [1.,1.]
output: fltarr(nfft+lfft),[fn,fl],frequencies for the psd,
where fn and fl are nfft/lfft size vectors; frequency
resolution, dfn/dfl, is the first non-zero positive
frequency in n/l dim
OVERLAP: input, lonarr(2), [no,lo], the number of overlapping data points
per segment, (default, [0,0]; maximum 0.75*[nwin,lwin]);
read note 5
RAXIS: input: intarr(2), [rx,ry], time interpolation factor for covar.
func.(for a single sequence, autocovar. func.); Allowed
values: 1,2,4; replaced with 1 for any other value
output: fltarr(nfft+lfft), auto- or cross-cov (P[*,*,1] or
P[*,*,6]) lag axes; ATTN: see important note 9 (NOTES:)
WINDAT: input,wintype or [wintype,ntap,ltap], or
[wintype,ntap,ltap,wflag] data window parameters:
wintype: 0 - no data windowing (rectangular window, default)
1 - Hanning data window
2 - Hamming data window
3 - Blackman data window
ntap: [ntap,ltap], number of points to be used to create
wintype 2-D taper(i.e., flat top window tapered as
wintype for the first ntap/2 and last ntap/2 points
of the nfft[*,1] 2-D window); usually ntap/nfft[*,1]
is about 0.1 to 0.2; if ntap=[0,0] no tapering is
performed; ntap < 16 is not recommended
HELP: show this help information
OUTPUTS:
P fltarr(nfft,lfft) or fltarr(nfft,lfft,2), for one sequence, x
P(*,*,0) - Pxx, x psd
P(*,*,1) - Rxx, x auto-covariance (if Raxis is defined)
(if x is real and Raxis is defined)
fltarr(nfft,lfft,6) or fltarr(nfft,lfft,7), for two sequences
P(*,*,0) - Pxx, x psd
P(*,*,1) - Pyy, y psd
P(*,*,2) - Pxy, xy cross psd (magnitude)
P(*,*,3) - Axy, xy cross psd (phase in radians)
P(*,*,4) - Txy, xy transfer function (magnitude)
P(*,*,5) - Cxy, xy squared coherence function
P(*,*,6) - Rxy, xy cross-covariance function
(for real signals only)
Read notes 2,3,4,8.
NOTES:
0) Running specfft2 without parameters will display the usage
1) External routines: detrend, hann2, hamming2, blackman2, mean
2) psds are shifted and 0 freq is f[nfft/2] for even nfft and
f[(nfft+1)/2] for odd nfft. Nyquist freq is the last positive
frequency. For real signal, spectra are symetrical w.r.t. the origin.
3) The area under the spectrum equals the power in the data (DC is
excluded).
4) For proper scaling of the spectra, sampling frequencies,
freq=[fsn,fsl], are required. This program calculates spectra as
functions of freq. not as functions of angular freq. (omega) or wave
number (k).
5) Up to 50% overlapping is recommended when Hann, Hamming or Blackman
windows are used. Low or no overlapping should be used with tapers
to avoid correlation between sample spectra.
8) Co and Quadrature components of cross psd can be calculated from
Pxy and Axy.
9) Normalized auto-,cross-covariance is calculated for real signals
only. Lags are from -nfft/(2*raxis*fs) to nfft/(2*raxis*fs)
It is a circular biased estimate. To resolve the circularity
it is advisable to use nfft>= 2*nwin, lfft>=2*lwin
Time interpolation factor (2 and 4) may cause aliasing in the cov.
function. At this time this problem is not addressed.
EXAMPLE:
x=findgen(512)*2.*!pi/20. & x=replicarr(x,1024)
y=findgen(1024)*2.*!pi/40. & y=replicarr(y,512,/dim)
z1=sin(x+y) & z2=sin(x-y)
f=[1.,1.] & rax=[1,2] & specfft2,P,[128,256],z1,win=0,freq=f,rax=rax
aximage,10.*alog10(P[*,*,0]),f[0:127],f[128:*],setw=[-1,13,0,1],/bar,imgz=2,$
title='Auto-spectrum(psd)',xtitle='Frequency [Hz]',ytitle='Frequency [Hz]'
aximage,P[*,*,1],rax[0:127],rax[128:*],setw=[-1,13,0,1],/bar,imgz=2, $
title='Auto-covariance',xtitle='Time [s]',ytitle='Time [s]'
f=[1.,1.] & rax=[4,1] & specfft2,P,[128,256],z2,win=0,freq=f,rax=rax
aximage,10.*alog10(P[*,*,0]),f[0:127],f[128:*],setw=[-1,13,0,1],/bar,imgz=2,$
title='Auto-spectrum(psd)',xtitle='Frequency [Hz]',ytitle='Frequency [Hz]'
aximage,P[*,*,1],rax[0:127],rax[128:*],setw=[-1,13,0,1],/bar,imgz=2, $
title='Auto-covariance',xtitle='Time [s]',ytitle='Time [s]'
f=[1.,1.] & rax=1. & specfft2,P,[128,256],z1,z2,win=0,freq=f,rax=rax
aximage,10.*alog10(P[*,*,2]),f[0:127],f[128:*],setw=[-1,13,0,1],/bar,imgz=2,$
title='Cross-spectrum(psd)',xtitle='Frequency [Hz]',ytitle='Frequency [Hz]'
aximage,P[*,*,6],rax[0:127],rax[128:*],setw=[-1,13,0,1],/bar,imgz=2, $
title='Cross-covariance',xtitle='Time [s]',ytitle='Time [s]'
(See /tools/idl/idltools/specfft2.pro)
NAME:
SPECPLOT
PURPOSE:
Plots the results from specfft routine
CALLING SEQUENCE:
specplot, P,Pc,axislabels=axl,charsize=charsize,freq=f,infotext=txt, $
lsmooth=lsm,nodate=nodate,plotg=pg,plotm=pm,plotps=ps,$
psdmom=mom,raxis=raxis,slope=slp,zoom=zm,help=help
INPUTS:
P: input, fltarr, this is an output from specfft
Pc : input, fltarr, this is an output from specfft
KEYWORD PARAMETERS:
AXISLABELS: input, strarr, x/y axis labels
axislabels[0] - frequency label (default, 'Frequency [Hz]')
axislabels[1] - Pxx label (default, 'Pxx PSD [[x]^2/Hz]')
axislabels[2] - Pyy label (default, 'Pyy PSD [[y]^2/Hz]')
axislabels[3] - Pxy label (default, 'Pxy Cros PSD')
axislabels[4] - Pco label (default, 'Pxy Co-Spectrum')
axislabels[5] - Pqu label (default, 'Pxy Quad-Spectrum')
axislabels[6] - Covariance Lag label (default, 'Time [s]')
When plot a single graphics axislabels[1] could be any label
When plot more than one graphics, axislabels elements must be
enetered in the described order. All other graphics are
labeled by default within the program.
CHARSIZE: input, float, define character size for the labels
FREQ: input, fltarr, the corresponding output from fftspec or
float, sampling rate (fs)
fltarr(2), [fs,nfft[0]]; nfft[0] used in specfft
INFOTEXT: input, string, when set will print the string at the
bottom of the page for a postscript file (ps=99)
LSMOOTH: input, intarr(2), when set [smoothtype,size]
smoothtype = 0 - no smoothing
1 - logarithmic averaging (x-log scale only)
2 - linear boxcar smoothing
size = # equally spaced blocks in log scale (smoothtype = 1)
# of boxcar smoothed frequencies (smoothtype = 2)
NODATE: when set supress date-time stamp (for PS device only)
PLOTG: input, string/arrstr, when set determine plotted graphics
allowed strings: 'pxx','pyy','pxy','axy','pco','pqu','cxy'
'rxx','rxy','txy'
default (pg not defined or 0):
for two data sequences x and y:
pg=['pxx','pco','pyy','pqu','cxy','axy','rxy','txy']
for one data sequence x:
pg=['pxx','rxx']
when pg set to 1:
for two data sequences x and y:
pg=['pxx','pxy','pyy','axy','cxy','txy','rxy']
for one data sequence x:
pg=['pxx','rxx']
PLOTM: input, integer, when set, determine the type of the plot
(default is 0):
x y simple weighted confidence weighted+confidence
lin-lin 0 4 8 12
lin-log 1 5 9 13
log-lin 2 6 10 14
log-log 3 7 11 15
weighted psd = Freq*P
PLOTPS: input, integer, set display window or PS device
for display windows: 0 to 31
for postscript: 99
Enter -1 to leave the current device active
PSDMOM: input, fltarr(5), the corresponding output from fftspec;
the moments will be printed at the bottom of the page
for a postscript device
RAXIS: input, fltarr, must be the corresponding output from fftspec
SLOPE: input, fltarr, [fstart,fstop], calculates a linear fit
for psds between fstart and fstop frequencies and plots out
the slope value; when set with a scalar different than 0
(e.g.,/slope), calculates a fit for the full freq range
ZOOM: input, fltarr, [fmin,fmax], when set plots between fmin and
fmax default is the full frequency range
HELP: show this text
SIDE EFFECTS:
Create plots on X or PS device
NOTES:
This program is intended as a simple plotting tool only.
Please report bugs to Samuel Haimov (haimov@uwyo.edu)
(See /tools/idl/idltools/specplot.pro)
NAME:
SPECTROGRAM
PURPOSE:
Calculates fft spectrogram for a n-point vector x divided into m (overlapping
or not) segments of nfft[1] size, each of which is detrended (mean or linear
trend) then windowed, padded with zeros (if needed) to the desired fft size,
nfft[0], FFT'd and stored in 2-D array.
CATEGORY:
idltools/signal
CALLING SEQUENCE:
spectrogram, P,nfft,x,overlap=overlap,windat=windat,freq=freq, $
time=time,detrendw=detrendw, help=help
INPUTS:
Nfft: long integer, or lonarr(2); fft length and data segment length
nfft[0]: FFT length (usually equal to the size of a data segment
unless nfft[1] is defined); proportional to power of 2
(e.g., 16,1024,...) is recommended
nfft[1}: optional data segment size (default is nfft[0]);
required conditions: nfft[0] ge nfft[1] and
nfft[1] le n_elements(x)
X: n-point vector, real or complex data
KEYWORD PARAMETERS:
DETRENDW: input, removes the mean or the linear trend from every data segment
0 - removes data segment linear trend (default)
1 - removes data segment mean
FREQ: input/output, sampling_rate/spectrogram_freq__axis
input: float, sampling rate, fs (it is used for scaling);
default (FREQ not defined) is 1; If FREQ is an array
it is assumed that fs=2*freq[n_elements(freq)-1]
output: frequency axis for the spectrogram; freq. resolution is
the first positive non-zero value;
freq[n_elements(freq)-1] is the Nyquist frequency
OVERLAP: input,long integer, number of overlapping data points
per data segment (default, 0, maximum 0.75*nfft[1])
TIME: input/output, start time / time axis of the spectrogram in
units determined by fs [1/fs]
input: long, hhmmss, start time for the input data series x
(default is 0); Note: In case of a spatial data series
enter negative number for the initial distance
output: fltarr, time axis of the spectrogram
WINDAT: input,wintype or [wintype,ntap], or [wintype,ntap,wflag] data
window parameters:
wintype: 0 - no data windowing (rectangular window, default)
1 - Hanning data window
2 - Hamming data window
3 - Blackman data window
ntap: number of points to be used to create wintype taper
(i.e., flat top window tapered as wintype for the first
ntap/2 and last ntap/2 points of the nfft[1] window);
usually ntap/nfft[1] is about 0.1 to 0.2;
if ntap=0 no tapering is performed; ntap < 16 is not
recommended
wflag: when set calculates periodical window;
default (or 0) is symmetrical window
HELP: show this help information
OUTPUTS:
P: fltarr(k,m), 2-D spectrogram; k-frequency, m-time
k = nfft[0] - for complex data
nfft[0]/2+1 - for real data and even nfft[0]
(nfft[0]+1)/2 - for real data and odd nfft[0]
NOTES:
0) Running spectrogram without parameters will display the usage
1) External routines: detrend, hann, hamming, blackman, mean
2) For complex signals, psds are shifted and 0 freq is f(nfft[0]/2) for
even nfft[0] and f((nfft[0]+1)/2) for odd nfft. Nyquist freq is the
last positive frequency.
3) The area under each spectrum equals the power in the data segment
(DC is excluded). Therefore for complex signals calculated spectra
are two-sided, while for real signals, one-sided.
4) Up to 50% overlapping is recommended when Hann, Hamming or Blackman
windows are used. Low or no overlapping should be used with tapers
to avoid correlation between sample spectra.
EXAMPLE:
n =16384 & nfft =512 & nwin =128
dt =0.5 & fs =1./dt & df =1./(nfft*dt)
fr=fltarr(n)
for k=1,nwin do fr((k-1)*nwin:k*nwin-1)=0.3+sin(2*!pi*(k-1)/nwin)*0.2
x=sin(2*!pi*fr*findgen(n)*dt)+1.1*randomn(seed,n)
f=fs & t=1.
spectrogram,P,[nfft,nwin],x,overlap=0,windat=1,freq=f,time=t,/detrend
aximage,P,/tr,t,f,setw=[-1,13,0,1],xtitle='Time [s]',ytitle='Frequency [hz]', $
title=['Spectrogram',' [x]^2/Hz'],imgz=2,asp=0.5,/bar
(See /tools/idl/idltools/spectrogram.pro)
NAME:
SRTM2HLL
PURPOSE:
Extract terrain elevation data (in meters) from SRTM data
file. The SRTM files are expected in 1 arc sec resolution
covering 1x1 deg segment (3601 x 3601). The srtm file name
must comply with the following convention: A88B999.hgt where
A is 'N' or 'S'; 88 is the segment botom left corner latitude;
B is 'W' or 'E', and 999 is the segment bottom left
corner longitude.
CATEGORY:
idltools
CALLING SEQUENCE:
srtm2hll,fn,hgt,lat,lon
INPUTS:
Fn: string, path/filename for the SRTM file
'' opens dialog_pickfile or if SECTOR is defined
uses the path for file location
string that ends with '/' is considered directory
path and dialog_pickfile opens for file selection
(irrelevant when SECTOR is defined)
KEYWORD PARAMETERS:
ARCSEC: input, integer, resolution in arc seconds; default is 1;
allowed values: 1 to 10, except 7
Note: elev. values for arcsec > 1 are not averaged,
ie, they are left unchanged from the original
1-sec data unless AVERAGE keyword is set
AVERAGE: input, when set and ARCSEC>1 the Hgt is the averaged of all
participating cells; the keyword is ignored if ARCSEC<2
(default is not to average and use the 1-arsec Hgt values)
NAN: when set replaces missing values(-32768) with NaNs
(ignored if TECPLOT keyword is set)
SECTOR: input,strarr(4), [lat0,lat1,lon0,lon1], min/max
LAT/LON position in 'A88.8' and 'B999.9' format
for the output Hgt (default,not defined: 1x1 deg
segment, given by Fn, is extracted)
Notes: 1) if SECTOR is defined Fn must contain the path
to the 1-sec SRTM file(s) only; empty string
for Fn means the current directory
2) the format is strictly enforced,
e.g., N41.45, W89.0, W089 will generate errors
3) A ('N' or 'S') must be the same for lat0 and lat1;
B ('W' or 'E') must be the same for lon0 and lon1
TECPLOT: input, string, path/file name of an ascii file containing
Hgt, Lat, and Lot output data (see SIDE EFFECTS)
HELP: shows this text
OUTPUTS:
Hgt: intarr(n,n) or fltarr(n,n), when NAN and/or AVERAGE are/is set;
(LON,LAT) elevations in meters
Lat: fltarr(n), latitude in degrees (negative if 'S')
Lon: dblarr(n), longitude in degrees (negative if 'W')
SIDE EFFECTS:
When keyword TECPLOT is defined the routine writes an ascii file
containing Hgt, Lat, and Lon in a format appropriate for use
with preplot utility, part of TECPLOT visualization software
NOTES:
The original 1-sec srtm data may have missing values (elevations).
Integer -32768 is used as a missing value in the input data.
When AVERAGE is not set HGT are the instantaneous values from the 1-sec
data at the corresponding LON/LAT (ie, the output hgt matches the input
hgt). If AVERAGE is set a simple averaging to all participating 1-sec
elevation values is performed. Note that outliers participating in the
calculated coarser resolution elevation will bias the mean.If a missing
value is detected within the desired resolution the averaged result is
also a missing value.
EXAMPLES:
srtm2hll,'srtm-1/',hgt,lat,lon,$
sector=['N41.0','N41.8','W105.0','W106.5'],$
arcsec=3,tecplot='N4142W105107.tecdat'
(See /tools/idl/idltools/srtm2hll.pro)
NAME:
STD
PURPOSE:
Returns unbiased standard deviation(std)/variance for random variable X.
CALLING SEQUENCE:
result=std(x, dim, var=var,nan=nan,silent=silent,help=help)
INPUTS:
X: input array (any numerical type)
Dim: the array dimension over which to calculate std, starting from 1
If DIM=0 or not present std for the whole array is calculated.
OUTPUTS:
The result is a scalar for DIM=0 or not present. For DIM > 0 the result
is an array with one less dimension than X. For LONG, DOUBLE, DCOMPLEX,
ULONG, LONG64, or ULONG64 the result is DOUBLE; for BYTE, INT, FLOAT it
is FLOAT; and for the complex types it matches the type.
KEYWORD PARAMETERS:
VAR: when set, the result is the variance
NAN: when set, NaNs in X are treated as missing values
SILENT: when set, information messages are suppressed
HELP: prints this help
NOTES:
The result has slightly better precision and the computation is
faster for 1-D arrays or when DIM=0.
The function does not handle well one data point cases for now.
It returns NaN and possibly a message: "% Program caused arithmetic
error: Floating illegal operand" for these cases.
print,std() prints out the usage
(See /tools/idl/idltools/std.pro)
NAME:
STRADJ
PURPOSE:
Adjust a string or string array to the left, right or center
CATEGORY:
String
CALLING SEQUENCE:
res=stradj(s,adjust=adjust,len=len,char=char,help=help)
INPUT:
S: string or string array
KEYWORD PARAMETERS:
ADJUST: 0 - no adjust, expand/trim the string to size len
if necessary padd spaces or char (default)
1 - adjust right (remove all trailing spaces)
2 - adjust left (remove all leading spaces)
3 - center (remove/add leading and trailing spaces to center)
LEN: 0 - use (max) length of s (default)
n - use n as desired max length
when necessary will trim s or padd with char
CHAR: filling character for adjusted strings, default is space
HELP: show this text
OUTPUTS:
res - adjusted string s
EXAMPLE:
Creating an adjusted numerical table is one useful application
of this function in combination with string function num2str.pro
stra=strarr(10,11)
stra(*,0)=['A','B','C','D','E','F','G','H','I','K']
stra(*,1:10)=num2str(findgen(10,10),/nozero,len=4)
print,stradj(stra,adj=3,len=7)
For more information on num2str type print,num2str(/help)
(See /tools/idl/idltools/stradj.pro)
NAME:
STRARR2STR
PURPOSE:
Concatenates the elements of a string array to a single string
CATEGORY:
String
CALLING SEQUENCE:
res=strarr2str(s,delimiter,help=help)
INPUT:
S: string array
Delimiter: string/char, to be used as separators between
the strings in S; default is space; to concatenate
without delimeter use an empty string '' or use
idl routine strjoin
KEYWORD PARAMETERS:
HELP: show this text
OUTPUTS:
Res: string with concatenated elements of S
SIDE EFFECTS:
If the input is not a string the function returns
an error message and Res is an empty string
If the input is a string but not an array the output
is identical to the input
EXAMPLE:
stra=num2str([12,30,5],len=2,char='0')
print,strarr2str(stra,':')
stra=['This','is','a','test']
print,strarr2str(stra)
NOTES:
This routine is redundant. You can use the standard idl routine
strjoin
(See /tools/idl/idltools/strarr2str.pro)
NAME:
SYMCAT
PURPOSE:
This function provides a symbol catalog for specifying a number of plotting symbols.
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:
Plot, findgen(11), PSYM=SYMCAT(theSymbol)
To connect symbols with lines, use a negative value for the PSYM keyword:
Plot, findgen(11), PSYM=-SYMCAT(theSymbol)
INPUTS:
theSymbol: The number of the symbol you wish to use. Possible values are:
0 : No symbol.
1 : Plus sign.
2 : Asterisk.
3 : Dot (period).
4 : Open diamond.
5 : Open upward triangle.
6 : Open square.
7 : X.
8 : Defined by the user with USERSYM.
9 : Open circle.
10 : Histogram style plot.
11 : Open downward triangle.
12 : Open rightfacing triangle.
13 : Open leftfacing triangle.
14 : Filled diamond.
15 : Filled square.
16 : Filled circle.
17 : Filled upward triangle.
18 : Filled downward triangle.
19 : Filled rightfacing triangle.
20 : Filled leftfacing triangle.
21 : Hourglass.
22 : Filled Hourglass.
23 : Bowtie.
24 : Filled bowtie.
25 : Standing Bar.
26 : Filled Standing Bar.
27 : Laying Bar.
28 : Filled Laying Bar.
29 : Hat up.
30 : Hat down.
31 : Hat right.
32 : Hat down.
33 : Big cross.
34 : Filled big cross.
35 : Circle with plus.
36 : Circle with X.
37 : Upper half circle.
38 : Filled upper half circle.
39 : Lower half circle.
40 : Filled lower half circle.
41 : Left half circle.
42 : Filled left half circle.
43 : Right half circle.
44 : Filled right half circle.
45 : Star.
46 : Filled star.
RETURN VALUE:
The return value is whatever is appropriate for passing along
to the PSYM keyword of (for example) a PLOT or OPLOT command.
For the vast majority of the symbols, the return value is 8.
KEYWORDS:
None.
MODIFICATION HISTORY:
Written by David W. Fanning, 2 September 2006. Loosely based on the
program MC_SYMBOL introduced on the IDL newsgroup 1 September 2006,
and MPI_PLOTCONFIG__DEFINE from the Coyote Library.
2 October 2006. DWF. Modified to allow PSYM=8 and PSYM=10 to have
their normal meanings. This shifted previous symbols by two values
from their old meanings. For example, an hourglass went from symbol
number 19 to 21.
(See /tools/idl/idltools/symcat.pro)
NAME:
TIME2SEC
PURPOSE:
Returns time after midnight given as hhmmss.dd in seconds
CATEGORY:
idltools/general
CALLING SEQUENCE:
res = time2sec(time)
INPUTS:
Time: input, long/double, time given as hhmmss[.dd]
KEYWORD PARAMETERS:
UNIX: long, YYYYMMDD for the input Time. If given time2sec
will return unix seconds for the given Time
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/time2sec.pro)
NAME:
TIME2TIMESTR
PURPOSE:
Returns time after midnight given in hhmmss.dd as a string/array 'hh:mm:ss'
The divider (':') is selectable.
CATEGORY:
idltools/general
CALLING SEQUENCE:
res = time2timestr(time)
INPUTS:
Time: input, long/double scalar/array, time given as hhmmss[.dd]
KEYWORD PARAMETERS:
DIVIDER: input, character to be used in the output time string
default is ':'; use empty string '' for no divider
FRAC: if set time2timestr will return 'hh:mm:ss.dd', where dd is
(time mod 1) truncated after the 2nd decimal place
otherwise the output is rounded to the closest second
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/time2timestr.pro)
NAME:
TIMEAXIS
PURPOSE:
Plot a time axis.
CATEGORY:
CALLING SEQUENCE:
timeaxis, [t]
INPUTS:
t = optional array of seconds after midnight. in
KEYWORD PARAMETERS:
Keywords:
JD=jd Set Julian Day number of reference date.
FORM=f Set axis label format string, over-rides default.
do help,dt_tm_mak(/help) to get formats.
For multi-line labels use @ as line delimiter.
NTICKS=n Set approximate number of desired ticks (def=6).
TITLE=txt Time axis title (def=none).
TRANGE=[tmin,tmax] Set specified time range.
YVALUE=Y Y coordinate of time axis (def=bottom).
TICKLEN=t Set tick length as % of yrange (def=5).
/NOLABELS means suppress tick labels.
/NOYEAR drops year from automatically formatted labels.
Doesn't apply to user specified formats.
LABELOFFSET=off Set label Y offset as % yrange (def=0).
Allows label vertical position adjustment.
DY=d Set line spacing factor for multiline labels (def=1).
COLOR=c Axis color.
CHARSIZE=s Axis text size.
CHARTHICK=cth thickness of label text (def=1).
THICK=thk thickness of axes and ticks (def=1).
MAJOR=g Linestyle for an optional major tick grid.
MINOR=g2 Linestyle for an optional minor tick grid.
TMAJOR=tmaj Returned seconds after JD of major ticks.
TMINOR=tmin Returned seconds after JD of minor ticks.
XBOTTOM Draws bottom x axis only
OUTPUTS:
COMMON BLOCKS:
NOTES:
Notes: To use do the following:
plot, t, y, xstyle=4
timeaxis
If no arguments are given to TIMEAXIS then an
axis will be drawn based on the last plot, if any.
Try DY=1.5 for PS fonts.
MODIFICATION HISTORY:
R. Sterner, 25 Feb, 1991
R. Sterner, 26 Jun, 1991 --- made nticks=0 give default ticks.
R. Sterner, 18 Nov, 1991 --- allowed Log Y axes.
R. Sterner, 11 Dec, 1992 --- added /NOLABELS.
R. Sterner, 20 May, 1993 --- Made date labeling (jd2mdays).
Allowed CHARSIZE for SIZE.
R. Sterner, 1999 Sep 23 --- Returned major and minor tick positions.
R. Sterner, 2000 Jun 23 --- Added label shift: LSHIFT=sec.
S. Haimov, 2001 Mar 15 --- Added /XBOTTOM
Copyright (C) 1991, Johns Hopkins University/Applied Physics Laboratory
Wyoming. 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 expressed or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See /tools/idl/idltools/timeaxis.pro)
NAME:
TIMESTR2SEC
PURPOSE:
Returns time given in 'hh:mm:ss[.dd]' as seconds after midnight.
The fractional part, if exist, is handled according to the FRAC keyword.
All leading and trailing spaces in the input are removed before checking
it for errors (see the requirements for the input Time).
CATEGORY:
idltools/general
CALLING SEQUENCE:
res = timestr2sec(time)
INPUTS:
Time: input, string/array, time in 'hh:mm:ss[.dd]' or 'h:mm:ss[.dd]',
For single digit minute or second the input should either have
a leading 0 or a leading space (e.g., '7:05:02' or '7: 5: 2')
Note that spaces are not allowed between hh/mm/ss and ':'.
KEYWORD PARAMETERS:
FRAC: if set timestr2sec will return double inclding the fractional
part in the input time; otherwise the output is long, truncated
after the whole seconds part
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/timestr2sec.pro)
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.
1642 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:
UNDEFINE, variable
REQUIRED INPUTS:
variable: The variable to be deleted. Up to 10 variables may be specified as arguments.
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
Simplified it even more by removing the unnecessary SIZE function. 28 June 2002. DWF.
Added capability to delete up to 10 variables at suggestion of Craig Markwardt. 10 Jan 2008. DWF.
(See /tools/idl/idltools/undefine.pro)
NAME:
UNIXTIME2US
PURPOSE:
Returns unix seconds,us,(double) given standard unix date/time string.
The reverse of this procedure is systime(0,us,/utc) )
UNIX seconds are defined here as seconds from Jan 1 1970 00:00:00 UTC
CATEGORY:
idltools/general
CALLING SEQUENCE:
res = unixtime2us(time)
INPUTS:
Time: standard unix time string (epoch starts Thu Jan 01 00:00:00 1970)
KEYWORD PARAMETERS:
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/unixtime2us.pro)
NAME:
US2UNIXTIME
PURPOSE:
Returns unix date/time string given unix seconds in UTC
It is similar to the upgraded RSI function systime(0,us,[/utc])
with the addition of DATE keyword.
CATEGORY:
idltools/general
CALLING SEQUENCE:
res = us2unixtime(us)
INPUTS:
Us: input, long/double, unix seconds from unix epoch
(00:00:00 UTC, 1 Jan 1970)
KEYWORD PARAMETERS:
DATE: input,returns date
if input is 1 returns YYYYMMDD
if input is 2 returns YYYYMMDDHHMMSS
UTC: input, when set Us is UTC
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
SIDE EFFECTS:
(See /tools/idl/idltools/us2unixtime.pro)
NAME:
WORDARRAY
PURPOSE:
Convert text string or string array to 1-d array of words.
CATEGORY:
CALLING SEQUENCE:
wordarray, instring, outlist
INPUTS:
instring = string or string array to process. in
KEYWORD PARAMETERS:
Keywords:
IGNORE=string of characters to ignore (array allowed).
These characters are removed before processing.
Ex: wordarray,in,out,ignore=',;()'
wordarray,in,out,ignore=[',',';','(',')']
DELIMITERS = word delimiter characters, like IGNORE.
/WHITE means include white space (spaces,tabs) along
with the specified delimiters.
NUMBER=num Number of elements in returned array.
OUTPUTS:
outlist = 1-d array of words in instring. out
COMMON BLOCKS:
NOTES:
Notes: Words are assumed delimited by given delimiters
(defaults are spaces and/or tabs)
Non-delimiters are returned as part of the words.
Delimiters not needed at the front and end of the strings.
See commalist for a near inverse.
MODIFICATION HISTORY:
R. Sterner, 29 Nov, 1989
BLG --- Modified June 22,1991 to include tabs as delimiters
R. Sterner, 11 Dec, 1992 --- fixed to handle pure white space.
R. Sterner, 27 Jan, 1993 --- dropped reference to array.
R. Sterner, 1998 Apr 1 --- Added DELIMITER. Modified IGNORE.
R. Sterner, 1998 Jul 31 --- Added NUMBER=nwds.
Copyright (C) 1989, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
(See /tools/idl/idltools/wordarray.pro)
NAME:
WYOCTIND
PURPOSE:
Returns starting black color index for dual color tables
separated by a black color strip, e.g. WYO12 (ct=45) and WYO23 (ct=46)
The black strip must be around the middle of the table (mid index).
Color tables 41 to 48 only are searched.
CATEGORY:
idltools/graphics
CALLING SEQUENCE:
wyoctind, ct
INPUTS:
ct - color table number
KEYWORD PARAMETERS:
HELP - show this text
OUTPUTS:
Returns first index of a black color in a dual color table.
If black color is not found returns -1.
COMMON BLOCKS:
common colors
NOTE:
If the available total color indices are less than 64 returns -1
Surch 20 indices in the middle of the table only
If ct is not given or negative, current color table is used.
If ct is given it searches from 41 to 48 color tables only
(See /tools/idl/idltools/wyoctind.pro)
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 /tools/idl/idltools/xcolors.pro)
NAME:
XCOLORT
PURPOSE:
XCOLORT allows to change a color table for given color indices.
See also CREATECT.
CATEGORY:
Color tables, widgets.
CALLING SEQUENCE:
XCOLORT, colorind
INPUTS:
colorind - [index,ncolors], where index is the first index and ncolors
is the number of indices in r_curr,g_curr and b_curr to be
updated. Values must be between 0 and 255.
KEYWORD PARAMETERS:
TOP - Adjust color indices according to the maximum color available
GROUP - Group leader, as passed to XMANAGER.
HELP - show this text
OUTPUTS:
r_curr,g_curr,b_curr (in common block COLORS)
COMMON BLOCKS:
COLORS: Contains the current RGB color tables.
SIDE EFFECTS:
The new color is saved in the COLORS common
and loaded to the display.
PROCEDURE:
Three sliders (R, G, and B) allow the user to modify the
current color.
(See /tools/idl/idltools/xcolort.pro)
NAME:
XCREATECT
PURPOSE:
XCREATECT allows to create a color table for given color indices.
See also CREATECT.
CATEGORY:
Color tables, widgets.
CALLING SEQUENCE:
XCREATECT
INPUTS:
KEYWORD PARAMETERS:
INIT - Erase current color table
CTINDEX - bytarr(2), start/stop color indices
CTNAME - string, color table name (in the color table file)
CTRID - byte, id color number in the color table file
CTFILE - string, file name of the color table to be modified
HELP - shows this help text
GROUP - Group leader, as passed to XMANAGER.
OUTPUTS:
r_curr,g_curr,b_curr (in common block COLORS)
COMMON BLOCKS:
COLORS: Contains the current RGB color tables.
COLORIND: Contains working variables
SIDE EFFECTS:
The new color is saved in the COLORS common block
and loaded to the display.
PROCEDURE:
Three sliders (R, G, and B) allow the user to modify the
current color.
(See /tools/idl/idltools/xcreatect.pro)
NAME:
XMESSAGE
PURPOSE:
Widget based message display
CATEGORY:
idltools/general, widgets
CALLING SEQUENCE:
xmessage,txt
INPUT:
Txt - string to be displayed
KEYWORD PARAMETERS:
HELP: Show this text
OUTPUTS:
COMMON BLOCKS:
(See /tools/idl/idltools/xmessage.pro)
NAME:
ZOOM
PURPOSE:
Display part of an image (or graphics) from the current window
enlarged in another window.
The cursor is used to mark the center of the zoom.
CATEGORY:
idltools/image
CALLING SEQUENCE:
ZOOM [, FACT = Fact, /INTERP, XSIZE = Xs, YSIZE = Ys, /CONTINUOUS, $
/KEEP, ZOOM_WINDOW=Zoom_Win, /NEW_WINDOW, /HELP ]
INPUTS:
All input parameters are passed as keywords.
KEYWORDS:
FACT: Zoom factor. This parameter must be an integer. The default
zoom factor is 4.
INTERP: Set this keyword to use bilinear interpolation, otherwise
pixel replication is used.
XSIZE: The X size of the zoom window. The default is 512.
YSIZE: The Y size of the zoom window. The default is 512.
CONTINUOUS: Set this keyword to make the zoom window track the mouse
without requiring the user to press the left mouse button.
This feature only works well on fast computers.
KEEP: Keep the zoom window after exiting the procedure.
ZOOM_WINDOW: When used with KEEP, returns the index of the zoom window.
Otherwise, if KEEP is not set, then -1 is returned.
NEW_WINDOW: Normally, if ZOOM is called with /KEEP and then called again,
it will use the same window to display the zoomed image.
Calling ZOOM with /NEW_WINDOW forces it to create a new window
for this purpose.
HELP: Show this text
OUTPUTS:
No explicit outputs. A new window is created if necessary. It
is destroyed upon exit if KEEP is not specified.
COMMON BLOCKS:
common zoom_window
SIDE EFFECTS:
A window is created/destroyed.
When ZOOM is reusing a zoom window from a previous call to ZOOM,/KEEP,
then the XSIZE and YSIZE parameters are reset to the actual size of the
window.
RESTRICTIONS:
ZOOM only works with color systems.
PROCEDURE:
(See /tools/idl/idltools/zoom.pro)