This page is a listing of the entire contents of this library for IDL. This listing is the long version. Viewing the much more compact listing may be handier.
NAME:
ABSCAL
PURPOSE:
Apply the FITS BZERO and BSCALE keyword values to a data array
CALLING SEQUENCE:
RESULT = ABSCAL( Value, Header, /DEBUG)
INPUTS:
VALUE - Any scalar, vector, or array (usually an integer type giving a
relative intensity).
HEADER - A FITS header array containing the absolute calibration
keyword BSCALE, and optionally BZERO and BUNIT.
OUTPUT:
RESULT = BSCALE*VALUE + BZERO, where the BSCALE and BZERO scalars
are taken from the FITS header.
If the absolute calibration keywords do not exist, then
RESULT = VALUE, and !ERR = -1.
OPTIONAL INPUT KEYWORD:
/DEBUG - If DEBUG is set, then ABSCAL will print the
calibration units given by the BUNIT keyword.
REVISION HISTORY:
Written W. Landsman, STX Corporation January 1987
Use DEBUG keyword instead of !DEBUG September 1995
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/abscal.pro)
NAME:
AD2XY
PURPOSE:
Compute X and Y from RA and DEC and a FITS astrometry structure
EXPLANATION:
A tangent (gnomonic) projection is computed directly; other projections
are computed using WCSXY2SPH. AD2XY is meant to be used internal to
other procedures. For interactive purposes, use ADXY.
CALLING SEQUENCE:
AD2XY, a ,d, astr, x, y
INPUTS:
A - R.A. in DEGREES, scalar or vector
D - Dec. in DEGREES, scalar or vector
ASTR - astrometry structure, output from EXTAST procedure containing:
.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 increment at reference point in
DEGREES/PIXEL
.CRPIX - 2 element vector giving X and Y coordinates of reference pixel
(def = NAXIS/2) in FITS convention (first pixel is 1,1)
.CRVAL - 2 element vector giving R.A. and DEC of reference pixel
in DEGREES
.CTYPE - 2 element vector giving projection types
OUTPUTS:
X - row position in pixels, scalar or vector
Y - column position in pixels, scalar or vector
X,Y will be in the standard IDL convention (first pixel is 0), and
*not* the FITS convention (first pixel is 1)
REVISION HISTORY:
Converted to IDL by B. Boothman, SASC Tech, 4/21/86
Use astrometry structure, W. Landsman Jan. 1994
Do computation correctly in degrees W. Landsman Dec. 1994
Only pass 2 CRVAL values to WCSSPH2XY W. Landsman June 1995
Don't subscript CTYPE W. Landsman August 1995
Converted to IDL V5.0 W. Landsman September 1997
Understand reversed X,Y (X-Dec, Y-RA) axes, W. Landsman October 1998
(See /host/bluemoon/usr2/idllib/astron/pro/ad2xy.pro)
NAME:
ADSTRING
PURPOSE:
Return RA and Dec as character string in sexigesimal format.
EXPLANATION:
RA and Dec may be entered as either a 2 element vector or as
two separate vectors (or scalars). One can also specify the precision
of the declination in digits after the decimal point.
CALLING SEQUENCE
result = ADSTRING( ra_dec, precision )
or
result = ADSTRING( ra,dec,[ precision ] )
INPUTS:
RA_DEC - 2 element vector giving the Right Ascension and declination
in decimal degrees.
or
RA - Right ascension in decimal degrees, numeric scalar or vector
DEC - Declination in decimal degrees, numeric scalar or vector
OPTIONAL INPUT:
PRECISION - Integer scalar (0-4) giving the number of digits after the
decimal of DEClination. The RA is automatically 1 digit more.
This parameter may either be the third parameter after RA,DEC
or the second parameter after [RA,DEC]. It is not available
for just DEC. If no PRECISION parameter is passed, a
precision of 1 for both RA and DEC is returned to maintain
compatibility with past ADSTRING functions. Values of
precision larger than 4 will be truncated to 4. If
PRECISION is 3 or 4, then RA and Dec should be input as
double precision.
OUTPUT:
RESULT - Character string containing HR,MIN,SEC,DEC,MIN,SEC formatted
as ( 2I3,F5.(p+1),2I3,F4.p ) where p is the PRECISION
parameter. If only a single scalar is supplied it is
converted to a sexigesimal string (2I3,F5.1).
EXAMPLE:
(1) Display CRVAL coordinates in a FITS header, H
IDL> crval = sxpar(h,'CRVAL*') ;Extract 2 element CRVAL vector (degs)
IDL> print, adstring(crval) ;Print CRVAL vector sexigesimal format
(2) print,adstring(30.42,-1.23,1) ==> ' 02 01 40.80 -01 13 48.0'
print,adstring(30.42,+0.23) ==> ' 02 01 40.8 +00 13 48.0'
print,adstring(+0.23) ==> '+00 13 48.0'
(3) The first two calls in (2) can be combined in a single call using
vector input
print,adstring([30.42,30.42],[-1.23,0.23], 1)
PROCEDURES CALLED:
FSTRING(), RADEC, SIXTY()
REVISION HISTORY:
Written W. Landsman June 1988
Addition of variable precision and DEC seconds precision fix.
ver. Aug. 1990 [E. Deutsch]
Output formatting spiffed up October 1991 [W. Landsman]
Remove ZPARCHECK call, accept 1 element vector April 1992 [W. Landsman]
Call ROUND() instead of NINT() February 1996 [W. Landsman]
Check roundoff past 60s October 1997 [W. Landsman]
Work for Precision =4 November 1997 [W. Landsman]
Converted to IDL V5.0 W. Landsman 24-Nov-1997
Major rewrite to allow vector inputs W. Landsman February 2000
(See /host/bluemoon/usr2/idllib/astron/pro/adstring.pro)
NAME:
ADXY
PURPOSE:
Use a FITS header to convert celestial (RA,Dec) to pixel coordinates
EXPLANATION:
Use an image header to compute X and Y positions, given the
RA and Dec in decimal degrees.
CALLING SEQUENCE:
ADXY, HDR ;Prompt for Ra and DEC
ADXY, hdr, a, d, x, y, [ /PRINT ]
INPUTS:
HDR - FITS Image header containing astrometry parameters
OPTIONAL INPUTS:
A - Right ascension in decimal DEGREES, scalar or vector
D - Declination in decimal DEGREES, scalar or vector
If A and D are not supplied, user will be prompted to supply
them in either decimal degrees or HR,MIN,SEC,DEG,MN,SC format.
OPTIONAL OUTPUT:
X - row position in pixels, same number of elements as A and D
Y - column position in pixels
X and Y will be in standard IDL convention (first pixel is 0) and not
the FITS convention (first pixel is 1).
OPTIONAL KEYWORD INPUT:
/PRINT - If this keyword is set and non-zero, then results are displayed
at the terminal.
OPERATIONAL NOTES:
If less than 5 parameters are supplied, or if the /PRINT keyword is
set, then then the X and Y positions are displayed at the terminal.
If the procedure is to be used repeatedly with the same header,
then it would be faster to use AD2XY.
PROCEDURES CALLED:
AD2XY, ADSTRING(), EXTAST, GETOPT()
REVISION HISTORY:
W. Landsman HSTX January, 1988
Use astrometry structure W. Landsman January, 1994
Changed default ADSTRING format W. Landsman September, 1995
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/adxy.pro)
NAME:
AFhread
PURPOSE:
Subroutine of WFPCREAD to read a GEIS header from an HST STSDAS image.
EXPLANATION:
This procedure reads a GEIS header from an HST image. It then looks
if a .SHH file is present for FOC images to calculate better
astrometry by getting the current PSANGLV3 from this file. Called by
WFPCREAD.PRO
CALLING SEQUENCE:
AFhread, HdrFile, hdr
INPUTS:
HdrFile - scalar string giving name of STSDAS header for an FOC image
OUTPUTS:
hdr - string array, FITS header for the FOC image. The position
angle of the V3 axis of HST (PSANGLV3) is added, if it could
be found in the .SHH file
PROCEDURE CALLS:
STRN(), SXADDPAR, SXHREAD, SXPAR()
REVISION HISTORY:
Written Eric W. Deutsch (U. of Washington) June, 1994
Documentation update W. Landsman (HSTX) July, 1994
Converted to IDL V5.0 W. Landsman September 1997
Removed call to EXIST() function W. Landsman April 1999
(See /host/bluemoon/usr2/idllib/astron/pro/afhread.pro)
NAME:
AIRTOVAC
PURPOSE:
Convert air wavelengths to vacuum wavelengths
EXPLANATION:
Wavelengths are corrected for the index of refraction of air under
standard conditions. Wavelength values below 2000 A will not be
altered. Uses the IAU standard for conversion given in Morton
(1991 Ap.J. Suppl. 77, 119)
CALLING SEQUENCE:
AIRTOVAC, WAVE
INPUT/OUTPUT:
WAVE - Wavelength in Angstroms, scalar or vector
WAVE should be input as air wavelength(s), it will be
returned as vacuum wavelength(s). WAVE is always converted to
double precision upon return.
EXAMPLE:
If the air wavelength is W = 6056.125 (a Krypton line), then
AIRTOVAC, W yields an vacuum wavelength of W = 6057.8019
METHOD:
See Morton (Ap. J. Suppl. 77, 119) for the formula used
REVISION HISTORY
Written W. Landsman November 1991
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/airtovac.pro)
NAME:
AITOFF
PURPOSE:
Convert Right Ascension, Declination to X,Y using an AITOFF projection.
EXPLANATION:
This procedure can be used to create an all-sky map in Galactic
coordinates with an equal-area Aitoff projection. Output map
coordinates are zero longitude centered.
CALLING SEQUENCE:
AITOFF, L, B, X, Y
INPUTS:
L - longitude - scalar or vector, in degrees
B - latitude - same number of elements as L, in degrees
OUTPUTS:
X - X coordinate, same number of elements as L. X is normalized to
be between -180 and 180
Y - Y coordinate, same number of elements as L. Y is normalized to
be between -90 and 90.
NOTES:
See AIPS memo No. 46, page 4, for details of the algorithm. This
version of AITOFF assumes the projection is centered at b=0 degrees.
REVISION HISTORY:
Written W.B. Landsman STX December 1989
Modified for Unix:
J. Bloch LANL SST-9 5/16/91 1.1
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/aitoff.pro)
NAME:
AITOFF_GRID
PURPOSE:
Produce an overlay of latitude and longitude lines over a plot or image
EXPLANATION:
The grid is plotted on the current graphics device. AITOFF_GRID
assumes that the ouput plot coordinates span the x-range of
-180 to 180 and the y-range goes from -90 to 90.
CALLING SEQUENCE:
AITOFF_GRID [,DLONG,DLAT,[LINESTYLE=N, LABEL =, /NEW ]
OPTIONAL INPUTS:
DLONG = Optional input longitude line spacing in degrees. If left
out, defaults to 30.
DLAT = Optional input lattitude line spacing in degrees. If left
out, defaults to 30.
OPTIONAL INPUT KEYWORDS:
LINESTYLE = Optional input integer specifying the linestyle to
use for drawing the grid lines.
LABEL = Optional keyword specifying that the lattitude and
longitude lines on the prime meridian and the
equator should be labeled in degrees. If LABELS is
given a value of 2, i.e. LABELS=2, then the longitude
labels will be in hours and minutes instead of
degrees.
/NEW = If this keyword is set, then AITOFF_GRID will create
a new plot grid, rather than overlay an existing plot.
OUTPUTS:
Draws grid lines on current graphics device.
EXAMPLE:
Create a labeled Aitoff grid of the Galaxy, and overlay stars at
specified Galactic longitudes, glong and latitudes, glat
IDL> aitoff_grid,/label,/new ;Create labeled grid
IDL> aitoff, glong, glat, x,y ;Convert to X,Y coordinates
IDL> plots,x,y,psym=2 ;Overlay "star" positions
AUTHOR AND MODIFICATIONS:
J. Bloch 1.2 6/2/91
Converted to IDL V5.0 W. Landsman September 1997
Create default plotting coords, if needed W. Landsman August 2000
(See /host/bluemoon/usr2/idllib/astron/pro/aitoff_grid.pro)
NAME:
APER
PURPOSE:
Compute concentric aperture photometry (adapted from DAOPHOT)
EXPLANATION:
APER can compute photometry in several user-specified aperture radii.
A separate sky value is computed for each source using specified inner
and outer sky radii.
CALLING SEQUENCE:
APER, image, xc, yc, [ mags, errap, sky, skyerr, phpadu, apr, skyrad,
badpix, /EXACT, /FLUX, PRINT = , /SILENT, SETSKYVAL = ]
INPUTS:
IMAGE - input image array
XC - vector of x coordinates.
YC - vector of y coordinates
OPTIONAL INPUTS:
PHPADU - Photons per Analog Digital Units, numeric scalar. Converts
the data numbers in IMAGE to photon units. (APER assumes
Poisson statistics.)
APR - Vector of up to 12 REAL photometry aperture radii.
SKYRAD - Two element vector giving the inner and outer radii
to be used for the sky annulus
BADPIX - Two element vector giving the minimum and maximum value
of a good pix (Default [-32765,32767])
OPTIONAL KEYWORD INPUTS:
/EXACT - By default, APER counts subpixels, but uses a polygon
approximation for the intersection of a circular aperture with
a square pixel (and normalize the total area of the sum of the
pixels to exactly match the circular area). If the /EXACT
keyword, then the intersection of the circular aperture with a
square pixel is computed exactly. The /EXACT keyword is much
slower and is only needed when small (~2 pixels) apertures are
used with very undersampled data.
/FLUX - By default, APER uses a magnitude system where a magnitude of
25 corresponds to 1 flux unit. If set, then APER will keep
results in flux units instead of magnitudes.
PRINT - if set and non-zero then APER will also write its results to
a file aper.prt. One can specify the output file name by
setting PRINT = 'filename'.
/SILENT - If supplied and non-zero then no output is displayed to the
terminal.
SETSKYVAL - Use this keyword to force the sky to a specified value
rather than have APER compute a sky value. SETSKYVAL
can either be a scalar specifying the sky value to use for
all sources, or a 3 element vector specifying the sky value,
the sigma of the sky value, and the number of elements used
to compute a sky value. The 3 element form of SETSKYVAL
is needed for accurate error budgeting.
OUTPUTS:
MAGS - NAPER by NSTAR array giving the magnitude for each star in
each aperture. (NAPER is the number of apertures, and NSTAR
is the number of stars). A flux of 1 digital unit is assigned
a zero point magnitude of 25.
ERRAP - NAPER by NSTAR array giving error in magnitude
for each star. If a magnitude could not be deter-
mined then ERRAP = 9.99.
SKY - NSTAR element vector giving sky value for each star
SKYERR - NSTAR element vector giving error in sky values
PROCEDURES USED:
DATATYPE(), GETOPT, MMM, PIXWT(), STRN(), STRNUMBER()
NOTES:
Reasons that a valid magnitude cannot be computed include the following:
(1) Star position is too close (within 0.5 pixels) to edge of the frame
(2) Less than 20 valid pixels available for computing sky
(3) Modal value of sky could not be computed by the procedure MMM
(4) *Any* pixel within the aperture radius is a "bad" pixel
APER was modified in June 2000 in two ways: (1) the /EXACT keyword was
added (2) the approximation of the intersection of a circular aperture
with square pixels was improved (i.e. when /EXACT is not used)
REVISON HISTORY:
Adapted to IDL from DAOPHOT June, 1989 B. Pfarr, STX
Adapted for IDL Version 2, J. Isensee, July, 1990
Code, documentation spiffed up W. Landsman August 1991
TEXTOUT may be a string W. Landsman September 1995
FLUX keyword added J. E. Hollis, February, 1996
SETSKYVAL keyword, increase maxsky W. Landsman, May 1997
Work for more than 32767 stars W. Landsman, August 1997
Converted to IDL V5.0 W. Landsman September 1997
Don't abort for insufficient sky pixels W. Landsman May 2000
Added /EXACT keyword W. Landsman June 2000
(See /host/bluemoon/usr2/idllib/astron/pro/aper.pro)
NAME:
ARCBAR
PURPOSE:
Draw an arc bar on an image showing the astronomical plate scale
CALLING SEQUENCE:
ARCBAR, hdr, arclen,[ COLOR= , /DATA, LABEL= , /NORMAL, POSITION =,
/SECONDS, SIZE=, THICK= ]
INPUTS:
hdr - image FITS header with astrometry, string array
arclen - numeric scalar giving length of bar in arcminutes (default)
or arcseconds (if /SECONDS is set)
OPTIONAL KEYWORD INPUTS:
COLOR - integer scalar specifying the color to draw the arcbar (using
PLOTS), default = !P.COLOR
/DATA - if set and non-zero, then the POSITION keyword is given in data
units
LABEL - string giving user defined label for bar. Default label is size
of bar in arcminutes
/NORMAL - if this keyword is set and non-zero, then POSITION is given in
normalized units
POSITION - 2 element vector giving the (X,Y) position in device units
(or normalized units if /NORMAL is set, or data units if /DATA
is set) at which to place the scale bar. If not supplied,
then the user will be prompted to place the cursor at the
desired position
SIZE - scalar specifying character size of label, default = 1.0
THICK - Character thickness of the label, default = !P.THICK
EXAMPLE:
Place a 3' arc minute scale bar, at position 300,200 of the current
image window, (which is associated with a FITS header, HDR)
IDL> arcbar, HDR, 3, pos = [300,200]
RESTRICTIONS:
When using using a device with scalable pixels (e.g. postscript)
the data coordinate system must be established before calling ARCBAR.
If data coordinates are not set, then ARCBAR assumes that the displayed
image size is given by the NAXIS1 keyword in the FITS header.
PROCEDURE CALLS:
AD2XY, EXTAST, GSSSADXY, SXPAR()
REVISON HISTORY:
written by L. Taylor (STX) from ARCBOX (Boothman)
modified for Version 2 IDL, B. Pfarr, STX, 4/91
New ASTROMETRY structures W.Landsman, HSTX, Jan 94
Recognize a GSSS header W. Landsman June 94
Added /NORMAL keyword W. Landsman Feb. 96
Use NAXIS1 for postscript if data coords not set, W. Landsman Aug 96
Fixed typo for postscript W. Landsman Oct. 96
Account for zeropoint offset in postscript W. Landsman Apr 97
Converted to IDL V5.0 W. Landsman September 1997
Added /DATA, /SECONDS keywords W. Landsman July 1998
(See /host/bluemoon/usr2/idllib/astron/pro/arcbar.pro)
NAME:
ARROWS
PURPOSE:
To display "weathervane" directional arrows on an astronomical image
EXPLANATION:
Overlays a graphic showing orientation of North and East.
CALLING SEQUENCE:
ARROWS,h, [ xcen, ycen, ARROWLEN= , CHARSIZE= COLOR= , /DATA
FONT=, /NORMAL, /NOTVERTEX, THICK= ]
INPUTS:
h - FITS or STSDAS header array, must include astrometry
OPTIONAL INPUTS:
xcen,ycen - numeric scalars, specifying the center position of
arrows. Position in device units unless the /NORMALIZED
keyword is specified. If not supplied, then ARROWS
will prompt for xcen and ycen
OPTIONAL KEYWORD INPUTS:
arrowlen - length of arrows in terms of normal Y size of vector-drawn
character, default = 3.5, floating point scalar
charsize - character size, default = 2.0, floating point scalar
color - color that the arrows and NE letters should be. Default
value is !P.COLOR
Data - if this keyword is set and nonzero, the input center (xcen,
ycen) is understood to be in data coordinates
font - IDL vector font number (1-20) to use to display NE letters.
For example, set font=13 to use complex italic font.
NotVertex - Normally (historically) the specified xcen,ycen indicated
the position of the vertex of the figure. If this
keyword is set, the xcen,ycen coordinates refer to a sort
of 'center of mass' of the figure. This allows the
figure to always appear with the area irregardless of
the rotation angle.
Normal - if this keyword is set and nonzero, the input center
(xcen,ycen) is taken to be in normalized coordinates. The
default is device coordinates.
thick - line thickness, default = 2.0, floating point scalar
OUTPUTS:
none
EXAMPLE:
Draw a weathervane at (400,100) on the currently active window,
showing the orientation of the image associated with a FITS header, hdr
IDL> arrows, hdr, 400, 100
METHOD:
Uses EXTAST to EXTract ASTrometry from the FITS header. The
directions of North and East are computed and the procedure
ONE_ARROW called to create the "weathervane".
PROCEDURES USED:
EXTAST - Extract astrometry structure from FITS header
ONE_ARROW - Draw a labeled arrow
ZPARCHECK
REVISON HISTORY:
written by B. Boothman 2/5/86
Recoded with new procedures ONE_ARROW, ONE_RAY. R.S.Hill,HSTX,5/20/92
Added separate determination for N and E arrow to properly display
arrows irregardless of handedness or other peculiarities and added
/NotVertex keyword to improve positioning of figure. E.Deutsch 1/10/93
Added /DATA and /NORMAL keywords W. Landsman July 1993
Recognize GSSS header W. Landsman June 1993
Added /FONT keyword W. Landsman April 1995
Modified to work correctly for COLOR=0 J.Wm.Parker, HITC 1995 May 25
Work correctly for negative CDELT values W. Landsman Feb. 1996
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/arrows.pro)
NAME: ASTDISP PURPOSE: Print astronomical and pixel coordinates in a standard format EXPLANATION: This procedure (ASTrometry DISPlay) prints the astronomical and pixel coordinates in a standard format. X,Y must be supplied. RA,DEC may also be supplied, and a data number (DN) may also be supplied. With use of the Coords= keyword, a string containing the formatted data can be returned in addition or instead (with /silent) of printing. CALLING SEQUENCE: ASTDISP, x, y, [Ra, Dec, DN, COORD = , /SILENT ] INPUT: X - The X pixel coordinate(s), scalar or vector Y - The Y pixel coordinate(s), scalar or vector OPTIONAL INPUTS: RA - Right Ascention in *degrees*, scalar or vector DEC - DEClination in *degrees*, scalar or vector (if RA is supplied, DEC must also be supplied) DN - Data Number or Flux values Each of the inputs X,Y, RA, DEC, DN should have the same number of elements OPTIONAL INPUT KEYWORDS: SILENT Prevents printing. Only useful when used with Coords= OUTPUT: Printed positions in both degrees and sexigesimal format All passed variables remain unchanged OPTIONAL KEYWORD OUTPUT: COORDS Returns the formatted coordinates in a string PROCEDURES CALLED: ADSTRING - used to format the RA and Dec HISTORY: 10-AUG-90 Version 1 written by Eric W. Deutsch 20-AUG-91 Converted to standard header. Vectorized Code. E. Deutsch 20-NOV-92 Added Coords= and /silent. E.Deutsch Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/astdisp.pro)
NAME: ASTRMFIX PURPOSE: Calculate a rough HST WFPC or FOC astrometry solution EXPLANATION: This program will calculate a rough HST WFPC or FOC astrometry solution using the keyword PSANGLEV3 which gives the angle of the V3 axis of HST. Called by WFPCREAD. CALLING SEQUENCE: AstrmFix, hdr, chip INPUT - OUTPUT: hdr - FITS header (string array) from either WFPC or FOC. Header will be updated with rough astrometry INPUT: chip - Scalar (typically 0-3) giving the WFPC chip to read. HISTORY: ??-???-???? Written by Eric W. Deutsch 22-OCT-1992 Changed all calculations to double precision. (E. Deutsch) 22-OCT-1992 Updated PC Pixel size of 0.04389 from WFPC IDT OV/SV manual(EWD) 22-OCT-1992 Updated WF Pixel size of 0.1016 from WFPC IDT OV/SV manual(EWD) 11-JAN-1993 Added warning message and changed CD001001... to CD1_1... (EWD) Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/astrmfix.pro)
NAME:
ASTRO
PURPOSE:
Interactive utility for precession and coordinate conversion.
CALLING SEQUENCE:
ASTRO, [ selection, EQUINOX =, /FK4]
OPTIONAL INPUT:
SELECTION - Scalar Integer (0-6) giving the the particular astronomical
utility to be used. (0) Precession, (1) RA, Dec (2000) to Galactic
coordinates, (2) Galactic to RA,Dec (2000) (3) RA,Dec (2000) to
Ecliptic, (4) Ecliptic to RA, Dec, (5) Ecliptic to Galactic, (6) Galactic
to Ecliptic. Program will prompt for SELECTION if this
parameter is omitted.
OPTIONAL KEYWORD INPUT:
EQUINOX - numeric scalar specifying the equinox to use when converting
between celestial and other coordinates. If not supplied,
then the RA and Dec will be assumed to be in EQUINOX J2000.
This keyword is ignored by the precession utility. For
example, to convert from RA and DEC (J1975) to Galactic
coordinates:
IDL> astro, 1, E=1975
/FK4 - If this keyword is set and nonzero, then calculations are done
in the FK4 system. For example, to convert from RA and Dec
(B1975) to Galactic coordinates
IDL> astro,1, E=1975,/FK4
METHOD:
ASTRO uses PRECESS to compute precession, and EULER to compute
coordinate conversions. The procedure GET_COORDS is used to
read the coordinates, and ADSTRING to format the RA,Dec output.
NOTES:
(1) ASTRO temporarily sets !QUIET to suppress compilation messages and
keep a pretty screen display.
(2) ASTRO was changed in December 1998 to use J2000 as the default
equinox, **and may be incompatible with earlier calls.***
(3) A nice online page for coordinate conversions is available at
http://heasarc.gsfc.nasa.gov/cgi-bin/Tools/convcoord/convcoord.pl
PROCEDURES USED:
Procedures: GET_COORDS, EULER Function: ADSTRING
REVISION HISTORY
Written, W. Landsman November 1987
Code cleaned up W. Landsman October 1991
Added Equinox keyword, call to GET_COORDS, W. Landsman April, 1992
Allow floating point equinox input J. Parker/W. Landsman July 1996
Make FK5 the default, add FK4 keyword
(See /host/bluemoon/usr2/idllib/astron/pro/astro.pro)
NAME:
ASTROLIB
PURPOSE:
Add the non-standard system variables used by the IDL Astronomy Library
EXPLANATION:
Also defines the environment variable or VMS
logical ASTRO_DATA pointing to the directory containing data files
associated with the IDL Astronomy library (system dependent).
CALLING SEQUENCE:
ASTROLIB
INPUTS:
None.
OUTPUTS:
None.
METHOD:
The non-standard system variables !PRIV, !DEBUG, !TEXTUNIT, and
!TEXTOUT are added using DEFSYSV.
REVISION HISTORY:
Written, Wayne Landsman, July 1986.
Use DEFSYSV instead of ADDSYSVAR December 1990
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/astrolib.pro)
NAME:
AVG
PURPOSE:
Return the average value of an array, or 1 dimension of an array
EXPLANATION:
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, /NAN, /DOUBLE ] )
INPUTS:
ARRAY = Input array. May be any type except string.
OPTIONAL INPUT PARAMETERS:
DIMENSION = Optional dimension to do average over, scalar
OPTIONAL KEYWORD INPUT:
/NAN - Set this keyword to cause the routine to check for occurrences of
the IEEE floating-point value NaN in the input data. Elements with
the value NaN are treated as missing data.
/DOUBLE - By default, if the input Array is double-precision, complex,
or double complex, the result is of the same type; otherwise,
the result is floating-point. Use of the /DOUBLE keyword
forces a double precision output -- this is equivalent to (but
faster than) first converting the input array to double.
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
Converted to IDL V5.0 W. Landsman September 1997
Added /NAN keyword W. Landsman July 2000
(See /host/bluemoon/usr2/idllib/astron/pro/avg.pro)
NAME:
A_b
PURPOSE:
Compute B band interstellar extinction according to the RC2.
EXPLANATION:
The predicted B band extinction is computed as a function of
Galactic position using the 21 parameter function given by
deVaucouleurs in the 2nd Reference Catalog of Galaxies (RC2). Note
that this formula is no longer used in the RC3 and that reddenings
are instead obtained from the Burstein-Heiles 21 cm maps.
CALLING SEQUENCE:
result = A_b( l2, b2)
INPUT PARAMETERS
l2 = Galactic longitude (degrees), scalar or vector
b2 = Galactic latitude (degrees), scalar or vector
OUTPUT PARAMETERS
RESULT - Interstellar extinction Ab in magnitudes, same number of
elements as input l2 and b2 parameters
NOTES:
The controversial aspect of the deVaucouleurs reddening curve
is that it predicts an extinction of about 0.2 at the poles
The parameters used here differ from the ones printed in the RC2
but are the ones actually used for entries in the catalog
(see Rowan-Robinson 1985)
This procedure is mainly of historical interest only, and reddening
is now better determined using dust maps, such as those available at
http://astro.berkeley.edu/davis/dust/index.html
REVISION HISTORY
Written by R. Cornett and W. Landsman, STX October 1987
Vectorized code W. Landsman STX December 1992
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/a_b.pro)
NAME:
BARYVEL
PURPOSE:
Calculates heliocentric and barycentric velocity components of Earth.
EXPLANATION:
BARYVEL takes into account the Earth-Moon motion, and is useful for
radial velocity work to an accuracy of ~1 m/s.
CALLING SEQUENCE:
BARYVEL, dje, deq, dvelh, dvelb
INPUTS:
DJE - (scalar) Julian ephemeris date.
DEQ - (scalar) epoch of mean equinox of dvelh and dvelb. If deq=0
then deq is assumed to be equal to dje.
OUTPUTS:
DVELH: (vector(3)) heliocentric velocity component. in km/s
DVELB: (vector(3)) barycentric velocity component. in km/s
The 3-vectors DVELH and DVELB are given in a right-handed coordinate
system with the +X axis toward the Vernal Equinox, and +Z axis
toward the celestial pole.
PROCEDURE CALLED:
Function PREMAT() -- computes precession matrix
NOTES:
Algorithm taken from FORTRAN program of Stumpff (1980, A&A Suppl, 41,1)
Stumpf claimed an accuracy of 42 cm/s for the velocity. A
comparison with the JPL FORTRAN planetary ephemeris program PLEPH
found agreement to within about 65 cm/s between 1986 and 1994
EXAMPLE:
Compute the radial velocity of the Earth toward Altair on 15-Feb-1994
IDL> jdcnv, 1994, 2, 15, 0, jd ;==> JD = 2449398.5
IDL> baryvel, jd, 2000, vh, vb
==> vh = [-17.07809, -22.80063, -9.885281] ;Heliocentric km/s
==> vb = [-17.08083, -22.80471, -9.886582] ;Barycentric km/s
IDL> ra = ten(19,50,46.77)*15/!RADEG ;RA in radians
IDL> dec = ten(08,52,3.5)/!RADEG ;Dec in radians
IDL> v = vb(0)*cos(dec)*cos(ra) + $ ;Project velocity toward star
vb(1)*cos(dec)*sin(ra) + vb(2)*sin(dec)
REVISION HISTORY:
Jeff Valenti, U.C. Berkeley Translated BARVEL.FOR to IDL.
W. Landsman, Cleaned up program sent by Chris McCarthy (SfSU) June 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/baryvel.pro)
NAME: BLINK PURPOSE: To allow the user to alternatively examine two or more windows within a single window. CALLING SEQUENCE: BLINK, Wndw [, T] INPUTS: Wndw A vector containing the indices of the windows to blink. T The time to wait, in seconds, between blinks. This is optional and set to 1 if not present. OUTPUTS: None. PROCEDURE: The images contained in the windows given are written to a pixmap. The contents of the the windows are copied to a display window, in order, until a key is struck. EXAMPLE: Blink windows 0 and 2 with a wait time of 3 seconds IDL> blink, [0,2], 3 MODIFICATION HISTORY: Written by Michael R. Greason, STX, 2 May 1990. Allow different size windows Wayne Landsman August, 1991 Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/blink.pro)
NAME: BOOST_ARRAY PURPOSE: Append one array onto a destination array EXPLANATION: 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. Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/boost_array.pro)
NAME:
BOXAVE
PURPOSE:
Box-average a 1 or 2 dimensional array. This procedure differs from
the intrinsic REBIN function in the follow 2 ways:
(1) the box size parameter is specified rather than the output
array size
(2) for INTEGER arrays, BOXAVE computes intermediate steps using REAL*4
arithmetic. This is considerably slower than REBIN but avoids
integer truncation
CALLING SEQUENCE:
result = BOXAVE( Array, Xsize,[ Ysize ] )
INPUTS:
ARRAY - Two dimensional input Array to be box-averaged. Array may be
one or 2 dimensions and of any type except character.
OPTIONAL INPUTS:
XSIZE - Size of box in the X direction, over which the array is to
be averaged. If omitted, program will prompt for this
parameter.
YSIZE - For 2 dimensional arrays, the box size in the Y direction.
If omitted, then the box size in the X and Y directions are
assumed to be equal
OUTPUT:
RESULT - Output array after box averaging. If the input array has
dimensions XDIM by YDIM, then RESULT has dimensions
XDIM/NBOX by YDIM/NBOX. The type of RESULT is the same as
the input array. However, the averaging is always computed
using REAL arithmetic, so that the calculation should be exact.
If the box size did not exactly divide the input array, then
then not all of the input array will be boxaveraged.
PROCEDURE:
BOXAVE boxaverages all points simultaneously using vector subscripting
NOTES:
If im_int is a 512 x 512 integer array, then the two statements
IDL> im = fix(round(rebin(float(im_int), 128, 128)))
IDL> im = boxave( im_int,4)
give equivalent results. The use of REBIN is faster, but BOXAVE is
is less demanding on virtual memory, since one does not need to make
a floating point copy of the entire array.
REVISION HISTORY:
Written, W. Landsman, October 1986
Call REBIN for REAL*4 and REAL*8 input arrays, W. Landsman Jan, 1992
Removed /NOZERO in output array definition W. Landsman 1995
Fixed occasional integer overflow problem W. Landsman Sep. 1995
Allow unsigned data types W. Landsman Jan. 2000
(See /host/bluemoon/usr2/idllib/astron/pro/boxave.pro)
NAME:
BPRECESS
PURPOSE:
Precess positions from J2000.0 (FK5) to B1950.0 (FK4)
EXPLANATION:
Calculates the mean place of a star at B1950.0 on the FK4 system from
the mean place at J2000.0 on the FK5 system.
CALLING SEQUENCE:
bprecess, ra, dec, ra_1950, dec_1950, [ MU_RADEC = , PARALLAX =
RAD_VEL =, EPOCH = ]
INPUTS:
RA,DEC - Input J2000 right ascension and declination in *degrees*.
Scalar or N element vector
OUTPUTS:
RA_1950, DEC_1950 - The corresponding B1950 right ascension and
declination in *degrees*. Same number of elements as
RA,DEC but always double precision.
OPTIONAL INPUT-OUTPUT KEYWORDS
MU_RADEC - 2xN element double precision vector containing the proper
motion in seconds of arc per tropical *century* in right
ascension and declination.
PARALLAX - N_element vector giving stellar parallax (seconds of arc)
RAD_VEL - N_element vector giving radial velocity in km/s
The values of MU_RADEC, PARALLAX, and RADVEL will all be modified
upon output to contain the values of these quantities in the
B1950 system. The parallax and radial velocity will have a very
minor influence on the B1950 position.
EPOCH - scalar giving epoch of original observations, default 2000.0d
This keyword value is only used if the MU_RADEC keyword is not set.
NOTES:
The algorithm is taken from the Explanatory Supplement to the
Astronomical Almanac 1992, page 186.
Also see Aoki et al (1983), A&A, 128,263
BPRECESS distinguishes between the following two cases:
(1) The proper motion is known and non-zero
(2) the proper motion is unknown or known to be exactly zero (i.e.
extragalactic radio sources). In this case, the reverse of
the algorithm in Appendix 2 of Aoki et al. (1983) is used to
ensure that the output proper motion is exactly zero. Better
precision can be achieved in this case by inputting the EPOCH
of the original observations.
The error in using the IDL procedure PRECESS for converting between
B1950 and J1950 can be up to 1.5", mainly in right ascension. If
better accuracy than this is needed then BPRECESS should be used.
An unsystematic comparison of BPRECESS with the IPAC precession
routine available at ned.ipac.caltech.edu always gives differences
less than 0.15".
EXAMPLE:
The SAO2000 catalogue gives the J2000 position and proper motion for
the star HD 119288. Find the B1950 position.
RA(2000) = 13h 42m 12.740s Dec(2000) = 8d 23' 17.69''
Mu(RA) = -.0257 s/yr Mu(Dec) = -.090 ''/yr
IDL> mu_radec = 100D* [ -15D*.0257, -0.090 ]
IDL> ra = ten(13, 42, 12.740)*15.D
IDL> dec = ten(8, 23, 17.69)
IDL> bprecess, ra, dec, ra1950, dec1950, mu_radec = mu_radec
IDL> print, adstring(ra1950, dec1950,2)
===> 13h 39m 44.526s +08d 38' 28.63"
REVISION HISTORY:
Written, W. Landsman October, 1992
Vectorized, W. Landsman February, 1994
Treat case where proper motion not known or exactly zero November 1994
Handling of arrays larger than 32767 Lars L. Christensen, march, 1995
Converted to IDL V5.0 W. Landsman September 1997
Fixed bug where A term not initialized for vector input
W. Landsman February 2000
(See /host/bluemoon/usr2/idllib/astron/pro/bprecess.pro)
NAME:
BREAK_PATH()
PURPOSE:
Breaks up a path string into its component directories.
CALLING SEQUENCE:
Result = BREAK_PATH( PATHS [ /NoCurrent])
INPUTS:
PATHS = A string containing one or more directory paths. The
individual paths are separated by commas, although in UNIX,
colons can also be used. In other words, PATHS has the same
format as !PATH, except that commas can be used as a separator
regardless of operating system.
A leading $ can be used in any path to signal that what follows
is an environmental variable, but the $ is not necessary. (In
VMS the $ can either be part of the path, or can signal logical
names for compatibility with Unix.) Environmental variables
can themselves contain multiple paths.
OUTPUT:
The result of the function is a string array of directories.
Unless the NOCURRENT keyword is set, the first element of the array is
always the null string, representing the current directory. All the
other directories will end in the correct separator character for the
current operating system.
OPTIONAL INPUT KEYWORD:
/NOCURRENT = If set, then the current directory (represented by
the null string) will not automatically be prepended to the
output.
PROCEDURE CALLS:
Functions: DATATYPE(), STR_SEP()
REVISION HISTORY:
Version 1, William Thompson, GSFC, 6 May 1993.
Added IDL for Windows compatibility.
Version 2, William Thompson, GSFC, 16 May 1995
Added keyword NOCURRENT
Version 3, William Thompson, GSFC, 29 August 1995
Modified to use OS_FAMILY
Version 4, Zarro, GSFC, 4 August 1997
Added trim to input
Converted to IDL V5.0 W. Landsman 25-Nov-1997
Fix directory character on Macintosh system A. Ferro February 2000
(See /host/bluemoon/usr2/idllib/astron/pro/break_path.pro)
NAME:
BSORT
PURPOSE:
Function to sort data into ascending order, like a simple bubble sort.
EXPLANATION:
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
Always return type LONG W. Landsman August 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/bsort.pro)
NAME:
CCM_UNRED
PURPOSE:
Deredden a flux vector using the CCM 1989 parameterization
EXPLANATION:
The reddening curve is that of Cardelli, Clayton, and Mathis (1989 ApJ.
345, 245), including the update for the near-UV given by O'Donnell
(1994, ApJ, 422, 158). Parameterization is valid from the IR to the
far-UV (3.5 microns to 0.1 microns).
Users might wish to consider using the alternate procedure FM_UNRED
which uses the extinction curve of Fitzpatrick (1999).
CALLING SEQUENCE:
CCM_UNRED, wave, flux, ebv, funred, [ R_V = ]
or
CCM_UNRED, wave, flux, ebv, [ R_V = ]
INPUT:
WAVE - wavelength vector (Angstroms)
FLUX - calibrated flux vector, same number of elements as WAVE
If only 3 parameters are supplied, then this vector will
updated on output to contain the dereddened flux.
EBV - color excess E(B-V), scalar. If a negative EBV is supplied,
then fluxes will be reddened rather than deredenned.
OUTPUT:
FUNRED - unreddened flux vector, same units and number of elements
as FLUX
OPTIONAL INPUT KEYWORD
R_V - scalar specifying the ratio of total selective extinction
R(V) = A(V) / E(B - V). If not specified, then R_V = 3.1
Extreme values of R(V) range from 2.75 to 5.3
EXAMPLE:
Determine how a flat spectrum (in wavelength) between 1200 A and 3200 A
is altered by a reddening of E(B-V) = 0.1. Assume an "average"
reddening for the diffuse interstellar medium (R(V) = 3.1)
IDL> w = 1200 + findgen(40)*50 ;Create a wavelength vector
IDL> f = w*0 + 1 ;Create a "flat" flux vector
IDL> ccm_unred, w, f, -0.1, fnew ;Redden (negative E(B-V)) flux vector
IDL> plot,w,fnew
NOTES:
(1) The CCM curve shows good agreement with the Savage & Mathis (1979)
ultraviolet curve shortward of 1400 A, but is probably
preferable between 1200 and 1400 A.
(2) Many sightlines with peculiar ultraviolet interstellar extinction
can be represented with a CCM curve, if the proper value of
R(V) is supplied.
(3) Curve is extrapolated between 912 and 1000 A as suggested by
Longo et al. (1989, ApJ, 339,474)
(4) Use the 4 parameter calling sequence if you wish to save the
original flux vector.
REVISION HISTORY:
Written W. Landsman Hughes/STX January, 1992
Extrapolate curve for wavelengths between 900 and 1000 A Dec. 1993
Use updated coefficients for near-UV from O'Donnell Feb 1994
Allow 3 parameter calling sequence April 1998
Converted to IDLV5.0 April 1998
(See /host/bluemoon/usr2/idllib/astron/pro/ccm_unred.pro)
NAME:
CHECK_FITS
PURPOSE:
Check that keywords in a FITS header array match the associated data
EXPLANATION:
Given a FITS array IM, and a associated FITS or STSDAS header HDR, this
procedure will check that
(1) HDR is a string array, and IM is defined and numeric
(2) The NAXISi values in HDR are appropriate to the dimensions
of IM
(3) The BITPIX value in HDR is appropriate to the datatype of IM
If HDR contains a DATATYPE keyword (as in STSDAS headers), then this is
also checked against the datatype of of IM
If the /UPDATE keyword is present, then FITS header will be modified, if
necessary, to force agreement with the image array
CALLING SEQUENCE:
check_FITS, im, hdr, [ dimen, idltype, /UPDATE, /NOTYPE, /SDAS, /SILENT
ERRMSG = ]'
INPUT PARAMETERS:
IM - FITS (or STSDAS) array, e.g. as read by READFITS
HDR - FITS (or STSDAS) header (string array) associated with IM
OPTIONAL OUTPUTS:
dimen - vector containing actual array dimensions
idltype- data type of the FITS array as specified in the IDL SIZE
function (1 for BYTE, 2 for INTEGER*2, 3 for INTEGER*4, etc.)
OPTIONAL KEYWORD INPUTS:
/NOTYPE - If this keyword is set, then only agreement of the array
dimensions with the FITS header are checked, and not the
data type.
/UPDATE - If this keyword is set then the BITPIX, NAXIS and DATATYPE
FITS keywords will be updated to agree with the array
/SDAS - If this keyword is set then the header is assumed to be from
an SDAS (.hhh) file. CHECK_FITS will then ensure that (1)
a DATATYPE keyword is included in the header and (2) BITPIX
is always written with positive values.
/FITS - If this keyword is present then CHECK_FITS assumes that it is
dealing with a FITS header and not an SDAS header, see notes
below.
/SILENT - If keyword is set and nonzero, the informational messages
will not be printed
OPTIONAL KEYWORD OUTPUT:
ERRMSG = If this keyword is present, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned.
SYSTEM VARIABLE:
For consistency with previous versions, CHECK_FITS sets the obsolete
!ERR keyword, although its use is discouraged in favor of the ERRMSG
keyword. If there is a fatal problem with the FITS array or header
then !ERR is set to -1. ( If the UPDATE keyword was supplied, and the
header could be fixed, then !ERR = 0.)
PROCEDURE:
Program checks the NAXIS1 and NAXIS2 parameters in the header to
see if they match the image array dimensions.
NOTES:
An important distinction between an STSDAS header and a FITS header
is that the BITPIX value in an STSDAS header is always positive,
e.g. BITPIX=32 for REAL*4 data. Users should use either the /SDAS
or the /FITS keyword if it is important whether the STSDAS or FITS
convention for REAL*4 data is used. Otherwise, CHECK_FITS assumes
that if a DATATYPE keyword is present then it is dealing with an
STSDAS header.
PROCEDURE CALLS:
STRN(),FXADDPAR, fxpar()
MODIFICATION HISTORY:
Written, December 1991 W. Landsman Hughes/STX to replace CHKIMHD
No error returned if NAXIS=0 and IM is a scalar W. Landsman Feb 93
Fixed bug for REAL*8 STSDAS data W. Landsman July 93
Make sure NAXIS agrees with NAXISi W. Landsman October 93
Converted to IDL V5.0 W. Landsman September 1997
Allow unsigned data types W. Landsman December 1999
Allow BZERO = 0 for unsigned data types W. Landsman January 2000
Added ERRMSG keyword, W. Landsman February 2000
Use FXADDPAR to put NAXISi in proper order W. Landsman August 2000
(See /host/bluemoon/usr2/idllib/astron/pro/check_fits.pro)
NAME : CHECK_TAPE_DRV PURPOSE : Associates tape drive numbers with device files. *Unix only* EXPLANATION : This is an internal routine to the CDS/SERTS Unix tape handling utilities. It converts tape drive numbers to actual device names, and checks to make sure that the device file is open. **Unix only** CALLING SEQUENCE: : CHECK_TAPE_DRV, UNIT, LOGICAL_DRIVE, DRIVE, LUN INPUTS UNIT = Tape unit number. Tape drives are selected via the UNIX environment variables "MT1", "MT2", etc. The desired tape drive is thus specified by numbers, as in VMS. Must be from 0 to 9. OUTPUTS : LOGICAL_DRIVE = Name of environment variable pointing to tape drive device file, e.g. "MT0". DRIVE = Name of device file, e.g. '/dev/nrst0'. LUN = Logical unit number used for reads and writes. COMMON : CHCK_TAPE_DRVS contains array TAPE_LUN, containing logical unit numbers for each tape device, and TAPE_OPEN, which tells whether each device is open or not. RESTRICTIONS: The environment variable "MTn", where n corresponds to the variable UNIT, must be defined. E.g., setenv MT0 /dev/nrst0 Requires IDL v3.0 or later. SIDE EFFECTS: If the device file is not yet open, then the tape is rewound, and a file unit is opened to it. Category : Utilities, I/O, Tape. Prev. Hist. : William Thompson, Apr 1991. Written : William Thompson, GSFC, April 1991. Modified : Version 1, William Thompson, GSFC, 21 December 1993. Added keyword /NOSTDIO to OPEN statement. Incorporated into CDS library. Version 2, William Thompson, GSFC, 22 December 1993. Added spawn to "mt rewind". Version 3, W. Landsman GSFC 10-Apr-1996 Open for Readonly, if Update access is unavailable Version : Version 3, 10-Apr-1996. Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/check_tape_drv.pro)
NAME:
CIC
PURPOSE:
Interpolate an irregularly sampled field using Cloud in Cell method
EXPLANATION:
This function interpolates an irregularly sampled field to a
regular grid using Cloud In Cell (nearest grid point gets
weight 1-dngp, point on other side gets weight dngp, where
dngp is the distance to the nearest grid point in units of the
cell size).
CATEGORY:
Mathematical functions, Interpolation
CALLING SEQUENCE:
Result = CIC, VALUE, POSX, NX[, POSY, NY, POSZ, NZ,
AVERAGE = average, WRAPAROUND = wraparound,
ISOLATED = isolated, NO_MESSAGE = no_message]
INPUTS:
VALUE: Array of sample weights (field values). For e.g. a
temperature field this would be the temperature and the
keyword AVERAGE should be set. For e.g. a density field
this could be either the particle mass (AVERAGE should
not be set) or the density (AVERAGE should be set).
POSX: Array of X coordinates of field samples, unit indices: [0,NX>.
NX: Desired number of grid points in X-direction.
OPTIONAL INPUTS:
POSY: Array of Y coordinates of field samples, unit indices: [0,NY>.
NY: Desired number of grid points in Y-direction.
POSZ: Array of Z coordinates of field samples, unit indices: [0,NZ>.
NZ: Desired number of grid points in Z-direction.
KEYWORD PARAMETERS:
AVERAGE: Set this keyword if the nodes contain field samples
(e.g. a temperature field). The value at each grid
point will then be the weighted average of all the
samples allocated to it. If this keyword is not
set, the value at each grid point will be the
weighted sum of all the nodes allocated to it
(e.g. for a density field from a distribution of
particles). (D=0).
WRAPAROUND: Set this keyword if you want the first grid point
to contain samples of both sides of the volume
(see below).
ISOLATED: Set this keyword if the data is isolated, i.e. not
periodic. In that case total `mass' is not conserved.
This keyword cannot be used in combination with the
keyword WRAPAROUND.
NO_MESSAGE: Suppress informational messages.
Example of default allocation of nearest grid points: n0=4, *=gridpoint.
0 1 2 3 Index of gridpoints
* * * * Grid points
|---|---|---|---| Range allocated to gridpoints ([0.0,1.0> --> 0, etc.)
0 1 2 3 4 posx
Example of ngp allocation for WRAPAROUND: n0=4, *=gridpoint.
0 1 2 3 Index of gridpoints
* * * * Grid points
|---|---|---|---|-- Range allocated to gridpoints ([0.5,1.5> --> 1, etc.)
0 1 2 3 4=0 posx
OUTPUTS:
Prints that a CIC interpolation is being performed of x
samples to y grid points, unless NO_MESSAGE is set.
RESTRICTIONS:
Field data is assumed to be periodic with the sampled volume
the basic cell, unless ISOLATED is set.
All input arrays must have the same dimensions.
Postition coordinates should be in `index units' of the
desired grid: POSX=[0,NX>, etc.
Keywords ISOLATED and WRAPAROUND cannot both be set.
PROCEDURE:
Nearest grid point is determined for each sample.
CIC weights are computed for each sample.
Samples are interpolated to the grid.
Grid point values are computed (sum or average of samples).
NOTES:
Use tsc.pro for a higher-order interpolation scheme, ngp.pro for a lower
order interpolation scheme. A standard reference for these
interpolation methods is: R.W. Hockney and J.W. Eastwood, Computer
Simulations Using Particles (New York: McGraw-Hill, 1981).
EXAMPLE:
nx=20
ny=10
posx=randomu(s,1000)
posy=randomu(s,1000)
value=posx^2+posy^2
field=cic(value,posx*nx,nx,posy*ny,ny,/average)
surface,field,/lego
MODIFICATION HISTORY:
Written by Joop Schaye, Feb 1999.
Avoid integer overflow for large dimensions P.Riley/W.Landsman Dec. 1999
(See /host/bluemoon/usr2/idllib/astron/pro/cic.pro)
NAME:
CIRRANGE
PURPOSE:
To force an angle into the range 0 <= ang < 360.
CALLING SEQUENCE:
CIRRANGE, ang, [/RADIANS]
INPUTS/OUTPUT:
ang - The angle to modify, in degrees. This parameter is
changed by this procedure. Can be a scalar or vector.
The type of ANG is always converted to double precision
on output.
OPTIONAL INPUT KEYWORDS:
/RADIANS - If present and non-zero, the angle is specified in
radians rather than degrees. It is forced into the range
0 <= ang < 2 PI.
PROCEDURE:
The angle is transformed between -360 and 360 using the MOD operator.
Negative values (if any) are then transformed between 0 and 360
MODIFICATION HISTORY:
Written by Michael R. Greason, Hughes STX, 10 February 1994.
Get rid of WHILE loop, W. Landsman, Hughex STX, May 1996
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/cirrange.pro)
NAME:
CLEANPLOT
PURPOSE:
Reset all plotting system variables (!P,!X,!Y,!Z) to their default values
EXPLANATION:
Reset all system variables (!P,!X,!Y,!Z) which are set by the user
and which affect plotting to their default values.
CALLING SEQUENCE:
Cleanplot, [ /Silent]
INPUTS:
None
OPTIONAL KEYWORD INPUT:
/SILENT - If set, then CLEANPLOT will not display a message giving the
the system variables tags being reset.
OUTPUTS:
None
SIDE EFFECTS:
The system variables that concern plotting are reset
to their default values. A message is output for each
variable changed. The CRANGE, S, WINDOW, and REGION fields of the
!X, !Y, and !Z system variables are not checked since these are
set by the graphics device and not by the user.
PROCEDURE:
This does NOT reset the plotting device.
This does not change any system variables that don't control plotting.
RESTRICTIONS:
If user default values for !P, !X, !Y and !Z are different from
the defaults adopted below, user should change P_old etc accordingly
MODIFICATION HISTORY:
Written IDL Version 2.3.0 W. Landsman & K. Venkatakrishna May '92
Handle new system variables in V3.0.0 W. Landsman Dec 92
Assume user has at least V3.0.0 W. Landsman August 95
V5.0 has 60 instead of 30 TICKV values W. Landsman Sep. 97
Change !D.N_COLORS to !D.TABLE_SIZE for 24 bit displays
W. Landsman April 1998
Added silent keyword to supress output & modified X_old to
handle the new !X and !Y tags in IDL 5.4 S. Penton July 2000
Test for visual depth if > V5.1 W. Landsman July 2000
(See /host/bluemoon/usr2/idllib/astron/pro/cleanplot.pro)
NAME:
CNTRD
PURPOSE:
Compute the centroid coordinates of a stellar object
using the algorithm in the DAOPHOT FIND subroutine.
CALLING SEQUENCE:
CNTRD, img, x, y, xcen, ycen, [ fwhm , /SILENT, /DEBUG]
INPUTS:
IMG - Two dimensional image array
X,Y - Scalar or vector integers giving approximate stellar center
OPTIONAL INPUT:
FWHM - floating scalar; Centroid is computed using a box of half
width equal to 1.5 sigma = 0.637* FWHM. CNTRD will prompt
for FWHM if not supplied
OUTPUTS:
XCEN - the computed X centroid position, same number of points as X
YCEN - computed Y centroid position, same number of points as Y
Values for XCEN and YCEN will not be computed if the computed
centroid falls outside of the box, or if the computed derivatives
are non-decreasing. If the centroid cannot be computed, then a
message is displayed and XCEN and YCEN are set to -1.
OPTIONAL OUTPUT KEYWORDS:
/SILENT - Normally CNTRD prints an error message if it is unable
to compute the centroid. Set /SILENT to suppress this.
/DEBUG - If this keyword is set, then CNTRD will display the subarray
it is using to compute the centroid.
PROCEDURE:
Maximum pixel within distance from input pixel X, Y determined
from FHWM is found and used as the center of a square, within
which the centroid is computed as the value (XCEN,YCEN) at which
the derivatives of the partial sums of the input image over (y,x)
with respect to (x,y) = 0.
MODIFICATION HISTORY:
Written 2/25/86, by J. K. Hill, S.A.S.C., following
algorithm used by P. Stetson in DAOPHOT.
Allowed input vectors G. Hennessy April, 1992
Fixed to prevent wrong answer if floating pt. X & Y supplied
W. Landsman March, 1993
Convert byte, integer subimages to float W. Landsman May 1995
Converted to IDL V5.0 W. Landsman September 1997
Better checking of edge of frame David Hogg October 2000
(See /host/bluemoon/usr2/idllib/astron/pro/cntrd.pro)
NAME: COMPARE_STRUCT PURPOSE: Compare all matching tag names and return differences EXPLANATION: Compare all matching Tags names (except for "except_Tags") between two structure arrays (may be different struct.defs.), and return a structured List of fields found different. CATEGORY: Structures CALLING SEQUENCE: diff_List = compare_struct( struct_A, struct_B ) INPUTS: struct_A, struct_B : the two structure arrays to compare. Struct_Name : for internal recursion use only. KeyWords: EXCEPT = string array of Tag names to ignore (NOT to compare). /BRIEF = number of differences found for each matching field of two structures is printed. /FULL = option to print even if zero differences found. /RECUR_A = option to search for Tag names in sub-structures of struct_A, and then call compare_struct recursively for those nested sub-structures. /RECUR_B = search for sub-structures of struct_B, and then call compare_struct recursively for those nested sub-structures. Note: compare_struct is automatically called recursively for those nested sub-structures in both struct_A and struct_B (otherwise cannot take difference) OUTPUT: Returns a structure array describing differences found, which can be examined using print,diff_List or help,/st,diff_List. PROCEDURE: Match Tag names and then use where function on tags. MODIFICATION HISTORY: written 1990 Frank Varosi STX @ NASA/GSFC (using copy_struct) modif Aug.90 by F.V. to check and compare same # of elements only. Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/compare_struct.pro)
NAME:
CONCAT_DIR
PURPOSE:
To concatenate directory and file names for current OS.
EXPLANATION:
The given file name is appended to the given directory name with the
format appropriate to the current operating system.
CALLING SEQUENCE:
result = concat_dir( directory, file)
INPUTS:
directory - the directory path (string)
file - the basic file name and extension (string)
can be an array of filenames.
OUTPUTS:
The function returns the concatenated string. If the file input
is a string array then the output will be a string array also.
EXAMPLES:
IDL> pixfile = concat_dir('$DIR_GIS_MODEL','pixels.dat')
IDL> file = ['f1.dat','f2.dat','f3.dat']
IDL> dir = '$DIR_NIS_CAL'
IDL> f = concat_dir(dir,file)
RESTRICTIONS:
Assumes Unix type format if os is not vms, MacOS or Windows.
The version of CONCAT_DIR available at
http://sohowww.nascom.nasa.gov/solarsoft/gen/idl/system/concat_dir.pro
includes additional VMS-specific keywords.
CATEGORY
Utilities, Strings
REVISION HISTORY:
Prev Hist. : Yohkoh routine by M. Morrison
Written : CDS version by C D Pike, RAL, 19/3/93
Version : Version 1 19/3/93
Documentation modified Nov-94 W. Landsman
Add V4.0 support for Windows W. Landsman Aug 95
Converted to IDL V5.0 W. Landsman September 1997
Changed loops to long integer W. Landsman December 1998
Added Mac support, translate Windows environment variables,
& treat case where dirname ends in '/' W. Landsman Feb. 2000
(See /host/bluemoon/usr2/idllib/astron/pro/concat_dir.pro)
NAME:
CONS_DEC
PURPOSE:
Obtain the X and Y coordinates of a line of constant declination
EXPLANATION:
Returns a set of Y pixels values, given an image with tangent projection
astrometry, and either
(1) A set of X pixel values, and a scalar declination value, or
(2) A set of declination values, and a scalar X value
Form (1) can be used to find the (X,Y) values of a line of constant
declination. Form (2) can be used to find the Y positions of a set
declinations, along a line of constant X.
CALLING SEQUENCE:
Y = CONS_DEC( DEC, X, CD, ASTR, [ ALPHA ])
INPUTS:
DEC - Declination value(s) in DEGREES (-!PI/2 < DEC < !PI/2).
If X is a vector, then DEC must be a scalar.
X - Specified X pixel value(s) for line of constant declination
If DEC is a vector, then X must be a scalar.
ASTR - Astrometry structure, as extracted from a FITS header by the
procedure EXTAST
OUTPUT:
Y - Computed set of Y pixel values. The number of Y values is the
same as either DEC or X, whichever is greater.
OPTIONAL OUTPUT:
ALPHA - the right ascensions (DEGREES) associated with the (X,Y) points
RESTRICTIONS:
Implemented only for the TANgent and SIN projections
NOTES:
The algorithm (and notation) is based on AIPS Memo 27 by Eric Greisen,
with modifications for a coordinate description (CD) matrix as
described in Paper II of Greisen & Calabretta (2000, A&A, in press).
These documents are available from
http://fits.cv.nrao.edu/documents/wcs/wcs.html
REVISION HISTORY:
Written, Wayne Landsman STX Co. April 1988
Use new astrometry structure, W. Landsman HSTX Jan. 1994
Use CD matrix, add SIN projection W. Landsman HSTX April, 1996
Converted to IDL V5.0 W. Landsman September 1997
Fix case where DEC is scalar, X is vector W. Landsman RITSS Feb. 2000
Fix possible sign error introduced Jan. 2000 W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/cons_dec.pro)
NAME:
CONS_RA
PURPOSE:
Obtain the X and Y coordinates of a line of constant right ascension
EXPLANATION:
Return a set of X pixel values given an image with astrometry,
and either
(1) a set of Y pixel values, and a scalar right ascension, or
(2) a set of right ascension values, and a scalar Y value.
In usage (1), CONS_RA can be used to determine the (X,Y) values
of a line of constant right ascension. In usage (2), CONS_RA can
used to determine the X positions of specified RA values, along a
line of constant Y.
CALLING SEQUENCE:
X = CONS_RA( RA, Y, ASTR, [ DEC] )
INPUTS:
RA - Right Ascension value in DEGREES (0 < RA < 360.). If Y is a
vector, then RA must be a scalar
Y - Specified Y pixel value(s) for line of constant right ascension
If RA is a vector, then Y must be a scalar
ASTR - Astrometry structure as extracted from a FITS header by the
procedure EXTAST
OUTPUTS
X - Computed set of X pixel values. The number of elements of X
is the maximum of the number of elements of RA and Y.
OPTIONAL OUTPUT:
DEC - Computed set of declinations (in DEGREES) for X,Y, coordinates
NOTES:
The algorithm (and notation) is based on AIPS Memo 27 by Eric Greisen,
with modifications for a coordinate description (CD) matrix as
described in Paper II of Greisen & Calabretta (2000, A&A, in press).
These documents are available from
http://fits.cv.nrao.edu/documents/wcs/wcs.html
RESTRICTIONS:
Implemented only for the TANgent and SIN projections
REVISION HISTORY:
Written, Wayne Landsman STX Co. April, 1988
Algorithm adapted from AIPS memo No. 27 by Eric Griessen
New astrometry structure
Converted to IDL V5.0 W. Landsman September 1997
Added SIN projection W. Landsman January 2000
Fix possible sign error introduced Jan. 2000 W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/cons_ra.pro)
NAME: CONVOLVE PURPOSE: Convolution of an image with a Point Spread Function (PSF) EXPLANATION: The default is to compute the convolution using a product of Fourier transforms (for speed). CALLING SEQUENCE: imconv = convolve( image1, psf, FT_PSF = psf_FT ) or: correl = convolve( image1, image2, /CORREL ) or: correl = convolve( image, /AUTO ) INPUTS: image = 2-D array (matrix) to be convolved with psf psf = the Point Spread Function, (size < or = to size of image). OPTIONAL INPUT KEYWORDS: FT_PSF = passes out/in the Fourier transform of the PSF, (so that it can be re-used the next time function is called). FT_IMAGE = passes out/in the Fourier transform of image. /CORRELATE uses the conjugate of the Fourier transform of PSF, to compute the cross-correlation of image and PSF, (equivalent to IDL function convol() with NO rotation of PSF) /AUTO_CORR computes the auto-correlation function of image using FFT. /NO_FT overrides the use of FFT, using IDL function convol() instead. (then PSF is rotated by 180 degrees to give same result) METHOD: When using FFT, PSF is centered & expanded to size of image. HISTORY: written, Frank Varosi, NASA/GSFC 1992. Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/convolve.pro)
NAME: CONV_STSDAS PURPOSE: Convert internal format of an STSDAS image to host machine architecture EXPLANATION: Converts the internal format of an STSDAS image (.hhh and .hhd file) to the host machine architecture. Useful for copying STSDAS files between different machines. If the host is not a VMS machine, then by default CONV_STSDAS assumes the image originated on VMS. If the host is VMS, then CONV_STSDAS assumes that the image originated on an IEEE machine (e.g. SparcStation). CALLING SEQUENCE: CONV_STSDAS, sdas_name, [ /FROM_IEEE] INPUTS: sdas_name - scalar string giving name of the STSDAS image CONV_STSDAS assumes a default header extension of .hhh -- otherwise the header extension should be included in sdas_name. The internal format of the file will be modified by CONV_STSDAS. OPTIONAL KEYWORD INPUT: /FROM_IEEE - On little endian machines (OSF, windows) this keyword indicates that the STSDAS file originated on an IEEE machine (e.g SparcStation) rather than a VMS machine EXAMPLE: Suppose files test.hhd and test.hhh have been copied with FTP from a Vax to a Sparcstation. Convert these files to the SparcStation internal format. IDL> conv_stsdas, 'test' METHOD: CONV_STSDAS reads each group image and parameter block and uses IEEE_TO_HOST or CONV_VAX_UNIX to convert the internal format. The converted images and parameter blocks are written back to the orginal file. PROCEDURE CALLS sxopen, fdecomp, datatype(), sxgpar(), ieee_to_host, conv_vax_unix() NOTES: (1) When copying STSDAS files to VMS, be sure the .hhh file is formatted as fixed block 80 byte. (2) CONV_STSDAS has no way of knowing if a file really came from a different machine architecture. If it is applied to a file that already has the correct internal format, then CONV_STSDAS will "convert" this file and corrupt the internal format. (3) Note that CONV_STSDAS currently does not support conversion *from* a little-endian machine (OSF, windows) REVISION HISTORY: Written W. Landsman January, 1993 Don't require .hhh extension April, 1993 Increase speed by calling SXGINFO May, 1993 Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/conv_stsdas.pro)
NAME:
CONV_UNIX_VAX
PURPOSE:
To convert Unix IDL data types to Vax IDL data types.
EXPLANATION:
CONV_UNIX_VAX assumes the Unix IDL data type is IEEE standard in either
big-endian or little-endian format.
CALLING SEQUENCE:
CONV_UNIX_VAX, variable, [ SOURCE_ARCH = ]
PARAMETERS:
variable - The data variable to be converted. This may be a scalar
or an array. Valid datatypes are integer, longword,
floating point, and double precision. The result of the
conversion is passed back in the original variable.
OPTIONAL INPUT KEYWORD:
SOURCE_ARCH = name (string) of source architecture
if using this function on a VAX, otherwise
!VERSION.ARCH is used to determine the conversion.
**If run on a VAX, the default is to assume the source to be
a little-endian machine with IEEE floating point
(e.g. MIPSEL or Alpha***).
RESTRICTIONS:
Requires that data be from IEEE standard Unix machines
(e.g. SUN, MIPSEL, or Alpha).
EXAMPLE:
Read a 100 by 100 matrix of floating point numbers from a data
file created on a Sun. Then convert the matrix values into
VAX format.
IDL> openr,1,'vax_float.dat
IDL> data = fltarr(100,100)
IDL> forrd,1,data
IDL> CONV_UNIX_VAX,data,SOURCE_ARCH='sparc'
MODIFICATION HISTORY:
Version 1 By John Hoegy 13-Jun-88
04-May-90 - WTT: Created CONV_UNIX_VAX from VAX2SUN,
reversing floating point procedure.
Modified P. Keegstra September 1994
Implemented MIPSEL and ALPHA architecture,
distinguishing VMS and OSF
Modified P. Keegstra February 1995
Added 386 PC based architectures
If since V5.1 then VMS is always little endian June 1998
Convert to IDL V5.0 W. Landsman June 1998
(See /host/bluemoon/usr2/idllib/astron/pro/conv_unix_vax.pro)
NAME:
CONV_VAX_UNIX
PURPOSE:
To convert VAX IDL data types to UNIX (Sun,MIPS,etc.) IDL data types.
EXPLANTION:
Generally used on non-Vax machines to parse data created on Vaxes.
The architecture is obtained from IDL sys.var. !VERSION.ARCH.
CALLING SEQUENCE:
var_unix = conv_vax_unix( var_vax, [TARGET_ARCH = ] )
INPUT PARAMETER:
var_vax - The data variable to be converted. This may be a scalar
or an array. All IDL datatypes are valid (including
structures). The result of the conversion is returned by the
function.
OPTIONAL INPUT KEYWORD:
TARGET_ARCH = name (string) of desired target architecture
(e.g. 'sparc' or 'mipsel'). If not supplied, then
!VERSION.ARCH is used to determine the target architecture.
Note that CONV_VAX_UNIX will leave variables unchanged on a
VMS machine, unless the TARGET_ARCH keyword is set.
EXAMPLE:
Read a 100 by 100 matrix of floating point numbers from a data
file created on a VAX. Then convert the matrix values into Sun format.
IDL> openr,1,'vax_float.dat'
IDL> data = fltarr(100,100)
IDL> readu,1,data
IDL> data = conv_vax_unix( data )
NOTE:
Prior to IDL V5.1, the architecture "alpha" was ambiguous, since VMS
alpha IDL used VAX D-float while OSF/1 alpha IDL uses little-endian
IEEE. The program uses !VERSION.OS to do the right thing when
converting to a representation appropriate for the current
platform. To convert to a representation appropriate for
an OSF/1 alpha on a VAX or (pre V5.1) VMS alpha, please specify
the "mipsel" (or "i386") architecture.
MODIFICATION HISTORY:
Written F. Varosi August 1990
Modified P. Keegstra April 1992
Implemented MIPSEL architecture
Modified P. Keegstra July 1994
Implemented ALPHA architecture, distinguishing VMS and OSF
Modified P. Keegstra February 1995
Added 386 PC based architectures
Modified P. Keegstra March 1995
Added note, restored and fixed old specifiers
for 386 PC based architectures
Modified W. Landsman for VAX problems in V4.0 August 1995
Work for double complex variables August 1995
Remove informational messages under VMS August 1997
Since V5.1, IDL VMS uses little endian IEEE June 1998
Convert to IDL V5.0 June 1998
(See /host/bluemoon/usr2/idllib/astron/pro/conv_vax_unix.pro)
NAME: COPY_STRUCT PURPOSE: Copy all fields with matching tag names from one structure to another EXPLANATION Fields with matching tag names are copied from one structure array to another structure array of different type. This allows copying of tag values when equating the structures of different types is not allowed, or when not all tags are to be copied. Can also recursively copy from/to structures nested within structures. Note that the number of elements in the output structure array is automatically adjusted to equal the length of input structure array. If this not desired then use pro copy_struct_inx which allows specifying via subscripts which elements are copied where in the arrays. CALLING SEQUENCE: copy_struct, struct_From, struct_To, NT_copied copy_struct, struct_From, struct_To, EXCEPT=["image","misc"] copy_struct, struct_From, struct_To, /RECUR_TANDEM INPUTS: struct_From = structure array to copy from. struct_To = structure array to copy values to. KEYWORDS: EXCEPT_TAGS = string array of tag names to ignore (to NOT copy). Used at all levels of recursion. SELECT_TAGS = tag names to copy (takes priority over EXCEPT). This keyword is not passed to recursive calls in order to avoid the confusion of not copying tags in sub-structures. /RECUR_FROM = search for sub-structures in struct_From, and then call copy_struct recursively for those nested structures. /RECUR_TO = search for sub-structures of struct_To, and then call copy_struct recursively for those nested structures. /RECUR_TANDEM = call copy_struct recursively for the sub-structures with matching Tag names in struct_From and struct_To (for use when Tag names match but sub-structure types differ). OUTPUTS: struct_To = structure array to which new tag values are copied. NT_copied = incremented by total # of tags copied (optional) INTERNAL: Recur_Level = # of times copy_struct calls itself. This argument is for internal recursive execution only. The user call is 1, subsequent recursive calls increment it, and the counter is decremented before returning. The counter is used just to find out if argument checking should be performed, and to set NT_copied = 0 first call. EXTERNAL CALLS: pro match (when keyword SELECT_TAGS is specified) PROCEDURE: Match Tag names and then use corresponding Tag numbers. HISTORY: written 1989 Frank Varosi STX @ NASA/GSFC mod Jul.90 by F.V. added option to copy sub-structures RECURSIVELY. mod Aug.90 by F.V. adjust # elements in TO (output) to equal # elements in FROM (input) & count # of fields copied. mod Jan.91 by F.V. added Recur_Level as internal argument so that argument checking done just once, to avoid confusion. Checked against Except_Tags in RECUR_FROM option. mod Oct.91 by F.V. added option SELECT_TAGS= selected field names. mod Aug.95 by W. Landsman to fix match of a single selected tag. mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion. Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/copy_struct.pro)
NAME: COPY_STRUCT_INX PURPOSE: Copy matching tags & specified indices from one structure to another EXPLANATION: Copy all fields with matching tag names (except for "except_Tags") from one structure array to another structure array of different type. This allows copying of tag values when equating the structures of different types is not allowed, or when not all tags are to be copied. Can also recursively copy from/to structures nested within structures. This procedure is same as copy_struct with option to specify indices (subscripts) of which array elements to copy from/to. CALLING SEQUENCE: copy_struct_inx, struct_From, struct_To, NT_copied, INDEX_FROM=subf copy_struct_inx, struct_From, struct_To, INDEX_FROM=subf, INDEX_TO=subto INPUTS: struct_From = structure array to copy from. struct_To = structure array to copy values to. KEYWORDS: INDEX_FROM = indices (subscripts) of which elements of array to copy. (default is all elements of input structure array) INDEX_TO = indices (subscripts) of which elements to copy to. (default is all elements of output structure array) EXCEPT_TAGS = string array of Tag names to ignore (to NOT copy). Used at all levels of recursion. SELECT_TAGS = Tag names to copy (takes priority over EXCEPT). This keyword is not passed to recursive calls in order to avoid the confusion of not copying tags in sub-structures. /RECUR_FROM = search for sub-structures in struct_From, and then call copy_struct recursively for those nested structures. /RECUR_TO = search for sub-structures of struct_To, and then call copy_struct recursively for those nested structures. /RECUR_TANDEM = call copy_struct recursively for the sub-structures with matching Tag names in struct_From and struct_To (for use when Tag names match but sub-structure types differ). OUTPUTS: struct_To = structure array to which new tag values are copied. NT_copied = incremented by total # of tags copied (optional) INTERNAL: Recur_Level = # of times copy_struct_inx calls itself. This argument is for internal recursive execution only. The user call is 1, subsequent recursive calls increment it, and the counter is decremented before returning. The counter is used just to find out if argument checking should be performed, and to set NT_copied = 0 first call. EXTERNAL CALLS: pro match (when keyword SELECT_TAGS is specified) PROCEDURE: Match Tag names and then use corresponding Tag numbers, apply the sub-indices during = and recursion. HISTORY: adapted from copy_struct: 1991 Frank Varosi STX @ NASA/GSFC mod Aug.95 by F.V. to fix match of a single selected tag. mod Mar.97 by F.V. do not pass the SELECT_TAGS keyword in recursion, and check validity of INDEX_FROM and INDEX_TO in more detail. Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/copy_struct_inx.pro)
NAME:
CORREL_IMAGES
PURPOSE:
Compute the 2-D cross-correlation function of two images
EXPLANATION:
Computes the 2-D cross-correlation function of two images for
a range of (x,y) shifting by pixels of one image relative to the other.
CALLING SEQUENCE:
Result = CORREL_IMAGES( image_A, image_B,
[XSHIFT=, YSHIFT=, XOFFSET_B=, YOFFSET_B=, REDUCTION=,
MAGNIFICATION=, /NUMPIX, /MONITOR )
INPUTS:
image_A, image_B = the two images of interest.
OPTIONAL INPUT KEYWORDS:
XSHIFT = the + & - shift to be applied in X direction, default=7.
YSHIFT = the Y direction + & - shifting, default=7.
XOFFSET_B = initial X pixel offset of image_B relative to image_A.
YOFFSET_B = Y pixel offset, defaults are (0,0).
REDUCTION = optional reduction factor causes computation of
Low resolution correlation of bin averaged images,
thus faster. Can be used to get approximate optimal
(x,y) offset of images, and then called for successive
lower reductions in conjunction with CorrMat_Analyze
until REDUCTION=1, getting offset up to single pixel.
MAGNIFICATION = option causes computation of high resolution correlation
of magnified images, thus much slower.
Shifting distance is automatically = 2 + Magnification,
and optimal pixel offset should be known and specified.
Optimal offset can then be found to fractional pixels
using CorrMat_Analyze( correl_images( ) ).
/NUMPIX - if set, causes the number of pixels for each correlation
to be saved in a second image, concatenated to the
correlation image, so Result is fltarr( Nx, Ny, 2 ).
/MONITOR causes the progress of computation to be briefly printed.
OUTPUTS:
Result is the cross-correlation function, given as a matrix.
PROCEDURE:
Loop over all possible (x,y) shifts, compute overlap and correlation
for each shift. Correlation set to zero when there is no overlap.
MODIFICATION HISTORY:
Written, July,1991, Frank Varosi, STX @ NASA/GSFC
Use ROUND instead of NINT, June 1995, Wayne Landsman HSTX
Avoid divide by zero errors, W. Landsman HSTX April 1996
Remove use of !DEBUG W. Landsman June 1997
Subtract mean of entire image before computing correlation, not just
mean of overlap region H. Ebeling/W. Landsman June 1998
(See /host/bluemoon/usr2/idllib/astron/pro/correl_images.pro)
NAME: CORREL_OPTIMIZE PURPOSE: Find the optimal (x,y) pixel offset of image_B relative to image_A EXPLANATION" Optimal offset is computed by means of maximizing the correlation function of the two images. CALLING SEQUENCE: CORREL_OPTIMIZE, image_A, image_B, xoffset_optimum, yoffset_optimum [ XOFF_INIT=, YOFF_INIT=, MAGNIFICATION=, /PRINT, /NUMPIX, /MONITOR, PLATEAU_THRESH= ] INPUTS: image_A, image_B = the two images of interest. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A, YOFF_INIT = Y pixel offset, (default offsets are 0 and 0). MAGNIFICATION = option to determine offsets up to fractional pixels, (example: MAG=2 means 1/2 pixel accuracy, default=1). /NUMPIX: sqrt( sqrt( # pixels )) used as correlation weighting factor. /MONITOR causes the progress of computation to be briefly printed. /PRINT causes the results of analysis to be printed. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1. Decrease this value for high signal-to-noise data OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. CALLS: function correl_images( image_A, image_B ) pro corrmat_analyze PROCEDURE: The combination of function correl_images( image_A, image_B ) and corrmat_analyze of the result is used to obtain the (x,y) offset yielding maximal correlation. The combination is first executed at large REDUCTION factors to speed up computation, then zooming in recursively on the optimal (x,y) offset by factors of 2. Finally, the MAGNIFICATION option (if specified) is executed to determine the (x,y) offset up to fractional pixels. MODIFICATION HISTORY: Written, July,1991, Frank Varosi, STX @ NASA/GSFC Added PLATEAU_THRESH keyword June 1997, Wayne Landsman STX Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/correl_optimize.pro)
NAME: CORRMAT_ANALYZE PURPOSE: Find the optimal (x,y) offset to maximize correlation of 2 images EXPLANATION: Analyzes the 2-D cross-correlation function of two images and finds the optimal(x,y) pixel offsets. Intended for use with function CORREL_IMAGES. CALLING SEQUENCE: corrmat_analyze, correl_mat, xoffset_optimum, yoffset_optimum, max_corr, edge, plateau, [XOFF_INIT=, YOFF_INIT=, REDUCTION=, MAGNIFICATION=, PLATEAU_THRESH=, /PRINT] INPUTS: correl_mat = the cross-correlation matrix of 2 images. (as computed by function CORREL_IMAGES( imA, imB ) ). NOTE: If correl_mat(*,*,1) is the number of pixels for each correlation, (the case when /NUMPIX was specified in call to CORREL_IMAGES) then sqrt( sqrt( # pixels )) is used as correlation weighting factor. OPTIONAL INPUT KEYWORDS: XOFF_INIT = initial X pixel offset of image_B relative to image_A. YOFF_INIT = Y pixel offset, (both as specified to correl_images). REDUCTION = reduction factor used in call to CORREL_IMAGES. MAGNIFICATION = magnification factor used in call to CORREL_IMAGES, this allows determination of offsets up to fractions of a pixel. PLATEAU_THRESH = threshold used for detecting plateaus in the cross-correlation matrix near maximum, (default=0.01), used only if MAGNIFICATION > 1 /PRINT causes the result of analysis to be printed. OUTPUTS: xoffset_optimum = optimal X pixel offset of image_B relative to image_A. yoffset_optimum = optimal Y pixel offset. max_corr = the maximal correlation corresponding to optimal offset. edge = 1 if maximum is at edge of correlation domain, otherwise=0. plateau = 1 if maximum is in a plateua of correlation function, else=0. PROCEDURE: Find point of maximum cross-correlation and calc. corresponding offsets. If MAGNIFICATION > 1: the correl_mat is checked for plateau near maximum, and if found, the center of plateau is taken as point of maximum cross-correlation. MODIFICATION HISTORY: Written, July-1991, Frank Varosi, STX @ NASA/GSFC Use ROUND instead of NINT, June 1995 Wayne Landsman HSTX Remove use of non-standard !DEBUG system variable W.L. HSTX Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/corrmat_analyze.pro)
NAME:
COSMO_PARAM
PURPOSE:
Derive full set of cosmological density parameters from a partial set
EXPLANATION:
This procedure is called by LUMDIST and GALAGE to allow the user a choice
in defining any two of four cosmological density parameters.
Given any two of the four input parameters -- (1) the normalized matter
density Omega_m (2) the normalized cosmolgical constant, Omega_lambda (2) the normalized
curvature term, Omega_k and (4) the deceleration parameter q0 -- this
program will derive the remaining two. Here "normalized" means divided by the closure
density so that Omega_m + Omega_lambda + Omega_k = 1. For a more
precise definition see Caroll, Press, & Turner (1992, ArAA, 30, 499).
If less than two parameters are defined, this procedure sets default
values of Omega_k=0 (flat space), Omega_lambda = 0.7, Omega_m = 0.3
and q0 = -0.5
CALLING SEQUENCE:
COSMO_PARAM, Omega_m, Omega_lambda, Omega_k, q0
INPUT-OUTPUTS:
Omega_M - normalized matter energy density, non-negative numeric scalar
Omega_Lambda - Normalized cosmological constant, numeric scalar
Omega_k - normalized curvature parmeter, numeric scalar. This is zero
for a flat universe
q0 - Deceleration parameter, numeric scalar = -R*(R'')/(R')^2
= 0.5*Omega_m - Omega_lambda
NOTES:
If more than two parameters are defined upon input (overspecification),
then the first two defined parameters in the ordered list Omega_m,
Omega_lambda, Omega_k, q0 are used to define the cosmology.
EXAMPLE:
Suppose one has Omega_m = 0.3, and Omega_k = 0.5 then to determine
Omega_lambda and q0
IDL> cosmo_param, 0.3, omega_lambda, 0.5, q0
which will return omega_lambda = 0.2 and q0 = -2.45
REVISION HISTORY:
W. Landsman Raytheon ITSS April 2000
(See /host/bluemoon/usr2/idllib/astron/pro/cosmo_param.pro)
NAME:
CREATE_STRUCT
PURPOSE:
Create an IDL structure from a list of tag names and dimensions
EXPLANATION:
Dynamically create an IDL structure variable from list of tag names
and data types of arbitrary dimensions. Useful when the type of
structure needed is not known until run time.
Unlike the intrinsic function CREATE_STRUCT(), this procedure does not
require the user to know the number of tags before run time. (Note
there is no name conflict since the intrinsic CREATE_STRUCT is a
function, and this file contains a procedure.)
CALLING SEQUENCE:
CREATE_STRUCT, STRUCT, strname, tagnames, tag_descript,
[ DIMEN = , /CHATTER, /NODELETE ]
INPUTS:
STRNAME - name to be associated with structure (string)
Must be unique for each structure created. Set
STRNAME = '' to create an anonymous structure
TAGNAMES - tag names for structure elements
(string or string array)
TAG_DESCRIPT - String descriptor for the structure, containing the
tag type and dimensions. For example, 'A(2),F(3),I', would
be the descriptor for a structure with 3 tags, strarr(2),
fltarr(3) and Integer scalar, respectively.
Allowed types are 'A' for strings, 'B' or 'L' for unsigned byte
integers, 'I' for integers, 'J' for longword integers,
'F' or 'E' for floating point, 'D' for double precision
'C' for complex, and 'M' for double complex
Uninterpretable characters in a format field are ignored.
For vectors, the tag description can also be specified by
a repeat count. For example, '16E,2J' would specify a
structure with two tags, fltarr(16), and lonarr(2)
OPTIONAL KEYWORD INPUTS:
DIMEN - number of dimensions of structure array (default is 1)
CHATTER - If /CHATTER is set, then CREATE_STRUCT will display
the dimensions of the structure to be created, and prompt
the user whether to continue. Default is no prompt.
NODELETE - If /NODELETE is set, then the temporary file created
CREATE_STRUCT will not be deleted upon exiting. See below
OUTPUTS:
STRUCT - IDL structure, created according to specifications
EXAMPLES:
IDL> create_struct, new, 'name',['tag1','tag2','tag3'], 'D(2),F,A(1)'
will create a structure variable new, with structure name NAME
To see the structure of new:
IDL> help,new,/struc
** Structure NAME, 3 tags, 20 length:
TAG1 DOUBLE Array(2)
TAG2 FLOAT 0.0
TAG3 STRING Array(1)
PROCEDURE:
Generates a temporary procedure file using input information with
the desired structure data types and dimensions hard-coded.
This file is then executed with CALL_PROCEDURE.
NOTES:
If CREATE_STRUCT cannot write a temporary .pro file in the current
directory, then it will write the temporary file in the getenv('HOME')
directory.
At present, can fail if a tag_name cannot be used as a proper
structure component definition, e.g., '0.10' will not
work, but a typical string like 'RA' or 'DEC' will.
A partial workaround checks for characters '\' and '/'
and '.' and converts them to '_'. in a tag_name.
Note that 'L' now specifies a LOGICAL (byte) data type and not a
a LONG data type for consistency with FITS binary tables
RESTRICTIONS:
The name of the structure must be unique, for each structure created.
Otherwise, the new variable will have the same structure as the
previous definition (because the temporary procedure will not be
recompiled). ** No error message will be generated ***
SUBROUTINES CALLED:
FDECOMP, GETTOK(), REPCHR()
MODIFICATION HISTORY:
Version 1.0 RAS January 1992
Modified 26 Feb 1992 for Rosat IDL Library (GAR)
Modified Jun 1992 to accept arrays for tag elements -- KLV, Hughes STX
Accept anonymous structures W. Landsman HSTX Sep. 92
Accept 'E' and 'J' format specifications W. Landsman Jan 93
'L' format now stands for logical and not long array
Accept repeat format for vectors W. Landsman Feb 93
Accept complex and double complex (for V4.0) W. Landsman Jul 95
Work for long structure definitions W. Landsman Aug 97
Converted to IDL V5.0 W. Landsman September 1997
Write temporary file in HOME directory if necessary W. Landsman Jul 98
Use OPENR,/DELETE for OS-independent file removal W. Landsman Jan 99
(See /host/bluemoon/usr2/idllib/astron/pro/create_struct.pro)
NAME:
CR_REJECT
PURPOSE:
General, iterative cosmic ray rejection using two or more input images.
EXPLANATION:
Uses a noise model input by the user, rather than
determining noise empirically from the images themselves.
The image returned has the combined exposure time of all the input
images, unless the bias flag is set, in which case the mean is
returned. This image is computed by summation (or taking mean)
regardless of loop and initialization options (see below).
CALLING SEQUENCE:
cr_reject, input_cube, rd_noise_dn, dark_dn, gain, mult_noise, $
combined_image, combined_npix, combined_noise
MODIFIED ARGUMENT:
input_cube - Cube in which each plane is an input image.
If the noise model is used (rd_noise_dn, dark_dn,
gain), then input_cube must be in units of DN.
If an input noise cube is supplied (rd_noise_dn
<0), then the units of input_cube and noise_cube
merely need to be consistent.
This array is used as a buffer and its contents
are not guaranteed on output (although for now,
weighting=0 with /restore_sky should give you back
your input unaltered).
INPUT ARGUMENTS:
rd_noise_dn - Read noise per pixel. Units are DN.
If negative, then the user supplies an error cube
via the keyword noise_cube. In the latter case,
mult_noise still applies, since it is basically a fudge.
dark_dn - Dark rate in DN per pixel per s. This can be a scalar,
or it can be a dark image divided by the exposure
time.
gain - Electrons per DN.
mult_noise - Coefficient for multiplicative noise term -- helps
account for differing PSFs or subpixel image shifts.
INPUT KEYWORDS:
exptime - If the images have different exposure times, pass
them in a vector. You can leave this off for
frames with the same exposure time, but dark counts
won't be treated correctly.
verbose - If set, lots of output.
nsig - Rejection limit in units of pixel-to-pixel noise
(sigma) on each input image. Can be specified as
an array, in which case the dimension gives the
maximum number of iterations to run. (Default =
[8, 6, 4]
dilation - With dfactor, provides functionality similar to the
expansion of the CR with pfactor and radius in STSDAS
crrej. Dilate gives the size of the border to be
tested around each initially detected CR pixel.
E.g., dilate=1 searches a 9 X 9 area centered on the
original pixel. If dfactor is set, the default is 1.
dfactor - See dilation. This parameter is equivalent to pfactor
in STSDAS crrej. The current threshold for rejection
is multiplied by this factor when doing the search
with the dilated mask. If dilation is set, the default
for this parameter is 0.5.
bias - Set if combining biases (divides through by number
of images at end, since exposure time is 0).
tracking_set - Subscripts of pixels to be followed through the
computation.
noskyadjust - Sky not to be subtracted before rejection tests. Default
is to do the subtraction.
xmedsky - Flag. If set, the sky is computed as a 1-d array
which is a column-by-column median. This is intended
for STIS slitless spectra. If sky adjustment is
disabled, this keyword has no effect.
input_mask - Mask cube input by the user. Should be byte data
because it's boolean. 1 means use the pixel,
and 0 means reject the pixel - these rejections
are in addition to those done by the CR rejection
algorithm as such.
The following keywords control how the current guess at a CR-free
"check image" is recomputed on each iteration:
median_loop - If set, the check image for each iteration is
the pixel-by-pixel median. THE MEAN IS
RETURNED in combined_image even if you set
this option. (Default is mean_loop.)
minimum_loop - If set, the check image for each iteration is
the pixel-by-pixel minimum. THE MEAN IS
RETURNED in combined_image even if you set
this option. (Default is mean_loop.)
mean_loop - If set, the check image for each iteration is
the pixel-by-pixel mean. (Same as the default.)
noclearmask - By default, the mask of CR flags is reset before
every iteration, and a pixel that has been
rejected has a chance to get back in the game
if the average migrates toward its value. If this
keyword is set, then any rejected pixel stays
rejected in subsequent iterations. Note that what
stsdas.hst_calib.wfpc.crrej does is the same
as the default. For this procedure, the default
was NOT to clear the flags, until 20 Oct. 1997.
restore_sky - Flag. If set, the routine adds the sky back into
input_cube before returning. Works only if
weighting=0.
null_value - Value to be used for output pixels to which no
input pixels contribute. Default=0
weighting - Selects weighting scheme in final image
combination:
0 (default) - Poissonian weighting - co-add
detected DN from non-CR pixels. (Pixel-by-
pixel scaling up to total exposure time,
for pixels in stack where some rejected.)
Equivalent to exptime weighting of rates.
1 or more - Sky and read noise weighting of rates.
Computed as weighted average of DN rates,
with total exp time multiplied back in
afterward.
In all cases, the image is returned as a sum in
DN with the total exposure time of the image
stack, and with total sky added back in.
The following keywords allow the initial guess at a CR-free "check
image" to be of a different kind from the iterative guesses:
init_med - If set, the initial check image is
the pixel-by-pixel median. (Not permitted if
input_cube has fewer than 3 planes; default is minimum.)
init_mean - If set, the initial check image is
the pixel-by-pixel mean. (Default is minimum.)
init_min - If set, the initial check image is
the pixel-by-pixel minimum. (Same as the default.)
OUTPUT ARGUMENTS::
combined_image - Mean image with CRs removed.
combined_npix - Byte (or integer) image of same dimensions as
combined_image, with each element containing
the number of non-CR stacked pixels that
went into the result.
combined_noise - Noise in combined image according to noise model
or supplied noise cube.
OUTPUT KEYWORDS:
mask_cube - CR masks for each input image. 1 means
good pixel; 0 means CR pixel.
skyvals - Sky value array. For an image cube with N planes,
this array is fltarr(N) if the sky is a scalar per
image plane, and fltarr(XDIM, N), is the XMEDSKY
is set.
INPUT/OUTPUT KEYWORD:
noise_cube - Estimated noise in each pixel of input_cube as
returned (if rd_noise_dn ge 0), or input noise
per pixel of image_cube (if rd_noise_dn lt 0).
skybox - X0, X1, Y0, Y1 bounds of image section used
to compute sky. If supplied by user, this
region is used. If not supplied, the
image bounds are returned. This parameter might
be used (for instance) if the imaging area
doesn't include the whole chip.
COMMON BLOCKS: none
SIDE EFFECTS: none
METHOD:
COMPARISON WITH STSDAS
Cr_reject emulates the crrej routine in stsdas.hst_calib.wfpc.
The two routines have been verified to give identical results
(except for some pixels along the edge of the image) under the
following conditions:
no sky adjustment
no dilation of CRs
initialization of trial image with minimum
taking mean for each trial image after first (no choice
in crrej)
Dilation introduces a difference between crrej and this routine
around the very edge of the image, because the IDL mask
manipulation routines don't handle the edge the same way as crrej
does. Away from the edge, crrej and cr_reject are the same with
respect to dilation.
The main difference between crrej and cr_reject is in the sky
computation. Cr_reject does a DAOPHOT I sky computation on a
subset of pixels grabbed from the image, whereas crrej searches
for a histogram mode.
REMARKS ON USAGE
The default is that the initial guess at a CR-free image is the
pixel-by-pixel minimum of all the input images. The pixels
cut from each component image are the ones more than nsig(0) sigma
from this minimum image. The next iteration is based on the
mean of the cleaned-up component images, and the cut is taken
at nsig(1) sigma. The next iteration is also based on the mean with
the cut taken at nsig(2) sigma.
The user can specify an arbitrary sequence of sigma cuts, e.g.,
nsig=[6,2] or nsig=[10,9,8,7]. The user can also specify that
the initial guess is the median (/init_med) rather than the
minimum, or even the mean. The iterated cleaned_up images after
the first guess can be computed as the mean or the median
(/mean_loop or /median_loop). The minimum_loop option is also
specified, but this is a trivial case, and you wouldn't want
to use it except perhaps for testing.
The routine takes into account exposure time if you want it to,
i.e., if the pieces of the CR-split aren't exactly the same.
For bias frames (exposure time 0), set /bias to return the mean
rather than the total of the cleaned-up component images.
The crrej pfactor and radius to propagate the detected CRs
outward from their initial locations have been implemented
in slightly different form using the IDL DILATE function.
It is possible to end up with output pixels to which no valid
input pixels contribute. These end up with the value
NULL_VALUE, and the corresponding pixels of combined_npix are
also returned as 0. This result can occur when the pixel is
very noisy across the whole image stack, i.e., if all the
values are, at any step of the process, far from the stack
average at that position even after rejecting the real
outliers. Because pixels are flagged symmetrically N sigma
above and below the current combined image (see code), all
the pixels at a given position can end up getting flagged.
(At least, that's how I think it happens.)
MODIFICATION HISTORY:
5 Mar. 1997 - Written. R. S. Hill
14 Mar. 1997 - Changed to masking approach to keep better
statistics and return CR-affected pixels to user.
Option to track subset of pixels added.
Dilation of initially detected CRs added.
Other small changes. RSH
17 Mar. 1997 - Arglist and treatment of exposure times fiddled
to mesh better with stis_cr. RSH
25 Mar. 1997 - Fixed bug if dilation finds nothing. RSH
4 Apr. 1997 - Changed name to cr_reject. RSH
15 Apr. 1997 - Restyled with emacs, nothing else done. RSH
18 Jun. 1997 - Input noise cube allowed. RSH
19 Jun. 1997 - Multiplicative noise deleted from final error. RSH
20 Jun. 1997 - Fixed error in using input noise cube. RSH
12 July 1997 - Sky adjustment option. RSH
27 Aug. 1997 - Dilation kernel made round, not square, and
floating-point radius allowed. RSH
16 Sep. 1997 - Clearmask added. Intermediate as well as final
mean is exptime weighted. RSH
17 Sep. 1997 - Redundant zeroes around dilation kernel trimmed. RSH
1 Oct. 1997 - Bugfix in preceding. RSH
21 Oct. 1997 - Clearmask changed to noclearmask. Bug in robust
array division fixed (misplaced parens). Sky as
a function of X (option). RSH
30 Jan. 1998 - Restore_sky keyword added. RSH
5 Feb. 1998 - Quick help corrected and updated. RSH
6 Feb. 1998 - Fixed bug in execution sequence for tracking_set
option. RSH
18 Mar. 1998 - Eliminated confusing maxiter spec. Added
null_value keyword. RSH
15 May 1998 - Input_mask keyword. RSH
27 May 1998 - Initialization of minimum image corrected. NRC, RSH
9 June 1998 - Input mask cube processing corrected. RSH
21 Sep. 1998 - Weighting keyword added. RSH
7 Oct. 1998 - Fixed bug in input_mask processing (introduced
in preceding update). Input_mask passed to
skyadj_cube. RSH
5 Mar. 1999 - Force init_min for 2 planes. RSH
1 Oct. 1999 - Make sure weighting=1 not given with noise cube. RSH
1 Dec. 1999 - Corrections to doc; restore_sky needs weighting=0. RSH
17 Mar. 2000 - SKYBOX added. RSH
(See /host/bluemoon/usr2/idllib/astron/pro/cr_reject.pro)
NAME:
CSPLINE
PURPOSE:
Function to evaluate a natural cubic spline at specified data points
EXPLANATION:
Combines the Numerical Recipes functions SPL_INIT and SPL_INTERP
CALLING SEQUENCE:
result = cspline( x, y, t, [ DERIV = ])
INPUTS:
x - vector of spline node positions, must be monotonic increasing or
decreasing
y - vector of node values
t - x-positions at which to evaluate the spline, scalar or vector
INPUT-OUTPUT KEYWORD:
DERIV - values of the second derivatives of the interpolating function
at the node points. This is an intermediate step in the
computation of the natural spline that requires only the X and
Y vectors. If repeated interpolation is to be applied to
the same (X,Y) pair, then some computation time can be saved
by supplying the DERIV keyword on each call. On the first call
DERIV will be computed and returned on output.
OUTPUT:
the values for positions t are returned as the function value
If any of the input variables are double precision, then the output will
also be double precision; otherwise the output is floating point.
EXAMPLE:
The following uses the example vectors from the SPL_INTERP documentation
IDL> x = (findgen(21)/20.0)*2.0*!PI ;X vector
IDL> y = sin(x) ;Y vector
IDL> t = (findgen(11)/11.0)*!PI ;Values at which to interpolate
IDL> plot,x,y,psym=1 ;Plot original grid
IDL> oplot, t,cspline(x,y,t),psym=2 ;Overplot interpolated values
METHOD:
The "Numerical Recipes" implementation of the natural cubic spline is
used, by calling the intrinsic IDL functions SPL_INIT and SPL_INTERP.
HISTORY:
version 1 D. Lindler May, 1989
version 2 W. Landsman April, 1997
Rewrite using the intrinsic SPL_INIT & SPL_INTERP functions
Converted to IDL V5.0 W. Landsman September 1997
Work for monotonic decreasing X vector W. Landsman February 1999
(See /host/bluemoon/usr2/idllib/astron/pro/cspline.pro)
NAME:
CT2LST
PURPOSE:
To convert from Local Civil Time to Local Mean Sidereal Time.
CALLING SEQUENCE:
CT2LST, Lst, Lng, Tz, Time, [Day, Mon, Year]
or
CT2LST, Lst, Lng, dummy, JD
INPUTS:
Lng - The longitude in degrees (east of Greenwich) of the place for
which the local sidereal time is desired, scalar. The Greenwich
mean sidereal time (GMST) can be found by setting Lng = 0.
Tz - The time zone of the site in hours. Use this to easily account
for Daylight Savings time (e.g. 4=EDT, 5 = EST/CDT), scalar
This parameter is not needed (and ignored) if Julian date is
supplied.
Time or JD - If more than four parameters are specified, then this is
the time of day of the specified date in decimal hours. If
exactly four parameters are specified, then this is the
Julian date of time in question, scalar or vector
OPTIONAL INPUTS:
Day - The day of the month (1-31),integer scalar or vector
Mon - The month, in numerical format (1-12), integer scalar or
Year - The year (e.g. 1987)
OUTPUTS:
Lst The Local Sidereal Time for the date/time specified in hours.
RESTRICTIONS:
If specified, the date should be in numerical form. The year should
appear as yyyy.
PROCEDURE:
The Julian date of the day and time is question is used to determine
the number of days to have passed since 0 Jan 2000. This is used
in conjunction with the GST of that date to extrapolate to the current
GST; this is then used to get the LST. See Astronomical Algorithms
by Jean Meeus, p. 84 (Eq. 11-4) for the constants used.
EXAMPLE:
Find the Greenwich mean sidereal time (GMST) on 1987 April 10, 19h21m UT
For GMST, we set lng=0, and for UT we set Tz = 0
IDL> CT2LST, lst, 0, 0,ten(19,21), 10, 4, 1987
==> lst = 8.5825249 hours (= 8h 34m 57.0896s)
The Web site http://tycho.usno.navy.mil/sidereal.html contains more
info on sidereal time, as well as an interactive calculator.
PROCEDURES USED:
jdcnv - Convert from year, month, day, hour to julian date
MODIFICATION HISTORY:
Adapted from the FORTRAN program GETSD by Michael R. Greason, STX,
27 October 1988.
Use IAU 1984 constants Wayne Landsman, HSTX, April 1995, results
differ by about 0.1 seconds
Converted to IDL V5.0 W. Landsman September 1997
Longitudes measured *east* of Greenwich W. Landsman December 1998
(See /host/bluemoon/usr2/idllib/astron/pro/ct2lst.pro)
NAME:
CURS
PURPOSE:
Selects an X windows cursor shape
CALLING SEQUENCE:
curs ;Interactively select a cursor shape.
curs, sel ;Make the given CURSOR_STANDARD value the cursor
shape.
OPTIONAL INPUT:
sel - Either an integer giving the CURSOR_STANDARD value (usually an
even value between 0 and 152) indicating the cursor shape, or
a string from the following menu
a -- Up arrow
b -- Left-angled arrow
c -- Right-angled arrow
d -- Crosshair
e -- Finger pointing left
f -- Finger pointing right
g -- Narrow crosshair
h -- Cycle through all possible standard cursor shapes
OUTPUTS:
None.
RESTRICTIONS:
Uses the CURSOR_STANDARD keyword of the DEVICE procedure. Although
this keyword is available under Macintosh and Windows IDL, the values
used by this procedure are specific to the X windows device.
PROCEDURE:
If the user supplies a valid cursor shape value, it is set. Otherwise,
an interactive command loop is entered; it will continue until a valid
value is given.
MODIFICATION HISTORY:
Converted to VAX 3100 workstations / IDL V2. M. Greason, STX, May 1990.
Avoid bad cursor parameter values W. Landsman February, 1991
Don't change value of input param W. Landsman August 1995
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/curs.pro)
NAME:
CURVAL
PURPOSE:
Cursor controlled display of image intensities and astronomical coords
EXPLANATION
CURVAL displays different information depending whether the user
supplied an image array, and/or a FITS header array
CALLING SEQUENCE(S):
curval ;Display x,y and byte intensity (inten)
curval, im ;Display x,y,inten, and also pixel value (from image array)
curval, hdr, [ im, OFFSET = , ZOOM =, FILEIMAGE =]
OPTIONAL INPUTS:
Hdr = FITS Header array
Im = Array containing values that are displayed. Any type.
OPTIONAL KEYWORD INPUTS:
OFFSET - 2 element vector giving the location of the image pixel (0,0)
on the window display. OFFSET can be positive (e.g if the
image is centered in a larger window) or negative (e.g. if the
only the central region of an image much larger than the window
is being displayed.
Default value is [0,0], or no offset.
ZOOM - Scalar specifying the magnification of the window with respect
to the image variable. Use, for example, if image has been
REBINed before display.
FILENAME = name of file to where CURVAL data can be saved.
Data will only be saved if left or center mouse button
are pressed.
OUTPUTS:
None.
SIDE EFFECTS:
X and Y values, etc., of the pixel under the cursor are constantly
displayed.
Pressing left or center mouse button prints a line of output, and
starts a new line.
Pressing right mouse button exits the procedure.
If the keyword FILENAME is defined, the date and time, and a heading
will be printed in the file before the data.
PROCEDURES CALLED:
EXTAST, GSSSXYAD, RADEC, SXPAR(), UNZOOM_XY, XY2AD
REVISION HISTORY:
Written, K. Rhode, STX May 1990
Added keyword FILENAME D. Alexander June 1991
Don't write to Journal file W. Landsman March 1993
Use astrometry structure W. Landsman Feb 1994
Modified for Mac IDL I. Freedman April 1994
Allow for zoomed or offset image W. Landsman Mar 1996
Proper rounding of zoomed pixel values W. Landsman/R. Hurt Dec. 1997
Converted to IDL V5.0 W. Landsman 10-Dec-1997
(See /host/bluemoon/usr2/idllib/astron/pro/curval.pro)
NAME: DAOERF PURPOSE: Calulates the intensity, and derivatives, of a 2-d Gaussian PSF EXPLANATION: Corrects for the finite size of a pixel by integrating the Gaussian over the size of the pixel. Used in the IDL-DAOPHOT sequence. CALLING SEQUENCE: DAOERF, XIN, YIN, A, F, [ PDER ] INPUTS: XIN - input scalar, vector or array, giving X coordinate values YIN - input scalar, vector or array, giving Y coordinate values, must have same number of elements as XIN. A - 5 element parameter array describing the Gaussian A(0) - peak intensity A(1) - X position of peak intensity (centroid) A(2) - Y position of peak intensity (centroid) A(3) - X sigma of the gaussian (=FWHM/2.345) A(4) - Y sigma of gaussian OUTPUTS: F - array containing value of the function at each (XIN,YIN) The number of output elements in F and PDER is identical with the number of elements in X and Y OPTIONAL OUTPUTS: PDER - 2 dimensional array of size (NPTS,5) giving the analytic derivative at each value of F with respect to each parameter A. REVISION HISTORY: Written: W. Landsman October, 1987 Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/daoerf.pro)
NAME:
DAO_VALUE
PURPOSE:
Returns the value of a DAOPHOT point-spread function at a set of points.
EXPLANATION:
The value of the point-spread function is the sum of a
two-dimensional integral under a bivariate Gaussian function, and
a value obtained by interpolation in a look-up table. DAO_VALUE will
optionally compute the derivatives wrt X and Y
CALLING SEQUENCE:
Result = DAO_VALUE( xx, yy, gauss, psf, [ dvdx, dvdy ] )
INPUTS:
XX,YY - the real coordinates of the desired point relative
to the centroid of the point-spread function.
GAUSS - 5 element vector describing the bivariate Gaussian
GAUSS(0)- the peak height of the best-fitting Gaussian profile.
GAUSS(1,2) - x and y offsets from the centroid of the point-spread
function to the center of the best-fitting Gaussian.
GAUSS(3,4) - the x and y sigmas of the best-fitting Gaussian.
PSF - a NPSF by NPSF array containing the look-up table.
OUTPUTS:
RESULT - the computed value of the point-spread function at
a position XX, YY relative to its centroid (which
coincides with the center of the central pixel of the
look-up table).
OPTIONAL OUTPUTS:
DVDX,DVDY - the first derivatives of the composite point-spread
function with respect to x and y.
NOTES
although the arguments XX,YY of the function DAO_VALUE
are relative to the centroid of the PSF, the function RINTER which
DAO_VALUE calls requires coordinates relative to the corner of the
array (see code).
PROCEDURES CALLED:
DAOERF, RINTER()
REVISON HISTORY:
Adapted to IDL by B. Pfarr, STX, 11/17/87 from 1986 STSDAS version
of DAOPHOT
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dao_value.pro)
NAME:
DATATYPE()
PURPOSE:
Returns the data type of a variable.
EXPLANATION:
This routine returns the data type of a variable in a format specified
by the optional flag parameter. Can also be used to emulate, in
earlier versions of IDL, the SIZE(/TNAME) option introduced in V5.2.
CALLING SEQUENCE :
Result = DATATYPE( VAR [, FLAG , /TNAME, /DESC ] )
INPUTS:
VAR = Variable to examine, no restrictions
OPTIONAL INPUT PARAMETERS:
FLAG = Integer between 0 and 3 giving the output format flag as
explained below. The default is 0.
/DESC = If set, then return a descriptor for the given variable. If the
variable is a scalar the value is returned as a string. If it is
an array a description is returned just like the HELP command
gives. Ex:'
IDL> print, datatype(fltarr(2,3,5),/desc) gives the string
'FLTARR(2,3,5)'
/TNAME - If set, then returns a identical result to the use of the /TNAME
keyword to the SIZE() function in IDL V5.2 and later.
Overrides the value of FLAG.
/HELP = If set, then a short explanation is printed out.
OUTPUT PARAMETERS:
The result of the function is the either a string or integer giving the
data type of VAR. Depending on the value of FLAG or /TNAME, the result
will be one of the values from the following table:
FLAG = 0 FLAG = 1 FLAG = 2 FLAG = 3 /TNAME
UND Undefined 0 UND UNDEFINED
BYT Byte 1 BYT BYTE
INT Integer 2 INT INT
LON Long 3 LON LONG
FLO Float 4 FLT FLOAT
DOU Double 5 DBL DOUBLE
COM Complex 6 COMPLEX COMPLEX
STR String 7 STR STRING
STC Structure 8 STC STRUCT
DCO DComplex 9 DCOMPLEX DCOMPLEX
PTR Pointer 10 PTR POINTER
OBJ Object 11 OBJ OBJREF
UIN UInt 12 UINT UINT
ULN ULong 13 ULON ULONG
L64 Long64 14 LON64 LONG64
U64 ULong64 15 ULON64 ULONG64
REVISION HISTORY:
Original Version: R. Sterner, JHU/APL, 24 October 1985.
Major rewrite, add /TNAME keyword, unsigned and 64 bit datatypes
W. Landsman August 1999
-
-------------------------------------------------------------
(See /host/bluemoon/usr2/idllib/astron/pro/datatype.pro)
NAME:
DATE
PURPOSE:
Convert day-of-year to a DD-MMM-YYYY string
CALLING SEQUENCE:
D_String = DATE(Year, day )
INPUTS:
Year - Integer scalar specifying the year. If the year contains only
two digits, then it is assumed to indicate the number of
years after 1900.
Day - Integer scalar giving number of days after Jan 0 of the
specified year. Can be larger than 366
OUTPUTS:
D_String - String giving date in format '13-MAR-1986'
RESTRICTIONS:
Will not work for years before 100 AD
EXAMPLE:
IDL> print, date(1997,279)
'6-Oct-1997'
MODIFICATION HISTORY:
D.M. fecit 24 October,1983
Work for years outside of the 19th century W. Landsman September 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/date.pro)
NAME:
DATE_CONV
PURPOSE:
Procedure to perform conversion of dates to one of three possible formats.
EXPLANATION:
The following date formats are allowed
format 1: real*8 scalar encoded as:
year*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)
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)
OR
YYYY-MM-DD HH:MM:SS.SS (ISO standard)
(eg. 1987-07-14 15:25:44.23)
format 4: three element vector giving spacecraft time words
from a Hubble Space Telescope (HST) 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.
NOTES:
Prior to Oct 1998, the returned real*8 date (format 1) was given as
(year-1900)*1000 + day + hour/24. + min/24./60 + sec/24./60/60
This output is ambiguous with respect to the year 2000. Note that the
current version of DATE_CONV() may not be backwards compatible with
versions prior to Oct 1998.
HISTORY:
version 1 D. Lindler July, 1987
adapted for IDL version 2 J. Isensee May, 1990
Made year 2000 compliant; allow ISO format input jls/acc Oct 1998
DJL/ACC Jan 1998, Modified to work with dates such as 6-JAN-1996 where
day of month has only one digit.
(See /host/bluemoon/usr2/idllib/astron/pro/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, positive 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.
METHOD:
Uses the algorithm of Fliegel and Van Falndern (1968) as reported in
the "Explanatory Supplement to the Astronomical Almanac" (1992), p. 604
Works for all Gregorian calendar dates with XJD > 0, i.e., dates after
-4713 November 23.
REVISION HISTORY:
Converted to IDL from Yeoman's Comet Ephemeris Generator,
B. Pfarr, STX, 6/16/88
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/daycnv.pro)
NAME:
DBBUILD
PURPOSE:
Build a database by appending new values for every item.
EXPLANATION:
The database must be opened for update (with DBOPEN) before calling
DBBUILD.
CALLING SEQUENCE:
DBBUILD, [ v1, v2, v3, v4......v30, /NOINDEX, /SILENT, STATUS = ]
INPUTS:
v1,v2....v30 - vectors containing values for all items in the database.
V1 contains values for the first item, V2 for the second, etc.
The number of vectors supplied must equal the number of items
(excluding entry number) in the database. The number of elements
in each vector should be the same. A multiple valued item
should be dimensioned NVALUE by NENTRY, where NVALUE is the number
of values, and NENTRY is the number of entries.
OPTIONAL INPUT KEYWORDS:
NOINDEX - If this keyword is supplied and non-zero then DBBUILD will
*not* create an indexed file. Useful to save time if
DBBUILD is to be called several times and the indexed file need
only be created on the last call
SILENT - If the keyword SILENT is set and non-zero, then DBBUILD
will not print a message when the index files are generated
OPTIONAL OUTPUT KEYWORD:
STATUS - Returns a status code denoting whether the operation was
successful (1) or unsuccessful (0). Useful when DBBUILD is
called from within other applications.
EXAMPLE:
Suppose a database named STARS contains the four items NAME,RA,DEC, and
FLUX. Assume that one already has the four vectors containing the
values, and that the database definition (.DBD) file already exists.
IDL> !PRIV=2 ;Writing to database requires !PRIV=2
IDL> dbcreate,'stars',1,1 ;Create database (.DBF) & index (.DBX) file
IDL> dbopen,'stars',1 ;Open database for update
IDL> dbbuild,name,ra,dec,flux ;Write 4 vectors into the database
NOTES:
Do not call DBCREATE before DBBUILD if you want to append entries to
an existing database
DBBUILD checks that each value vector matches the idl type given in the
database definition (.DBD) file, and that character strings are the
proper length.
REVISION HISTORY:
Written W. Landsman March, 1989
Added /NOINDEX keyword W. Landsman November, 1992
User no longer need supply all items W. Landsman December, 1992
Added STATUS keyword, William Thompson, GSFC, 1 April 1994
Added /SILENT keyword, William Thompson, GSFC, October 1995
Allow up to 30 items, fix problem if first item was multiple value
W. Landsman GSFC, July 1996
Faster build of external databases on big endian machines
W. Landsman GSFC, November 1997
Converted to IDL V5.0 W. Landsman 24-Nov-1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbbuild.pro)
NAME:
DBCIRCLE
PURPOSE:
Find sources in a database within specified radius of specified center
EXPLANATION:
Database must include items named 'RA' (in hours) and 'DEC' (in degrees)
and must have previously been opened with DBOPEN
CALLING SEQUENCE:
list = DBCIRCLE( ra_cen, dec_cen, [radius, dis, sublist, /SILENT,
TO_B1950, /TO_J2000 ] )
INPUTS:
RA_CEN - Right ascension of the search center in decimal HOURS, scalar
DEC_CEN - Declination of the search center in decimal DEGREES, scalar
RA_CEN and DEC_CEN should be in the same equinox as the
currently opened catalog.
OPTIONAL INPUT:
RADIUS - Radius of the search field in arc minutes, scalar.
DBCIRCLE prompts for RADIUS if not supplied.
SUBLIST - Vector giving entry numbers in currently opened database
to be searched. Default is to search all entries
OUTPUTS:
LIST - Vector giving entry numbers in the currently opened catalog
which have positions within the specified search circle
LIST is set to -1 if no sources fall within the search circle
!ERR is set to the number sources found.
OPTIONAL OUTPUT
DIS - The distance in arcminutes of each entry specified by LIST
to the search center (given by RA_CEN and DEC_CEN)
OPTIONAL KEYWORD INPUT:
/SILENT - If this keyword is set, then DBCIRCLE will not print the
number of entries found at the terminal
/TO_J2000 - If this keyword is set, then the entered coordinates are
assumed to be in equinox B1950, and will be converted to
J2000 before searching the database
/TO_B1950 - If this keyword is set, then the entered coordinates are
assumed to be in equinox J2000, and will be converted to
B1950 before searching the database
NOTE: The user must determine on his own whether the database
is in B1950 or J2000 coordinates.
METHOD:
A DBFIND search is first performed on a square area of given radius.
The list is the restricted to a circular area by using GCIRC to
compute the distance of each object to the field center.
EXAMPLE:
Find all Hipparcos stars within 40' of the nucleus of M33
(at J2000 1h 33m 50.9s 30d 39' 36.7'')
IDL> dbopen,'hipparcos'
IDL> list = dbcircle( ten(1,33,50.9), ten(3,39,36.7), 40)
PROCEDURE CALLS:
BPRECESS, DBFIND(), DBEXT, DB_INFO(), GCIRC, JPRECESS
REVISION HISTORY:
Written W. Landsman STX January 1990
Fixed search when crossing 0h July 1990
Spiffed up code a bit October, 1991
Converted to IDL V5.0 W. Landsman September 1997
Leave DIS vector unchanged if no entries found W. Landsman July 1999
Use maximum declination, rather than declination at field center to
correct RA for latitude effect W. Landsman September 1999
(See /host/bluemoon/usr2/idllib/astron/pro/dbcircle.pro)
NAME:
DBCLOSE
PURPOSE:
procedure to close a data base file
CALLING SEQUENCE:
dbclose
INPUTS:
None
OUTPUTS
None
SIDE EFFECTS:
the data base files currently opened are closed
PROCEDURE CALLS:
DB_INFO(), HOST_TO_IEEE
HISTORY:
version 2 D. Lindler Oct. 1987
For IDL version 2 August 1990
William Thompson, GSFC/CDS (ARC), 30 May 1994
Added support for external (IEEE) data format
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbclose.pro)
NAME:
DBCOMPARE
PURPOSE:
Display two entries in an IDL database side by side in a column format
CALLING SEQUENCE:
dbcompare, list1, list2, [items, TEXTOUT= , /DIFF]
INPUTS:
list1 - Integer scalar giving first entry number to be compared.
list2 - Integer scalar giving second entry number to be compared.
OPTIONAL INPUT-OUTPUT:
items - items to be compared, if not supplied then all items will be
compared. The items can be specified in any of the following ways:
form 1 scalar string giving item(s) as list of names
separated by commas
form 2 string array giving list of item names
form 3 string of form '$filename' giving name
of text file containing items (one item per line) line)
form 4 integer scalar giving single item number or
integer vector list of item numbers
form 5 Null string specifying interactive selection. This
is the default if 'items' is not supplied
form 6 '*' select all items (= default)
If items was undefined or a null string on input, then
on output it will contain the items interactively selected.
OPTIONAL INPUT KEYWORDS:
/DIFF - If this keyword is set and non-zero, then only the items
in the database that differ will be printed
TEXTOUT - Scalar Integer (1-7) Used to determine output device. See
TEXTOPEN for more info.
SYSTEM VARIABLES:
Output device controlled by non-standard system variable !TEXTOUT, if
TEXTOUT keyword is not used.
EXAMPLE:
Display entries 3624 and 3625 in column form showing only the items
that differ.
IDL> dbcompare,3624,3625,/diff
PROCEDURES USED:
DATATYPE(), DB_INFO(), DB_ITEM, DB_ITEM_INFO(), DBRD, DBXVAL()
TEXTOPEN, TEXTCLOSE
HISTORY:
Written, W. Landsman July 1996
Converted to IDL V5.0 W. Landsman September 1997
Fix documentation, add Syntax display W. Landsman November 1998
(See /host/bluemoon/usr2/idllib/astron/pro/dbcompare.pro)
NAME
DBCOMPRESS
PURPOSE:
Compress a .dbf database file after a call to DBDELETE
EXPLANATION:
The procedure DBDELETE will remove specified entries from a database
but it will not free the unused space. DBCOMPRESS will compress
the .dbf file so that it only contains valid entries.
CALLING SEQUENCE:
DBCOMPRESS, dbname
INPUT PARAMETERS:
dbname - Name of the database to be compressed, scalar string
NOTES:
(1) Will not compress the index (.dbx) file. The size of the .dbx file
is controlled by the MaxEntries value in the database definition
(.dbd) file
(2) The updated .dbf file is written in the current directory.
This may need to be moved into the ZDBASE directory.
PROCEDURE CALLS:
DBOPEN, DB_INFO(), FIND_WITH_DEF()
REVISION HISTORY:
Written, W. Landsman Raytheon STX May 1998
Converted to IDL V5.0 June 1998
(See /host/bluemoon/usr2/idllib/astron/pro/dbcompress.pro)
NAME:
DBCREATE
PURPOSE:
Create a new data base (.dbf), index (.dbx) or description (.dbh) file
EXPLANATION:
A database definition (.dbd) file must already exist.
The default directory must be a ZDBASE: directory.
CALLING SEQUENCE:
dbcreate, name,[ newindex, newdb, maxitems] [,/EXTERNAL]
INPUTS:
name- name of the data base (with no qualifier), scalar string.
The description will be read from the file "NAME".dbd
OPTIONAL INPUTS:
newindex - if non-zero then a new index file is created,
otherwise it is assumed that changes do not affect the
index file. (default=0)
newdb - if non-zero then a new data base file (.dbf) will
be created. Otherwise changes are assumed not to affect
the file's present format.
maxitems - maximum number of items in data base.
If not supplied then the number of items is
limited to 200.
OUTPUTS:
NONE.
OPTIONAL INPUT KEYWORD:
external - If set, then the database is written with an external data
representation. This allows the database files to be used on
any computer platform, e.g. through NFS mounts, but some
overhead is added to reading the files. The default is to
write the data in the native format of the computer being used.
This keyword is only paid attention to if NEWDB or NEWINDEX
are nonzero. Otherwise, the database is opened to find
out if it uses external representation or not.
Extreme caution should be used if this keyword is used with
only NEWINDEX set to a nonzero value. This mode is allowed so
that databases written on machines which already use the
external data representation format, e.g. Sun workstations, to
be marked external so that other machines can read them.
PROCEDURE CALLS:
GETTOK(), FIND_WITH_DEF(), HOST_TO_IEEE, ZPARCHECK
RESTRICTIONS:
If newdb=0 is not specified, the changes to the .dbd file can
not alter the length of the records in the data base file.
and may not alter positions of current fields in the file.
permissible changes are:
1) utilization of spares to create a item or field
2) change in field name(s)
3) respecification of index items
4) changes in default print formats
5) change in data base title
6) changes in pointer specification to other data
data bases
!priv must be 2 or greater to execute this routine.
SIDE EFFECTS:
data base description file ZDBASE:name.dbh is created
and optionally ZDBASE:name.dbf (data file) and
ZDBASE.dbx (index file) if it is a new data base.
REVISION HISTORY:
D. Lindler, GSFC/HRS, October 1987
Modified: Version 1, William Thompson, GSFC, 29 March 1994
Version 2, William Thompson, GSFC/CDS (ARC), 28 May 1994
Added EXTERNAL keyword.
Version 4, William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
8/14/95 JKF/ACC - allow EXTERNAL data for newindex OR newdb modes.
Make sure all databases closed before starting W. Landsman June 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbcreate.pro)
NAME:
DBDELETE
PURPOSE
Deletes specified entries from data base
CALLING SEQUENCE:
DBDELETE, list, [ name, /DEBUG ]
INPUTS:
list - list of entries to be deleted, scalar or vector
name - optional name of data base, scalar string. If not specified
then the data base file must be previously opened for update
by DBOPEN.
OPERATIONAL NOTES:
!PRIV must be at least 3 to execute.
SIDE EFFECTS:
The data base file (ZDBASE:name.DBF) is modified by removing the
specified entries and reordering the remaining entry numbers
accordingly (ie. if you delete entry 100, it will be replaced
by entry 101 and the database will contain 1 less entry.
EXAMPLE:
Delete entries in a database STARS where RA=DEC = 0.0
IDL> !PRIV= 3 ;Set privileges
IDL> dbopen,'STARS',1 ;Open for update
IDL> list = dbfind('ra=0.0,dec=0.0') ;Obtain LIST vector
IDL> dbdelete, list ;Delete specified entries from db
NOTES:
The procedure is rather slow because the entire database is re-
created with the specified entries deleted.
OPTIONAL KEYWORD INPUT:
DEBUG - if this keyword is set and non-zero, then additional
diagnostics will be printed as each entry is deleted.
COMMON BLOCKS:
DBCOM
PROCEDURE CALLS:
DBINDEX, DB_INFO(), DBOPEN, DBPUT, ZPARCHECK
HISTORY
Version 2 D. Lindler July, 1989
Updated documentation W. Landsman December 1992
William Thompson, GSFC, 28 February 1995
Fixed bug when external representation used.
Fixed for case where second parameter supplied W. Landsman April 1996
Use keyword DEBUG rather than !DEBUG W. Landsman May 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbdelete.pro)
NAME: DBEDIT PURPOSE: Interactively edit specified fields in a database. EXPLANATION: The value of each field is displayed, and the user has the option of changing or keeping the value. Widgets will be used if they are available. CALLING SEQUENCE: dbedit, list, [ items ] INPUTS: list - scalar or vector of database entry numbers. Set list = 0 to interactively add a new entry to a database. Set list = -1 to edit all entries. OPTIONAL INPUTS: items - list of items to be edited. If omitted, all fields can be edited. COMMON BLOCKS: DB_COM -- contains information about the opened database. DBW_C -- contains information intrinsic to this program. SIDE EFFECTS: Will update the database files. RESTRICTIIONS: Database must be opened for update prior to running this program. User must be running DBEDIT from an account that has write privileges to the databases. If one is editing an indexed item, then after all edits are complete, DBINDEX will be called to reindex the entire item. This may be time consuming. Cannot be used to edit items with multiple values EXAMPLE: Suppose one had new parallaxes for all stars fainter than 5th magnitude in the Yale Bright Star Catalog and wanted to update the PRLAX and PRLAX_CODE fields with these new numbers IDL> !priv=2 IDL> dbopen, 'yale_bs', 1 ;Open catalog for update IDL> list = dbfind( 'v>5') ;Find fainter than 5th magnitude IDL> dbedit, list, 'prlax, prlax_code' ;Manual entry of new values PROCEDURE: (1) Use the cursor and point to the value you want to edit. (2) Type the new field value over the old field value. (3) When you are done changing all of the field values for each entry save the entry to the databases by pressing 'SAVE ENTRY TO DATABASES'. Here all of the values will be checked to see if they are the correct data type. If a field value is not of the correct data type, it will not be saved. Use the buttons "PREV ENTRY" and "NEXT ENTRY" to move between entry numbers. You must save each entry before going on to another entry in order for your changes to be saved. Pressing "RESET THIS ENTRY" will remove any unsaved changes to the current entry. REVISION HISTORY: Adapted from Landsman's DBEDIT added widgets, Melissa Marsh, HSTX, August 1993 do not need to press return after entering each entry, fixed layout problem on SUN, Melissa Marsh, HSTX, January 1994 Only updates the fields which are changed. Joel Offenberg, HSTX, Mar 94 Corrected test for changed fields Wayne Landsman HSTX, Mar 94 Removed a couple of redundant statements W. Landsman HSTX Jan 96 Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbedit.pro)
NAME: DBEDIT_BASIC PURPOSE: Subroutine of DBEDIT_BASIC to edit a database on a dumb terminal. EXPLANATION: Interactively edit specified fields in a database. The value of each field is displayed, and the user has the option of changing or keeping the value. CALLING SEQUENCE: dbedit_basic, list, [ items ] INPUTS: list - scalar or vector of database entry numbers. Set LIST=0 to interactively add a new entry to a database. OPTIONAL INPUTS items - list of items to be edited. If not supplied, then the value of every field will be displayed. NOTES: (1) Database must be opened for update (dbopen,,1) before calling DBEDIT_BASIC. User must have write privileges on the database files. (2) User gets a second chance to look at edited values, before they are actually written to the database PROMPTS: The item values for each entry to be edited are first displayed User is the asked "EDIT VALUES IN THIS ENTRY (Y(es), N(o), or Q(uit))? If user answers 'Y' or hits RETURN, then each item is displayed with its current value, which the user can update. If user answered 'N' then DBEDIT_BASIC skips to the next entry. If user answers 'Q' then DBEDIT will exit, saving all previous changes. EXAMPLE: Suppose V magnitudes (V_MAG) in a database STARS with unknown values were assigned a value of 99.9. Once the true values become known, the database can be edited IDL> !PRIV=2 & dbopen,'STARS',1 ;Open database for update IDL> list = dbfind('V_MAG=99.9') ;Get list of bad V_MAG values IDL> dbedit,list,'V_MAG' ;Interactively insert good V_MAG values REVISION HISTORY: Written W. Landsman STX April, 1989 Rename DBEDIT_BASIC from DBEDIT July, 1993 Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbedit_basic.pro)
NAME:
DBEXT
PURPOSE:
Extract values of up to 12 items from an IDL database
EXPLANATION:
Procedure to extract values of up to 12 items from
data base file, and place into IDL variables
CALLING SEQUENCE:
dbext,list,items,v1,[v2,v3,v4,v5,v6,v7,v8,v9,v10,v11,v12]
INPUTS:
list - list of entry numbers to be printed, vector or scalar
If list = -1, then all entries will be extracted.
list may be converted to a vector by DBEXT
items - standard item list specification. See DBPRINT for
the 6 different ways that items may be specified.
OUTPUTS:
v1...v12 - the vectors of values for up to 12 items.
EXAMPLE:
Extract all RA and DEC values from the currently opened database, and
place into the IDL vectors, IDLRA and IDLDEC.
IDL> DBEXT,-1,'RA,DEC',idlra,idldec
HISTORY
version 2 D. Lindler NOV. 1987
check for INDEXED items W. Landsman Feb. 1989
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbext.pro)
NAME:
DBEXT_DBF
PURPOSE:
Subroutine of DBEXT to extract values of up to 18 items from a database
EXPLANATION:
This is a subroutine of DBEXT, which is the routine a user should
normally use.
CALLING SEQUENCE:
dbext_dbf,list,dbno,sbyte,nbytes,idltype,nval,v1,[ v2,v3,v4,v5,v6,v7,
v8,v9,v10,v11,v12,v13,v14,v15,v16,v17,v18 ITEM_DBNO = ]
INPUTS:
list - list of entry numbers to extract desired items. It is the
entry numbers in the primary data base unless dbno is greater
than or equal to -1. In that case it is the entry number in
the specified data base.
dbno - number of the opened db file
if set to -1 then all data bases are included
sbyte - starting byte in the entry. If single data base then it must
be the starting byte for that data base only and not the
concatenation of db records
nbytes - number of bytes in the entry
idltype - idl data type of each item to be extracted
nval - number of values per entry of each item to be extracted
OUTPUTS:
v1...v18 - the vectors of values for up to 18 items
OPTIONAL INPUT KEYWORD:
item_dbno - A vector of the individual database numbers for each item.
Simplifies the code for linked databases
PROCEDURE CALLS:
DB_INFO(), DB_ITEM_INFO(), DBRD, DBXVAL(), IS_IEEE_BIG(), IEEE_TO_HOST
HISTORY
version 1 D. Lindler Nov. 1987
Extract multiple valued entries W. Landsman May 1989
William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
Work with multiple element string items W. Landsman August 1995
Increase speed for external databases on IEEE machines WBL August 1996
IEEE conversion implemented on blocks of entries using BIG
Added keyword ITEM_DBNO R. Schwartz, GSFC/SDAC, August 1996
Return a vector even if only 1 value W. Thompson October 1996
Change variable name of BYTESWAP to BSWAP W. Thompson Mar 1997
Use /OVERWRITE with reform W. Landsman May 1997
Converted to IDL V5.0 W. Landsman September 1997
Increase maximum number of items to 18 W. Landsman November 1999
(See /host/bluemoon/usr2/idllib/astron/pro/dbext_dbf.pro)
NAME: DBEXT_IND PURPOSE: routine to read a indexed item values from index file CALLING SEQUENCE: dbext_ind,list,item,dbno,values INPUTS: list - list of entry numbers to extract values for (if it is a scalar, values for all entries are extracted) item - item to extract dbno - number of the opened data base OUTPUT: values - vector of values returned as function value HISTORY: version 1 D. Lindler Feb 88 Faster processing of string values W. Landsman April, 1992 William Thompson, GSFC/CDS (ARC), 30 May 1994 Added support for external (IEEE) data format Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbext_ind.pro)
NAME:
DBFIND()
PURPOSE:
Search data base for entries with specified characteristics
EXPLANATION:
Function to search data base for entries with specified
search characteristics.
CALLING SEQUENCE:
result = dbfind(spar,[ listin, /SILENT, /FULLSTRING, ERRMSG= ])
INPUTS:
spar - search_parameters (string)...each search parameter
is of the form:
option 1) min_val < item_name < max_val
option 2) item_name = value
option 3) item_name = [value_1, value_10]
Note: option 3 is also the slowest.
option 4) item_name > value
option 5) item_name < value
option 6) item_name = value(tolerance) ;eg. temp=25.0(5.2)
option 7) item_name ;must be non-zero
Multiple search parameters are separated by a comma.
eg. 'cam_no=2,14 is interpreted as greater than or equal.
RA and DEC keyfields are stored as floating point numbers
in the data base may be entered as HH:MM:SEC and
DEG:MIN:SEC. Where:
HH:MM:SEC equals HH + MM/60.0 + SEC/3600.
DEG:MIN:SEC equals DEG + MIN/60.0 + SEC/3600.
For example:
40:34:10.5 < dec < 43:25:19 , 8:22:1.0 < ra < 8:23:23.0
Specially encoded date/time in the data base may
be entered by CCYY/DAY:hr:min:sec which is
interpreted as
CCYY*1000+DAY+hr/24.0+min/24.0/60.+sec/24.0/3600.
If a two digit year is supplied and YY GE 40 then it is
understood to refer to year 1900 +YY; if YY LT 40 then it is
understood to refer to year 2000 +YY
For example
1985/201:10:35:30
(See /host/bluemoon/usr2/idllib/astron/pro/dbfind.pro)
DBFIND_ENTRY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBFIND_ENTRY
PURPOSE:
Subroutine of DBFIND to perform an entry number search
EXPLANATION:
This is a subroutine of dbfind and is not a standalone procedure
It performs a entry number search.
CALLING SEQUENCE:
dbfind_entry, type, svals, nentries, values
INPUTS:
type - type of search (output from dbfparse)
svals - search values (output from dbfparse)
values - array of values to search
OUTPUT:
good - indices of good values
!err is set to number of good values
REVISION HISTORY:
D. Lindler July,1987
Fixed test for final entry number W. Landsman Sept. 95
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbfind_entry.pro)
DBFIND_SORT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBFIND_SORT
PURPOSE:
Subroutine of DBFIND to perform a search using sorted values
EXPLANATION:
This is a subroutine of dbfind and is not a standalone procedure
It is used to limit the search using sorted values
CALLING SEQUENCE:
dbfind_sort, it, type, svals, list, [/FULLSTRING ]
INPUT:
it - item number, scalar
type - type of search (output from dbfparse)
svals - search values (output from dbfparse)
INPUT/OUTPUT:
list - found entries
!err is set to number of good values
!ERR = -2 for an invalid search
INPUT KEYWORD:
/FULLSTRING - By default, one has a match if a search string is
included in any part of a database value (substring match).
But if /FULLSTRING is set, then all characters in the database
value must match the search string (excluding leading and
trailing blanks). Both types of string searches are case
insensitive.
REVISION HISTORY:
D. Lindler July,1987
William Thompson, GSFC/CDS (ARC), 30 May 1994
Added support for external (IEEE) data format
William Thompson, GSFC, 14 March 1995 Added keyword FULLSTRING
Converted to IDL V5.0 W. Landsman September 1997
Minimize use of obsolete !ERR variable W. Landsman February 2000
(See /host/bluemoon/usr2/idllib/astron/pro/dbfind_sort.pro)
DBFPARSE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBFPARSE
PURPOSE
Parse the search string supplied to DBFIND. Not a standalone routine
CALLING SEQUENCE:
DBFPARSE, [ spar, items, stype, values ]
INPUTS:
spar - search parameter specification, scalar string
OUTPUTS:
items - list of items to search on
stype - search type, numeric scalar
0 item=values(j,0)
-1 item>values(j,0)
-2 item
(See /host/bluemoon/usr2/idllib/astron/pro/dbfparse.pro)
DBGET
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBGET
PURPOSE:
Find entry numbers which contain specified values of a given item.
EXPLANATION:
DBGET() is useful as an alternative to DBFIND() when the desired
search values are not easily expressed as a string.
CALLING SEQUENCE:
list = dbget( item, values, [ listin ], /SILENT, /FULLSTRING )
INPUTS:
item - Item name or number
values - scalar or vector containing item values to search for.
OPTIONAL INPUTS:
listin - list of entries to be searched. If not supplied, or
set to -1, then all entries are searched
OUTPUT:
list - vector giving the entry number of entries containing desired
item values. The number of elements in LIST may be different
from that of VALUE, since a value might be located zero, once,
or many times in the database. Use the function DBMATCH if a
one to one correspondence is desired between VALUES and LIST.
OPTIONAL INPUT KEYWORDS:
/SILENT - If this keyword is set, then DBGET will not display
the number of entries found
/FULLSTRING - By default, one has a match if a search string is
included in any part of a database value (substring match).
But if /FULLSTRING is set, then all characters in the database
value must match the search string (excluding leading and
trailing blanks). Both types of string searches are case
insensitive.
RESTRICTIONS:
When linked databases are opened together, DBGET can only be used to
search on items in the primary database.
EXAMPLE:
Get info on selected HD stars in Bright Star catalogue
IDL> dbopen, 'YALE_BS'
IDL> hdno = [1141,2363,3574,4128,6192,6314,6668] ;Desired HD numbers
IDL> list = dbget( 'HD', hdno ) ;Get corresponding entry numbers
SYSTEM VARIABLES:
!ERR is set to the number of entries found
REVISION HISTORY:
Written, W. Landsman STX February, 1989
William Thompson, GSFC, 14 March 1995 Added keyword FULLSTRING
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbget.pro)
DBHELP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBHELP
PURPOSE:
List available databases or items in the currently open database
EXPLANATION:
Procedure to either list available databases (if no database is
currently open) or the items in the currently open database.
CALLING SEQUENCE:
dbhelp, [ flag , TEXTOUT=, /SORT ]
INPUT:
flag - (optional) if set to nonzero then item or database
descriptions are also printed
default=0
If flag is a string, then it is interpreted as the
name of a data base (if no data base is opened) or a name
of an item in the opened data base. In this case, help
is displayed only for the particular item or database
OUTPUTS:
None
OPTIONAL INPUT KEYWORDS:
TEXTOUT - Used to determine output device. If not present, the
value of !TEXTOUT system variable is used (see TEXTOPEN )
textout=0 Nowhere
textout=1 if a TTY then TERMINAL using /more option
otherwise standard (Unit=-1) output
textout=2 if a TTY then TERMINAL without /more option
otherwise standard (Unit=-1) output
textout=3 .prt
textout=4 laser.tmp
textout=5 user must open file
textout=7 same as 3 but text is appended to .prt
file if it already exists.
textout = filename (default extension of .prt)
/SORT - If set and non-zero, then the help items will be displayed
sorted alphabetically. If more than one database is open,
then this keyword does nothing.
METHOD:
If no data base is opened then a list of data bases are
printed, otherwise the items in the open data base are printed.
If a string is supplied for flag and a data base is opened
flag is assumed to be an item name. The information for that
item is printed along with contents in a optional file
zdbase:dbname_itemname.hlp
if a string is supplied for flag and no data base is opened,
then string is assumed to be the name of a data base file.
only information for that file is printed along with an
optional file zdbase:dbname.hlp.
PROCEDURES USED:
DB_INFO(),DB_ITEM_INFO(),FIND_WITH_DEF(), TEXTOPEN, TEXTCLOSE
HISTORY:
Version 2 D. Lindler Nov 1987 (new db format)
Faster printing of title desc. W. Landsman May 1989
Keyword textout added, J. Isensee, July, 1990
Modified to work on Unix, D. Neill, ACC, Feb 1991.
William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
Remove duplicate database names Wayne Landsman December 1994
8/17/95 jkf/acc - force lowercase filenames for .hlp files.
Converted to IDL V5.0 W. Landsman September 1997
Added /SORT keyword J. Sandoval/W. Landsman October 1998
(See /host/bluemoon/usr2/idllib/astron/pro/dbhelp.pro)
DBINDEX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBINDEX
PURPOSE:
Procedure to create index file for data base
CALLING SEQUENCE:
dbindex, [ items ]
OPTIONAL INPUT:
items - names or numbers of items to be index -- if not supplied,
then all indexed fields will be processed.
OUTPUT:
Index file .dbx is created on disk location ZDBASE:
OPERATIONAL NOTES:
(1) Data base must have been previously opened for update
by DBOPEN
(2) Only 18 items can be indexed at one time. If the database has
more than 18 items, then two separate calls to DBINDEX are needed.
PROCEDURES CALLED:
DBINDEX_BLK, DB_INFO(), DB_ITEM, DB_ITEM_INFO(), IEEE_TO_HOST,
IS_IEEE_BIG()
HISTORY:
version 2 D. Lindler Nov 1987 (new db format)
W. Landsman added optional items parameter Feb 1989
M. Greason converted to IDL version 2. June 1990.
William Thompson, GSFC/CDS (ARC), 30 May 1994
Added support for external (IEEE) data format
Test if machine is bigendian W. Landsman May, 1996
Change variable name of BYTESWAP to BSWAP W. Thompson Mar, 1997
Increased number of fields to 15 W. Landsman June, 1997
Converted to IDL V5.0 W. Landsman September 1997
Increase number of items to 18 W. Landsman November 1999
(See /host/bluemoon/usr2/idllib/astron/pro/dbindex.pro)
DBINDEX_BLK
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBINDEX_BLK
PURPOSE:
Subroutine of DBINDEX to create associated variable of correct datatype
EXPLANATION:
DBINDEX_BLK will offset into the file by a specified amount in
preparation for writing to the file.
CALLING SEQUENCE:
res = dbindex_blk(unit, nb, bsz, ofb, dtype)
INPUTS:
unit The unit number assigned to the file.
nb The number of blocks to offset into the file.
bsz The size of each block, in bytes, to offset into the file.
ofb The offset into the block, in bytes.
dtype The IDL datatype as defined in the SIZE function
OUTPUTS:
res The returned variable. This is an associated variable.
RESTRICTIONS:
The file must have been previously opened.
MODIFICATION HISTORY:
Written by Michael R. Greason, STX, 14 June 1990.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbindex_blk.pro)
DBMATCH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBMATCH
PURPOSE:
Find the entry number in a database for each element of item values
EXPLANATION:
DBMATCH() is especially useful for finding a one-to-one
correspondence between entries in different databases, and thus to
create the vector needed for database pointers.
CALLING SEQUENCE:
list = DBMATCH( item, values, [ listin, /FULLSTRING ] )
INPUTS:
ITEM - Item name or number, scalar
VALUES - scalar or vector containing item values to search for.
OPTIONAL INPUTS:
LISTIN - list of entries to be searched. If not supplied, or
set to -1, then all entries are searched
OUTPUT:
LIST - vector of entry numbers with the same number of elements as
VALUES. Contains a value of 0 wherever the corresponding item
value was not found.
OPTIONAL INPUT:
/FULLSTRING - By default, one has a match if a search string is
included in any part of a database value (substring match).
But if /FULLSTRING is set, then all characters in the database
value must match the search string (excluding leading and
trailing blanks). Both types of string searches are case
insensitive.
NOTES:
DBMATCH is meant to be used for items which do not have duplicate values
in a database (e.g. catalog numbers). If more than one entry is found
for a particular item value, then only the first one is stored in LIST.
When linked databases are opened together, DBMATCH can only be
used to search on items in the primary database.
EXAMPLE:
Make a vector which points from entries in the Yale Bright Star catalog
to those in the Hipparcos catalog, using the HD number
IDL> dbopen, 'yale_bs' ;Open the Yale Bright star catalog
IDL> dbext, -1, 'HD', hd ;Get the HD numbers
IDL> dbopen, 'hipparcos' ;Open the Hipparcos catalog
IDL> list = dbmatch( 'HD', HD) ;Get entries in Hipparcos catalog
;corresponding to each HD number.
PROCEDURE CALLS:
DB_ITEM, DB_ITEM_INFO(), DBEXT, DBFIND_SORT()
REVISION HISTORY:
Written, W. Landsman STX February, 1990
Fixed error when list in parameter used May, 1992
Faster algorithm with sorted item when listin parameter supplied
Added keyword FULLSTRING,check for empty database, William Thompson,
GSFC, 15 March 1995
Work for more than 32767 values, added CATCH W. Landsman July 1997
Converted to IDL V5.0 W. Landsman 25-Nov-1997
Change some loop variables to type LONG, W. Landsman July 1999
Remove loop for substring searches (faster) W. landsman August 1999
(See /host/bluemoon/usr2/idllib/astron/pro/dbmatch.pro)
DBOPEN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBOPEN
PURPOSE:
Routine to open an IDL database
CALLING SEQUENCE:
dbopen, name, update
INPUTS:
name - (Optional) name or names of the data base files to open.
It has one of the following forms:
'name' -open single data base file
'name1,name2,...,nameN' - open N files which are
connected via pointers.
'name,*' -Open the data base with all data
bases connected via pointers
'' -Interactively allow selection of
the data base files.
If not supplied then '' is assumed.
name may optionally be a string array with one name
per element.
update - (Optional) Integer flag specifing openning for update.
0 - Open for read only
1 - Open for update
2 - Open index file for update only
!PRIV must be 2 or greater to open a file for update.
If a file is opened for update only a single data base
can be specified.
OUTPUTS:
none
KEYWORDS:
UNAVAIL - If present, a "database doesn't exit" flag is returned
through it. 0 = the database exists and was opened (if
no other errors arose). 1 = the database doesn't exist.
Also if present, the error message for non-existent databases
is suppressed. The action, however, remains the same. If
specifiying this, be sure that the variable passed exists
before the call to DBOPEN.
SIDE EFFECTS:
The .DBF and .dbx files are opened using unit numbers obtained by
GET_LUN. Descriptions of the files are placed in the common block
DB_COM.
HISTORY:
Version 2, D. Lindler, Nov. 1987
For IDL Version 2 W. Landsman May 1990 -- Will require further
modfication once SCREEN_SELECT is working
Modified to work under Unix, D. Neill, ACC, Feb 1991.
UNAVAIL keyword added. M. Greason, Hughes STX, Feb 1993.
William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
8/29/95 JKF/ACC - forces lowercase for input database names.
W. Landsman, Use CATCH to catch errors July, 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbopen.pro)
DBPRINT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBPRINT
PURPOSE:
Procedure to print specified items from a list of database entries
CALLING SEQUENCE:
dbprint, list, [items, FORMS= , TEXTOUT= , /NoHeader]
INPUTS:
list - list of entry numbers to be printed, vector or scalar
if list = -1, then all entries will be printed.
An error message is returned if any entry number is larger
than the number of entries in the database
OPTIONAL INPUT-OUTPUT:
items - items to be printed, specified in any of the following ways:
form 1 scalar string giving item(s) as list of names
separated by commas
form 2 string array giving list of item names
form 3 string of form '$filename' giving name
of text file containing items (one item per
line)
form 4 integer scalar giving single item number or
integer vector list of item numbers
form 5 Null string specifying interactive selection. This
is the default if 'items' is not supplied
form 6 '*' select all items, printout will be in
table format.
If items was undefined or a null string on input, then
on output it will contain the items interactively selected.
OPTIONAL INPUT KEYWORDS:
FORMS - The number of printed lines per page. If forms is not
present, output assumed to be in PORTRAIT form, and
a heading and 47 lines are printed on each page, with
a page eject between each page. For LANDSCAPE form with
headings on each page, and a page eject between pages, set
forms = 34. For a heading only on the first page, and no
page eject, set forms = 0. This is the default for output
to the terminal.
TEXTOUT - Integer (0-7) used to determine output device (see TEXTOPEN
for more info). If not present, the !TEXTOUT system variable is used.
textout=0 Nowhere
textout=1 if a TTY then TERMINAL using /more option
otherwise standard (Unit=-1) output
textout=2 if a TTY then TERMINAL without /more option
otherwise standard (Unit=-1) output
textout=3 dbprint.prt (file)
textout=4 laser.tmp
textout=5 user must open file
textout=7 same as 3 but text is appended to .prt
textout = filename (default extension of .prt)
/NOHEADER - If this keyword is set, then the column headers will not
be printed
EXAMPLE:
The following example shows how a multiple valued item DATAMAX can be
printed as separate columns. In the WFPC2 target database, DATAMAX
is an item with 4 values, one for each of the 4 chips
IDL> dbopen,'wflog'
IDL> dbprint,list,'entry,datamax(0),datamax(1),datamax(2),datamax(3)'
SYSTEM VARIABLES:
Output device controlled by non-standard system varaible !TEXTOUT, if
TEXTOUT keyword is not used.
NOTES:
Users may want to adjust the default lines_per_page value given at
the beginning of the program for their own particular printer.
HISTORY:
version 2 D. Lindler Nov. 1987 (new db format)
Test if user pressed 'Q' in response to /MORE W. Landsman Sep 1991
Apply STRTRIM to free form (table) output W. Landsman Dec 1992
Test for string value of TEXTOUT W. Landsman Feb 1994
William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
W. Landsman, GSFC, July, 1997, Use CATCH to catch errors
Converted to IDL V5.0 W. Landsman September 1997
Removed STRTRIM in table format output to handle byte values April 1999
Fixed occasional problem when /NOHEADER is supplied Sep. 1999
Only byteswap when necessary for improved performance Feb. 2000
Change loop index for table listing to type LONG W. Landsman Aug 2000
(See /host/bluemoon/usr2/idllib/astron/pro/dbprint.pro)
DBPUT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBPUT
PURPOSE:
Procedure to place a new value for a specified item into
a data base file entry.
CALLING SEQUENCE:
dbput, item, val, entry
INPUTS:
item - item name or number
val - item value(s)
INPUT/OUTPUT:
entry - entry (byte array) or scalar entry number.
if entry is a scalar entry number then the data
base file will be updated. Otherwise the change
will be only made to the entry array which must
be written latter using DBWRT.
OPERATIONAL NOTES:
If entry is a scalar entry number or the input file name
is supplied, the entry in the data base will be updated
instead of a supplied entry variable. In this case, !priv
must be greater than 1.
HISTORY:
version 2 D. Lindler Feb 1988 (new db formats)
modified to convert blanks into zeros correctly D. Neill Jan 1991
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbput.pro)
DBRD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBRD
PURPOSE:
procedure to read an entry from a data base file or from
linked multiple databases.
CALLING SEQUENCE:
dbrd, enum, entry, [available, dbno, /NoConvert]
INPUTS:
enum - entry number to read, integer scalar
OUTPUT:
entry - byte array containing the entry
OPTIONAL OUTPUT:
available - byte array with length equal to number of data
bases opened. available(i) eq 1 if an entry (pointed
to) is available. It always equals 1 for the first
data base, otherwise it is an error condition.
OPTIONAL INPUT:
dbno - specification of the data base number to return. If
supplied, only the record for the requested data base
number is returned in entry. Normally this input should
not be supplied. dbno is numbered for 0 to n-1 and gives
the number of the data base opened. The data bases are
numbered in the order supplied to dbopen. If dbno is supplied
then the entry number refers to that data base and not the
primary or first data base. If set to -1, then it means all
data bases opened (same as not supplying it)
OPTIONAL INPUT KEYWORD:
noconvert - if set then don't convert external to host format.
Assumes that calling program will take care of this
requirement.
OPERATIONAL NOTES:
If multiple data base files are opened, the records are
concatenated with each other
HISTORY
version 2 D. Lindler Nov. 1987
William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
Version 3, Richard Schwartz, GSFC/SDAC, 23-Aug-1996
Add noconvert keyword
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbrd.pro)
DBSEARCH
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBSEARCH
PURPOSE:
Subroutine of DBFIND() to search a vector for specified values
CALLING SEQUENCE:
dbsearch, type, svals, values, good, FULLSTRING = fullstring
INPUT:
type - type of search (output from dbfparse)
svals - search values (output from dbfparse)
values - array of values to search
OUTPUT:
good - indices of good values
!err is set to number of good values
OPTIONAL INPUT KEYWORD:
FULLSTRING - By default, one has a match if a search string is
included in any part of a database value (substring match).
But if /FULLSTRING is set, then all characters in the database
value must match the search string (excluding leading and
trailing blanks). Both types of string searches are case
insensitive.
REVISION HISTORY:
D. Lindler July,1987
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbsearch.pro)
DBSORT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBSORT
PURPOSE:
Routine to sort list of entries in data base
CALLING SEQUENCE:
result = dbsort( list, items , [ REVERSE = ])
INPUTS:
list - list of entry numbers to sort
-1 to sort all entries
items - list of items to sort (up to 9 items)
OUTPUT:
result - numeric vector giving input list sorted by items
OPTIONAL KEYWORD INPUT:
REVERSE - scalar or vector with the same number of elements as the
the number of items to sort. If the corresponding element of REVERSE
is non-zero then that item is sorted in descending rather than
ascending order.
EXAMPLE:
Sort an astronomical catalog with RA as primary sort, and declination
as secondary sort (used when RA values are equal)
IDL> NEWLIST = DBSORT( -1, 'RA,DEC' )
If for some reason, one wanted the DEC sorted in descending order, but
the RA in ascending order
IDL> NEWLIST = DBSORT( -1, 'RA,DEC', REV = [ 0, 1 ] )
METHOD:
The list is sorted such that each item is sorted into
asscending order starting with the last item.
COMMON BLOCKS:
DBCOM
PROCEDURES USED:
ZPARCHECK, BSORT, DB_ITEM
HISTORY
VERSION 1 D. Lindler Oct. 86
Added REVERSE keyword W. Landsman August, 1991
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbsort.pro)
DBTITLE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBTITLE
PURPOSE:
function to create title line for routine dbprint
CALLING SEQUENCE:
result = dbtitle( c, f )
INPUTS:
c = string array of titles for each item
f = field length of each item
OUTPUT:
header string returned as function value
OPERATIONAL NOTES:
this is a subroutine of DBPRINT.
HISTORY:
version 1 D. Lindler Sept 86
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbtitle.pro)
DBUPDATE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBUPDATE
PURPOSE:
Update columns of data in a database -- inverse of DBEXT
EXPLANATION:
Database must be open for update before calling DBUPDATE
CALLING SEQUENCE:
dbupdate, list, items, v1, [ v2, v3, v4......v14 ]
INPUTS:
list - entries in database to be updated, scalar or vector
If list=-1 then all entries will be updated
items -standard list of items that will be updated.
v1,v2....v14 - vectors containing values for specified items. The
number of vectors supplied must equal the number of items
specified. The number of elements in each vector should be
the same.
EXAMPLES:
A database STAR contains RA and DEC in radians, convert to degrees
IDL> !PRIV=2 & dbopen,'STAR',1 ;Open database for update
IDL> dbext,-1,'RA,DEC',ra,dec ;Extract RA and DEC, all entries
IDL> ra = ra*!RADEG & dec=dec*!RADEG ;Convert to degrees
IDL> dbupdate,-1,'RA,DEC',ra,dec ;Update database with new values
NOTES:
It is quicker to update several items simultaneously rather than use
repeated calls to DBUPDATE.
It is possible to update multiple valued items. In this case, the
input vector should be of dimension (NVAL,NLIST) where NVAL is the
number of values per item, and NLIST is the number of entries to be
updated. This vector will be temporarily transposed by DBUPDATE but
will be restored before DBUPDATE exits.
REVISION HISTORY
Written W. Landsman STX March, 1989
Work for multiple valued items May, 1991
String arrays no longer need to be fixed length December 1992
Transpose multiple array items back on output December 1993
Faster update of external databases on big endian machines November 1997
Converted to IDL V5.0 W. Landsman 24-Nov-1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbupdate.pro)
DBVAL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBVAL
PURPOSE:
procedure to extract value(s) of the specified item from
a data base file entry.
CALLING SEQUENCE:
result = dbval( entry, item )
INPUTS:
entry - byte array containing the entry, or a scalar entry number
item - name (string) or number (integer) of the item
OUTPUT:
the value(s) will be returned as the function value
EXAMPLE:
Extract a flux vector from entry 28 of the database FARUV
==> flux = dbval(28,'FLUX')
HISTORY:
version 2 D. Lindler Nov, 1987 (new db format)
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbval.pro)
DBWRT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBWRT
PURPOSE:
procedure to update or add a new entry to a data base
CALLING SEQUENCE:
dbwrt, entry, [ index, append, /NoConvert ]
INPUTS:
entry - entry record to be updated or added if first
item (entry number=0)
OPTIONAL INPUTS:
index - optional integer flag, if set to non zero then index
file is updated. (default=0, do not update index file)
(Updating the index file is time-consuming, and should
normally be done after all changes have been made.
append - optional integer flag, if set to non-zero the record
is appended as a new entry, regardless of what the
entry number in the record is. The entry number will
be reset to the next entry number in the file.
OUTPUTS:
data base file is updated.
If index is non-zero then the index file is updated.
OPTIONAL INPUT KEYWORD:
NoConvert - If set then don't convert to host format with an external
database. Useful when the calling program decides that
conversion isn't needed (i.e. on a big-endian machine), or
takes care of the conversion itself.
OPERATIONAL NOTES:
!PRIV must be greater than 1 to execute
HISTORY:
version 2 D. Lindler Feb. 1988 (new db format)
converted to IDL Version 2. M. Greason, STX, June 1990.
William Thompson, GSFC/CDS (ARC), 28 May 1994
Added support for external (IEEE) representation.
Converted to IDL V5.0 W. Landsman 24-Nov-1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbwrt.pro)
DBXPUT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBXPUT
PURPOSE:
routine to replace value of an item in a data base entry
CALLING SEQUENCE:
dbxput, val, entry, idltype, sbyte, nbytes
INPUT:
val - value(s) to be placed into entry, string values might be
truncated to fit number of allowed bytes in item
entry - entry or entries to be updated
idltype - idl data type for item (1-7)
sbyte - starting byte in record
nbytes - total number of bytes in value added
OUTPUT:
entry - (updated)
OPERATIONAL NOTES:
This routine assumes that the calling procedure or user knows what he
or she is doing. String items are truncated or padded to the fixed
size specified by the database but otherwise no validity checks are
made.
HISTORY:
version 1, D. Lindler Aug, 1986
converted to IDL Version 2. M. Greason, STX, June 1990.
Work with multiple element string items W. Landsman August 1995
Really work with multiple element string items
R. Bergman/W. Landsman July 1996
Work with multiple entries, R. Schwartz, GSFC/SDAC August 1996
Use /overwrite with REFORM() W. Landsman May 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbxput.pro)
DBXVAL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DBXVAL
PURPOSE:
Quickly return a value of the specified item number
EXPLANATION:
Procedure to quickly return a value of the specified item number
from the entry.
CALLING SEQUENCE:
result = dbxval( entry, idltype, nvalues, sbyte, nbytes )
INPUTS
entry - entry or entries from data base (bytarr)
idltype - idl data type (obtained with db_item_info)
nvalues - number of values to return (obtained with db_item)
sbyte - starting byte in the entry (obtained with db_item)
nbytes - number of bytes (needed only for string type)
(obtained with db_item)
OUTPUTS:
function value is value of the specified item in entry
RESTRICTIONS:
To increase speed the routine assumes that entry and item are
valid and that the data base is already opened using dbopen.
REVISION HISTORY:
version 0 D. Lindler Nov. 1987 (for new db format)
Version 1, William Thompson, GSFC, 28 March 1994.
Incorporated into CDS library.
Version 2, Richard Schwartz, GSFC/SDAC, 23 August 1996
Allowed Entry to have 2 dimensions
Version 2.1, 22 Feb 1997, JK Feggans,
avoid reform for strings arrays.
Version 2.2 Use overwrite with REFORM(), W. Landsman, May 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dbxval.pro)
DB_ENT2EXT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DB_ENT2EXT
PURPOSE:
Convert a database entry to external (IEEE) data format
EXPLANATION:
Converts a database entry to external (IEEE) data format prior to
writing it. Called from DBWRT.
CALLING SEQUENCE:
DB_ENT2EXT, ENTRY
INPUTS:
ENTRY = Byte array containing a single record to be written to the
database file.
OUTPUTS:
ENTRY = The converted array is returned in place of the input array.
COMMON BLOCKS:
DB_COM
HISTORY:
Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994
Version 2, William Thompson, GSFC/CDS (ARC), 15 September 1995
Fixed bug where only the first element in a
multidimensional array was converted.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/db_ent2ext.pro)
DB_ENT2HOST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DB_ENT2HOST
PURPOSE:
Converts a database entry from external data format to host format.
EXPLANATION:
All items are extracted from the entry, and then converted to host
format, and placed back into the entry. Called from DBRD and DBEXT_DBF.
CALLING SEQUENCE:
DB_ENT2HOST, ENTRY, DBNO
INPUTS:
ENTRY = Byte array containing a single record read from the
database file.
DBNO = Number of the opened database file.
OUTPUTS:
ENTRY = The converted array is returned in place of the input array.
COMMON BLOCKS:
DB_COM
HISTORY:
Version 1, William Thompson, GSFC/CDS (ARC), 1 June 1994
Version 2, William Thompson, GSFC/CDS (ARC), 15 September 1995
Fixed bug where only the first element in a
multidimensional array was converted.
Version 3, Richard Schwartz, GSFC/SDAC, 23 August 1996
Allow 2 dimensional byte arrays for entries to facilitate
multiple entry processing. Pass IDLTYPE onto IEEE_TO_HOST
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/db_ent2host.pro)
DB_INFO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DB_INFO
PURPOSE:
Function to obtain information on opened data base file(s)
CALLING SEQUENCES:
1) result = db_info(request)
2) result = db_info(request,dbname)
INPUTS (calling sequence 1):
request - string specifying requested value(s)
value of request value returned in result
'open' Flag set to 1 if data base(s) are opened
'number' Number of data base files opened
'items' Total number of items (all db's opened)
'update' update flag (1 if opened for update)
'unit_dbf' Unit number of the .dbf files
'unit_dbx' Unit number of the .dbx files
'entries' Number of entries in the db's
'length' Record lengths for the db's
'external' True if the db's are in external format
INPUTS (calling sequence 2):
request - string specifying requested value(s)
value of request value returned in result
'name' Name of the data base
'number' Sequential number of the db
'items' Number of items for this db
'item1' Position of item1 for this db
in item list for all db's
'item2' Position of last item for this db.
'pointer' Number of the item which points
to this db. 0 for first or primary
db. -1 if link file pointers.
'length' Record length for this db.
'title' Title of the data base
'unit_dbf' Unit number of the .dbf file
'unit_dbx' Unit number of the .dbx file
'entries' Number of entries in the db
'seqnum' Last sequence number used
'alloc' Allocated space (# entries)
'update' 1 if data base opened for update
'external' True if data base in external format
dbname - data base name or number
OUTPUTS:
Requested value(s) are returned as the function value.
HISTORY:
version 1 D. Lindler Oct. 1987
changed type from 1 to 7 for IDLV2, J. Isensee, Nov., 1990
William Thompson, GSFC/CDS (ARC), 30 May 1994
Added EXTERNAL request type.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/db_info.pro)
DB_ITEM
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DB_ITEM
PURPOSE:
Returns the item numbers and other info. for an item name.
EXPLANATION:
Procedure to return the item numbers and other information
of a specified item name
CALLING SEQUENCE:
db_item, items, itnum, ivalnum, idltype, sbyte, numvals, nbytes
INPUTS:
items - item name or number
form 1 scalar string giving item(s) as list of names
separated by commas
form 2 string array giving list of item names
form 3 string of form '$filename' giving name
of text file containing items (one item per
line)
form 4 integer scalar giving single item number or
integer vector list of item numbers
form 5 Null string specifying interactive selection
Upon return items will contain selected items
in form 1
form 6 '*' select all items
OUTPUTS:
itnum - item number
ivalnum - value(s) number from multiple valued item
idltype - data type(s) (1=string,2=byte,4=i*4,...)
sbyte - starting byte(s) in entry
numvals - number of data values for item(s)
It is the full length of a vector item unless
a subscript was supplied
nbytes - number of bytes for each value
All outputs are vectors even if a single item is requested
OPTIONAL INPUT KEYWORDS:
ERRMSG = If defined and passed, then any error messages will
be returned to the user in this parameter rather than depending
on the MESSAGE routine in IDL. If no errors are encountered,
then a null string is returned. In order to use this feature,
ERRMSG must be defined first, e.g.
ERRMSG = ''
DB_ITEM, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
PROCEDURE CALLS:
DATATYPE, DB_INFO, GETTOK, SCREEN_SELECT, SPEC_DIR
REVISION HISTORY:
Written : D. Lindler, GSFC/HRS, October 1987
Version 2, William Thompson, GSFC, 17-Mar-1997
Added keyword ERRMSG
Converted to IDL V5.0 W. Landsman October 1997
(See /host/bluemoon/usr2/idllib/astron/pro/db_item.pro)
DB_ITEM_INFO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DB_ITEM_INFO
PURPOSE:
routine to return information on selected item(s) in the opened
data bases.
CALLING SEQUENCE:
result = db_item_info( request, itnums)
INPUTS:
request - string giving the requested information.
'name' - item names
'idltype' - IDL data type (integers)
see documentation of intrinsic SIZE funtion
'nvalues' - vector item length (1 for scalar)
'sbyte' - starting byte in .dbf record (use bytepos
to get starting byte in record returned by
dbrd)
'nbytes' - bytes per data value
'index' - index types
'description' - description of the item
'pflag' - pointer item flags
'pointer' - data bases the items point to
'format' - print formats
'flen' - print field length
'headers' - print headers
'bytepos' - starting byte in dbrd record for the items
'dbnumber' - number of the opened data base
'pnumber' - number of db it points to (if the db is
opened)
'itemnumber' - item number in the file
itnums -(optional) Item numbers. If not supplied info on all items
are returned.
OUTPUT:
Requested information is returned as a vector. Its type depends
on the item requested.
HISTORY:
version 1 D. Lindler Nov. 1987
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/db_item_info.pro)
DB_OR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DB_OR
PURPOSE:
Combine two vectors of entry numbers, removing duplicate values.
EXPLANATION:
DB_OR can also be used to remove duplicate values from any longword
vector
CALLING SEQUENCE:
LIST = DB_OR( LIST1 ) ;Remove duplicate values from LIST1
or
LIST = DB_OR( LIST1, LIST2 ) ;Concatenate LIST1 and LIST2, remove dups
INPUTS:
LIST1, LIST2 - Vectors containing entry numbers, must be non-negative
integers or longwords.
OUTPUT:
LIST - Vector containing entry numbers in either LIST1 or LIST2
METHOD
DB_OR returns where the histogram of the entry vectors is non-zero
PROCEDURE CALLS
ZPARCHECK - checks parameters
REVISION HISTORY:
Written, W. Landsman February, 1989
Check for degenerate values W.L. February, 1993
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/db_or.pro)
DB_TITLES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DB_TITLES
PURPOSE:
Print database name and title. Called by DBHELP
CALLING SEQUENCE:
db_titles, fnames, titles
INPUT:
fnames - string array of data base names
SIDE EFFECT:
Database name is printed along with the description in the .dbh file
HISTORY:
version 2 W. Landsman May, 1989
modified to work under Unix, D. Neill, ACC, Feb 1991.
William Thompson, GSFC/CDS (ARC), 1 June 1994
Added support for external (IEEE) representation.
William Thompson, GSFC, 3 November 1994
Modified to allow ZDBASE to be a path string.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/db_titles.pro)
DEF_DIRLIST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DEF_DIRLIST
PURPOSE:
Define directory list using setenv or setlog
EXPLANATION:
Environment variables which point to a list of directories can
end up to be very long. In VMS this can be a problem, because logical
names cannot be longer than 256 characters. However, it is possible to
get around this in VMS by assigning multiple values to a single logical
name--a facility that does not exist in Unix.
This routine will define the environment variable as either a delimited
string, or as a series of values, whichever is most appropriate.
CALLING SEQUENCE:
DEF_DIRLIST, EVAR, VALUE
INPUTD:
EVAR = The name of the environment variable to define.
VALUE = The value to give to EVAR. This can be either a single,
delimited string, or it can be an array of directory names.
The routine will choose for itself how to use this to define the
environment variable.
EXAMPLES:
DIRS = FIND_ALL_DIR('+/data/fits')
DEF_DIRLIST, 'FITS_DATA', DIRS
PROCEDURE CALLS:
SETENV, STR_SEP()
Note: The intrinsic SETENV command is available under Unix & Windows
only. However, it is available as a Library procedure for VMS.
REVISION HISTORY:
Version 1, 06-Aug-1996, William Thompson, GSFC
Converted to IDL V5.0 June 1998 W. Landsman
(See /host/bluemoon/usr2/idllib/astron/pro/def_dirlist.pro)
DELVARX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DELVARX
PURPOSE:
Delete variables for memory management (can call from routines)
EXPLANATION:
Like intrinsic DELVAR function, but can be used from any calling level
CALLING SEQUENCE:
DELVARX, a [,b,c,d,e,f,g,h,i,j]
INPUTS:
p0, p1...p9 - variables to delete
RESTRICTIONS:
Can't use recursively due to EXECUTE function
METHOD:
Uses EXECUTE and TEMPORARY function
REVISION HISTORY:
Copied from the Solar library, written by slf, 25-Feb-1993
Added to Astronomy Library, September 1995
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/delvarx.pro)
DEREDD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DEREDD
PURPOSE:
Deredden stellar Stromgren parameters given for a value of E(b-y)
EXPLANATION:
See the procedure UVBYBETA for more info.
CALLING SEQUENCE:
deredd, eby, by, m1, c1, ub, by0, m0, c0, ub0
INPUTS:
Eby - color index E(b-y),scalar (E(b-y) = 0.73*E(B-V) )
by - b-y color (observed)
m1 - Stromgren line blanketing parameter (observed)
c1 - Stromgren Balmer discontinuity parameter (observed)
ub - u-b color (observed)
OUTPUTS:
by0 - b-y color (dereddened)
m0 - Line blanketing index (dereddened)
c0 - Balmer discontinuity parameter (dereddened)
ub0 - u-b color (dereddened)
REVISION HISTORY:
Adapted from FORTRAN routine DEREDD by T.T. Moon
W. Landsman STX Co. April, 1988
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/deredd.pro)
DETABIFY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DETABIFY
PURPOSE:
Replaces tabs in character strings with appropriate number of spaces
EXPLANATION:
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.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/detabify.pro)
DISMOUNT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DISMOUNT
PURPOSE:
Emulates the VMS DISMOUNT function in Unix.
EXPLANATION :
Emulates the VMS DISMOUNT function in the Unix environment.
Although this is not a standard IDL function, it is available
as a separate LINKIMAGE routine for VMS.
The main purpose of this procedure is to close the file unit
open on the tape device, and optionally to unload the tape.
Errors can result if the tape is unloaded manually rather than
using this routine.
**Unix only**
CALLING SEQUENCE:
DISMOUNT, UNIT
Inputs : UNIT = Tape unit number. Tape drives are selected via the UNIX
environment variables "MT1", "MT2", etc. The desired
tape drive is thus specified by numbers, as in VMS.
Must be from 0 to 9.
Opt. Inputs : None.
Outputs : None.
Opt. Outputs: None.
Keywords : NOUNLOAD = If set, then the tape is simply rewound, not taken
off line.
Calls : CHECK_TAPE_DRV
Common : CHCK_TAPE_DRVS contains array TAPE_LUN, containing logical unit
numbers for each tape device, and TAPE_OPEN, which tells
whether each device is open or not.
Restrictions: The environment variable "MTn", where n corresponds to the
variable UNIT, must be defined. E.g.,
setenv MT0 /dev/nrst0
Requires IDL v3.0 or later.
Side effects: The device file is opened.
Category : Utilities, I/O, Tape.
Prev. Hist. : None.
Written : William Thompson, GSFC, 21 December 1993.
Modified : Version 1, William Thompson, GSFC, 21 December 1993.
Version : Version 1, 21 December 1993.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/dismount.pro)
DIST_CIRCLE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DIST_CIRCLE
PURPOSE:
Form a square array where each value is its distance to a given center.
EXPLANATION:
Returns a square array in which the value of each element is its
distance to a specified center. Useful for circular aperture photometry.
CALLING SEQUENCE:
DIST_CIRCLE, IM, N, [ XCEN, YCEN, /DOUBLE ]
INPUTS:
N = either a scalar specifying the size of the N x N square output
array, or a 2 element vector specifying the size of the
N x M rectangular output array.
OPTIONAL INPUTS:
XCEN,YCEN = Scalars designating the X,Y pixel center. These need
not be integers, and need not be located within the
output image. If not supplied then the center of the output
image is used (XCEN = YCEN = (N-1)/2.).
OUTPUTS:
IM - N by N (or M x N) floating array in which the value of each
pixel is equal to its distance to XCEN,YCEN
OPTIONAL INPUT KEYWORD:
/DOUBLE - If this keyword is set and nonzero, the output array will
be of type DOUBLE rather than floating point.
EXAMPLE:
Total the flux in a circular aperture within 3' of a specified RA
and DEC on an 512 x 512 image IM, with a header H.
IDL> adxy, H, RA, DEC, x, y ;Convert RA and DEC to X,Y
IDL> getrot, H, rot, cdelt ;CDELT gives plate scale deg/pixel
IDL> cdelt = cdelt*3600. ;Convert to arc sec/pixel
IDL> dist_circle, circle, 512, x, y ;Create a distance circle image
IDL> circle = circle*abs(cdelt[0]) ;Distances now given in arcseconds
IDL> good = where(circle LT 180) ;Within 3 arc minutes
IDL> print,total( IM[good] ) ;Total pixel values within 3'
RESTRICTIONS:
The speed of DIST_CIRCLE decreases and the the demands on virtual
increase as the square of the output dimensions. Users should
dimension the output array as small as possible, and re-use the
array rather than re-calling DIST_CIRCLE
MODIFICATION HISTORY:
Adapted from DIST W. Landsman March 1991
Allow a rectangular output array W. Landsman June 1994
Converted to IDL V5.0 W. Landsman September 1997
Add /DOUBLE keyword, make XCEN,YCEN optional W. Landsman Jun 1998
(See /host/bluemoon/usr2/idllib/astron/pro/dist_circle.pro)
DIST_ELLIPSE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
DIST_ELLIPSE
PURPOSE:
Create a mask array useful for elliptical aperture photemetry
EXPLANATION:
Form an array in which the value of each element is equal to the
semi-major axis of the ellipse of specified center, axial ratio, and
position angle, which passes through that element. Useful for
elliptical aperture photometry.
CALLING SEQUENCE:
DIST_ELLIPSE, IM, N, XC, YC, RATIO, POS_ANG, /DOUBLE
INPUTS:
N = either a scalar specifying the size of the N x N square output
array, or a 2 element vector specifying the size of the
M x N rectangular output array.
XC,YC - Scalars giving the position of the ellipse center. This does
not necessarily have to be within the image
RATIO - Scalar giving the ratio of the major to minor axis. This
should be greater than 1 for postion angle to have its
standard meaning.
OPTIONAL INPUTS:
POS_ANG - Position angle of the major axis, measured counter-clockwise
from the Y axis. For an image in standard orientation
(North up, East left) this is the astronomical position angle.
OPTIONAL INPUT KEYWORD:
/DOUBLE - If this keyword is set and nonzero, the output array will
be of type DOUBLE rather than floating point.
OUTPUT:
IM - REAL*4 elliptical mask array, of size M x N. THe value of each
pixel is equal to the semi-major axis of the ellipse of center
XC,YC, axial ratio RATIO, and position angle POS_ANG, which
passes through the pixel.
EXAMPLE:
Total the flux in a elliptical aperture with a major axis of 3', an
axial ratio of 2.3, and a position angle of 25 degrees centered on
a specified RA and DEC. The image array, IM is 200 x 200, and has
an associated FITS header H.
ADXY, H, ra, dec, x, y ;Get X and Y corresponding to RA and Dec
GETROT, H, rot, cdelt ;CDELT gives plate scale degrees/pixel
cdelt = abs( cdelt)*3600. ;CDELT now in arc seconds/pixel
DIST_ELLIPSE, ell, 200, x, y, 2.3, 25 ;Create a elliptical image mask
ell = ell*cdelt(0) ;Distances now given in arcseconds
good = where( ell lt 180 ) ;Within 3 arc minutes
print,total( im(good) ) ;Total pixel values within 3'
RESTRICTIONS:
The speed of DIST_ELLIPSE decreases and the the demands on virtual
increase as the square of the output dimensions. Users should
dimension the output array as small as possible, and re-use the
array rather than re-calling DIST_ELLIPSE
REVISION HISTORY:
Written W. Landsman April, 1991
Somewhat faster algorithm August, 1992
Allow rectangular output array June, 1994
Converted to IDL V5.0 W. Landsman September 1997
Added /DOUBLE keyword W. Landsman July 2000
(See /host/bluemoon/usr2/idllib/astron/pro/dist_ellipse.pro)
EQPOLE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
EQPOLE
PURPOSE:
Convert RA and Dec to X,Y using an equal-area polar projection.
EXPLANATION:
The output X and Y coordinates are scaled to be between
-90 and +90 to go from equator to pole to equator. Output map points
can be centered on the north pole or south pole.
CALLING SEQUENCE:
EQPOLE, L, B, X, Y, [ /SOUTHPOLE ]
INPUTS:
L - longitude - scalar or vector, in degrees
B - latitude - same number of elements as RA, in degrees
OUTPUTS:
X - X coordinate, same number of elements as RA. X is normalized to
be between -90 and 90.
Y - Y coordinate, same number of elements as DEC. Y is normalized to
be between -90 and 90.
KEYWORDS:
/SOUTHPOLE - Keyword to indicate that the plot is to be centered
on the south pole instead of the north pole.
REVISION HISTORY:
J. Bloch LANL, SST-9 1.1 5/16/91
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/eqpole.pro)
EQPOLE_GRID
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
EQPOLE_GRID
PURPOSE:
Produce an equal area polar projection grid overlay
EXPLANATION:
Grid is written on the current graphics device using the equal area
polar projection. EQPOLE_GRID assumes that the output plot
coordinates span the x and y ranges of -90 to 90 for a region that
covers the equator to the chosen pole. The grid is assumed to go from
the equator to the chosen pole.
CALLING SEQUENCE:
EQPOLE_GRID[,DLONG,DLAT,[/SOUTHPOLE,LINESTYLE=N, LABEL = , /NEW]
INPUTS:
DLONG = Optional input longitude line spacing in degrees. If left
out, defaults to 30.
DLAT = Optional input lattitude line spacing in degrees. If left
out, defaults to 30.
INPUT KEYWORDS:
/SOUTHPOLE = Optional flag indicating that the output plot is
to be centered on the south rather than the north
pole.
LINESTYLE = Optional input integer specifying the linestyle to
use for drawing the grid lines.
LABEL = Optional flag for creating labels on the output
grid on the prime meridian and the equator for
lattitude and longitude lines. If set =2, then
the longitude lines are labeled in hours and minutes.
/NEW = If this keyword is set, then EQPOLE_GRID will create
a new plot, rather than overlay an existing plot.
OUTPUTS:
Draws grid lines on current graphics device.
EXAMPLE:
Create a labeled equal area projection grid of the Galaxy, centered on
the South pole, and overlay stars at specified Galactic longitudes,
glong and latitudes, glat
IDL> eqpole_grid,/label,/new,/south ;Create labeled grid
IDL> eqpole, glong, glat, x,y ;Convert to X,Y coordinates
IDL> plots,x,y,psym=2 ;Overplot "star" positions.
COPYRIGHT NOTICE:
Copyright 1992, The Regents of the University of California. This
software was produced under U.S. Government contract (W-7405-ENG-36)
by Los Alamos National Laboratory, which is operated by the
University of California for the U.S. Department of Energy.
The U.S. Government is licensed to use, reproduce, and distribute
this software. Neither the Government nor the University makes
any warranty, express or implied, or assumes any liability or
responsibility for the use of this software.
AUTHOR AND MODIFICATIONS:
J. Bloch 1.4 10/28/92
Converted to IDL V5.0 W. Landsman September 1997
Create default plotting coords, if needed W. Landsman August 2000
(See /host/bluemoon/usr2/idllib/astron/pro/eqpole_grid.pro)
EULER
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
EULER
PURPOSE:
Transform between Galactic, celestial, and ecliptic coordinates.
EXPLANATION:
Use the procedure ASTRO to use this routine interactively
CALLING SEQUENCE:
EULER, AI, BI, AO, BO, [ SELECT, /FK4 ]
INPUTS:
AI - Input Longitude in DEGREES, scalar or vector. If only two
parameters are supplied, then AI and BI will be modified to
contain the output longitude and latitude.
BI - Input Latitude in DEGREES
OPTIONAL INPUT:
SELECT - Integer (1-6) specifying type of coordinate transformation.
SELECT From To | SELECT From To
1 RA-Dec (2000) Galactic | 4 Ecliptic RA-Dec
2 Galactic RA-DEC | 5 Ecliptic Galactic
3 RA-Dec Ecliptic | 6 Galactic Ecliptic
If omitted, program will prompt for the value of SELECT
Celestial coordinates (RA, Dec) should be given in equinox J2000
unless the /FK4 keyword is set.
OUTPUTS:
AO - Output Longitude in DEGREES
BO - Output Latitude in DEGREES
INPUT KEYWORD:
/FK4 - If this keyword is set and non-zero, then input and output
celestial and ecliptic coordinates should be given in equinox
B1950.
NOTES:
EULER was changed in December 1998 to use J2000 coordinates as the
default, ** and may be incompatible with earlier versions***.
REVISION HISTORY:
Written W. Landsman, February 1987
Adapted from Fortran by Daryl Yentis NRL
Converted to IDL V5.0 W. Landsman September 1997
Made J2000 the default, added /FK4 keyword W. Landsman December 1998
(See /host/bluemoon/usr2/idllib/astron/pro/euler.pro)
EXPAND_TILDE()
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
EXPAND_TILDE()
PURPOSE:
Expand tilde in UNIX directory names
CALLING SEQUENCE:
IDL> output=expand_tilde(input)
INPUTS:
INPUT = input file or directory name, scalar string
OUTPUT:
Returns expanded filename, scalar string
EXAMPLES:
output=expand_tilde('~zarro/test.doc')
---> output='/usr/users/zarro'
NOTES:
This version of EXPAND_TILDE differs from the version in the Solar
Library in that it does not call the functions EXIST and IDL_RELEASE.
However, it should work identically.
PROCEDURE CALLS:
DATATYPE()
REVISION HISTORY:
Version 1, 17-Feb-1997, D M Zarro. Written
Transfered from Solar Library W. Landsman Sep. 1997
Made more robust D.Zarro/W. Landsman Sep. 2000
(See /host/bluemoon/usr2/idllib/astron/pro/expand_tilde.pro)
EXTAST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
EXTAST
PURPOSE:
Extract astrometry parameters from a FITS image header.
EXPLANATION:
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) in FITS convention (first pixel is 1,1)
.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. As of Nov 1998,
this is the recommend format
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 preprint: Representations of Celestial Coordinates in FITS by
Griesen and Calabretta, available at
http://www.cv.nrao.edu/fits/documents/wcs/wcs.html
NOTES:
(1) An anonymous structure is created to avoid structure definition
conflicts. This is needed because some projection systems
require additional dimensions (i.e. spherical cube
projections require a specification of the cube face).
PROCEDURES CALLED:
FITS_CD_FIX, GSSSEXTAST, SXPAR(), ZPARCHECK
REVISION HISTORY
Written by B. Boothman 4/15/86
Accept CD001001 keywords 1-3-88
Accept CD1_1, CD2_1... keywords W. Landsman Nov. 92
Recognize GSSS FITS header W. Landsman June 94
Converted to IDL V5.0 W. Landsman September 1997
Get correct sign, when converting CDELT* to CD matrix for right-handed
coordinate system W. Landsman November 1998
(See /host/bluemoon/usr2/idllib/astron/pro/extast.pro)
EXTGRP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
EXTGRP
PURPOSE:
Extract the group parameter information out of SXREAD output
EXPLANATION:
This procedure extracts the group parameter information out of a
header and parameter variable obtained from SXREAD. This allows
astrometry, photometry and other parameters to be easily SXPARed by
conventional methods and allows the image and header to be saved in
a SIMPLE format.
CALLING SEQUENCE:
ExtGrp, hdr, par
INPUT:
HDR - The header which is to be converted (input and output)
PAR - The Parameter string returned from a call to SXREAD
OUTPUT:
HDR - The converted header, string array
OTHER PROCEDURES CALLED:
SXPAR(), SXADDPAR, SXGPAR(), STRN()
HISTORY:
25-JUN-90 Version 1 written
13-JUL-92 Header finally added to this ancient procedure, code spiffed up
a bit. Now 3 times faster. Added PTYPE comment inclusion. E. Deutsch
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/extgrp.pro)
EXTRAP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
EXTRAP
PURPOSE:
This procedure fills in the ends of a one-dimensional array from
interior portions using polynomial extrapolation.
CATEGORY:
Image processing
CALLING SEQUENCE:
EXTRAP, Deg, X, Y, Y2
INPUT POSITIONAL PARAMETERS:
Deg: Degree of polynomial
X: Independent variable
Y: Dependent variable
KEYWORD PARAMETERS:
LIMS: 3-element array giving range of X to be used to fit
polynomial and starting point where extrapolation is
to be substituted; if not given, you click on a plot;
order of elements is [xmin, xmax, xstart]; if LIMS is
specified, then program is silent
OUTPUT POSITIONAL PARAMETERS:
Y2: Dependent variable with extrapolated portion filled in
SIDE EFFECTS:
May pop a window for selecting range.
MODIFICATION HISTORY:
Written by RSH, RITSS, 14 Aug 98
Spiffed up for library. RSH, 6 Oct 98
(See /host/bluemoon/usr2/idllib/astron/pro/skyadj_cube.pro)
FACTOR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FACTOR
PURPOSE:
Find prime factors of a given number.
CALLING SEQUENCE:
FACTOR, x, p, n
INPUTS:
x = Number to factor, scalar positive integer
OUTPUT PARAMETERS:
p = Array of prime numbers.
n = Count of each element of p.
INPUT KEYWORD PARAMETER:
/HELP - Display help documentation
PROCEDURES USED:
PRIME()
Also see numfactors, print_fact in the JHUAPL Library
MODIFICATION HISTORY:
R. Sterner. 4 Oct, 1988.
RES 25 Oct, 1990 --- converted to IDL V2.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1988, Johns Hopkins University/Applied Physics Laboratory
This software may be used, copied, or redistributed as long as it is not
sold and this copyright notice is reproduced on each copy made. This
routine is provided as is without any express or implied warranties
whatsoever. Other limitations apply as described in the file disclaimer.txt.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/factor.pro)
FDECOMP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FDECOMP
PURPOSE:
Routine to decompose a file name for any operating system
CALLING SEQUENCE:
FDECOMP, filename, disk, dir, name, qual, version, [OSFamily = ]
INPUT:
filename - string file name, scalar
OUTPUTS:
All the output parameters are scalar strings
disk - disk name, always '' on a Unix machine, scalar string
dir - directory name, scalar string
name - file name, scalar string
qual - qualifier, set equal to the characters beyond the last "."
version - version number, always '' on a non-VMS machine, scalar string
OPTIONAL INPUT KEYWORD:
OSFamily - one of the four scalar strings specifying the operating
system: 'vms','Windows','MacOS' or 'unix'. If not supplied,
then !VERSION.OS_FAMILY is used to determine the OS.
EXAMPLES:
Consider the following file names
Unix: file = '/rsi/idl40/avg.pro'
VMS: file = '$1$dua5:[rsi.idl40]avg.pro;3
Mac: file = 'Macintosh HD:Programs:avg.pro'
Windows: file = 'd:\rsi\idl40\avg.pro'
then IDL> FDECOMP, file, disk, dir, name, qual, version
will return the following
Disk Dir Name Qual Version
Unix: '' '/rsi/idl40/' 'avg' 'pro' ''
VMS: '$1$dua5' '[RSI.IDL40]' 'avg' 'pro' '3'
Mac: 'Macintosh HD' ':Programs:' 'avg' 'pro' ''
Windows: 'd:' \rsi\idl40\ 'avg' 'pro' ''
NOTES:
(1) All tokens are removed between
1) name and qual (i.e period is removed)
2) qual and ver (i.e. VMS semicolon is removed)
(2) On VMS the filenames "MOTD" and "MOTD." are distinguished by the
fact that qual = '' for the former and qual = ' ' for the latter.
A version of FDECOMP that accepts vector input strings is available for
IDL V5.3 or later from http://idlastro.gsfc.nasa.gov/ftp/v53/
ROUTINES CALLED:
Function GETTOK()
HISTORY
version 1 D. Lindler Oct 1986
Include VMS DECNET machine name in disk W. Landsman HSTX Feb. 94
Converted to Mac IDL, I. Freedman HSTX March 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fdecomp.pro)
FILTER_IMAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FILTER_IMAGE
PURPOSE:
Identical to MEDIAN or SMOOTH but handle edges and allow iterations.
EXPLANATION:
Computes the average and/or median of pixels in moving box,
replacing center pixel with the computed average and/or median,
(using the IDL smooth or median functions).
The main reason for using this function is the options to
also process the pixels at edges and corners of image, and,
to apply iterative smoothing simulating convolution with Gaussian,
and/or to convolve image with a Gaussian kernel.
CALLING SEQUENCE:
Result = filter_image( image, SMOOTH=box_width, /MEDIAN, /ALL )
INPUT:
image = 2-D array (matrix)
OPTIONAL INPUT KEYWORDS:
SMOOTH = scalar (odd) integer specifying the width of a square box
for moving average, in # pixels.
/SMOOTH means use box width = 3 pixels for smoothing.
MEDIAN = scalar (odd) integer specifying the width of square moving
box for median filter, in # pixels.
/MEDIAN means use box width = 3 pixels for median filter.
/ALL_PIXELS causes the edges of image to be filtered as well,
accomplished by reflecting pixels adjacent to edges outward.
/ITERATE means apply smooth(image,3) iteratively for a count of
(box_width-1)/2 times (=radius), when box_width >= 5.
This is equivalent to convolution with a Gaussian PSF
of FWHM = 2 * sqrt( radius ) as radius gets large.
Note that /ALL_PIXELS is automatically applied,
giving better results in the iteration limit.
(also, MEDIAN keyword is ignored when /ITER is specified).
FWHM_GAUSSIAN = Full-width half-max of Gaussian to convolve with image.
FWHM can be a single number (circular beam),
or 2 numbers giving axes of elliptical beam.
/NO_FT_CONVOL causes the convolution to be computed directly,
with IDL function convol.
The default is to use FFT when factors of size are all LE 13.
(note that external function convolve handles both cases)
RESULT:
Function returns the smoothed, median filtered, or convolved image.
If both SMOOTH and MEDIAN are specified, median filter is applied first.
EXAMPLES:
To apply 3x3 moving median filter and
then 3x3 moving average, both applied to all pixels:
Result = filter_image( image, /SMOOTH, /MEDIAN, /ALL )
To iteratively apply 3x3 moving average filter for 4 = (9-1)/2 times,
thus approximating convolution with Gaussian of FWHM = 2*sqrt(4) = 4 :
Result = filter_image( image, SMOOTH=9, /ITER )
To convolve all pixels with Gaussian of FWHM = 3.7 x 5.2 pixels:
Result = filter_image( image, FWHM=[3.7,5.2], /ALL )
EXTERNAL CALLS:
function psf_gaussian
function convolve
pro factor
function prime ;all these called only if FWHM is specified.
PROCEDURE:
If /ALL_PIXELS or /ITERATE keywords are set then
create a larger image by reflecting the edges outward,
then call the IDL median and/or smooth function on the larger image,
and just return the central part (the orginal size image).
HISTORY:
Written, 1991, Frank Varosi, NASA/GSFC.
FV, 1992, added /ITERATE option.
FV, 1993, added FWHM_GAUSSIAN= option.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/filter_image.pro)
FIND
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FIND
PURPOSE:
Find positive brightness perturbations (i.e stars) in an image
EXPLANATION:
Also returns centroids and shape parameters (roundness & sharpness).
Adapted from 1986 STSDAS version of DAOPHOT.
CALLING SEQUENCE:
FIND, image, [ x, y, flux, sharp, round, hmin, fwhm, roundlim, sharplim
PRINT= , /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] ). Change this
default only if the stars have siginificantly larger or
or smaller concentration than a Gaussian
roundlim - 2 element vector giving low and high cutoff for the
roundness statistic (Default: [-1.0,1.0] ). Change this
default only if the stars are significantly elongated.
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.
PRINT - if set and non-zero then T_FIND will also write its results to
a file FIND.PRT. Also one can specify a different output file
name by setting PRINT = 'filename'.
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
NOTES:
The sharpness statistic compares the central pixel to the mean of the
surrounding pixels. If this difference is greater than the originally
estimated height of the Gaussian or less than 0.2 the height of the
Gaussian (for the default values of SHARPLIM) then the star will be
rejected.
PROCEDURE CALLS:
DATATYPE(), GETOPT
REVISION HISTORY:
Written W. Landsman, STX February, 1987
ROUND now an internal function in V3.1 W. Landsman July 1993
Change variable name DERIV to DERIVAT W. Landsman Feb. 1996
Use /PRINT keyword instead of TEXTOUT W. Landsman May 1996
Changed loop indices to type LONG W. Landsman Aug. 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/find.pro)
FINDPRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FINDPRO
PURPOSE:
Find all locations of a procedure in the IDL !PATH
EXPLANATION:
FINDPRO searces for the procedure name (as a .pro or a .sav file) in all
IDL libraries or directories given in the !PATH system variable.
CALLING SEQUENCE:
FINDPRO, [ Proc_Name, /NoPrint, DirList = , ProList = ]
OPTIONAL INPUT:
Proc_Name - Character string giving the name of the IDL procedure or
function. Do not include the ".pro" extension. If Proc_Name is
omitted, the program will prompt for PROC_NAME. "*" wildcards
are permitted.
OPTINAL KEYWORD INPUT:
/NoPrint - if set, then the file's path is not printed on the screen and
absolutely no error messages are printed on the screen. If not
set, then - since the MESSAGE routine is used - error messages
will be printed but the printing of informational messages
depends on the value of the !Quiet variable.
OPTIONAL KEYWORD OUTPUTS:
DirList - The directories in which the file is located are returned in
the keyword as a string array.
If the procedure was found in a VMS text library, then the
full path and name of that library is returned and is prefixed
by an "@" sign as a flag that it is a library, not a directory.
If the procedure is an intrinsic IDL procedure, then the
value of DirList = ['INTRINSIC'].
If the procedure is not found, the value of DirList = [''].
ProList - The list (full pathnames) of procedures found. Useful if you
are looking for the name of a procedure using wildcards.
The order of the names in DirList and ProList is identical to the order
in which the procedure name appears in the !PATH
PROCEDURE:
The system variable !PATH is parsed using EXPAND_PATH into individual
libraries or directories. Each library or directory is then
searched for the procedure name. If not found in !PATH, then the
the name is compared with the list of intrinsic IDL procedures given
by the ROUTINE_INFO function.
EXAMPLE:
(1) Find the procedure CURVEFIT. Assume for this example that the user
also has a copy of the CURVEFIT.PRO procedure in her home directory
on a Unix machine.
IDL> findpro, 'curvefit', DIRLIST=DirList
Procedure curvefit.pro found in directory .
Procedure curvefit.pro found in directory /home/idl/lib/userlib
IDL> help, DirList
DIRLIST STRING = Array(2)
IDL> help, DirList(0), DirList(1)
STRING = '.'
STRING = '/home/idl/lib/userlib'
(2) Find all procedures in one's !path containing the characters "zoom"
IDL> findpro,'*zoom*'
RESTRICTIONS:
User will be unable to find a path for a native IDL function
or procedure, or for a FORTRAN or C routine added with CALL_EXTERNAL.
Remember that Unix is case sensitive, and most procedures will be in
lower case.
PROCEDURES USED:
ZPARCHECK, FDECOMP, UNIQ()
REVISION HISTORY:
Based on code extracted from the GETPRO procedure, J. Parker 1994
Use the intrinsic EXPAND_PATH function W. Landsman Nov. 1994
Use ROUTINE_NAMES() to check for intrinsic procs W. Landsman Jul 95
Added Macintosh, WINDOWS compatibility W. Landsman Sep. 95
Removed spurious first element in PROLIST W. Landsman March 1997
Don't include duplicate directories in !PATH WL May 1997
Converted to IDL V5.0 W. Landsman September 1997
Use ROUTINE_INFO instead of undocumented ROUTINE_NAMES W.L. October 1998
Also check for save sets W. Landsman October 1999
Force lower case check for VMS W. Landsman January 2000
(See /host/bluemoon/usr2/idllib/astron/pro/findpro.pro)
FIND_ALL_DIR()
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FIND_ALL_DIR()
PURPOSE:
Finds all directories under a specified directory.
EXPLANATION:
This routine finds all the directories in a directory tree when the
root of the tree is specified. This provides the same functionality as
having a directory with a plus in front of it in the environment
variable IDL_PATH.
CALLING SEQUENCE:
Result = FIND_ALL_DIR( PATH )
PATHS = FIND_ALL_DIR('+mypath', /PATH_FORMAT)
PATHS = FIND_ALL_DIR('+mypath1:+mypath2')
INPUTS:
PATH = The path specification for the top directory in the tree.
Optionally this may begin with the '+' character but the action
is the same unless the PLUS_REQUIRED keyword is set.
One can also path a series of directories separated
by the correct character ("," for VMS, ":" for Unix)
OUTPUTS:
The result of the function is a list of directories starting from the
top directory passed and working downward from there. Normally, this
will be a string array with one directory per array element, but if
the PATH_FORMAT keyword is set, then a single string will be returned,
in the correct format to be incorporated into !PATH.
OPTIONAL INPUT KEYWORDS:
PATH_FORMAT = If set, then a single string is returned, in
the format of !PATH.
PLUS_REQUIRED = If set, then a leading plus sign is required
in order to expand out a directory tree.
This is especially useful if the input is a
series of directories, where some components
should be expanded, but others shouldn't.
RESET = Often FIND_ALL_DIR is used with logical names. It
can be rather slow to search through these subdirectories.
The /RESET keyword can be used to redefine an environment
variable so that subsequent calls don't need to look for the
subdirectories.
To use /RESET, the PATH parameter must contain the name of a
*single* environment variable. For example
setenv,'FITS_DATA=+/datadisk/fits'
dir = find_all_dir('FITS_DATA',/reset,/plus)
The /RESET keyword is usually combined with /PLUS_REQUIRED.
PROCEDURE CALLS:
DEF_DIRLIST, FIND_WITH_DEF(), BREAK_PATH()
RESTRICTIONS:
PATH must point to a directory that actually exists.
On VMS computers this routine calls a command file, FIND_ALL_DIR.COM
(available only on VMS distribution) to find the directories. This
command file must be in one of the directories in IDL's standard search
path, !PATH.
REVISION HISTORY:
Written : William Thompson, GSFC, 3 May 1993.
Version 6 William Thompson, GSFC, 20 August 1996
Version 7, William Thompson, GSFC, 13 February 1998
Include Windows and MacOS seperators.
Converted to V5.0, March 1998
(See /host/bluemoon/usr2/idllib/astron/pro/find_all_dir.pro)
FIND_WITH_DEF()
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FIND_WITH_DEF()
PURPOSE:
Searches for files with a default path and extension.
EXPLANATION:
Finds files using default paths and extensions, similar to using the
DEFAULT keyword with the OPEN statement in VMS. Using this routine
together with environment variables allows an OS-independent approach
to finding files.
CALLING SEQUENCE:
Result = FIND_WITH_DEF( FILENAME, PATHS [, EXTENSIONS ] )
INPUTS:
FILENAME = Name of file to be searched for. It may either be a
complete filename, or the path or extension could be left
off, in which case the routine will attempt to find the
file using the default paths and extensions.
PATHS = One or more default paths to use in the search in case
FILENAME does not contain a path itself. The individual
paths are separated by commas, although in UNIX, colons
can also be used. In other words, PATHS has the same
format as !PATH, except that commas can be used as a
separator regardless of operating system. The current
directory is always searched first, unless the keyword
NOCURRENT is set.
A leading $ can be used in any path to signal that what
follows is an environmental variable, but the $ is not
necessary. (In VMS the $ can either be part of the path,
or can signal logical names for compatibility with Unix.)
Environmental variables can themselves contain multiple
paths.
OPTIONAL INPUTS:
EXTENSIONS = One or more extensions to append to end of filename if the
filename does not contain one (e.g. ".dat"). The period
is optional. Multiple extensions can be separated by
commas or colons.
OUTPUTS:
The result of the function is the name of the file if successful, or
the null string if unsuccessful.
OPTIONAL INPUT KEYWORDS:
NOCURRENT = If set, then the current directory is not searched.
RESET = The FIND_WITH_DEF routine supports paths which are
preceeded with the plus sign to signal that all
subdirectories should also be searched. Often this is
used with logical names. It can be rather slow to search
through these subdirectories. The /RESET keyword can be
used to redefine an environment variable so that
subsequent calls don't need to look for the
subdirectories.
To use /RESET, the PATHS parameter must contain the name
of a *single* environment variable. For example
setenv,'FITS_DATA=+/datadisk/fits'
file = find_with_def('test.fits','FITS_DATA',/reset)
EXAMPLE:
FILENAME = ''
READ, 'File to open: ', FILENAME
FILE = FIND_WITH_DEF( FILENAME, 'SERTS_DATA', '.fix' )
IF FILE NE '' THEN ...
PROCEDURE CALLS:
BREAK_PATH(), FIND_ALL_DIR(), STR_SEP()
REVISION HISTORY:
Version 1, William Thompson, GSFC, 3 May 1993.
Removed trailing / and : characters.
Fixed bugs
Allow for commas within values of logical names.
Added keyword NOCURRENT.
Changed to call BREAK_PATH
Version 2, William Thompson, GSFC, 3 November 1994
Made EXTENSIONS optional.
Version 3, William Thompson, GSFC, 30 April 1996
Call FIND_ALL_DIR to resolve any plus signs.
Version 4, S.V. Haugan, UiO, 5 June 1996
Using OPENR,..,ERROR=ERROR to avoid an IDL 3.6
internal nesting error.
Version 5, R.A. Schwartz, GSFC, 11 July 1996
Use SPEC_DIR to interpret PATH under VMS
Version 6, William Thompson, GSFC, 5 August 1996
Took out call to SPEC_DIR (i.e., reverted to version 4). The
use of SPEC_DIR was required to support logical names defined
via SETLOG,/CONFINE. However, it conflicted with the ability
to use logical names with multiple values. Removing the
/CONFINE made it unnecessary to call SPEC_DIR in this routine.
Version 7, William Thompson, GSFC, 6 August 1996
Added keyword RESET
Converted to IDL V5.0 W. Landsman October 1997
Use STRTRIM instead of TRIM, W. Landsman November 1998
(See /host/bluemoon/usr2/idllib/astron/pro/find_with_def.pro)
FITEXY
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FITEXY
PURPOSE:
Best straight-line fit to data with errors in both coordinates
EXPLANATION:
Linear Least-squares approximation in one-dimension (y = a + b*x),
when both x and y data have errors
CALLING EXAMPLE:
FITEXY, x, y, A, B, X_SIG= , Y_SIG= , [sigma_A_B, chi_sq, q, TOL=]
INPUTS:
x = array of values for independent variable.
y = array of data values assumed to be linearly dependent on x.
REQUIRED INPUT KEYWORDS:
X_SIGMA = scalar or array specifying the standard deviation of x data.
Y_SIGMA = scalar or array specifying the standard deviation of y data.
OPTIONAL INPUT KEYWORD:
TOLERANCE = desired accuracy of minimum & zero location, default=1.e-3.
OUTPUTS:
A_intercept = constant parameter result of linear fit,
B_slope = slope parameter, so that:
( A_intercept + B_slope * x ) approximates the y data.
OPTIONAL OUTPUT:
sigma_A_B = two element array giving standard deviation of
A_intercept and B_slope parameters, respectively.
The standard deviations are not meaningful if (i) the
fit is poor (see parameter q), or (ii) b is so large that
the data are consistent with a vertical (infinite b) line.
If the data are consistent with *all* values of b, then
sigma_A_B = [1e33,e33]
chi_sq = resulting minimum Chi-Square of Linear fit, scalar
q - chi-sq probability, scalar (0-1) giving the probability that
a correct model would give a value equal or larger than the
observed chi squared. A small value of q indicates a poor
fit, perhaps because the errors are underestimated.
COMMON:
common fitexy, communicates the data for computation of chi-square.
PROCEDURE CALLS:
CHISQ_FITEXY() ;Included in this file
MINF_BRACKET, MINF_PARABOLIC, ZBRENT ;In IDL Astronomy Library
MOMENT(), CHISQR_PDF() ;In standard IDL distribution
PROCEDURE:
From "Numerical Recipes" column by Press and Teukolsky:
in "Computer in Physics", May, 1992 Vol.6 No.3
Also see the 2nd edition of the book "Numerical Recipes" by Press et al.
MODIFICATION HISTORY:
Written, Frank Varosi NASA/GSFC September 1992.
Now returns q rather than 1-q W. Landsman December 1992
Converted to IDL V5.0 W. Landsman September 1997
Use CHISQR_PDF, MOMENT instead of STDEV,CHI_SQR1 W. Landsman April 1998
Fixed typo for initial guess of slope, this error was nearly
always insignificant W. Landsman March 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fitexy.pro)
FITSDIR
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FITSDIR
PURPOSE:
Provide a brief description of the primary headers of FITS disk files.
EXPLANATION:
The values of the FITS keywords NAXISi, OBS-DATE (or TDATEOBS or DATE),
TELESCOPE (or INSTRUME), OBJECT (or TARGNAME), EXPTIME (or INTEG) are
displayed. All of these are commonly used FITS keywords
and all except EXPTIME are officially reserved FITS keywords.
Keyword names in parentheses are searched if the primary keyword is not
found.
CALLING SEQUENCE:
FITSDIR , [ directory, TEXTOUT =, /NoTelescope ]
OPTIONAL INPUT PARAMETERS:
DIRECTORY - Scalar string giving file name, disk or directory to be
searched. Wildcard file names are allowed. Examples of
valid VMS or Unix names include '*.fit' or 'tape*'. An
example of a valid VMS name is 'UIT$USER2:[JONES]*.FIT' while
a valid Unix string is 'iraf/*.fits'.
If not given, FITSDIR searches *.fits files in the default
directory.
OPTIONAL KEYWORD INPUT PARAMETER
/NOTELESCOPE - If this keyword is set and non-zero then the value of
the (usually less important) TELESCOPE keyword is not
displayed, and more space is available to display the other
keyword values
TEXTOUT - Controls output device as described in TEXTOPEN procedure
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=7 Append to existing .prt file
textout = filename (default extension of .prt)
OUTPUT PARAMETERS:
None.
RESTRICTIONS:
(1) Field values may be truncated if their length exceeds the default
format.
File name NAXISi OBS-DATE TELESCOPE OBJECT EXPTIME
A18 A11 A10 A10 A20 F7.1
A20 A12 A10 A29 F7.1
(2) Only reads the primary FITS headers. FITS files containing
only extensions (binary or ASCII tables) may have little
information in their primary header. Use FITS_HELP or
FTAB_HELP to get info on FITS extensions.
(3) Users may wish to modify the program to display other FITS
keywords of particular interest to them
EXAMPLES:
IDL> fitsdir ;Print info on all '*.fits' files in current
directory.
IDL> fitsdir ,'*.fit' ;Lists all '*.fit' files in current directory
IDL> fitsdir ,'tape*' ;Print info on all tape* files in current
;directory. Files meeting the wildcard name
;that are not FITS files are ignored
Write info on all *.fits files in the Unix directory /usr2/smith, to a
file 'smith.txt' and don't display the value of the TELESCOPE keyword
IDL> fitsdir ,'/usr2/smith/*.fits',t='smith.txt', /NoTel
PROCEDURE:
FINDFILE is used to find the specified FITS files. The header of
each file is read, and rejected if the file is not FITS. Each header
searched for the parameters NAXISi, TELESCOP, OBJECT, DATE-OBS and
EXPTIME.
SYSTEM VARIABLES:
The non-standard system variables !TEXTOUT and !TEXTUNIT must be
defined before calling FITS_INFO.
DEFSYSV,'!TEXTOUT',1
DEFSYSV,'!TEXTUNIT',0
One way to define these is to call the procedure ASTROLIB.
See TEXTOPEN.PRO for more info
PROCEDURES USED:
FDECOMP, REMCHAR, SPEC_DIR(), TEXTOPEN, TEXTCLOSE, ZPARCHECK
MODIFICATION HISTORY:
Written, W. Landsman, HSTX February, 1993
Converted to IDL V5.0 W. Landsman September 1997
Search alternate keyword names W.Landsman October 1998
Avoid integer truncation for NAXISi >32767 W. Landsman July 2000
Don't leave open unit W. Landsman July 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fitsdir.pro)
FITSLIST
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FITSLIST
PURPOSE:
Display and write FITS headers from a FITS tape
EXPLANATION:
Procedure will read FITS files from a tape on the specified
tape unit. The headers are placed in file NAME, with the
default extension of .LIS. Headers are also displayed at the
terminal. Unix and VMS IDL only.
CALLING SEQUENCE:
FITSLIST
FITSLIST,UPDATE_SWITCH
OPTIONAL INPUT:
UPDATE_SWITCH - If passed and nonzero, then an existing file is opened,
and output is appended to the end of this file. Also,
the FITS tape is not rewound prior to starting the read.
This is useful if the tape contains spurious EOF marks.
OUTPUT:
None.
SIDE EFFECTS:
File NAME or NAME.LIS is created, or if UPDATE_SWITCH is nonzero then
additional information is appended to the file.
Headers are displayed at terminal as well as written to file.
RESTRICTIONS:
Tape must be mounted before calling FITSLIST.
FITSLIST uses the VMS IDL tape positioning command, but will also
run on Unix machines by using procedures which call IOCTL and
which emulate the VMS IDL tape I/O functions (e.g TAPRD)
PROMPTS:
Program will prompt for
(1) NAME of output listing file
(2) tape unit number
PROCEDURES CALLED:
FITSTAPE
HISTORY:
William Thompson, 15-May-1986, based on FITSREAD.
William Thompson, 09-Feb-1990, added file numbers.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fitslist.pro)
FITSRGB_TO_TIFF
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FITSRGB_to_TIFF
PURPOSE:
Combine separate red, green, and blue FITS images into TIFF format
EXPLANATION:
The output TIFF (class R) file can have colors interleaved either
either by pixel or image. The colour mix is also adjustable.
CALLING SEQUENCE:
FITSRGB_to_TIFF, path, rgb_files, tiff_name [,/BY_PIXEL, /PREVIEW,
RED= , GREEN =, BLUE =]
INPUTS:
path = file system directory path to the RGB files required.
rgb_files = string array with three components - the red FITS file
filename, the blue FITS file filename and the green FITS
file filename
OUTPUTS:
tiff_name = string containing name of tiff file to be produced
OPTIONAL OUTPUT:
Header = String array containing the header from the FITS file.
OPTIONAL INPUT KEYWORDS:
BY_PIXEL = This causes TIFF file RGB to be interleaved by pixel
rather than the default of by image.
PREVIEW = Allows a 24 bit image to be displayed on the screen
to check the colour mix.
RED = Real number containing the fractional mix of red
GREEN = Real number containing the fractional mix of green
BLUE = Real number containing the fractional mix of blue
EXAMPLE:
Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from
the directory '/data/images/space' and output a TIFF file named
'colour.tiff'
IDL> FITSRGB_to_TIFF, '/data/images/space', ['red.fits', $
'blue.fits', 'green.fits'], 'colour.tiff'
Read three FITS files, 'red.fits', 'blue.fits' and 'green.fits' from
the current directory and output a TIFF file named '/images/out.tiff'
In this case, the red image is twice as strong as the green and the
blue is a third more intense. A preview on screen is also wanted.
IDL> FITSRGB_to_TIFF, '.', ['red.fits', $
'blue.fits', 'green.fits'], '/images/out.tiff', $
/PREVIEW, RED=0.5, GREEN=1.0, BLUE=0.666
RESTRICTIONS:
(1) Limited to the ability of the routine READFITS
NOTES:
None
PROCEDURES USED:
Functions: READFITS, CONCAT_DIR
Procedures: WRITE_TIFF
MODIFICATION HISTORY:
16th January 1995 - Written by Carl Shaw, Queen's University Belfast
27 Jan 1995 - W. Landsman, Add CONCAT_DIR for VMS, Windows compatibility
Converted to IDL V5.0 W. Landsman September 1997
Use WRITE_TIFF instead of obsolete TIFF_WRITE W. Landsman December 1998
Cosmetic changes W. Landsman February 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fitsrgb_to_tiff.pro)
FITSTAPE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FITSTAPE
PURPOSE:
Subroutine to perform FITS tape I/O.
EXPLANATION:
For VMS or Unix IDL only
CALLING SEQUENCE:
status = fitstape( command, unit, bitpix, data )
INPUTS:
command - string command from the following choices
'init' - initialization (must be first call to fitstape)
'read' - get next 2880 byte data buffer
'eof' - check for end of tape file
'write'- write 2880 byte data buffer
'woef' - empty buffer and write end-of-file
unit - tape unit number
bitpix - bits/per data element (used to control byte swapping)
(required for 'read' and 'write')
(for 'init' command this parameter gives
the blocking factor, number of 2880 byte
records per tape record. if not supplied 1 is
assumed)
data - 2880 byte data array if 'write' command
OUTPUTS:
data - 2880 byte data array if 'read' command
status is returned as the function value
with the following meanings.
'init' = 1
'read' = !err returned by taprd
'write' = 1
'eof' = 1 if at end of file
0 if not at end of file
'weof' = 1
COMMON BLOCKS
QFITSTAPE
HISTORY
Version 1 D. Lindler Nov 1986
Converted to IDL Version 2. M. Greason, STX, June 1990.
Recognize BITPIX = -32 and BITPIX = -64 W. Landsman April 1992
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fitstape.pro)
FITS_CD_FIX
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FITS_CD_FIX
PURPOSE:
Convert between different representations of the CD matrix in a FITS header
EXPLANATION:
According the paper, "Representations of Celestial Coordinates in FITS"
by Griesen and Calabretta, available at
http://www.cv.nrao.edu/fits/documents/wcs/wcs.html
the rotation of an image from standard coordinates is represented by a
coordinate description (CD) matrix. However, there have been several
different representations proposed for the CD matrix. Currently,
(April 2000), the preferred form is CDn_m (as used in IRAF), which
contains both rotation & plate scale info. However,
an earlier draft of Griesen & Calabretta proposed the CD00n00m form.
containing only rotation (and skew) info, with the plate scale stored in
the CDELT* keywords.
FITS_CD_FIX converts from the representation of the CD matrix with an
underscore (e.g. CDn_m) to that with all integers (e.g. CD00n00m). Users
will more commonly go in the reverse direction (since the CDn_m format
is now prefered) using the /REVERSE keyword.
CALLING SEQUENCE:
FITS_CD_FIX, Hdr, [/REVERSE]
INPUT-OUTPUT:
HDR - FITS header, 80 x N string array. If the header does not
contain the CDn_m keywords then it is left unmodified. Other-
wise the CDn_m keywords are removed and the CD00n00m keywords
inserted (with the same values).
OPTIONAL KEYWORD INPUT
/REVERSE - If this keyword is set and non-zero, then the process is
reversed, i.e. CD00n00m keywords are removed from the header
and CDn_m keywords are inserted.
PROCEDURES USED:
SXADDPAR, SXDELPAR, SXPAR
REVISION HISTORY:
Written W. Landsman Feb 1990
Major rewrite Feb 1994
Converted to IDL V5.0 W. Landsman September 1997
Use double precision formatting of CD matrix W. Landsman April 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fits_cd_fix.pro)
FITS_CLOSE
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
FITS_CLOSE
*PURPOSE:
Close a FITS data file
*CATEGORY:
INPUT/OUTPUT
*CALLING SEQUENCE:
FITS_CLOSE,fcb
*INPUTS:
FCB: fits control block returned by FITS_OPEN.
*KEYWORD PARAMETERS:
/NO_ABORT: Set to return to calling program instead of a RETALL
when an I/O error is encountered. If set, the routine will
return with !err=-1 and a message in the keyword MESSAGE.
If not set, FITS_CLOSE will print the message and issue a RETALL
MESSAGE = value: Output error message
*EXAMPLES:
Open a FITS file, read some data, and close it with FITS_CLOSE
FITS_OPEN,'infile',fcb
FITS_READ,fcb,data
FITS_READ,fcb,moredata
FITS_CLOSE,fcb
*HISTORY:
Written by: D. Lindler August, 1995
Converted to IDL V5.0 W. Landsman September 1997
Do nothing if fcb an invalid structure D. Schlegel/W. Landsman Oct. 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fits_close.pro)
FITS_HELP
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
FITS_HELP
*PURPOSE:
To print a summary of the primary data units and extensions in a
FITS file.
*CATEGORY:
INPUT/OUTPUT
*CALLING SEQUENCE:
FITS_HELP,filename_or_fcb
*INPUTS:
FILENAME_OR_FCB - name of the fits file or the FITS Control Block (FCB)
returned by FITS_OPEN.
*OUTPUTS:
a summary of the fits file is printed.
*EXAMPLES:
FITS_HELP,'myfile.fits'
FITS_OPEN,'anotherfile.fits',fcb
FITS_HELP,fcb
*PROCEDURES USED:
FITS_OPEN, FITS_CLOSE
*HISTORY:
Written by: D. Lindler August, 1995
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fits_help.pro)
FITS_INFO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FITS_INFO
PURPOSE:
Provide information about the contents of a FITS file
EXPLANATION:
Information includes number of header records and size of data array.
Applies to primary header and all extensions. Information can be
printed at the terminal and/or stored in a common block
CALLING SEQUENCE:
FITS_INFO, Filename, [ /SILENT , TEXTOUT = , N_ext = ]
INPUT:
Filename - Scalar string giving the name of the FITS file(s)
Can include wildcards such as '*.fits'
OPTIONAL INPUT KEYWORDS:
/SILENT - If set, then the display of the file description on the
terminal will be suppressed
TEXTOUT - specifies output device.
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, see TEXTOPEN
textout=7 append to existing file
textout = filename (default extension of .prt)
If TEXTOUT is not supplied, then !TEXTOUT is used
OPTIONAL OUTPUT KEYWORD:
N_ext - Returns an integer scalar giving the number of extensions in
the FITS file
COMMON BLOCKS
DESCRIPTOR = File descriptor string of the form N_hdrrec Naxis IDL_type
Naxis1 Naxis2 ... Naxisn [N_hdrrec table_type Naxis
IDL_type Naxis1 ... Naxisn] (repeated for each extension)
See the procedure RDFITS_STRUCT for an example of the
use of this common block
EXAMPLE:
Display info about all FITS files of the form '*.fit' in the current
directory
IDL> fits_info, '*.fit'
Any time a *.fit file is found which is *not* in FITS format, an error
message is displayed at the terminal and the program continues
PROCEDURES USED:
GETTOK(), STRN(), SXPAR(), TEXTOPEN, TEXTCLOSE
SYSTEM VARIABLES:
The non-standard system variables !TEXTOUT and !TEXTUNIT must be
defined before calling FITS_INFO.
DEFSYSV,'!TEXTOUT',1
DEFSYSV,'!TEXTUNIT',0
One way to define these is to call the procedure ASTROLIB.
See TEXTOPEN.PRO for more info
MODIFICATION HISTORY:
Written, K. Venkatakrishna, Hughes STX, May 1992
Added N_ext keyword, and table_name info, G. Reichert
Work on *very* large FITS files October 92
More checks to recognize corrupted FITS files February, 1993
Proper check for END keyword December 1994
Correctly size variable length binary tables WBL December 1994
EXTNAME keyword can be anywhere in extension header WBL January 1998
Correctly skip past extensions with no data WBL April 1998
Converted to IDL V5.0, W. Landsman, April 1998
(See /host/bluemoon/usr2/idllib/astron/pro/fits_info.pro)
FITS_OPEN
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
FITS_OPEN
*PURPOSE:
Opens a FITS (Flexible Image Transport System) data file.
*CATEGORY:
INPUT/OUTPUT
*CALLING SEQUENCE:
FITS_OPEN, filename, fcb
*INPUTS:
filename : name of the FITS file to open
*OUTPUTS:
fcb : (FITS Control Block) a IDL structure containing information
concerning the file. It is an input to FITS_READ, FITS_WRITE
and FITS_CLOSE
*KEYWORD PARAMETERS:
/WRITE: Set this keyword to open a new file for writing.
/APPEND: Set to append to an existing file.
/NO_ABORT: Set to return to calling program instead of a RETALL
when an I/O error is encountered. If set, the routine will
return with !err=-1 and a message in the keyword MESSAGE.
If not set, FITS_OPEN will print the message and issue a RETALL
MESSAGE = value: Output error message
/HPRINT - print headers with routine HPRINT as they are read.
(useful for debugging a strange file)
*NOTES:
The output FCB should be passed to the other FITS routines (FITS_OPEN,
FITS_READ, FITS_HELP, and FITS_WRITE). It has the following structure
when FITS_OPEN is called without /WRITE or /APPEND keywords set.
FCB.FILENAME - name of the input file
.UNIT - unit number the file is opened to
.NEXTEND - number of extensions in the file.
.XTENSION - string array giving the extension type for each
extension.
.EXTNAME - string array giving the extension name for each
extension. (null string if not defined the extension)
.EXTVER - vector of extension version numbers (0 if not
defined)
.EXTLEVEL - vector of extension levels (0 if not defined)
.GCOUNT - vector with the number of groups in each extension.
.PCOUNT - vector with parameter count for each group
.BITPIX - BITPIX for each extension with values
8 byte data
16 short word integers
32 long word integers
-32 IEEE floating point
-64 IEEE double precision floating point
.NAXIS - number of axes for each extension. (0 for null data
units)
.AXIS - 2-D array where axis(*,N) gives the size of each axes
for extension N
.START_HEADER - vector giving the starting byte in the file
where each extension header begins
.START_DATA - vector giving the starting byte in the file
where the data for each extension begins
.HMAIN - keyword parameters (less standard required FITS
keywords) for the primary data unit.
.OPEN_FOR_WRITE - flag (0= open for read, 1=open for write,
2=open for update)
.LAST_EXTENSION - last extension number read.
.RANDOM_GROUPS - 1 if the PDU is random groups format,
0 otherwise
When FITS open is called with the /WRITE or /APPEND option, FCB
contains:
FCB.FILENAME - name of the input file
.UNIT - unit number the file is opened to
.NEXTEND - number of extensions in the file.
.OPEN_FOR_WRITE - flag (1=open for write, 2=open for update)
*EXAMPLES:
Open a FITS file for reading:
FITS_OPEN,'myfile.fits',fcb
Open a new FITS file for output:
FITS_OPEN,'newfile.fits',fcb,/write
PROCEDURES USED:
HPRINT, SXDELPAR, SXPAR()
*HISTORY:
Written by: D. Lindler August, 1995
July, 1996 NICMOS Modified to allow open for overwrite
to allow primary header to be modified
DJL Oct. 15, 1996 corrected to properly extend AXIS when more
than 100 extensions present
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fits_open.pro)
FITS_READ
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
FITS_READ
*PURPOSE:
To read a FITS file.
*CATEGORY:
INPUT/OUTPUT
*CALLING SEQUENCE:
FITS_READ, filename_or_fcb, data [,header, group_par]
*INPUTS:
FILENAME_OR_FCB - this parameter can be the FITS Control Block (FCB)
returned by FITS_OPEN or the file name of the FITS file. If
a file name is supplied, FITS_READ will open the file with
FITS_OPEN and close the file with FITS_CLOSE before exiting.
When multiple extensions are to be read from the file, it is
more efficient for the user to call FITS_OPEN and leave the
file open until all extensions are read.
*OUTPUTS:
DATA - data array. If /NOSCALE is specified, BSCALE and BZERO
(if present in the header) will not be used to scale the data.
If Keywords FIRST and LAST are used to read a portion of the
data or the heap portion of an extension, no scaling is done
and data is returned as a 1-D vector. The user can use the IDL
function REFORM to convert the data to the correct dimensions
if desired. If /DATA_ONLY is specified, no scaling is done.
HEADER - FITS Header. If an extension is read, and the /NO_PDU keyword
parameter is not supplied, the primary data unit header
and the extension header will be combined. The header will have
the form:
BEGIN MAIN HEADER --------------------------------
BEGIN EXTENSION HEADER ---------------------------
1. (Default=0, the first group)
NaNvalue - On non-IEEE floating point machines, it gives the value
to place into words with IEEE NaN.
ENUM - Output extension number that was read.
*NOTES:
Determination or which extension to read.
case 1: EXTEN_NO specified. EXTEN_NO will give the number of the
extension to read. The primary data unit is refered
to as extension 0. If EXTEN_NO is specified, XTENSION,
EXTNAME, EXTVER, and EXTLEVEL parameters are ignored.
case 2: if EXTEN_NO is not specified, the first extension
with the specified XTENSION, EXTNAME, EXTVER, and
EXTLEVEL will be read. If any of the 4 parameters
are not specified, they will not be used in the search.
Setting EXTLEVEL=0, EXTVER=0, EXTNAME='', or
XTENSION='' is the same as not supplying them.
case 3: if none of the keyword parameters, EXTEN_NO, XTENSION,
EXTNAME, EXTVER, or EXTLEVEL are supplied. FITS_READ
will read the next extension in the file. If the
primary data unit (PDU), extension 0, is null, the
first call to FITS_READ will read the first extension
of the file.
The only way to read a null PDU is to use EXTEN_NO = 0.
If FIRST and LAST are specified, the data is returned without applying
any scale factors (BSCALE and BZERO) and the data is returned in a
1-D vector. This will allow you to read any portion of a multiple
dimension data set. Once returned, the IDL function REFORM can be
used to place the correct dimensions on the data.
IMPLICIT IMAGES: FITS_READ will construct an implicit image
for cases where NAXIS=0 and the NPIX1, NPIX2, and PIXVALUE
keywords are present. The output image will be:
image = replicate(PIXVALUE,NPIX1,NPIX2)
*EXAMPLES:
Read the primary data unit of a FITS file, if it is null read the
first extension:
FITS_READ, 'myfile.fits', data, header
Read the first two extensions of a FITS file and the extension with
EXTNAME = 'FLUX' and EXTVER = 4
FITS_OPEN, 'myfile.fits', fcb
FITS_READ, fcb,data1, header2, exten_no = 1
FITS_READ, fcb,data1, header2, exten_no = 2
FITS_READ, fcb,data3, header3, extname='flux', extver=4
FITS_CLOSE, fcb
Read the sixth image in a data cube for the fourth extension.
FITS_OPEN, 'myfile.fits', fcb
image_number = 6
ns = fcb.axis(0,4)
nl = fcb.axis(1,4)
i1 = (ns*nl)*(image_number-1)
i2 = i2 + ns*nl-1
FITS_READ,fcb,image,header,first=i1,last=i2
image = reform(image,ns,nl,/overwrite)
FITS_CLOSE
*PROCEDURES USED:
FITS_CLOSE, FITS_OPEN, IEEE_TO_HOST, IS_IEEE_BIG()
SXADDPAR, SXDELPAR, SXPAR()
*HISTORY:
Written by: D. Lindler, August 1995
Converted to IDL V5.0 W. Landsman September 1997
Avoid use of !ERR W. Landsman August 1999
Read unsigned datatypes, added /no_unsigned W. Landsman December 1999
Don't call FITS_CLOSE unless fcb is defined W. Landsman January 2000
Set BZERO = 0 for unsigned integer data W. Landsman January 2000
Only call IEEE_TO_HOST if needed W. Landsman February 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fits_read.pro)
FITS_WRITE
[Previous Routine]
[Next Routine]
[List of Routines]
*NAME:
FITS_WRITE
*PURPOSE:
To write a FITS primary data unit or extension.
*CATEGORY:
INPUT/OUTPUT
*CALLING SEQUENCE:
FITS_WRITE, filename_or_fcb, data, [header_in]
*INPUTS:
FILENAME_OR_FCB: name of the output data file or the FITS control
block returned by FITS_OPEN (called with the /WRITE or
/APPEND) parameters.
*OPTIONAL INPUTS:
DATA: data array to write. If not supplied or set to a scalar, a
null image is written.
HEADER_IN: FITS header keyword. If not supplied, a minimal basic
header will be created. Required FITS keywords, SIMPLE,
BITPIX, XTENSION, NAXIS, ... are added by FITS_WRITE and
do not need to be supplied with the header. If supplied,
thier values will be updated as necessary to reflect DATA.
*KEYWORD PARAMETERS:
XTENSION: type of extension to write (Default="IMAGE"). If not
supplied, it will be taken from HEADER_IN. If not in either
place, the default is "IMAGE". This parameter is ignored
when writing the primary data unit.
EXTNAME: EXTNAME for the extension. If not supplied, it will be taken
from HEADER_IN. If not supplied and not in HEADER_IN, no
EXTNAME will be written into the output extension.
EXTVER: EXTVER for the extension. If not supplied, it will be taken
from HEADER_IN. If not supplied and not in HEADER_IN, no
EXTVER will be written into the output extension.
EXTLEVEL: EXTLEVEL for the extension. If not supplied, it will be taken
from HEADER_IN. If not supplied and not in HEADER_IN, no
EXTLEVEL will be written into the output extension.
NaNvalue: data value in DATA to be replaced with IEEE NaN in the output
file.
/NO_ABORT: Set to return to calling program instead of a RETALL
when an I/O error is encountered. If set, the routine will
return with !err=-1 and a message in the keyword MESSAGE.
If not set, FITS_READ will print the message and issue a RETALL
MESSAGE: value of the error message for use with /NO_ABORT
HEADER: actual output header written to the FITS file.
/NO_DATA: Set if you only want FITS_WRITE to write a header. The
header supplied will be written without modification and
the user is expected to write the data using WRITEU to unit
FCB.UNIT. When FITS_WRITE is called with /NO_DATA, the user is
responsible for the validity of the header, and must write
the correct amount and format of the data. When FITS_WRITE
is used in this fashion, it will pad the data from a previously
written extension to 2880 blocks before writting the header.
*NOTES:
If the first call to FITS_WRITE is an extension, FITS_WRITE will
automatically write a null image as the primary data unit.
Keywords and history in the input header will be properly separated
into the primary data unit and extension portions when constructing
the output header (See FITS_READ for information on the internal
Header format which separates the extension and PDU header portions).
*EXAMPLES:
Write an IDL variable to a FITS file with the minimal required header.
FITS_WRITE,'newfile.fits',ARRAY
Write the same array as an image extension, with a null Primary data
unit.
FITS_WRITE,'newfile.fits',ARRAY,xtension='IMAGE'
Write 4 image extensions to the same file.
FITS_OPEN,'newfile.fits',fcb
FITS_WRITE,fcb,data1,extname='FLUX',extver=1
FITS_WRITE,fcb,err1,extname'ERR',extver=1
FITS_WRITE,fcb,data2,extname='FLUX',extver=2
FITS_WRITE,fcb,err2,extname='ERR',extver=2
FITS_CLOSE,FCB
*PROCEDURES USED:
FITS_OPEN, SXADDPAR, SXDELPAR, SXPAR()
*HISTORY:
Written by: D. Lindler August, 1995
Work for variable length extensions W. Landsman August 1997
Converted to IDL V5.0 W. Landsman September 1997
PCOUNT and GCOUNT added for IMAGE extensions J. Graham October 1999
Write unsigned data types W. Landsman December 1999
Pad data area with zeros not blanks W. McCann/W. Landsman October 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fits_write.pro)
FLEGENDRE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FLEGENDRE
PURPOSE:
Compute the first M terms in a Legendre polynomial expansion.
EXPLANATION:
Meant to be used as a supplied function to SVDFIT.
This procedure became partially obsolete in IDL V5.0 with the
introduction of the /LEGENDRE keyword to SVDFIT and the associated
SVDLEG function. However, note that, unlike SVDLEG, FLEGENDRE works
on vector values of X.
CALLING SEQUENCE:
result = FLEGENDRE( X, M)
INPUTS:
X - the value of the independent variable, scalar or vector
M - number of term of the Legendre expansion to compute, integer scalar
OUTPUTS:
result - (N,M) array, where N is the number of elements in X and M
is the order. Contains the value of each Legendre term for
each value of X
EXAMPLE:
(1) If x = 2.88 and M = 3 then
IDL> print, flegendre(x,3) ==> [1.00, 2.88, 11.9416]
This result can be checked by explicity computing the first 3 Legendre
terms, 1.0, x, 0.5*( 3*x^2 -1)
(2) Find the coefficients to an M term Legendre polynomial that gives
the best least-squares fit to a dataset (x,y)
IDL> coeff = SVDFIT( x,y,M,func='flegendre')
The coefficients can then be supplied to the function POLYLEG to
compute the best YFIT values for any X.
METHOD:
The recurrence relation for the Legendre polynomials is used to compute
each term. Compare with the function FLEG in "Numerical Recipes"
by Press et al. (1992), p. 674
REVISION HISTORY:
Written Wayne Landsman Hughes STX April 1995
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/flegendre.pro)
FLUX2MAG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FLUX2MAG
PURPOSE:
Convert from flux (ergs/s/cm^2/A) to magnitudes.
EXPLANATION:
Use MAG2FLUX() for the opposite direction.
CALLING SEQUENCE:
mag = flux2mag( flux, [ zero_pt, ABwave= ] )
INPUTS:
flux - scalar or vector flux vector, in erg cm-2 s-1 A-1
OPTIONAL INPUT:
zero_pt - scalar giving the zero point level of the magnitude.
If not supplied then zero_pt = 21.1 (Code et al 1976)
Ignored if the ABwave keyword is supplied
OPTIONAL KEYWORD INPUT:
ABwave - wavelength scalar or vector in Angstroms. If supplied, then
FLUX2MAG() returns Oke AB magnitudes (Oke & Gunn 1983, ApJ, 266,
713).
OUTPUT:
mag - magnitude vector. If the ABwave keyword is set then mag
is given by the expression
ABMAG = -2.5*alog10(f) - 5*alog10(ABwave) - 2.406
Otherwise, mag is given by the expression
mag = -2.5*alog10(flux) - zero_pt
EXAMPLE:
Suppose one is given wavelength and flux vectors, w (in Angstroms) and
f (in erg cm-2 s-1 A-1). Plot the spectrum in AB magnitudes
IDL> plot, w, flux2mag(f,ABwave = w), /nozero
REVISION HISTORY:
Written J. Hill STX Co. 1988
Converted to IDL V5.0 W. Landsman September 1997
Added ABwave keyword W. Landsman September 1998
(See /host/bluemoon/usr2/idllib/astron/pro/flux2mag.pro)
FM_UNRED
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FM_UNRED
PURPOSE:
Deredden a flux vector using the Fitzpatrick (1999) parameterization
EXPLANATION:
The R-dependent Galactic extinction curve is that of Fitzpatrick & Massa
(Fitzpatrick, 1999, PASP, 111, 63; astro-ph/9809387 ).
Parameterization is valid from the IR to the far-UV (3.5 microns to 0.1
microns). UV extinction curve is extrapolated down to 912 Angstroms.
CALLING SEQUENCE:
FM_UNRED, wave, flux, ebv, [ funred, R_V = , /LMC2, /AVGLMC, ExtCurve=
gamma =, x0=, c1=, c2=, c3=, c4= ]
INPUT:
WAVE - wavelength vector (Angstroms)
FLUX - calibrated flux vector, same number of elements as WAVE
If only 3 parameters are supplied, then this vector will
updated on output to contain the dereddened flux.
EBV - color excess E(B-V), scalar. If a negative EBV is supplied,
then fluxes will be reddened rather than deredenned.
OUTPUT:
FUNRED - unreddened flux vector, same units and number of elements
as FLUX
OPTIONAL INPUT KEYWORDS
R_V - scalar specifying the ratio of total to selective extinction
R(V) = A(V) / E(B - V). If not specified, then R = 3.1
Extreme values of R(V) range from 2.3 to 5.3
/AVGLMC - if set, then the default fit parameters c1,c2,c3,c4,gamma,x0
are set to the average values determined for reddening in the
general Large Magellanic Cloud (LMC) field by Misselt et al.
(1999, ApJ, 515, 128)
/LMC2 - if set, then the fit parameters are set to the values determined
for the LMC2 field (including 30 Dor) by Misselt et al.
Note that neither /AVGLMC or /LMC2 will alter the default value
of R_V which is poorly known for the LMC.
The following five input keyword parameters allow the user to customize
the adopted extinction curve
x0 - Centroid of 2200 A bump in microns (default = 4.596)
gamma - Width of 2200 A bump in microns (default =0.99)
c3 - Strength of the 2200 A bump (default = 3.23)
c4 - FUV curvature (default = 0.41)
c2 - Slope of the linear UV extinction component
(default = -0.824 + 4.717/R)
c1 - Intercept of the linear UV extinction component
(default = 2.030 - 3.007*c2
OPTIONAL OUTPUT KEYWORD:
ExtCurve - Returns the E(wave-V)/E(B-V) extinction curve, interpolated
onto the input wavelength vector
EXAMPLE:
Determine how a flat spectrum (in wavelength) between 1200 A and 3200 A
is altered by a reddening of E(B-V) = 0.1. Assume an "average"
reddening for the diffuse interstellar medium (R(V) = 3.1)
IDL> w = 1200 + findgen(40)*50 ;Create a wavelength vector
IDL> f = w*0 + 1 ;Create a "flat" flux vector
IDL> fm_unred, w, f, -0.1, fnew ;Redden (negative E(B-V)) flux vector
IDL> plot,w,fnew
NOTES:
(1) The following comparisons between the FM curve and that of Cardelli,
Clayton, & Mathis (1989), (see ccm_unred.pro):
(a) - In the UV, the FM and CCM curves are similar for R < 4.0, but
diverge for larger R
(b) - In the optical region, the FM more closely matches the
monochromatic extinction, especially near the R band.
(2) Many sightlines with peculiar ultraviolet interstellar extinction
can be represented with the FM curve, if the proper value of
R(V) is supplied.
(3) Use the 4 parameter calling sequence if you wish to save the
original flux vector.
PROCEDURE CALLS:
CSPLINE(), POLY()
REVISION HISTORY:
Written W. Landsman Raytheon STX October, 1998
Based on FMRCurve by E. Fitzpatrick (Villanova)
Added /LMC2 and /AVGLMC keywords, W. Landsman August 2000
Added ExtCurve keyword, J. Wm. Parker August 2000
-
(See /host/bluemoon/usr2/idllib/astron/pro/fm_unred.pro)
FORPRINT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FORPRINT
PURPOSE
Print a set of vectors by looping over each index value.
EXPLANATION:
If W and F are equal length vectors, then the statement
IDL> forprint, w, f
is equivalent to
IDL> for i = 0L, N_elements(w)-1 do print,w[i],f[i]
CALLING SEQUENCE:
forprint, v1,[ v2, v3, v4,....v18, FORMAT = , TEXTOUT = ,STARTLINE =,
NUMLINE =, /SILENT ]
INPUTS:
V1,V2,...V18 - Arbitary IDL vectors. If the vectors are not of
equal length then the number of rows printed will be equal
to the length of the smallest vector. Up to 18 vectors
can be supplied.
OPTIONAL KEYWORD INPUTS:
TEXTOUT - Controls print output device, defaults to !TEXTOUT
textout=1 TERMINAL using /more option
textout=2 TERMINAL without /more option
textout=3 .prt
textout=4 laser.tmp
textout=5 user must open file
textout = filename (default extension of .prt)
textout=7 Append to .prt file if it exists
FORMAT - Scalar format string as in the PRINT procedure. The use
of outer parenthesis is optional. Ex. - format="(F10.3,I7)"
This program will automatically remove a leading "$" from
incoming format statments. Ex. - "$(I4)" would become "(I4)".
STARTLINE - Integer scalar specifying the first line in the arrays
to print. Default is STARTLINE = 1, i.e. start at the
beginning of the arrays.
SILENT - Normally, with a hardcopy output (TEXTOUT > 2), FORPRINT will
add a time stamp to the output file. If the SILENT keyword
is set and non-zero, then this time stamp is suppressed.
OUTPUTS:
None
SYSTEM VARIABLES:
If keyword TEXTOUT is not used, the default is the nonstandard
keyword !TEXTOUT. If you want to use FORPRINT to write more than
once to the same file, or use a different file name then set
TEXTOUT=5, and open and close then file yourself (see documentation
of TEXTOPEN for more info).
One way to add the non-standard system variables !TEXTOUT and !TEXTUNIT
is to use the procedure ASTROLIB
EXAMPLE:
Suppose W,F, and E are the wavelength, flux, and epsilon vectors for
an IUE spectrum. Print these values to a file 'output.dat' in a nice
format.
IDL> fmt = '(F10.3,1PE12.2,I7)'
IDL> forprint, F = fmt, w, f, e, TEXT = 'output.dat'
PROCEDURES CALLED:
DATATYPE(), TEXTOPEN, TEXTCLOSE
REVISION HISTORY:
Written W. Landsman April, 1989
Keywords textout and format added, J. Isensee, July, 1990
Made use of parenthesis in FORMAT optional W. Landsman May 1992
Added STARTLINE keyword W. Landsman November 1992
Set up so can handle 18 input vectors. J. Isensee, HSTX Corp. July 1993
Handle string value of TEXTOUT W. Landsman, HSTX September 1993
Added NUMLINE keyword W. Landsman, HSTX February 1996
Added SILENT keyword W. Landsman, RSTX, April 1998
Converted to IDL V5.0 W. Landsman, RSTX, April, 1998
(See /host/bluemoon/usr2/idllib/astron/pro/forprint.pro)
FREBIN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FREBIN
PURPOSE:
Shrink or expand the size of an array an arbitary amount using interpolation
EXPLANATION:
FREBIN is an alternative to CONGRID or REBIN. Like CONGRID it
allows expansion or contraction by an arbitary amount. ( REBIN requires
integral factors of the original image size.) Like REBIN it conserves
flux by ensuring that each input pixel is equally represented in the output
array.
CALLING SEQUENCE:
result = FREBIN( image, nsout, nlout, [ /TOTAL] )
INPUTS:
image - input image, 1-d or 2-d numeric array
nsout - number of samples in the output image, numeric scalar
OPTIONAL INPUT:
nlout - number of lines in the output image, numeric scalar
If not supplied, then set equal to 1
OPTIONAL KEYWORD INPUTS:
/total - if set, the output pixels will be the sum of pixels within
the appropriate box of the input image. Otherwise they will
be the average. Use of the /TOTAL keyword conserves surface flux.
OUTPUTS:
The resized image is returned as the function result. If the input
image is of type DOUBLE or FLOAT then the resized image is of the same
type. If the input image is BYTE, INTEGER or LONG then the output
image is usually of type FLOAT. The one exception is expansion by
integral amount (pixel duplication), when the output image is the same
type as the input image.
EXAMPLE:
Suppose one has an 800 x 800 image array, im, that must be expanded to
a size 850 x 900 while conserving surface flux:
IDL> im1 = frebin(im,850,900,/total)
im1 will be a 850 x 900 array, and total(im1) = total(im)
NOTES:
If the input image sizes are a multiple of the output image sizes
then FREBIN is equivalent to the IDL REBIN function for compression,
and simple pixel duplication on expansion.
If the number of output pixels are not integers, the output image
size will be truncated to an integer. The platescale, however, will
reflect the non-integer number of pixels. For example, if you want to
bin a 100 x 100 integer image such that each output pixel is 3.1
input pixels in each direction use:
n = 100/3.1 ; 32.2581
image_out = frebin(image,n,n)
The output image will be 32 x 32 and a small portion at the trailing
edges of the input image will be ignored.
PROCEDURE CALLS:
DATATYPE()
HISTORY:
Adapted from May 1998 STIS version, written D. Lindler, ACC
Added /NOZERO, use INTERPOLATE instead of CONGRID, June 98 W. Landsman
Fixed for nsout non-integral but a multiple of image size Aug 98 D.Lindler
DJL, Oct 20, 1998, Modified to work for floating point image sizes when
expanding the image.
(See /host/bluemoon/usr2/idllib/astron/pro/frebin.pro)
FSTRING
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FSTRING
PURPOSE:
Shell around STRING function to fix 1024 size limit on formatting strings
CALLING SEQUENCE:
new = fstring(old, [ format, FORMAT = )
INPUTS:
OLD = string or number to format, scalar, vector or array
OPTIONAL STRING:
FORMAT = scalar string giving format to pass to the STRING() function
See restrictions on possible formats below.
OPTIONAL KEYWORD INPUT:
FORMAT = Format string can alternatively be called as keyword
OUTPUT:
FSTRING will return a string with the same dimensions
RESTRICTIONS:
Because FSTRING breaks up the formatting into 1024 element chunks, problems
can arise if the number of formatting elements does not evenly divide
into 1024. For example, if format = '(i6,f6.2,e12.6)', (i.e. three
formatting elements) then both the 1023rd and 1024th element will be
formatted as I6.
EXAMPLE:
Create a string array of 10000 uniform random numbers formatted as F6.2
IDL> a = fstring( randomu(seed,10000), '(f6.2)')
REVISION HISTORY:
Written W. Landsman (based on program by D. Zarro) February 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fstring.pro)
FTAB_DELROW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTAB_DELROW
PURPOSE:
Delete rows of data from a FITS ASCII or binary table extension
CALLING SEQUENCE:
ftab_delrow, filename, rows, EXTEN_NO =, NEWFILE = ]
INPUTS-OUPUTS
filename - scalar string giving name of the FITS file containing an
ASCII or binary table extension.
rows - scalar or vector, specifying the row numbers to delete
First row has index 0. If a vector, it will be sorted and
duplicates will be removed
OPTIONAL KEYWORD INPUTS:
EXTEN_NO - scalar integer specifying which extension number to process
Default is to process the first extension
NEWFILE - scalar string specifying the name of the new output FITS file
FTAB_DELROW will prompt for this parameter if not supplied
EXAMPLE:
Compress the first extension of a FITS file 'test.fits' to include
only non-negative values in the 'FLUX' column
ftab_ext,'test.fits','flux',flux ;Obtain original flux vector
bad = where(flux lt 0) ;Find negative fluxes
ftab_delrow,'test.fits',bad,new='test1.fits' ;Delete specified rows
RESTRICTIONS:
Does not work for variable length binary tables
PROCEDURES USED:
FITS_CLOSE, FITS_OPEN, FITS_READ, FITS_WRITE, FTDELROW, TBDELROW
REVISION HISTORY:
Written W. Landsman STX Co. August, 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/ftab_delrow.pro)
FTAB_EXT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTAB_EXT
PURPOSE:
Routine to extract columns from a FITS (binary or ASCII) table
CALLING SEQUENCE:
FTAB_EXT, name_or_fcb, columns, v1, [v2,..,v9, ROWS=, EXTEN_NO= ]
INPUTS:
name_or_fcb - either a scalar string giving the name of a FITS file
containing a (binary or ASCII) table, or an IDL structure
containing as file control block (FCB) returned by FITS_OPEN
If FTAB_EXT is to be called repeatedly on the same file, then
it is quicker to first open the file with FITS_OPEN, and then
pass the FCB structure to FTAB_EXT
columns - table columns to extract. Can be either
(1) String with names separated by commas
(2) Scalar or vector of column numbers
OUTPUTS:
v1,...,v9 - values for the columns. Up to 9 columns can be extracted
OPTIONAL INPUT KEYWORDS:
ROWS - scalar or vector giving row number(s) to extract
Row numbers start at 0. If not supplied or set to
-1 then values for all rows are returned
EXTEN_NO - Extension number to process. If not set, then data is
extracted from the first extension in the file (EXTEN_NO=1)
EXAMPLES:
Read wavelength and flux vectors from the first extension of a
FITS file, 'spec.fit'. Using FTAB_HELP,'spec.fit' we find that this
information is in columns named 'WAVELENGTH' and 'FLUX' (in columns 1
and 2). To read the data
IDL> ftab_ext,'spec.fit','wavelength,flux',w,f
or
IDL> ftab_ext,'spec.fit',[1,2],w,f
PROCEDURES CALLED:
FITS_READ, FITS_CLOSE, FTINFO, FTGET(), GETTOK(), TBINFO, TBGET()
HISTORY:
version 1 W. Landsman August 1997
Converted to IDL V5.0 W. Landsman September 1997
Improve speed processing binary tables W. Landsman March 2000
Use new FTINFO calling sequence W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/ftab_ext.pro)
FTAB_HELP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTAB_HELP
PURPOSE:
Describe the columns of a FITS binary or ASCII table extension.
CALLING SEQUENCE:
FTAB_HELP, filename, [ EXTEN_No = , TEXTOUT= ]
or
FTAB_HELP, fcb, [EXTEN_No=, TEXTOUT= ]
INPUTS:
filename - scalar string giving name of the FITS file.
fcb - FITS control block returned by a previous call to FITS_OPEN
OPTIONAL KEYWORD INPUTS:
EXTEN_NO - integer scalar specifying which FITS extension to read.
Default is to display the first FITS extension.
TEXTOUT - scalar number (0-7) or string (file name) determining
output device (see TEXTOPEN). Default is TEXTOUT=1, output
to the user's terminal
EXAMPLE:
Describe the columns in the second extension of a FITS file spec.fits
and write the results to a file 'spec2.lis'
IDL> ftab_help,'spec.fits',exten=2,t='spec2.lis'
SYSTEM VARIABLES:
Uses the non-standard system variables !TEXTOUT and !TEXTUNIT
which must be defined (e.g. with ASTROLIB) before compilation
PROCEDURES USED:
FITS_READ, FITS_CLOSE, FTHELP, TBHELP, TEXTOPEN, TEXTCLOSE
HISTORY:
version 1 W. Landsman August 1997
Converted to IDL V5.0 W. Landsman September 1997
Corrected documentation W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/ftab_help.pro)
FTAB_PRINT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTAB_PRINT
PURPOSE:
Print the contents of a FITS (binary or ASCII) table extension.
EXPLANATION:
User can specify which rows or columns to print
CALLING SEQUENCE:
FTAB_PRINT, filename, columns, rows, [ TEXTOUT=, FMT=, EXTEN_NO=]
INPUTS:
filename - scalar string giving name of a FITS file containing a
binary or ASCII table
columns - string giving column names, or vector giving
column numbers (beginning with 1). If string
supplied then column names should be separated by comma's.
rows - (optional) vector of row numbers to print (beginning with 0).
If not supplied or set to scalar, -1, then all rows
are printed.
OPTIONAL KEYWORD INPUT:
EXTEN_NO - Extension number to read. If not set, then the first
extension is printed (EXTEN_NO=1)
TEXTOUT - scalar number (0-7) or string (file name) determining
output device (see TEXTOPEN). Default is TEXTOUT=1, output
to the user's terminal
FMT = Format string for print display (binary tables only). If not
supplied, then any formats in the TDISP keyword fields will be
used, otherwise IDL default formats. For ASCII tables, the
format used is always as stored in the FITS table.
EXAMPLE:
Print all rows of the first 5 columns of the first extension of the
file 'wfpc.fits'
IDL> ftab_print,'wfpc.fits',indgen(5)+1
SYSTEM VARIABLES:
Uses the non-standard system variables !TEXTOUT and !TEXTUNIT
which must be defined (e.g. with ASTROLIB) prior to compilation.
PROCEDURES USED:
FITS_OPEN, FITS_READ, FTPRINT, TBPRINT
HISTORY:
version 1 W. Landsman August 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/ftab_print.pro)
FTADDCOL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTADDCOL
PURPOSE:
Routine to add a field to a FITS ASCII table
CALLING SEQUENCE:
ftaddcol, h, tab, name, idltype, [ tform, tunit, tscal, tzero, tnull ]
INPUTS:
h - FITS table header. It will be updated as appropriate
tab - FITS table array. Number of columns will be increased if
neccessary.
name - field name, scalar string
idltype - idl data type (as returned by SIZE function) for field,
For string data (type=7) use minus the string length.
OPTIONAL INPUTS:
tform - format specification 'qww.dd' where q = A, I, E, or D
tunit - string giving physical units for the column.
tscal - scale factor
tzero - zero point for field
tnull - null value for field
Use '' as the value of tform,tunit,tscal,tzero,tnull if you want
the default or no specification of them in the table header.
OUTPUTS:
h,tab - updated to allow new column of data
PROCEDURES USED:
FTINFO, FTSIZE, GETTOK(), SXADDPAR
HISTORY:
version 1 D. Lindler July, 1987
Converted to IDL V5.0 W. Landsman September 1997
Updated call to new FTINFO W. Landsman April 2000
(See /host/bluemoon/usr2/idllib/astron/pro/ftaddcol.pro)
FTCREATE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTCREATE
PURPOSE:
Create a new (blank) FITS ASCII table and header with specified size.
CALLING SEQUENCE:
ftcreate, maxcols, maxrows, h, tab
INPUTS:
maxcols - number of character columns allocated, integer scalar
maxrows - maximum number of rows allocated, integer scalar
OUTPUTS:
h - FITS header, string array
tab - empty table, byte array
HISTORY:
version 1 D. Lindler July. 87
21-Sep-88: Because the degenerative dimension is deleted in Sun IDL,
this procedure has been modified to create table with at
least two rows. If this isn't done, the other FT routines
choke on a table of one row.
24-Oct-88: Changed length of header strings from 81 to 80. This conforms
to the latest format for FITS header strings. The 81 character
format was dropped due to problems it caused when data was
transferred back to the VAX.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/ftcreate.pro)
FTDELCOL
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTDELCOL
PURPOSE:
Delete a column of data from a FITS table
CALLING SEQUENCE:
ftdelcol, h, tab, name
INPUTS-OUPUTS
h,tab - FITS table header and data array. H and TAB will
be updated with the specified column deleted
INPUTS:
name - Either (1) a string giving the name of the column to delete
or (2) a scalar giving the column number to delete
EXAMPLE:
Suppose it has been determined that the F7.2 format used for a field
FLUX in a FITS table is insufficient. The old column must first be
deleted before a new column can be written with a new format.
flux = FTGET(h,tab,'FLUX') ;Save the existing values
FTDELCOL,h,tab,'FLUX' ;Delete the existing column
FTADDCOL,h,tab,'FLUX',8,'F9.2' ;Create a new column with larger format
FTPUT,h,tab,'FLUX',0,flux ;Put back the original values
REVISION HISTORY:
Written W. Landsman STX Co. August, 1988
Adapted for IDL Version 2, J. Isensee, July, 1990
Converted to IDL V5.0 W. Landsman September 1997
Updated call to new FTINFO W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/ftdelcol.pro)
FTDELROW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTDELROW
PURPOSE:
Delete a row of data from a FITS table
CALLING SEQUENCE:
ftdelrow, h, tab, rows
INPUTS-OUPUTS
h,tab - FITS table header and data array. H and TAB will
be updated on output with the specified row(s) deleted.
rows - scalar or vector, specifying the row numbers to delete
This vector will be sorted and duplicates removed by FTDELROW
EXAMPLE:
Compress a table to include only non-negative flux values
flux = FTGET(h,tab,'FLUX') ;Obtain original flux vector
bad = where(flux lt 0) ;Find negative fluxes
FTDELROW,h,tab,bad ;Delete rows with negative fluxes
PROCEDURE:
Specified rows are deleted from the data array, TAB. The NAXIS2
keyword in the header is updated.
REVISION HISTORY:
Written W. Landsman STX Co. August, 1988
Checked for IDL Version 2, J. Isensee, July, 1990
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/ftdelrow.pro)
FTGET
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTGET
PURPOSE:
Function to return value(s) from specified column in a FITS ASCII table
CALLING SEQUENCE
values = FTGET( h, tab, field, [ rows, nulls ] )
or
values = FTGET( ft_str, tab, field. [rows, nulls]
INPUTS:
h - FITS ASCII extension header (e.g. as returned by FITS_READ)
or
ft_str - FITS table structure extracted from FITS header by FTINFO
Use of the IDL structure will improve processing speed
tab - FITS ASCII table array (e.g. as returned by FITS_READ)
field - field name or number
OPTIONAL INPUTS:
rows - scalar or vector giving row number(s)
Row numbers start at 0. If not supplied or set to
-1 then values for all rows are returned
OUTPUTS:
the values for the row are returned as the function value.
Null values are set to 0 or blanks for strings.
OPTIONAL OUTPUT:
nulls - null value flag of same length as the returned data.
It is set to 1 at null value positions and 0 elsewhere.
If supplied then the optional input, rows, must also
be supplied.
EXAMPLE:
Read the columns labeled 'WAVELENGTH' and 'FLUX' from the second
(ASCII table) extension of a FITS file 'spectra.fit'
IDL> fits_read,'spectra.fit',tab,htab,exten=2 ;Read 2nd extension
IDL> w = ftget( htab, tab,'wavelength') ;Wavelength vector
IDL> f = ftget( htab, tab,'flux') ;Flux vector
Slightly more efficient would be to first call FTINFO
IDL> ftinfo, htab, ft_str ;Extract structure
IDL> w = ftget(ft_str, tab,'wavelength') ;Wavelength vector
IDL> f = ftget(ft_str, tab,'flux') ;Flux vector
NOTES:
(1) Use the higher-level procedure FTAB_EXT to extract vectors
directly from the FITS file.
(2) Use FTAB_HELP or FTHELP to determine the columns in a particular
ASCII table.
HISTORY:
coded by D. Lindler July, 1987
Always check for null values W. Landsman August 1990
More informative error message W. Landsman Feb. 1996
Converted to IDL V5.0 W. Landsman September 1997
Allow structure rather than FITS header W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/ftget.pro)
FTHELP
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTHELP
PURPOSE:
Routine to print a description of a FITS ASCII table extension
CALLING SEQUENCE:
FTHELP, H, [ TEXTOUT = ]
INPUTS:
H - FITS header for ASCII table extension, string array
OPTIONAL INPUT KEYWORD
TEXTOUT - scalar number (0-7) or string (file name) determining
output device (see TEXTOPEN). Default is TEXTOUT=1, output
to the user's terminal
NOTES:
FTHELP checks that the keyword XTENSION equals 'TABLE' in the FITS
header.
SYSTEM VARIABLES:
Uses the non-standard system variables !TEXTOUT and !TEXTUNIT
which must be defined (e.g. with ASTROLIB) prior to compilation.
PROCEDURES USED:
REMCHAR, SXPAR(), TEXTOPEN, TEXTCLOSE, ZPARCHECK
HISTORY:
version 1 W. Landsman Jan. 1988
Add TEXTOUT option, cleaner format W. Landsman September 1991
TTYPE value can be longer than 8 chars, W. Landsman August 1995
Converted to IDL V5.0 W. Landsman September 1997
Remove calls to !ERR, some vectorization W. Landsman February 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fthelp.pro)
FTHMOD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTHMOD
PURPOSE:
Procedure to modify header information for a specified field
in a FITS table.
CALLING SEQUENCE:
fthmod, h, field, parameter, value
INPUT:
h - FITS header for the table
field - field name or number
parameter - string name of the parameter to modify. Choices
include:
TTYPE - field name
TUNIT - physical units for field (eg. 'ANGSTROMS')
TNULL - null value (string) for field, (eg. '***')
TFORM - format specification for the field
TSCAL - scale factor
TZERO - zero offset
User should be aware that the validity of the change is
not checked. Unless you really know what you are doing,
this routine should only be used to change field names,
units, or another user specified parameter.
value - new value for the parameter. Refer to the FITS table
standards documentation for valid values.
EXAMPLE:
Change the units for a field name "FLUX" to "Janskys" in a FITS table
header,h
IDL> FTHMOD, h, 'FLUX', 'TUNIT','Janskys'
METHOD:
The header keyword is modified
with the new value.
HISTORY:
version 1, D. Lindler July 1987
Converted to IDL V5.0 W. Landsman September 1997
Major rewrite to use new FTINFO call W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fthmod.pro)
FTINFO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTINFO
PURPOSE:
Return an informational structure from a FITS ASCII table header.
CALLING SEQUENCE:
ftinfo,h,ft_str, [Count = ]
INPUTS:
h - FITS ASCII table header, string array
OUTPUTS:
ft_str - IDL structure with extracted info from the FITS ASCII table
header. Tags include
.tbcol - starting column position in bytes
.width - width of the field in bytes
.idltype - idltype of field.
7 - string, 4- real*4, 3-integer, 5-real*8
.tunit - string unit numbers
.tscal - scale factor
.tzero - zero point for field
.tnull - null value for the field
.tform - format for the field
.ttype - field name
OPTIONAL OUTPUT KEYWORD:
Count - Integer scalar giving number of fields in the table
PROCEDURES USED:
GETTOK(), SXPAR()
NOTES:
This procedure underwent a major revision in May 2000, and **THE
NEW CALLING SEQUENCE IS INCOMPATIBLE WITH THE OLD ONE **
HISTORY:
D. Lindler July, 1987
Converted to IDL V5.0 W. Landsman September 1997
Major rewrite, return structure W. Landsman April 2000
(See /host/bluemoon/usr2/idllib/astron/pro/ftinfo.pro)
FTKEEPROW
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTKEEPROW
PURPOSE:
Subscripts (and reorders) a FITS table. A companion piece to FTDELROW.
CALLING SEQUENCE:
ftkeeprow, h, tab, subs
INPUT PARAMETERS:
h = FITS table header array
tab = FITS table data array
subs = subscript array of FITS table rows. Works like any other IDL
subscript array (0 based, of course).
OUTPUT PARAMETERS:
h and tab are modified
MODIFICATION HISTORY:
Written by R. S. Hill, ST Sys. Corp., 2 May 1991.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/ftkeeprow.pro)
FTPRINT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTPRINT
PURPOSE:
Procedure to print specified columns and rows of a FITS table
CALLING SEQUENCE:
FTPRINT, h, tab, columns, [ rows, TEXTOUT = ]
INPUTS:
h - Fits header for table, string array
tab - table array
columns - string giving column names, or vector giving
column numbers (beginning with 1). If string
supplied then column names should be separated by comma's.
rows - (optional) vector of row numbers to print. If
not supplied or set to scalar, -1, then all rows
are printed.
OUTPUTS:
None
OPTIONAL INPUT KEYWORDS:
TEXTOUT controls the output device; see the procedure TEXTOPEN
SYSTEM VARIABLES:
Uses nonstandard system variables !TEXTOUT and !TEXTOPEN
Set !TEXTOUT = 3 to direct output to a disk file. The system
variable is overriden by the value of the keyword TEXTOUT
EXAMPLES:
ftprint,h,tab,'STAR ID,RA,DEC' ;print id,ra,dec for all stars
ftprint,h,tab,[2,3,4],indgen(100) ;print columns 2-4 for
;first 100 stars
ftprint,h,tab,text="stars.dat" ;Convert entire FITS table to
;an ASCII file named STARS.DAT
PROCEDURES USED:
FTSIZE, FTINFO, TEXTOPEN, TEXTCLOSE
RESTRICTIONS:
(1) Program does not check whether output length exceeds output
device capacity (e.g. 80 or 132).
(2) Column heading may be truncated to fit in space defined by
the FORMAT specified for the column
(3) Program does not check for null values
HISTORY:
version 1 D. Lindler Feb. 1987
Accept undefined values of rows, columns W. Landsman August 1997
Converted to IDL V5.0 W. Landsman September 1997
New FTINFO calling sequence W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/ftprint.pro)
FTPUT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTPUT
PURPOSE:
Procedure to add or update a field in an FITS ASCII table
CALLING SEQUENCE:
FTPUT, htab, tab, field, row, values, [ nulls ]
INPUTS:
htab - FITS ASCII table header string array
tab - FITS ASCII table array (e.g. as read by READFITS)
field - string field name or integer field number
row - either a non-negative integer scalar giving starting row to
update, or a non-negative integer vector specifying rows to
update. FTPUT will append a new row to a table if the value
of 'row' exceeds the number of rows in the tab array
values - value(s) to add or update. If row is a vector
then values must contain the same number of elements.
OPTIONAL INPUT:
nulls - null value flag of same length as values.
It should be set to 1 at null value positions
and 0 elsewhere.
OUTPUTS:
htab,tab will be updated as specified.
NOTES:
(1) If the specified field is not already in the table, then FTPUT will
create a new column for that field using default formatting. However,
FTADDCOL should be called prior to FTPUT for explicit formatting.
PROCEDURES CALLED
FSTRING(), FTADDCOL, FTINFO, FTSIZE, SXADDPAR, SXPAR()
HISTORY:
version 1 D. Lindler July, 1987
Allow E format W. Landsman March 1992
Write in F format if E format will overflow April 1994
Update documentation W. Landsman January 1996
Allow 1 element vector W. Landsman March 1996
Adjust string length to maximum of input string array June 1997
Work for more than 32767 elements August 1997
Converted to IDL V5.0 W. Landsman September 1997
Updated call to the new FTINFO W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/ftput.pro)
FTSIZE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTSIZE
PURPOSE:
Procedure to return the size of a FITS ASCII table.
CALLING SEQUENCE:
ftsize,h,tab,ncols,rows,tfields,ncols_all,nrows_all, [ERRMSG = ]
INPUTS:
h - FITS ASCII table header, string array
tab - FITS table array, 2-d byte array
OUTPUTS:
ncols - number of characters per row in table
nrows - number of rows in table
tfields - number of fields per row
ncols_all - number of characters/row allocated (size of tab)
nrows_all - number of rows allocated
OPTIONAL OUTPUT KEYWORD:
ERRMSG = If this keyword is present, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned.
HISTORY
D. Lindler July, 1987
Fix for 1-row table, W. Landsman HSTX, June 1994
Converted to IDL V5.0 W. Landsman September 1997
Added ERRMSG keyword W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/ftsize.pro)
FTSORT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FTSORT
PURPOSE:
Sort a FITS ASCII table according to a specified field
CALLING SEQUENCE:
FTSORT,h,tab,[field, REVERSE = ] ;Sort original table header and array
or
FTSORT,h,tab,hnew,tabnew,[field, REVERSE =] ;Create new sorted header
INPUTS:
H - FITS header (string array)
TAB - FITS table (byte array) associated with H. If less than 4
parameters are supplied, then H and TAB will be updated to
contain the sorted table
OPTIONAL INPUTS:
FIELD - Field name(s) or number(s) used to sort the entire table.
If FIELD is a vector then the first element is used for the
primary sort, the second element is used for the secondary
sort, and so forth. (A secondary sort only takes effect when
values in the primary sort field are equal.) Character fields
are sorted using the ASCII collating sequence. If omitted,
the user will be prompted for the field name.
OPTIONAL OUTPUTS:
HNEW,TABNEW - Header and table containing the sorted tables
EXAMPLE:
Sort a FITS ASCII table by the 'DECLINATION' field in descending order
Assume that the table header htab, and array, tab, have already been
read (e.g. with READFITS or FITS_READ):
IDL> FTSORT, htab, tab,'DECLINATION',/REVERSE
OPTIONAL INPUT KEYWORD:
REVERSE - If set then the table is sorted in reverse order (maximum
to minimum. If FIELD is a vector, then REVERSE can also be
a vector. For example, REVERSE = [1,0] indicates that the
primary sort should be in descending order, and the secondary
sort should be in ascending order.
EXAMPLE:
SIDE EFFECTS:
A HISTORY record is added to the table header.
REVISION HISTORY:
Written W. Landsman June, 1988
Converted to IDL V5.0 W. Landsman September 1997
New FTINFO calling sequence, added REVERSE keyword, allow secondary sorts
W. Landsman May 2000
(See /host/bluemoon/usr2/idllib/astron/pro/ftsort.pro)
FXADDPAR
[Previous Routine]
[Next Routine]
[List of Routines]
Name :
FXADDPAR
Purpose :
Add or modify a parameter in a FITS header array.
Explanation :
This version of FXADDPAR will write string values longer than 68
characters using the FITS continuation convention described at
http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html
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. If the value is a string and is "long"
(more than 69 characters), then it may be continued
over more than one line using the OGIP CONTINUE
standard.
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.
/NOCONTINUE = By default, FXADDPAR will break strings longer than 68
characters into multiple lines using the continuation
convention. If this keyword is set, then the line will
instead be truncated to 68 characters. This was the default
behaviour of FXADDPAR prior to December 1999.
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.
String values longer than 68 characters will be split into multiple
lines using the OGIP CONTINUE convention, unless the /NOCONTINUE keyword
is set. For a description of the CONTINUE convention see
http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.htm
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 2, William Thompson, GSFC, 5 September 1997
Fixed bug replacing strings that contain "/" character--it
interpreted the following characters as a comment.
Version 3, Craig Markwardt, GSFC, December 1997
Allow long values to extend over multiple lines
Version 4, D. Lindler, March 2000, modified to use capital E instead
of a lower case e for exponential format.
Version 4.1 W. Landsman April 2000, make user-supplied format uppercase
Version :
Version 4.1, April 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fxaddpar.pro)
FXBADDCOL
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXBADDCOL
Purpose :
Adds a column to a binary table extension.
Explanation :
Modify a basic FITS binary table extension (BINTABLE) header array to
define a column.
Use :
FXBADDCOL, INDEX, HEADER, ARRAY [, TTYPE [, COMMENT ]]
Inputs :
HEADER = String array containing FITS extension header.
ARRAY = IDL variable used to determine the data size and type
associated with the column. If the column is defined as
containing variable length arrays, then ARRAY must be of the
maximum size to be stored in the column.
Opt. Inputs :
TTYPE = Column label.
COMMENT = Comment for TTYPE
Outputs :
INDEX = Index (1-999) of the created column.
HEADER = The header is modified to reflect the added column.
Opt. Outputs:
None.
Keywords :
VARIABLE= If set, then the column is defined to contain pointers to
variable length arrays in the heap area.
DCOMPLEX= If set, and ARRAY is complex, with the first dimension being
two (real and imaginary parts), then the column is defined as
double-precision complex (type "M"). This keyword is
only needed prior to IDL Version 4.0, when the double
double complex datatype was unavailable in IDL
BIT = If passed, and ARRAY is of type byte, then the column is
defined as containg bit mask arrays (type "X"), with the
value of BIT being equal to the number of mask bits.
LOGICAL = If set, and array is of type byte, then the column is defined
as containing logical arrays (type "L").
NO_TDIM = If set, then the TDIMn keyword is not written out to the
header. No TDIMn keywords are written for columns containing
variable length arrays.
TUNIT = If passed, then corresponding keyword is added to header.
TSCAL = Same.
TZERO = Same.
TNULL = Same.
TDISP = Same.
TDMIN = Same.
TDMAX = Same.
TDESC = Same.
TCUNI = Same.
TROTA = Same.
TRPIX = Same.
TRVAL = Same.
TDELT = Same.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBADDCOL, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
FXADDPAR, FXPAR
Common :
None.
Restrictions:
Warning: No checking is done of any of the parameters defining the
values of optional FITS keywords.
FXBHMAKE must first be called to initialize the header.
If ARRAY is of type character, then it must be of the maximum length
expected for this column. If a character string array, then the
largest string in the array is used to determine the maximum length.
The DCOMPLEX keyword is ignored if ARRAY is not double-precision.
ARRAY must also have a first dimension of two representing the real and
imaginary parts.
The BIT and LOGICAL keywords are ignored if ARRAY is not of type byte.
BIT takes precedence over LOGICAL.
Side effects:
If the data array is multidimensional, then a TDIM keyword is added to
the header, unless either NO_TDIM or VARIABLE is set.
No TDIMn keywords are written out for bit arrays (format 'X'), since
the dimensions would refer to bits, not bytes.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
William Thompson, Jan 1992.
W. Thompson, Feb 1992, changed from function to procedure.
W. Thompson, Feb 1992, modified to support variable length arrays.
Written :
William Thompson, GSFC, January 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 31 May 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 4, William Thompson, GSFC, 30 December 1994
Added keyword TCUNI.
Version 5, Wayne Landsman, GSFC, 12 Aug 1997
Recognize double complex IDL datatype
Version :
Version 5, 12 Aug 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbaddcol.pro)
FXBCLOSE
[Previous Routine]
[Next Routine]
[List of Routines]
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 :
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBCLOSE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
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 2, William Thompson, GSFC, 21 June 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version :
Version 3, 23 June 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbclose.pro)
FXBCOLNUM
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXBCOLNUM()
Purpose :
Returns a binary table column number.
Explanation :
Given a column specified either by number or name, this routine will
return the appropriate column number.
Use :
Result = FXBCOLNUM( UNIT, COL )
Inputs :
UNIT = Logical unit number corresponding to the file containing the
binary table.
COL = Column in the binary table, given either as a character
string containing a column label (TTYPE), or as a numerical
column index starting from column one.
Opt. Inputs :
None.
Outputs :
The result of the function is the number of the column specified, or
zero if no column is found (when passed by name).
Opt. Outputs:
None.
Keywords :
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
Result = FXBCOLNUM( ERRMSG=ERRMSG, ... )
IF ERRMSG NE '' THEN ...
Calls :
None.
Common :
Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions:
The binary table file must have been opened with FXBOPEN.
If COL is passed as a number, rather than as a name, then it must be
consistent with the number of columns in the table.
Side effects:
None.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
None.
Written :
William Thompson, GSFC, 2 July 1993.
Modified :
Version 1, William Thompson, GSFC, 2 July 1993.
Version 2, William Thompson, GSFC, 29 October 1993.
Added error message for not finding column by name.
Version 3, William Thompson, GSFC, 21 June 1994
Added ERRMSG keyword.
Version 4, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version :
Version 4, 23 June 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbcolnum.pro)
FXBCREATE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXBCREATE
Purpose :
Open a new binary table at the end of a FITS file.
Explanation :
Write a binary table extension header to the end of a disk FITS file,
and leave it open to receive the data.
The FITS file is opened, and the pointer is positioned just after the
last 2880 byte record. Then the binary header is appended. Calls to
FXBWRITE will append the binary data to this file, and then FXBFINISH
will close the file.
Use :
FXBCREATE, UNIT, FILENAME, HEADER
Inputs :
FILENAME = Name of FITS file to be opened.
HEADER = String array containing the FITS binary table extension
header.
Opt. Inputs :
None.
Outputs :
UNIT = Logical unit number of the opened file.
EXTENSION= Extension number of newly created extension.
Opt. Outputs:
None.
Keywords :
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBCREATE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
FXADDPAR, FXBFINDLUN, FXBPARSE, FXFINDEND
Common :
Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions:
The primary FITS data unit must already be written to a file. The
binary table extension header must already be defined (FXBHMAKE), and
must match the data that will be written to the file.
Side effects:
None.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman.
W. Thompson, Feb 1992, changed from function to procedure.
W. Thompson, Feb 1992, removed all references to temporary files.
Written :
William Thompson, GSFC, January 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 21 July 1993.
Fixed bug with variable length arrays.
Version 3, William Thompson, GSFC, 21 June 1994
Added ERRMSG keyword.
Version 4, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 5, Antony Bird, Southampton, 25 June 1997
Modified to allow very long tables
Version :
Version 5, 25 June 1997
Converted to IDL V5.0 W. Landsman September 1997
Added EXTENSION parameter, C. Markwardt 1999 Jul 15
(See /host/bluemoon/usr2/idllib/astron/pro/fxbcreate.pro)
FXBDIMEN
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : FXBDIMEN()
Purpose : Returns the dimensions for a column in a FITS binary table.
Explanation : This procedure returns the dimensions associated with a column
in a binary table opened for read with the command FXBOPEN.
Use : Result = FXBDIMEN(UNIT,COL)
Inputs : UNIT = Logical unit number returned by FXBOPEN routine.
Must be a scalar integer.
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 : None.
Outputs : The result of the function is an array containing the
dimensions for the specified column in the FITS binary table
that UNIT points to.
Opt. Outputs: None.
Keywords : ERRMSG = If defined and passed, then any error messages will
be returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no
errors are encountered, then a null string is
returned. In order to use this feature, ERRMSG must
be defined first, e.g.
ERRMSG = ''
Result = FXBDIMEN( ERRMSG=ERRMSG, ... )
IF ERRMSG NE '' THEN ...
Calls : FXBCOLNUM, FXBFINDLUN
Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions: None.
Side effects: The dimensions will be returned whether or not the table is
still open or not.
If UNIT does not point to a binary table, then 0 is returned.
If UNIT is an undefined variable, then 0 is returned.
Category : Data Handling, I/O, FITS, Generic.
Prev. Hist. : None.
Written : William Thompson, GSFC, 4 March 1994.
Modified : Version 1, William Thompson, GSFC, 4 March 1994.
Version 2, William Thompson, GSFC, 21 June 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version : Version 3, 23 June 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbdimen.pro)
FXBFIND
[Previous Routine]
[Next Routine]
[List of Routines]
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.
Vectorized implementation improves performance, CM 18 Nov 1999
(See /host/bluemoon/usr2/idllib/astron/pro/fxbfind.pro)
FXBFINDLUN
[Previous Routine]
[Next Routine]
[List of Routines]
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 3, Michael Schubnell, University of Michigan, 22 May 1996
Change N_DIMS from short to long integer.
Version :
Version 3, 22 May 1996
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbfindlun.pro)
FXBFINISH
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXBFINISH
Purpose :
Close a FITS binary table extension file opened for write.
Explanation :
Closes a FITS binary table extension file that had been opened for
write by FXBCREATE.
Use :
FXBFINISH, UNIT
Inputs :
UNIT = Logical unit number of the file.
Opt. Inputs :
None.
Outputs :
None.
Opt. Outputs:
None.
Keywords :
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBFINISH, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
None.
Common :
Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions:
The file must have been opened with FXBCREATE, and written with
FXBWRITE.
Side effects:
Any bytes needed to pad the file out to an integral multiple of 2880
bytes are written out to the file. Then, the file is closed.
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, Feb 1992, removed all references to temporary files.
Written :
William Thompson, GSFC, January 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 21 July 1993.
Fixed bug with variable length arrays.
Version 3, William Thompson, GSFC, 31 May 1994
Added ERRMSG keyword.
Version 4, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version :
Version 4, 23 June 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbfinish.pro)
FXBGROW
[Previous Routine]
[Next Routine]
[List of Routines]
Project : RXTE/PCA
Name :
FXBGROW
Purpose :
Increase the number of rows in a binary table.
Explanation :
Call FXBGROW to increase the size of an already-existing FITS
binary table. The number of rows increases to NROWS (or does
not change if NROWS is less than the number of rows already
existing). WARNING: the table to be grown must be the *last*
extension in the FITS file. FXBGROW does *not* preserve any
following extensions. This procedure is useful when a table
with an unknown number of rows must be created. The caller
would then call FXBCREATE to construct a table of some base
size, and follow with calls to FXBGROW to lengthen the table
as needed.
Use :
FXBGROW, UNIT, HEADER, NROWS[, ERRMSG=ERRMSG, NOZERO=NOZERO]
Inputs :
UNIT = Logical unit number of an already-opened file.
HEADER = String array containing the FITS binary table extension
header. The header is modified in place.
NROWS = New number of rows, always more than the previous
number.
Opt. Inputs :
None.
Outputs :
None.
Opt. Outputs:
None.
Keywords :
NOZERO = when set, FXBGROW will not zero-pad the new data if
it doesn't have to.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBGROW, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
FXADDPAR, FXHREAD
Common :
Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions:
The file must be open with write permission.
The binary table extension in question must already by written
to the file (using FXBCREATE), and must be the last extension
in the file.
A table can never shrink via this operation.
This operation is not well optimized for tables with large
heap usage, such as large variable-length columns. Since the
procedure must move the entire heap upon every call, it could
be (1) memory intensive and (2) I/O intensive.
Side effects:
The FITS file will grow in size, and heap areas are
preserved by moving them to the end of the file.
The header is modified to reflect the new number of rows.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
Initially written, C. Markwardt, GSFC, Nov 1998
Written :
Craig Markwardt, GSFC, Nov 1998
Version :
Version 1, 17 Nov 1998
(See /host/bluemoon/usr2/idllib/astron/pro/fxbgrow.pro)
FXBHEADER
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : FXBHEADER()
Purpose : Returns the header of an open FITS binary table.
Explanation : This procedure returns the FITS extension header of a FITS
binary table opened for read with the command FXBOPEN.
Use : Result = FXBHEADER(UNIT)
Inputs : UNIT = Logical unit number returned by FXBOPEN routine.
Must be a scalar integer.
Opt. Inputs : None.
Outputs : The result of the function is a string array containing the
header for the FITS binary table that UNIT points to.
Opt. Outputs: None.
Keywords : None.
Calls : FXBFINDLUN
Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions: None.
Side effects: The string array returned always has as many elements as the
largest header read by FXBOPEN. Any extra elements beyond the
true header are blank or null strings.
The header will be returned whether or not the table is still
open or not.
If UNIT does not point to a binary table, then a string array
of nulls is returned.
If UNIT is an undefined variable, then the null string is
returned.
Category : Data Handling, I/O, FITS, Generic.
Prev. Hist. : None.
Written : William Thompson, GSFC, 1 July 1993.
Modified : Version 1, William Thompson, GSFC, 1 July 1993.
Version : Version 1, 1 July 1993.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbheader.pro)
FXBHELP
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXBHELP
Purpose :
Prints short description of columns in a FITS binary table.
Explanation :
Prints a short description of the columns in a FITS binary table to the
terminal screen.
Use :
FXBHELP, UNIT
Inputs :
UNIT = Logical unit number of file opened by FXBOPEN.
Opt. Inputs :
None.
Outputs :
None.
Opt. Outputs:
None.
Keywords :
None.
Calls :
FXBFIND, FXBFINDLUN, FXPAR
Common :
Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions:
The file must have been opened with FXBOPEN.
Side effects:
Certain fields may be truncated in the display.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
William Thompson, Feb. 1992, from TBHELP by W. Landsman.
Written :
William Thompson, GSFC, February 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 12 May 1993.
Modified to not write to a logical unit number assigned to the
terminal. This makes it compatible with IDL for Windows.
Version :
Version 2, 12 May 1993.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbhelp.pro)
FXBHMAKE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXBHMAKE
Purpose :
Create basic FITS binary table extension (BINTABLE) header.
Explanation :
Creates a basic header array with all the required keywords, but with
none of the table columns defined. This defines a basic structure
which can then be added to or modified by other routines.
Use :
FXBHMAKE, HEADER, NROWS [, EXTNAME [, COMMENT ]]
Inputs :
NROWS = Number of rows in the binary table.
Opt. Inputs :
EXTNAME = If passed, then the EXTNAME record is added with this value.
COMMENT = Comment to go along with EXTNAME.
Outputs :
HEADER = String array containing FITS extension header.
Opt. Outputs:
None.
Keywords :
INITIALIZE = If set, then the header is completely initialized, and any
previous entries are lost.
DATE = If set, then the DATE keyword is added to the header.
EXTVER = Extension version number (integer).
EXTLEVEL = Extension level number (integer).
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBHMAKE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
GET_DATE, FXADDPAR, FXHCLEAN
Common :
None.
Restrictions:
Warning: No checking is done of any of the parameters.
Side effects:
None.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
William Thompson, Jan 1992.
William Thompson, Sep 1992, added EXTVER and EXTLEVEL keywords.
Written :
William Thompson, GSFC, January 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 21 June 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version :
Version 3, 23 June 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbhmake.pro)
FXBINTABLE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXBINTABLE
Purpose :
Common block FXBINTABLE used by "FXB" routines.
Explanation :
This is not an IDL routine as such, but contains the definition of the
common block FXBINTABLE for inclusion into other routines. By defining
the common block in one place, the problem of conflicting definitions
is avoided.
This file is included into routines that need this common block with
the single line (left justified)
@fxbintable
FXBINTABLE contains the following arrays:
LUN = An array of logical unit numbers of currently (or
previously) opened binary table files.
STATE = Array containing the state of the FITS files
associated with the logical unit numbers, where
0=closed, 1=open for read, and 2=open for write.
HEAD = FITS binary table headers.
MHEADER = Array containing the positions of the first data byte
of the header for each file referenced by array LUN.
NHEADER = Array containing the positions of the first data byte
after the header for each file referenced by array
LUN.
NAXIS1 = Values of NAXIS1 from the binary table headers.
NAXIS2 = Values of NAXIS2 from the binary table headers.
TFIELDS = Values of TFIELDS from the binary table headers.
HEAP = The start of the first byte of the heap area
for variable length arrays.
DHEAP = The start of the first byte of the next variable
length array, if writing.
BYTOFF = Byte offset from the beginning of the row for each
column in the binary table headers.
TTYPE = Values of TTYPE for each column in the binary table
headers.
FORMAT = Character code formats of the various columns.
IDLTYPE = IDL type code for each column in the binary table
headers.
N_ELEM = Number of elements for each column in the binary
table headers.
TSCAL = Scale factors for the individual columns.
TZERO = Zero offsets for the individual columns.
MAXVAL = For variable length arrays, contains the maximum
number of elements for each column in the binary
table headers.
N_DIMS = Number of dimensions, and array of dimensions for
each column of type string in the binary table
headers.
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 /host/bluemoon/usr2/idllib/astron/pro/fxbintable.pro)
FXBISOPEN
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : FXBISOPEN()
Purpose : Returns true if UNIT points to an open FITS binary table.
Explanation : This procedure checks to see if the logical unit number given
by the variable UNIT corresponds to a FITS binary table opened
for read with the command FXBOPEN, and which has not yet been
closed with FXBCLOSE.
Use : Result = FXBISOPEN(UNIT)
If FXBISOPEN(UNIT) THEN ...
Inputs : UNIT = Logical unit number returned by FXBOPEN routine.
Must be a scalar integer.
Opt. Inputs : None.
Outputs : The result of the function is either True (1) or False (0),
depending on whether UNIT points to an open binary table or
not.
Opt. Outputs: None.
Keywords : None.
Calls : FXBFINDLUN
Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions: None.
Side effects: If UNIT is an undefined variable, then False (0) is returned.
If UNIT points to a FITS binary table file that is opened for
write, then False (0) is returned.
Category : Data Handling, I/O, FITS, Generic.
Prev. Hist. : None.
Written : William Thompson, GSFC, 1 July 1993.
Modified : Version 1, William Thompson, GSFC, 1 July 1993.
Version : Version 1, 1 July 1993.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbisopen.pro)
FXBOPEN
[Previous Routine]
[Next Routine]
[List of Routines]
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. Optional
extension *number* may be specified, in either of
the following formats (using the FTOOLS
convention): FILENAME[EXT] or FILENAME+EXT, where
EXT is 1 or higher. Such an extension
specification takes priority over EXTENSION.
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.
ACCESS = A scalar string describing access privileges as
one of READ ('R') or UPDATE ('RW').
DEFAULT: 'R'
REOPEN = If set, UNIT must be an already-opened file unit.
FXBOPEN will treat the file as a FITS file.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBOPEN, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
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 2, William Thompson, GSFC, 27 May 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 21 June 1994
Extended ERRMSG to call to FXBPARSE
Version 4, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 4, 23 June 1994
Converted to IDL V5.0 W. Landsman September 1997
Added ACCESS, REOPEN keywords, and FXFILTER package, CM 1999 Feb 03
Added FILENAME[EXT] and FILENAME+EXT extension parsing, CM 1999 Jun 28
Some general tidying, CM 1999 Nov 18
(See /host/bluemoon/usr2/idllib/astron/pro/fxbopen.pro)
FXBPARSE
[Previous Routine]
[Next Routine]
[List of Routines]
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.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBPARSE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
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 2, William Thompson, GSFC, 21 June 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 4, Michael Schubnell, University of Michigan, 22 May 1996
Change N_DIMS from short to long integer.
Version 5, W. Landsman, GSFC, 12 Aug 1997
Use double complex datatype, if needed
Version 6, W. Landsman GSFC 30 Aug 1997
Version :
Version 6, 31 Aug 1997
Optimized FXPAR; call FXBFIND for speed, CM 1999 Nov 18
(See /host/bluemoon/usr2/idllib/astron/pro/fxbparse.pro)
FXBREAD
[Previous Routine]
[Next Routine]
[List of Routines]
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 output data will not be scaled using the
optional TSCAL and TZERO keywords in the FITS header.
Default is to scale.
NOIEEE = If set, then the output data is not byte-swapped to
machine order. NOIEEE implies NOSCALE.
Default is to perform the byte-swap.
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.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBREAD, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
IEEE_TO_HOST, FXPAR, WHERE_NEGZERO, 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 5, William Thompson, GSFC, 31 May 1994
Added ERRMSG keyword.
Version 6, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 7, William Thompson, GSFC, 29 December 1994
Fixed bug where single element dimensions were lost.
Version 8, William Thompson, GSFC, 20 March 1995
Fixed bug introduced in version 7.
Version 9, Wayne Landsman, GSFC, 3 July 1996
Fixed bug involving use of virtual keyword.
Version 10, William Thompson, GSFC, 31-Jan-1997
Added call to WHERE_NEGZERO.
Version 11, Wayne Landsman, GSFC, 12 Aug, 1997
Use IDL dcomplex datatype if needed
Version 12, Wayne Landmsan, GSFC, 20 Feb, 1998
Remove call to WHERE_NEGZERO (now part of IEEE_TO_HOST)
Version 13, 18 Nov 1999, CM, Add NOIEEE keyword
Version 14, 21 Aug 2000, William Thompson, GSFC
Catch I/O errors
Version :
Version 14, 21 Aug 2000
(See /host/bluemoon/usr2/idllib/astron/pro/fxbread.pro)
FXBREADM
[Previous Routine]
[Next Routine]
[List of Routines]
Project : RXTE/PCA
Name :
FXBREADM
Purpose :
Read multiple columns/rows from a disk FITS binary table file.
Explanation :
A call to FXBREADM will read data from multiple rows and
multiple columns in a single procedure call. Up to fifty
columns may be read in a single pass; the number of rows is
limited essentially by available memory. The file should have
already been opened with FXBOPEN. FXBREADM optimizes reading
multiple columns by first reading a large chunk of data from
the FITS file directly, and then slicing the data into columns
within memory. FXBREADM cannot read variable-length arrays;
use FXBREAD instead.
Use :
FXBREADM, UNIT, COL, DATA1, DATA2, ... [, ROW=ROW ]
Inputs :
UNIT = Logical unit number corresponding to the file containing the
binary table.
COL = An array of columns in the binary table to read data
from, either as character strings containing column
labels (TTYPE), or as numerical column indices
starting from column one.
Opt. Inputs :
None.
Outputs :
D0, ... = A named variable to accept the data values, one for
each column. The columns are stored in order of the
list in COL. If the read operation fails for a
particular column, then the corresponding output Dn
variable is not altered. See the STATUS keyword.
Opt. Outputs:
None.
Keywords :
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.
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 = FXBREADM ignores this keyword. It is here for
compatibility only.
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.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBREAD, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
WARNMSG = Messages which are considered to be non-fatal
"warnings" are returned in this output string.
BUFFERSIZE = Raw data are transferred from the file in chunks
to conserve memory. This is the size in bytes of
each chunk. If a value of zero is given, then all
of the data are transferred in one pass. Default is
32768 (32 kB).
STATUS = An output array containing the status for each
column read, 1 meaning success and 0 meaning failure.
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.
No variable-length columns may be read with FXBREADM.
Generaly speaking, FXBREADM will be faster than iterative
calls to FXBREAD when (a) a large number of columns is to be
read or (b) the size in bytes of each cell is small, so that
the overhead of the FOR loop in FXBREAD becomes significant.
Side effects:
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. :
C. Markwardt, January 1999, based in concept on FXBREAD version 12 from
IDLASTRO, but with significant and
major changes to accomodate the
multiple row/column technique. Mostly
the parameter checking and general data
flow remain.
Written :
Craig Markwardt, GSFC, January 1999.
Modified :
Version 1, Craig Markwardt, GSFC 18 January 1999.
Documented this routine, 18 January 1999.
Version :
Version 1, 18 January 1999.
(See /host/bluemoon/usr2/idllib/astron/pro/fxbreadm.pro)
FXBSTATE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : FXBSTATE()
Purpose : Returns the state of a FITS binary table.
Explanation : This procedure returns the state of a FITS binary table that
was either opened for read with the command FXBOPEN, or for
write with the command FXBCREATE.
Use : Result = FXBSTATE(UNIT)
Inputs : UNIT = Logical unit number returned by FXBOPEN routine.
Must be a scalar integer.
Opt. Inputs : None.
Outputs : The result of the function is the state of the FITS binary
table that UNIT points to. This can be one of three values:
0 = Closed
1 = Open for read
2 = Open for write
Opt. Outputs: None.
Keywords : None.
Calls : FXBFINDLUN
Common : Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions: None.
Side effects: If UNIT is an undefined variable, then 0 (closed) is returned.
Category : Data Handling, I/O, FITS, Generic.
Prev. Hist. : None.
Written : William Thompson, GSFC, 1 July 1993.
Modified : Version 1, William Thompson, GSFC, 1 July 1993.
Version : Version 1, 1 July 1993.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbstate.pro)
FXBTDIM
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXBTDIM()
Purpose :
Parse TDIM-like kwywords.
Explanation :
Parses the value of a TDIM-like keyword (e.g. TDIMnnn, TDESC, etc.) to
return the separate elements contained within.
Use :
Result = FXBTDIM( TDIM_KEYWORD )
Inputs :
TDIM_KEYWORD = The value of a TDIM-like keyword. Must be a
character string of the form "(value1,value2,...)".
If the parentheses characters are missing, then the
string is simply returned as is, without any further
processing.
Opt. Inputs :
None.
Outputs :
The result of the function is a character string array containing the
values contained within the keyword parameter. If a numerical result
is desired, then simply call, e.g.
Result = FIX( FXBTDIM( TDIM_KEYWORD ))
Opt. Outputs:
None.
Keywords :
None.
Calls :
GETTOK
Common :
None.
Restrictions:
The input parameter must have the proper format. The separate values
must not contain the comma character. TDIM_KEYWORD must not be an
array.
Side effects:
None.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
William Thompson, Jan. 1992.
William Thompson, Jan. 1993, renamed to be compatible with DOS
limitations.
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.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbtdim.pro)
FXBTFORM
[Previous Routine]
[Next Routine]
[List of Routines]
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 :
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBTFORM, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
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 2, William Thompson, GSFC, 21 June 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 4, William Thompson, GSFC, 9 April 1997
Modified so that variable length arrays can be read, even if
the maximum array size is not in the header.
Version 5 Wayne Landsman, GSFC, August 1997
Recognize double complex array type if since IDL version 4.0
Version :
Version 6
Optimized FXPAR call, CM 1999 Nov 18
(See /host/bluemoon/usr2/idllib/astron/pro/fxbtform.pro)
FXBWRITE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXBWRITE
Purpose :
Write a binary data array to a disk FITS binary table file.
Explanation :
Each call to FXBWRITE will write to the data file, which should already
have been created and opened by FXBCREATE. One needs to call this
routine for every column and every row in the binary table. FXBFINISH
will then close the file.
Use :
FXBWRITE, UNIT, DATA, COL, ROW
Inputs :
UNIT = Logical unit number corresponding to the file containing the
binary table.
DATA = IDL data array to be written to the file.
COL = Column in the binary table to place data in, starting from
column one.
ROW = Row in the binary table to place data in, starting from row
one.
Opt. Inputs :
None.
Outputs :
None.
Opt. Outputs:
None.
Keywords :
BIT = Number of bits in bit mask arrays (type "X"). Only used if
the column is of variable size.
NANVALUE= Value signalling data dropout. All points corresponding to
this value are set to be IEEE NaN (not-a-number). Ignored
unless DATA is of type float, double-precision or complex.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBWRITE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
HOST_TO_IEEE
Common :
Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions:
The binary table file must have been opened with FXBCREATE.
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.
Side effects:
None.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
W. Thompson, Jan 1992, based on WRITEFITS by J. Woffard and W. Landsman.
W. Thompson, Feb 1992, modified to support variable length arrays.
W. Thompson, Feb 1992, removed all references to temporary files.
Written :
William Thompson, GSFC, January 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 21 July 1993.
Fixed bug with variable length arrays.
Version 3, William Thompson, GSFC, 31 May 1994
Added ERRMSG keyword.
Version 4, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 5, Wayne Landsman, GSFC, 12 Aug 1997
Recognize IDL double complex data type
Version :
Version 5, 12 August 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxbwrite.pro)
FXBWRITM
[Previous Routine]
[Next Routine]
[List of Routines]
Project : RXTE/PCA
Name :
FXBWRITM
Purpose :
Write multiple columns/rows to a disk FITS binary table file.
Explanation :
A call to FXBWRITM will write multiple rows and multiple
columns to a binary table in a single procedure call. Up to
fifty columns may be read in a single pass. The file should
have already been opened with FXBOPEN (with write access) or
FXBCREATE. FXBWRITM optimizes writing multiple columns by
first writing a large chunk of data to the FITS file all at
once. FXBWRITM cannot write variable-length arrays; use
FXBWRITE instead.
Use :
FXBWRITM, UNIT, COL, D0, D1, D2, ..., ROW=ROW
Inputs :
UNIT = Logical unit number corresponding to the file containing the
binary table.
D0,... = An IDL data array to be written to the file, one for
each column.
COL = Column in the binary table to place data in, starting from
column one.
Opt. Inputs :
None.
Outputs :
None.
Opt. Outputs:
None.
Keywords :
ROW = Either row number in the binary table to writedata to,
starting from row one, or a two element array containing a
range of row numbers to write. If not passed, then
the entire column is written.
NANVALUE= Value signalling data dropout. All points corresponding to
this value are set to be IEEE NaN (not-a-number). Ignored
unless DATA is of type float, double-precision or complex.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXBWRITE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
WARNMSG = Messages which are considered to be non-fatal
"warnings" are returned in this output string.
BUFFERSIZE = Data are transferred in chunks to conserve
memory. This is the size in bytes of each chunk.
If a value of zero is given, then all of the data
are transferred in one pass. Default is 32768 (32
kB).
STATUS = An output array containing the status for each
read, 1 meaning success and 0 meaning failure.
Calls :
HOST_TO_IEEE
Common :
Uses common block FXBINTABLE--see "fxbintable.pro" for more
information.
Restrictions:
The binary table file must have been opened with FXBCREATE or
FXBOPEN (with write access).
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.
Side effects:
None.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
C. Markwardt, based on FXBWRITE and FXBREADM (ver 1), Jan 1999
Written :
Craig Markwardt, GSFC, January 1999.
Modified :
Version 1, Craig Markwardt, GSFC 18 January 1999.
Documented this routine, 18 January 1999.
Version :
Version 1, 18 January 1999.
(See /host/bluemoon/usr2/idllib/astron/pro/fxbwritm.pro)
FXFINDEND
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXFINDEND
Purpose :
Find the end of a FITS file.
Explanation :
This routine finds the end of the last logical record in a FITS file,
which may be different from that of the physical end of the file. Each
FITS header is read in and parsed, and the file pointer is moved to
where the next FITS extension header would be if there is one, or to
the end of the file if not.
Use :
FXFINDEND, UNIT [, EXTENSION]
Inputs :
UNIT = Logical unit number for the opened file.
Opt. Inputs :
None.
Outputs :
None.
Opt. Outputs:
EXTENSION = The extension number that a new extension would
have if placed at the end of the file.
Keywords :
None.
Calls :
FXHREAD, FXPAR
Common :
None.
Restrictions:
The file must have been opened for block I/O. There must not be any
FITS "special records" at the end of the file.
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.
Converted to IDL V5.0 W. Landsman September 1997
Added EXTENSION parameter, CM 1999 Nov 18
(See /host/bluemoon/usr2/idllib/astron/pro/fxfindend.pro)
FXHCLEAN
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXHCLEAN
Purpose :
Removes required keywords from FITS header.
Explanation :
Removes any keywords relevant to array structure from a FITS header,
preparatory to recreating it with the proper values.
Use :
FXHCLEAN, HEADER
Inputs :
HEADER = FITS header to be cleaned.
Opt. Inputs :
None.
Outputs :
HEADER = The cleaned FITS header is returned in place of the input
array.
Opt. Outputs:
None.
Keywords :
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXHCLEAN, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
SXDELPAR, FXPAR
Common :
None.
Restrictions:
HEADER must be a string array containing a properly formatted FITS
header.
Side effects:
Warning: when cleaning a binary table extension header, not all of the
keywords pertaining to columns in the table may be removed.
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 2, William Thompson, GSFC, 31 May 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 4, William Thompson, GSFC, 30 December 1994
Added TCUNIn to list of column keywords to be removed.
Version :
Version 4, 30 December 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxhclean.pro)
FXHMAKE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXHMAKE
Purpose :
Create a basic FITS header array.
Explanation :
Creates a basic header array with all the required keywords. This
defines a basic structure which can then be added to or modified by
other routines.
Use :
FXHMAKE, HEADER [, DATA ]
Inputs :
None required.
Opt. Inputs :
DATA = IDL data array to be written to file in the primary data unit
(not in an extension). This is used to determine the values
of the BITPIX and NAXIS, etc. keywords.
If not passed, then BITPIX is set to eight, NAXIS is set to
zero, and no NAXISnnn keywords are included in this
preliminary header.
Outputs :
HEADER = String array containing FITS header.
Opt. Outputs:
None.
Keywords :
INITIALIZE = If set, then the header is completely initialized, and any
previous entries are lost.
EXTEND = If set, then the keyword EXTEND is inserted into the file,
with the value of "T" (true).
DATE = If set, then the DATE keyword is added to the header.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXHMAKE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
GET_DATE, FXADDPAR, FXHCLEAN
Common :
None.
Restrictions:
Groups are not currently supported.
Side effects:
BITPIX, NAXIS, etc. are defined such that complex arrays are stored as
floating point, with an extra first dimension of two elements (real and
imaginary parts).
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
William Thompson, Jan 1992, from FXHMAKE by D. Lindler and M. Greason.
Differences include:
* Use of FITS standard (negative BITPIX) to signal floating
point numbers instead of (SDAS/Geis) DATATYPE keyword.
* Storage of complex numbers as pairs of real numbers.
* Support for EXTEND keyword, and for cases where there is no
primary data array.
* Insertion of DATE record made optional. Only required FITS
keywords are inserted automatically.
Written :
William Thompson, GSFC, January 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 21 June 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 4, Wayne Landsman, GSFC, 12 August 1997
Recognize double complex data type
Version :
Version 4, 12 Aug 1997
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxhmake.pro)
FXHMODIFY
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXHMODIFY
Purpose :
Modify a FITS header in a file on disk.
Explanation :
Opens a FITS file, and adds or modifies a parameter in the FITS header.
Can be used for either the main header, or for an extension header.
The modification is performed directly on the disk file.
Use :
FXHMODIFY, FILENAME, NAME, VALUE, COMMENT
Inputs :
FILENAME = String containing the name of the file to be read.
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 :
None.
Opt. Outputs:
None.
Keywords :
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. If not passed, then the primary FITS header is
modified.
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.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXHMODIFY, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
FXHREAD, FXPAR, FXADDPAR
Common :
None.
Restrictions:
Adding records to a FITS header is not allowed if it would increase the
number of 2880 byte records needed to store the header. Modifying
existing records is always allowed.
This routine can not be used to modify any of the keywords that control
the structure of the FITS file, e.g. BITPIX, NAXIS, PCOUNT, etc. Doing
so could corrupt the readability of the FITS file.
Side effects:
None.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
None.
Written :
William Thompson, GSFC, 3 March 1994.
Modified :
Version 1, William Thompson, GSFC, 3 March 1994.
Version 2, William Thompson, GSFC, 31 May 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version :
Version 3, 23 June 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxhmodify.pro)
FXHREAD
[Previous Routine]
[Next Routine]
[List of Routines]
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.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxhread.pro)
FXMOVE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FXMOVE
PURPOSE:
Skip a specified number of extensions in a FITS file
CALLING SEQUENCE:
STATUS=FXMOVE(UNIT, N_EXT)
INPUT PARAMETERS:
UNIT = An open unit descriptor for a FITS data stream.
N_EXT = Number of extensions to skip.
RETURNS:
0 if successful.
-1 if an error is encountered.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Repositions the file pointer.
PROCEDURE:
Each FITS header is read in and parsed, and the file pointer is moved
to where the next FITS extension header until the desired
extension is reached.
PROCEDURE CALLS:
FXPAR(), MRD_HREAD, MRD_SKIP
MODIFICATION HISTORY:
Extracted from FXPOSIT 8-March-2000 by T. McGlynn
(See /host/bluemoon/usr2/idllib/astron/pro/fxmove.pro)
FXPAR()
[Previous Routine]
[Next Routine]
[List of Routines]
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.
If the value is too long for one line, it may be continued on to the
the next input card, using the OGIP CONTINUE convention. For more info,
http://heasarc.gsfc.nasa.gov/docs/heasarc/ofwg/docs/ofwg_recomm/r13.html
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. If an integer is too large to be stored as
type LONG, then it is returned as DOUBLE.
CALLING SEQUENCE:
Result = FXPAR( HDR, NAME [, ABORT, COUNT=, COMMENT=, /NOCONTINUE ] )
Result = FXPAR(HEADER,'DATE') ;Finds the value of DATE
Result = FXPAR(HEADER,'NAXIS*') ;Returns array dimensions as
;vector
REQUIRED 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.
OPTIONAL INPUT:
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.
START = A best-guess starting position of the sought-after
keyword in the header. If specified, then FXPAR
first searches for scalar keywords in the header in
the index range bounded by START-PRECHECK and
START+POSTCHECK. This can speed up keyword searches
in large headers. If the keyword is not found, then
FXPAR searches the entire header.
If not specified then the entire header is searched.
Searches of the form 'keyword*' also search the
entire header and ignore START.
Upon return START is changed to be the position of
the newly found keyword. Thus the best way to
search for a series of keywords is to search for
them in the order they appear in the header like
this:
START = 0L
P1 = FXPAR('P1', START=START)
P2 = FXPAR('P2', START=START)
PRECHECK = If START is specified, then PRECHECK is the number
of keywords preceding START to be searched.
Default: 5
POSTCHECK = If START is specified, then POSTCHECK is the number
of keywords after START to be searched.
Default: 20
OUTPUT:
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.
OPTIONAL INPUT KEYWORDS:
/NOCONTINUE = If set, then continuation lines will not be read, even
if present in the header
OPTIONAL OUTPUT KEYWORD:
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.
PROCEDURE CALLS:
GETTOK(), VALID_NUM
SIDE EFFECTS:
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.
NOTES:
The functions SXPAR() and FXPAR() are nearly identical, although
FXPAR() has slightly more sophisticated parsing. There is no
particular reason for having two nearly identical procedures, but
both are too widely used to drop either one.
REVISION HISTORY:
Version 1, William Thompson, GSFC, 12 April 1993.
Adapted from SXPAR
Version 2, William Thompson, GSFC, 14 October 1994
Modified to use VALID_NUM instead of STRNUMBER. Inserted
additional call to VALID_NUM to trap cases where character
strings did not contain quotation marks.
Version 3, William Thompson, GSFC, 22 December 1994
Fixed bug with blank keywords, following suggestion by Wayne
Landsman.
Version 4, Mons Morrison, LMSAL, 9-Jan-98
Made non-trailing ' for string tag just be a warning (not
a fatal error). It was needed because "sxaddpar" had an
error which did not write tags properly for long strings
(over 68 characters)
Version 5, Wayne Landsman GSFC, 29 May 1998
Fixed potential problem with overflow of LONG values
Version 6, Craig Markwardt, GSFC, 28 Jan 1998,
Added CONTINUE parsing
Version 7, Craig Markwardt, GSFC, 18 Nov 1999,
Added START, PRE/POSTCHECK keywords for better performance
(See /host/bluemoon/usr2/idllib/astron/pro/fxpar.pro)
FXPARPOS
[Previous Routine]
[Next Routine]
[List of Routines]
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.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxparpos.pro)
FXPOSIT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FXPOSIT
PURPOSE:
Return the unit number of a FITS file positioned at specified extension
EXPLANATION:
The FITS file will be ready to be read at the beginning of the
specified extension.
CALLING SEQUENCE:
unit=FXPOSIT(FILE, EXT_NO, /READONLY, COMPRESS=program)
INPUT PARAMETERS:
FILE = FITS file name, scalar string
EXT_NO = Extension to be moved to, scalar nonnegative integer
RETURNS:
Unit number of file or -1 if an error is detected.
OPTIONAL KEYWORD PARAMETER:
/READONLY - If this keyword is set and non-zero, then OPENR rather
than OPENU will be used to open the FITS file.
COMPRESS - If this keyword is set and non-zero, then then treat
the file as compressed. If 1 assume a gzipped file.
Where possible use IDLs internal decompression
facilities (i.e., v5.3 or greater) or on Unix systems
spawn off a process to decompress and use its output
as the FITS stream. If the keyword is not 1, then
use its value as a string giving the command needed for
decompression.
COMMON BLOCKS:
None.
SIDE EFFECTS:
Opens and returns the descriptor of a file.
PROCEDURE:
Open the appropriate file, or spawn a command and intercept
the output.
Call FXMOVE to get to the appropriate extension.
PROCEDURE CALLS:
EXPAND_TILDE() (Unix only), FXPAR(), FXMOVE()
MODIFICATION HISTORY:
Derived from William Thompson's FXFINDEND routine.
Modified by T.McGlynn, 5-October-1994.
Modified by T.McGlynn, 25-Feb-1995 to handle compressed
files. Pipes cannot be accessed using FXHREAD so
MRD_HREAD was written.
W. Landsman 23-Apr-1997 Force the /bin/sh shell when uncompressing
W. Landsman 26-May-1997 Non-unix is not just VMS
T. McGlynn 22-Apr-1999 Add /binary modifier needed for Windows
T. McGlynn 03-June-1999 Use /noshell option to get rid of processes left by spawn.
Use findfile to retain ability to use wildcards
W. Landsman 03-Aug-1999 Use EXPAND_TILDE under Unix to find file
T. McGlynn 04-Apr-2000 Put reading code into FXMOVE,
additional support for compression from D.Palmer.
W. Landsman/D.Zarro 04-Jul-2000 Added test for !VERSION.OS EQ 'Win32' (WinNT)
(See /host/bluemoon/usr2/idllib/astron/pro/fxposit.pro)
FXREAD
[Previous Routine]
[Next Routine]
[List of Routines]
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 -1,-1,
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 -1,-1, 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.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXREAD, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
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 3, William Thompson, GSFC, 31 May 1994
Added ERRMSG keyword.
Version 4, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 5, Zarro (SAC/GSFC), 14 Feb 1997
Added I/O error checking
Version 6, 20-May-1998, David Schlegel/W. Thompson
Allow a single pixel to be read in.
Change the signal to read in the entire array to be -1
Version :
Version 6, 20-May-1998
(See /host/bluemoon/usr2/idllib/astron/pro/fxread.pro)
FXTAPEREAD
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : FXTAPEREAD
Purpose : Copy FITS files tape to disk with interactive capabilities.
Explanation : Copy FITS files from tape onto disk. Data is left in FITS
format, and not converted to SDAS. For use on VMS (any
version) and UNIX running IDL Version 3.1 or later (see
Restrictions).
Use : FXTAPEREAD ; Prompt for all parameters.
FXTAPEREAD, UNIT, LIST, KEYWORD, TAPENAME, FNAMES [, XWSTR]
FXTAPEREAD, 1, INDGEN(5)+1, 'IMAGE'
; Read the first 5 files on unit 1. The filenames are
; taken from the IMAGE keyword.
FXTAPEREAD, 1, [2,4], '', '', ['GALAXY', 'STAR']
; Read files 2 and 4 on unit 1. Create files named
; GALAXY and STAR.
FXTAPEREAD, 1, [2,4]
; Read files 2 and 4, and prompt for filenames.
Inputs : None necessary.
Opt. Inputs : Interactive users will normally just type FXTAPEREAD and be
prompted for all parameters. However, the following
parameters can be passed directly to FXTAPEREAD:
UNIT = Tape unit number (scalar: 0-9).
LIST = Vector containing list of file numbers to read.
KEYWORD = Scalar string giving a FITS keyword which will be
extracted from the headers on tape and used for file
names. Set KEYWORD to the null string '', if such a
keyword is not to be used.
TAPENAME= Scalar string giving a name for the tape. Filenames
will be constructed by concatenating TAPENAME with
the file number. TAPENAME is used only if KEYWORD
is passed as the null string ''.
FNAMES = Vector string giving a file name for each file
number given in LIST. FNAMES is used only if both
KEYWORD = '' and TAPENAME = ''. Spaces are trimmed
from names in FNAMES.
XWSTR = A string array that contains informational text
concerning tape reading events. These strings are
printed either to the screen or to the FILENAME
widget (internally called XWIDGET) created by the
XWINTAPE procedure.
Outputs : None.
Opt. Outputs: FNAMES = If KEYWORD or TAPENAME is set to a non-null string,
then the filename created by FXTPIO_READ is stored
in this variable to be returned to the caller.
XWSTR = A string array that contains informational text
concerning tape reading events. These strings are
printed either to the screen or to the FILENAME
widget (internally called XWIDGET) created by the
XWINTAPE procedure. Note that FXTAPEREAD adds
strings to this array and passes them back to the
caller.
Keywords : ERRMSG = If defined and passed, then any error messages will
be returned to the user in this parameter rather
than being handled by the IDL MESSAGE utility. If
no errors are encountered, then a null string is
returned. In order to use this feature, the string
ERRMSG must be defined first, e.g.,
ERRMSG = ''
FXTAPEREAD, 1, INDGEN(5)+1, 'IMAGE', $
ERRMSG=ERRMSG
IF ERRMSG(0) NE '' THEN ...
NOSUFFIX = Normally FXTAPEREAD (via FXTPIO_READ) will
automatically append a ".fits" to the end of a
passed file name. Setting this keyword prevents
that from happening.
SFDU = This keyword tells this routine that the first file
on the tape is an SFDU header file (defined to be
tape file number 1). If this keyword is set, then
the first file on the tape is skipped after the
initial rewind is preformed.
XWIDGET = This keyword tells this routine that an X-window
widget (i.e., XWINTAPE) is driving this program.
If this is the case, any informational messages
generated from this routine will be displayed in the
widget instead of the screen.
Calls : DATATYPE, FITSTAPE, GETFILES, FXTPIO_READ
Common : None.
Restrictions: Supported under VMS and (NOW) under UNIX running IDL Versions
3.1 or later when the UNIX versions of TAPRD, TAPWRT, etc. are
included in a user library directory.
Side effects: FXTAPEREAD will always rewind the tape before processing.
The FITS file is copied over record by record with no
conversion, until the marker is reached. No
testing is done of the validity of the FITS file.
Images are NOT converted using BSCALE and BZERO factors in the
header.
For each tape file a FITS disk file will be created with the
name ".FITS" unless /NOSUFFIX has been set..
Category : Data Handling, I/O, FITS, Generic.
Prev. Hist. : William Thompson, March 1992, from FITSRD by D. Lindler.
William Thompson, May 1992, fixed TPOS bug when reading
multiple files.
William Thompson, Jan. 1993, changed for renamed FXTPIO_READ.
Written : William Thompson, GSFC, March 1992.
Modified : Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, Donald G. Luttermoser, GSFC/ARC, 13 March 1995.
Added ERRMSG keyword. Reformatted and modified the
documentation.
Version 3, Donald G. Luttermoser, GSFC/ARC, 20 March 1995.
Added NOSUFFIX & SFDU keyword.
Version 4, Donald G. Luttermoser, GSFC/ARC, 9 May 1995.
Added the XWIDGET keyword.
Version 5, Donald G. Luttermoser, GSFC/ARC, 13 December 1995.
Fixed the output text when an SFDU header file has
been written to the tape. This SFDU file is now
referred to tape file #1 (instead of #0 as previously
done) and the first FITS file is tape file #2 (instead
of #1).
Version : Version 5, 13 December 1995.
Converted to IDL V5.0 W. Landsman October 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxtaperead.pro)
FXTAPEWRITE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name : FXTAPEWRITE
Purpose : Procedure to copy disk FITS files to tape with interactive
capabilities.
Explanation : Writes the FITS files to tape based upon the parameters
inputted or supplied. If no parameters are supplied, then the
user is asked a series of questions to walk him or her through
copying a number of FITS files from disk to tape.
Use : FXTAPEWRITE ; Prompt for all parameters.
FXTAPEWRITE, UNIT, BLFAC, FNAMES, KEYWORD [, XWSTR]
FXTAPEWRITE, 0, 1, FNAMES
; Writes all FITS files listed in FNAMES to the tape
; associated to UNIT = 0 with 2880 bytes per record.
FXTAPEWRITE, 1, 3, 'CDS', 'FILENAME'
; Writes all FITS files beginning with the name 'CDS'
; to the tape associated to UNIT = 1 with 8640 (2880*3)
; bytes per record and includes the keyword 'FILENAME'
; in the FITS header which contains the disk file name
; of the file being written.
Inputs : None necessary.
Opt. Inputs : Interactive users will normally just type FXTAPEWRITE and be
prompted for all parameters. However, the following
parameters can be passed directly to FXTAPEWRITE:
UNIT = Tape unit number (integer scalar).
BLFAC = Blocking factor (1-10) = # of 2880 byte records per
block.
FNAMES = File names (string array). If in interactive mode,
the file names may either be specified individually,
or a tapename may be specified, and all files in the
form "tapename.FITS" will be written to tape.
KEYWORD = Name of a FITS keyword to put file names into. This
will simplify subsequent reading of the FITS tape,
since individual filenames will not have to be
specified. If you don't want to put the file names
into the FITS header, then just hit
(interactive mode) or do not pass this parameter.
XWSTR = A string array that contains informational text
concerning the tape I/O. These strings are printed
either to the screen or to the FILENAME widget (set
internally to XWIDGET) if the XWINTAPE procedure is
driving this routine.
Outputs : None.
Opt. Outputs: XWSTR = A string array that contains informational text
concerning the tape I/O. These strings are printed
either to the screen or to the FILENAME widget (set
internally to XWIDGET) if the XWINTAPE procedure is
driving this routine. Note that FXTAPEWRITE will
add strings to this array which is then passed back
to the caller.
Keywords : XWIDGET = This keyword tells this FXTAPEWRITE that the XWINTAPE
widget procedure is driving this procedure. If so,
then any informational text is printed to the
FILENAME widget (internally set to XWIDGET) created
by XWINTAPE.
SFDU = If set, then an SFDU header file was placed at the
beginning of the tape.
ERRMSG = If defined and passed, then any error messages will
be returned to the user in this parameter rather
than being handled by the IDL MESSAGE utility. If
no errors are encountered, then a null string is
returned. In order to use this feature, the string
ERRMSG must be defined first, e.g.,
ERRMSG = ''
FXTAPEWRITE, 1, 1, FNAMES, ERRMSG=ERRMSG
IF ERRMSG(0) NE '' THEN ...
Calls : DATATYPE, FITSTAPE, GETFILES, FXTPIO_WRITE
Common : None.
Restrictions: Supported under VMS and (NOW) under UNIX running IDL Versions
3.1 or later when the UNIX versions of TAPRD, TAPWRT, etc. are
included in a user library directory.
Side effects: Tape is not rewound before files are written. Tape should be
positioned with REWIND or SKIPF before calling FXTAPEWRITE.
If you want to append new FITS files to a tape, then call
TINIT (tape init) to position tape between final double EOF.
Category : Data Handling, I/O, FITS, Generic.
Prev. Hist. : William Thompson, March 1992, from FITSWRT by D. Lindler.
William Thompson, May 1992, removed call to TINIT.
William Thompson, Jan. 1993, changed for renamed FXTPIO_WRITE.
Written : William Thompson, GSFC, March 1992.
Modified : Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, Donald G. Luttermoser, GSFC/ARC, 13 March 1995.
Included "passed" input parameters and ERRMSG keyword.
Reformatted and modified the documentation.
Version 3, Donald G. Luttermoser, GSFC/ARC, 9 May 1995.
Added the XWIDGET keyword.
Version 4, Donald G. Luttermoser, GSFC/ARC, 13 December 1995.
Corrected output text such that if an SFDU file was
placed at the beginning of the tape (indicated with
the added keyword /SFDU), the first FITS file written
to the tape is tape file #2 (not #1 as previously done).
Version : Version 4, 13 December 1995.
Converted to IDL V5.0 W. Landsman October 1997
(See /host/bluemoon/usr2/idllib/astron/pro/fxtapewrite.pro)
FXTPIO_READ
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FXTPIO_READ
PURPOSE:
Copies FITS files from tape to disk -- internal routine.
EXPLANATION :
Procedure to copy a FITS file from a tape on the specified tape unit to
the disk file .FITS (unless the /NOSUFFIX keyword has been set).
For use on VMS (any version) and UNIX running IDL Version 3.1 or later
(see Restrictions).
The procedure FXTAPEREAD is normally used to read a FITS tape.
FXTPIO_READ is a procedure call internal to FXTAPEREAD.
CALLING SEQUENCE:
FXTPIO_READ, UNIT, NAME, [ KEYWORD, /NOSUFFIX, ERRMSG = ]
INPUT PARAMETERS:
UNIT = Tape unit number (scalar: 0-9).
NAME = File name (without an extension, unless /NOSUFFIX is set).
OPTIONAL INPUT PARAMETERS:
KEYWORD = If supplied and not equal to the null string then the file
name will be taken from the value of the header keyword
specified.
OUTPUTS:
NAME = Name of file if input keyword parameter is supplied.
OPTIONAL OUTPUT KEYWORD:
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than being handled
by the IDL MESSAGE utility. If no errors are encountered, then
a null string is returned. In order to use this feature, the
string ERRMSG must be defined first, e.g.,
ERRMSG = ''
FXTPIO_READ, 1, NAME, ERRMSG=ERRMSG
IF ERRMSG(0) NE '' THEN ...
OPTIONAL INPUT KEYWORD:
NOSUFFIX = Normally FXTPIO_READ will automatically append a
".fits" to the end of a passed file name. Setting
this keyword prevents this from happening.
PROCEDURE CALLS:
REMCHAR, FITSTAPE, FXPAR
RESTRICTIONS:
Supported under VMS and (NOW) under UNIX running IDL Versions
3.1 or later when the UNIX versions of TAPRD, TAPWRT, etc. are
included in a user library directory.
SIDE EFFECTS:
The FITS file is copied to a disk file called .FITS
(unless the /NOSUFFIX keyword has been set).
The FITS file is copied over record by record with no conversion, until
the end-of-file marker is reached. No testing is done of the validity
of the FITS file.
Images are NOT converted using BSCALE and BZERO factors in the header.
Category : Data Handling, I/O, FITS, Generic.
Prev. Hist. : William Thompson, March 1992, from FITSREAD by D. Lindler, M.
Greason, and W. Landsman.
W. Thompson, May 1992, changed open statement to force 2880
byte fixed length records (VMS). The software here
does not depend on this file configuration, but other
FITS readers might.
William Thompson, Jan. 1993, renamed to be compatible with DOS
Version 2, Donald G. Luttermoser, GSFC/ARC, 14 March 1995.
Added ERRMSG and NOSUFFIX keywords.
(See /host/bluemoon/usr2/idllib/astron/pro/fxtpio_read.pro)
FXTPIO_WRITE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
FXTPIO_WRITE
PURPOSE:
Copy FITS files from disk to tape -- internal routine.
EXPLANATION:
Procedure will copy a disk FITS file to the specified tape unit, at
the current tape position. Used for true disk FITS files, not
SDAS/Geis files. Called by FXTAPEWRITE.
CALLING SEQUENCE:
FXTPIO_WRITE, UNIT, FILE, [ KEYWORD, ERRRMSG = ]
INPUTS:
UNIT = IDL tape unit number (scalar: 0-9).
FILE = Disk FITS file name, with extension.
OPTIONAL INPUTS:
KEYWORD = Keyword to place file name into. If not supplied or
equal to the null string '' then the file name is
not put into the header before writing it to tape.
OUTPUTS:
NONE
OPTIONAL KEYWORD OUTPUT:
ERRMSG = If defined and passed, then any error messages will
be returned to the user in this parameter rather than being
handled by the IDL MESSAGE utility. If no errors are
encountered, then a null string is returned. In order to use
this feature, the string ERRMSG must be defined first, e.g.,
ERRMSG = ''
FXTPIO_WRITE, 1, FILE, ERRMSG=ERRMSG
IF ERRMSG(0) NE '' THEN ...
PROCEDURE CALLS:
REMCHAR, FXHREAD, FXPAR, FDECOMP, FXADDPAR, FITSTAPE
RESTRICTIONS:
Supported under VMS and (NOW) under UNIX running IDL Versions
3.1 or later when the UNIX versions of TAPRD, TAPWRT, etc. are
included in a user library directory.
REVISION HISTORY:
William Thompson, March 1992, from FITSWRITE by D. Lindler, W.
Landsman, and M. Greason.
William Thompson, Jan. 1993, renamed to be compatible with DOS
Version 2, Donald G. Luttermoser, GSFC/ARC, 14 March 1995.
Added ERRMSG keyword. Updated documentation concerning
UNIX.
Version 3, Donald G. Luttermoser, GSFC/ARC, 9 May 1995.
Removed the "PRINT, FILE" line from this routine and
placed it in FXTAPEWRITE which drives this procedure.
(See /host/bluemoon/usr2/idllib/astron/pro/fxtpio_write.pro)
FXWRITE
[Previous Routine]
[Next Routine]
[List of Routines]
Project : SOHO - CDS
Name :
FXWRITE
Purpose :
Write a disk FITS file.
Explanation :
Creates a disk FITS file and writes a FITS primary header, and
optionally a primary data array.
Use :
FXWRITE, FILENAME, HEADER [, DATA ]
Inputs :
FILENAME = String containing the name of the file to be written.
HEADER = String array containing the header for the FITS file.
Opt. Inputs :
DATA = IDL data array to be written to the file. If not passed,
then it is assumed that extensions will be added to the
file.
Outputs :
None.
Opt. Outputs:
None.
Keywords :
NANVALUE = Value signalling data dropout. All points corresponding to
this value are set to be IEEE NaN (not-a-number). Ignored
unless DATA is of type float, double-precision or complex.
NOUPDATE = If set, then the optional BSCALE and BZERO keywords in the
HEADER array will not be changed. The default is to reset
these keywords to BSCALE=1, BZERO=0.
ERRMSG = If defined and passed, then any error messages will be
returned to the user in this parameter rather than
depending on the MESSAGE routine in IDL. If no errors are
encountered, then a null string is returned. In order to
use this feature, ERRMSG must be defined first, e.g.
ERRMSG = ''
FXWRITE, ERRMSG=ERRMSG, ...
IF ERRMSG NE '' THEN ...
Calls :
CHECK_FITS, GET_DATE, HOST_TO_IEEE, FXADDPAR, FXPAR
Common :
None.
Restrictions:
If DATA is passed, then HEADER must be consistent with it. If no data
array is being written to the file, then HEADER must also be consistent
with that. The routine FXHMAKE can be used to create a FITS header.
If found, then the optional keywords BSCALE and BZERO in the 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.
If the /NOUPDATE keyword is set, however, then the BSCALE and BZERO
keywords are not changed. The user should then be aware that FITS
readers will apply these numbers to the data, even if the data is
already converted to floating point form.
Groups are not supported.
Side effects:
None.
Category :
Data Handling, I/O, FITS, Generic.
Prev. Hist. :
W. Thompson, Jan 1992, from WRITEFITS by J. Woffard and W. Landsman.
Differences include:
* Made DATA array optional, and HEADER array mandatory.
* Changed order of HEADER and DATA parameters.
* No attempt made to fix HEADER array.
W. Thompson, May 1992, changed open statement to force 2880 byte fixed
length records (VMS). The software here does not
depend on this file configuration, but other
FITS readers might.
W. Thompson, Aug 1992, added code to reset BSCALE and BZERO records,
and added the NOUPDATE keyword.
Written :
William Thompson, GSFC, January 1992.
Modified :
Version 1, William Thompson, GSFC, 12 April 1993.
Incorporated into CDS library.
Version 2, William Thompson, GSFC, 31 May 1994
Added ERRMSG keyword.
Version 3, William Thompson, GSFC, 23 June 1994
Modified so that ERRMSG is not touched if not defined.
Version 4, William Thompson, GSFC, 12 August 1999
Catch error if unable to open file.
Version :
Version 4, 12 August 1999
(See /host/bluemoon/usr2/idllib/astron/pro/fxwrite.pro)
F_FORMAT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
F_FORMAT
PURPOSE:
Choose a nice floating format for displaying an array of REAL data.
EXPLANATION:
Called by TVLIST, IMLIST.
CALLING SEQUENCE:
fmt = F_FORMAT( minval, maxval, factor, [ length ] )
INPUTS:
MINVAL - REAL scalar giving the minimum value of an array of numbers
for which one desires a nice format.
MAXVAL - REAL scalar giving maximum value in array of numbers
OPTIONAL INPUT:
LENGTH - length of the output F format (default = 5)
must be an integer scalar > 2
OUTPUT:
FMT - an F or I format string, e.g. 'F5.1'
FACTOR - factor of 10 by which to multiply array of numbers to achieve
a pretty display using format FMT.
EXAMPLE:
Find a nice format to print an array of numbers with a minimum of 5.2e-3
and a maximum of 4.2e-2.
IDL> fmt = F_FORMAT( 5.2e-3, 4.2e-2, factor )
yields fmt = '(F5.2)' and factor = .01, i.e. the array can be displayed
with a F5.2 format after multiplication by 100.
REVISION HISTORY:
Written W. Landsman December 1988
Deal with factors < 1. August 1991
Deal with factors < 1. *and* a large range October 1992
Now returns In format rather than Fn.0 February, 1994
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/f_format.pro)
GALAGE
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GALAGE
PURPOSE:
Determine the age of a galaxy given its redshift and a formation redshift.
CALLING SEQUENCE:
age = galage(z, [zform, H0 =, k=, lambda0 =, Omega_m= , q0 =, /SILENT])'
INPUTS:
z - positive numeric vector or scalar of measured redshifts
zform - redshift of galaxy formation (> z), numeric positive scalar
To determine the age of the universe at a given redshift, set zform
to a large number (e.g. ~1000).
OPTIONAL KEYWORD INPUTS:
H0 - Hubble constant in km/s/Mpc, positive scalar, default is 70
/SILENT - If set, then the adopted cosmological parameters are not
displayed at the terminal.
No more than two of the following four parameters should be
specified. None of them need be specified -- the adopted defaults
are given.
k - curvature constant, normalized to the closure density. Default is
0, (indicating a flat universe)
Omega_m - Matter density, normalized to the closure density, default
is 0.3. Must be non-negative
Lambda0 - Cosmological constant, normalized to the closure density,
default is 0.7
q0 - Deceleration parameter, numeric scalar = -R*(R'')/(R')^2, default
is -0.5
OUTPUTS:
age - age of galaxy in years, will have the same number of elements
as the input Z vector
EXAMPLE:
(1) Determine the age of a galaxy observed at z = 1.5 in a cosmology with
Omega_matter = 0.3 and Lambda = 0.0. Assume the formation redshift was
at z = 25, and use the default Hubble constant (=70 km/s/Mpc)
IDL> print,galage(1.5,25,Omega_m=0.3, Lambda = 0)
===> 3.35 Gyr
(2) Plot the age of a galaxy in Gyr out to a redshift of z = 5, assuming
the default cosmology (omega_m=0.3, lambda=0.7), and zform = 100
IDL> z = findgen(50)/10.
IDL> plot,z,galage(z,100)/1e9,xtit='z',ytit = 'Age (Gyr)'
PROCEDURE:
For a given formation time zform and a measured z, integrate dt/dz from
zform to z. Analytic formula of dt/dz in Gardner, PASP 110:291-305, 1998
March (eq. 7)
COMMENTS:
(1) Integrates using the IDL Astronomy Version procedure QSIMP. (The
intrinsic IDL QSIMP function is not called because of its ridiculous
restriction that only scalar arguments can be passed to the integrating
function.) The function 'dtdz' is defined at the beginning of the
routine (so it can compile first).
(2) Should probably be fixed to use a different integrator from QSIMP when
computing age from an "infinite" redshift of formation. But using a
large value of zform seems to work adequately.
PROCEDURES CALLED:
COSMO_PARAM, QSIMP
HISTORY:
STIS version by P. Plait (ACC) June 1999
IDL Astro Version W. Landsman (Raytheon ITSS) April 2000
(See /host/bluemoon/usr2/idllib/astron/pro/galage.pro)
GAL_FLAT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GAL_FLAT
PURPOSE:
Transforms the image of a galaxy so that the galaxy appears face-on
EXPLANATION:
Either a nearest-neighbor approximations or a bilinear interpolation
may be used.
CALLING SEQUENCE:
RESULT = GAL_FLAT( image, ang, inc, [, cen, /INTERP ] )
INPUTS:
IMAGE - Image to be transformed
ANG - Angle of major axis, counterclockwise from Y-axis, degrees
For an image in standard orientation (North up, East left)
this is the Position Angle
INC - Angle of inclination of galaxy, degrees
OPTIONAL INPUTS:
CEN - Two element vector giving the X and Y position of galaxy center
If not supplied, then the galaxy center is assumed to coincide
with the image center
INPUT KEYWORDS:
INTERP - If present, and non-zero, then bilinear interpolation will be
performed. Otherwise a nearest neighbor approximation is used.
OUTPUTS:
RESULT - the transformed image, same dimensions and type as IMAGE
METHOD:
A set of 4 equal spaced control points are corrected for inclination
using the procedure POLYWARP. These control points are used by
POLY_2D to correct the whole image.
REVISION HISTORY:
Written by R. S. Hill, SASC Technologies Inc., 4 December 1985
Code cleaned up a bit W. Landsman December 1992
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/gal_flat.pro)
GAUSSIAN
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GAUSSIAN
PURPOSE:
Compute the 1-d Gaussian function and optionally the derivative
EXPLANATION:
Compute the 1-D Gaussian function and optionally the derivative
at an array of points.
CALLING SEQUENCE:
y = gaussian( xi, parms,[ pderiv ])
INPUTS:
xi = array, independent variable of Gaussian function.
parms = parameters of Gaussian, 2 or 3 element array:
parms(0) = maximum value (factor) of Gaussian,
parms(1) = mean value (center) of Gaussian,
parms(2) = standard deviation (sigma) of Gaussian.
(if parms has only 2 elements then sigma taken from common).
OPTIONAL OUTPUT:
pderiv = optional output of partial derivatives,
computed only if parameter is present in call.
pderiv(*,i) = partial derivative at all xi absisca values
with respect to parms(i), i=0,1,2.
Function returns array of Gaussian evaluated at xi.
EXAMPLE:
Evaulate a Gaussian centered at x=0, with sigma=1, and a peak value
of 10 at the points 0.5 and 1.5. Also compute the derivative
IDL> f = gaussian( [0.5,1.5], [10,0,1], DERIV )
==> f= [8.825,3.25]. DERIV will be a 2 x 3 array containing the
numerical derivative at the two points with respect to the 3 parameters.
COMMON BLOCKS:
common gaussian, sigma
HISTORY:
Written, Frank Varosi NASA/GSFC 1992.
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/gaussian.pro)
GCIRC
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GCIRC
PURPOSE:
Computes rigorous great circle arc distances.
EXPLANATION:
Input/Output can either be either sexigesimal RA, Dec, or in radians.
All computations are double precision.
CALLING SEQUENCE:
GCIRC, U, RA1, DC1, RA2, DC2, DIS
INPUTS:
U -- Describes units of inputs and output:
0: everything radians
1: RAx in decimal hours, DCx in decimal
degrees, DIS in arc seconds
RA1 -- Right ascension of point 1
DC1 -- Declination of point 1
RA2 -- Right ascension of point 2
DC2 -- Declination of point 2
OUTPUTS:
DIS -- Angular distance on the sky between points 1 and 2
See U above for units; double precision
PROCEDURE:
"Cosine formula" (p. 7 of Smart's Spherical Astronomy or
p. 12 of Green's Spherical Astronomy)
NOTES:
(1) If RA1,DC1 are scalars, and RA2,DC2 are vectors, then DIS is a
vector giving the distance of each element of RA2,DC2 to RA1,DC1.
Similarly, if RA1,DC1 are vectors, and RA2, DC2 are scalars, then DIS
is a vector giving the distance of each element of RA1, DC1 to
RA2, DC2. If both RA1,DC1 and RA2,DC2 are vectors then DIS is a
vector giving the distance of each element of RA1,DC1 to the
corresponding element of RA2,DC2. If the input vectors are not the
same length, then excess elements of the longer ones will be ignored.
(2) Coordinates closer together than a few milliarcsec cannot
be distinguished. If you are in this realm, you should be
using special-purpose algorithms.
(3) The function SPHDIST provides an alternate method of computing
a spherical distance.
PROCEDURE CALLS:
ISARRAY()
MODIFICATION HISTORY:
Written in Fortran by R. Hill -- SASC Technologies -- January 3, 1986
Translated from FORTRAN to IDL, RSH, STX, 2/6/87
Vector arguments allowed W. Landsman April 1989
Prints result if last argument not given. RSH, RSTX, 3 Apr. 1998
Converted to IDL V5.0 April 1998
(See /host/bluemoon/usr2/idllib/astron/pro/gcirc.pro)
GETFILES
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GETFILES
PURPOSE:
Prompt the user to interactively specify a list of files
EXPLANATION:
User can specify a single file per line or a range of files
separated by a dash or comma. Used, for example, by FITSRD to
return a list of file numbers on tape to read
CALLING SEQUENCE:
getfiles, list
OUTPUT:
LIST - integer array containing file numbers
SIDE EFFFECTS:
User will be prompted to enter a list of file numbers
REVISION HISTORY
Written D. Lindler November, 1985
Converted to Version 2 IDL, August 1990
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/getfiles.pro)
GETLOG
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GETLOG
PURPOSE:
Formats a logical directory for the given operating system.
CALLING SEQUENCE:
result = GETLOG(lname)
INPUTS:
lname - the base name of the logical (without special characters).
OUTPUTS:
Returns appropriate string.
Under VMS the logical is not translated since it may correspond to
multiple directories.
RESTRICTIONS:
Assumes that the directory logical will have meaning to the host
operating system.
PROCEDURE:
The operating system in !version.os_family is checked. If it equals:
'vms' then a ':' is appended.
'windows' directory name is translated with GETENV()
and a '\' is appended
'unix' directory name is translated with GETENV()
and a '/' is appended
'MacOS' directory name is translated with GETENV()
EXAMPLE:
Open the file 'stars.dbh' in the logical directory ZDBASE in an
operating system independent way:
IDL> openr,1,getlog('ZDBASE') + 'stars.dbh'
MODIFICATION HISTORY:
Written, JDNeill, May, 1990.
Modified, JDNeill,Sep, 1990 -- for unix return full path instead of
just environment variable name.
Modified, I. Freedman, HSTX April 1994 -- for MacOS return full path
Bug in CASE statement fixed. JDO, HSTX, May 2 1994.
Added Windows compatibility W. Landsman September 1995
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/getlog.pro)
GETOPT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GETOPT
PURPOSE:
Convert a string supplied by the user into a valid scalar or vector
EXPLANATION:
Distinct elements in the string may be
separated by either a comma or a space. The output scalar
or vector can be specified to be either integer or floating
point. A null string is converted to a zero. !ERR is set
to the number of elements supplied.
CALLING SEQUENCE:
option = GETOPT( input, [ type, numopt ])
INPUTS:
input - string that was input by user in response to a prompt
Arithmetic operations can be included in the string (see
examples)
OPTIONAL INPUTS:
type - Either an "I" (integer) or an "F" (floating point) specifying
the datatype of the output vector. Default is floating point
numopt - number of values expected by calling procedure
If less than NUMOPT values are supplied the output
vector will be padded with zeros.
OUTPUTS:
option - scalar or vector containing the numeric conversion of
the fields in the string INPUT. If NUMOPT is not
supplied, the number of elements in OPTION will
equal the number of distinct fields in INPUT.
NOTES:
(1) If an input is invalid, !ERR is set to -1 and the result is set
to 999.
(2) GETOPT uses the execute function to interpret the user string.
Therefore GETOPT itself cannot be called with the EXECUTE
function.
(3) GETOPT has a hard limit of 10 tokens in the input string.
EXAMPLES:
(1) a = getopt( '3.4,5*4 ', 'I' ) yields a = [ 3, 20]
(2) a = getopt( '5/2.', 'F', 5) yields a = [2.5,0.,0.,0.,0.]
(3) a = getopt( '2*3,5,6') yields a = [6.,5.,6.]
REVISON HISTORY:
written by B. Pfarr, STX, 5/6/87
change value of !ERR W. Landsman STX, 6/30/88
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/getopt.pro)
GETPRO
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GETPRO
PURPOSE:
Search !PATH for a procedure, and copy into user's working directory
EXPLANATION:
Extract a procedure from an IDL Library or directory given in the
!PATH system variable and place it in the current default directory
(presumably to be edited by the user). GETPRO can also be used to
obtain a copy of the default startup file.
CALLING SEQUENCE:
GETPRO, [ proc_name ] ;Find PROC_NAME in !PATH and copy
OPTIONAL INPUT:
proc_name - Character string giving the name of the IDL procedure or
function. Do not give an extension. If omitted,
the program will prompt for PROC_NAME.
OUTPUTS:
None.
SIDE EFFECTS:
A file with the extension .pro and a name given by PROC_NAME will
be created on the user's directory.
PROCEDURE:
The system variable !PATH is parsed into individual libraries or
directories. Each library or directory is then searched for the
procedure name. When found, a SPAWN is used to extract or copy
the procedure into the user's directory. If not found in !PATH,
then the ROUTINE_INFO() function is used to determine if it is an
intrinsic IDL procedure.
EXAMPLE:
Put a copy of the USER library procedure CURVEFIT on the current
directory
IDL> getpro, 'CURVEFIT'
RESTRICTIONS:
User will be unable to obain source code for a native IDL function
or procedure, or for a FORTRAN or C routine added with CALL_EXTERNAL.
User must have write privilege to the current directory
This procedure is not used with Macintosh IDL.
PROCEDURE CALLS:
FDECOMP, ZPARCHECK
REVISION HISTORY:
Written W. Landsman, STX Corp. June 1990
Now use intrinsic EXPAND_PATH() command W. Landsman November 1994
Use ROUTINE_NAMES() to check for intrinsic procs W. Landsman July 95
Update for Windows/IDL W. Landsman September 95
Check if procedure is in current directory W. Landsman June 1997
Converted to IDL V5.0 W. Landsman September 1997
Use ROUTINE_INFO instead of undocumented ROUTINE_NAMES W.L. October 1998
(See /host/bluemoon/usr2/idllib/astron/pro/getpro.pro)
GETPSF
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GETPSF
PURPOSE:
To generate a point-spread function (PSF) from observed stars.
EXPLANATION:
The PSF is represented as a 2-dimensional Gaussian
(integrated over each pixel) and a lookup table of residuals.
The lookup table and Gaussian parameters are output in a FITS
image file. The PSF FITS file created by GETPSF can be
read with the procedure RDPSF. Adapted from the 1986 STSDAS
version of DAOPHOT
CALLING SEQUENCE:
GETPSF, image, xc, yc, apmag, sky, [ronois, phpadu, gauss, psf,
idpsf, psfrad, fitrad, psfname, /DEBUG ]
INPUTS:
IMAGE - input image array
XC - input vector of x coordinates (from FIND), these should be
IDL (first pixel is (0,0)) convention.
YC - input vector of y coordinates (from FIND)
APMAG - vector of magnitudes (from APER), used for initial estimate
of gaussian intensity. If APMAG is multidimensional, (more
than 1 aperture was used in APER) then the first aperture
is used.
SKY - vector of sky values (from APER)
OPTIONAL INPUTS:
The user will be prompted for the following parameters if not supplied.
RONOIS - readout noise per pixel, (in electrons, or equivalent photons)
PHPADU - photons per analog digital unit, used to scale the data
numbers in IMAGE into photon units
IDPSF - subscripts of the list of stars created by
APER which will be used to define the PSF. Stars whose
centroid does not fall within PSFRAD of the edge of the frame,
or for which a Gaussian fit requires more than 25 iterations,
will be ignored when creating the final PSF.
PSFRAD - the scalar radius, in pixels, of the circular area within
which the PSF will be defined. This should be slightly larger
than the radius of the brightest star that one will be
interested in.
FITRAD - the scalar radius, in pixels of the circular area used in the
least-square star fits. Stetson suggest that FITRAD should
approximately equal to the FWHM, slightly less for crowded
fields. (FITRAD must be smaller than PSFRAD.)
PSFNAME- Name of the FITS file that will contain the table of residuals,
and the best-fit Gaussian parameters. This file is
subsequently required for use by NSTAR.
OPTIONAL OUTPUTS:
GAUSS - 5 element vector giving parameters of gaussian fit to the
first PSF star
GAUSS(0) - height of the gaussian (above sky)
GAUSS(1) - the offset (in pixels) of the best fitting gaussian
and the original X centroid
GAUSS(2) - similiar offset from the Y centroid
GAUSS(3) - Gaussian sigma in X
GAUSS(4) - Gaussian sigma in Y
PSF - 2-d array of PSF residuals after a Gaussian fit.
PROCEDURE:
GETPSF fits a Gaussian profile to the core of the first PSF star
and generates a look-up table of the residuals of the
actual image data from the Gaussian fit. If desired, it will then
fit this PSF to another star (using PKFIT) to determine its precise
centroid, scale the same Gaussian to the new star's core, and add the
differences between the actual data and the scaled Gaussian to the
table of residuals. (In other words, the Gaussian fit is performed
only on the first star.)
OPTIONAL KEYWORD INPUT:
DEBUG - if this keyword is set and non-zero, then the result of each
fitting iteration will be displayed.
PROCEDURES CALLED
DAOERF, MAKE_2D, MKHDR, RINTER(), PKFIT, STRNUMBER(), STRN(), WRITEFITS
REVISON HISTORY:
Adapted from the 1986 version of DAOPHOT in STSDAS
IDL Version 2 W Landsman November 1988
Use DEBUG keyword instead of !DEBUG W. Landsman May 1996
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/getpsf.pro)
GETROT
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GETROT
PURPOSE:
Return the rotation and plate scale of an image from its FITS header
EXPLANATION:
Derive the counterclockwise rotation angle, and the X and Y scale
factors of an image, from a FITS image header. Input parameter
may be either a FITS image header or an astrometry structure (as
obtained by EXTAST.PRO)
CALLING SEQUENCE:
GETROT, Hdr, [ Rot, CDelt, /DEBUG ]
or
GETROT, Astr, Rot, CDelt, /DEBUG ]
INPUT PARAMETERS:
HDR - FITS Image header (string array). Program will extract the
astrometry structure
or
ASTR - ASTROMETRY structure, of the type returned by EXTAST.
See the documentation for EXTAST.PRO for details.
OPTIONAL OUTPUT PARAMETERS:
ROT - Scalar giving the counterclockwise rotation of NORTH in DEGREES
from the +Y axis of the image.
CDELT- 2 element vector giving the scale factors in DEGREES/PIXEL in
the X and Y directions. Values correspond to the FITS
parameters CDELT1 and CDELT2
If no output variables are supplied (or /DEBUG is set), then GETROT
will display the rotation and plate scale at the terminal.
OPTIONAL INPUT KEYWORD
DEBUG - if DEBUG is set, GETROT will print the rotation for both the
X and Y axis when these values are unequal. If DEBUG is set to 2,
then the output parameter ROT will contain both X and Y rotations.
PROCEDURE:
If the FITS header already contains CDELT (and CD or CROTA) keyword,
(as suggested by the proposed Greisen & Calabretta FITS standard)
then this is used for the scale factor.
If the header contains CD keywords but no CDELT keywords (as in IRAF
headers) then the scale factor is derived from the CD matrix.
REVISION HISTORY:
Written W. Landsman STX January 1987
Convert to IDL V2. M. Greason, STX, May 1990
Option to return both rotations added. J. D. Offenberg, STX, Aug 1991
Use new astrometry structure W. Landsman Mar 1994
Recognize a GSSS header W. Landsman June 1994
Converted to IDL V5.0 W. Landsman September 1997
Correct rotation determination with unequal CDELT values WL October 1998
(See /host/bluemoon/usr2/idllib/astron/pro/getrot.pro)
GETTOK
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GETTOK
PURPOSE:
Retrieve the first part of the string up to a specified character
EXPLANATION:
GET TOKen - Retrieve first part of 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'
NOTES:
A version of GETTOK that accepts vector strings is available for users
of IDL V5.3 or later from http://idlastro.gsfc.nasa.gov/ftp/v53/
HISTORY
version 1 by D. Lindler APR,86
Remove leading blanks W. Landsman (from JKF) Aug. 1991
Converted to IDL V5.0 W. Landsman September 1997
(See /host/bluemoon/usr2/idllib/astron/pro/gettok.pro)
GETWRD
[Previous Routine]
[Next Routine]
[List of Routines]
NAME:
GETWRD
PURPOSE:
Return the n'th word from a text string.
CATEGORY:
CALLING SEQUENCE:
wrd = getwrd(txt, n, [m])
INPUTS:
txt = text string to extract from. in
n = word number to get (first = 0 = def). in
m = optional last word number to get. in
KEYWORD PARAMETERS:
Keywords:
LOCATION = l. Return word n string location.
DELIMITER = d. Set word delimiter (def = space & tab).
/LAST means n is offset from last word. So n=0 gives
last word, n=-1 gives next to last, ...
If n=-2 and m=0 then last 3 words are returned.
/NOTRIM suppresses whitespace trimming on ends.
NWORDS=n. Returns number of words in string.
OUTPUTS:
wrd = returned word or words. out
COMMON BLOCKS:
getwrd_com
NOTES:
Note: If a NULL string is given (txt="") then the last string
given is used. This saves finding the words again.
If m > n wrd will be a string of words from word n to
word m. If no m is given wrd will be a single word.
n<0 returns text starting at word abs(n) to string end
If n is out of range then a null string is returned.
See also nwrds.
MODIFICATION HISTORY:
Ray Sterner, 6 Jan, 1985.
R. Sterner, Fall 1989 --- converted to SUN.
R. Sterner, Jan 1990 --- added delimiter.
R. Sterner, 18 Mar, 1990 --- added /LAST.
R. Sterner, 31 Jan, 1991 --- added /NOTRIM.
R. Sterner, 20 May, 1991 --- Added common and NULL string.
R. Sterner, 13 Dec, 1992 --- Made tabs equivalent to spaces.
R. Sterner, 4 Jan, 1993 --- Added NWORDS keyword.
Johns Hopkins University Applied Physics Laboratory.
Copyright (C) 1985, Johns Hopkins University/Applied Physics La