NAME

xwfits -- Convert IRAF image and table files to FITS files.

USAGE

xwfits iraf_files fits_files

DESCRIPTION

This task uses the TABLES stwfits task, with parameters defaulted for use with XRAY data. The xwfits task will accept IRAF images, STSDAS tables or trailer files as input and will convert them to standard FITS format, writing them out to either tape or disk.

This task can also write the floating point pixel value in the new IEEE FITS standard. Single or double precision image data will be written to single or double precision IEEE floating point representation. This method preserves the precision of the original data.

A trailer file is an ASCII file having a fixed record length of up to 132 characters per row. stwfits writes a FITS table with 132 characters per row. The extension for a trailer file must be .trl.

Options are available to write either the full FITS header or just a short description to the standard output. The program can select an appropriate bitpix value based on the precision of the GEIS data. Two scaling options are available: one to automatically calculate the appropriate scaling factors, and the other to allow scaling factors to be entered directly. The IEEE option is set with the ieee parameter. Scaling is not supported using this option.

Short output can now be defined by the user by creating an ASCII file containing keywords and field widths. The name of this format file is then passed to the parameter format_file. A log file can also be created by providing an output file name to be parameter log_file (up 132 characters per line). Short output sent to the screen is truncated to 80 characters. For more details see the parameters description below.

NOTES AND WARNINGS ABOUT TABLES

The FITS standard for tables says that all data should be written as ASCII strings. Based on this, some considerations need to be addressed.

There are 2 ways to write FITS table data from an STSDAS table: one is to rely on the display format of the input table and the other is to set def_tab_precision=yes.

With the display format table, the FITS writer will take the width and number of digits specified as the true precision of the data--this is what goes in the FITS table data. For example a column format specification of f5.2 will select 5 character for the width of the column which contains 2 decimal digits of precision.

If def_tab_precision=yes then the column format above f5.2 will get reset to E15.7. In general, all column precisions are changed to take the full precision of their data type. The drawback to this is that your FITS file can grow considerably larger than the original STSDAS table. If you are concerned about the size of your files, check the display format of the input table to make sure that what you see when editing the table is what you want when you read the FITS file back to a table.

This task supports a new, but unapproved, binary extension standard. The STSDAS tables will be written in the IEEE binary standard using the FITS table extension.

PARAMETERS

iraf_files [file name template]

The file(s) that are to be converted. This parameter may be a single file name or a list of files, e.g., file1, file*.imh, ftable.tab, ftable*.tab, or @filelist. If you want to write a table as a separate file, you will need to specify the extension .tab to differentiate it from an image file. See the description of the extensions parameter for more details.

fits_files [string]

Destination for the output files. This parameter takes either an output file name template, a directory name or the name of a tape drive.

If a file name is passed to this parameter, files will be written to disk. If more than one file is to be written to disk, the file number will be appended to the value of this parameter; if an extension is given in the filename then the file number is appended only to the root and the extension added. If a directory name is given, the output FITS filename is the input filename and the extension fit added to it; if the input extension is imh, these will be replaced by .fit. Files can be written to magnetic tape by using a tape drive specification rather than a file name. The tape drive specification takes the form "mt*[n]" where "mt" indicates a tape device, "*" represents a density, and "[n]" is a tape file number. Tape output will be written beginning at the specified file number, e.g., file 5 if fits_files = "mtb1600[5]". Data in file 5 and succeeding files will be overwritten. If no tape file number is specified in fits_files, the newtape parameter can be set to "yes" and tape output will be written at the beginning of the tape. If newtape is not set to "yes", then the output will be appended to the tape after the last file. To use the tape you need to allocate it with the allocate command, for example, "allocate mta".

(newtape) [boolean]

Is the tape blank? This parameter is requested only if no tape file number is specified in fits_files, e.g., fits_files = "mtb1600". Setting newtape=yes will cause files to be written at the beginning of the tape.

(long_header = no) [boolean]

Print the full FITS header on the standard output for each IRAF image converted?

(short_header = yes) [boolean]

Print only a short header? Lists files processed, their dimensions, size, data type, and scaling parameter on the standard output.

The keywords below represent the standard single line of information per processed file. You can change this by supplying a filename to the parameter format_file. If you want a log file, you can supply a file name to the parameter log_file. Up to 80 characters per line are sent to the display terminal.

The following information will be listed in short headers by default. The first column is a name of an image header keyword or a special name the program will process to give you the requested column information.

	FITSNAME	Output FITS name (Disk filename or tape
		        file number). (10 character)
	FILENAME	Input image file  (16 character)
	BITPIX		(I,R,D,U,S) and bits per pixels of the
			input data.
	DIMENS		Output FITS file dimensionality.
	BZERO		Zero offset
	BSCALE		Scale factor

Notes: (I,R,D,U,S) refer to Integer, Real, Double, Unsigned and Short input data types, respectively. If the ieee parameter is set, a minus (-) sign appears between the letter and the bits figure.

DIMENS is the number of dimensions in the output FITS file; the format is NxNxNg , where g indicates that the output FITS file contains an extra dimension to account for the groups in a multigroup STSDAS file. This mode is used only when the gftoxdim parameter is selected. If the input file is a table, this keyword indicates the number of colunms and the number of rows in the table with the suffix "C" and "R" (e.g., 27Cx12R).

(format_file = ) [file name]

If you want to define your own output format--still limited to one line per file--you can create an ASCII text file with some of the special keywords, in addition to your own image header keyword that you want to see in the display terminal or in the log file.

The format of the format file is as follow. One column with the keywords and a second with the field width and position of the values within the columns. The column format is similar to the Fortran print formatted statement.

The following special keywords are available:

FITSNAME	-10.10	# (string) The output FITS name or file number.
FILENAME	-16.16	# (string) The input file name.
BITPIX		-5.5	# (string) (I,U,R,D,S) and bit per pixels.
DIMENS		-10.10	# (string) Output FITS file dimensionality.
DATATYPE	-8.8	# (string) Input file data type.
BZERO		-12.6g	# (float)  Scale offset value.
BSCALE		-12.6g	# (float)  Scale value.			

In addition to these specials keywords, you can add your own that match the ones in the input image header.

(log_file = ) [file name]

Name of the output log file, if you want one created. The output is the same as short_header, but can have up to 132 characters per line.

(make_image = yes) [boolean]

Create an image file?

By default the program writes the FITS image(s) to the output destination. If the make_image switch is set to "no", the task will print FITS headers on the standard output and no output file is created; this will let you examine the FITS headers before the tape is actually written.

(bitpix = 0) [integer]

A bitpix value of 8, 16, or 32 will produce either an unsigned byte, a twos-complement 16-bit integer, or a twos-complement 32-bit integer FITS image. If bitpix is set to any other value, the program will choose one of these three values based on the precision of the IRAF image. The default value of zero will let the program choose the value from the input image data type.

(extensions = no) [boolean]

Append IRAF tables to the current output file?

The criterion used to select these tables is that they have the same root name as the input file, for example, you want to append tables uvb_raw.tab and uvb.clean.tab to the file uvb.imh or to the table name uvb.tab. If extension=no, you will need to specify all the images and tables in the iraf_file parameter.

(def_tab_precision = no) [boolean]

Write the table value data for each column with the full precision of its data type? The resulting FITS file could be much bigger due to the expanded column size, but you need to ensure that you will not loose precision when converting from binary STSDAS values to ASCII representation. This was described in more detail in the Description section, above.

(binary_table = yes) [boolean]

Write the table value data for each column in binary IEEE standard?

The resulting FITS file will have binary representation for non-ASCII information. This is the preferred method of writing table data because each cell will occupy 4 bytes (for most data types).

(gftoxdim = no) [boolean]

Write a GEIS file as a single FITS file with a table appended to it?

The resulting FITS image will have an extra dimension to account for the groups (if gcount > 1) and the table will contain the names and values of the group parameter block. (See below for more details.)

(ieee = yes) [boolean]

Do you want IEEE FITS data?

The new FITS IEEE standard allows you to write FITS data in IEEE floating point format. Single and double precision is supported.

(force_minmax = no) [boolean]

Force minimum and maximum data values to be recomputed? Bscale and offset are calculated based on the minimum and maximum values of the image data. Sometimes, for STSDAS images, the values DATAMIN and DATAMAX don't actually represent the extreme limits of the image causing incorrect scale and offset values because stwfits will not recompute the limits if MAX exceeds MIN. If your input data is of type REAL or DOUBLE and you are not sure the values are correct, then this flag should be set to "yes".

(scale = yes) [boolean]

Scale the image before writing output?

Two types of scaling are available: user-defined scaling, or autoscaling. The scaling parameters bscale and bzero may be entered by the user (when autoscale = no), or the program can calculate the appropriate bscale and bzero factors (autoscale = yes). If scale=no, the IRAF image data is converted directly to integers of the specified bitpix with possible loss of precision.

(autoscale = yes) [boolean]

Calculate the bscale and bzero factors based on the IRAF image data type and the maximum and minimum data values?

(bscale = 1.0) [real]

This is the FITS bscale parameter, which is defined as p = i * bscale + bzero, where p and i are the physical and tape data values respectively. The bscale parameter is only requested if the 'scale = yes' and autoscale = no.

(bzero = 0.0) [real]

This is the FITS bzero parameter (see bscale definition, above). This parameter is only requested if scale = no and autoscale = yes.

(blocking_factor = 1) [integer]

The tape blocking factor for FITS files. 2,880-byte records are normally assumed. If the blocking factor is greater than 1 and less than or equal to 10, then 2,880-byte records will be written to a single tape record. The FITS standard specifies that blocking_factor must be less than or equal to 10. If blocking_factor > 10 then the program will interpret this number as the actual tape block size in bytes. For example, if blocking_factor = 1024 then 1,024-byte records will be written to tape. This is a very dangerous option and has been included to accomodate users with restricted block size devices such as Sun microcassettes. A warning message will be issued prior to execution if an illegal block size is used.

EXAMPLES

1. Write 2 input IMAGE files to FITS files. Notice that the tape drive mta should be allocated at this time with the command "allocate mta".

	xd> xwfits image_im1.imh,image_bk1.imh  mta

2. Convert a series of IMAGE files to FITS image files and write them on a blank magnetic tape, allowing the program to select the appropriate bitpix and scaling parameters. Notice that the parameter gftoxdim is not set. If any of the input files is a multigroup GEIS file then there will be one FITS file per group.

	xd> xwfits iraf_file*.imh mtb1600[1]

3. Convert a IMAGE file to a 32-bits per pixel FITS file with no scaling; append the file to a tape that already contains data.

	xd> xwfits iraf_file mtb1600[EOT] bi=32 sc-

4. Convert an IMAGE to a 16-bit FITS specifying bscale and bzero; write the FITS file to disk.

	xd> xwfits iraf_file fits_file bi=16 au- bs=4.0 bz=0.0

5. Convert an IRAF pixel file iraf_file to a 32-bits per pixels FITS file and append to it (in the same file) the IRAF tables iraf_file_1.tab and iraf_file.uvb.tab.

	xd> xwfits iraf_file fits_file bi=32 extensions=yes

6. Same as above but put the IRAF tables in different files.

  xd> xwfits iraf_file,iraf_file_1.tab,iraf_file.uvb.tab bi=32 
extensions=no

7. Display a short header (default) and also keep a log in the file fits.log.

	xd> xwfits iraf_file*.imh short+  log_file="fits_log"

8. Display a short header, keep the a log file and use a special format file called my_format

	xd> xwfits ifi*.imh  log_file="fits_log"  for="my_format"  gft+

	xd> xwfits images*.imh mtb[1] block=5

	xd> xwfits asciif.trl mtb

	xd> xwfits *.imh  mtb  ieee+

BUGS

Blank pixel values are not correctly handled.

A fatal error sometimes occurs when short_header=yes. This error is caused by the file after the one being displayed and will cause the task to exit.

SEE ALSO

stwfits, strfits, xrfits, qp2fits, catfits, allocate

Type "help fitsio opt=sys" for a detailed description of the fitsio package.