This page was created by the IDL library routine
mk_html_help. For more information on
this routine, refer to the IDL Online Help Navigator
or type:
? mk_html_help
at the IDL command line prompt.
Last modified: Fri Mar 24 12:48:43 2000.
NAME:
AMOEBA
PURPOSE:
Multidimensional minimization of a function FUNC(X), where
X is an N-dimensional vector, using the downhill simplex
method of Nelder and Mead, 1965, Computer Journal, Vol 7, pp 308-313.
This routine is based on the AMOEBA routine, Numerical
Recipes in C: The Art of Scientific Computing (Second Edition), Page
411, and is used by permission.
CATEGORY:
Function minimization/maximization. Simplex method.
CALLING SEQUENCE:
Result = AMOEBA(Ftol, ....)
INPUTS:
FTOL: the fractional tolerance to be achieved in the function
value. e.g. the fractional decrease in the function value in the
terminating step. This should never be less than the
machine's single or double precision.
KEYWORD PARAMETERS:
FUNCTION_NAME: a string containing the name of the function to
be minimized. If omitted, the function FUNC is minimized.
This function must accept an Ndim vector as its only parameter and
return a scalar single or double precision floating point value as its
result.
FUNCTION_VALUE: (output) on exit, an Ndim+1 element vector
containing the function values at the simplex points. The first
element contains the function minimum.
NCALLS: (output) the of times the function was evaluated.
NMAX: the maximum number of function evaluations allowed
before terminating. Default = 5000.
P0: Initial starting point, an Ndim element vector. The starting
point must be specified using either the keyword SIMPLEX, or P0 and
SCALE. P0 may be either single or double precision floating.
For example, in a 3-dimensional problem, if the initial guess
is the point [0,0,0], and it is known that the function's
minimum value occurs in the interval: -10 <
X(0) < 10, -100 < X(1) < 100, -200 < X(2) < 200, specify: P0=[0,0,0],
SCALE=[10, 100, 200].
SCALE: a scalar or Ndim element vector contaiing the problem's
characteristic length scale for each dimension.
SCALE is used with P0 to form an initial (Ndim+1) point simplex.
If all dimensions have the same scale, specify a scalar.
SIMPLEX: (output and/or optional input) On input, if P0 and SCALE
are not set, SIMPLEX contains the Ndim+1 vertices, each of
Ndim elements, of starting simplex, in either single or double
precision floating point, in an (Ndim, Ndim+1) array. On output,
SIMPLEX contains the simplex, of dimensions (Ndim, Ndim+1), enclosing
the function minimum. The first point, Simplex(*,0), corresponds to
the function's minimum.
OUTPUTS:
Result: If the minimum is found, an Ndim vector, corresponding to
the Function's minimum value is returned. If a function minimum
within the given tolerance, is NOT found in the given number of
evaluations, a scalar value of -1 is returned.
COMMON BLOCKS:
None.
SIDE EFFECTS:
None.
PROCEDURE:
This procedure implements the Simplex method, described in
Numerical Recipes, Section 10.4. See also the POWELL procedure.
Advantages: requires only function evaluations, not
derivatives, may be more reliable than the POWELL method.
Disadvantages: not as efficient as Powell's method, and usually
requires more function evaluations.
Results are performed in the mode (single or double precision)
returned by the user-supplied function. The mode of the inputs P0,
SCALE, or SIMPLEX, should match that returned by the function. The
mode of the input vector supplied to the user-written function, is
determined by P0, SCALE, or SIMPLEX.
EXAMPLE:
Use Amoeba to find the slope and intercept of a straight line fitting
a given set of points minimizing the maximum error:
The function to be minimized returns the maximum error,
given p(0) = intercept, and p(1) = slope:
FUNCTION FUNC, p
COMMON FUNC_XY, x, y
RETURN, MAX(ABS(y - (p(0) + p(1) * x)))
END
Put the data points into a common block so they are accessible to the
function:
COMMON FUNC_XY, x, y
Define the data points:
x = findgen(17)*5
y = [ 12.0, 24.3, 39.6, 51.0, 66.5, 78.4, 92.7, 107.8, 120.0, $
135.5, 147.5, 161.0, 175.4, 187.4, 202.5, 215.4, 229.9]
Call the function. Fractional tolerance = 1 part in 10^5,
Initial guess = [0,0], and the minimum should be found within
a distance of 100 of that point:
r = AMOEBA(1.0e-5, SCALE=1.0e2, P0 = [0, 0], FUNCTION_VALUE=fval)
Check for convergence:
if n_elements(r) eq 1 then message,'AMOEBA failed to converge'
Print results.
print, 'Intercept, Slope:', r, 'Function value (max error): ', fval(0)
Intercept, Slope: 11.4100 2.72800
Function value: 1.33000
MODIFICATION HISTORY:
DMS, May, 1996. Written.
(See amoeba.pro)
NAME: AUX_FUNCT_TIMELINE PURPOSE: different auxiliary functions for time conversions COMMENT: yes, it should be better documented.
(See aux_funct_timeline.pro)
NAME:
AVG
PURPOSE:
Calculate the average value of an array, or calculate the average
value over one dimension of an array as a function of all the other
dimensions.
CALLING SEQUENCE:
RESULT = AVG( ARRAY, [ DIMENSION ] )
INPUTS:
ARRAY = Input array. May be any type except string.
OPTIONAL INPUT PARAMETERS:
DIMENSION = Optional dimension to do average over, scalar
OUTPUTS:
The average value of the array when called with one parameter.
If DIMENSION is passed, then the result is an array with all the
dimensions of the input array except for the dimension specified,
each element of which is the average of the corresponding vector
in the input array.
For example, if A is an array with dimensions of (3,4,5), then the
command B = AVG(A,1) is equivalent to
B = FLTARR(3,5)
FOR J = 0,4 DO BEGIN
FOR I = 0,2 DO BEGIN
B(I,J) = TOTAL( A(I,*,J) ) / 4.
ENDFOR
ENDFOR
RESTRICTIONS:
Dimension specified must be valid for the array passed; otherwise the
input array is returned as the output array.
PROCEDURE:
AVG(ARRAY) = TOTAL(ARRAY)/N_ELEMENTS(ARRAY) when called with one
parameter.
MODIFICATION HISTORY:
William Thompson Applied Research Corporation
July, 1986 8201 Corporate Drive
Landover, MD 20785
Converted to Version 2 July, 1990
Replace SUM call with TOTAL W. Landsman May, 1992
(See avg.pro)
NAME:
BISECT_PDF
PURPOSE:
This function computes the cutoff value x such that the probabilty
of an observation from the given distribution, less than x, is a(0).
u and l are the upper and lower limits for x, respectively.
a(1) and a(2) are degrees of freedom, if appropriate.
funct is a string specifying the probability density function.
BISECT_PDF is not intended to be a user-callable function.
(See bisect_pdf.pro)
NAME: BIWEIGHT_MEAN PURPOSE: Calculate the center and dispersion (like mean and sigma) of a distribution using bisquare weighting. CALLING SEQUENCE: Mean = BIWEIGHT_MEAN( Vector, [ Sigma, Weights ] ) INPUTS: Vector = Distribution in vector form OUTPUT: Mean - The location of the center. OPTIONAL OUTPUT ARGUMENTS: Sigma = An outlier-resistant measure of the dispersion about the center, analogous to the standard deviation. The half-width of the 95% confidence interval = |STUDENT_T( .95, .7*(N-1) )*SIGMA/SQRT(N)|, where N = number of points. Weights = The weights applied to the data in the last iteration. SUBROUTINE CALLS: MED, which calculates a median REVISION HISTORY Written, H. Freudenreich, STX, 12/89 Modified 2/94, H.T.F.: use a biweighted standard deviation rather than median absolute deviation. Modified 2/94, H.T.F.: use the fractional change in SIGMA as the convergence criterion rather than the change in center/SIGMA.
(See biweight_mean.pro)
NAME: BOOST_ARRAY PURPOSE: Add array APPEND to array DESTINATION, allowing the dimensions of DESTINATION to adjust to accomodate it. If both input arrays have the same number of dimensions, then the output array will have one additional dimension. Otherwise, the last dimension of DESTINATION will be incremented by one. CATEGOBY: Utility CALLING SEQUENCE: BOOST_ARRAY, DESTINATION, APPEND INPUT: DESTINATION = Array to be expanded. APPEND = Array to append to DESTINATION. OUTPUTS: DESTINATION = Expanded output array. RESTRICTIONS: DESTINATION and APPEND have to be either both of type string or both of numerical types. APPEND cannot have more dimensions than DESTINATION. MODIFICATION HISTOBY: Written Aug'88 (DMZ, ARC) Modified Sep'89 to handle byte arrays (DMZ) Modifed to version 2, Paul Hick (ARC), Feb 1991 Removed restriction to 2D arrays, William Thompson (ARC), Feb 1992.
(See boost_array.pro)
NAME:
BSORT
PURPOSE:
Function to sort data into ascending order, like a simple bubble sort.
original subscript order is maintained when values are equal (FIFO).
(This differs from the IDL SORT routine alone, which may rearrange
order for equal values)
CALLING SEQUENCE:
result = bsort( array, [ asort, /INFO, /REVERSE ] )
INPUT:
Array - array to be sorted
OUTPUT:
result - sort subscripts are returned as function value
OPTIONAL OUTPUT:
Asort - sorted array
OPTIONAL KEYWORD INPUTS:
/REVERSE - if this keyword is set, and non-zero, then data is sorted
in descending order instead of ascending order.
/INFO = optional keyword to cause brief message about # equal values.
HISTORY
written by F. Varosi Oct.90:
uses WHERE to find equal clumps, instead of looping with IF ( EQ ).
compatible with string arrays, test for degenerate array
20-MAY-1991 JKF/ACC via T AKE- return indexes if the array to
be sorted has all equal values.
Aug - 91 Added REVERSE keyword W. Landsman
(See bsort.pro)
NAME:
CHISQR_CVF
PURPOSE:
This function computes the cutoff value (v) such that:
Probability(X > v) = p
where X is a random variable from the Chi-square distribution
with (df) degrees of freedom.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = chisqr_cvf(P, DF)
INPUTS:
P: A non-negative scalar, in the interval [0.0, 1.0], of type
float or double that specifies the probability of occurance
or success.
DF: A positive scalar of type integer, float or double that
specifies the degrees of freedom of the Chi-square distribution.
EXAMPLE:
Compute the cutoff value (v) such that Probability(X > v) = 0.100
from the Chi-square distribution with (DF = 3) degrees of freedom.
The result should be 6.25139
result = chisqr_cvf(0.100, 3)
REFERENCE:
ADVANCED ENGINEERING MATHEMATICS (seventh edition)
Erwin Kreyszig
ISBN 0-471-55380-8
MODIFICATION HISTORY:
Modified by: GGS, RSI, July 1994
Minor changes to code. New documentation header.
(See chisqr_cvf.pro)
NAME:
CHISQR_PDF
PURPOSE:
This function computes the probabilty (p) such that:
Probability(X <= v) = p
where X is a random variable from the Chi-square distribution
with (df) degrees of freedom.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = chisqr_pdf(V, DF)
INPUTS:
V: A scalar of type integer, float or double that specifies
the cutoff value.
DF: A positive scalar of type integer, float or double that
specifies the degrees of freedom of the Chi-square distribution.
EXAMPLES:
Compute the probability that a random variable X, from the Chi-square
distribution with (DF = 3) degrees of freedom, is less than or equal
to 6.25. The result should be 0.899939
result = chisqr_pdf(6.25, 3)
Compute the probability that a random variable X, from the Chi-square
distribution with (DF = 3) degrees of freedom, is greater than 6.25.
The result should be 0.100061
result = 1 - chisqr_pdf(6.25, 3)
REFERENCE:
ADVANCED ENGINEERING MATHEMATICS (seventh edition)
Erwin Kreyszig
ISBN 0-471-55380-8
MODIFICATION HISTORY:
Modified by: GGS, RSI, July 1994
Minor changes to code. New documentation header.
(See chisqr_pdf.pro)
compute_chisq Compute the reduced chi-squared per degree of freedom for a restored image. CALLING SEQUENCE: compute_chisq,blur,reblur,sigma,scale,chisq INPUTS: blur - original image or spectrum reblur - restored image or spectrum reconvolved with the point spread function sigma - standard deviation of the white noise scale - counts/flux unit for computing the Poisson noise. OPTIONAL KEYWORD INPUTS region - vector of 4 elements giving the region of the image to perform the chi-squared test. Default is the entire image. OUTPUT: chisq - reduced chi-square per degree of freedom. HISTORY: version 1 D. Lindler April 1992
(See compute_chisq.pro)
NOTE: This routine has been made obsolete because it has been replaced
by WIDGET_DROPLIST.
NAME:
CW_BSELECTOR
PURPOSE:
CW_BSELECTOR is a compound widget that appears as a pull-down
menu whose label shows the widget's current value. When the button
is pressed, the menu appears and the newly selected value becomes
the new title of the pull-down menu.
CATEGORY:
Compound widgets.
CALLING SEQUENCE:
widget = CW_BSELECTOR(Parent, Names)
To get or set the value of a CW_BSELECTOR, use the GET_VALUE and
SET_VALUE keywords to WIDGET_CONTROL. The value of a CW_BSELECTOR
is the index of the selected item.
INPUTS:
Parent: The ID of the parent widget.
Names: A string array, containing one string per button,
giving the name of each button.
KEYWORD PARAMETERS:
EVENT_FUNCT: The name of an optional user-supplied event function
for buttons. This function is called with the return
value structure whenever a button is pressed, and
follows the conventions for user-written event
functions.
FONT: The name of the font to be used for the button
titles. If this keyword is not specified, the default
font is used.
FRAME: Specifies the width of the frame to be drawn around
the base.
IDS: A named variable into which the button IDs will be
stored, as a longword vector.
LABEL_LEFT: Creates a text label to the left of the buttons.
LABEL_TOP: Creates a text label above the buttons.
MAP: If set, the base will be mapped when the widget
is realized (the default).
RETURN_ID: If set, the VALUE field of returned events will be
the widget ID of the button.
RETURN_INDEX: If set, the VALUE field of returned events will be
the zero-based index of the button within the base.
THIS IS THE DEFAULT.
RETURN_NAME: If set, the VALUE field of returned events will be
the name of the button within the base.
RETURN_UVALUE: An array of user values to be associated with
each button. Selecting the button sets the uvalue
of the CW_BSELECTOR to the button's uvalue and
returns the uvalue in the value field of the event
structure. If this keyword isn't specified, the
CW_BSELECTOR's uvalue remains unchanged.
SET_VALUE: The initial value of the buttons. This keyword is
set to the index of the Names array element desired.
So if it is desired that the initial value be the
second element of the Names array, SET_VALUE would
be set equal to 1. This is equivalent to the later
statement:
WIDGET_CONTROL, widget, set_value=value
UVALUE: The user value to be associated with the widget.
XOFFSET: The X offset of the widget relative to its parent.
YOFFSET: The Y offset of the widget relative to its parent.
OUTPUTS:
The ID of the created widget is returned.
SIDE EFFECTS:
This widget generates event structures with the following definition:
event = { ID:0L, TOP:0L, HANDLER:0L, INDEX:0, VALUE:0 }
The INDEX field is the index (0 based) of the menu choice. VALUE is
either the INDEX, ID, NAME, or BUTTON_UVALUE of the button,
depending on how the widget was created.
RESTRICTIONS:
Only buttons with textual names are handled by this widget.
Bitmaps are not understood.
MODIFICATION HISTORY:
1 April 1993, DMS, Adapted from CW_BGROUP.
22 Dec. 1993, KDB, Corrected documentation for keyword SET_VALUE.
(See cw_bselector.pro)
NAME:
DATE_CONV
PURPOSE:
Procedure to perform conversion of dates to one of three possible
formats.
format 1: real*8 scalar encoded as:
(year-1900)*1000 + day + hour/24. + min/24./60 + sec/24./60/60
where day is the day of year (1 to 366)
format 2: Vector encoded as:
date(0) = year (eg. 1987 or just 87)
date(1) = day of year (1 to 366)
date(2) = hour
date(3) = minute
date(4) = second
format 3: string (ascii text) encoded as
DD-MON-YEAR HH:MM:SS.SS
(eg. 14-JUL-1987 15:25:44.23)
format 4: three element vector giving spacecraft time words
from ST telemetry packet.
CALLING SEQUENCE
results = DATE_CONV( DATE, TYPE )
INPUTS:
DATE - input date in one of the three possible formats.
TYPE - type of output format desired. If not supplied then
format 3 (real*8 scalar) is used.
valid values:
'REAL' - format 1
'VECTOR' - format 2
'STRING' - format 3
TYPE can be abbreviated to the single character strings 'R',
'V', and 'S'.
Nobody wants to convert TO spacecraft time (I hope!)
OUTPUTS:
The converted date is returned as the function value.
HISTORY:
version 1 D. Lindler July, 1987
adapted for IDL version 2 J. Isensee May, 1990
(See date_conv.pro)
NAME:
DAYCNV
PURPOSE:
Converts julian dates to gregorian calendar dates
CALLING SEQUENCE:
DAYCNV, XJD, YR, MN, DAY, HR
INPUTS:
XJD = Julian date, double precision scalar or vector
OUTPUTS:
YR = Year (Integer)
MN = Month (Integer)
DAY = Day (Integer)
HR = Hours and fractional hours (Real). If XJD is a vector,
then YR,MN,DAY and HR will be vectors of the same length.
EXAMPLE:
IDL> DAYCNV, 2440000.D, yr, mn, day, hr
yields yr = 1968, mn =5, day = 23, hr =12.
WARNING:
Be sure that the julian date is specified as double precision to
maintain accuracy at the fractional hour level.
REVISION HISTORY:
Converted to IDL from Yeoman's Comet Ephemeris Generator,
B. Pfarr, STX, 6/16/88
(See daycnv.pro)
NAME: DETABIFY PURPOSE: Replaces tabs in character strings with the appropriate number of spaces. The number of space characters inserted is calculated to space out to the next effective tab stop, each of which is eight characters apart. CALLING SEQUENCE: Result = DETABIFY( CHAR_STR ) INPUT PARAMETERS: CHAR_STR = Character string variable (or array) to remove tabs from. OUTPUT: Result of function is CHAR_STR with tabs replaced by spaces. RESTRICTIONS: CHAR_STR must be a character string variable. MODIFICATION HISTORY: William Thompson, Feb. 1992.
(See detabify.pro)
NAME:
EXTAST
PURPOSE:
Extract astrometry parameters from a FITS image header.
The astrometry in the header can be in either CD (Coordinate
description) format, or CROTA and CDELT (AIPS-type) format.
However, the output astrometry will always be in CD format.
CALLING SEQUENCE:
EXTAST, hdr, [ astr, noparams ]
INPUT:
HDR - variable containing the FITS header (string array)
OUTPUTS:
ASTR - Anonymous structure containing astrometry info from the FITS
header. ASTR always contains the following tags (even though
some projections do not require all the parameters)
.CD - 2 x 2 array containing the astrometry parameters CD1_1 CD1_2
in DEGREES/PIXEL CD2_1 CD2_2
.CDELT - 2 element vector giving physical increment at reference pixel
.CRPIX - 2 element vector giving X and Y coordinates of reference pixel
(def = NAXIS/2)
.CRVAL - 2 element double precision vector giving R.A. and DEC of
reference pixel in DEGREES
.CTYPE - 2 element string vector giving projection types, default
['RA---TAN','DEC--TAN']
.LONGPOLE - scalar longitude of north pole (default = 180)
.PROJP1 - Scalar parameter needed in some projections
.PROJP2 - Scalar parameter needed in some projections
NOPARAMS - Scalar indicating the results of EXTAST
-1 = Failure - Header missing astrometry parameters
0 = Success - Header contains CD00n00m + CDELT* astrometry
1 = Success - Header contains CROTA + CDELT (AIPS-type) astrometry
2 = Success - Header contains CDn_m astrometry
PROCEDURE
EXTAST checks for astrometry parameters in the following order:
(1) the CD matrix CD1_1,CD1_2... plus CRPIX and CRVAL.
(2) the CD matrix CD001001,CD001002...plus CRPIX and CRVAL
(3) CROTA2 (or CROTA1) and CDELT plus CRPIX and CRVAL.
See the Memo: Representations of Celestial Coordinates in FITS by
Griesen and Calabretta, available at fits.cv.nrao.edu
NOTES:
(1) An anonymous structure is created to avoid structure definition
conflicts. This is needed because some projection systems
require additional dimensions (i.e. spherical cube
projections require a specification of the cube face).
PROCEDURES CALLED:
ZPARCHECK, SXPAR
REVISION HISTORY
Written by B. Boothman 4/15/86
Accept CD001001 keywords 1-3-88
Accept CD1_1, CD2_1... keywords W. Landsman Nov. 92
(See extast.pro)
NAME: FIND PURPOSE: Find positive brightness perturbations (i.e stars) in a 2 dimensional image and compute centroids, and shape parameters, Adapted from 1986 STSDAS version of DAOPHOT. CALLING SEQUENCE: find, image, [ x, y, flux, sharp, round, hmin, fwhm, roundlim, sharplim TEXTOUT = , /SILENT ] INPUTS: image - 2 dimensional image array (integer or real) for which one wishes to identify the stars present OPTIONAL INPUTS: FIND will prompt for these parameters if not supplied hmin - Threshold intensity for a point source - should generally be 3 or 4 sigma above background fwhm - FWHM to be used in the convolve filter sharplim - 2 element vector giving low and high cutoff for the sharpness statistic (Default: [0.2,1.0] ) roundlim - 2 element vector giving low and high cutoff for the roundness statistic (Default: [-1.0,1.0] ) OPTIONAL INPUT KEYWORDS: SILENT - Normally, FIND will write out each star that meets all selection criteria. If the SILENT keyword is set and non-zero, then this printout is suppressed. TEXTOUT - Controls output device (see the procedure TEXTOPEN) 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 OUTPUTS: x - vector containing x position of all stars identified by FIND y- vector containing y position of all stars identified by FIND flux - vector containing flux of identified stars as determined by a gaussian fit. Fluxes are NOT converted to magnitudes. sharp - vector containing sharpness statistic for identified stars round - vector containing roundness statistic for identified stars SYSTEM VARIABLES: The non-standard system variable TEXTOUT determines the output device if the keyword TEXTOUT is not supplied. See TEXTOPEN for more info. REVISION HISTORY: Written W. Landsman, STX February, 1987 Keyword textout added, J. Isensee, July, 1990 ROUND now an internal function in V3.1 W. Landsman July 1993 KEYWORD messi added to avoid info if everything is OK (CG) March 96
(See find.pro)
Project : SOHO - CDS
Name :
FXADDPAR
Purpose :
Add or modify a parameter in a FITS header array.
Explanation :
Use :
FXADDPAR, HEADER, NAME, VALUE, COMMENT
Inputs :
HEADER = String array containing FITS header. The maximum string
length must be equal to 80. If not defined, then FXADDPAR
will create an empty FITS header array.
NAME = Name of parameter. If NAME is already in the header the
value and possibly comment fields are modified. Otherwise a
new record is added to the header. If NAME is equal to
either "COMMENT" or "HISTORY" then the value will be added to
the record without replacement. In this case the comment
parameter is ignored.
VALUE = Value for parameter. The value expression must be of the
correct type, e.g. integer, floating or string. String
values of 'T' or 'F' are considered logical values.
Opt. Inputs :
COMMENT = String field. The '/' is added by this routine. Added
starting in position 31. If not supplied, or set equal to ''
(the null string), then any previous comment field in the
header for that keyword is retained (when found).
Outputs :
HEADER = Updated header array.
Opt. Outputs:
None.
Keywords :
BEFORE = Keyword string name. The parameter will be placed before the
location of this keyword. For example, if BEFORE='HISTORY'
then the parameter will be placed before the first history
location. This applies only when adding a new keyword;
keywords already in the header are kept in the same position.
AFTER = Same as BEFORE, but the parameter will be placed after the
location of this keyword. This keyword takes precedence over
BEFORE.
FORMAT = Specifies FORTRAN-like format for parameter, e.g. "F7.3". A
scalar string should be used. For complex numbers the format
should be defined so that it can be applied separately to the
real and imaginary parts.
Calls :
FXPAR, FXPARPOS
Common :
None.
Restrictions:
Warning -- Parameters and names are not checked against valid FITS
parameter names, values and types.
The required FITS keywords SIMPLE (or XTENSION), BITPIX, NAXIS, NAXIS1,
NAXIS2, etc., must be entered in order. The actual values of these
keywords are not checked for legality and consistency, however.
Side effects:
All HISTORY records are inserted in order at the end of the header.
All COMMENT records are also inserted in order at the end of the
header, but before the HISTORY records. The BEFORE and AFTER keywords
can override this.
All records with no keyword (blank) are inserted in order at the end of
the header, but before the COMMENT and HISTORY records. The BEFORE and
AFTER keywords can override this.
All other records are inserted before any of the HISTORY, COMMENT, or
"blank" records. The BEFORE and AFTER keywords can override this.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
William Thompson, Jan 1992, from SXADDPAR by D. Lindler and J. Isensee.
Differences include:
* LOCATION parameter replaced with keywords BEFORE and AFTER.
* Support for COMMENT and "blank" FITS keywords.
* Better support for standard FITS formatting of string and
complex values.
* Built-in knowledge of the proper position of required
keywords in FITS (although not necessarily SDAS/Geis) primary
headers, and in TABLE and BINTABLE extension headers.
William Thompson, May 1992, fixed bug when extending length of header,
and new record is COMMENT, HISTORY, or blank.
Written :
William Thompson, GSFC, January 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version :
Version 1, 12 April 1993.
(See fxaddpar.pro)
Project : SOHO - CDS Name : FXBCLOSE Purpose : Close a FITS binary table extension opened for read. Explanation : Closes a FITS binary table extension that had been opened for read by FXBOPEN. Use : FXBCLOSE, UNIT Inputs : UNIT = Logical unit number of the file. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : None. Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must have been opened with FXBOPEN. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See fxbclose.pro)
Project : SOHO - CDS Name : FXBFIND Purpose : Find column keywords in a FITS binary table header. Explanation : Finds the value of a column keyword for all the columns in the binary table for which it is set. For example, FXBFIND, UNIT, 'TTYPE', COLUMNS, VALUES, N_FOUND Would find all instances of the keywords TTYPE1, TTYPE2, etc. The array COLUMNS would contain the column numbers for which a TTYPEn keyword was found, and VALUES would contain the values. N_FOUND would contain the total number of instances found. Use : FXBFIND, [UNIT or HEADER], KEYWORD, COLUMNS, VALUES, N_FOUND [, DEFAULT ] Inputs : Either UNIT or HEADER must be passed. UNIT = Logical unit number of file opened by FXBOPEN. HEADER = FITS binary table header. KEYWORD = Prefix to a series of FITS binary table column keywords. The keywords to be searched for are formed by combining this prefix with the numbers 1 through the value of TFIELDS in the header. Opt. Inputs : DEFAULT = Default value to use for any column keywords that aren't found. If passed, then COLUMNS and VALUES will contain entries for every column. Otherwise, COLUMNS and VALUES only contain entries for columns where values were found. Outputs : COLUMNS = Array containing the column numbers for which values of the requested keyword series were found. VALUES = Array containing the found values. N_FOUND = Number of values found. The value of this parameter is unaffected by whether or not DEFAULT is passed. Opt. Outputs: None. Keywords : None. Calls : FXBFINDLUN, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: If UNIT is passed, then the file must have been opened with FXBOPEN. If HEADER is passed, then it must be a legal FITS binary table header. The type of DEFAULT must be consistent with the values of the requested keywords, i.e. both most be either of string or numerical type. The KEYWORD prefix must not have more than five characters to leave room for the three digits allowed for the column numbers. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See fxbfind.pro)
Project : SOHO - CDS Name : FXBFINDLUN() Purpose : Find logical unit number UNIT in FXBINTABLE common block. Explanation : Finds the proper index to use for getting information about the logical unit number UNIT in the arrays stored in the FXBINTABLE common block. Called from FXBCREATE and FXBOPEN. Use : Result = FXBFINDLUN( UNIT ) Inputs : UNIT = Logical unit number. Opt. Inputs : None. Outputs : The result of the function is an index into the FXBINTABLE common block. Opt. Outputs: None. Keywords : None. Calls : None. Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: If UNIT is not found in the common block, then it is added to the common block. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 21 July 1993. Added DHEAP variable to fix bug with variable length arrays. Version : Version 2, 21 July 1993.
(See fxbfindlun.pro)
Project : SOHO - CDS Name : FXBOPEN Purpose : Open binary table extension in a disk FITS file for reading. Explanation : Opens a binary table extension in a disk FITS file for reading. The columns are then read using FXBREAD, and the file is closed when done with FXBCLOSE. Use : FXBOPEN, UNIT, FILENAME, EXTENSION [, HEADER ] Inputs : FILENAME = Name of FITS file to be opened. EXTENSION = Either the number of the FITS extension, starting with the first extension after the primary data unit being one; or a character string containing the value of EXTNAME to search for. Opt. Inputs : None. Outputs : UNIT = Logical unit number of the opened file. Opt. Outputs: HEADER = String array containing the FITS binary table extension header. Keywords : NO_TDIM = If set, then any TDIMn keywords found in the header are ignored. Calls : FXBFINDLUN, FXBPARSE, FXHREAD, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The file must be a valid FITS file. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb 1992, based on READFITS by J. Woffard and W. Landsman. W. Thompson, Feb 1992, changed from function to procedure. W. Thompson, June 1992, fixed up error handling. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See fxbopen.pro)
Project : SOHO - CDS Name : FXBPARSE Purpose : Parse the binary table extension header. Explanation : Parses the binary table extension header, and store the information about the format of the binary table in the FXBINTABLE common block--called from FXBCREATE and FXBOPEN. Use : FXBPARSE, ILUN, UNIT, HEADER Inputs : ILUN = Index into the arrays in the FXBINTABLE common block. HEADER = FITS binary table extension header. Opt. Inputs : None. Outputs : None. Opt. Outputs: None. Keywords : NO_TDIM = If set, then any TDIMn keywords found in the header are ignored. Calls : FXBFIND, FXBTDIM, FXBTFORM, FXPAR Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: None. Side effects: Any TDIMn keywords found for bit arrays (format 'X') are ignored, since the dimensions would refer to bits, not bytes. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Feb. 1992. William Thompson, Jan. 1993, modified for renamed FXBTFORM and FXBTDIM. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See fxbparse.pro)
Project : SOHO - CDS Name : FXBREAD Purpose : Read a data array from a disk FITS binary table file. Explanation : Each call to FXBREAD will read the data from one column and one row from the FITS data file, which should already have been opened by FXBOPEN. One needs to call this routine for every column and every row in the binary table. FXBCLOSE will then close the FITS data file. Use : FXBREAD, UNIT, DATA, COL [, ROW ] Inputs : UNIT = Logical unit number corresponding to the file containing the binary table. COL = Column in the binary table to read data from, either as a character string containing a column label (TTYPE), or as a numerical column index starting from column one. Opt. Inputs : ROW = Either row number in the binary table to read data from, starting from row one, or a two element array containing a range of row numbers to read. If not passed, then the entire column is read in. Row must be passed for variable length arrays. Outputs : DATA = IDL data array to be read from the file. Opt. Outputs: None. Keywords : NOSCALE = If set, then the ouput data will not be scaled using the optional TSCAL and TZERO keywords in the FITS header. Default is to scale. VIRTUAL = If set, and COL is passed as a name rather than a number, then if the program can't find a column with that name, it will then look for a keyword with that name in the header. Such a keyword would then act as a "virtual column", with the same value for every row. DIMENSIONS = Vector array containing the dimensions to be used to read in the data. Bypasses any dimensioning information stored in the header. Ignored for bit arrays. If the data type is double-precision complex, then an extra dimension of 2 is prepended to the dimensions passed by the user. NANVALUE= Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are converted to this number. Ignored unless DATA is of type float, double-precision or complex. Calls : IEEE_TO_HOST, FXPAR, WHERENAN Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more information. Restrictions: The binary table file must have been opened with FXBOPEN. The data must be consistent with the column definition in the binary table header. The row number must be consistent with the number of rows stored in the binary table header. The number of elements implied by the dimensions keyword must not exceed the number of elements stored in the file. Side effects: If the DIMENSIONS keyword is used, then the number of data points read in may be less than the number of points stored in the table. If there are no elements to read in (the number of elements is zero), then the program sets !ERR to -1, and DATA is unmodified. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Jan 1992. W. Thompson, Feb 1992, modified to support variable length arrays. W. Thompson, Jun 1992, modified way that row ranges are read in. No longer works reiteratively. W. Thompson, Jun 1992, fixed bug where NANVALUE would be modified by TSCAL and TZERO keywords. W. Thompson, Jun 1992, fixed bug when reading character strings. Treats dimensions better when reading multiple rows. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 30 June 1993. Added overwrite keyword to REFORM call to speed up. Version 3, William Thompson, GSFC, 21 July 1993. Fixed bug with variable length arrays. Version 4, William Thompson, GSFC, 29 October 1993. Added error message for not finding column by name. Version : Version 4, 29 October 1993.
(See fxbread.pro)
Project : SOHO - CDS Name : FXBTFORM Purpose : Returns information about FITS binary table columns. Explanation : Procedure to return information about the format of the various columns in a FITS binary table. Use : FXBTFORM,HEADER,TBCOL,IDLTYPE,FORMAT,NUMVAL,MAXVAL Inputs : HEADER = Fits binary table header. Opt. Inputs : None. Outputs : TBCOL = Array of starting column positions in bytes. IDLTYPE = IDL data types of columns. FORMAT = Character code defining the data types of the columns. NUMVAL = Number of elements of the data arrays in the columns. MAXVAL = Maximum number of elements for columns containing variable length arrays, or zero otherwise. Opt. Outputs: None. Keywords : None. Calls : FXPAR Common : None. Restrictions: None. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, Feb. 1992, from TBINFO by D. Lindler. W. Thompson, Jan. 1993, renamed to be compatible with DOS limitations. Written : William Thompson, GSFC, February 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See fxbtform.pro)
Project : SOHO - CDS
Name :
FXHREAD
Purpose :
Reads a FITS header from an opened disk file.
Explanation :
Reads a FITS header from an opened disk file.
Use :
FXHREAD, UNIT, HEADER [, STATUS ]
Inputs :
UNIT = Logical unit number.
Opt. Inputs :
Outputs :
HEADER = String array containing the FITS header.
Opt. Outputs:
STATUS = Condition code giving the status of the read. Normally, this
is zero, but is set to !ERR if an error occurs, or if the
first byte of the header is zero (ASCII null).
Keywords :
None.
Calls :
None.
Common :
None.
Restrictions:
The file must already be positioned at the start of the header. It
must be a proper FITS file.
Side effects:
The file ends by being positioned at the end of the FITS header, unless
an error occurs.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
W. Thompson, Feb 1992, from READFITS by J. Woffard and W. Landsman.
W. Thompson, Aug 1992, added test for SIMPLE keyword.
Written :
William Thompson, GSFC, February 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version :
Version 1, 12 April 1993.
(See fxhread.pro)
Project : SOHO - CDS
Name :
FXPAR()
Purpose :
Obtain the value of a parameter in a FITS header.
Explanation :
The first 8 chacters of each element of HDR are searched for a match to
NAME. If the keyword is one of those allowed to take multiple values
("HISTORY", "COMMENT", or " " (blank)), then the value is taken
as the next 72 characters. Otherwise, it is assumed that the next
character is "=", and the value (and optional comment) is then parsed
from the last 71 characters. An error occurs if there is no parameter
with the given name.
Complex numbers are recognized as two numbers separated by one or more
space characters.
If a numeric value has no decimal point (or E or D) it is returned as
type LONG. If it contains more than 8 numerals, or contains the
character 'D', then it is returned as type DOUBLE. Otherwise it is
returned as type FLOAT
Use :
Result = FXPAR( HDR, NAME [, ABORT ] )
Result = FXPAR(HEADER,'DATE') ;Finds the value of DATE
Result = FXPAR(HEADER,'NAXIS*') ;Returns array dimensions as
;vector
Inputs :
HDR = FITS header string array (e.g. as returned by FXREAD). Each
element should have a length of 80 characters
NAME = String name of the parameter to return. If NAME is of the
form 'keyword*' then an array is returned containing values
of keywordN where N is an integer. The value of keywordN
will be placed in RESULT(N-1). The data type of RESULT will
be the type of the first valid match of keywordN found.
Opt. Inputs :
ABORT = String specifying that FXPAR should do a RETALL if a
parameter is not found. ABORT should contain a string to be
printed if the keyword parameter is not found. If not
supplied, FXPAR will return with a negative !err if a keyword
is not found.
Outputs :
The returned value of the function is the value(s) associated with the
requested keyword in the header array.
If the parameter is complex, double precision, floating point, long or
string, then the result is of that type. Apostrophes are stripped from
strings. If the parameter is logical, 1 is returned for T, and 0 is
returned for F.
If NAME was of form 'keyword*' then a vector of values are returned.
Opt. Outputs:
None.
Keywords :
COUNT = Optional keyword to return a value equal to the number of
parameters found by FXPAR.
COMMENTS= Array of comments associated with the returned values.
Calls :
GETTOK, STRNUMBER
Common :
None.
Restrictions:
None.
Side effects:
Keyword COUNT returns the number of parameters found.
The system variable !err is set to -1 if parameter not found, 0 for a
scalar value returned. If a vector is returned it is set to the number
of keyword matches found.
If a keyword occurs more than once in a header, a warning is given,
and the first occurence is used. However, if the keyword is "HISTORY",
"COMMENT", or " " (blank), then multiple values are returned.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
DMS, May, 1983, Written.
D. Lindler Jan 90 added ABORT input parameter
J. Isensee Jul,90 added COUNT keyword
W. Thompson, Feb. 1992, added support for FITS complex values.
W. Thompson, Oct. 1992, rewrote to change strategy for extracting
values to allow for non-standard formats and renamed to FXPAR.
Added COMMENT keyword.
Written :
David M. Stern, RSI, May 1983.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version :
Version 1, 12 April 1993.
(See fxpar.pro)
Project : SOHO - CDS Name : FXPARPOS() Purpose : Finds position to insert record into FITS header. Explanation : Finds the position to insert a record into a FITS header. Called from FXADDPAR. Use : Result = FXPARPOS(KEYWRD, IEND [, BEFORE=BEFORE ] [, AFTER=AFTER ]) Inputs : KEYWRD = Array of eight-character keywords in header. IEND = Position of END keyword. Opt. Inputs : None. Outputs : Result of function is position to insert record. Opt. Outputs: None. Keywords : BEFORE = Keyword string name. The parameter will be placed before the location of this keyword. For example, if BEFORE='HISTORY' then the parameter will be placed before the first history location. This applies only when adding a new keyword; keywords already in the header are kept in the same position. AFTER = Same as BEFORE, but the parameter will be placed after the location of this keyword. This keyword takes precedence over BEFORE. If neither BEFORE or AFTER keywords are passed, then IEND is returned. Calls : None. Common : None. Restrictions: KEYWRD and IEND must be consistent with the relevant FITS header. Side effects: None. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : William Thompson, Jan 1992. Written : William Thompson, GSFC, January 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version : Version 1, 12 April 1993.
(See fxparpos.pro)
Project : SOHO - CDS Name : FXREAD Purpose : Read basic FITS files. Explanation : Read the primary array from a disk FITS file. Optionally allows the user to read in only a subarray and/or every Nth pixel. Use : FXREAD, FILENAME, DATA [, HEADER [, I1, I2 [, J1, J2 ]] [, STEP ]] Inputs : FILENAME = String containing the name of the file to be read. Opt. Inputs : I1,I2 = Data range to read in the first dimension. If passed, then HEADER must also be passed. If not passed, or set to 0,0 then the entire range is read. J1,J2 = Data range to read in the second dimension. If passed, then HEADER and I1,J2 must also be passed. If not passed, or set to 0,0 then the entire range is read. STEP = Step size to use in reading the data. If passed, then HEADER must also be passed. Default value is 1. Ignored if less than 1. Outputs : DATA = Data array to be read from the file. Opt. Outputs: HEADER = String array containing the header for the FITS file. Keywords : NANVALUE = Value signalling data dropout. All points corresponding to IEEE NaN (not-a-number) are set to this value. Ignored unless DATA is of type float or double-precision. PROMPT = If set, then the optional parameters are prompted for at the keyboard. AVERAGE = If set, then the array size is reduced by averaging pixels together rather than by subselecting pixels. Ignored unless STEP is nontrivial. Note: this is much slower. YSTEP = If passed, then STEP is the step size in the 1st dimension, and YSTEP is the step size in the 2nd dimension. Otherwise, STEP applies to both directions. NOSCALE = If set, then the output data will not be scaled using the optional BSCALE and BZERO keywords in the FITS header. Default is to scale, if and only if BSCALE and BZERO are present and nontrivial. NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the optional HEADER array will not be changed. The default is to reset these keywords to BSCALE=1, BZERO=0. Ignored if NOSCALE is set. Calls : GET_DATE, IEEE_TO_HOST, FXADDPAR, FXHREAD, FXPAR, WHERENAN Common : None. Restrictions: Groups are not supported. The optional parameters I1, I2, and STEP only work with one or two-dimensional arrays. J1 and J2 only work with two-dimensional arrays. Use of the AVERAGE keyword is not compatible with arrays with missing pixels. Side effects: If the keywords BSCALE and BZERO are present in the FITS header, and have non-trivial values, then the returned array DATA is formed by the equation DATA = BSCALE*original + BZERO However, this behavior can overridden by using the /NOSCALE keyword. If the data is scaled, then the optional HEADER array is changed so that BSCALE=1 and BZERO=0. This is so that these scaling parameters are not applied to the data a second time by another routine. Also, history records are added storing the original values of these constants. Note that only the returned array is modified--the header in the FITS file itself is untouched. If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO keywords are not changed. It is then the user's responsibility to ensure that these parameters are not reapplied to the data. In particular, these keywords should not be present in any header when writing another FITS file, unless the user wants their values to be applied when the file is read back in. Otherwise, FITS readers will read in the wrong values for the data array. Category : Data Handling, I/O, FITS, Generic. Prev. Hist. : W. Thompson, May 1992, based in part on READFITS by W. Landsman, and STSUB by M. Greason and K. Venkatakrishna. W. Thompson, Jun 1992, added code to interpret BSCALE and BZERO records, and added NOSCALE and NOUPDATE keywords. W. Thompson, Aug 1992, changed to call FXHREAD, and to add history records for BZERO, BSCALE. Written : William Thompson, GSFC, May 1992. Modified : Version 1, William Thompson, GSFC, 12 April 1993. Incorporated into CDS library. Version 2, William Thompson, GSFC, 17 November 1993. Corrected bug with AVERAGE keyword on non-IEEE compatible machines. Corrected bug with subsampling on VAX machines. Version : Version 2, 17 November 1993.
(See fxread.pro)
NAME: GETTOK PURPOSE: Function to retrieve the first part of the string until the character char is encountered. CALLING SEQUENCE: token = gettok( st, char ) INPUT: char - character separating tokens, scalar string INPUT-OUTPUT: st - (scalar) string to get token from (on output token is removed) OUTPUT: token - scalar string value is returned EXAMPLE: If ST is 'abc=999' then gettok(ST,'=') would return 'abc' and ST would be left as '999' HISTORY version 1 by D. Lindler APR,86 Remove leading blanks W. Landsman (from JKF) Aug. 1991
(See gettok.pro)
NAME:
GET_DATE
PURPOSE:
Return the current date in DD/MM/YY format. This is the format
required by the DATE and DATE-OBS keywords in a FITS header
CALLING SEQUENCE:
GET_DATE, dte
INPUTS:
None
OUTPUTS:
dte = An eight character scalar string specifying the current day
(0-31), current month (1-12), and last two digits of the
current year
EXAMPLE:
Add the current date to the DATE keyword in a FITS header,h
IDL> GET_DATE,dte
IDL> sxaddpar, h, 'DATE', dte
REVISION HISTORY:
Written W. Landsman March 1991
(See get_date.pro)
NAME: IEEE_TO_HOST PURPOSE: To translate an IDL variable in IEEE-754 representation (as used, for example, in FITS data ), into the host machine architecture. CALLING SEQUENCE: IEEE_TO_HOST, data, [ IDLTYPE = , ] INPUT-OUTPUT PARAMETERS: data - any IDL variable, scalar or vector. It will be modified by IEEE_TO_HOST to convert from IEEE to host representation. Byte and string variables are returned by IEEE_TO_HOST unchanged OPTIONAL KEYWORD INPUTS: IDLTYPE - scalar integer (1-7) specifying the IDL datatype according to the code given by the SIZE function. This keyword is usually when DATA is a byte array to be interpreted as another datatype (e.g. FLOAT). EXAMPLE: A 2880 byte array (named FITARR) from a FITS record is to be interpreted as floating and converted to the host representaton: IDL> IEEE_TO_HOST, bytarr, IDLTYPE = 4 METHOD: The BYTEORDER procedure is called with the appropiate keyword RESTRICTION: Will run *much* faster for floating or double precision if the IDL version is since 2.2.2 when the /XDRTOF keyword became available to BYTEORDER. However, IEEE_TO_HOST should still work in earlier versions of IDL. Note that V3.0.0 has a bug in the /XDRTOD keyword on DecStations so IEEE_TO_HOST has a workaround. MODIFICATION HISTORY: Written, W. Landsman Hughes/STX May, 1992 Fixed error Case statement for float and double September 1992 Workaround to /XDRTOD problem on DecStations January 1993
(See ieee_to_host.pro)
NAME:
IGAMMA
PURPOSE:
This function computes the incomplete gamma function, Px(a).
CATEGORY:
Special Functions.
CALLING SEQUENCE:
Result = Igamma(a, x)
INPUTS:
A: A positive scalar of type integer, float or double that
specifies the parametric exponent of the integrand.
X: A positive scalar of type integer, float or double that
specifies the upper limit of integration.
KEYWORD PARAMETERS:
METHOD: Use this keyword to specify a named variable which returns
the method used to compute the incomplete gamma function.
A value of 0 indicates that a power series representation
was used. A value of 1 indicates that a continued fractions
method was used.
EXAMPLE:
Compute the incomplete gamma function for the corresponding elements
of A and X.
Define the parametric exponents.
A = [0.10, 0.50, 1.00, 1.10, 6.00, 26.00]
Define the the upper limits of integration.
X = [0.0316228, 0.0707107, 5.00000, 1.04881, 2.44949, 25.4951]
Allocate an array to store the results.
result = fltarr(n_elements(A))
Compute the incomplete gamma functions.
for k = 0, n_elements(A)-1 do $
result(k) = Igamma(A(k), X(k))
The result should be:
[0.742026, 0.293128, 0.993262, 0.607646, 0.0387318, 0.486387]
PROCEDURE:
IGAMMA computes the incomplete gamma function, Px(a), using either
a power series representation or a continued fractions method. If X
is less than or equal to A+1, a power series representation is used.
If X is greater than A+1, a continued fractions method is used.
REFERENCE:
Numerical Recipes, The Art of Scientific Computing (Second Edition)
Cambridge University Press
ISBN 0-521-43108-5
MODIFICATION HISTORY:
Written by: GGS, RSI, September 1994
IGAMMA is based on the routines: gser.c, gcf.c, and
gammln.c described in section 6.2 of Numerical Recipes,
The Art of Scientific Computing (Second Edition), and is
used by permission.
(See igamma.pro)
NAME:
IGAMMA_PDF
PURPOSE:
This function computes the incomplete gamma function using a series
representation. It is called by the probability density functions
in this directory. See the function IGAMMA() in the "math"
subdirectory for the user-callable version of the incomplete gamma
function.
MODIFICATION HISTORY:
Modified by: Jong Yi, Sept 1992
Increased iterations in g_series.pro
Modified by: GGS, RSI, July 1994
Minor changes to code.
(See igamma_pdf.pro)
NAME:
JULDATE
PURPOSE:
Convert from calender to Reduced Julian Date
CALLING SEQUENCE:
JULDATE, /PROMPT ;Prompt for Calender Date, print Julian Date
or
JULDATE, date, jd
INPUT:
DATE - 5-element array containing year,month (1-12),day,hour & minute
all specified as numbers (Universal Time). Year after 1900
can be specified 2 ways, either for example, as 83 or 1983.
Years B.C should be entered as negative numbers. If Hour or
Minute are not supplied, they will default to 0.
OUTPUT:
JD - reduced julian date, double precision scalar. To convert to
Julian Date, add 2400000. JULDATE will print the value of
JD at the terminal if less than 2 parameters are supplied, or
if the /PROMPT keyword is set
OPTIONAL INPUT KEYWORD:
PROMPT - If this keyword is set and non-zero, then JULDATE will prompt
for the calender date at the terminal.
RESTRICTIONS:
Will not work for years between 0 and 99 A.D. (since these are
interpreted as years 1900 - 1999). Will not work for year 1582.
The procedure HELIO_JD can be used after JULDATE, if a heliocentric
Julian date is required.
EXAMPLE:
A date of 25-DEC-1981 06:25 UT may be expressed as either
IDL> juldate, [81,12,25,6,25], jd
IDL> juldate, [1981,12,25.2673611], jd
In either case, one should obtain a reduced julian date of
JD = 44963.7673611
REVISION HISTORY
Adapted from IUE RDAF (S. Parsons) 8-31-87
Algorithm from Sky and Telescope April 1981
Added /PROMPT keyword, W. Landsman September 1992
(See juldate.pro)
+
*NAME: LUCY_GUESS
*PURPOSE: Richardson-Lucy alg. for deconvolving spectra using Bayesian methods.
Requires the point spread function.
*CALLING SEQUENCE:
LUCY_GUESS, n_iter, f, psf, new, guess=guess, conv_guess=conv_guess
*PARAMETERS:
INPUT:
n_iter - (REQ) - (0) - (I,L) - Number of iterations.
f - (REQ) - (1,2) - (I,R,L,D) - Measured flux vector.
psf - (REQ) - (1,2) - (I,R,L,D) - Point spread function,
binned to 1 diode resolution.
OPTIONAL INPUT PARAMETER:
guess - (1,2) - (I,R,L,D) - Guess of form of the deconvolved
spectrum.
conv_guess - (logical) - Flag to convol the optional paramter GUESS.
Note: GUESS is required to use CONV_GUESS.
OUTPUT:
NEW - (REQ) - (1) - (I,R,L,D) - Deconvolved spectrum.
*SUBROUTINES CALLED:
CONVOL
*EXAMPLES:
*RESTRICTIONS:
Requires the point spread function to be computed previously.
*MODIFICATION HISTORY:
Ver 1.0 - 01/10/90 - S. Shore - GSFC
Ver 1.1 - 10/19/90 - S. Shore - GSFC - Reverses PSF to conform with
IDL convolution procedure.
Ver 2.0 - 12/15/90 - J. Blackwell - GSFC - Modified to conform with
GHRS DAF standards.
1/23/92 JKF/ACC - moved to IDL V2.
4/9/92 RDR Version 2.1 - revised I/O
4/9/92 JKF/ACC - added optional parameters
Ver 3.0 - 4/27/92 - SNS - GSFC - Modified reversal of psf
for calculating weight.
(See lucy_guess.pro)
NAME: MATCH PURPOSE: Routine to match values in two vectors. CALLING SEQUENCE: match, a, b, suba, subb INPUTS: a,b - two vectors to match elements OUTPUTS: suba - subscripts of elements in vector a with a match in vector b subb - subscripts of the positions of the elements in vector b with matchs in vector a. suba and subb are ordered such that a(suba) equals b(subb) OPTIONAL KEYWORD OUTPUT: COUNT - set to the number of matches, integer scalar SIDE EFFECTS: !ERR is set to the number of matches, can be used instead of COUNT RESTRICTIONS: a and b should not have duplicate values within them. You can use rem_dup function to remove duplicate values in a vector EXAMPLE: If a = [3,5,7,9,11] & b = [5,6,7,8,9,10] then IDL> match, a, b, suba, subb, COUNT = count will give suba = [1,2,3], subb = [0,2,4], COUNT = 3 and suba(a) = subb(b) = [5,7,9] HISTORY: D. Lindler Mar. 1986. Fixed "indgen" call for very large arrays W. Landsman Sep 1991 Added COUNT keyword W. Landsman Sep. 1992
(See match.pro)
maxlike2 Computes the maximum likelyhood deconvolution. CALLING SEQUENCE: maxlike2,blur,psf,iter,fftp,reblur,/init,niter=N, scale=R,sigma=R,chimin=R,convar=R,stall=R,display=S,region=V, header=A INPUTS: blur - unrestored raw image psf - point spread function (normalized to total = 1.0) INPUTS/OUTPUTS: iter - restored image. if undefined, set to a scalar, or keyword INIT is specified it will be initialized with all pixels having the average flux value of BLUR OPTIONAL INPUTS/OUTPUTS: fftp - the fft of the psf. If not defined or if INIT is specified then then it will be an output parameter. reblur - The convolution of iter with the PSF. If not defined or INIT is specified, it will be computed by the routine for the input ITER. Upon output it will the the convolution of the output ITER with the PSF. OPTIONAL KEYWORD PARAMETER INPUTS: /INIT - specifies that X and FFTP should be initialized. This should only be used on the first call. NITER=n - specifies the maximum number of iterations. Default = 50 SCALE=r - specifies the number of Poisson counts per flux unit. This is used by the Chi-sqaure termination test. If set to 0.0 then only white noise is assumed. (default = 1.0) SIGMA=r - standard deviation of the white noise. This is used by the Chi-squared termination test. (default = 0.0) CHIMIN=r - Chi-squared value required for termination. Default=1.0 If set to 0.0 this test is disabled. CONVAR=r - Co-variance of the white noise for the modifed Lucy algorithm. (see method). (Default = 0.0) STALL=r - If the chi-squared changes by less than STALL, the iterations are assumed to be stalled and processing is terminated. (default = 0.001). If set to 0.0 this test is disabled. DISPLAY - IDL command to display the ITER. examples: DISPLAY = 'tvscl,alog(iter>0.01<100.0)' DISPLAY = 'contour,iter>0' if not supplied then the iteration is not displayed REGION - region of image to use for the chi-squared test given as a 4 element vector [starting sample, ending sample, staring line, ending line]. Default is to use the entire image. HEADER - input/output FITS header. If supplied it will be updated with restoration history. METHOD: Let: b = unrestored raw input image p = point spread function x = previous iteration (each pixel is initialized to the average value in b for the 0th iteration) C(q,t) = the convolution of q and t pr = 180 degree rotation of p cx = previous iteration convolved with the psf, C(x,p) Each iteration is computed by: CASE 1: CONVAR = 0.0, SCALE>0 (standard Lucy algorithm) x = x * C( b/cx,pr) CASE 2: CONVAR>0, SCALE>0 (Modified Lucy alogorithm to include white (Gaussian Noise) in addition to Poisson noise x = x * C( (b+CONVAR)/(cx+CONVAR) , pr) CASE 3: SCALE = 0 White (Gaussian) noise only x = x + C(b-cx,pr) EXAMPLES: Straight Lucy alogorithm with 7.5 counts per unit flux (WFPC). Default termination (maximum of 50 iterations) MAXLIKE2,blur, psf, result, /init, scale=7.5 Do 80 iterations of the standard lucy algorithm with no tests for termination. Follow it with 40 more. result = 0 ;set to scalar, (same as using /INIT) MAXLIKE2,blur,psf,result,chimin=0,stall=0,niter=80 MAXLIKE2,blur,psf,result,chimin=0,stall=0,niter=40 Lucy modified to include Poisson noise and additive Gaussian noise with a variance of 4.0. Results are displayed on the image display after each iteration. MAXLIKE2,blur,psf,result,/init,convar=4.0,sigma=2.0, $ display='tvscl,iter<100'
(See maxlike2.pro)
NAME MED PURPOSE Compute the median of an array, which may be of even length. CALLING SEQUENCE: MID_VALUE = MED(A) OUTPUTS The median of array A REVISION HISTORY: H.T. Freudenreich, ?/89
(See med.pro)
NAME: MEDSMOOTH PURPOSE: Median smoothing of a vector, including pointe near its ends. CALLING SEQUENCE: SMOOTHED = MEDSMOOTH( VECTOR, WINDOW_WIDTH ) INPUTS: VECTOR = The vector to be smoothed WINDOW = The full width of the window over which the median is determined for each point. OUTPUT: Function returns the smoothed vector SUBROUTINES CALLED: MEDIAN, to find the median PROCEDURE: Each point is replaced by the median of the nearest WINDOW of points. The width of the window shrinks towards the ends of the vector, so that only the first and last points are not filtered. These points are replaced by forecasting from smoothed interior points. REVISION HISTORY: Written, H. Freudenreich, STX, 12/89 H.Freudenreich, 8/90: took care of end-points by shrinking window. Bug by end-points fixed - JA+CG 6/99
(See medsmooth.pro)
NAME: MEDSMOOTH PURPOSE: Median smoothing of a vector, including pointe near its ends. CALLING SEQUENCE: SMOOTHED = MEDSMOOTH( VECTOR, WINDOW_WIDTH ) INPUTS: VECTOR = The vector to be smoothed WINDOW = The full width of the window over which the median is determined for each point. OUTPUT: Function returns the smoothed vector SUBROUTINES CALLED: MEDIAN, to find the median PROCEDURE: Each point is replaced by the median of the nearest WINDOW of points. The width of the window shrinks towards the ends of the vector, so that only the first and last points are not filtered. These points are replaced by forecasting from smoothed interior points. REVISION HISTORY: Written, H. Freudenreich, STX, 12/89 H.Freudenreich, 8/90: took care of end-points by shrinking window.
(See test.pro)
mem2 Computes the maximum likelyhood deconvolution. CALLING SEQUENCE: mem2,blur,psf,iter,fftp,lambda,/init,niter=N, scale=R,sigma=R,chimin=R,stall=R,display=S,region=V, header=S INPUTS: blur - unrestored raw image psf - point spread function (normalized to total = 1.0) INPUTS/OUTPUTS: iter - restored image. if undefined, set to a scalar, or keyword INIT is specified it will be initialized with all pixels having the average flux value of BLUR OPTIONAL INPUTS/OUTPUTS: lambda - internal array used by the routine. If you want to continue iterating in a subsequent call you must supply this array in the calling sequence and supply it in subsequent calls. If keyword /INIT is specified, lambda is undefined or lambda is set to a scalar, MEM2 initializes lambda (0th iteration). fftp - the fft of the psf. If not defined or if INIT is specified then then it will be computed and returned as an output. It can be passed to subsequent calls to save computing time. OPTIONAL KEYWORD PARAMETER INPUTS: /INIT - specifies that X and FFTP should be initialized. This should only be used on the first call. NITER=n - specifies the maximum number of iterations. Default = 50. (on output it gives the actual number of iterations completed). SCALE=r - specifies the number of Poisson counts per flux unit. This is used by the Chi-sqaure termination test. If set to 0.0 then only white noise is assumed. (default = 1.0) SIGMA=r - standard deviation of the white noise. This is used by the Chi-squared termination test. (default = 0.0) CHIMIN=r - Chi-squared value required for termination. Default=1.0 If set to 0.0 this test is disabled. STALL=r - If the chi-squared changes by less than STALL, the iterations are assumed to be stalled and processing is terminated. (default = 0.001). If set to 0.0 this test is disabled. DISPLAY - IDL command to display the ITER. examples: DISPLAY = 'tvscl,alog(iter>0.01<100.0)' DISPLAY = 'contour,iter>0' if not supplied then the iteration is not displayed REGION - region of image to use for the chi=squared test given as a four element vector, [starting sample, ending sample, starting line, ending line]. Default is to use the entire image. HEADER - input/output FITS header. If supplied it will be updated with restoration history. METHOD: From Hollis, and Dorband, "Comparing Restored and VLA imagery of R. Aquarii" AJ (1992 Feb. 10). Let: b = unrestored raw input image p = point spread function lambda = lambda's from the previous iteration. They are all set to 0.0 for the 0th iteration C(q,t) = the convolution of q and t pr = 180 degree rotation of p The next iteration is computed by: d = exp(C(lambda,pr) d = d/total(d) x = C(d,p) lambda = lambda + alog(b/x/total(b)) ;updated lambda's x = x*total(b) ;resulting image All convolutions are computed with FFT's EXAMPLES: Do up to 50 iterations with standard termination tests for Poison statistics: mem2,blur,psf,result Do 80 iterations with no tests for termination. Follow it with 40 more. mem2,blur,psf,result,lambda,chimin=0,stall=0,niter=80,/init mem2,blur,psf,result,lambda,chimin=0,stall=0,niter=40 Use both Poisson noise (where 1 flux unit = 7.5 counts) and additive Gaussian noise with a sigma of 2.0 for testing convergence. Results are displayed on the image display after each iteration. mem2,blur,psf,result,scale=7.5,sigma=2.0, $ display='tvscl,iter<100'
(See mem2.pro)
NAME:
MOMENT
PURPOSE:
This function computes the mean, variance, skewness and kurtosis
of an n-element vector.
CATEGORY:
Statistics.
CALLING SEQUENCE:
Result = Moment(X)
INPUTS:
X: An n-element vector of type integer, float or double.
KEYWORD PARAMETERS:
MDEV: Use this keyword to specify a named variable which returns
the mean absolute deviation of X.
SDEV: Use this keyword to specify a named variable which returns
the standard deviation of X.
EXAMPLE:
Define the n-element vector of sample data.
x = [65, 63, 67, 64, 68, 62, 70, 66, 68, 67, 69, 71, 66, 65, 70]
Compute the mean, variance, skewness and kurtosis.
result = moment(x)
The result should be the 4-element vector:
[66.7333, 7.06667, -0.0942851, -1.18258]
PROCEDURE:
MOMENT computes the first four "moments" about the mean of an
n-element vector of sample data. The computational formulas
are given in the Univariate Statistics section of the Mathematics
Guide.
REFERENCE:
APPLIED STATISTICS (third edition)
J. Neter, W. Wasserman, G.A. Whitmore
ISBN 0-205-10328-6
MODIFICATION HISTORY:
Written by: GGS, RSI, August 1994
(See moment.pro)
NAME: OPLOTERR PURPOSE: Overplot data points with accompanying error bars. CATEGORY: Plotting, 2-dimensional. CALLING SEQUENCE: OPLOTERR, [ X ,] Y , Err [, Psym ] INPUTS: Y: The array of Y values. Err: The array of error bar values. OPTIONAL INPUT PARAMETERS: X: An optional array of X values. The procedure checks whether or not the third parameter passed is a vector to decide if X was passed. If X is not passed, then INDGEN(Y) is assumed for the X values. PSYM: The plotting symbol to use (default = +7). COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: Arrays cannot be of type string. There must be enough points to plot. PROCEDURE: A plot of X versus Y with error bars drawn from Y - ERR to Y + ERR is written to the output device over any plot already there. MODIFICATION HISTORY: William Thompson Applied Research Corporation July, 1986 8201 Corporate Drive Landover, MD 20785 Loop variable = Longtype to allow for more than 32756 points Carlos GABRIEL (ESA/SAI) June 1996
(See oploterr.pro)
NAME:
PIA_PROC_GEN
PURPOSE:
Menu and procedure within the PIA to get automatically
a sequence of steps to be performed, without major interaction.
Data reduction from ERD up to SPD level, including calibration.
CATEGORY:
PIA - processing
CALLING SEQUENCE:
PIA_PROC_GEN
INPUTS:
none
KEYWORD PARAMETERS:
SRD: If present, processing stopped at SRD level
SCP: If present, processing stopped at SCP level
FROM_SRD: If present, processing started at SRD level
FROM_SCP: If present, processing started at SCP level
ABS_PHT: Absolute photometry ('dark'+'straylight' recognition)
SPARSE_MAP: Sparse map case
PER_RPID: Reduce long measurement dividing per RPID
AUTO_REC: Recognize for AOT type and reduce accordingly
GROUP: The group leader of this widget hierarchy
OUTPUTS:
none
SIDE EFFECTS:
If the FITS files are chosen as input, the ERD dynamical structure
is expanded with all the measurements contained in those files.
The dynamical structures containing the SRD, SCP and SPD levels
are expanded with all the measurements to be processed.
COMMON BLOCKS:
phterd: ERD dynamical structure
phtsrd: SRD dynamical structure
phtscp: SCP dynamical structure
phtspd: SPD dynamical structure
phtresact: actual responsivities
deglitch_param: parameters for deglitching procedure
PROCEDURES USED:
PIA Procedure(s):
deglitch_param_init
lin_voltages
pia_gencho
pia_load_ierd
pia_load_iscp
pia_load_isrd
pia_pickfile
pia_respons
pia_rodisc
pia_sigdisc
pickmeas
process_erd
process_scp
process_srd
read_erd
respons_interpol
Internal:
pia_proc_gen_event
MODIFICATION HISTORY:
Written by: Carlos Gabriel (ESA/ESTEC) January 1995
Last Modification:
P05/P25 case extended & saves also,
new use of gen_choices (CG) April 1997
V6.2
Batch and per RPID modes integrated,
correction for reset interval and vignetting and
ramps sub-division capability added (CG) May 1997
Still some improvements to provide more info in the
log screen (JAcosta) June 1997
V6.3
Using subtr_darstr_meas extension +
correct treatment of RPID division +
extension in responsivity choices (CG) June 1997
V6.4
Using decoded administration names &
Stop at SCP if per raster point (CG) September 1997
V6.5
call to add_coordinates changed (JAc) February 1998
FCS limits check -> def.Resp. if OoL (CG) February 1998
V7.0
Problem with FCSN=-1 fixed (CG) February 1998
Def. Resp. also for interpolation if OoL (CG) March 1998
2 Threshold deglitching added (CG) March 1998
Default responsivity choice corrected for sequences
with more than 2 calibration measurements (CG) March 1998
If chopped meas. corrected for signal loss default
response is taken automatically (CG) May 1998
V7.1
(See PIA_script_example.pro)
NAME:
PIA_STRUCTURES_HELP
PURPOSE:
Print information on the dynamical PIA buffers
CATEGORY:
PIA - help
CALLING SEQUENCE:
pia_structures_help, [/phterd], [/phtsrd], ...
INPUT KEYWORDS:
phterd: To obtain info on phterd
phtsrd: To obtain info on phtsrd
phtscp: To obtain info on phtscp
phtspd: To obtain info on phtspd
phtaap: To obtain info on phtaap
PROCEDURES USED:
Common Block(s) or @ procedure(s):
phterd
phtsrd
phtscp
phtspd
phtaap
MODIFICATION HISTORY:
Written by: C. Gabriel (ESA-SAI) July 1996
(See pia_structures_help.pro)
NAME: POLY_SMOOTH PURPOSE: Reduce noise in 1-D data (e.g. time-series, spectrum) but retain dynamic range of variations in the data by applying a least squares smoothing polynomial filter, also called the Savitzky-Golay smoothing filter, 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 make WIDTH between 1 and 2 times the FWHM of desired features. KEYWORDS: DEGREE = degree of polynomials to use in designing the filter via least squares fits, (default DEGREE = 2), and the higher degrees will preserve sharper features. NLEFT = # of past data points to use in filter convolution, excluding current point, overrides width parameter, so that width = NLEFT + NRIGHT + 1. (default = NRIGHT) NRIGHT = # of future data points to use (default = NLEFT). DERIV_ORDER = order of derivative desired (default = 0, no derivative). COEFFICIENTS = optional output of the filter coefficients applied, but they are all stored in common block for reuse, anyway. RESULTS: Function returns the data convolved with polynomial filter coefs. 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.
(See poly_smooth.pro)
fft_psf compute fft of a point spread function inserted into an image with the same size as an input image INPUTS: image - image with size of the desired psf fft. psf - point spread function OUTPUTS: fftp - fft of the psf HISTORY: version 1 D. Lindler
(See psf_fft.pro)
NAME: psf_Gaussian PURPOSE: Return a point spread function having Gaussian profiles, as either a 1D vector, a 2D image, or 3D volumetric-data. CALLING: psf = psf_Gaussian( NPIXEL=, FWHM= , [/NORMALIZE, /ST_DEV, ) or: psf = psf_Gaussian( parameters, NPIXEL = ) REQUIRED KEYWORDS: 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.
(See psf_gaussian.pro)
NAME: RADEC PURPOSE: To convert right ascension and declination from decimal degrees to sexigesimal hours (for R.A.) and degrees( for Dec.). 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
(See radec.pro)
NAME:
READCOL
PURPOSE:
Read a free-format ASCII data file with columns of data into IDL
variables. Lines of data not meeting the specified format (e.g.
comments) are ignored. Columns may be separated by commas or spaces.
Use READFMT to read a fixed-format ASCII file.
CALLING SEQUENCE:
readcol, name, v1, [ v2, v3, v4, v5, ... v30 ,
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,...V15 - IDL vectors to contain columns of data.
Up to 30 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, SPEC_DIR, REPCHR, STRNUMBER
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.
Read a maximum of 30 cols. Carlos Gabriel, ESA-SAI, 14-JUL-97.
(See readcol.pro)
NAME:
REMCHAR
PURPOSE:
Remove all appearances of character (char) from string (st)
CALLING SEQUENCE:
REMCHAR, ST, CHAR
INPUTS:
ST - String from which character will be removed.
CHAR- Character to be removed from string.
EXAMPLE:
If a = 'a,b,c,d,e,f,g' then
IDL> remchar,a, ','
will give a = 'abcdefg'
REVISIONS HISTORY
Written D. Lindler October 1986
Test if empty string needs to be returned W. Landsman Feb 1991
(See remchar.pro)
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)
NAME: REPCHR PURPOSE: Replace all occurences of one character with another in a text string. (Use the procedure REPSTR to replace more than one character.) CALLING SEQUENCE: new = repchr( old, c1, [c2] ) INPUTS: OLD = text string to edit, scalar or vector C1 = character to replace. OPTIONAL INPUTS: C2 = character to insert (def = ' ' = space). OUTPUTS: NEW = edited string. EXAMPLE: If old = 'THIS_IS_THE_TEXT' and c1 = '_' then IDL> print, repchr( old,c1 ) would display 'THIS IS THE TEXT' MODIFICATION HISTORY: R. Sterner. 28 Oct, 1986. Removed call to ARRAY function, W. Landsman December, 1991
(See repchr.pro)
NAME: ROBUST_SIGMA PURPOSE: Calculate a resistant estimate of the dispersion of a distribution. For an uncontaminated distribution, this is identical to the standard deviation. CALLING SEQUENCE: result = ROBUST_SIGMA( Y, [ /ZERO ] ) INPUT: Y = Vector of quantity for which the dispersion is to be calculated OPTIONAL INPUT KEYWORD: ZERO - if set, the dispersion is calculated w.r.t. 0.0 rather than the central value of the vector. If Y is a vector of residuals, this should be set. OUTPUT: ROBUST_SIGMA returns the dispersion. In case of failure, returns value of -1.0 SUBROUTINE CALLS: MED, which calculates the median PROCEDURE: Use the median absolute deviation as the initial estimate, then weight points using Tukey's Biweight. See, for example, "Understanding Robust and Exploratory Data Analysis," by Hoaglin, Mosteller and Tukey, John Wiley & Sons, 1983. REVSION HISTORY: H. Freudenreich, STX, 8/90
(See robust_sigma.pro)
NAME: SIGMA PURPOSE: Calculate the standard deviation value of an array, or calculate the standard deviation over one dimension of an array as a function of all the other dimensions. CATEGORY: Statistics. CALLING SEQUENCE: Result = SIGMA(Array) Result = SIGMA(Array, N_Par) Result = SIGMA(Array, N_Par, Dimension) INPUTS: Array: The input array of any type except string. OPTIONAL INPUT PARAMETERS: N_Par: The number of parameters. The default value is zero. The number of degrees of freedom is N_ELEMENTS(Array) - N_Par. The value of sigma varies as one over the square root of the number of degrees of freedom. Dimension: The dimension to do standard deviation over. OUTPUTS: SIGMA returns the standard deviation value of the array when called with one parameter. If DIMENSION is passed, then the result is an array with all the dimensions of the input array except for the dimension specified, each element of which is the standard deviation of the corresponding vector in the input array. For example, if A is an array with dimensions of (3,4,5), then the command: B = SIGMA(A,N,1) is equivalent to B = FLTARR(3,5) FOR J = 0,4 DO BEGIN FOR I = 0,2 DO BEGIN B(I,J) = SIGMA(A(I,*,J), N) ENDFOR ENDFOR COMMON BLOCKS: None. SIDE EFFECTS: None. RESTRICTIONS: The dimension specified must be valid for the array passed, otherwise the input array is returned as the output array. PROCEDURE: When DIMENSION is passed, then the function SUM is used. MODIFICATION HISTORY: William Thompson Applied Research Corporation July, 1986 8201 Corporate Drive Landover, MD 20785 DMS, May, 1993 Removed AVG fcn, use new features of TOTAL.
(See sigma.pro)
NAME:
SINCE_VERSION
PURPOSE:
Determine if the current release of IDL (as given in the
!VERSION.RELEASE system variable) comes after the user specified
release.
CALLING SEQUENCE:
test = SINCE_VERSION( release )
INPUT:
release - scalar string, must be formatted exactly like the
!VERSION.RELEASE system variable (e.g. '3.0.0')
OUTPUT:
test - 1 if current release is identical or later than the specified
'release' else 0
EXAMPLE:
Use the /FTOXDR keyword to the BYTEORDER procedure if the current
release of IDL is 2.2.2 or later
IDL> if since_version('2.2.2') then byteorder, a, /FTOXDR
REVISION HISTORY:
Written Wayne Landsman Hughes/STX January, 1992
Corrected algorithm W. Landsman April, 1992
(See since_version.pro)
NAME: SIXTY() PURPOSE: Converts decimal number to sexigesimal. Reverse of TEN function. CALLING SEQUENCE: X = SIXTY( SCALAR ) INPUTS: SCALAR -- Decimal quantity. OUTPUTS: Function value returned = double 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. MODIFICATION HISTORY: Written by R. S. Hill, STX, 19-OCT-87 Output changed to single precision. RSH, STX, 1/26/88
(See sixty.pro)
NAME: SIZE_STRUCT PURPOSE: Obtain the size in bytes of an IDL structure definition. CATEGORY: Structures 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).
(See size_struct.pro)
NAME: STORE_ARRAY PURPOSE: Insert array INSERT into array DESTINATION, allowing the dimensions of DESTINATION to adjust to accomodate it. CATEGOBY: Utility CALLING SEQUENCE: STORE_ARRAY, DESTINATION, INSERT, INDEX INPUT: DESTINATION = Array to be expanded. INSERT = Array to insert into DESTINATION. INDEX = Index of the final dimension of DESTINATION to insert INSERT into. OUTPUTS: DESTINATION = Expanded output array. If both input arrays have the same number of dimensions, then the DESTINATION will be replaced with INSERT. RESTRICTIONS: DESTINATION and INSERT have to be either both of type string or both of numerical types. INSERT must not have more dimensions than DESTINATION. MODIFICATION HISTOBY: William Thompson, Feb. 1992, from BOOST_ARRAY by D. Zarro and P. Hick.
(See store_array.pro)
NAME:
STRNUMBER
PURPOSE:
Function to determine if a string is a valid numeric value.
CALLING SEQUENCE:
result = strnumber( st, [val] )
INPUTS:
st - any IDL scalar string
OUTPUTS:
1 is returned as the function value if the string st has a
valid numeric value, otherwise, 0 is returned.
OPTIONAL OUTPUT:
val - (optional) value of the string. real*8
WARNING:
(1) In V2.2.2 there was a bug in the IDL ON_IOERROR procedure that
will cause the following statement to hang up IDL
IDL> print,'' + string( strnumber('xxx') )
This bug was fixed in V2.3.0
(2) In V2.3.2, an IDL bug is seen in the following statements
IDL> st = 'E'
IDL> q = strnumber(st) & print,st
The variable 'st' gets modified to an empty string. This problem
is related to the ambiguity of whether 'E' is a number or not
(could be = 0.0E). This bug was fixed in V3.0.0
(3) STRNUMBER was modified in February 1993 to include a special
test for empty or null strings, which now returns a 0 (not a
number). Without this special test, it was found that a
empty string (' ') could corrupt the stack.
HISTORY:
version 1 By D. Lindler Aug. 1987
test for empty string, W. Landsman February, 1993
(See strnumber.pro)
NAME:
SXPAR
PURPOSE:
Obtain the value of a parameter in a FITS header
CALLING SEQUENCE:
result = SXPAR( hdr, name,[ abort, COUNT= ])
INPUTS:
Hdr = FITS header array, (e.g. as returned by SXOPEN or READFITS)
string array, each element should have a length of 80
characters
Name = String name of the parameter to return. If Name is of
the form 'keyword*' then an array is returned containing
values of keywordN where N is an integer. The value
of keywordN will be placed in RESULT(N-1). The data type
of RESULT will be the type of the first valid match of keywordN
found.
OPTIONAL INPUTS:
ABORT - string specifying that SXPAR should do a RETALL
if a parameter is not found. ABORT should contain
a string to be printed if the keyword parameter is not found.
If not supplied SXPAR will return with a negative
!err if a keyword is not found.
OPTIONAL KEYWORD OUTPUT:
COUNT - Optional keyword to return a value equal to the number of
parameters found by sxpar, integer scalar
OUTPUTS:
Function value = value of parameter in header.
If parameter is double precision, floating, long or string,
the result is of that type. Apostrophes are stripped
from strings. If the parameter is logical, 1 is
returned for T, and 0 is returned for F.
If Name was of form 'keyword*' then a vector of values
are returned.
SIDE EFFECTS:
Keyword COUNT returns the number of parameters found.
!err is set to -1 if parameter not found, 0 for a scalar
value returned. If a vector is returned it is set to the
number of keyword matches found.
If a keyword occurs more than once in a header, a warning is given,
and the first occurence is used.
EXAMPLES:
Given a FITS header, h, return the values of all the NAXISi values
into a vector. Then place the history records into a string vector.
IDL> naxisi = sxpar( h ,'NAXIS*') ; Extract NAXISi value
IDL> history = sxpar( h, 'HISTORY' ) ; Extract HISTORY records
PROCEDURE:
The first 8 chacters of each element of Hdr are searched for a
match to Name. The value from the last 20 characters is returned.
An error occurs if there is no parameter with the given name.
If a numeric value has no decimal point it is returned as type
LONG. If it contains more than 8 numerals, or contains the
character 'D', then it is returned as type DOUBLE. Otherwise
it is returned as type FLOAT
MODIFICATION HISTORY:
DMS, May, 1983, Written.
D. Lindler Jan 90 added ABORT input parameter
J. Isensee Jul,90 added COUNT keyword
W. Thompson, Feb. 1992, added support for FITS complex values.
W. Thompson, May 1992, corrected problem with HISTORY/COMMENT/blank
keywords, and complex value error correction.
(See sxpar.pro)
+ NAME: XManagerTool PURPOSE: The XmanagerTool procedure has been renamed XMTool for compatibility with operating systems with short filenames (i.e. MS DOS). XManagerTool remains as a wrapper that calls the new version. See the documentation of XMTool for information. CATEGORY: Widget Management. MODIFICATION HISTORY: TC, 20 December 1992
(See xmanagertool.pro)
NAME:
XMENU
PURPOSE:
This procedure simplifies setting up widget menus. XMENU accepts a
string array of menu labels, creates a widget base, and populates
the base with buttons containing the specified labels.
CALLING SEQUENCE:
XMENU, Values [, Parent]
INPUTS:
Values: An array of labels for the butons (menu items).
If VALUES is a string array, then it is a 1-D array of labels.
If it a byte array, it is a 3-D array of bitmaps, where
the 1st 2 dimensions are the width and height of each
bitmap.
Parent: The widget ID of parent base widget. If this argument is
omitted, the menu base is a top-level base.
KEYWORDS:
BASE: A named variable to recieve the widget ID of the created base.
BUTTONS: A named variable to recieve the widget ID of the created
buttons. This return value is a longword array, with each
element matching the corresponding element in Values.
COLUMN: This keyword specifies that the buttons should be layed out
in columns. The value specified gives the number of columns
desired.
EXCLUSIVE: Set this keyword to make each menu selection an exclusive
button. Exclusive buttons have both selected and unselected
states and only one button at a time can be selected.
FONT: A string containing the name of the font for the button labels.
FRAME: If this keyword is specified, it represents the thickness (in
pixels) of the frame drawn around the base. The default is
no frame.
NONEXCLUSIVE: Set this keyword to make each menu selection a non-exclusive
button. Non-exclusive buttons have both selected and
un-selected states. More that one button can be selected at
one time.
NO_RELEASE: Set this keyword to prevent the buttons from returning release
events. Normally, buttons return both selection and release
events.
ROW: This keyword specifies that the buttons should be layed out
in rows. The value specified gives the number of rows desired.
SCROLL: Set this keyword to give the base scrollbars to allow a large
number of buttons to be viewed in a small region.
SPACE: The space, in pixels, to be left around the edges of the base.
TITLE: If PARENT is not specified, TITLE specifies the MENU title.
If PARENT is specified, a framed base is created and a
label with the value TITLE is added before the menu.
XPAD: The horizontal space, in pixels, to be left between the
buttons.
YPAD: The vertical space, in pixels, to be left between the buttons.
UVALUE: An array of user values to be set into the UVALUE of the
buttons. This array must have the same number of elements
as VALUES.
X_SCROLL_SIZE: The width of the scrolling viewport. This keyword implies
SCROLL.
Y_SCROLL_SIZE: The height of the scrolling viewport. This keyword
implies SCROLL.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A widget base containing buttons is created, but not realized.
EXAMPLE:
For an example of using XMENU to create menus see the "Non-Exclusive
Menu" and "Exclusive Menu" examples in the "Simple Widget Examples".
The simple widget examples menu can be seen by entering WEXMASTER at
the IDL prompt.
MODIFICATION HISTORY:
16 January 1991, AB, RSI
5 September 1991, SMR, RSI Fixed bug where titles were ignored when
no base specified.
21 January 1992, ACY, RSI Added FONT keyword.
(See xmenu.pro)
NAME:
XPDMENU
PURPOSE:
This procedure implifies setting up widget pulldown menus. XPDMENU
reads a description of the menu to be generated, and calls
the appropriate widget creation functions to generate it.
CALLING SEQUENCE:
XPDMENU, Desc, Parent
INPUTS:
DESC: Either the name of a file that contains the description of the
pulldown menu to be generated, or a string array that
contains the description. The rules for a pull-down menu
description are as follows:
Leading and trailing whitespace is ignored. Lines starting
with the '#' character or blank lines are ignored. All other
lines contain 2 fields, a button label and a value. The label
should be quoted with any desired delimiter, usually single
or double quotes. The value can be omitted, in which case the
label is used as the value. To make a menu choice reveal
another pull-down menu, place a '{' character in its value
field. Such a pulldown is terminated by a line containing
a '}' in the label field.
Example:
"Colors" {
"Red"
"Green"
"Blue" {
"Light"
"Medium"
"Dark"
"Navy"
"Royal"
}
"Cyan"
"Magenta"
}
"Quit" DONE
This example builds a menu bar with 2 buttons,
named "Colors" and "Quit". "Colors" is a pulldown
containing "Red", "Green", "Blue", "Cyan", and "Magenta".
"Blue" is a sub-pulldown containing shades of blue.
Such sub-menus can be nested to any desired level.
Most of the lines don't specify an explicit value. The
exception is "Quit", which has the value "DONE". It can
be instructive to run the following small program:
a = WIDGET_BASE()
XPDMENU, a, 'test' ; Test contains the above
widget_control, /REALIZE, a
uvalue=''
repeat begin
event = widget_event(a)
WIDGET_CONTROL, get_uvalue=uvalue, event.id
print, uvalue
end until uvalue eq "EXIT"
WIDGET_CONTROL, /destroy, a
end
Note that if you choose to make DESC be a string array,
the arrays contents must be exactly the same as the file
would be (including the quotes around the fields). Each
element of the array corresponds to one line of a file.
PARENT: Widget ID of the parent base widget for the pulldown menu.
If this argument is omitted, the menu base is a top-level base.
KEYWORDS:
BASE: A named variable to recieve the widget ID of the created base.
COLUMN: If set, the buttons will be arranged in a column. If unset,
the buttons will be arranged in a row.
FRAME: The width, in pixels of the frame drawn around the base. The
default is no frame.
TITLE: If PARENT is not supplied, TITLE can be set a string to be
used as the title for the widget base.
FONT: A string that contains the name of the font to use for the
menu buttons.
OUTPUTS:
None.
COMMON BLOCKS:
None.
SIDE EFFECTS:
A pulldown menu widget heirarchy is created, but not realized.
Each button has the label specified by the first field of the
corresponding pulldown menu description line. Each button has a
user value (uvalue) specified by the second field.
RESTRICTIONS:
Very little syntax checking is done on the description file.
Incorrectly formated input can lead to unexpected results.
EXAMPLE:
For an example of using XPDMENU, see the "Pull-Down Menu" example
in the "Simple Widget Examples". To create the simple widget examples
main menu, enter WEXMASTER from the IDL prompt.
MODIFICATION HISTORY:
4 October 1990, AB, RSI.
16 January 1991, AB Added the option of DESC being a string
array containing the description.
(See xpdmenu.pro)
NAME: ZPARCHECK PURPOSE: Routine to check user parameters to a procedure CALLING SEQUENCE: zparcheck, progname, parameter, parnum, types, dimens, [ message ] INPUTS: progname - scalar string name of calling procedure parameter - parameter passed to the routine parnum - integer parameter number types - integer scalar or vector of valid types 1 - byte 2 - integer 3 - int*4 4 - real*4 5 - real*8 6 - complex 7 - string 8 - structure dimens - integer scalar or vector giving number of allowed dimensions. OPTIONAL INPUT: message - string message describing the parameter to be printed if an error is found OUTPUTS: none EXAMPLE: IDL> zparcheck, 'HREBIN', hdr, 2, 7, 1, 'FITS Image Header' This example checks whether the parameter 'hdr' is of type string (=7) and is a vector (1 dimension). If either of these tests fail, a message will be printed "Parameter 2 (FITS Image Header) is undefined" "Valid dimensions are 1" "Valid types are string" SIDE EFFECTS: If an error in the parameter is a message is printed a RETALL issued HISTORY version 1 D. Lindler Dec. 86 documentation updated. M. Greason, May 1990.
(See zparcheck.pro)