FITSIN - Reads a FITS tape composed of simple, group or table files

Description:

This application reads selected files from a FITS tape. The files may be Basic (simple) FITS, and/or have TABLE extensions (Harten et al. 1988).

The programme reads a simple or a random-groups-format FITS file (Wells et al. 1981; Greisen & Harten 1981), and writes the data into an NDF , and the headers into the NDF's FITS extension. Table-format files (Grosbøl et al. 1988) are read, and the application creates two files: a text formatted table/catalogue and a FACTS description file (as used by SCAR) based upon the FITS header cards. Composite FITS files can be processed. You may specify a list of files, including wildcards. A record of the FITS headers, and group parameters (for a group-format file) can be stored in a text file.

There is an option to run in automatic mode, where the names of output NDF data structures are generated automatically, and you can decide whether or not format conversion is to be applied to all files (rather than being prompted for each). This is very useful if there is a large number of files to be processed. Even if you want unique file names, format-conversion prompting may be switched off globally.

Usage:

fitsin mt files out [auto] fmtcnv [logfile] more=? dscftable=? table=?

Parameters:

AUTO = _LOGICAL (Read)

It is TRUE if automatic mode is required, where the name of each output NDF structure or table file is to be generated by the application, and therefore not prompted; and a global format-conversion switch may be set. In manual mode the FITS header is reported, but not in automatic.

For simple or group format FITS objects in automatic mode the application generates a filename beginning with a defined prefix followed by the number of the file on tape. For example, if the prefix was "XRAY" and the 25$^{\rm th}$ file of the tape was being processed, the filename of the NDF would be XRAY25.

For table-format FITS objects in the automatic mode the application generates a filename beginning with a defined prefix followed by the number of the file on tape. For example, if the prefix was "cat" and the 9$^{\rm th}$ file of the tape was being processed, the filename of the table and its associated FACTS description file would be cat9.dat and dscfcat9.dat respectively. [FALSE]

DSCFTABLE = FILENAME (Read)

Name of the text file to contain the FACTS descriptors, which defines the table's format for SCAR. Since SCAR is now deprecated, this parameter has little use, except perhaps to give a summary of the format of the file specified by Parameter TABLE. A null value (!) means that no description file will be created, so this is now the recommended usage. If your FITS file comprises just tables, you should consider other tools such as the CURSA package, which has facilities for examining and processing ASCII and binary tables in FITS files.

A suggested filename for the description file is reported immediately prior to prompting in manual mode. It is the name of the catalogue, as written in the FITS header, with a "dscf" prefix.

ENCODINGS = LITERAL (Read)

Determines which FITS keywords should be used to define the world co-ordinate systems to be stored in the NDF's WCS component. The allowed values (case-insensitive) are as follows.

• "FITS-IRAF" -- This uses keywords CRVALi CRPIXi, CDi_j, and is the system commonly used by IRAF. It is described in the document ``World Coordinate Systems Representations Within the FITS Format'' by R.J. Hanisch and D.G. Wells, 1988, available by ftp from fits.cv.nrao.edu /fits/documents/wcs/wcs88.ps.Z.

• "FITS-WCS" -- This is the FITS standard WCS encoding scheme described in the paper ``Representation of celestial coordinates in FITS''
  (http://www.cv.nrao.edu/fits/documents/wcs/wcs.html).
  

  It is very similar to FITS-IRAF but supports a wider range of projections and co-ordinate systems.

• "FITS-PC" -- This uses keywords CRVALi, CDELTi, CRPIXi, PCiiijjj, etc, as in a previous (now superceded) draft of the above FITS world co-ordinate system paper by E.W. Greisen and M. Calabretta.

• "FITS-AIPS" -- This uses conventions described in the document ``Non-linear Coordinate Systems in AIPS'' by Eric W. Greisen (revised 9th September, 1994), available by ftp from fits.cv.nrao.edu /fits/documents/wcs/aips27.ps.Z. It is currently employed by the AIPS data analysis facility, so its use will facilitate data exchange with AIPS. This encoding uses CROTAi and CDELTi keywords to describe axis rotation and scaling.

• "DSS" -- This is the system used by the Digital Sky Survey, and uses keywords AMDXn, AMDYn, PLTRAH, etc.

• "Native" -- This is the native system used by the AST library (see SUN/210), and provides a loss-free method for transferring WCS information between AST-based application. It allows more complicated WCS information to be stored and retrieved than any of the other encodings.

A comma-separated list of up to six values may be supplied, in which case the value actually used is in the first in the list for which corresponding keywords can be found in the FITS header.

A FITS header may contain keywords from more than one of these encodings, in which case it is possible for the encodings to be inconsistent with each other. This may happen for instance if an application modifies the keyword associated with one encoding but fails to make equivalent modifications to the others. If a null parameter value (!) is supplied for ENCODINGS, then an attempt is made to determine the most reliable encoding to use as follows. If both native and non-native encodings are available, then the first non-native encoding to be found which is inconsistent with the native encoding is used. If all encodings are consistent, then the native encoding is used (if present). [!]

FILES() = _CHAR (Read)

The list of the file numbers to be processed. Files are numbered consecutively from 1 from the start of the tape. Single files or a set of adjacent files may be specified, e.g. typing [4,6-9,12,14-16] will read files 4,6,7,8,9,12,14,15,16. (Note that the brackets are required to distinguish this array of characters from a single string including commas. The brackets are unnecessary when there only one item.) For efficiency reasons it is sensible to give the file numbers in ascending order.

If you wish to extract all the files enter the wildcard $*$. 5-$*$ will read from 5 to the last file. The processing will continue until the end of the tape is reached; no error will result from this.

FMTCNV = _LOGICAL (Read)

This specifies whether or not format conversion will occur. If FALSE, the HDS type of the data array in the NDF will be the equivalent of the FITS data format on tape (e.g. BITPIX=16 creates a _WORD array). If TRUE, the data array in the current file, or all files in automatic mode, will be converted from the FITS data type on tape to _REAL in the NDF. The conversion applies the values of the FITS keywords BSCALE and BZERO to the tape data to generate the `true' data values. If BSCALE and BZERO are not given in the FITS header, they are taken to be 1.0 and 0.0 respectively. The suggested default is TRUE.

GLOCON = _LOGICAL (Read)

If FALSE, a format-conversion query occurs for each FITS file. If TRUE, the value of FMTCNV is obtained before any file numbers and will apply to all data arrays. It is ignored in automatic mode--in effect it becomes TRUE. [FALSE]

LABEL = _LOGICAL (Read)

It should be TRUE if the tape has labelled files. Labelled files are non-standard. If TRUE, the application skips three file marks per file, rather that one. [FALSE]

LOGFILE = FILENAME (Read)

The file name of the text log of the FITS header cards. For group-format data the group parameters are evaluated and appended to the full header. The log includes the names of the output files used to store the data array or table. A null value (!) means that no log file is produced. [!]

MORE = _LOGICAL (Read)

A prompt asking if any more files are to be processed once the current list has been exhausted.

MT = DEVICE (Read)

Tape deck containing the data, usually an explicit device, though it can be a pre-assigned environment variable.

OUT = NDF (Write)

Output NDF structure holding the full contents of the FITS file. If the null value (!) is given no NDF will be created. This offers an opportunity to review the descriptors before deciding whether or not the data are to be extracted.

PREFIX = LITERAL (Read)

The prefix of the NDF's or table's file name. It is only used in the automatic mode.

REWIND = _LOGICAL (Read)

If it is TRUE, the tape drive is rewound before the reading of the FITS files commences. If it is FALSE, the tape is not rewound, and the current tape position is read from file USRDEVDATASET.sdf. Note that file numbers are absolute and not relative. REWIND=FALSE is useful if you need to read a series of files, process them, then read some more, without having to remember the tape's position or apply unnecessary wear to the tape. [TRUE]

TABLE = FILENAME (Read)

Name of the text file to contain the table itself, read from the file. In manual mode, the suggested default filename is the name of description file less the "dscf" prefix, or if there is no description file or if the description file does not have the "dscf" prefix, the suggested name reverts to the catalogue name in the FITS header.

Examples:

fitsin mt=/dev/rmt/1n files=[2-4,9] auto prefix=ccd nofmtcnv

This reads files 2, 3, 4, and 9 from the FITS tape on device /dev/rmt/1n. The output NDF names will be ccd2, ccd3, ccd4, and ccd9 (assuming there are no groups). The data will not have format conversion.

fitsin mt=$TAPE files=$*$ auto prefix=ccd fmtcnv logfile=jkt.log

This reads all the files from the FITS tape on the device assigned to the environment variable TAPE. The output files begin with a prefix "ccd". Integer data arrays are converted to real using the scale and zero found in the FITS header. A record of the headers and the names of the output files are written to the text file jkt.log.

References

• Wells, D.C., Greisen, E.W. & Harten, R.H. 1981, Astron. Astrophys. Suppl. Ser. 44, 363.

• Greisen, E.W. & Harten, R.H. 1981, Astron. Astrophys. Suppl. Ser. 44, 371.

• Grosbøl, P., Harten, R.H., Greisen, E.W & Wells, D.C. 1988 Astron. Astrophys. Suppl. Ser. 73, 359.

• Harten, R.H., Grosbøl, P., Greisen, E.W & Wells, D.C. 1988 Astron. Astrophys. Suppl. Ser. 73, 365.

Related Applications

KAPPA: FITSDIN, FITSHEAD, FITSIMP, FITSLIST; CONVERT: FITS2NDF; CURSA; FIGARO: RDFITS.

Implementation Status:

• The application processes tapes blocked at other than an integer multiple of 2880 bytes up to a maximum of 63360, provided it is a multiple of the number of bytes per data value.

• For simple or group format FITS:
  • IEEE floating point is supported.

  • If BUNIT is present its value will appear as the NDF's UNITS component.

  • If OBJECT is present its value will appear as the NDF's TITLE component.

  • If the BLANK item is present in the header, undefined pixels are converted from the BLANK value to Starlink-standard bad value during data conversion.

  • An AXIS  component will be stored in the NDF if the CRVALn keyword is present. (n is the number of the dimension.) If the CRPIXn keyword is absent it defaults to 1, and likewise for the CDELTn keyword. The value of CTYPEn is made the label of the axis structure.

• For groups format, a new NDF is created for each data array. The name of the NDF of the second and subsequent data arrays is generated by the application as the <filename>G<number>, where <filename> is the name of the first NDF, supplied by you or generated automatically, and <number> is the number of the group.

  Each group NDF contains the full header in the FITS extension, appended by the set of group parameters. The group parameters are evaluated using their scales and offsets, and made to look like FITS cards, whose keywords are derived from the values of PTYPEm in the main header. (m is the number of the group parameter.) The same format is used in the log file.

• If there is no data array on tape, i.e. the FITS file comprises header cards only, then a dummy vector data array of dimension two is created to make the output a valid NDF. This data array is undefined.