[Previous Routine] [Next Routine] [List of Routines]NAME: NINT PURPOSE: Nearest integer function. EXPLANATION: NINT() is similar to the intrinsic ROUND function, with the following two differences: (1) if no absolute value exceeds 32767, then the array is returned as as a type INTEGER instead of LONG (2) NINT will work on strings, e.g. print,nint(['3.4','-0.9']) will give [3,-1] CALLING SEQUENCE: result = nint( x, [ /LONG] ) INPUT: X - An IDL variable, scalar or vector, usually floating or double Unless the LONG keyword is set, X must be between -32767.5 and 32767.5 to avoid integer overflow OUTPUT RESULT - Nearest integer to X OPTIONAL KEYWORD INPUT: LONG - If this keyword is set and non-zero, then the result of NINT is of type LONG. Otherwise, the result is of type LONG if any absolute values exceed 32767, and type INTEGER if all all absolute values are less than 32767. EXAMPLE: If X = [-0.9,-0.1,0.1,0.9] then NINT(X) = [-1,0,0,1] PROCEDURE CALL: DATATYPE() REVISION HISTORY: Written W. Landsman January 1989 Added LONG keyword November 1991 Use ROUND if since V3.1.0 June 1993 Always start with ROUND function April 1995 Return LONG values, if some input value exceed 32767 and accept string values February 1998(See nint.pro)
NSTAR
[Previous Routine] [Next Routine] [List of Routines]NAME: NSTAR PURPOSE: Simultaneous point spread function fitting (adapted from DAOPHOT) CALLING SEQUENCE: NSTAR, image, id, xc, yc, mags, sky, group, [ phpadu, readns, psfname, magerr, iter, chisq, peak, /PRINT , /SILENT, /VARSKY, /DEBUG ] INPUTS: image - image array id - vector of stellar ID numbers given by FIND xc - vector containing X position centroids of stars (e.g. as found by FIND) yc - vector of Y position centroids mags - vector of aperture magnitudes (e.g. as found by APER) If 9 or more parameters are supplied then, upon output ID,XC,YC, and MAGS will be modified to contain the new values of these parameters as determined by NSTAR. Note that the number of output stars may be less than the number of input stars since stars may converge, or "disappear" because they are too faint. sky - vector of sky background values (e.g. as found by APER) group - vector containing group id's of stars as found by GROUP OPTIONAL INPUT: phpadu - numeric scalar giving number of photons per digital unit. Needed for computing Poisson error statistics. readns - readout noise per pixel, numeric scalar. If not supplied, NSTAR will try to read the values of READNS and PHPADU from the PSF header. If still not found, user will be prompted. psfname - name of FITS image file containing the point spread function residuals as determined by GETPSF, scalar string. If omitted, then NSTAR will prompt for this parameter. OPTIONAL OUTPUTS: MAGERR - vector of errors in the magnitudes found by NSTAR ITER - vector containing the number of iterations required for each output star. CHISQ- vector containing the chi square of the PSF fit for each output star. PEAK - vector containing the difference of the mean residual of the pixels in the outer half of the fitting circle and the mean residual of pixels in the inner half of the fitting circle OPTIONAL KEYWORD INPUTS: SILENT - if set and non-zero, then NSTAR will not display its results at the terminal PRINT - if set and non-zero then NSTAR will also write its results to a file NSTAR.PRT. One also can specify the output file name by setting PRINT = 'filename'. VARSKY - if this keyword is set and non-zero, then the sky level of each group is set as a free parameter. DEBUG - if this keyword is set and non-zero, then the result of each fitting iteration will be displayed. PROCEDURES USED: DAO_VALUE(), READFITS(), REMOVE, SPEC_DIR(), STRN(), SXPAR() COMMON BLOCK: RINTER - contains pre-tabulated values for cubic interpolation REVISION HISTORY W. Landsman ST Systems Co. May, 1988 Adapted for IDL Version 2, J. Isensee, September, 1990 Minor fixes so that PRINT='filename' really prints to 'filename', and it really silent if SILENT is set. J.Wm.Parker HSTX 1995-Oct-31 Added /VARSKY option W. Landsman HSTX May 1996 Converted to IDL V5.0 W. Landsman September 1997(See nstar.pro)
NULLTRIM
[Previous Routine] [Next Routine] [List of Routines]NAME: NULLTRIM PURPOSE: Trim a string of all characters after and including the first null EXPLANATION: The null character is an ascii 0b CALLING SEQUENCE: result = nulltrim( st ) INPUTS: st = input string OUTPUTS: trimmed string returned as the function value. HISTORY: D. Lindler July, 1987 Converted to IDL V5.0 W. Landsman September 1997(See nulltrim.pro)
NUMLINES()
[Previous Routine] [Next Routine] [List of Routines]NAME: NUMLINES() PURPOSE: Return the number of lines in a file CALLING SEQUENCE: nl = NUMLINES( filename ) INPUT: filename = name of file, scalar string OUTPUT: nl = number of lines in the file, scalar longword Set to -1 if the number of lines could not be determined METHOD: If Unix then spawn to wc; otherwise read 1 line at a time and count PROCEDURE CALLS: EXPAND_TILDE(), SPEC_DIR() MODIFICATION HISTORY: W. Landsman February 1996 Use /bin/sh shell with wc under Unix March 1997 Use EXPAND_TILDE() under Unix September 1997 Converted to IDL V5.0 W. Landsman September 1997(See numlines.pro)
NUTATE
[Previous Routine] [Next Routine] [List of Routines]NAME: NUTATE PURPOSE: Return the nutation in longitude and obliquity for a given Julian date CALLING SEQUENCE: NUTATE, jd, Nut_long, Nut_obliq INPUT: jd - Julian ephemeris date, scalar or vector, double precision OUTPUT: Nut_long - the nutation in longitude, same # of elements as jd Nut_obliq - nutation in latitude, same # of elements as jd EXAMPLE: Plot the large-scale variation of the nutation in longitude during the 20th century IDL> yr = 1900 + indgen(100) IDL> jdcnv,yr,1,1,0,jul ;Find Julian date of first day of year IDL> nutate,jul, nut_long ;Nutation in longitude IDL> plot, yr, nut_long This plot will reveal the dominant (18.6 year) period, but a finer grid is needed to display the shorter periods in the nutation. METHOD: Uses the formula in Chapter 21 of ``Astronomical Algorithms'' by Jean Meeus which is based on the 1980 IAU Theory of Nutation and includes all terms larger than 0.0003". PROCEDURES CALLED: POLY() (from IDL User's Library) CIRRANGE, ISARRAY() (from IDL Astronomy Library) REVISION HISTORY: Written, W.Landsman (Goddard/HSTX) June 1996 Converted to IDL V5.0 W. Landsman September 1997(See nutate.pro)
N_STRUCT
[Previous Routine] [Next Routine] [List of Routines]NAME: N_STRUCT PURPOSE: To determine if variable is a structure and return number of elements. CALLING SEQUENCE: n = N_struct( var, ntags ) INPUT: var = any variable. OUTPUT: ntags = number of structure tags. RESULT: Returns zero if variable is not a structure, otherwise returns # elems. PROCEDURE: Determine if argument is a structure by checking for # of tags. If structure, use size function to get # of elements (instead of N_elements) so that it works on I/O associated structures. MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC 1989. Converted to IDL V5.0 W. Landsman September 1997(See n_struct.pro)
ONE_ARROW
[Previous Routine] [Next Routine] [List of Routines]NAME: ONE_ARROW PURPOSE: Draws an arrow labeled with a single character on the current device EXPLANATION: ONE_ARROW is called, for example, by ARROWS to create a "weathervane" showing the N-E orientation of an image. CALLING SEQUENCE: one_arrow, xcen, ycen, angle, label, CHARSIZE = , THICK = , COLOR = ARROWSIZE=, FONT = ] INPUT PARAMETERS: xcen, ycen = starting point of arrow in device coordinates, floating point scalars, angle = angle of arrow in degrees counterclockwise from +X direction label = single-character label (may be blank) OUTPUT PARAMETERS: none OPTIONAL INPUT PARAMETERS: CHARSIZE = usual IDL meaning, default = 2.0 THICK = usual IDL meaning, default = 2.0 COLOR = usual IDL meaning, default = !P.COLOR ARROWSIZE = 3-element vector defining appearance of arrow. Default = [30.0, 9.0, 35.0], meaning arrow is 30 pixels long; arrowhead lines 9 pixels long and inclined 35 degrees from arrow shaft. If you try to use a non-TV device, you will probably want to change this. FONT - IDL vector font number to use (1-20). For example, to write the 'N' and 'E' characters in complex script, set font=13 EXAMPLE: Draw an triple size arrow emanating from the point (212,224) and labeled with the character 'S' IDL> one_arrow,212,224,270,'S',charsize=3 PROCEDURE: Calls one_ray to vector-draw arrow. MODIFICATION HISTORY: Written by R. S. Hill, Hughes STX Corp., 20-May-1992. Added font keyword, W.B. Landsman Hughes STX Corp. April 1995 Modified to work correctly for COLOR=0 J.Wm.Parker, HITC 1995 May 25 Converted to IDL V5.0 W. Landsman September 1997(See one_arrow.pro)
ONE_RAY
[Previous Routine] [Next Routine] [List of Routines]NAME: ONE_RAY PURPOSE: Draw a line with a specified starting point, length, and angle CALLING SEQUENCE: one_ray, xcen, ycen, len, angle, terminus, [ THICK=, COLOR =, /NODRAW ] INPUT PARAMETERS: xcen, ycen = starting point in device coordinates, floating point scalars len = length in pixels, device coordinates angle = angle in degrees counterclockwise from +X direction OUTPUT PARAMETERS: terminus = two-element vector giving ending point of ray in device coordinates OPTIONAL KEYWORD INPUT PARAMETERS: thick usual IDL meaning, default = 1.0 color usual IDL meaning, default = !P.COLOR nodraw if non-zero, the ray is not actually drawn, but the terminus is still calculated EXAMPLE: Draw a double thickness line of length 32 pixels from (256,256) 45 degrees counterclockwise from the X axis IDL> one_ray, 256, 256, 32, 45 ,term, THICK = 2 PROCEDURE: straightforward matrix arithmetic MODIFICATION HISTORY: Written by R. S. Hill, Hughes STX Corp., 20-May-1992. Modified to work correctly for COLOR=0 J.Wm.Parker HITC 1995 May 25 Converted to IDL V5.0 W. Landsman September 1997(See one_ray.pro)
OPLOTERROR
[Previous Routine] [Next Routine] [List of Routines]NAME: OPLOTERROR PURPOSE: Over-plot data points with accompanying X or Y error bars. EXPLANATION: For use instead of PLOTERROR when the plotting system has already been defined. CALLING SEQUENCE: oploterror, [ x,] y, [xerr], yerr [,/NOHAT, HATLENGTH= , ERRTHICK= , ERRSTYLE=, ERRCOLOR =, /LOBAR, /HIBAR, NSKIP= ] INPUTS: X = array of abcissae, any datatype except string Y = array of Y values, any datatype except string XERR = array of error bar values (along X) YERR = array of error bar values (along Y) OPTIONAL INPUT KEYWORD PARAMETERS: /NOHAT = if specified and non-zero, the error bars are drawn without hats. HATLENGTH = the length of the hat lines used to cap the error bars. Defaults to !D.X_VSIZE / 100). ERRTHICK = the thickness of the error bar lines. Defaults to the THICK plotting keyword. ERRSTYLE = the line style to use when drawing the error bars. Uses the same codes as LINESTYLE. ERRCOLOR = scalar integer (0 - !D.N_TABLE) specifying the color to use for the error bars NSKIP = Positive Integer specifying the error bars to be plotted. For example, if NSKIP = 2 then every other error bar is plotted; if NSKIP=3 then every third error bar is plotted. Default is to plot every error bar (NSKIP = 1) LOBAR = if specified and non-zero, will draw only the -ERR error bars. HIBAR = if specified and non-zero, will draw only the +ERR error bars. If neither LOBAR or HIBAR are set _or_ if both are set, you will get both error bars. Just specify one if you only want one set. NOTES: If only two parameters are input, they are taken as Y and YERR If only three parameters are input, they will be taken as X, Y and YERR respectively. EXAMPLE: Suppose one has X and Y vectors with associated errors XERR and YERR and that a plotting system has already been defined: (1) Overplot Y vs. X with both X and Y errors and no lines connecting the points IDL> oploterror, x, y, xerr, yerr, psym=3 (2) Like (1) but overplot only the Y errors bars and omits "hats" IDL> oploterror, x, y, yerr, psym=3, /NOHAT (3) Like (2) but suppose one has a positive error vector YERR1, and a negative error vector YERR2 (asymmetric error bars) IDL> oploterror, x, y, yerr1, psym=3, /NOHAT,/HIBAR IDL> oploterror, x, y, yerr2, psym=3, /NOHAT,/LOBAR PROCEDURE: A plot of X versus Y with error bars drawn from Y - YERR to Y + YERR and optionally from X - XERR to X + XERR is written to the output device WARNING: This an enhanced version of the procedure OPLOTERR in the standard RSI library. It was renamed to OPLOTERROR in June 1998 in the IDL Astronomy library. MODIFICATION HISTORY: Adapted from the most recent version of PLOTERR. M. R. Greason, Hughes STX, 11 August 1992. Removed spurious keywords for IDL V3.0.0 W. Landsman Jan. 1993 Added ability to plot a single point W. Landsman July 1993 Added COLOR keyword option to error bars W. Landsman November 1993 Add ERRCOLOR, use _EXTRA keyword, W. Landsman, July 1995 Remove spurious call to PLOT_KEYWORDS W. Landsman, August 1995 OPLOT more than 32767 error bars W. Landsman, Feb 1996 Added NSKIP keyword W. Landsman, Dec 1996 Added HIBAR and LOBAR keywords, M. Buie, Lowell Obs., Feb 1998 Rename to OPLOTERROR W. Lansdman June 1998 Converted to IDL V5.0 W. Landsman June 1998(See oploterror.pro)
ORDINAL
[Previous Routine] [Next Routine] [List of Routines]NAME: ORDINAL PURPOSE: Convert an integer to a correct English ordinal string: EXPLANATION: The first four ordinal strings are "1st", "2nd", "3rd", "4th" .... CALLING SEQUENCE: result = ordinal( num ) INPUT PARAMETERS: num = number to be made an ordinal. If float, will be FIXed. OUTPUT PARAMETERS: result = string such as '1st' '3rd' '164th' '87th', etc. MODIFICATION HISTORY: Written by R. S. Hill, STX, 8 Aug. 1991 Converted to IDL V5.0 W. Landsman September 1997(See ordinal.pro)
OSFCNVRT
[Previous Routine] [Next Routine] [List of Routines]NAME: OSFCNVRT PURPOSE: Return the correctly formatted logical directory syntax for the host OS CALLING SEQUENCE: OSFCNVRT,lname INPUTS: lname - the file specification as a logical name + file name string OUTPUTS: Returns appropriate string. SIDE EFFECTS: None. RESTRICTIONS: Assumes that the input is composed of only a logical and a filename combination without lower directory garbage. PROCEDURE: The operating system in !version.os is checked. If it equals: 'vms' then a ':' is appended. else unix os is assumed and the logical portion is uppercased, a '$' is prepended and a '/' is appended. MODIFICATION HISTORY: Written, JDNeill, May, 1990. Converted to IDL V5.0 W. Landsman September 1997(See osfcnvrt.pro)
PARTVELVEC
[Previous Routine] [Next Routine] [List of Routines]NAME: PARTVELVEC PURPOSE: Plot the velocity vectors of particles at their positions EXPLANATION: This procedure plots the velocity vectors of particles (at the positions of the particles). CATEGORY: Plotting, Two-dimensional. CALLING SEQUENCE: PARTVELVEC, VELX, VELY, POSX, POSY [, X, Y] INPUTS: VELX: An array of any dimension, containing the x-components of the particle velocities. VELY: An array of the same dimension as velx, containing the y-components of the particle velocities. POSX: An array of the same dimension as velx, containing the x-components of the particle positions. POSY: An array of the same dimension as velx, containing the y-components of the particle positions. OPTIONAL INPUTS: X: Optional abcissae values. X must be a vector. Y: Optional ordinate values. Y must be a vector. If only X is specified, then Y is taken equal to be equal to X. OPTIONAL INPUT KEYWORD PARAMETERS: FRACTION: The fraction of the vectors to plot. They are taken at random from the complete sample. Default is FRACTION = 1.0, use all vectors LENGTH: The maximum vectorlength relative to the plot data window. Default = 0.08 COLOR: The color for the vectors, axes and titles. Default=!P.COLOR Plot All other keywords available to PLOT are also used Keywords: by this procedure. OUTPUTS: This procedure plots the velocity vectors (VELX,VELY) at the positions of the particles, (POSX,POSY). If X and Y are not specified, then the size of the plot is such that all vectors just fit within in the plot data window. SIDE EFFECTS: Plotting on the current device is performed. EXAMPLE: Generate some particle positions and velocities. POSX=RANDOMU(seed,200) POSY=RANDOMU(seed,200) VELX=RANDOMU(seed,200)-0.5 VELY=RANDOMU(seed,200)-0.5 Plot the particle velocities. PARTVELVEC, VELX, VELY, POSX, POSY MODIFICATION HISTORY: Written by: Joop Schaye (jschaye@astro.rug.nl), Sep 1996. Converted to IDL V5.0 W. Landsman September 1997(See partvelvec.pro)
PCA
[Previous Routine] [Next Routine] [List of Routines]NAME: PCA PURPOSE: Carry out a Principal Components Analysis (Karhunen-Loeve Transform) EXPLANATION: Results can be directed to the screen, a file, or output variables See notes below for comparison with the intrinisc IDL function PCOMP. CALLING SEQUENCE: PCA, data, eigenval, eigenvect, percentages, proj_obj, proj_atr, [MATRIX =, TEXTOUT = ,/COVARIANCE, /SSQ, /SILENT ] INPUT PARAMETERS: data - 2-d data matrix, data(i,j) contains the jth attribute value for the ith object in the sample. If N_OBJ is the total number of objects (rows) in the sample, and N_ATTRIB is the total number of attributes (columns) then data should be dimensioned N_OBJ x N_ATTRIB. OPTIONAL INPUT KEYWORD PARAMETERS: /COVARIANCE - if this keyword is set, then the PCA will be carried out on the covariance matrix (rare), the default is to use the correlation matrix /SILENT - If this keyword is set, then no output is printed /SSQ - if this keyword is set, then the PCA will be carried out on on the sums-of-squares & cross-products matrix (rare) TEXTOUT - Controls print output device, defaults to !TEXTOUT textout=1 TERMINAL using /more option textout=2 TERMINAL without /more option textout=3.prt textout=4 laser.tmp textout=5 user must open file textout = filename (default extension of .prt) OPTIONAL OUTPUT PARAMETERS: eigenval - N_ATTRIB element vector containing the sorted eigenvalues eigenvect - N_ATRRIB x N_ATTRIB matrix containing the corresponding eigenvectors percentages - N_ATTRIB element containing the cumulative percentage variances associated with the principal components proj_obj - N_OBJ by N_ATTRIB matrix containing the projections of the objects on the principal components proj_atr - N_ATTRIB by N_ATTRIB matrix containing the projections of the attributes on the principal components OPTIONAL OUTPUT PARAMETER MATRIX = analysed matrix, either the covariance matrix if /COVARIANCE is set, the "sum of squares and cross-products" matrix if /SSQ is set, or the (by default) correlation matrix. Matrix will have dimensions N_ATTRIB x N_ATTRIB NOTES: This procedure performs Principal Components Analysis (Karhunen-Loeve Transform) according to the method described in "Multivariate Data Analysis" by Murtagh & Heck [Reidel : Dordrecht 1987], pp. 33-48. Keywords /COVARIANCE and /SSQ are mutually exclusive. The printout contains only (at most) the first seven principle eigenvectors. However, the output variables EIGENVECT contain all the eigenvectors Different authors scale the covariance matrix in different ways. The eigenvalues output by PCA may have to be scaled by 1/N_OBJ or 1/(N_OBJ-1) to agree with other calculations when /COVAR is set. PCA uses the non-standard system variables !TEXTOUT and !TEXTUNIT. These can be added to one's session using the procedure ASTROLIB. The intrinisc IDL function PCOMP (introduced in V5.0) duplicates most most of the functionality of PCA, but uses different conventions and normalizations. Note the following: (1) PCOMP requires a N_ATTRIB x N_OBJ input array; this is the transpose of what PCA expects (2) PCA uses standardized variables; use /STANDARIZE keyword to PCOMP for a direct comparision. (3) PCA (unlike PCOMP) normalizes the eigenvectors by the square root of the eigenvalues. (4) PCA returns cumulative percentages; the VARIANCES keyword of PCOMP returns the variance in each variable EXAMPLE: Perform a PCA analysis on the covariance matrix of a data matrix, DATA, and write the results to a file IDL> PCA, data, /COVAR, t = 'pca.dat' Perform a PCA analysis on the correlation matrix. Suppress all printing, and save the eigenvectors and eigenvalues in output variables IDL> PCA, data, eigenval, eigenvect, /SILENT PROCEDURES CALLED: TEXTOPEN, TEXTCLOSE REVISION HISTORY: Immanuel Freedman (after Murtagh F. and Heck A.). December 1993 Wayne Landsman, modified I/O December 1993 Converted to IDL V5.0 W. Landsman September 1997 Fix MATRIX output, remove GOTO statements W. Landsman August 1998 Changed some index variable to type LONG W. Landsman March 2000 (See pca.pro)
PENT
[Previous Routine] [Next Routine] [List of Routines]NAME: PENT PURPOSE: Return the information entropy of a time series EXPLANATION: This function will return S, the information entropy of a time series for a set of trial periods CATEGORY: Time series analysis, period finding, astronomical utilities. CALLING SEQUENCE: Result = PENT(P, T, X, [N, M ] ) INPUTS: P - array of trial period values. T - array of observation times (same units as P). X - array of observations. OPTIONAL INPUTS: N - If four parameters are given then the 4th parameter is assumed to be N. Then NxN boxes are used to calculate S. M,N - If five parameters are given then parameter 4 is M and parameter 5 is N. S is then calculated using MxN boxes - M partitions for the phase and N partitions for the data. OUTPUTS: This function returns S, the information entropy of the time series for the periods given in P as defined by Cincotta, Me'ndez & Nu'n~ez (Astrophysical Journal 449, 231-235, 1995). The minima of S occur at values of P where X shows periodicity. PROCEDURE: The procedure involves dividing the phase space into N^2 partitions (NxN boxes) and then calulating: __ N^2 S = - \ mu_i . ln(mu_i) for all mu_i <> 0 /_ i = 1 where mu_i is the number of data points in partition i normalised by the number of partitions. The option of using MxN boxes is an additional feature of this routine. EXAMPLE: To generate a similar sythetic data set to Cincotta et al. we do the following: IDL> P0 = 173.015 ; Fundamental period IDL> T = randomu(seed,400)*15000 ; 400 random observation times IDL> A0 = 14.0 ; Mean magnitude IDL> M0 = -0.5 * sin(2*!pi*T/P0) ; Fundamental mode IDL> M1 = -0.15 * sin(4*!pi*T/P0) ; 1st harmonic IDL> M2 = -0.05 * sin(6*!pi*T/P0) ; 2nd harmonic IDL> sig = randomu(seed,400)*0.03 ; noise IDL> U = A0 + M0 + M1 + M2 + sig ; Synthetic data IDL> Ptest = 100. + findgen(2000)/2. ; Trial periods IDL> S = pent(Ptest,T,U) ; Calculate S ... this takes a few seconds ... IDL> plot,Ptest,S,xtitle="P",ytitle="S" ; plot S v. P IDL> print,Ptest(where(S eq min(S))) ; Print best period (+/- 0.5) The plot produced should be similar to Fig. 2 of Cincotta et al. RESTRICTIONS: My own (limited) experience with this routine suggests that it is not as good as other techniques for finding weak, multi-periodic signals in poorly sampled data, but is good for establishing periods of eclipsing binary stars when M is quite large (try MxN = 64x16, 128x16 or even 256x16). This suggests it may be good for other periodic light curves (Cepheids, RR Lyrae etc.). I would be glad to receive reports of other peoples experience with this technique (e-mail pflm@bro730.astro.ku.dk). MODIFICATION HISTORY: Written by: Pierre Maxted, 14Sep95 Modifications: Normalisation of S corrected, T-min(T) taken out of loop. - Pierre Maxted, 15Sep95 Converted to IDL V5.0 W. Landsman September 1997(See pent.pro)
PIXCOLOR
[Previous Routine] [Next Routine] [List of Routines]NAME: PIXCOLOR PURPOSE: Assign colors to specified pixel values in a color lookup table CALLING SEQUENCE: PIXCOLOR, pixvalue, color ;Set color at specified pixel values OPTIONAL INPUT PARMETERS: pixvalue - value or range of pixel value whose color will be modified. A single pixel value may be specified by an integer If a range of values is specified, then it must be written as a string, with a colon denoting the range (e.g.'102:123') If omitted, program will prompt for this parameter. color - single character string giving specified color values. Available options are 'R' (red), 'B' (blue), 'G' (green) 'Y' (yellow), 'T' (turquoise), 'V' (violet), 'W' (white) or 'D' (dark). If omitted, program will prompt for this parameter. OUTPUTS: None PROCEDURE: TVLCT is used in RGB mode to load the specified pixel values. EXAMPLE: Set pixel values of 245 to a color of red IDL> pixcolor,245,'R' REVISION HISTORY: Written, W. Landsman ST Systems Corp. February, 1987 Converted to IDL V5.0 W. Landsman September 1997(See pixcolor.pro)
PKFIT
[Previous Routine] [Next Routine] [List of Routines]NAME: PKFIT PURPOSE: Subroutine of GETPSF to perform a one-star least-squares fit EXPLANATION: Part of the DAOPHOT PSF photometry sequence CALLING SEQUENCE: PKFIT, f, scale, x, y, sky, radius, ronois, phpadu, gauss, psf, errmag, chi, sharp, Niter, /DEBUG INPUTS: F - NX by NY array containing actual picture data. X, Y - the initial estimates of the centroid of the star relative to the corner (0,0) of the subarray. Upon return, the final computed values of X and Y will be passed back to the calling routine. SKY - the local sky brightness value, as obtained from APER RADIUS- the fitting radius-- only pixels within RADIUS of the instantaneous estimate of the star's centroid will be included in the fit, scalar RONOIS - readout noise per pixel, scalar PHPADU - photons per analog digital unit, scalar GAUSS - vector containing the values of the five parameters defining the analytic Gaussian which approximates the core of the PSF. PSF - an NPSF by NPSF look-up table containing corrections from the Gaussian approximation of the PSF to the true PSF. INPUT-OUTPUT: SCALE - the initial estimate of the brightness of the star, expressed as a fraction of the brightness of the PSF. Upon return, the final computed value of SCALE will be passed back to the calling routine. OUTPUTS: ERRMAG - the estimated standard error of the value of SCALE returned by this routine. CHI - the estimated goodness-of-fit statistic: the ratio of the observed pixel-to-pixel mean absolute deviation from the profile fit, to the value expected on the basis of the noise as determined from Poisson statistics and the readout noise. SHARP - a goodness-of-fit statistic describing how much broader the actual profile of the object appears than the profile of the PSF. NITER - the number of iterations the solution required to achieve convergence. If NITER = 25, the solution did not converge. If for some reason a singular matrix occurs during the least- squares solution, this will be flagged by setting NITER = -1. RESTRICTIONS: No parameter checking is performed REVISON HISTORY: Adapted from the official DAO version of 1985 January 25 Version 2.0 W. Landsman STX November 1988 Converted to IDL V5.0 W. Landsman September 1997(See pkfit.pro)
PLANCK()
[Previous Routine] [Next Routine] [List of Routines]NAME: PLANCK() PURPOSE: To calculate the Planck function in units of ergs/cm2/s/A CALLING SEQUENCE: bbflux = PLANCK( wave, temp) INPUT PARAMETERS: WAVE Scalar or vector giving the wavelength(s) in **Angstroms** at which the planck function is to be evaluated. TEMP Scalar giving the temperature of the planck function in degree K OUTPUT PARAMETERS: BBFLUX - Scalar or vector giving the planck function at the specified wavelength points. EXAMPLES: To calculate the blackbody flux (i.e. PI*Intensity) in erg/cm^2/s/A for 30,000 K every 100 Angstroms between 2000A and 2900 A IDL> WAVE = 2000 + INDGEN(10)*100 IDL> BBFLUX = PLANCK(WAVE,30000) RESTRICTIONS: Values less than approximately 1E-24 are truncated to 0. PROCEDURE: The wavelength data are converted to cm, and the planck function is calculated for each wavelength point. See Allen (1973), Astrophysical Quantities, section 44 for more information. MODIFICATION HISTORY: Adapted from the IUE RDAF August, 1989 Converted to IDL V5.0 W. Landsman September 1997(See planck.pro)
PLOTERROR
[Previous Routine] [Next Routine] [List of Routines]NAME: PLOTERROR PURPOSE: Plot data points with accompanying X or Y error bars. EXPLANATION: This is a greatly enhanced version of the standard IDL Library routine PLOTERR CALLING SEQUENCE: ploterror, [ x,] y, [xerr], yerr [, TYPE=, /NOHAT, HATLENGTH= , ERRTHICK=, ERRSTYLE=, ERRCOLOR=, NSKIP= ] INPUTS: X = array of abcissae. Y = array of Y values. XERR = array of error bar values (along X) YERR = array of error bar values (along Y) OPTIONAL INPUT KEYWORD PARAMETERS: TYPE = type of plot produced. The possible types are: TYPE = 0 : X Linear - Y Linear (default) TYPE = 1 : X Linear - Y Log TYPE = 2 : X Log - Y Linear TYPE = 3 : X Log - Y Log Actually, if 0 is specified, the XLOG and YLOG keywords are used. If these aren't specified, then a linear-linear plot is produced. This keyword is available to maintain compatibility with the previous version of PLOTERROR. NOHAT = if specified and non-zero, the error bars are drawn without hats. HATLENGTH = the length of the hat lines used to cap the error bars. Defaults to !D.X_VSIZE / 100). ERRTHICK = the thickness of the error bar lines. Defaults to the THICK plotting keyword. ERRSTYLE = the line style to use when drawing the error bars. Uses the same codes as LINESTYLE. ERRCOLOR = scalar integer (0 - !D.N_TABLE) specifying the color to use for the error bars NSKIP = Integer specifying the error bars to be plotted. For example, if NSKIP = 2 then every other error bar is plotted; if NSKIP=3 then every third error bar is plotted. Default is to plot every error bar (NSKIP = 1) RESTRICTIONS: Arrays must not be of type string. There must be enough points to plot. If only three parameters are input, they will be taken as X, Y and YERR respectively. EXAMPLE: Suppose one has X and Y vectors with associated errors XERR and YERR (1) Plot Y vs. X with both X and Y errors and no lines connecting the points IDL> ploterror, x, y, xerr, yerr, psym=3 (2) Like (1) but plot only the Y errors bars and omits "hats" IDL> ploterror, x, y, yerr, psym=3, /NOHAT WARNING: This an enhanced version of the procedure PLOTERR in the standard IDL distribution. It was renamed from PLOTERR to PLOTERROR in June 1998 in the IDL Astronomy Library to avoid conflict with the RSI procedure. PROCEDURE: A plot of X versus Y with error bars drawn from Y - YERR to Y + YERR and optionally from X - XERR to X + XERR is written to the output device MODIFICATION HISTORY: William Thompson Applied Research Corporation July, 1986 DMS, April, 1989 Modified for Unix Michael R. Greason ST Systems May, 1991 Added most of the plotting keywords, put hats on the error bars. K. Venkatakrishna Added option to plot xerr, May, 1992 Michael R. Greason Corrected handling of reversed axes. Aug. 1992 W. Landsman Use _EXTRA keyword July 1995 W. Landsman Plot more than 32767 points Feb 1996 W. Landsman Fix Y scaling when only XRANGE supplied Nov 1996 W. Landsman Added NSKIP keyword Dec 1996 W. Landsman Use XLOG, YLOG instead of XTYPE, YTYPE Jan 1998 W. Landsman Rename to PLOTERROR, OPLOTERROR Jun 1998 W. Landsman Convert to IDL V5.0 Jun 1998(See ploterror.pro)
PLOTHIST
[Previous Routine] [Next Routine] [List of Routines]NAME: PLOTHIST PURPOSE: Plot the histogram of an array with the corresponding abcissa. CALLING SEQUENCE: plothist, arr, xhist, yhist, [, BIN=bin, ... plotting keywords] INPUTS: arr - The array to plot the histogram of. It can include negative values, but non-integral values will be truncated. OPTIONAL OUTPUTS: xhist - X vector used in making the plot ( = lindgen( N_elements(h)) * bin + min(arr) ) yhist - Y vector used in making the plot (= histogram(arr/bin)) OPTIONAL INPUT KEYWORDS: BIN - The size of each bin of the histogram, scalar (not necessarily integral). If not present (or zero), the bin size is set to 1. NOPLOT - If set, will not plot the result. Useful if intention is to only get the xhist and yhist outputs. OVERPLOT - If set, will overplot the data on the current plot. User must take care that only keywords valid for OPLOT are used. PEAK - if non-zero, then the entire histogram is normalized to have a maximum value equal to the value in PEAK. If PEAK is negative, the histogram is inverted. FILL - if set, will plot a filled (rather than line) histogram. The following keywords take effect only if the FILL keyword is set: FCOLOR - color to use for filling the histogram FLINE - if set, will use lines rather than solid color for fill (see the LINE_FILL keyword in the POLYFILL routine) FORIENTATION - angle of lines for fill (see the ORIENTATION keyword in the POLYFILL routine) FPATTERN - the pattern to use for the fill (see the PATTERN keyword in the POLYFILL routine) FSPACING - the spacing of the lines to use in the fill (see the SPACING keyword in the POLYFILL routine) Any input keyword that can be supplied to the PLOT procedure can also be supplied to PLOTHIST. EXAMPLE: Create a vector of 1000 values derived from a gaussian of mean 0, and sigma of 1. Plot the histogram of these value with a bin size of 0.1 IDL> a = randomn(seed,1000) IDL> plothist,a, bin = 0.1 MODIFICATION HISTORY: Written W. Landsman January, 1991 Add inherited keywords W. Landsman March, 1994 Use ROUND instead of NINT W. Landsman August, 1995 Add NoPlot and Overplot keywords. J.Wm.Parker July, 1997 Add Peak keyword. J.Wm.Parker Jan, 1998 Add FILL,FCOLOR,FLINE,FPATTERN,FSPACING keywords. J.Wm.Parker Jan, 1998 Converted to IDL V5.0 W. Landsman 21-Jan-1998(See plothist.pro)
PLOTSYM
[Previous Routine] [Next Routine] [List of Routines]NAME: PLOTSYM PURPOSE: Define useful plotting symbols not in the standard !PSYM definitions. EXPLANATION: After symbol has been defined with PLOTSYM, a plotting command should follow with either PSYM = 8 or !P.PSYM = 8 (see USERSYM) CALLING SEQUENCE: PLOTSYM, PSYM,[ PSIZE, /FILL] INPUTS: PSYM - The following integer values of PSYM will create the corresponding plot symbols 0 - circle 1 - downward arrow (upper limit), base of arrow begins at plot value 2 - upward arrow (lower limt) 3 - 5 pointed star 4 - triangle 5 - upside down triangle 6 - left pointing arrow 7 - right pointing arrow 8 - square Arrows are defined such that their base begins at their origin. OPTIONAL INPUTS: PSIZE - Size of the plotting symbol in multiples of the default size (default PSIZE=1). Does not need to be an integer OPTIONAL INPUT KEYWORD: FILL - Parameter indicating whether to fill the symbol (see USERSYM) The default is 0, unfilled symbol. Does not affect arrows or character symbols. OUTPUTS: None EXAMPLES: Plot Y vs. X with filled stars as the symbol, twice the default size IDL> PLOTSYM, 3 ,2, /FILL ;Plotting symbol is a filled star, ;twice default size IDL> PLOT,X,Y,PSYM=8 ;Set PSYM = 8 to get star symbol Now plot Y vs. X with open circle as the symbol IDL> PLOTSYM, 0 ;Plotting symbol is a circle IDL> PLOT,X,Y,PSYM=8 METHOD: Appropriate X,Y vectors are used to define the symbol and passed to the USERSYM command. REVISION HISTORY Written W. Landsman June 1992 18-JAN-1996 Added a square symbol, HCW. Converted to IDL V5.0 W. Landsman September 1997(See plotsym.pro)
POIDEV
[Previous Routine] [Next Routine] [List of Routines]NAME: POIDEV PURPOSE: Generate a Poisson random deviate EXPLANATION: Return an integer random deviate drawn from a Poisson distribution with a specified mean. Adapted from procedure of the same name in "Numerical Recipes" by Press et al. (1986), Section 7.3 NOTE: This routine became partially obsolete in V5.0 with the introduction of the POISSON keyword to the intrinsic functions RANDOMU and RANDOMN. However, POIDEV is still useful for adding Poisson noise to an image array. CALLING SEQUENCE: result = POIDEV( xm, [ SEED = ] ) INPUTS: xm - numeric scalar or vector, specifying the mean of the Poisson distribution OUTPUT: result - Long integer scalar or vector, same size as xm OPTIONAL KEYWORD INPUT-OUTPUT: SEED - Scalar to be used as the seed for the random distribution. For best results, SEED should be a large (>100) integer. If SEED is undefined, then its value is taken from the system clock (see RANDOMU). The value of SEED is always updated upon output. This keyword can be used to have POIDEV give identical results on consecutive runs. EXAMPLE: (1) Add Poisson noise to an integral image array, im IDL> imnoise = POIDEV( im) (2) Verify the expected mean and sigma for an input value of 81 IDL> p = POIDEV( intarr(10000) + 81) ;Test for 10,000 points IDL> print,avg(p),sigma(p) Average and sigma of the 10000 points should be close to 81 and 9 METHOD: For small values (< 20) independent exponential deviates are generated until their sum exceeds the specfied mean, the number of events required is returned as the Poisson deviate. For large (> 20) values, uniform random variates are compared with a Lorentzian distribution function. NOTES: Negative values in the input array will be returned as zeros. REVISION HISTORY: Version 1 Wayne Landsman July 1992 Added SEED keyword September 1992 Call intrinsic LNGAMMA function November 1994 Converted to IDL V5.0 W. Landsman September 1997(See poidev.pro)
POLINT
[Previous Routine] [Next Routine] [List of Routines]NAME: POLINT PURPOSE: Interpolate a set of N points by fitting a polynomial of degree N-1 EXPLANATION: Adapted from algorithm in Numerical Recipes, Press et al. (1986) Section 3.1. CALLING SEQUENCE POLINT, xa, ya, x, y, [ dy ] INPUTS: XA - X Numeric vector, all values must be distinct. The number of values in XA should rarely exceed 10 (i.e. a 9th order polynomial) YA - Y Numeric vector, same number of elements X - Numeric scalar specifying value to be interpolated OUTPUT: Y - Scalar, interpolated value in (XA,YA) corresponding to X OPTIONAL OUTPUT DY - Error estimate on Y, scalar EXAMPLE: Find sin(2.5) by polynomial interpolation on sin(indgen(10)) IDL> xa = indgen(10) IDL> ya = sin( xa ) IDL> polint, xa, ya, 2.5, y ,dy The above method gives y = .5988 & dy = 3.1e-4 a close approximation to the actual sin(2.5) = .5985 METHOD: Uses Neville's algorithm to iteratively build up the correct polynomial, with each iteration containing one higher order. REVISION HISTORY: Written W. Landsman January, 1992 Converted to IDL V5.0 W. Landsman September 1997(See polint.pro)
POLREC
[Previous Routine] [Next Routine] [List of Routines]NAME: POLREC PURPOSE: Convert 2-d polar coordinates to rectangular coordinates. CATEGORY: CALLING SEQUENCE: polrec, r, a, x, y INPUTS: r, a = vector in polar form: radius, angle (radians). in KEYWORD PARAMETERS: Keywords: /DEGREES means angle is in degrees, else radians. OUTPUTS: x, y = vector in rectangular form. out COMMON BLOCKS: NOTES: MODIFICATION HISTORY: R. Sterner. 18 Aug, 1986. Johns Hopkins University Applied Physics Laboratory. RES 13 Feb, 1991 --- added /degrees. Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory This software may be used, copied, or redistributed as long as it is not sold and this copyright notice is reproduced on each copy made. This routine is provided as is without any express or implied warranties whatsoever. Other limitations apply as described in the file disclaimer.txt. Converted to IDL V5.0 W. Landsman September 1997(See polrec.pro)
POLYLEG
[Previous Routine] [Next Routine] [List of Routines]NAME: POLYLEG PURPOSE: Evaluate a Legendre polynomial with specified coefficients. EXPLANATION: Meant to be used analogously to the POLY function in the IDL User's Library distribution. CALLING SEQUENCE: Result = POLYLEG( X, C ) INPUTS: X - input variable, scalar or vector C - vector of Legendre polynomial coefficients. OUTPUTS: POLYLEG returns a result equal to: C(0) + C(1)*P_1(x) + C(2)*P_2(x) + ... where P_j(x) is the jth Legendre polynomial. The output will have the same dimensions as the input X variable. EXAMPLE: If x = [0.5, 1.0] and C = [2.4, 1.3, 2.5] then print, polyleg(x, c) ====> [2.7375, 6.20] The result can be checked using the first 3 Legendre polynomial terms C(0) + C(1)*x + C(2)*(0.5*(3*x^2-1)) METHOD: Uses the recurrence relation of Legendre polynomials (n+1)*P_n+1(x) = (2n+1)*x*P_n(x) - n*P_n-1(x) evaluated with the Clenshaw recurrence formula, see Numerical Recipes by Press et al. (1992), Section 5.5 REVISION HISTORY: Written W. Landsman Hughes STX Co. April, 1995 Fixed for double precision W. Landsman May, 1997 Converted to IDL V5.0 W. Landsman September 1997(See polyleg.pro)
POLY_SMOOTH
[Previous Routine] [Next Routine] [List of Routines]NAME: POLY_SMOOTH PURPOSE: Apply a least-squares (Savitzky-Golay) polynomial smoothing filter EXPLANATION: Reduce noise in 1-D data (e.g. time-series, spectrum) but retain dynamic range of variations in the data by applying a least squares smoothing polynomial filter, also called the Savitzky-Golay smoothing filter, cf. Numerical Recipes (Press et al. 1992, Sec.14.8) The low-pass filter coefficients are computed by effectively least-squares fitting a polynomial in moving window, centered on each data point, so the new value will be the zero-th coefficient of the polynomial. Approximate first derivates of the data can be computed by using first degree coefficient of each polynomial, and so on. The filter coefficients for a specified polynomial degree and window width are computed independent of any data, and stored in a common block. The filter is then convolved with the data array to result in smoothed data with reduced noise, but retaining higher order variations (better than SMOOTH). CALLING SEQUENCE: spectrum = poly_smooth( data, [ width, DEGREE = , NLEFT = , NRIGHT = DERIV_ORDER = ,COEFF = ] INPUTS: data = 1-D array, such as a spectrum or time-series. width = total number of data points to use in filter convolution, (default = 5, using 2 past and 2 future data points), must be larger than DEGREE of polynomials, and a guideline is to make WIDTH between 1 and 2 times the FWHM of desired features. OPTIONAL INPUT KEYWORDS: DEGREE = degree of polynomials to use in designing the filter via least squares fits, (default DEGREE = 2) The higher degrees will preserve sharper features. NLEFT = # of past data points to use in filter convolution, excluding current point, overrides width parameter, so that width = NLEFT + NRIGHT + 1. (default = NRIGHT) NRIGHT = # of future data points to use (default = NLEFT). DERIV_ORDER = order of derivative desired (default = 0, no derivative). OPTIONAL OUTPUT KEYWORD: COEFFICIENTS = optional output of the filter coefficients applied, but they are all stored in common block for reuse, anyway. RESULTS: Function returns the data convolved with polynomial filter coefs. EXAMPLE: Given a wavelength - flux spectrum (w,f), apply a 31 point quadratic smoothing filter and plot IDL> plot, w, poly_smooth(f,31) COMMON BLOCKS: common poly_smooth, degc, nlc, nrc, coefs, ordermax PROCEDURE: As described in Numerical Recipies, 2nd edition sec.14.8, Savitsky-Golay filter. Matrix of normal eqs. is formed by starting with small terms and then adding progressively larger terms (powers). The filter coefficients of up to derivative ordermax are stored in common, until the specifications change, then recompute coefficients. Coefficients are stored in convolution order, zero lag in the middle. MODIFICATION HISTORY: Written, Frank Varosi NASA/GSFC 1993. Converted to IDL V5.0 W. Landsman September 1997(See poly_smooth.pro)
POSANG
[Previous Routine] [Next Routine] [List of Routines]NAME: POSANG PURPOSE: Computes rigorous position angle of source 2 relative to source 1 EXPLANATION: Computes the rigorous position angle of source 2 (with given RA, Dec) using source 1 (with given RA, Dec) as the center. CALLING SEQUENCE: POSANG, U, RA1, DC1, RA2, DC2, ANGLE INPUTS: U -- Describes units of inputs and output: 0: everything radians 1: RAx in decimal hours, DCx in decimal degrees, ANGLE in degrees RA1 -- Right ascension of point 1 DC1 -- Declination of point 1 RA2 -- Right ascension of point 2 DC2 -- Declination of point 2 OUTPUTS: ANGLE-- Angle of the great circle containing [ra2, dc2] from the meridian containing [ra1, dc1], in the sense north through east rotating about [ra1, dc1]. See U above for units. PROCEDURE: The "four-parts formula" from spherical trig (p. 12 of Smart's Spherical Astronomy or p. 12 of Green' Spherical Astronomy). EXAMPLE: For the star 56 Per, the Hipparcos catalog gives a position of RA = 66.15593384, Dec = 33.94988843 for component A, and RA = 66.15646079, Dec = 33.96100069 for component B. What is the position angle of B relative to A? IDL> RA1 = 66.15593384/15.d & DC1 = 33.95988843 IDL> RA2 = 66.15646079/15.d & DC2 = 33.96100069 IDL> posang,1,ra1,dc1,ra2,dc2, ang will give the answer of ang = 21.4 degrees NOTES: (1) If RA1,DC1 are scalars, and RA2,DC2 are vectors, then ANGLE is a vector giving the position angle between each element of RA2,DC2 and RA1,DC1. Similarly, if RA1,DC1 are vectors, and RA2, DC2 are scalars, then DIS is a vector giving the position angle of each element of RA1, DC1 and RA2, DC2. If both RA1,DC1 and RA2,DC2 are vectors then ANGLE is a vector giving the position angle between each element of RA1,DC1 and the corresponding element of RA2,DC2. If then vectors are not the same length, then excess elements of the longer one will be ignored. (2) Note that POSANG is not commutative -- the position angle between A and B is theta, then the position angle between B and A is 180+theta PROCEDURE CALLS: ISARRAY() HISTORY: Modified from GCIRC, R. S. Hill, RSTX, 1 Apr. 1998(See posang.pro)
POSITIVITY
[Previous Routine] [Next Routine] [List of Routines]NAME: POSITIVITY PURPOSE: Map an image uniquely and smoothly into all positive values. EXPLANATION: Take unconstrained x (usually an image), and map it uniquely and smoothly into positive values. Negative values of x get mapped to interval ( 0, sqrt( epsilon )/2 ], positive values go to ( sqrt( epsilon )/2, oo ) with deriv approaching 1. Derivative is always 1/2 at x=0. Derivative is used by the MRL deconvolution algorithm. CALLING SEQUENCE: result = POSITIVITY( x, [ /DERIVATIVE, EPSILON = ) INPUTS: x - input array, unconstrained OUTPUT: result = output array = ((x + sqrt(x^2 + epsilon))/2 if the /DERIV keyword is set then instead the derivative of the above expression with respect to X is returned OPTIONAL INPUT KEYWORDS: DERIV - if this keyword set, then the derivative of the positivity mapping is returned, rather than the mapping itself EPSILON - real scalar specifying the interval into which to map negative values. If EPSILON EQ 0 then the mapping reduces to positive truncation. If EPSILON LT then the mapping reduces to an identity (no change). Default is EPSILON = 1e-9 REVISION HISTORY: F.Varosi NASA/GSFC 1992, as suggested by R.Pina UCSD. Converted to IDL V5.0 W. Landsman September 1997(See positivity.pro)
PRECESS
[Previous Routine] [Next Routine] [List of Routines]NAME: PRECESS PURPOSE: Precess coordinates from EQUINOX1 to EQUINOX2. EXPLANATION: For interactive display, one can use the procedure ASTRO which calls PRECESS or use the /PRINT keyword. The default (RA,DEC) system is FK5 based on epoch J2000.0 but FK4 based on B1950.0 is available via the /FK4 keyword. CALLING SEQUENCE: PRECESS, ra, dec, [ equinox1, equinox2, /PRINT, /FK4, /RADIAN ] INPUT - OUTPUT: RA - Input right ascension (scalar or vector) in DEGREES, unless the /RADIAN keyword is set DEC - Input declination in DEGREES (scalar or vector), unless the /RADIAN keyword is set The input RA and DEC are modified by PRECESS to give the values after precession. OPTIONAL INPUTS: EQUINOX1 - Original equinox of coordinates, numeric scalar. If omitted, then PRECESS will query for EQUINOX1 and EQUINOX2. EQUINOX2 - Equinox of precessed coordinates. OPTIONAL INPUT KEYWORDS: PRINT - If this keyword is set and non-zero, then the precessed coordinates are displayed at the terminal. Cannot be used with the /RADIAN keyword FK4 - If this keyword is set, the FK4 (B1950.0) system will be used otherwise FK5 (J2000.0) will be used instead. RADIAN - If this keyword is set and non-zero, then the input and output RA and DEC vectors are in radians rather than degrees RESTRICTIONS: Accuracy of precession decreases for declination values near 90 degrees. PRECESS should not be used more than 2.5 centuries from 2000 on the FK5 system (1950.0 on the FK4 system). EXAMPLES: (1) The Pole Star has J2000.0 coordinates (2h, 31m, 46.3s, 89d 15' 50.6"); compute its coordinates at J1985.0 IDL> precess, ten(2,31,46.3)*15, ten(89,15,50.6), 2000, 1985, /PRINT ====> 2h 16m 22.73s, 89d 11' 47.3" (2) Precess the B1950 coordinates of Eps Ind (RA = 21h 59m,33.053s, DEC = (-56d, 59', 33.053") to equinox B1975. IDL> ra = ten(21, 59, 33.053)*15 IDL> dec = ten(-56, 59, 33.053) IDL> precess, ra, dec ,1950, 1975, /fk4 PROCEDURE: Algorithm from Computational Spherical Astronomy by Taff (1983), p. 24. (FK4). FK5 constants from "Astronomical Almanac Explanatory Supplement 1992, page 104 Table 3.211.1. PROCEDURE CALLED: Function PREMAT - computes precession matrix REVISION HISTORY Written, Wayne Landsman, STI Corporation August 1986 Correct negative output RA values February 1989 Added /PRINT keyword W. Landsman November, 1991 Provided FK5 (J2000.0) I. Freedman January 1994 Precession Matrix computation now in PREMAT W. Landsman June 1994 Added /RADIAN keyword W. Landsman June 1997 Converted to IDL V5.0 W. Landsman September 1997(See precess.pro)
PRECESS_CD
[Previous Routine] [Next Routine] [List of Routines]NAME: PRECESS_CD PURPOSE: Precess the CD (coordinate description) matrix from a FITS header EXPLANATION: The CD matrix is precessed from EPOCH1 to EPOCH2. Called by HPRECESS CALLING SEQUENCE: PRECESS_CD, cd, epoch1, epoch2, crval_old, crval_new INPUTS/OUTPUT: CD - 2 x 2 CD (coordinate description) matrix in any units (degrees or radians). CD will altered on output to contain precessed values in the same units. On output CD will always be double precision no matter how input. INPUTS: EPOCH1 - Original equinox of coordinates, scalar (e.g. 1950.0). EPOCH2 - Equinox of precessed coordinates, scalar (e.g. 2000.0) CRVAL_OLD - 2 element vector containing RA and DEC in DEGREES of the reference pixel in the original equinox CRVAL_NEW - 2 elements vector giving CRVAL in the new equinox INPUT KEYWORD: If this keyword is set, then the precession constants are taken in the FK4 reference frame. The default is the FK5 frame. RESTRICTIONS: PRECESS_CD should not be used more than 2.5 centuries from the year 1900. PROCEDURE: Adapted from the STSDAS program FMATPREC. Precession changes the location of the north pole, and thus changes the rotation of an image from north up. This is reflected in the precession of the CD matrix. This is usually a very small change. PROCEDURE CALLS: PRECESS REVISION HISTORY: Written, Wayne Landsman, ST Systems February 1988 Fixed sign error in computation of SINRA March 1992 Added /FK4 keyword Feb 1994 Converted to IDL V5.0 W. Landsman September 1997(See precess_cd.pro)
PREMAT
[Previous Routine] [Next Routine] [List of Routines]NAME: PREMAT PURPOSE: Return the precession matrix needed to go from EQUINOX1 to EQUINOX2. EXPLANTION: This matrix is used by the procedures PRECESS and BARYVEL to precess astronomical coordinates CALLING SEQUENCE: matrix = PREMAT( equinox1, equinox2, [ /FK4 ] ) INPUTS: EQUINOX1 - Original equinox of coordinates, numeric scalar. EQUINOX2 - Equinox of precessed coordinates. OUTPUT: matrix - double precision 3 x 3 precession matrix, used to precess equatorial rectangular coordinates OPTIONAL INPUT KEYWORDS: FK4 - If this keyword is set, the FK4 (B1950.0) system precession angles are used to compute the precession matrix. The default is to use FK5 (J2000.0) precession angles EXAMPLES: Return the precession matrix from 1950.0 to 1975.0 in the FK4 system IDL> matrix = PREMAT( 1950.0, 1975.0, /FK4) PROCEDURE: FK4 constants from "Computational Spherical Astronomy" by Taff (1983), p. 24. (FK4). FK5 constants from "Astronomical Almanac Explanatory Supplement 1992, page 104 Table 3.211.1. REVISION HISTORY Written, Wayne Landsman, HSTX Corporation, June 1994 Converted to IDL V5.0 W. Landsman September 1997(See premat.pro)
PRINT_STRUCT
[Previous Routine] [Next Routine] [List of Routines]NAME: PRINT_STRUCT PURPOSE: Print the tag values of an array of structures in nice column format. EXPLANATION: The tag names are displayed in a header line. CALLING SEQUENCE: print_struct, structure, Tags_to_print [ , title, string_matrix ] INPUTS: structure = array of structured variables Tags_to_print = string array specifying the names of tags to print. Default is to print all tags which are not arrays. OPTIONAL INPUT KEYWORDS: FILE = string, optional file name to which output will then be written. LUN_OUT = Logical unit number for output to an open file, default is to print to standard output. TNUMS = tag numbers to print (alternative to specifying tag names). TRANGE = [beg,end] tag number range to print. FRANGE = same as TRANGE. WHICH = optional array of subscripts to select which structure elements to print. FORM_FLOAT = string array of three elements specifying floating point format, ex: FORM=['f','9','2'] means "(F9.2)", (default float format is G12.4). MAX_ELEMENTS = positive integer, print only tags that have less than this number of elements (default is no screening). /STRINGS : instead of printing, return the array of strings in fourth argument of procedure: string_matrix. OUTPUTS: title = optional string, list of tags printed/processed. string_matrix = optional output of string matrix of tag values, instead of printing to terminal or file, if /STRINGS. EXTERNAL CALLS: function N_struct PROCEDURE: Check the types and lengths of fields to decide formats, then loop and form text string from requested fields, then print. HISTORY: Written: Frank Varosi NASA/GSFC 1991. F.V.1993, fixed up the print formats. F.V.1994, added more keyword options. F.V.1997, added WHICH and MAX_ELEM keyword options. WBL 1997, Use UNIQ() rather than UNIQUE function Converted to IDL V5.0 W. Landsman September 1997(See print_struct.pro)
PROB_KS
[Previous Routine] [Next Routine] [List of Routines]NAME: PROB_KS PURPOSE: Return the significance of the Kolmogoroff-Smirnov statistic EXPLANATION: Returns the significance level of an observed value of the Kolmogorov-Smirnov statistic D for an effective number of data points N_eff. Called by KSONE and KSTWO CALLING SEQUENCE: prob_ks, D, N_eff, probks INPUT PARAMATERS: D - Kolmogorov statistic, floating scalar, always non-negative N_eff - Effective number of data points, scalar. For a 2 sided test this is given by (N1*N2)/(N1+N2) where N1 and N2 are the number of points in each data set. OUTPUT PARAMETERS: probks - floating scalar between 0 and 1 giving the significance level of the K-S statistic. Small values of PROB suggest that the distribution being tested are not the same REVISION HISTORY: Written W. Landsman August, 1992 Corrected typo (termbv for termbf) H. Ebeling/W.Landsman March 1996 Probably did not affect numeric result, but iteration went longer than necessary Converted to IDL V5.0 W. Landsman September 1997(See prob_ks.pro)
PRODUCT
[Previous Routine] [Next Routine] [List of Routines]NAME: PRODUCT PURPOSE: Calculates the product of all the elements of an array EXPLANATION: PRODUCT() is the multiplicative equivalent of TOTAL(). CALLING SEQUENCE: Result = PRODUCT(ARRAY) INPUT PARAMETERS: ARRAY = Array of elements to multiply together. For instance, ARRAY could contain the dimensions of another array--then PRODUCT(ARRAY) would be the total number of elements of that other array. OUTPUT: The result of the function is the total product of all the elements of ARRAY. OPTIONAL KEYWORD PARAMETERS: None. COMMON BLOCKS: None. SIDE EFFECTS: The result will always be of at least floating point type. RESTRICTIONS: ARRAY must be a numerical type. PROCEDURE: Straightforward. MODIFICATION HISTORY: William Thompson, Feb. 1992. Converted to IDL V5.0 W. Landsman September 1997(See product.pro)
PSF_GAUSSIAN
[Previous Routine] [Next Routine] [List of Routines]NAME: PSF_GAUSSIAN PURPOSE: Create a 1-d, 2-d, or 3-d Gaussian with specified FWHM, center EXPLANATION: Return a point spread function having Gaussian profiles, as either a 1D vector, a 2D image, or 3D volumetric-data. CALLING SEQUENCE: psf = psf_Gaussian( NPIXEL=, FWHM= , [/NORMALIZE, /ST_DEV, ) or: psf = psf_Gaussian( parameters, NPIXEL = ) REQUIRED INPUT KEYWORD: NPIXEL = number pixels for each dimension, specify as an array, or just one number to make all sizes equal. OPTIONAL KEYWORDS: NDIMEN = dimension of result: 1 (vector), 2 (image), or 3 (volume), default = 2 (an image result). FWHM = the desired Full-Width Half-Max (pixels) in each dimension, specify as an array, or single number to make all the same. CENTROID = pixels numbers of PSF maximum ( 0.5 is center of a pixel ), default is exact center of requested vector/image/volume. STDEV = optional way to specify width by standard deviation param. XY_CORREL = scalar between 0 and 1 specifying correlation coefficient Use this keyword, for example, to specify an elliptical gaussian oriented at an angle to the X,Y axis /NORMALIZE causes resulting PSF to be normalized so Total( psf ) = 1. INPUTS (optional): parameters = an NDIMEN by 3 array giving for each dimension: [ maxval, center, stdev ], overrides other keywords. EXAMPLE: Create a 31 x 31 array containing a normalized centered gaussian with an X FWHM = 4.3 and a Y FWHM = 3.6 IDL> array = PSF_GAUSSIAN( Npixel=31, FWHM=[4.3,3.6], /NORMAL EXTERNAL CALLS: function Gaussian HISTORY: Written, Frank Varosi NASA/GSFC 1991. Converted to IDL V5.0 W. Landsman September 1997(See psf_gaussian.pro)
PUTAST
[Previous Routine] [Next Routine] [List of Routines]NAME: PUTAST PURPOSE: Put astrometry parameters into a given FITS header. CALLING SEQUENCE: putast, hdr, astr, [EQUINOX =, CD_TYPE = ] or putast, hdr, cd,[ crpix, crval], [ EQUINOX =, CD_TYPE = ] INPUTS: HDR - FITS header, string array. HDR will be updated to contain the supplied astrometry. ASTR - IDL structure containing values of the astrometry parameters CDELT, CRPIX, CRVAL, CTYPE, LONGPOLE, PROJP1, and PROJP2 See EXTAST.PRO for more info about the structure definition or CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2 CD2_1 CD2_2 in units of DEGREES/PIXEL CRPIX - 2 element vector giving X and Y coord of reference pixel BE SURE THE COORDINATES IN CRPIX ARE GIVEN IN FORTRAN STANDARD (e.g. FIRST PIXEL IN IMAGE IS (1,1) ) CRVAL - 2 element vector giving R.A. and DEC of reference pixel in degrees OUTPUTS: HDR - FITS header now contains the updated astrometry parameters A brief HISTORY record is also added. OPTIONAL KEYWORD INPUTS: EQUINOX - numeric scalar giving equinox (e.g. 2000) of the reference coordinates CD_TYPE - Scalar, either 0, 1 , or 2 specifying how the CD matrix is to be written into the header (0) as CD00n00m values (1) convert to rotation and write as a CROTA2 value (2) as CDn_m value As of September 1997, there is still no general agreement on the notation to use for the CD matrix; however form (0) will almost certainly not be used. In addition, since form (2) is used for HST images, it almost certainly will be supported in the future. The document "Representations of Celestial Coordinates in FITS" by Griesen and Calabretta at http://www.cv.nrao.edu/fits/documents/wcs/wcs.html discusses these issues but note this is only a draft. If CD_TYPE is not supplied, PUTAST will try to determine the type of astrometry already in the header. If there is no astrometry in the header then the default is CD_TYPE = 2 NOTES: The recommended use of this procedure is to supply an astrometry structure. PROMPTS: If only a header is supplied, the user will be prompted for a plate scale, the X and Y coordinates of a reference pixel, the RA and DEC of the reference pixel, the equinox of the RA and Dec and a rotation angle. PROCEDURES USED: DATATYPE(), GET_COORDS, SXADDPAR, SXPAR(), ZPARCHECK REVISION HISTORY: Written by W. Landsman 9-3-87 Major rewrite, use new astrometry structure March, 1994 Use both CD and CDELT to get plate scale for CD_TYPE=1 September 1995 Use lower case for FITS keyword Comments W.L. March 1997 Fixed for CD_TYPE=1 and CDELT = [1.0,1.0] W.L September 1997 Default value of CD_TYPE is now 2, Use GET_COORDS to read coordinates to correct -0 problem W.L. September 1997 Update CROTA1 if it already exists W.L. October 1997 Convert rotation to degrees for CD_TYPE = 1 W. L. June 1998 Convert to IDL V5.0 W.L. June 1998(See putast.pro)
QDCB_GRID
[Previous Routine] [Next Routine] [List of Routines]NAME: QDCB_GRID PURPOSE: Produce an overlay of latitude and longitude lines over a plot or image EXPLANATION: Grid is plotted on the current graphics device assuming that the current plot is a map in the so called quad cube projection. The output plot range is assumed to go from 7.0 to -1.0 on the X axis and -3.0 to 3.0 on the Y axis. Within this plotting space, the quad cube faces are laid out as follows (X=Empty, Astronomical Layout shown - X axis can be swapped for geographic maps): 3.0_ XXX0 4321 -3.0_XXX5 | | 7.0 -1.0 CATEGORY: Mapping Support Routine CALLING SEQUENCE: QDCB_GRID,[,DLONG,DLAT,[LINESTYLE=N,/LABELS] INPUT PARAMETERS: DLONG = Optional input longitude line spacing in degrees. If left out, defaults to 30. DLAT = Optional input lattitude line spacing in degrees. If left out, defaults to 30. OPTIONAL KEYWORD PARAMETERS: LINESTYLE = Optional input integer specifying the linestyle to use for drawing the grid lines. LABELS = Optional keyword specifying that the lattitude and longitude lines on the prime meridian and the equator should be labeled in degrees. If LABELS is given a value of 2, i.e. LABELS=2, then the longitude labels will be in hours and minutes instead of degrees. OUTPUT PARAMETERS: NONE PROCEDURE: Uses WCSSPH2XY.PRO with projection 23 ("QSC" - COBE Quadrilatieralized Spherical Cube) to compute positions of grid lines and labels. COPYRIGHT NOTICE: Copyright 1991, The Regents of the University of California. This software was produced under U.S. Government contract (W-7405-ENG-36) by Los Alamos National Laboratory, which is operated by the University of California for the U.S. Department of Energy. The U.S. Government is licensed to use, reproduce, and distribute this software. Neither the Government nor the University makes any warranty, express or implied, or assumes any liability or responsibility for the use of this software. AUTHOR: Jeff Bloch MODIFICATIONS/REVISION LEVEL: %I% %G% Use WCSSPH2XY instead of QDCB Wayne Landsman December 1994 Converted to IDL V5.0 W. Landsman September 1997(See qdcb_grid.pro)
QGET_STRING
[Previous Routine] [Next Routine] [List of Routines]NAME: QGET_STRING PURPOSE: To get a string from the keyboard without echoing it to the screen. CALLING SEQUENCE: string = QGET_STRING() INPUTS: None. OUTPUTS: string The string read from the keyboard. SIDE EFFECTS: A string variable is created and filled. PROCEDURE: The IDL GET_KBRD functions is used to get each character in the string. Each character is added to the string until a carriage return is struck. The carriage return is not appended to the string. Striking the delete key or the backspace key removes the previous character from the string (only the backspace key will work in VMS IDL). PROCEDURES CALLED: MODIFICATION HISTORY: Written by Michael R. Greason, STX, 8 January 1991. Work for Mac and Windows IDL W. Landsman September 1995 Converted to IDL V5.0 W. Landsman September 1997(See qget_string.pro)
QSIMP
[Previous Routine] [Next Routine] [List of Routines]NAME: QSIMP PURPOSE: Integrate using Simpson's rule to specified accuracy. EXPLANATION: Integrate a function to specified accuracy using the extended trapezoidal rule. Adapted from algorithm in Numerical Recipes, by Press et al. (1992, 2nd edition), Section 4.2. This procedure became partly obsolete in IDL V3.5 with the introduction of the intrinsic function QSIMP(), but see notes below. CALLING SEQUENCE: QSIMP, func, A, B, S, [ EPS = , MAX_ITER = ] INPUTS: func - scalar string giving name of function of one variable to be integrated A,B - numeric scalars giving the lower and upper bound of the integration OUTPUTS: S - Scalar giving the approximation to the integral of the specified function between A and B. OPTIONAL KEYWORD PARAMETERS: EPS - scalar specifying the fractional accuracy before ending the iteration. Default = 1E-6 MAX_ITER - Integer specifying the total number iterations at which QSIMP will terminate even if the specified accuracy has not yet been met. The maximum number of function evaluations will be 2^(MAX_ITER). Default value is MAX_ITER = 20 NOTES: (1) The function QTRAP is robust way of doing integrals that are not very smooth. However, if the function has a continuous 3rd derivative then QSIMP will likely be more efficient at performing the integral. (2) QSIMP can be much faster than the intrinsic QSIMP() function (as of IDL V5.1). This is because the intrinisc QSIMP() function only requires that the user supplied function accept a *scalar* variable. Thus on the the 16th iteration, the intrinsic QSIMP() makes 32,767 calls to the user function, whereas this procedure makes one call with a 32,767 element vector. (3) Since the intrinsic QSIMP is a function, and this file contains a procedure, there should be no name conflict. EXAMPLE: Compute the integral of sin(x) from 0 to !PI/3. IDL> QSIMP, 'sin', 0, !PI/3, S & print, S The value obtained should be cos(!PI/3) = 0.5 PROCEDURES CALLED: TRAPZD, ZPARCHECK REVISION HISTORY: W. Landsman ST Systems Co. August, 1991 Continue after max iter warning message W. Landsman March, 1996 Converted to IDL V5.0 W. Landsman September 1997(See qsimp.pro)
QTRAP
[Previous Routine] [Next Routine] [List of Routines]NAME: QTRAP PURPOSE: Integrate using trapezoidal rule to specified accuracy. EXPLANATION: Integrate a function to specified accuracy using the extended trapezoidal rule. Adapted from Numerical Recipes (1992, 2nd edition), Section 4.2. CALLING SEQUENCE: QTRAP, func, A, B, S, [EPS = , MAX_ITER = ] INPUTS: func - scalar string giving name of function of one variable to be integrated A,B - numeric scalars giving the lower and upper bound of the integration OUTPUTS: S - Scalar giving the approximation to the integral of the specified function between A and B. OPTIONAL KEYWORD PARAMETERS: EPS - scalar specify the fractional accuracy before ending the iteration. Default = 1E-6 MAX_ITER - Integer specifying the total number iterations at which QTRAP will terminate even if the specified accuracy has not yet been met. The maximum number of function evaluations will be 2^(MAX_ITER). Default value is MAX_ITER = 20 NOTES: QTRAP is robust way of doing integrals that are not very smooth. If the function has a continuous 3rd derivative then the function QSIMP will likely be more efficient at performing the integral. EXAMPLE: Compute the integral of sin(x) from 0 to !PI/3. IDL> QTRAP, 'sin', 0, !PI/3, S & print,S The value obtained should be cos(!PI/3) = 0.5 PROCEDURES CALLED: TRAPZD, ZPARCHECK REVISION HISTORY: W. Landsman ST Systems Co. August, 1991 Continue after Max Iter warning message, W. Landsman March 1996 Converted to IDL V5.0 W. Landsman September 1997(See qtrap.pro)
QUADTERP
[Previous Routine] [Next Routine] [List of Routines]NAME: QUADTERP PURPOSE: Quadratic interpolation of X,Y vectors onto a new X grid EXPLANATION: Quadratically interpolate (3 point Lagrangian) a function Y = f(X) at specified grid points. Use LINTERP for linear interpolation CALLING SEQUENCE: QUADTERP, Xtab, Ytab, Xint, Yint, [ MISSING = ] INPUT: Xtab - Vector (X TABle) containing the current independent variable Must be either monotonic increasing or decreasing Ytab - Vector (Y TABle) containing the dependent variable defined at each of the points of XTAB. Xint - Scalar or vector giving the values of X for which interpolated Y values are sought OUTPUT: Yint - Interpolated value(s) of Y, same number of points as Xint OPTIONAL INPUT KEYWORD: MISSING - Scalar specifying Yint value(s) to be assigned, when Xint value(s) are outside of the range of Xtab. Default is to truncate the out of range Yint value(s) to the nearest value of Ytab. See the help for the INTERPOLATE function. METHOD: 3-point Lagrangian interpolation. The average of the two quadratics derived from the four nearest points is returned in YTAB. A single quadratic is used near the end points. The procedure TABINV is used to locate center point of the interpolation. RESTRICTIONS: Unless MISSING keyword is set, points outside the range of Xtab in which valid quadratics can be computed are returned at the value of the nearest end point of Ytab (i.e. Ytab(0) and Ytab(NPTS-1) ). EXAMPLE: A spectrum has been defined using a wavelength vector WAVE and a flux vector FLUX. Interpolate onto a new wavelength grid, e.g. IDL> wgrid = [1540.,1541.,1542.,1543.,1544.,1545.] IDL> quadterp, wave, flux, wgrid, fgrid FGRID will be a 5 element vector containing the quadratically interpolated values of FLUX at the wavelengths given in WGRID. EXTERNAL ROUTINES: TABINV, ZPARCHECK, DATATYPE() REVISION HISTORY: 31 October 1986 by B. Boothman, adapted from the IUE RDAF 12 December 1988 J. Murthy, corrected error in Xint September 1992, W. Landsman, fixed problem with double precision August 1993, W. Landsman, added MISSING keyword June, 1995, W. Landsman, use single quadratic near end points Converted to IDL V5.0 W. Landsman September 1997(See quadterp.pro)
RADEC
[Previous Routine] [Next Routine] [List of Routines]NAME: RADEC PURPOSE: To convert RA and Dec from decimal to sexigesimal units. EXPLANATION: The conversion is to sexigesimal hours for RA, and sexigesimal degrees for declination. CALLING SEQUENCE: radec, ra, dec, ihr, imin, xsec, ideg, imn, xsc INPUTS: ra - right ascension in decimal DEGREES, scalar or vector dec - declination in decimal DEGREES, scalar or vector, same number of elements as RA OUTPUTS: ihr - right ascension hours (INTEGER*2) imin - right ascension minutes (INTEGER*2) xsec - right ascension seconds (REAL*4 or REAL*8) ideg - declination degrees (INTEGER*2) imn - declination minutes (INTEGER*2) xsc - declination seconds (REAL*4 or REAL*8) RESTRICTIONS: RADEC does minimal parameter checking. REVISON HISTORY: Written by B. Pfarr, STX, 4/24/87 Converted to IDL V5.0 W. Landsman September 1997(See radec.pro)
RANDOMP
[Previous Routine] [Next Routine] [List of Routines]NAME: RANDOMP PURPOSE: Generates an array of random numbers distributed as a power law. CALLING SEQUENCE: RANDOMP, X, Pow, N, [ RANGE_X = [low,high], SEED= ]' INPUTS: Pow: Exponent of power law. The pdf of X is f_X(x) = A*x^pow, low <= x <= high ASTRONOMERS PLEASE NOTE: pow is little gamma = big gamma - 1 for stellar IMFs. N: Number of elements in generated vector. OPTIONAL INPUT KEYWORD PARAMETER: RANGE_X: 2-element vector [low,high] specifying the range of output X values; the default is [5, 100]. OPTIONAL INPUT-OUTPUT KEYWORD PARAMETER: SEED: Seed value for RANDOMU function. As described in the documentation for RANDOMU, the value of SEED is updated on each call to RANDOMP, and taken from the system clock if not supplied. This keyword can be used to have RANDOMP give identical results on different runs. OUTPUTS: X: Vector of random numbers, distributed as a power law between specified range PROCEDURE: "Transformation Method" for random variables is described in Bevington & Robinson, "Data Reduction & Error Analysis for Physical Sciences", 2nd Edition (McGraw-Hill, 1992). p. 83. Output of RANDOMU function is transformed to power-law random variable. EXAMPLE: Create a stellar initial mass function (IMF) with 10000 stars ranging from 0.5 to 100 solar masses and a Salpeter slope. Enter: RANDOMP,MASS,-2.35,10000,RANGE_X=[0.5,100] MODIFICATION HISTORY: Written by R. S. Hill, Hughes STX, July 13, 1995 July 14, 1995 SEED keyword added at Landsman's suggestion. Documentation converted to standard format. RSH Converted to IDL V5.0 W. Landsman September 1997(See randomp.pro)
RDFITS_STRUCT
[Previous Routine] [Next Routine] [List of Routines]NAME: RDFITS_STRUCT PURPOSE: Read an entire FITS file (all extensions) into a single IDL structure. EXPLANATION: Each header, image or table array is placed in a separate structure tag. CALLING SEQUENCE: RDFITS_STRUCT, filename, struct, [ /NODELETE, /SILENT ] INPUT: FILENAME = Scalar string giving the name of the FITS file OPTIONAL KEYWORD: NODELETE - RDFITS_STRUCT creates a temporary file with the name temp_'fitsname'.pro which contains the IDL structure definition Normally, this temporary file is deleted -- set the /NODELETE keyword to keep it. SILENT - Set this keyword to suppress informational displays at the terminal. OUTPUT: struct = structure into which FITS data is read. The primary header and image are placed into tag names HDR0 and IM0. Any extensions are placed into the tag names HDRi, TABi PROCEDURES USED: FDECOMP, FITS_INFO, HEADFITS(), GETTOK(), READFITS(), STRN() METHOD: The procedure FITS_INFO is used to determine whether a primary image exists and the number of extensions. The number and type of structure tags required is written to a temporary file and assigned to an appropiate HEADFITS or READFITS call. The temporary file is executed using CALL_PROCEDURE. EXAMPLE: Read the FITS file 'm33.fits' into an IDL structure, st IDL> rdfits_struct, 'm33.fits', st IDL> help, /str, st ;Display info about the structure RESTRICTIONS: The current algorithm is not particularly efficient. The user must delete the temporary file under MacOS. Does not handle random groups or variable length binary tables MODIFICATION HISTORY: Written K. Venkatakrishna, STX April 1992 Code cleaned up a bit W. Landsman STX October 92 Modified for MacOS I. Freedman HSTX April 1994 Work under Windows 95 W. Landsman HSTX January 1996 Use anonymous structures, skip extensions without data WBL April 1998 Converted to IDL V5.0, W. Landsman, April 1998(See rdfits_struct.pro)
RDFLOAT
[Previous Routine] [Next Routine] [List of Routines]NAME: RDFLOAT PURPOSE: Quickly read a numeric ASCII data file into IDL floating pt. vectors. EXPLANATION: Columns of data may be separated by commas or spaces. This program is fast but is restricted to data files where all columns can be read as floating point (or all double precision). Use READCOL if greater flexibility is desired. Use READFMT to read a fixed-format ASCII file. CALLING SEQUENCE: RDFLOAT, name, v1, [ v2, v3, v4, v5, ... v19] /DOUBLE, SKIPLINE = , NUMLINE = ] INPUTS: NAME - Name of ASCII data file, scalar string. In VMS, an extension of .DAT is assumed, if not supplied. OPTIONAL INPUT KEYWORDS: SKIPLINE - Scalar specifying number of lines to skip at the top of file before reading. Default is to start at the first line. NUMLINE - Scalar specifying number of lines in the file to read. Default is to read the entire file DOUBLE - If this keyword is set, then all variables are read in as double precision. OUTPUTS: V1,V2,V3,...V19 - IDL vectors to contain columns of data. Up to 19 columns may be read. All output vectors are of type float, unless the /DOUBLE keyword is set, EXAMPLES: Each row in a file POSITION.DAT contains a star number and 6 columns of data giving an RA and Dec in sexigesimal format. Read into IDL variables. IDL> rdfloat,'POSITION',ID,hr,min,sec,deg,dmin,dsec All output vectors will be floating point RESTRICTIONS: (1) All rows in the file must be formatted identically (except for those skipped by SKIPLINE). RDFLOAT reads the first line of the data (after SKIPLINE) to determine the number of columns of data. (2) Cannot be used to read strings PROCEDURES USED: STR_SEP(), NUMLINES() REVISION HISTORY: Written W. Landsman September 1995 Call NUMLINES() function February 1996 Read up to 19 columns August 1997 Converted to IDL V5.0 W. Landsman September 1997(See rdfloat.pro)
RDPLOT
[Previous Routine] [Next Routine] [List of Routines]NAME: RDPLOT PURPOSE: Like CURSOR but with a full-screen cursor and continuous readout option EXPLANATION: This program is designed to essentially mimic the IDL CURSOR command, but with the additional options of continuously printing out the data values of the cursor's position, and using a full-screen cursor rather than a small cross cursor. The Full screen cursor uses OPLOT and X-windows graphics masking to emulate the cursor. One difference is that IF the PRINT keyword is set but the DOWN, WAIT, or CHANGE keywords are not set, then the leftmost mouse button will print a "newline" line-feed, but not exit. CALLING SEQUENCE: RDPLOT, [X, Y, WaitFlag], [/DATA, /DEVICE, /NORMAL, /NOWAIT, /WAIT, /DOWN, /CHANGE, ERR=, PRINT=, XTITLE=, YTITLE=, XVALUES=, YVALUES=, /FULLCURSOR, /NOCLIP, LINESTYLE=, THICK=, COLOR=, /CROSS] REQUIRED INPUTS: None. OPTIONAL INPUTS: WAITFLAG = Uses the same table as the intrinsic CURSOR command, But note that unlike the CURSOR command, there is no UP keyword. WaitFlag=0 sets the NOWAIT keyword WaitFlag=1 sets the WAIT keyword {default} WaitFlag=2 sets the CHANGE keyword WaitFlag=3 sets the DOWN keyword OPTIONAL KEYWORD PARAMETERS: DATA = Data coordinates are displayed and returned. DEVICE = device coordinates are displayed and returned. NORMAL = normal coordinates are displayed and returned. NOWAIT = if non-zero the routine will immediately return the cursor's present position. WAIT = if non-zero will wait for a mouse key click before returning. If cursor key is already down, then procedure immediately exits. DOWN = equivalent to WAIT *except* that if the mouse key is already down when the procedure is called, the procedure will wait until the mouse key is clicked down again. CHANGE = returns when the mouse is moved OR a key is clicked up or down. ERR = returns the most recent value of the !Err value. PRINT = if non-zero will continuously print out the data values of the cursor's position. If PRINT>1, program will printout a brief header describing the mouse button functions. However, note that the button functions are overridden if any of the DOWN, WAIT, mouse or CHANGE values are non-zero. XTITLE = label used to describe the values of the abscissa if PRINT>0. YTITLE = label used to describe the values of the ordinate if PRINT>0. XVALUES = a vector corresponding to the values to be printed when the PRINT keyword is set. This allows the user the option of printing out other values rather than the default X coordinate position of the cursor. E.g., if XVALUES is a string vector of dates such as ['May 1', 'May 2', ...], then those dates will be printed rather than the X value of the cursor's position: if X=1 then 'May 2' would be printed, etc. This requires that the values of the X coordinate read by the cursor must be positive (can't access negative elements). If XVALUES=-1, then NO values for X will be printed. YVALUES = analagous to the XVALUES keyword. FULLCURSOR = if non-zero default cursor is blanked out and full-screen (or full plot window, depending on the value of NOCLIP) lines are drawn; their intersecton is centered on the cursor position. NOCLIP = if non-zero will make a full-screen cursor, otherwise it will default to the value in !P.NOCLIP. LINESTYLE = style of line that makes the full-screen cursor. THICK = thickness of the line that makes the full-screen cursor. COLOR = color of the full-screen cursor. CROSS = if non-zero will show the regular cross AND full screen cursors. NOTES: Note that this procedure does not allow the "UP" keyword/flag...which doesn't seem to work too well in the origianl CURSOR version anyway. If a data coordinate system has not been established, then RDPLOT will create one identical to the device coordinate system. Note that this kluge is required even if the user specified /NORMAL coordinates, since RDPLOT makes use of the OPLOT procedure. This new data coordinate system is effectively "erased" (!X.CRange and !Y.CRange are both set to zero) upon exit of the routine so as to not change the plot status from the user's point of view. Only tested on X-windows systems. If this program is interrupted, the graphics function might be left in a non-standard state; in that case, run the program RESET_RDPLOT to return the standard graphics functions, or type the command: DEVICE, /CURSOR_CROSS, SET_GRAPHICS=3, BYPASS=0 BUGS: It is assumed that the current background of the plot is correctly defined by the value in !P.Background. Otherwise, the color of the long cursor probably will not be correct. Sometimes the color doesn't work anyway, and I'm not sure why. There may be some cases (e.g., when THICK>1 and NOCLIP=0) when the full-screen cursor is not correctly erased, leaving "ghost images" on the plot. It just seems that the screen updates get slow or the positions ambiguous with a thick line and the cursor off the plot. PROCEDURE: Basically is a bells-n-whistles version of the CURSOR procedure. All the details are covered in the above discussion of the keywords. EXAMPLE (a silly, but informative one): Months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', $ 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'] plot, indgen(12), xrange=[-5, 15] rdplot, /FULL, /PRINT, XTITLE='Month: ', YTITLE='Y-value per month = ', $ xvalues=Months MODIFICATION HISTORY: Written (originally named CURFULL) by J.Wm.Parker 1993 Nov 22 Created data coordinates if not already present, W. Landsman Nov. 93 Added continuous printout of data values, COLOR and FULLCURSOR keywords (so that default is that it acts just like the cursor command). Changed name from CURFULL to RDPLOT. J.Wm.Parker 1994 Apr 20 Modified (with some translation table assistance from the IDL support group) to correctly plot the crosshair with the desired IDL color using the device's translation table to determine the XOR function and using the BYPASS function. Added the RESET_RDPLOT procedure to cleanup crashes that might occur while running RDPLOT. Other minor changes/bug fixes. J.Wm.Parker 1994 May 21 Modified DOWN, WAIT, CHANGE functions to behave more similar to the generic CURSOR procedure. J.Wm.Parker 1995 April 24 Added XVALUES, YVALUES keywords and cleanup. J.Wm.Parker 1995 April 24 Convert to IDL V5.0, W. Landsman July 1998(See rdplot.pro)
RDPSF
[Previous Routine] [Next Routine] [List of Routines]NAME: RDPSF PURPOSE: Read the FITS file created by GETPSF in the DAOPHOT sequence EXPLANATION: Combines the Gaussian with the residuals to create an output PSF array. CALLING SEQUENCE: RDPSF, PSF, HPSF, [ PSFNAME] OPTIONAL INPUTS psfname - string giving the name of the FITS file containing the PSF residuals OUTPUTS psf - array containing the actual PSF hpsf - header associated with psf PROCEDURES CALLED: DAO_VALUE(), MAKE_2D, SXADDPAR, READFITS(), SXPAR() REVISION HISTORY: Written W. Landsman December, 1988 Checked for IDL Version 2, J. Isensee & J. Hill, December, 1990 Converted to IDL V5.0 W. Landsman September 1997(See rdpsf.pro)
READCOL
[Previous Routine] [Next Routine] [List of Routines]NAME: READCOL PURPOSE: Read a free-format ASCII file with columns of data into IDL vectors EXPLANATION: Lines of data not meeting the specified format (e.g. comments) are ignored. Columns may be separated by commas or spaces. Use READFMT to read a fixed-format ASCII file. Use RDFLOAT for much faster I/O (but less flexibility). CALLING SEQUENCE: READCOL, name, v1, [ v2, v3, v4, v5, ... v25 , FORMAT = , /DEBUG , /SILENT , SKIPLINE = , NUMLINE = ] INPUTS: NAME - Name of ASCII data file, scalar string. In VMS, an extension of .DAT is assumed, if not supplied. OPTIONAL INPUT KEYWORDS: FORMAT - scalar string containing a letter specifying an IDL type for each column of data to be read. Allowed letters are A - string data, B - byte, D - double precision, F- floating point, I - integer, L - longword, and X - skip a column. Columns without a specified format are assumed to be floating point. Examples of valid values of FMT are 'A,B,I' ;First column to read as 6 character string, then 1 column of byte data, 1 column integer data 'L,L,L,L' ;Four columns will be read as longword arrays. ' ' ;All columns are floating point If a FORMAT keyword string is not supplied, then all columns are assumed to be floating point. SILENT - Normally, READCOL will display each line that it skips over. If SILENT is set and non-zero then these messages will be suppressed. DEBUG - If this keyword is non-zero, then additional information is printed as READCOL attempts to read and interpret the file. SKIPLINE - Scalar specifying number of lines to skip at the top of file before reading. Default is to start at the first line. NUMLINE - Scalar specifying number of lines in the file to read. Default is to read the entire file OUTPUTS: V1,V2,V3,...V25 - IDL vectors to contain columns of data. Up to 25 columns may be read. The type of the output vectors are as specified by FORMAT. EXAMPLES: Each row in a file POSITION.DAT contains a star name and 6 columns of data giving an RA and Dec in sexigesimal format. Read into IDL variables. (NOTE: The star names must not contain internal spaces.) IDL> FMT = 'A,I,I,F,I,I,F' IDL> READCOL,'POSITION',F=FMT,name,hr,min,sec,deg,dmin,dsec The HR,MIN,DEG, and DMIN variables will be integer vectors. Alternatively, all except the first column could be specified as floating point. IDL> READCOL,'POSITION',F='A',name,hr,min,sec,deg,dmin,dsec To read just the variables HR,MIN,SEC IDL> READCOL,'POSITION',F='X,I,I,F',HR,MIN,SEC RESTRICTIONS: This procedure is designed for generality and not for speed. If a large ASCII file is to be read repeatedly, it may be worth writing a specialized reader. Columns to be read as strings must not contain spaces or commas, since these are interpreted as column delimiters. Use READFMT to read such files. Numeric values are converted to specified format. For example, the value 0.13 read with an 'I' format will be converted to 0. PROCEDURES CALLED GETTOK(), NUMLINES(), REPCHR(), STRNUMBER(), ZPARCHECK REVISION HISTORY: Written W. Landsman November, 1988 Modified J. Bloch June, 1991 (Fixed problem with over allocation of logical units.) Added SKIPLINE and NUMLINE keywords W. Landsman March 92 Read a maximum of 25 cols. Joan Isensee, Hughes STX Corp., 15-SEP-93. Call NUMLINES() function W. Lansdman Feb. 1996 Converted to IDL V5.0 W. Landsman September 1997(See readcol.pro)
READFITS
[Previous Routine] [Next Routine] [List of Routines]NAME: READFITS PURPOSE: Read a FITS file into IDL data and header variables. EXPLANATION: Under Unix, READFITS() can also read gzip or Unix compressed FITS files. CALLING SEQUENCE: Result = READFITS( Filename,[ Header, heap, /NOSCALE, EXTEN_NO=, NSLICE=, /SILENT , NaNVALUE =, STARTROW =, NUMROW = ] ) INPUTS: FILENAME = Scalar string containing the name of the FITS file (including extension) to be read. If the filename has a *.gz extension, it will be treated as a gzip compressed file. If it has a .Z extension, it will be treated as a Unix compressed file. OUTPUTS: Result = FITS data array constructed from designated record. If the specified file was not found, then Result = -1 OPTIONAL OUTPUT: Header = String array containing the header from the FITS file. heap = For extensions, the optional heap area following the main data array (e.g. for variable length binary extensions). OPTIONAL INPUT KEYWORDS: EXTEN_NO - scalar integer specify the FITS extension to read. For example, specify EXTEN = 1 or /EXTEN to read the first FITS extension. Extensions are read using recursive calls to READFITS. NaNVALUE - This scalar is only needed on architectures (such as VMS prior to IDL V5.1) that do not recognize the IEEE "not a number" (NaN) convention. It specifies the value to translate any IEEE NAN values in the FITS data array. In addition, if the data is stored as integer (BITPIX = 16 or 32), and BSCALE is present, then NaNValue gives the values to pixels assigned with the BLANK keyword. NOSCALE - If present and non-zero, then the ouput data will not be scaled using the optional BSCALE and BZERO keywords in the FITS header. Default is to scale. NSLICE - An integer scalar specifying which N-1 dimensional slice of a N-dimensional array to read. For example, if the primary image of a file 'wfpc.fits' contains a 800 x 800 x 4 array, then IDL> im = readfits('wfpc.fits',h, nslice=2) is equivalent to IDL> im = readfits('wfpc.fits',h) IDL> im = im(*,*,2) but the use of the NSLICE keyword is much more efficient. NUMROW - This keyword only applies when reading a FITS extension. If specifies the number of rows (scalar integer) of the extension table to read. Useful when one does not want to read the entire table. POINT_LUN - Position (in bytes) in the FITS file at which to start reading. Useful if READFITS is called by another procedure which needs to directly read a FITS extension. Should always be a multiple of 2880. /SILENT - Normally, READFITS will display the size the array at the terminal. The SILENT keyword will suppress this STARTROW - This keyword only applies when reading a FITS extension It specifies the row (scalar integer) of the extension table at which to begin reading. Useful when one does not want to read the entire table. EXAMPLE: Read a FITS file TEST.FITS into an IDL image array, IM and FITS header array, H. Do not scale the data with BSCALE and BZERO. IDL> im = READFITS( 'TEST.FITS', h, /NOSCALE) If the file contain a FITS extension, it could be read with IDL> tab = READFITS( 'TEST.FITS', htab, /EXTEN ) The function TBGET() can be used for further processing of a binary table, and FTGET() for an ASCII table. To read only rows 100-149 of the FITS extension, IDL> tab = READFITS( 'TEST.FITS', htab, /EXTEN, STARTR=100, NUMR = 50 ) To read in a file that has been compressed: IDL> tab = READFITS('test.fits.gz',h) ERROR HANDLING: If an error is encountered reading the FITS file, then (1) the system variable !ERROR is set (via the MESSAGE facility) (2) the error message is displayed (unless /SILENT is set), and the message is also stored in !ERR_STRING (3) READFITS returns with a value of -1 RESTRICTIONS: (1) Cannot handle random group FITS NOTES: (1) If data is stored as integer (BITPIX = 16 or 32), and BSCALE and/or BZERO keywords are present, then the output array is scaled to floating point (unless /NOSCALE is present) using the values of BSCALE and BZERO. In the header, the values of BSCALE and BZERO are then reset to 1. and 0., while the original values are written into the new keywords O_BSCALE and O_BZERO. If the BLANK keyword was present, then any input integer values equal to BLANK in the input integer image are scaled to NaN (or the value of the NaNValue keyword) after the scaling to floating point. (2) The procedure FXREAD can be used as an alternative to READFITS. FXREAD has the option of reading an arbitary subsection of the primary FITS data. (3) The use of the NSLICE keyword is incompatible with the NUMROW or STARTROW keywords. PROCEDURES USED: Functions: SXPAR(), WHERENAN() Procedures: FDECOMP, IEEE_TO_HOST, SXADDPAR, SXDELPAR MODIFICATION HISTORY: MODIFIED, Wayne Landsman October, 1991 Added call to TEMPORARY function to speed processing Feb-92 Added STARTROW and NUMROW keywords for FITS tables Jul-92 Work under "windows" R. Isaacman Jan-93 Check for SIMPLE keyword in first 8 characters Feb-93 Removed EOF function for DECNET access Aug-93 Work under "alpha" Sep-93 Null array processing fixed: quotes in a message properly nested, return added. Affected case when readfits called from another procedure. R.S.Hill Jul-94 Correct size of variable length binary tables W.Landsman Dec-94 To read in compressed files on Unix systems. J. Bloch Jan-95 Check that file is a multiple of 2880 bytes Aug-95 Added FINDFILE check for file existence K.Feggans Oct-95 Consistent Error Handling W. Landsman Nov-95 Handle gzip image extensions W. Landsman Apr-96 Fixed bug reading 1-d data introduced Apr-96 W. Landsman Jun-96 Don't use FINDFILE (too slow), & check for Blank values WBL Oct-96 !VALUES wasn't compatible with IDL V3.6 WBL Jan-97 Added ability to read Unix compressed (.Z) files WBL Jan-97 Changed a FIX to LONG to handle very large tables WBL Apr-97 Force use of /bin/sh shell with gzip WBL Apr-97 Recognize BSCALE, BZERO in IMAGE extensions WBL Jun-97 Added NSLICE keyword WBL Jul-97 Added ability to read heap area after extensions WBL Aug-97 Suppress *all* nonfatal messages with /SILENT WBL Dec-97 Converted to IDL V5.0 WBL Dec-1997 Fix NaN assignment for int data C. Gehman/JPL Mar-98 Fix bug with NaNvalue = 0.0 C. Gehman/JPL Mar-98(See readfits.pro)
READFMT
[Previous Routine] [Next Routine] [List of Routines]NAME: READFMT PURPOSE: Quickly read a fixed format ASCII data file into IDL variables. EXPLANATION: Lines of data not meeting the specified format (e.g. comments) are ignored. To read a free format ASCII data file use the procedures READCOL or RDFLOAT. CALLING SEQUENCE: READFMT, name, fmt, v1,[ v2, v3, v4, ..., v25 , /SILENT, /DEBUG, SKIPLINE= , NUMLINE =] INPUTS: NAME - Name of ASCII data file. An extension of .DAT is assumed, if not supplied. FMT - scalar string containing a valid FORTRAN read format. Must include a field length specification. Cannot include internal parenthesis. A format field must be included for each output vector. Multiple format fields are allowed, but the repetition factor must be less than 100, (.i.e. 19X is allowed but 117X is illegal) Examples of valid FMT values are FMT = 'A7,3X,2I4' or FMT = '1H ,5I7,2A7' Examples of INVALID FMT values are FMT = 'A7,B3' ;'B' is not a valid FORTRAN format FMT = 'A7,2(I3,F5.1)' ;Internal parenthesis not allowed FMT = 'A7,F,I' ;Field length not included OUTPUTS: V1,V2,V3,V4... - IDL vectors to contain columns of data. Up to 25 output vectors may be read. The type of the output vectors are specified by FMT. OPTIONAL KEYWORD INPUTS: SILENT - If this keyword is set and non-zero, then certain terminal output is suppressed while reading the file DEBUG - Set this keyword to display additional information while reading the file. SKIPLINE - Scalar specifying number of lines to skip at the top of file before reading. Default is to start at first line NUMLINE - Scalar specifying number of lines in the file to read. Default is to read the entire file EXAMPLES: Each row in a fixed-formated file POSITION.DAT contains a 5 character star name and 6 columns of data giving an RA and Dec in sexigesimal format. A possible format for such data might be IDL> FMT = 'A5,2I3,F5.1,2x,3I3' and the file could be quickly read with IDL> READFMT,'POSITION', fmt, name, hr, min, sec, deg, dmin, dsec NAME will be a string vector,SEC will be a floating point vector, and the other vectors will be of integer type. RESTRICTIONS: This procedure is designed for generality and not for speed. If a large ASCII file is to be read repeatedly, it may be worth writing a specialized reader. NOTES: When reading a field with an integer format I, the output vector is byte - if n = 1 integer*2 - if 1 < n < 5 integer*4 - in all other cases PROCEDURE CALLS: GETTOK(), NUMLINES(), REMCHAR, ZPARCHECK REVISION HISTORY: Written W. Landsman November, 1988 Added SKIPLINE and NUMLINE keywords March 92 Allow up to 25 columns to be read June 92 Call NUMLINES() function Feb 1996 Converted to IDL V5.0 W. Landsman September 1997 (See readfmt.pro)
READ_KEY
[Previous Routine] [Next Routine] [List of Routines]NAME: READ_KEY PURPOSE: To read a keystroke and return its ASCII equivalent EXPLANATION: If an ESCAPE sequence was produced and the sequence is recognized (e.g. up arrow), then a code is returned. CALLING SEQUENCE: key = READ_KEY(Wait) INPUTS: Wait - The wait flag. If non-zero, execution is halted until a key is struck. If zero, execution returns immediately and a zero is returned if there was no keystroke waiting in the keyboard buffer. If not specified, zero is assumed. OUTPUT: Returned - The key struck. The ASCII code for non-escape sequences. Escape sequence equivalents: Up Arrow -- 128 Down Arrow -- 130 Left Arrow -- 129 Right Arrow -- 131 Else -- 0 The return value is a byte value. MODIFICATION HISTORY: Written by Michael R. Greason, STX, 22 June 1990. Rewritten for a SUN workstation. MRG, STX, 23 August 1990. Converted to IDL V5.0 W. Landsman September 1997(See read_key.pro)
RECPOL
[Previous Routine] [Next Routine] [List of Routines]NAME: RECPOL PURPOSE: Convert 2-d rectangular coordinates to polar coordinates. CATEGORY: CALLING SEQUENCE: recpol, x, y, r, a INPUTS: x, y = vector in rectangular form. in KEYWORD PARAMETERS: Keywords: /DEGREES means angle is in degrees, else radians. OUTPUTS: r, a = vector in polar form: radius, angle. out COMMON BLOCKS: NOTES: MODIFICATION HISTORY: R. Sterner. 18 Aug, 1986. Johns Hopkins University Applied Physics Laboratory. RES 13 Feb, 1991 --- added /degrees. R. Sterner, 30 Dec, 1991 --- simplified. R. Sterner, 25 May, 1993 --- Fixed atan (0,0) problem. Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory This software may be used, copied, or redistributed as long as it is not sold and this copyright notice is reproduced on each copy made. This routine is provided as is without any express or implied warranties whatsoever. Other limitations apply as described in the file disclaimer.txt. Converted to IDL V5.0 W. Landsman September 1997(See recpol.pro)
REDSHIFT
[Previous Routine] [Next Routine] [List of Routines]NAME: REDSHIFT PURPOSE: Converts between redshift, Recession velocity, and Distance CALLING SEQUENCE: redshift, [h, HELP = ] INPUTS: h = optional Hubble constant (def = 50 km/s/Mpc). in OUTPUTS: Results are displayed at the terminal screen NOTES: Note: H may be changed at any time by typing h=new_value. Also displays angular size equivalence and photometric information. MODIFICATION HISTORY: R. Sterner. 17 July, 1987. Johns Hopkins University Applied Physics Laboratory. RES 7 Jan, 1988 --- added H0. Copyright (C) 1987, Johns Hopkins University/Applied Physics Laboratory This software may be used, copied, or redistributed as long as it is not sold and this copyright notice is reproduced on each copy made. This routine is provided as is without any express or implied warranties whatsoever. Other limitations apply as described in the file disclaimer.txt. Converted to IDL V5.0 W. Landsman September 1997(See redshift.pro)
REMCHAR
[Previous Routine] [Next Routine] [List of Routines]NAME: REMCHAR PURPOSE: Remove all appearances of character (char) from string (st) CALLING SEQUENCE: REMCHAR, ST, CHAR INPUT-OUTPUT: ST - String from which character will be removed, scalar or vector INPUT: CHAR- Single character to be removed from string or all elements of a string array EXAMPLE: If a = 'a,b,c,d,e,f,g' then IDL> remchar,a, ',' will give a = 'abcdefg' REVISIONS HISTORY Written D. Lindler October 1986 Test if empty string needs to be returned W. Landsman Feb 1991 Work on string arrays W. Landsman August 1997 Converted to IDL V5.0 W. Landsman September 1997(See remchar.pro)
REMOVE
[Previous Routine] [Next Routine] [List of Routines]NAME: REMOVE PURPOSE: Contract a vector or up to 7 vectors by removing specified elements CALLING SEQUENCE: REMOVE, index, vector1,[ vector2, vector3, vector4, vector5,vector6, vector7] INPUTS: INDEX - scalar or vector giving the index number of elements to be removed from vectors. Duplicate entries in index are ignored. An error will occur if one attempts to remove all the elements of a vector. INPUT-OUTPUT: VECTOR1 - Vector or array. Elements specifed by INDEX will be removed from VECTOR1. Upon return VECTOR1 will contain N fewer elements, where N is the number of values in INDEX. OPTIONAL INPUT-OUTPUTS: VECTOR2,VECTOR3,...VECTOR7 - additional vectors containing the same number of elements as VECTOR1. These will be contracted in the same manner as VECTOR1. EXAMPLES: (1) If INDEX = [2,4,6,4] and V = [1,3,4,3,2,5,7,3] then after the call IDL> remove,index,v V will contain the values [1,3,3,5,3] (2) Suppose one has a wavelength vector W, and three associated flux vectors F1, F2, and F3. Remove all points where a quality vector, EPS is negative IDL> bad = where( EPS LT 0, Nbad) IDL> if Nbad GT 0 then remove, bad, w, f1, f2, f3 METHOD: If only 1 element is to be removed, then the vectors are shortened by simple subscripting. If more than 1 element is to be removed, then a "keep" vector of indices to save is formed, and applied to the input vectors REVISION HISTORY: Written W. Landsman ST Systems Co. April 28, 1988 Cleaned up code W. Landsman September, 1992 Converted to IDL V5.0 W. Landsman September 1997(See remove.pro)
REM_DUP
[Previous Routine] [Next Routine] [List of Routines]NAME: REM_DUP PURPOSE: Function to remove duplicate values from a vector. CALLING SEQUENCE: result = rem_dup( a, [ flag ] ) INPUTS: a - vector of values from which duplicates are to be found flag - (optional) if supplied then when duplicates occur, the one with the largest value of flag is selected. If not supplied the the first occurence of the value in a is selected. Should be a vector with the same number of elements as a. OUTPUT: A vector of subscripts in a is returned. Each subscript points to a selected value such that a(rem_dup(a,flag)) has no duplicates. SIDE EFFECTS: The returned subscripts will sort the values in a in ascending order with duplicates removed. EXAMPLES: Remove duplicate values in vector a. a = a( rem_dup(a) ) Remove duplicates in vector WAVE. When duplicate values are found, select the one with the largest intensity, INTE. sub = rem_dup( wave, inte) wave = wave( sub ) inte = inte( sub ) NOTES: The UNIQ function in the User's Library uses a faster algorithm, but has no equivalent of the "flag" parameter MODIFICATION HISTORY: D. Lindler Mar. 87 11/16/90 JKF ACC - converted to IDL Version 2. August 1997 -- Changed loop index to type LONG October 1997 -- Also changed NGOOD index to LONG Converted to IDL V5.0 W. Landsman October 1997(See rem_dup.pro)
REPCHR
[Previous Routine] [Next Routine] [List of Routines]NAME: REPCHR PURPOSE: Replace all occurrences of one character with another in a text string. CATEGORY: CALLING SEQUENCE: new = repchr(old, c1, [c2]) INPUTS: old = original text string. in c1 = character to replace. in c2 = character to replace it with. in default is space. KEYWORD PARAMETERS: OUTPUTS: new = edited string. out COMMON BLOCKS: NOTES: MODIFICATION HISTORY: R. Sterner. 28 Oct, 1986. Johns Hopkins Applied Physics Lab. RES 1 Sep, 1989 --- converted to SUN. R. Sterner, 27 Jan, 1993 --- dropped reference to array. Copyright (C) 1986, Johns Hopkins University/Applied Physics Laboratory This software may be used, copied, or redistributed as long as it is not sold and this copyright notice is reproduced on each copy made. This routine is provided as is without any express or implied warranties whatsoever. Other limitations apply as described in the file disclaimer.txt. Converted to IDL V5.0 W. Landsman September 1997(See repchr.pro)
REPSTR
[Previous Routine] [Next Routine] [List of Routines]NAME: REPSTR PURPOSE: Replace all occurences of one substring by another. EXPLANATION: Meant to emulate the string substitution capabilities of text editors CALLING SEQUENCE: result = repstr( obj, in, out ) INPUT PARAMETERS: obj = object string for editing, scalar or array in = substring of 'obj' to be replaced, scalar OPTIONAL INPUT PARMETER: out = what 'in' is replaced with, scalar. If not supplied then out = '', i.e. 'in' is not replaced by anything. OUTPUT PARAMETERS: Result returned as function value. Input object string not changed unless assignment done in calling program. PROCEDURE: Searches for 'in', splits 'obj' into 3 pieces, reassembles with 'out' in place of 'in'. Repeats until all cases done. EXAMPLE: If a = 'I am what I am' then print,repstr(a,'am','was') will give 'I was what I was'. MODIFICATION HISTORY: Written by Robert S. Hill, ST Systems Corp., 12 April 1989. Accept vector object strings, W. Landsman HSTX, April, 1996 Converted to IDL V5.0 W. Landsman September 1997(See repstr.pro)
REWIND
[Previous Routine] [Next Routine] [List of Routines]NAME : REWIND PURPOSE : Emulates the VMS REWIND function in Unix. EXPLANATION : Emulates the VMS REWIND function in the Unix environment. **Unix only** CALLING SEQUENCE: REWIND, UNIT Inputs : UNIT = Tape unit number. Tape drives are selected via the UNIX environment variables "MT1", "MT2", etc. The desired tape drive is thus specified by numbers, as in VMS. Must be from 0 to 9. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : CHECK_TAPE_DRV Common : None. Restrictions: The environment variable "MTn", where n corresponds to the variable UNIT, must be defined. E.g., setenv MT0 /dev/nrst0 Requires IDL v3.0 or later. Side effects: The device file is opened. Category : Utilities, I/O, Tape. Prev. Hist. : VERSION 1, R. W. Thompson 11/30/89 William Thompson, Apr 1991, rewrote to better emulate VMS version. Written : R. W. Thompson, GSFC/IUE, 30 November 1989. Modified : Version 1, William Thompson, GSFC, 21 December 1993. Rewrote to use IOCTL. Version : Version 1, 21 December 1993. Converted to IDL V5.0 W. Landsman September 1997(See rewind.pro)
RINTER
[Previous Routine] [Next Routine] [List of Routines]NAME: RINTER PURPOSE: Cubic interpolation of an image at a set of reference points. EXPLANATION: This interpolation program is equivalent to using the intrinsic INTERPOLATE() function in IDL V5.0 with CUBIC = -0.5. However, RINTER() has two advantages: (1) one can optionally obtain the X and Y derivatives at the reference points, and (2) if repeated interpolation is to be applied to an array, then some values can be pre-computed and stored in Common. RINTER() was originally for use with the DAOPHOT procedures, but can also be used for general cubic interpolation. CALLING SEQUENCE: Z = RINTER( P, X, Y, [ DFDX, DFDY ] ) INPUTS: P - Two dimensional data array, X - Either an N element vector or an N x M element array, containing X subscripts where cubic interpolation is desired. Y - Either an N element vector or an N x M element arra, containing Y subscripts where cubic interpolation is desired. OUTPUT: Z - Result = interpolated vector or array. If X and Y are vectors, then so is Z, but if X and Y are arrays then Z will be also. If P is DOUBLE precision, then so is Z, otherwise Z is REAL. OPTIONAL OUTPUT: DFDX - Vector or Array, (same size and type as Z), containing the derivatives with respect to X DFDY - Array containing derivatives with respect to Y EXAMPLE: suppose P is a 256 x 256 element array and X = FINDGEN(50)/2. + 100. and Y = X. Then Z will be a 50 element array, containing the cubic interpolated points. SIDE EFFECTS: can be time consuming. RESTRICTION: Interpolation is not possible at positions outside the range of the array (including all negative subscripts), or within 2 pixel units of the edge. No error message is given but values of the output array are meaningless at these positions. PROCEDURE: invokes CUBIC interpolation algorithm to evaluate each element in Z at virtual coordinates contained in X and Y with the data in P. COMMON BLOCKS: If repeated interpolation of the same array is to occur, then one can save time by initializing the common block RINTER REVISION HISTORY: March 1988 written W. Landsman STX Co. Checked for IDL Version 2, J. Isensee, September, 1990 Corrected call to HISTOGRAM, W. Landsman November 1990 Converted to IDL V5.0 W. Landsman September 1997(See rinter.pro)
SCREEN_SELECT
[Previous Routine] [Next Routine] [List of Routines]NAME: SCREEN_SELECT PURPOSE: Allow a user to make an interactive screen selection from a list EXPLANATION: This procedure determines whether to use the dumb terminal version, or the widget version by examining the !D.NAME system variable. CALLING SEQUENCE: screen_select, selections, iselected, comments, command_line, only_one INPUTS: selections - string array giving list of items that can be selected. OPTIONAL INPUTS: comments - comments which can be requested for each item in array selections. It can be: string array - same length as array selections. null string - no comments available scalar string - name of a procedure which will return comments. It will take selections as its first argument and return comments as its second argument. command_line - optional command line to be placed at the bottom of the screen. It is usually used to specify what the user is selecting. only_one - integer flag. If set to 1 then the user can only select one item. The routine returns immediately after the first selection is made. OUTPUTS: iselected - list of indices in selections giving the selected items. SIDE EFFECTS: !err is set to the number of selections made PROCEDURE: The actual processing is farmed out to different procedures depending on the terminal type. Widget Terminal ==> SELECT_W.PRO VT100 Terminal ==> SELECT_O.PRO HISTORY: Written by M. Greason, STX, May 1990. Added widget support W. Landsman January, 1992 Remove X window but no widget option November, 1994 Converted to IDL V5.0 W. Landsman September 1997(See screen_select.pro)
SCR_ATTRIB
[Previous Routine] [Next Routine] [List of Routines]NAME: SCR_ATTRIB PURPOSE: To set the screen attribute to those given, in the given order. CALLING SEQUENCE: scr_attrib [, a1, a2, a3, a4, a5] INPUTS: a1 - a5 -- The attribute codes. The attributes are set in the command string in the given order. Thus, if a1 turns the attributes off and a2 sets reverse video, the final attribute will reset and then set to reverse video. If the order were reversed, then the current attribute would have reverse video added to it, and then would be reset, leaving the terminal with all attributes off. Up to five attribute codes may be specified. The codes are: 0 : all attributes off (default) 1 : bold on 2 : underscore on 3 : blink on 4 : reverse video on OUTPUTS: None. SIDE EFFECTS: None. RESTRICTIONS: This procedure will only work with DEC compatible equipment (or terminal emulators). PROCEDURE: A string containing the appropriate DEC terminal command is put together and printed. NOTE: In general, the DEC commands correspond to the ANSI escape sequences. MODIFICATION HISTORY: Written by Michael R. Greason, STX, May 1990. Converted to IDL V5.0 W. Landsman September 1997(See scr_attrib.pro)
SCR_CHARSET
[Previous Routine] [Next Routine] [List of Routines]NAME: SCR_CHARSET PURPOSE: To change the character sets. CALLING SEQUENCE: scr_charset [, g, cset] INPUTS: g -- The terminal character set to change (either 0, for the G0 designator, or 1, for the G1 designator). 0 = default. cset -- The character set to use: 0 : United Kingdom. 1 : United States (USASCII) -- default. 2 : Special graphics characters and line drawing set. 3 : Alternate character ROM. 4 : Alternate character ROM special graphics chars. OUTPUTS: None. SIDE EFFECTS: None. RESTRICTIONS: This procedure will only work with DEC compatible equipment (or terminal emulators). PROCEDURE: A string containing the appropriate DEC terminal command is put together and printed. NOTE: In general, the DEC commands correspond to the ANSI escape sequences. MODIFICATION HISTORY: Written by Michael R. Greason, STX, May 1990. Converted to IDL V5.0 W. Landsman September 1997(See scr_charset.pro)
SCR_CURMOV
[Previous Routine] [Next Routine] [List of Routines]NAME: SCR_CURMOV PURPOSE: To mov the cursor around the screen relative to its original position. CALLING SEQUENCE: scr_curmov [, cmd, n] INPUTS: cmd -- An integer indicating the direction in which to move the curs. 0 : Up 1 : Down (Default) 2 : Left 3 : Right n -- The number of spaces to move the cursor. If not specified (or if less than or equal to zero), this is set to one. OUTPUTS: None. SIDE EFFECTS: None. RESTRICTIONS: This procedure will only work with DEC compatible equipment (or terminal emulators). PROCEDURE: A string containing the appropriate DEC terminal command is put together and printed. NOTE: In general, the DEC commands correspond to the ANSI escape sequences. MODIFICATION HISTORY: Written by Michael R. Greason, STX, May 1990. Converted to IDL V5.0 W. Landsman September 1997(See scr_curmov.pro)
SCR_CURPOS
[Previous Routine] [Next Routine] [List of Routines]NAME: SCR_CURPOS PURPOSE: To position the cursor at the specified screen location. EXPLANATION: Unspecified coordinates are set to one. Please note that the ESCAPE sequence expects the coordinates to be counted from (1,1). CALLING SEQUENCE: scr_curpos [, lin, col] INPUTS: lin -- The screen line coordinate. col -- The screen column coordinate. OUTPUTS: None. SIDE EFFECTS: None. RESTRICTIONS: This procedure will only work with DEC compatible equipment (or terminal emulators). PROCEDURE: A string containing the appropriate DEC terminal command is put together and printed. NOTE: In general, the DEC commands correspond to the ANSI escape sequences. MODIFICATION HISTORY: Written by Michael R. Greason, STX, May 1990. Converted to IDL V5.0 W. Landsman September 1997(See scr_curpos.pro)
SCR_ERASE
[Previous Routine] [Next Routine] [List of Routines]NAME: SCR_ERASE PURPOSE: To erase portions of the terminal screen. CALLING SEQUENCE: scr_erase [, cmd] INPUTS: cmd -- An integer telling the procedure what part of the screen to erase. If not specified, it is set to 5. Key: 0 : From cursor to end-of-line. 1 : From beginning-of-line to cursor. 2 : Entire line containing cursor. 3 : From cursor to end-of-screen. 4 : from beginning-of-screen to cursor. ELSE : Entire screen. OUTPUTS: None. SIDE EFFECTS: None. RESTRICTIONS: This procedure will only work with DEC compatible equipment (or terminal emulators). PROCEDURE: A string containing the appropriate DEC terminal command is put together and printed. NOTE: In general, the DEC commands correspond to the ANSI escape sequences. MODIFICATION HISTORY: Written by Michael R. Greason, STX, May 1990. Converted to IDL V5.0 W. Landsman September 1997(See scr_erase.pro)
SCR_OTHER
[Previous Routine] [Next Routine] [List of Routines]NAME: SCR_OTHER PURPOSE: To allow the user to issue any ESCAPE sequence. CALLING SEQUENCE: scr_other, str INPUTS: str -- A string containing the escape sequence. The initial ESCAPE should not be included; this will be added by this procedure. This parameter is NOT optional; if not available, the procedure will return without doing anything. OUTPUTS: None. SIDE EFFECTS: None. RESTRICTIONS: This procedure will only work with DEC compatible equipment (or terminal emulators). PROCEDURE: A string containing the appropriate DEC terminal command is put together and printed. NOTE: In general, the DEC commands correspond to the ANSI escape sequences. MODIFICATION HISTORY: Written by Michael R. Greason, STX, May 1990. Converted to IDL V5.0 W. Landsman September 1997(See scr_other.pro)
SCR_RESET
[Previous Routine] [Next Routine] [List of Routines]NAME: SCR_RESET PURPOSE: To reset the terminal. CALLING SEQUENCE: scr_reset INPUTS: None. OUTPUTS: None. SIDE EFFECTS: None. RESTRICTIONS: This procedure will only work with DEC compatible equipment (or terminal emulators). PROCEDURE: A string containing the appropriate DEC terminal command is put together and printed. NOTE: In general, the DEC commands correspond to the ANSI escape sequences. MODIFICATION HISTORY: Written by Michael R. Greason, STX, May 1990. Converted to IDL V5.0 W. Landsman September 1997(See scr_reset.pro)
SCR_SCROLL
[Previous Routine] [Next Routine] [List of Routines]NAME: SCR_SCROLL PURPOSE: Define the scrolling area on the screen. EXPLANATION: Please note that the line coordinates should be counted from 1. CALLING SEQUENCE: scr_scroll [, top, bot] INPUTS: top -- The line to be the top of the scrolling area. The default value is 1 and the maximum value is 23. bot -- The line to be the bottom of the scrolling area. The default value is 24 and the minimum value is 2. OUTPUTS: None. SIDE EFFECTS: NOTE: The screen coordinate system is NOT effected. (1,1) is not the top of the scrolling area but the top of the screen. RESTRICTIONS: This procedure will only work with DEC compatible equipment (or terminal emulators). PROCEDURE: A string containing the appropriate DEC terminal command is put together and printed. NOTE: In general, the DEC commands correspond to the ANSI escape sequences. MODIFICATION HISTORY: Written by Michael R. Greason, STX, May 1990. Converted to IDL V5.0 W. Landsman September 1997(See scr_scroll.pro)
SELECT_O
[Previous Routine] [Next Routine] [List of Routines]NAME: SELECT_O PURPOSE: Dumb-terminal routine to let a user interactively select from a list EXPLANATION: This is the non-widget version of SCREEN_SELECT CALLING SEQUENCE: select_o, selections, iselected, comments, command_line, only_one INPUTS: selections - string array giving list of items that can be selected. OPTIONAL INPUTS: comments - comments which can be requested for each item in array selections. It can be: string array - same length as array selections. null string - no comments available scalar string - name of a procedure which will return comments. It will take selections as its first argument and return comments as its second argument. command_line - optional command line to be placed at the bottom of the screen. It is usually used to specify what the user is selecting. only_one - integer flag. If set to 1 then the user can only select one item. The routine returns immediately after the first selection is made. OUTPUTS: iselected - list of indices in selections giving the selected items. SIDE EFFECTS: !err is set to the number of selections made HISTORY: version 1, D. Lindler April 88. modified to IDL V2 (from screen_select). M. Greason, May 1990. changed name from screen_select_o W. Landsman January 1993 Converted to IDL V5.0 W. Landsman September 1997(See select_o.pro)
SELECT_W
[Previous Routine] [Next Routine] [List of Routines]NAME: SELECT_W PURPOSE: Create a non-exclusive widget menu of items EXPLANATION: More than one item may be selected or 'de-selected'. Normally called by SCREEN_SELECT CALLING SEQUENCE: SELECT_W, items ,iselected, [ comments, command_line, only_one ] INPUTS: items - string array giving list of items that can be selected. OPTIONAL INPUTS: comments - comments which can be requested for each item in array selections. NOT YET IMPLEMENTED command_line - optional command line to be placed at the bottom of the screen. It is usually used to specify what the user is selecting. only_one - integer flag. If set to 1 then the user can only select one item. The routine returns immediately after the first selection is made. OUTPUT: iselected - list of indices in selections giving the selected items. COMMON BLOCKS: SELECT_W - Used to communicate with the SELECT_W_EVENT procedure MODIFICATION HISTORY: Written, K. Venkatakrishna & W. Landsman, Hughes/STX January, 1992 Widgets made MODAL. M. Greason, Hughes STX, 15 July 1992. Changed handling of MODAL keyword for V5.0 W.Thompson September 1997 Converted to IDL V5.0 W. Landsman September 1997(See select_w.pro)
SIGMA_FILTER
[Previous Routine] [Next Routine] [List of Routines]NAME: SIGMA_FILTER PURPOSE: Replace pixels more than a specified pixels deviant from its neighbors EXPLANATION: Computes the mean and standard deviation of pixels in a box centered at each pixel of the image, but excluding the center pixel. If the center pixel value exceeds some # of standard deviations from the mean, it is replaced by the mean in box. Note option to process pixels on the edges. CALLING SEQUENCE: Result = sigma_filter( image, box_width, N_sigma=(#), /ALL,/MON ) INPUTS: image = 2-D image (matrix) box_width = width of square filter box, in # pixels (default = 3) KEYWORDS: N_sigma = # standard deviations to define outliers, floating point, recommend > 2, default = 3. For gaussian statistics: N_sigma = 1 smooths 35% of pixels, 2 = 5%, 3 = 1%. RADIUS = alternative to specify box radius, so box_width = 2*radius+1. /ALL_PIXELS causes computation to include edges of image, /KEEP causes opposite effect: pixels with values outside of specified deviation are not changed, pixels within deviation are smoothed. /ITERATE causes sigma_filter to be applied recursively (max = 20 times) until no more pixels change (only allowed when N_sigma >= 2). /MONITOR prints information about % pixels replaced. Optional Outputs: N_CHANGE = # of pixels changed (replaced with neighborhood mean). VARIANCE = image of pixel neighborhood variances * (N_sigma)^2, DEVIATION = image of pixel deviations from neighborhood means, squared. CALLS: function filter_image( ) PROCEDURE: Compute mean over moving box-cars using smooth, subtract center values, compute variance using smooth on deviations from mean, check where pixel deviation from mean is within variance of box, replace those pixels in smoothed image (mean) with orignal values, return the resulting partial mean image. MODIFICATION HISTORY: Written, 1991, Frank Varosi and Dan Gezari NASA/GSFC F.V.1992, added optional keywords /ITER,/MON,VAR=,DEV=,N_CHANGE=. Converted to IDL V5.0 W. Landsman September 1997(See sigma_filter.pro)
SIGRANGE()
[Previous Routine] [Next Routine] [List of Routines]NAME: SIGRANGE() PURPOSE: Selects the most significant data range in an image. EXPLANATION: Selects out the most significant range in the data to be used in displaying images. The histogram of ARRAY is used to select the most significant range. Useful for scaling an image display. CALLING SEQUENCE: OUTPUT = SIGRANGE( ARRAY ) INPUTS: ARRAY = Array to take most significant range of. OPTIONAL INPUTS: None. OUTPUTS: The function returns an array where values above and below the selected range are set equal to the maximum and minimum of the range respectively. OPTIONAL INPUT KEYWORDS: FRACTION = Fraction of data to consider most significant. Defaults to 0.9 MISSING = Value used to flag missing points. Data points with this value are not considered or changed. OPTIONAL OUTPUT KEYWORD RANGE = 2 element vector, giving the range (minimum and maxmimum) used RESTRICTIONS: ARRAY must have more than two points. Fraction must be greater than 0 and less than 1. SIGRANGE was originally part of the SERTS image display package. Other routines from this package are available at http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/image/ Note that this version of SIGRANGE does not include the non-standard system variables used in the SERTS package. REVISION HISTORY: Version 1, William Thompson, GSFC, 12 May 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 25 May 1993. Changed call to HISTOGRAM to be compatible with OpenVMS/ALPHA Version 3, CDP, RAL, Add RANGE keyword. 16-Apr-96 Version 4, William Thompson, GSFC, 17 April 1996 Corrected some problems when range is too high. Version 5, 13-Jan-1998, William Thompson, GSFC Use random numbers to improve statistics when only using a fraction of the array. Converted to IDL V5.0, February, 1998(See sigrange.pro)
SIXLIN
[Previous Routine] [Next Routine] [List of Routines]NAME: SIXLIN PURPOSE: Compute linear regression coefficients by six different methods. EXPLANATION: Adapted from the FORTRAN program (Rev. 1.1) supplied by Isobe, Feigelson, Akritas, and Babu Ap. J. Vol. 364, p. 104 (1990). Suggested when there is no understanding about the nature of the scatter about a linear relation, and NOT when the errors in the variable are calculable. CALLING SEQUENCE: SIXLIN, xx, yy, a, siga, b, sigb INPUTS: XX - vector of X values YY - vector of Y values, same number of elements as XX OUTPUTS: A - Vector of 6 Y intercept coefficients SIGA - Vector of standard deviations of 6 Y intercepts B - Vector of 6 slope coefficients SIGB - Vector of standard deviations of slope coefficients The output variables are computed using linear regression for each of the following 6 cases: (0) Ordinary Least Squares (OLS) Y vs. X (1) Ordinary Least Squares X vs. Y (2) Ordinary Least Squares Bisector (3) Orthogonal Reduced Major Axis (4) Reduced Major-Axis (5) Mean ordinary Least Squares NOTES: Isobe et al. make the following recommendations (1) If the different linear regression methods yield similar results then quoting OLS(Y|X) is probably the most familiar. (2) If the linear relation is to be used to predict Y vs. X then OLS(Y|X) should be used. (3) If the goal is to determine the functional relationship between X and Y then the OLS bisector is recommended. REVISION HISTORY: Written Wayne Landsman February, 1991 Corrected sigma calculations February, 1992 Converted to IDL V5.0 W. Landsman September 1997(See sixlin.pro)
SIXTY()
[Previous Routine] [Next Routine] [List of Routines]NAME: SIXTY() PURPOSE: Converts a decimal number to sexigesimal. EXPLANATION: Reverse of the TEN() function. CALLING SEQUENCE: X = SIXTY( SCALAR ) INPUTS: SCALAR -- Decimal quantity. OUTPUTS: Function value returned = floating real vector of three elements, sexigesimal equivalent of input decimal quantity. A negative number is signified by making the first non-zero element of the output vection negative. PROCEDURE: Mostly involves checking arguments and setting the sign. EXAMPLE: If x = -0.345d then sixty(x) = [0.0, -20.0, 24.0] MODIFICATION HISTORY: Written by R. S. Hill, STX, 19-OCT-87 Output changed to single precision. RSH, STX, 1/26/88 Accept single element vector W. Landsman Sep. 1996 Converted to IDL V5.0 W. Landsman September 1997(See sixty.pro)
SIZE_STRUCT
[Previous Routine] [Next Routine] [List of Routines]NAME: SIZE_STRUCT PURPOSE: Obtain the size in bytes of an IDL structure definition. EXPLANATION: For most applications this function is superceded by use of the /LENGTH keyword to the intrinsic N_TAGS function introduced in IDL V2.3.0 CALLING SEQUENCE: bytes = size_struct( structure ) examples: print, size_struct( "fdq_sdf" ) INPUTS: structure = a structure variable or a string giving the structure name as known by IDL (help,/struct,variable). /PRINT = to print all sub structure sizes. inputs/outputs used recursively: struct = the structure VARIABLE currently analyzed. Max_Field_Size = size of the largest field found in structure. RESULT: Function returns the total size in bytes of a structure element. PROCEDURE: Strategy is to call size_struct recursively if structure contains sub-structures. Otherwise just add up the field sizes. MODIFICATION HISTORY: written 1990 Frank Varosi STX @ NASA/GSFC (using align_struct). Converted to IDL V5.0 W. Landsman September 1997(See size_struct.pro)
SKIPF
[Previous Routine] [Next Routine] [List of Routines]NAME : SKIPF PURPOSE : Emulates the VMS SKIPF function on UNIX machines. EXPLANATION : Emulates the VMS SKIPF function on UNIX machines. CALLING SEQUENCE : SKIPF, UNIT, NSKIP SKIPF, UNIT, NSKIP, RECORDS Inputs : UNIT = Tape unit number. Tape drives are selected via the UNIX environment variables "MT1", "MT2", etc. The desired tape drive is thus specified by numbers, as in VMS. Must be from 0 to 9. NSKIP = Number of files or records to skip. Opt. Inputs : RECORDS = If present, then records are skipped instead of files. Outputs : None. However, !ERR is set to ABS(NSKIP) Opt. Outputs: None. Keywords : None. Calls : CHECK_TAPE_DRV Common : None. Restrictions: This routine may not act exactly the same as the VMS equivalent, particularly in regards to the behavior of the !ERR system variable. The environment variable "MTn", where n corresponds to the variable UNIT, must be defined. E.g., setenv MT0 /dev/nrst0 Requires IDL v3.0 or later. Side effects: The device file is opened. !ERR is set to ABS(NSKIP). Category : Utilities, I/O, Tape. Prev. Hist. : VERSION 1, R. W. Thompson 12/4/89 William Thompson, Apr 1991, rewrote to better emulate VMS version. Written : R. W. Thompson, GSFC/IUE, 4 December 1989. Modified : Version 1, William Thompson, GSFC, 21 December 1993. Rewrote to use IOCTL. Version : Version 1, 21 December 1993. Converted to IDL V5.0 W. Landsman September 1997(See skipf.pro)
SKY